DeepSeek Harness LSP 能力接缝Capability Seam为 Agent 提供精准的语义代码导航工具【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness导读本文围绕 DeepSeek Harness 中 LSPLanguage Server Protocol能力接缝的设计与实现展开讲解 Harness 如何通过dsh-lsp、dsh-lsp-stdio、dsh-tool-lsp三个包为模型 Agent 提供goToDefinition、findReferences、goToImplementation、hover四类语义查询工具。读完本文你将理解这套三包分层背后的模型契约、Provider 注册与选择机制、stdio 本地语言服务器的进程与文档生命周期管理以及如何在部署中通过cordis.yml显式配置语言服务器并接入模型工具。背景文本搜索无法替代符号语义Harness 原有能力中Agent 只有文本搜索search和文件读取read两种代码导航手段。但文本匹配存在天然局限它无法可靠区分两个同名函数、无法跟随 import 别名、无法把接口连接到它的实现类、也无法报告推断出的类型。在修改代码之前Agent 缺少人类从编辑器语言服务器获得的那种语义导航能力。原设计文档2026-07-15-lsp-capability-seam.md指出LSP 支持横跨三方职责模型需要稳定的查询契约、Harness 需要 Provider 选择与结果归一化、本地实现需要进程/JSON-RPC/工作区/同步/文件系统行为。如果把它们揉在一起就会把模型契约绑定到本地子进程上从而阻碍远程或沙箱原生 Provider 的接入。此外多数语言服务器在以当前文本打开被查询文档时表现最佳因此兼容的 Agent 客户端必须约束文档状态、定义源文件读取是否为模型观测并让文档快照与服务器的工作区索引处于同一文件系统命名空间。总体设计三包能力接缝方案是在packages/lsp/下建立一个三包能力接缝对外暴露一个只读模型工具一个通用本地 Provider 实现deepseek-ai/dsh-lsppackages/lsp/lsp拥有ctx.lsp、Provider 注册与选择、归一化的请求/结果、执行控制与结构化 LSP 错误。deepseek-ai/dsh-lsp-stdiopackages/lsp/lsp-stdio把配置的 stdio 语言服务器适配到接缝上。一个插件实例接受一个具名服务器表为每条命令和扩展名→语言 id映射注册一个隔离的 Provider。deepseek-ai/dsh-tool-lsppackages/lsp/tool-lsp拥有模型可见的lsp工具 schema、提示词引导、参数校验、结果上限与格式化以及传输无关的 UI 呈现。dsh-lsp-stdio是通用宿主而不是语言服务器目录或安装器。部署必须显式配置命令与映射未来的预置preset应属于组合插件或cordis.yml覆盖层。模型与接缝只暴露四个操作不提供任意 JSON-RPC 方法逃逸通道ctx.lsp上不存在 escape hatch。这四个操作字面量对齐了 Claude Code 熟悉的 camelCase 命名而工具名与file_path字段仍由 Harness 持有。系统提示词将 LSP 定位为精准辅助Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references.接缝契约ctx.lsp的类型与语义dsh-lsp包在 types.ts 中定义了完整的接缝词汇表位置与范围均为零基 UTF-16与 LSP 协议一致模型工具侧再负责一基游标换算。核心契约如下import type { Branded } from deepseek-ai/dsh-brand type LspOperation goToDefinition | findReferences | goToImplementation | hover type LspProviderId BrandedLspProviderId interface LspPosition { readonly line: number readonly character: number } interface LspRange { readonly start: LspPosition readonly end: LspPosition } interface LspQueryRequest { readonly operation: LspOperation readonly filePath: string readonly position: LspPosition readonly workspaceRoot: string } interface LspProviderQuery extends LspQueryRequest { readonly languageId: string } type LspQueryResult | { readonly kind: locations; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceUri: string } | { readonly kind: hover; readonly hover: { readonly contents: string; readonly range?: LspRange } | null } interface LspProvider { readonly id: LspProviderId readonly extensionToLanguage: ReadonlyRecordstring, string query(request: LspProviderQuery, signal?: AbortSignal): PromiseLspQueryResult } interface LspService { registerProvider(provider: LspProvider): () void query(request: LspQueryRequest, signal?: AbortSignal): PromiseLspQueryResult }几个值得注意的语义设计点均可在 index.ts 的实现中验证原子注册registerProvider()先完整校验并冲突检查再一次性保留品牌化 id 与全部归一化扩展名任一输入无效或冲突则什么都不发布disposer 会释放全部保留。Provider 插件通过ctx.effect()注册。按扩展名、与顺序无关的选择query()用finalExtension()提取文件最终扩展名小写、带前导点如Foo.TS→.ts、foo.d.ts→.ts在路由表中查找无匹配抛出结构化LSP_UNAVAILABLE错误。选择发生在每次查询时与注册顺序无关。单一query()操作由于没有需要实现默认值的字段workspaceRoot必填、languageId来自注册、超时与结果上限由消费方持有接缝不需要resolve()或query(spec)的两步式 API把选择与调用原子化绑定到注册生命周期。闭合结果联合导航操作归一化为locationshover归一化为内容或nulllocations变体携带 Provider 的规范工作区file:URIresolvedWorkspaceUri消费方必须用它来相对化文件 URI而不能用宿主机路径规则解析可能带符号链接的进程路径——因为执行平台可能与调用方不同。无协议类型泄漏接缝不暴露协议类型、进程/文档控制、通用请求逃逸通道。findReferences总是包含声明Provider 内部强制执行本地映射设置context.includeDeclaration: true调用方拿不到开关。模型可见的工具契约dsh-tool-lsp在 index.ts 中注册唯一的lsp工具输入 schema 如下interface LspToolInput { readonly operation: goToDefinition | findReferences | goToImplementation | hover readonly file_path: string readonly line: number readonly character: number }line与character是正的、一基 UTF-16游标坐标工具在 render.ts 的parseLspArgs中转换为接缝的零基LspPositionline - 1/character - 1渲染位置时再转回一基。Provider、语言 id、工作区根、上限、超时、初始化与可执行文件都不在模型输入范围内。工作区根来自会话header.cwdsession-cwd.ts 中exec.agent?.session.header.cwd无回退缺失时在查询与启动之前就以LSP_WORKSPACE_REQUIRED失败。本地 Provider 对相对路径基于该根解析也接受绝对路径两种形式都会在启动前规范化目标在工作区之外则拒绝。结果渲染位置渲染为稳定的、按文件分组的path:line:character条目一基不套用 Harness 宿主路径规则。有效的file:URI 在 Provider 规范工作区 URI 之内变成相对路径之外则变成由 URI 派生的绝对路径畸形与非file:URI 保持原样。maxLocations默认100超限时报告省略数maxResultChars默认16_000对每个完整渲染结果含截断元数据本身设上限。空结果也是成功空 locations 与nullhover 都是无结果的成功响应缺失或畸形的服务器载荷则以结构化LSP_MALFORMED_RESPONSE失败见translate.ts的malformedResponse。UI 呈现保持纯函数presentLspCall使用{ card: generic, kind: search, title, locations: [{ path: file_path, line }] }title 由 args 派生出操作与游标由于共享的FileLocation无 character 字段title 保留列号卡片聚焦输入行。运行时注入最小化插件只注入tools、lsp、systemPrompt三个服务不 import 任何 Provider。超时归属单一调用方预算超时是职责边界上的敏感点文档与实现给出了一套清晰的归属规则dsh-tool-lsp在工具定义上挂一个可配置的timeoutMs预算默认60_000DEFAULT_LSP_TOOL_TIMEOUT_MS由dsh-tool-call-timeout-policy强制执行并提供exec.signal该信号直达ctx.lsp.query。预算覆盖完整的排队打开/查询/关闭生命周期模型不可配置。接缝与 Provider不加任何启动或请求期限。非工具调用方因此不会得到隐藏超时必须自行提供AbortSignal需要预算时使用deadline()。Provider 的销毁发生在工具执行之外所以dsh-lsp-stdio单独持有shutdownTimeoutMs默认5_000用于shutdown/exit与killGraceMs默认2_000用于请求取消宽限和 SIGTERM→SIGKILL 升级失败的实例清理同样受这两个界限约束。计时值超过 Node 调度上限2_147_483_647ms 时加载失败tool-lsp的assertTimer与MAX_TIMER_DELAY_MS。工作区、文件系统与文档同步dsh-lsp-stdio在语言服务器所在的执行世界中通过ctx.fs规范化和读取文件host.ts要求工作区目标是目录canonicalizeWorkspace用fs.resolvefs.stat校验类型返回稳定FsTarget池身份、进程路径子进程 cwd与file:URI。通过 Provider 自有的包含检查拒绝工作区之外的源readHostSource消费streamText并在数据块到达时强制maxDocumentBytes。Provider 保留常规文件校验与 UTF-8 解码协议消费方持有自己的文档上限。每次文件系统操作都把调用方取消与 Provider 销毁融合在一起入队前跟踪工作区查找销毁时等待这些查找完成。不发射fs/observed只有 LSP 结果对模型可见因此该查询不满足写前读read-before-write策略。read工具不适合作为源它的输出是分窗的、带行号、对转录可见且被观测的。若在tool-lsp里读取还会把 Provider 特定的同步职责分配给消费方并排除非本地 Provider。兼容优先的瞬态打开序列本地 Provider 对每次查询使用一条兼容优先的瞬态打开序列见 instance.ts 的runQuery通过ctx.fs解析并包含源文件在同一 Provider 上流式读取当前文本同时强制文档字节上限。发送textDocument/didOpenversion: 1、全文、配置的语言 id。写入保持可中止失败或取消会使实例失效并在池可复用前等待有界的进程终止。发送请求的操作textDocument/definition、textDocument/references、textDocument/implementation或textDocument/hover映射见translate.ts的requestMethod。若didOpen成功则在请求 settle 或中止后于finally中尝试textDocument/didClose。关闭写入失败不会替换已定的结果或错误但会使实例失效并等待有界进程终止。每次调用后文档即关闭因此首个版本不需要didChange、didSave、内容缓存、变更监听器或文档 LRU。每个工作区一条可中止的 Provider 队列把读源/打开/查询/关闭生命周期串行化排队的查询只在轮到自己时读取当前字节不同工作区可并行。服务器的工作区索引仍负责从源触达的已关闭文件。兼容性判定supportsTransientOpen接受传统textDocumentSync的Full1或Incremental2枚举或openClose: true的选项形式省略、None0或显式不兼容的同步形式都会在didOpen之前以不支持失败。本地服务器生命周期与协议行为dsh-lsp-stdio按(provider id, 规范工作区目标)惰性单飞一台服务器加载时用配置的环境调用ctx.subprocess.resolveExecutable()不可用则注册前失败首次查询通过无 shell 的裸协议管道启动保留有界的 stderr 尾部。字节上限maxMessageBytes默认16_000_000、maxStderrBytes默认1_000_000、maxDocumentBytes默认4_000_000见 README.md 配置表。崩溃会使当前查询失败且不重放后续查询可替换进程。MVP 没有跨请求重启计数器。初始化connection.tsinstance.ts的CLIENT_CAPABILITIESprocessId: null——因为客户端与服务器可能处于不同的进程命名空间。声明general.positionEncodings: [utf-16]、workspace: { workspaceFolders: true, configuration: true }、textDocument.hover.contentFormat: [markdown, plaintext]、linkSupport: true针对 definition 与 implementation无动态注册。返回的操作与同步能力是权威的服务器省略positionEncoding默认utf-16任何其他值都是协议错误negotiatePositionEncoding。配置可提供初始化选项与workspace/configuration应答但客户端拒绝workspace/applyEdit绝不执行命令或编辑answerServerRequest。归一化纯函数见translate.ts导航Location直接映射LocationLink从targetUritargetSelectionRange映射位置必须是非负整数畸形载荷抛LSP_MALFORMED_RESPONSE。Hover只接受有效的MarkupContent与MarkedString形状字符串值原样保留语言标签值渲染为围栏代码块数组以空行拼接。maxResultChars由模型工具在渲染后施加。中止与销毁中止到达每个查询阶段id 一旦存在就发送$/cancelRequest无响应的服务器会被终止并等待实例串行化保证了不会伤及并行工作。销毁会拒绝并取消工作、尝试优雅关闭、通过有界终止升级、并等待静默tearDown优雅shutdown/exit→forceTerminate树级终止 → 等待进程树退出。部署配置示例把本地语言服务器接入 Agent需要在cordis.yml或等价插件配置中依次挂载文件系统与子进程 Provider同一执行世界、dsh-lsp接缝、dsh-lsp-stdio本地宿主以及dsh-tool-lsp模型工具。以下配置取自 dsh-lsp-stdio 的 README- name: deepseek-ai/dsh-fs-local - name: deepseek-ai/dsh-subprocess-local - name: deepseek-ai/dsh-lsp - name: deepseek-ai/dsh-lsp-stdio config: servers: typescript: command: typescript-language-server args: [--stdio] extensionToLanguage: .ts: typescript - name: deepseek-ai/dsh-tool-lspservers记录把每个稳定 Provider id 映射到一条服务器命令。每条可执行文件都在加载时凭据擦洗后解析坏条目会阻止所有 Provider 注册进程在首次匹配查询时才惰性启动。字段语义汇总与 README.md 及生成配置目录 docs/config-catalog.md 一致字段默认值含义command必填要启动的可执行文件——绝对路径或在子进程 PATH 上于加载时解析无 shell 启动extensionToLanguage必填小写前导点扩展名 → LSP 语言 id如{ .ts: typescript }args[]传给可执行文件的参数env{}在凭据擦洗后的环境之上合并的额外环境匹配KEY/PASSWORD/SECRET/TOKEN的变量与所有DSH_*名称不会转发initializationOptionsnull转发给服务器的静态initialize选项configurationnull对每个workspace/configuration项的静态应答maxMessageBytes16000000接受的单个最大分帧消息maxStderrBytes1000000为诊断保留的最大 stderr 尾部maxDocumentBytes4000000本宿主打开的最大源文件shutdownTimeoutMs5000优雅shutdown/exit的预算killGraceMs2000请求取消与 SIGTERM→SIGKILL 升级的宽限servers必须至少含一个非空 id 条目计时预算必须是 Node 计时范围内的正整数字节上限必须为正。安全边界Provider 信任其配置的服务器不附加任何沙箱服务器获得挂载执行世界的文件系统与进程权限。查询源在服务器启动前就被拒绝缺失、非常规、非 UTF-8、超大或规范上超出工作区。结果位置可能指向工作区外但外部路径永远不会成为查询源。为同一执行世界挂载文件系统与子进程 Provider 是硬性要求——跨世界组合是无效的。刻意延迟的 APISymbols符号搜索需要不同的 schema且与 read/search 重叠未来的工作区符号工具必须接受搜索查询。Call hierarchy调用层级支持参差不齐prepareCallHierarchy只是内部前置步骤而非模型操作。Diagnostics诊断需要独立的时效性、累积与转录规则。Mutation变更重命名、代码操作、格式化等需要独立的工具并整合预览、权限与写策略。扩展名独占性扩展名在单个运行时内是排他的——两个 Provider 不能同时认领.ts即使语言 id 不同。这是有意的 MVP 限制预期的演进方向是在注册之上增加部署配置的选择器可以在不把 Provider 选择塞进模型输入、也不改变LspProvider.query的前提下放宽独占保留。替代方案回顾设计文档记录了被否决的候选方案有助于理解最终形态照搬 Claude Code 的统一 schema其游标操作验证了核心用例但 symbols 与 call hierarchy 需要不同参数照搬全部九个操作会冻结投机性表面积因此接缝只对齐四个语义查询。让 Provider 注册工具加载的服务器会控制模型 schema 与提示词破坏跨本地/远程 Provider 的稳定契约。暴露任意 LSP 方法JSON-RPC 逃逸通道会泄漏协议载荷并允许未审查的变更或命令执行操作联合保持闭合。暴露resolve(request)/query(spec)没有需默认字段时resolve 只会暴露 Provider 选择且公开 spec 可能活得比 Provider 销毁更久。把 signal 包装进 LSP 执行上下文对象Web 传裸AbortSignal包装单一字段会造成无法解释的不对称。通过模型可见的read工具读取源输出分窗、带行号、转录可见且被观测Provider 直接通过同一ctx.fs执行世界消费流式全文。保持文档打开镜像编辑需要版本所有权、全路径didChange、HMR 恢复、驱逐与陈旧状态规则瞬态打开避免了这套 MVP 状态机。配置分阶段超时嵌套计时器造成互相竞争的分类与新预算单一调用方期限覆盖查询工作只有调用外的拆除保留本地界限。不didOpen直接查询虽被允许但支持不一致可能使用陈旧服务器状态。加路由或选第一个匹配注册顺序与 HMR 时机不是产品语义冲突因此让注册失败。单实例并发查询若取消失败终止共享进程会杀死无关工作按实例串行化限制了爆炸半径实例间仍并行。内置预置或 PATH 发现目录会让通用宿主拥有语言策略发现无法推断参数、语言 id 或初始化。测试矩阵与结论测试覆盖见各包tests/目录印证了上述语义包测试钉死三包依赖方向、运行时注入与仅通过ctx.lsp通信。工具测试钉死四个操作、坐标校验、配置上限与省略标记、提示词与 UI 呈现tool-lsp.spec.ts、render.spec.ts。注册表测试钉死原子保留/释放、顺序无关选择与结构化错误lsp.spec.ts。Fake-stdio 测试钉死初始化能力、四个协议映射、Location/LocationLink与 hover 归一化、references.includeDeclaration映射translate.spec.ts、connection.spec.ts、framing.spec.ts。生命周期测试钉死启动单飞、完整生命周期串行化、跨工作区并行、可中止队列、崩溃替换不重放等lifecycle.spec.ts、instance.spec.ts。关键无 key 的 TypeScript 真实服务器 e2e 演练全部四个操作typescript-server.e2e.ts。需要接受的事实与限制语言服务器在方法支持、能力解释与索引就绪度上各不相同LSP 没有通用的索引完成信号不兼容瞬态打开同步的服务器即使关闭文档查询可用也不受支持受支持的服务器仍可能返回空或部分结果因此工具不承诺跨服务器完整性。瞬态打开会重复解析与通知并行 Agent 下按实例串行化增加延迟长生命周期工作区进程在销毁前占用内存。此外UTF-16 游标列对协议精确但模型在非 BMP 字符附近数起来困难无效或偏离符号的位置可能产生空结果因此错误文本与提示词示例必须解释坐标约定而不是鼓励滥用 LSP。延伸阅读设计文档.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md接缝类型契约packages/lsp/lsp/src/types.ts接缝实现packages/lsp/lsp/src/index.ts本地宿主packages/lsp/lsp-stdio/src/host.ts、instance.ts、translate.ts、connection.ts模型工具packages/lsp/tool-lsp/src/index.ts、render.ts、session-cwd.ts配置目录docs/config-catalog.md架构总览docs/architecture.md【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考