「我搜到一个同名函数,改完才发现改错了地方。」 「findReferences 返回空,是不是这个函数根本没被调用?」这两种情况背后的问题相同:把「文本命中」和「符号关系」当成了一回事。
实际排查中最常见的六类误判是:
- 以为查到同名就找到了目标符号;
- 看到空位置列表就断定没有调用方;
- 以为目录里有 schema 就等于提供方已经运行;
- 把截断的展示当成完整清单;
- 以为 LSP 结果授予了修改权限;
- 改了光标位置,期待缺失的提供方被装上。
先记住一句话:文本搜索找字符,语言服务器解析符号;前者覆盖全但不懂语义,后者懂语义但有前提。 站内基础版可参考用 LSP 跳转定义与引用。
一、什么时候该用 LSP
LSP 子系统参考介绍服务、提供方注册表和工具消费方;工具说明给出的建议很明确:普通导航优先使用 search 和 read,只有在文本匹配不明确、或者需要精确关系时才用 LSP。
两个典型场景:
- 同名符号对应多个声明——纯文本搜索会把它们全列出来;
- 修改前需要更准确地了解引用和实现——这时候要的是关系,不是字符。
三个方法是配合用的,不是选一个
文档建议的顺序是:先搜索可能的符号 → 读取周围代码确定是哪一次出现 → 再在该位置询问语义关系。
这条顺序有个重要限定:服务器返回的是针对当前工作区的分析结果,因此不能据此断定已经找到所有使用处。
四个操作,集合是封闭的
| 操作 | 要回答的问题 | 返回 |
|---|---|---|
goToDefinition |
这个符号在哪里定义? | 位置列表 |
findReferences |
哪里引用了它? | 位置列表,包含声明 |
goToImplementation |
哪里实现了它? | 位置列表 |
hover |
光标处有什么信息? | 文本或无悬停信息 |
文档列出的操作范围是固定的:符号搜索和调用层级不属于这个接口。即使某个语言服务器支持更多协议方法,也不代表该工具自动暴露这些方法。
二、一次查询需要什么
1. 四个字段
供模型调用的 schema 要求 operation、file_path、line、character 四个字段。路径可以相对于会话工作区,也可以是绝对路径。
坐标规则是这类问题的高发区:
- 两个坐标都是从 1 开始的正数;
- 字符位置按 UTF-16 代码单元计数;
- 底层服务使用从 0 开始的 UTF-16 坐标,工具负责输入和输出转换。
由此产生一个很实际的坑:遇到非基本多文种平面字符后,视觉上数出来的列数可能与 UTF-16 数值不同。 也就是说,你肉眼数的第 8 列,不一定就是 character: 8。
还要注意:光标没有落在符号上时,即使符号存在,也可能返回空结果。
2. 调用结构示意
下面只是工具调用的结构示意,不是 Shell 命令;路径和位置必须换成实际代码中的符号:
{
"operation":"findReferences","file_path":"src/example.ts","line":12,"character":8}
3. 几个无需手动设置的项
findReferences固定包含声明,没有面向模型的排除声明开关;- 会话当前工作目录提供工作区根;
- 模型输入不需要选择提供方、语言 ID、可执行程序、超时或结果上限。
最后一点值得展开说说:工具说明指出,切换会话目录影响之后的查询,但不会改变已运行服务器的根目录。 因此,切换工作区后结果没变并非 bug:已运行的服务器仍使用原来的根目录。
三、围绕一次修改怎么导航
1. 五步
- 确认会话位于预期工作区,并确认
lsp工具和处理目标扩展名的提供方可用。LSP 是可选能力,目录里有 schema 不能证明提供方已经运行。 - 先搜索并读取相关文件,定位准确符号,记录从 1 开始的行号和 UTF-16 字符位置,避免把光标放在不相关的行首。
- 在可能有歧义的使用位置查询
goToDefinition,或用hover查看光标处的信息;然后读取返回位置所在文件及附近代码,了解声明的上下文。 - 在合适的符号处运行
findReferences,同时查看声明和返回位置。对于接口或派发点,如果服务器支持,可再用goToImplementation查看实现。 - 检查是否有省略或截断标记,并结合文本搜索和相关测试评估影响。修改后结合实际代码重新检查;LSP 结果本身不能代替行为测试。
2. 空结果要分两种情况
如果工具成功返回空位置,先核对路径、工作区和光标。 因为成功的空结果与结构化错误是两种情况。
而且语言服务器还可能由于索引尚未完成、或语言支持不同而返回空结果或部分结果。
结论:不要把空列表理解为一定没有调用方。
3. 一个同名符号的现场
同一个名称同时出现在类型声明、测试替身和普通变量中时,文本搜索会列出所有文本命中。
正确做法是:先读取并选择实际调用位置,再查看定义,这样可以减少把无关同名项当成目标的机会。
随后查询引用时,仍应检查结果上限,并阅读返回代码:单条位置记录无法说明该调用的业务含义,也不能替代对动态调用路径的判断。
四、结果和错误怎么读
1. 结果的呈现形式
- 导航结果按文件分组,以从 1 开始的
path:line:character呈现; - 悬停返回规范化文本,或无信息提示;
- 服务层位置包含 URI 和从 0 开始的范围;
- 结果还包含
resolvedWorkspaceUri,消费方可据此按照提供方解析后的根目录解释位置,请求根涉及符号链接时也适用; - 非文件 URI 可能原样保留。
2. 三个默认上限
工具说明记录的该包默认值是 maxLocations: 100、maxResultChars: 16000 和 timeoutMs: 60000。
这几项的作用需要区分:
- 前两项限制展示内容,省略和截断标记也计入字符上限;
- 它们不改变规范化结果;
- 被截断的展示不能当成完整清单;
- 超时覆盖排队的打开、查询和关闭过程,由部署控制,而不是模型参数。
还有一条纪律:依赖默认值之前要核对已安装版本的配置。
3. 结构化错误码
LSP_UNAVAILABLE:没有提供方匹配扩展名;LSP_WORKSPACE_REQUIRED:非 Agent 调用缺少会话工作区;LSP_MALFORMED_RESPONSE:提供方响应无效;- 不支持的操作和提供方冲突也有结构化错误码。
排查时要保留错误码和上下文。另一个实用提醒是:不断改变光标位置,也不会安装缺失的提供方。
五、限制与安全边界
- LSP 导航是只读操作,但源文件、路径、悬停文本和查询结果仍可能暴露私有代码。 分享日志前检查并删除不必要的信息。
- 已配置的提供方可能启动语言服务器进程:应审查其来源及部署配置。
- 工具已注册、或查询成功,都不能证明服务器或输出值得信任。
- LSP 位置不能代替编辑前读取目标文件:文件系统参考另行定义读取和编辑行为,文件观察策略使用版本信息,并可能拒绝过时修改。
- 不要认为一次导航结果授予了修改文件的权限。
- 参考资料没有保证跨服务器结果完整,也没有保证支持所有语言。
- 动态派发、生成代码、索引状态和提供方行为都可能使影响分析更复杂。
- 把 LSP 与代码检查及测试一起使用,并在修改后验证实际行为。
六、术语速查
- LSP:此处用于语义代码导航的语言服务器协议。
- 提供方:针对特定文件扩展名注册的查询实现。
- 工作区根:用来解析路径和索引查询的会话目录。
- UTF-16 坐标:按代码单元计算的行列位置;工具与服务的起始基数不同。
- 规范化结果:经过有界展示之前的结构化查询结果。
相关阅读
本文依据 DeepSeek Harness 官方 LSP 子系统参考与工具说明整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/use-lsp-to-navigate-definitions-and-references
插件与文档收录于:https://dsh-plugin.com/zh/blog