ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness LSP 导航怎么用:定义、引用、诊断与符号四种查询配方教程

配置与使用发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH pluginLSP代码导航诊断
LSP 工具把语言服务器能力交给模型,但四种查询要的输入不同。本文给跳转定义、查找引用、查看诊断、列符号四个配方,以及没有 provider 时 LSP_UNAVAILABLE 的处理方式。

LSP 工具不是「一个万能代码搜索」,而是四种输入不同的查询:定义、引用、诊断、符号。 官方把提供方选择与语言服务器子进程放在 ctx.lsp 之后,因此工具 schema 在更换提供方时保持稳定(来源)。会用四种配方,模型就能从「猜代码」变成「查代码」。

DeepSeek Harness LSP 能力边界

LSP 给的是语言服务器已经理解的东西,不是全文搜索。 它能回答「这个符号在哪定义」「谁引用了它」「这个文件有什么诊断」「这个文件有哪些符号」,但不能替代 grep 找任意字符串。(来源)

这条边界带来两个结论:

  1. 输入要精确到位置 — 定义与引用需要文件与行列,位置偏了就会查错;
  2. 结果依赖索引 — 语言服务器没打开或没索引的文件,可能查不到符号。

把 LSP 当全文搜索用,常见结果是「明明有这个词,却查不到」。这不是工具坏了,而是查询类型不对;找任意字符串应该用 grep。

LSP 也不是编译器。诊断能提示类型错误、未定义符号,但不保证覆盖所有构建问题;构建失败仍要看编译输出。

DeepSeek Harness 四种查询与输入

四种查询的输入与产出不同,先看表再写任务。 对照如下(来源):

查询输入产出适合问什么
定义文件 + 位置声明位置这个函数在哪定义
引用文件 + 位置使用位置列表谁调用了它
诊断文件或工作区诊断列表这个文件有什么问题
符号文件或工作区符号列表这个文件/项目有哪些符号

定义与引用都依赖「位置」,不是「名字」。只给名字,工具不知道你指的是哪个同名符号;同名函数在不同文件里,结果可能完全不同。

诊断与符号可以按文件,也可以按工作区,取决于提供方支持的范围。按工作区查询可能更慢,但能发现跨文件问题。

四者的共同点是「结构化结果」:返回位置、范围、严重级别等字段,而不是一段自然语言。模型可以据此继续读文件或改代码。

DeepSeek Harness 输入从哪来

位置输入通常来自当前文件、搜索结果或上一次查询的返回。 三种来源(来源):

  1. 当前打开的文件 — 用户或模型已经知道文件与光标位置;
  2. grep/搜索 — 先找到符号出现的位置,再用 LSP 查定义或引用;
  3. LSP 返回 — 定义结果给出新位置,可以继续查引用或诊断。

第三种最容易形成链式查询:先查定义,拿到声明位置,再查引用,最后看诊断。链式查询比一次问「这个项目有什么问题」更精确。

位置通常是行列号或字符偏移,具体格式以工具 schema 为准。输入前先确认文件路径是工作区内的路径,避免语言服务器找不到文件。

如果位置来自另一个工具的输出,注意行列基准:有的从 0 开始,有的从 1 开始。基准错了,查询会落在相邻符号上。

DeepSeek Harness 没有 provider 时

没有注册 LSP 提供方时,查询返回 LSP_UNAVAILABLE,不是空结果。 官方明确:运行时要求已注册提供方,例如 stdio 提供方;没有提供方时,查询返回结构化 LSP_UNAVAILABLE 错误,而不是改变 schema(来源)。

这条设计的目的是让失败可解释:空结果可能表示「没找到」,LSP_UNAVAILABLE 表示「能力不可用」。两者处理方式不同。

遇到 LSP_UNAVAILABLE,先查三件事:

  1. 提供方是否加载 — profile 或组合包是否包含 LSP 提供方;
  2. 语言服务器是否存在 — 提供方能否启动对应语言的服务器;
  3. 项目是否被识别 — 语言服务器是否支持该文件类型与项目结构。

不要在没有 provider 时反复改查询参数。参数再对,能力也不可用。

