开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读Command是 Language Server ProtocolLSP中用于在语言服务器与客户端之间传递可执行动作引用的核心类型服务器在补全、Code Action、Code Lens 等请求响应中返回Command字面量客户端将其渲染为 UI 入口再通过workspace/executeCommand请求回传给服务器执行。本文以 3.19 版本规范文档为主体完整解析Command接口的每个字段含 3.18.0 新增的tooltip、其在整个命令执行链路中的角色以及服务器端如何声明executeCommandProvider能力、如何配合WorkspaceEdit完成一次端到端的修复/重构流程。一、Command 类型是什么Command在规范中定义为一个对命令的引用a reference to a command其定义位于 _specifications/lsp/3.19/types/command.md。它本身不包含命令的执行逻辑而是携带三样关键信息用于在用户界面展示的标题、标识实际命令处理器的字符串 ID以及调用时所需的参数列表。命令的真正实现在服务器端或客户端扩展代码中Command只是门牌号与快递单。规范原文明确指出了两点使用前提推荐在服务器端实现命令执行——前提是客户端与服务器都声明了对应的能力即客户端支持workspace.executeCommand服务器声明executeCommandProvider协议目前不定义任何公认命令集合well-known commands也就是说command字段中的字符串 ID 由具体的服务器与客户端实现自行约定LSP 本身不负责注册或规范化这些命令。完整类型定义如下3.19 规范原文interface Command { /** * Title of the command, like save. */ title: string; /** * An optional tooltip. * * since 3.18.0 */ tooltip?: string; /** * The identifier of the actual command handler. */ command: string; /** * Arguments that the command handler should be * invoked with. */ arguments?: LSPAny[]; }在仓库的机器可读元模型中该结构被以完全一致的形式登记在 _specifications/lsp/3.19/metaModel/metaModel.json结构条目名Command包含title: string、可选tooltip: string标注since: 3.18.0、command: string、可选arguments: LSPAny[]四个属性可供各类 SDK 代码生成器直接消费这也说明该类型是协议级的一等公民类型。二、字段逐项解析titleUI 展示标题必填title是命令在用户界面中的展示文本例如save、Fix all、Extract method。它是唯一一个必填的字符串字段客户端通常将其直接渲染为菜单项、Code Lens 内联文字或 Code Action 列表中的按钮文本。规范建议标题保持简短、人类可读例如 _specifications/lsp/3.19/language/codeAction.md 中的示例命令标题为Do Foo。tooltip可选提示气泡3.18.0 新增tooltip自 3.18.0 版本加入用于在 UI 上为命令提供一段可选的悬停提示文本。它属于向后兼容的增量字段旧客户端可以安全地忽略它新客户端则可在鼠标悬停命令入口时展示更详细的说明。在 metaModel.json 中该字段被标记为optional: true且since: 3.18.0。command实际命令处理器的标识必填command是一个字符串标识符指向实际命令处理器。它不会直接出现在 UI 中UI 展示的是title而是被客户端用于在本地命令系统中查找处理器。因为协议不规定公认命令集合这个 ID 必须由服务器与客户端实现方提前约定例如workbench.action.files.save、myLanguageServer.extractMethod这类命名空间化的 ID。arguments传给处理器的参数可选arguments是LSPAny[]类型的可选数组即 JSON 任意值的数组。命令处理器被调用时这些参数会原样透传给执行函数。规范特别强调参数通常在服务器向客户端返回命令时附带指定The arguments are typically specified when a command is returned from the server to the client。典型用法是携带上下文信息例如 Code Action 对应的诊断信息、目标 URI 与位置、需要重构的函数名等。一个完整的CommandJSON 实例如下{ title: Extract to function, command: myLanguageServer.extractFunction, arguments: [ { uri: file:///path/to/file.ts, range: { start: { line: 10, character: 4 }, end: { line: 12, character: 8 } } } ] }三、Command 在协议中的流转闭环Command并非孤立类型它贯穿一条服务器产出 → 客户端展示 → 客户端回传 → 服务器执行的完整链路核心流程记录在 _specifications/lsp/3.19/workspace/executeCommand.md。3.1 产出端哪些请求会返回 Command规范中明确列出会产生Command的请求至少包括textDocument/codeAction返回(Command | CodeAction)[]服务器可返回纯Command字面量也可返回包含command属性的CodeAction字面量详见 _specifications/lsp/3.19/language/codeAction.mdtextDocument/codeLensCodeLens的command字段即为CommandCode Lens 表示应随源代码一起展示的命令例如引用计数、运行测试入口等详见 _specifications/lsp/3.19/language/codeLens.md此外从仓库源码结构看Command同样出现在textDocument/completion、textDocument/inlayHint、textDocument/inlineCompletion等请求的响应类型中作为可选的附带动作。以 Code Action 为例CodeAction类型中command?: Command字段since 3.8.0支持字面量明确规定一个 Code Action 必须设置edit和/或command若两者都提供则先应用edit再执行command。3.2 执行端workspace/executeCommand 请求当用户在 UI 中触发命令后客户端向服务器发送workspace/executeCommand请求methodworkspace/executeCommandparamsExecuteCommandParams定义如下export interface ExecuteCommandParams extends WorkDoneProgressParams { /** * The identifier of the actual command handler. */ command: string; /** * Arguments that the command should be invoked with. */ arguments?: LSPAny[]; }可以看到ExecuteCommandParams与Command的command/arguments字段一一对应——这正印证了Command的语义客户端把Command中携带的标识符与参数原样交还给服务器执行。responseLSPAny若执行过程中发生异常返回带code与message的错误。3.3 结果落地workspace/applyEdit规范明确指出workspace/executeCommand最常见的用法服务器在执行命令后构造一个WorkspaceEdit结构并通过从服务器发往客户端的workspace/applyEdit请求把修改应用到工作区。也就是说命令执行的副作用文件修改、重构、修复通常以结构化编辑而非文本流的形式返回客户端由客户端负责落地从而保证编辑事务的一致性与可撤销性。四、能力协商与动态注册命令执行链路依赖两端能力的协商这部分同样定义在 _specifications/lsp/3.19/workspace/executeCommand.md。客户端能力属性路径workspace.executeCommand类型ExecuteCommandClientCapabilitiesexport interface ExecuteCommandClientCapabilities { /** * Execute command supports dynamic registration. */ dynamicRegistration?: boolean; }服务器能力属性路径executeCommandProvider类型ExecuteCommandOptionsexport interface ExecuteCommandOptions extends WorkDoneProgressOptions { /** * The commands to be executed on the server. */ commands: string[]; }ExecuteCommandOptions.commands是服务器能够执行的命令 ID 白名单——这是服务器在initialize响应中向客户端宣告我认识哪些命令的关键清单客户端可据此过滤或灰化不支持的入口。注册选项ExecuteCommandRegistrationOptions直接继承ExecuteCommandOptions空扩展用于支持动态注册的场景export interface ExecuteCommandRegistrationOptions extends ExecuteCommandOptions { }在服务端能力声明的 JSON 形态大致如下{ capabilities: { executeCommandProvider: { commands: [ myLanguageServer.extractFunction, myLanguageServer.fixAll ], workDoneProgress: true } } }五、Code Action / Code Lens 中的 Command 实战要点5.1 服务器应自行处理命令_specifications/lsp/3.19/language/codeAction.md 明确建议为了让服务器在众多客户端中都能正常工作Code Action 中指定的命令应由服务器处理配合workspace/executeCommand与ServerCapabilities.executeCommandProvider而不是由客户端处理。如果客户端支持随 Code Action 直接附带编辑edit则应优先使用该模式以减少一次服务器往返。5.2 延迟计算与 resolve 链路自 3.16.0 起客户端可通过codeAction.resolveSupport声明可延迟计算的属性例如edit服务器则通过codeActionProvider.resolveProvider声明提供codeAction/resolve路由。此时服务器可先返回一个未完全填充的CodeAction仅含title待客户端通过codeAction/resolve请求补齐edit。Command在 Code Action 中承担了轻量占位、按需执行的角色若edit计算昂贵或体积庞大服务器可以只返回命令让真正的工作延后到用户触发时再执行。同类机制也存在于 Code Lens 上CodeLens的command字段可选未关联命令的 Code Lens 被视为unresolved需通过codeLens/resolve请求补全CodeLens定义见 _specifications/lsp/3.19/language/codeLens.md。5.3 参数携带与数据保真在 resolve 场景中CodeAction与CodeLens都提供了data?: LSPAny字段用于在初始请求与 resolve 请求之间保留上下文。作为对比Command的arguments承担类似职责命令在 UI 中通常被存放一段时间后才被触发因此服务器应把执行所需的一切上下文目标 URI、range、诊断等打包进arguments保证命令被触发时无需重新计算或猜测上下文。六、设计要点与版本演进小结回顾Command类型的设计可以总结出以下几个值得注意的协议原则引用而非实现Command只携带标题 ID 参数执行逻辑归属服务器或扩展代码协议层面不约束实现方式开放的命令命名空间协议不定义 well-known commands命令 ID 由实现双方约定这保证了不同语言服务器可以自由扩展自己的命令集也意味着客户端必须以未知命令的心态优雅降级参数全 JSON 化arguments使用LSPAny[]任何可 JSON 序列化的数据都可以作为命令参数传递保持了协议的传输层中立性能力先行服务器必须在executeCommandProvider.commands中明确声明可执行命令清单客户端在ExecuteCommandClientCapabilities中声明支持与动态注册能力双向协商后才可安全使用命令链路渐进式版本演进tooltip字段于 3.18.0 引入属于增量可选字段未来协议版本对Command的扩展如新增可选字段大概率同样遵循可选 向后兼容的模式。元模型文件 _specifications/lsp/3.19/metaModel/metaModel.json 与类型文档 _specifications/lsp/3.19/types/command.md 始终保持同步可作为版本差异对照的权威依据。七、结语Command虽是一个仅有四个字段的小类型却是 LSP 中客户端 UI 动作与服务器执行逻辑之间的桥梁它让补全项、Code Lens、Code Action 可以附带可执行动作让服务器可以把昂贵的计算推迟到用户真正点击时才进行也让workspace/executeCommandworkspace/applyEdit的触发—执行—落地闭环得以成立。对于语言服务器与客户端 SDK 的实现者而言正确理解Command的字段语义、能力协商流程与 resolve 机制是交付高质量交互体验如引用计数、快速修复、重构菜单的基础。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐Language Server Protocol 3.18 Command 类型全解析从 CodeAction 到 workspace/executeCommand 的命令分发机制Language Server Protocol 3.18 Command 类型全解析从 CodeAction 到 workspace/executeComm开发工具Language Server Protocol 3.18 的 workspace/executeCommand从 Command 下发到服务端执行与 WorkspaceEdit 回写完整链路Language Server Protocol 3.18 的 workspace/executeCommand从 Command 下发到服务端执行与 Wor开发工具Language Server Protocol 3.17 详解workspace/executeCommand 命令执行请求的完整机制与实战指南Language Server Protocol 3.17 详解 workspace/executeCommand 命令执行请求的完整机制与实战指南 导读本开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考