DeepSeek Harness LSP 导航怎么用:定义、引用、诊断与符号四种查询配方教程
LSP 工具不是「一个万能代码搜索」,而是四种输入不同的查询:定义、引用、诊断、符号。 官方把提供方选择与语言服务器子进程放在 ctx.lsp 之后,因此工具 schema 在更换提供方时保持稳定(来源)。会用四种配方,模型就能从「猜代码」变成「查代码」。
DeepSeek Harness LSP 能力边界
LSP 给的是语言服务器已经理解的东西,不是全文搜索。 它能回答「这个符号在哪定义」「谁引用了它」「这个文件有什么诊断」「这个文件有哪些符号」,但不能替代 grep 找任意字符串。(来源)
这条边界带来两个结论:
- 输入要精确到位置 — 定义与引用需要文件与行列,位置偏了就会查错;
- 结果依赖索引 — 语言服务器没打开或没索引的文件,可能查不到符号。
把 LSP 当全文搜索用,常见结果是「明明有这个词,却查不到」。这不是工具坏了,而是查询类型不对;找任意字符串应该用 grep。
LSP 也不是编译器。诊断能提示类型错误、未定义符号,但不保证覆盖所有构建问题;构建失败仍要看编译输出。
DeepSeek Harness 四种查询与输入
四种查询的输入与产出不同,先看表再写任务。 对照如下(来源):
| 查询 | 输入 | 产出 | 适合问什么 |
|---|---|---|---|
| 定义 | 文件 + 位置 | 声明位置 | 这个函数在哪定义 |
| 引用 | 文件 + 位置 | 使用位置列表 | 谁调用了它 |
| 诊断 | 文件或工作区 | 诊断列表 | 这个文件有什么问题 |
| 符号 | 文件或工作区 | 符号列表 | 这个文件/项目有哪些符号 |
定义与引用都依赖「位置」,不是「名字」。只给名字,工具不知道你指的是哪个同名符号;同名函数在不同文件里,结果可能完全不同。
诊断与符号可以按文件,也可以按工作区,取决于提供方支持的范围。按工作区查询可能更慢,但能发现跨文件问题。
四者的共同点是「结构化结果」:返回位置、范围、严重级别等字段,而不是一段自然语言。模型可以据此继续读文件或改代码。
DeepSeek Harness 输入从哪来
位置输入通常来自当前文件、搜索结果或上一次查询的返回。 三种来源(来源):
- 当前打开的文件 — 用户或模型已经知道文件与光标位置;
- grep/搜索 — 先找到符号出现的位置,再用 LSP 查定义或引用;
- LSP 返回 — 定义结果给出新位置,可以继续查引用或诊断。
第三种最容易形成链式查询:先查定义,拿到声明位置,再查引用,最后看诊断。链式查询比一次问「这个项目有什么问题」更精确。
位置通常是行列号或字符偏移,具体格式以工具 schema 为准。输入前先确认文件路径是工作区内的路径,避免语言服务器找不到文件。
如果位置来自另一个工具的输出,注意行列基准:有的从 0 开始,有的从 1 开始。基准错了,查询会落在相邻符号上。
DeepSeek Harness 没有 provider 时
没有注册 LSP 提供方时,查询返回 LSP_UNAVAILABLE,不是空结果。 官方明确:运行时要求已注册提供方,例如 stdio 提供方;没有提供方时,查询返回结构化 LSP_UNAVAILABLE 错误,而不是改变 schema(来源)。
这条设计的目的是让失败可解释:空结果可能表示「没找到」,LSP_UNAVAILABLE 表示「能力不可用」。两者处理方式不同。
遇到 LSP_UNAVAILABLE,先查三件事:
- 提供方是否加载 — profile 或组合包是否包含 LSP 提供方;
- 语言服务器是否存在 — 提供方能否启动对应语言的服务器;
- 项目是否被识别 — 语言服务器是否支持该文件类型与项目结构。
不要在没有 provider 时反复改查询参数。参数再对,能力也不可用。
DeepSeek Harness 四个配方
四个配方可以直接照用,覆盖大多数代码导航任务。 每个配方给「怎么问」与「预期结果」(来源):
- 找定义 — 「在
src/index.ts第 12 行第 5 列,跳转到该符号的定义。」预期返回声明文件与位置;空结果先确认位置是否落在符号上。 - 找引用 — 「在同一个位置,列出所有引用。」预期返回使用位置列表;结果可能跨文件,注意过滤测试与生成代码。
- 看诊断 — 「查询
src/index.ts的诊断。」预期返回错误、警告与位置;没有诊断不等于没有构建问题。 - 列符号 — 「列出
src/index.ts的符号。」预期返回函数、类、变量及位置;文件太大时结果可能被截断。
四个配方的共同点是「先位置、后范围」。先定位到一个符号,再扩大范围查引用或诊断;一上来就查整个工作区,结果往往太多。
如果配方返回空,先换一个已知符号验证能力是否可用,再查输入。不要用空结果直接判断「代码没问题」。
DeepSeek Harness 四步验证 LSP 是否可用
验证 LSP,按四步走,不要只看一次查询。 四步(来源):
- 能力可用 — 查一个已知符号的定义,确认返回非空;
- 位置准确 — 换一个同名符号,确认定义没有串到另一个文件;
- 引用完整 — 查一个被多处引用的符号,确认结果覆盖主要使用点;
- 诊断可信 — 故意引入一个未定义符号,确认诊断能报出来。
四步都过,LSP 的输入、位置与提供方基本正确。只过第一步,常见问题是位置基准错了;只过前两步,常见问题是索引不完整。
旧文 dev-lsp-seam 讲 LSP 提供方契约,DSH plugin 接 LSP 讲 LspQueryRequest;本篇补的是四种查询配方。先确认能力可用,再谈查询结果。
LSP 查询的上限是语言服务器理解的范围,不是整个仓库的所有文本。
常见问题
DeepSeek Harness 需要这样。DeepSeek Harness 的 lsp 工具要求已注册提供方,例如 stdio 提供方;没有提供方时查询会返回 LSP_UNAVAILABLE,而不是自动安装语言服务器。
DeepSeek Harness 里,两者都需要文件与位置;定义返回符号声明处,引用返回所有使用处。DeepSeek Harness 的 LSP 查询按位置定位,输入不准就会得到空结果或错误位置。
DeepSeek Harness 里,取决于提供方与操作。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 导航
来源
- DeepSeek Harness 官方文档 - LSP 导航· deepseek-harness
- DeepSeek Harness 官方文档 - 工具 Schema 目录· deepseek-harness