DeepSeek Harness 四个配方

四个配方可以直接照用,覆盖大多数代码导航任务。 每个配方给「怎么问」与「预期结果」(来源):

  1. 找定义 — 「在 src/index.ts 第 12 行第 5 列,跳转到该符号的定义。」预期返回声明文件与位置;空结果先确认位置是否落在符号上。
  2. 找引用 — 「在同一个位置,列出所有引用。」预期返回使用位置列表;结果可能跨文件,注意过滤测试与生成代码。
  3. 看诊断 — 「查询 src/index.ts 的诊断。」预期返回错误、警告与位置;没有诊断不等于没有构建问题。
  4. 列符号 — 「列出 src/index.ts 的符号。」预期返回函数、类、变量及位置;文件太大时结果可能被截断。

四个配方的共同点是「先位置、后范围」。先定位到一个符号,再扩大范围查引用或诊断;一上来就查整个工作区,结果往往太多。

如果配方返回空,先换一个已知符号验证能力是否可用,再查输入。不要用空结果直接判断「代码没问题」。

DeepSeek Harness 四步验证 LSP 是否可用

验证 LSP,按四步走,不要只看一次查询。 四步(来源):

  1. 能力可用 — 查一个已知符号的定义,确认返回非空;
  2. 位置准确 — 换一个同名符号,确认定义没有串到另一个文件;
  3. 引用完整 — 查一个被多处引用的符号,确认结果覆盖主要使用点;
  4. 诊断可信 — 故意引入一个未定义符号,确认诊断能报出来。

四步都过,LSP 的输入、位置与提供方基本正确。只过第一步,常见问题是位置基准错了;只过前两步,常见问题是索引不完整。

旧文 dev-lsp-seam 讲 LSP 提供方契约,DSH plugin 接 LSP 讲 LspQueryRequest;本篇补的是四种查询配方。先确认能力可用,再谈查询结果。

LSP 查询的上限是语言服务器理解的范围,不是整个仓库的所有文本。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的 LSP 工具需要额外安装语言服务器吗?

DeepSeek Harness 需要这样。DeepSeek Harness 的 lsp 工具要求已注册提供方,例如 stdio 提供方;没有提供方时查询会返回 LSP_UNAVAILABLE,而不是自动安装语言服务器。

DeepSeek Harness 里跳转定义和查找引用分别要什么输入?

DeepSeek Harness 里,两者都需要文件与位置;定义返回符号声明处,引用返回所有使用处。DeepSeek Harness 的 LSP 查询按位置定位,输入不准就会得到空结果或错误位置。

DeepSeek Harness 的 LSP 诊断是实时推送还是按需查询?

DeepSeek Harness 里,取决于提供方与操作。DeepSeek Harness 的 lsp 工具可以按需查询诊断;语言服务器也可能在打开文件后推送诊断,两者不要混为一谈。

DeepSeek Harness 的 LSP 查询返回空结果,是不是工具坏了?

DeepSeek Harness 里不一定,具体取决于配置。DeepSeek Harness 的 LSP 空结果可能表示位置没有符号、文件未被语言服务器索引、或提供方不支持该操作;先换一个已知符号验证。

相关术语

LSP
LSP 是语言服务器协议,DeepSeek Harness 通过 lsp 工具把定义、引用、诊断与符号等能力交给模型。— DeepSeek Harness 官方文档 - LSP 导航
provider
provider 是 DeepSeek Harness 中为 LSP 提供实际语言服务器连接的后端,例如 stdio 提供方;没有 provider 时查询不可用。— DeepSeek Harness 官方文档 - LSP 导航
LSP_UNAVAILABLE
LSP_UNAVAILABLE 是 DeepSeek Harness 在没有注册 LSP 提供方时返回的结构化错误,表示能力不可用而不是查询失败。— DeepSeek Harness 官方文档 - 工具 Schema 目录
符号
符号是代码中的命名实体,例如函数、类、变量;LSP 可以按文件或工作区列出符号及其位置。— DeepSeek Harness 官方文档 - LSP 导航

来源