语言服务器运行时间

语言服务器运行时(Language Server Runtimes)是基于JSON-RPC的协议,用于服务器和客户端之间的互动(通常嵌入到开发工具中). JSON-RPC协议沿用了该程序所使用的版本 LSP 规格 - 3.17,用于兼容性。 支持LSP版本3.17的一个子集(见 LSP 软件)加上另外一套请求和答复类型(见 特征) (中文(简体) ).

Language Server Runtimes支持一些主机环境,每个主机都有自己的内在传输机制和环境考虑,这也必须支持JSON-RPC的通信. 要了解主机环境之间的差异,请查看 运行时主机环境。 。 。 .

术语

服务器运行时间将提供"Features",指语言服务器运行时间的核心功能(如LSP,日志等). 这些功能将在构建时注入到服务器业务逻辑执行之上. 能力 是由 LSP 提供的一组语言特性.

项目结构

项目源代码被拆分为下个目录:

• /src: 本目录包含项目的所有源代码.
  • /protocol:JSON-RPC基于Typescription的运行时协议执行,它定义了运行时客户端与运行时客户端之间的通信(例如AWS工具包扩展).
  • /runtimes: 执行由服务器执行者开发的多个运行时间(独立,网络工作)和功能,这些运行时间和功能暴露在运行时间服务器上.
  • /server-interface:定义特性的接口,运行时为运行时服务器执行器提供.
  • /testing:测试服务器执行器的助手.

特征

LSP 软件

服务器运行时间执行起到LSP方法的代理作用,这意味着它支持所有LSP方法. 除此之外,还可以将LSP方法扩展为支持自定义能力.

特性规格

LSP 窗口

LSP 工作空间

LSP 扩展

认证

运行时间支持两种类型的证书: IAM 全权证书 和 Bearer 令牌(例如 Builder ID) 。 这些全权证书应以简洁文本提供给目的地.

// IAM Credentials data
export interface IamCredentials {
    accessKeyId: string
    secretAccessKey: string
    sessionToken?: string
}

// Bearer Token data
export interface BearerCredentials {
    token: string
}

目的地负责管理资质状态,在状态变化时刷新和更新.

初始化

运行时间默认支持两种类型的证书认证,不需要事先与客户端达成协议或握手. 如果客户端支持特定类型的证书,则相应的LSP update 方法可以直接调用。 对于通过纯文本证书不合适的案件(如独立运行时间),可以在发送到服务器前加密(参见 加密) (中文(简体) ).

特性规格

下表概述了自定义的LSP方法由服务器支持进行认证:

export type Credentials = IamCredentials | BearerCredentials

// Credentials provided to the server by the server's host
export interface UpdateCredentialsPayload {
    // Plaintext IamCredentials/BearerCredentials or JSON blob of encrypted credentials
    data: string | Credentials
    // If the payload is encrypted
    // Defaults to false if undefined or null
    encrypted?: boolean
}

获取连接元数据

服务器 Auth 特性支持在服务器中存储额外的 Auth 连接数据. 获取连接元数据是服务器向客户端发送的请求,以获取新的连接信息. 服务器期望客户端提供指定的元数据 ConnectionMetadata 接口.

export interface ConnectionMetadata {
    sso?: SsoProfileData
}

export interface SsoProfileData {
    startUrl?: string
}

遥测

初始化

运行时间默认支持遥测功能,允许服务器向目的地发送度量衡. 目前正在计划另外在初始化期间和正在进行的会议期间禁用这一特性.

特性规格

遥测通知从服务器发送到客户端,要求客户端登录一个遥测事件. 使用遥测特性的AWS跑时会发出带有指定有效载荷接口的默认LSP遥测通知的计量事件. 遥测通知如下:

export type MetricEvent = {
    name: string
    data?: any
    result?: ResultType
    errorData?: ErrorData
}

日志

设计 TBD

初始化

默认运行时间支持日志功能,允许服务器输出日志,日志级别不同.

特性规格

在日志运行时间中设定的日志级别可以由客户端决定,作为初始化请求的一部分,这是第一个 请求由客户端启动到 LSP 服务器。 日志级别可以在服务器启动后动态更新 workspace/didChangeConfiguration 来自客户端的通知 - 提醒运行时间通过 LSP 从客户端获取新日志级别 getConfigurations 请求.

1. 初始化请求中的参数 : InitializeParams.initializationOptions.logLevel
2. 从运行时间到客户端请求日志级的配置请求参数 : {section: "aws.logLevel"}

聊天

