DeepSeek Harness LSP 语义导航解析

让 AI 编码智能体真正"读懂"代码，光靠文本检索是不够的：grep 能找到字符串，却回答不了"这个函数在哪里定义""还有谁在调用它"这类语义问题。DeepSeek Harness 为此接入了一套 LSP（Language Server Protocol，语言服务器协议）语义导航能力，并把它设计成一个独立的能力接缝：在单一的 ctx.lsp 服务上对外公开语义代码导航。接缝不是单一模块，它在物理上拆成三层：服务定义层提供 ctx.lsp 服务与提供方注册表；通用服务提供方层是一个经过配置的 stdio 语言服务器宿主；消费方则是模型实际看到并调用的 lsp 工具 schema。三层各管一段，边界清楚：更换语言服务器提供方，不会改变模型请求导航的方式。

值得强调的是，LSP 在这套框架里是一项可选能力，不属于 agent loop 主干。正因如此，它的词汇定义放在子系统文档里而不进入核心文档，不需要导航能力的部署可以完全不加载它，核心循环保持干净。

DeepSeek Harness LSP 能力接缝三层架构图

只开放四种查询，联合是闭合的

接缝对模型公开的语义查询恰好只有四种：goToDefinition 跳到定义，findReferences 查找引用，goToImplementation 跳到实现，hover 提供悬浮信息。这是一个闭合联合：想新增一种查询，编译器会强制你同步修改接缝、提供方和工具三处，漏掉任何一处都过不了编译。符号与调用层次刻意没有列为操作，因为它们需要不同的请求与结果 schema，硬塞进来只会破坏闭合性。

坐标约定是这类设计里最容易踩坑的部分。接缝内部与 LSP 协议保持一致，使用从零开始的 UTF-16 坐标；而面向模型的工具采用从 1 开始的光标约定，对人和模型都更直观。两个坐标系在工具边界做双向转换，模型永远只面对一种坐标习惯。

LSP 语义查询完整流程图

请求没有默认值，结果没有逃生口

请求模型的设计原则是每个字段都必填。workspaceRoot 由调用方提供；languageId 不出现在请求里，它来自提供方注册时的扩展名映射，由接缝派生；超时与结果上限由消费方决定。于是没有任何字段需要实现方提供默认值，也就不存在协议里常见的 resolve() 两段式步骤。派生出的 languageId 只用于同步瞬态文档，从不参与提供方选择。

结果同样是一个闭合的可辨识联合：三种导航操作统一规范化为 locations 列表，hover 规范化为内容或 null。消费方用 switch 对 kind 做穷尽处理，新增分支会让编译失败，直到处理完毕，运行期不会遇到没见过的结果形状。

两个细节值得单独说。其一，findReferences 的结果始终包含声明本身，这一点由提供方在内部强制保证，调用方没有对应的开关，也就没有开错的可能。其二，locations 变体会携带 resolvedWorkspaceUri，即提供方的规范工作区 file: URI。调用方把结果里的绝对 URI 转成相对路径时，必须使用这个 URI，而不是拿请求里可能经过符号链接的路径去套宿主平台的路径规则，因为提供方的执行平台可能和调用方不同。

提供方注册：要么全部成功，要么什么都不发生

每个提供方拥有一个稳定的品牌化 id，以及一份扩展名到语言 id 的映射，键为小写、点开头，例如 .ts 映射到 typescript。registerProvider 会原子性地预留 id 和每一个扩展名：注册无效或发生冲突时，什么都不会发布并抛出 LspError；返回的 disposer 会一次性释放全部预留项，资源随调用方一起销毁，不会留下半更新的注册表。

每次查询独立选择提供方，且选择与注册顺序无关：按文件扩展名匹配注册表，没有匹配项就抛出错误码 LSP_UNAVAILABLE。接缝不公开协议类型、进程句柄或文档控制接口，也不提供通用的 JSON-RPC 逃生口，从根上杜绝调用方绕过规范化直接说协议方言。

错误处理按码不按文案。LspError 扩展自框架的 HarnessError，提供一组稳定错误码：LSP_INVALID_PROVIDER、LSP_CONFLICT、LSP_UNAVAILABLE、LSP_DISPOSED、LSP_UNSUPPORTED_OPERATION 和 LSP_MALFORMED_RESPONSE。调用方应按错误码做路由，而不是解析 message 文本，文案随时可能变，错误码不会。