开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读本文基于本仓库_specifications/lsp/3.19/types/partialResults.md规范文档系统讲解 LSP 3.15 起引入的 Partial Result Progress部分结果进度机制服务器如何在客户端允许的前提下通过通用的$/progress通知将workspace/symbol、textDocument/reference等请求的超大结果集分批增量返回以及错误发生时客户端应如何正确处理已收到的部分结果。读完本文你将掌握partialResultToken的传递方式、$/progress通知的载荷结构、结果追加与最终响应置空的协议约定并能据此在语言服务器与客户端中实现可流式返回的结果通道。一、Partial Result 机制的由来与定位1.1 版本与协议地位Partial Result Progress 是 Language Server Protocol 自3.15.0版本起正式引入的能力。它在协议中归属于请求参数层面的通用基础设施与 Work Done Progress 并列由以下规范文档共同定义Partial Result Progress 说明本文核心定义机制与错误处理规则PartialResultParams 类型定义承载partialResultToken的参数字面量接口Work Done Progress 类型定义同源于$/progress通知的兄弟机制。注意虽然本节仓库同时维护了 3.17、3.18、3.19 三个版本目录但 partialResults.md 在 3.18 与 3.19 中的内容完全一致均标注 Since 3.15.0。Partial Result 语义自 3.15 定型后保持稳定本文以 3.19 版本为准展开。1.2 为什么需要 Partial Result在未引入该机制之前像workspace/symbol工作区符号检索、textDocument/reference查找引用这类请求服务器必须等全部结果收集完毕后再一次性返回完整数组。当结果集规模巨大例如全仓引用、全局符号索引时客户端 UI 长时间空白无反馈网络传输单个超大 JSON 响应首屏渲染延迟高服务器内存被一次性的大结果集占用。Partial Result 解决的是结果本身的分批投递问题服务器边收集边推送客户端边接收边展示配合 Work Done Progress 的进度提示形成完整的流式结果 进度反馈体验。二、核心机制$/progress通知 partialResultToken2.1 通用进度通知$/progressPartial Result 与 Work Done Progress 共享同一个通用的$/progress通知通道。从本仓库的 3.19 metaModel.json 可见其在元模型中的定义{ method: $/progress, typeName: ProgressNotification, messageDirection: both, params: { kind: reference, name: ProgressParams } }要点$/progress的messageDirection为both即客户端与服务器双向都可发送其参数结构ProgressParams形如{ token: ProgressToken, value: { ... } }其中token用于把通知关联到某一次具体的请求value则根据通知类型携带不同的载荷Work Done 的 begin/report/end 或 Partial Result 的结果数组。2.2 什么请求支持 Partial Result并非所有请求都支持部分结果。从 3.19 metaModel.json 中可以看到大量请求结构的mixins同时注入了WorkDoneProgressParams与PartialResultParams例如ImplementationParamsmetaModel.json 第 2413-2430 行{ name: ImplementationParams, extends: [{ kind: reference, name: TextDocumentPositionParams }], mixins: [ { kind: reference, name: WorkDoneProgressParams }, { kind: reference, name: PartialResultParams } ] }同理textDocument/reference、workspace/symbol、textDocument/documentSymbol、workspace/executeCommand等请求在元模型中均以PartialResultParams作为 mixin全文检索可见PartialResultParams在 metaModel.json 中出现 26 处覆盖了语言特性类与工作区类的主要查询请求。PartialResultParams本身的完整定义见 partialResultParams.mdexport interface PartialResultParams { /** * An optional token that a server can use to report partial results (e.g. * streaming) to the client. */ partialResultToken?: ProgressToken; }ProgressToken类型metaModel.json 第 15863 行为integer | string的联合类型即令牌既可以是整数编号也可以是字符串 UUID。2.3 一次完整的 Partial Result 交互规范文档给出了一个同时支持 Work Done 与 Partial Result 的textDocument/reference请求示例{ textDocument: { uri: file:///folder/file.ts }, position: { line: 9, character: 5 }, context: { includeDeclaration: true }, // The token used to report work done progress. workDoneToken: 1d546990-40a3-4b77-b134-46622995f6ae, // The token used to report partial result progress. partialResultToken: 5f6f349e-4f81-4a3b-afff-ee04bff96804 }字段解读字段含义textDocument.uri目标文档的file://URIposition.line/position.character引用符号所在位置0 基context.includeDeclaration是否包含声明位置本身workDoneToken供服务器发送进度 begin/report/end 通知的令牌partialResultToken供服务器发送部分结果通知的令牌服务器收到请求后用partialResultToken作为$/progress通知的token字段逐批推送结果。例如查找引用返回前两批结果时{ token: 5f6f349e-4f81-4a3b-afff-ee04bff96804, value: [ { uri: file:///folder/file.ts, range: { start: { line: 12, character: 8 }, end: { line: 12, character: 16 } } } ] }后续批次继续以同一 token 追加发送。三、服务器端的协议约定发送方规则规范对服务器发送 Partial Result 提出了两条刚性约定这是实现时最容易出错、也最需要严格遵守的部分3.1 全部结果必须走$/progress最终响应结果必须为空If a server reports partial result via a corresponding$/progress, the whole result must be reported using$/progressnotifications, each of which appends items to the result. The final response has to be empty in terms of result values.即一旦服务器决定用$/progress上报部分结果就必须把所有结果都通过$/progress通知发出每一条通知向结果集追加一批条目最终请求响应中的结果值必须为空。例如textDocument/reference的正常响应类型为Location[]走 Partial Result 时最终响应应为{ jsonrpc: 2.0, id: 1, result: [] }即空数组 / null 结果值。之所以这样设计规范给出的理由是避免混淆最终结果应如何解读——例如收到完整结果时客户端无法判断它到底是又一个部分结果、还是一个替换性的最终结果。通过响应结果为空 所有数据走通知的明确约定客户端可以无歧义地合并所有$/progress载荷。3.2 载荷结构与最终结果类型一致The value payload of a partial result progress notification is in most cases the same as the final result.部分结果的载荷类型与最终结果类型基本一致。例如workspace/symbol的最终结果是SymbolInformation[] | WorkspaceSymbol[]那么每条$/progress的value也是SymbolInformation[] | WorkspaceSymbol[]——即每条通知携带一段同类型的数组切片而不是单个条目。3.3 一个 token 的一次性使用与 Work Done Progress 的服务器主动进度window/workDoneProgress/create创建的 token 仅能使用一次不同Partial Result 的 token 由客户端随请求下发其生命周期绑定本次请求token 仅在请求发出后、响应返回前这段时间内有效。服务器应保证在响应返回前完成所有部分结果通知的发送。四、客户端处理规则接收方与错误语义4.1 正常路径增量合并客户端收到以partialResultToken为 token 的$/progress通知后应将通知value中的条目追加到该请求的结果集合中。多个$/progress通知之间是有序追加关系append客户端按收到顺序合并即可无需去重或排序。4.2 错误路径按错误码区分处理规范明确规定若请求最终响应报错已收到的部分结果按以下规则处理响应错误code客户端处理方式RequestCancelled即-32800请求被取消可以使用已收到的结果但必须向用户明确该请求已被取消、结果可能不完整其他所有错误码丢弃已收到的部分结果不得使用用伪代码表述客户端逻辑onRequestError(error, collectedPartialResults) { if (error.code RequestCancelled) { // 可用但需标注请求已取消结果可能不完整 ui.showResults(collectedPartialResults, { incomplete: true }); } else { // 其他错误丢弃 discard(collectedPartialResults); } }4.3 客户端能力信号按请求实例逐次声明值得注意协议中没有客户端是否支持 Partial Result的静态能力声明如clientCapabilities中的固定开关。原因正如 Work Done Progress 章节所解释的——对多数客户端而言这不是静态属性同一个请求类型在不同实例上可能不同。因此客户端是否接受部分结果通过每个请求参数中是否存在partialResultToken字段来逐次声明。服务器不应假设客户端总是支持也不应要求客户端预先声明全局能力。服务器侧对应的支持情况通过具体请求的能力项声明例如referencesProvider中可带workDoneProgress选项但 Partial Result 本身同样不设独立的静态 capability全部依赖请求实例上的 token 存在性。五、从元模型看 Partial Result 在 3.19 的覆盖范围为了验证哪些请求真正接入了 Partial Result可在 3.19 metaModel.json 中检索name: PartialResultParams出现的 26 处位置它们分别出现在以下请求/注册结构的mixins中节选ImplementationParams第 2413-2430 行TypeDefinitionParams、DeclarationParams、ReferencesParams同构结构DocumentSymbolParams、WorkspaceSymbolParams、CodeLensParams、DocumentLinkParams、DocumentColorParams、FoldingRangeParams、SelectionRangeParams、InlayHintParams、CallHierarchy*Params、MonikerParams等据此可以总结出三类典型场景引用/定义类查询textDocument/reference、textDocument/declaration、textDocument/typeDefinition、textDocument/implementation——结果是一批Location天然适合流式返回文档/工作区符号textDocument/documentSymbol、workspace/symbol——全仓或大文件符号集合可能很大文档内散点数据textDocument/codeLens、textDocument/documentLink、textDocument/foldingRange、textDocument/documentColor、textDocument/inlayHint等——文档级请求虽然结果相对可控但协议同样允许流式返回以降低单次响应体积。以上请求名单为从元模型 mixins 中可推断的实现事实具体到某个语言服务器是否真的对某个请求启用 Partial Result取决于该服务器实现客户端仍需按token 存在即支持的规则适配。六、实现要点与最佳实践综合规范与元模型证据落地 Partial Result 时建议遵循以下要点客户端侧仅在确实需要流式展示如引用面板渐进填充时才在请求参数中附加partialResultToken收到$/progress通知时按 token 路由到对应请求并持续追加合并收到最终响应后若result为空数组而此前已有部分结果则直接用合并结果若响应报错则按第 4.2 节规则处理。服务器侧当请求携带partialResultToken时不要等全部结果收集完再一次性返回而是分批构造$/progress通知token partialResultTokenvalue 结果切片全部发完后返回空结果最终响应结果置空是强制性约定切不可通知发一半、响应再带部分数据否则客户端将无法区分追加与替换语义。取消语义若请求被取消响应应带RequestCancelled错误码此时客户端可保留已收到的部分结果并标注不完整其他错误则必须丢弃部分结果避免把错误场景的残缺数据当作有效结果展示。与 Work Done Progress 协同两者共享$/progress通道但语义不同进度 vs 数据。实现时可同时下发workDoneToken与partialResultToken进度与数据并行推进但务必区分通知载荷类型避免混淆。七、小结Partial Result Progress 是 LSP 3.15 引入、在 3.19 中保持稳定的通用流式结果机制客户端通过请求参数中的partialResultToken逐实例声明支持服务器通过$/progress通知以追加切片的方式推送与最终结果同类型的数据最终响应结果置空错误时按RequestCancelled与其他错误码分别决定可保留但标注不完整或整体丢弃。该机制与 Work Done Progress 共同构成了 LSP 面向长耗时、大结果量请求的完整反馈方案是workspace/symbol、textDocument/reference等高成本查询在现代语言服务器与编辑器集成中实现边算边出体验的基础设施。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐Language Server Protocol 部分结果进度Partial Result Progress机制详解基于 $/progress 的流式结果报告Language Server Protocol 部分结果进度Partial Result Progress机制详解基于 $/progress 的流式结果开发工具如何写出自己的KittenBlock扩展以ps2-controller为例从Blockly积木到Python代码生成全解如何写出自己的KittenBlock扩展以ps2 controller为例从Blockly积木到Python代码生成全解 本文以 ps2 controlle开发工具opencodex 中的 Cursor 用量上报修复方案基于累计上下文与错误路径发射的 WP1 计划全解析opencodex 中的 Cursor 用量上报修复方案基于累计上下文与错误路径发射的 WP1 计划全解析 导读 本文以 opencodex 仓库中 devl开发工具上一篇探索 psutilsWindows 上的实用 PowerShell 命令工具集下一篇Compositional Numeric Library核心特性解析从fixed-precision到scaled integers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考