运行时间定义了 Chat 接口,允许运行时间服务器执行器定义聊天事件的处理器,以允许对话体验. 聊天数据类型大多是按下列模式制作的: 我亲爱的,一个为聊天体验设计的驱动UI库的事件. mynah-ui 是建议在目的地使用的 UI 库。 然而 Chat 接口的通用性足以兼容其他 UI 方法

初始化

运行时间默认支持聊天

特性规格

export interface ChatPrompt {
    prompt?: string
    escapedPrompt?: string
    command?: string
}

interface PartialResultParams {
    partialResultToken?: number | string
}

export interface ChatParams extends PartialResultParams {
    tabId: string
    prompt: ChatPrompt
    cursorState?: CursorState[]
    textDocument?: TextDocumentIdentifier
}

完整的聊天参数和结果接口可见于 聊天时间

身份管理

身份管理功能旨在集中管理认证和身份相关功能. API包括:

• 列出和管理用户简介和SSO会议
• 获取有效的 SSO 访问令牌, 根据需要处理 PKCE 或设备代码登录流量
• 控制有效SSO标志的寿命和通知
• 无效缓存的 SSO 令牌

特性规格

完整的身份管理参数和结果接口可见于 身份管理

客户能力

要求客户端执行支持接收以下请求: 1

• window/showDocument

  client.onRequest<ShowDocumentResult, Error>(
      ShowDocumentRequest.method,
      async (params: ShowDocumentParams) => { ... }
  )
  

• window/showMessageRequest

  client.onRequest<MessageActionItem | null, Error>(
      ShowMessageRequest.method,
      async (params: ShowMessageRequestParams) => { ... }
  )
  

• onProgress

  client.onProgress(
      GetSsoTokenProgressType, 
      GetSsoTokenProgressToken,
      async (partialResult: GetSsoTokenProgress) => { 
          // partialResult is likely encrypted
          ...
      }
  )
  

通知

通知功能可以用来向客户发送定制客户端通知. 通知可以包含动作,比如显示 URL,也可以包含后续动作,比如请求客户确认. 当客户端对后续动作作出反应时,预计将从客户端发送到服务器的同步通知,以通知服务器有关此事.

通知应用于需要客户注意的罕见/例外情况(如发生了一些变化或建议采取的行动),但不会阻碍主要流动。 如果发送过多,客户可以决定暂停通知.

考虑使用 LSP 显示信件通知 相反,如果你的通知不需要采取行动或后续行动.

特性规格

代理工具

为了创建代理应用程序,服务器可以定义可以被发送到模型后端使用的工具. 工具可以在多个服务器中创建,并在同一运行时间的所有服务器之间共享. 工具使用中没有JSON/RPC组件,工具都保存在运行时内存中.

工具引用可以使用LSP,工作空间或聊天能力与客户端环境互动.

该代理特性使用以下接口:

export type Agent = {
    /**
     * Add a tool to the local tool repository. Tools with the same name will be overwritten.
     *
     * Tools should be called using `runTool`.
     *
     * @param spec Tool Specification
     * @param handler The async method to execute when the tool is called
     */
    addTool: <T extends InferSchema<S['inputSchema']>, S extends ToolSpec, R>(
        spec: S,
        handler: (input: T, token?: CancellationToken) => Promise<R>
    ) => void

    /**
     * Run a tool by name. This method will lookup the tool in the local tool repository and
     * validate the input against the tool's schema.
     *
     * Throws an error if the tool is not found, or if validation fails.
     *
     * @param toolName The name of the tool to run
     * @param input The input to the tool
     * @returns The result of the tool execution
     */
    runTool: (toolName: string, input: any, token?: CancellationToken) => Promise<any>

    /**
     * Get the list of tools in the local tool repository.
     * @param options Options for the format of the output. Can be either 'bedrock' or 'mcp' (the default)
     * @returns The tool repository in the requested output format
     */
    getTools: <T extends GetToolsOptions>(options?: T) => T extends { format: 'bedrock' } ? BedrockTools : Tools
}

一个典型的代理循环会是这样的:

const AgentServer: Server = ({ chat, agent }) => {

    agent.addTool({
        name: 'use_greeting',
        description: 'A kind greeting to the user'
        inputSchema: {
            type: 'object',
            parameters: {
                name: {
                    type: 'string'
                }
            }
        }
    }, async (input: { name: string }) => {
        return `hello, ${name}`
    })

    chat.onChatPrompt((params: ChatParams) => {
        let currentStep = 0;
        const maxSteps = 5; // Prevent infinite loops
        let finalResponse = '';
        const conversationHistory = [];

        while (currentStep < maxSteps) {
            const response = await invokeModel(conversationHistory, params.prompt.prompt, agent.getTools({format: 'bedrock'})) // or { format: 'mcp' }
            
            // Check if the response includes tool uses
            if (response.tool_use && response.tool_use.length > 0) {
                // Execute each tool use
                const toolResults = await Promise.all(
                    response.tool_use.map((toolUse) => ({
                        toolUseId: toolUse.Id,
                        content: await agent.runTool(toolUse.name, toolUse.input)
                    }))
                )

                // Ensure error handling and validation errors

                // You could also emit partial results here to keep the user informed of progress

                // Add tool results to conversation
                conversationHistory.push({
                    role: "tool",
                    content: JSON.stringify(toolResults)
                })

                // Continue the conversation with tool results
                userInput = `Tool execution results: ${JSON.stringify(toolResults)}. Please continue with the task.`
            } else {
                // No more tool calls needed, return final response
                finalResponse = response.content;
                break;
            }

            currentStep++
        }

        return {
            body: finalResponse
        }
    })

    // disposable
    return () => {
        // Do nothing
    }
}

运行时主机环境

服务器一般作为进程或网络工作人员运行. 下文详细介绍了如何初始化各类服务器运行时间.

服务器初始化流程和特性谈判

Language Server runtimes使用LSP摘要在客户端和服务器之间建立了JSON-RPC连接. 我们使用 Initialize LSP生命周期方法为服务器提供初始化选项.

特性将在执行时立即进行配置 Initialize 主连接的流量.

客户端会发送 Initialize LSP 请求, 带有自定义选项来配置可选特性 InitializeParams.initializationOptions 属性。 在此通过的配置将影响下文所定义的不同能力的执行细节. initializationOptions 可以通过运行时间处理,并根据其执行细节来初始化功能. 关于使用哪些选项的信息,请参见每个功能中的Initilization部分.

独立服务器

功能和模式可以在启动时通过命令行参数传递给服务器. 独立服务器的执行细节是,它可以从一个特殊的开始 --set-credentials-encryption-key 在启动主LSP连接之前输入特殊流程的参数,用于接受加密选项作为参数.

server-standalone.exe

# Server options
[--stdio] - uses stdio as the communication channel (https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#implementationConsiderations)
[--set-credentials-encryption-key] - signal to server to invoke a flow for accepting encryption key before starting main server initialisation.

[--version] - server returns its version

...
# We can define extra options, e.g. extra transport modes to provide compatibility with different clients are also possible.
[--pipe] - use pipes (Windows) or socket files (Linux, Mac) as the communication channel. The pipe / socket file name is passed as the next arg or with —pipe=.
[--socket] - uses a socket as the communication channel. The port is passed as next arg or with —port=.
[--node-ipc] - use node IPC communication between the client and the server. This is only supported if both client and server run under node.

服务器启动图 :

加密

运行时支持以stdio作为传输方式通过LSP传输加密证书. 加密选项必须在 LSP 初始化开始前通过 stdin 发送到运行时间 。 目前,运行时间支持使用256位密钥进行AES对称加密.

以下步骤概述了如何启用加密证书:

1. 随机创建256位(32字节)加密密钥.
2. 通过 --set-credentials-encryption-key 命令行参数到启动时的服务器进程。 这将向服务器发出客户端想要启用加密的信号,并在接下来的5秒内等待加密选项.
3. 立刻派JSON来 stdin ,后面是新行 /n 字符,它将向运行时间显示传输结束。 如果LSP初始化继续,加密选项已被验证并保存. 如果客户端在前5秒未能发送加密选项,或者JSON对象无效,则进程会以状态代码10退出.

{
    "version": "1.0",
    "key": "<base64 encoded encryption key>",
    "mode": "JWT"
}

4. 在LSP初始化完成后,目的地应当通过LSP发送证书并负责不断更新.

要发送加密的证书 UpdateCredentialsPayload 参数应发送到相应的 aws/credentials/${type}/update 方法.

UpdateCredentialsPayload 规格 :

1. - 加密的: 设置为 true · ;
2. - 数据: 代表加密的字符串值 日本 符号 。 加密必须用 { alg: 'dir', enc: 'A256GCM' } 参数。 被加密的有效载荷必须包含带有资质的数据字段.
3. 客户端可以设置 nbf/ 实例 jWT 令牌上的债权,将在运行时验证。 A 类 clockTolerance 在核实索赔时,允许60秒.

// JWT payload to be encrypted
{
   "data": <credentials>
}

网络工人

传统发展

警卫

见 捐款 更多信息.

许可证

这个项目根据Apache-2.0许可证获得许可证.