code-intelligence

代码智能

根据任务选择搜索工具，而不是凭习惯。通用且与语言无关； 领域技能会通过服务器能力矩阵和生态系统前置条件扩展它 ——例如，同一市场中的 terraform-skill 插件负责维护 terraform-ls 能力矩阵和 Terraform 设置。这是由模型触发的指导， 而非强制规则。

工具优先级

目标	使用	权衡
符号关系：定义、引用、调用位置、重命名安全性	在某个位置调用语言服务器（LSP）	需要运行中的服务器和已索引的工作区
精确文本、已知名称、穷举列举、配置/值文件	rg 然后 Read	不具备语义范围；也会匹配注释中的字符串
概念性 / 模糊搜索 / “可能在哪里” / 跨仓库发现	语义/神经搜索工具（若宿主提供）	结果不精确；绝不能用于计数或完整性声明

详情：优先级表、 LSP 何时会出错。

调用 LSP

• 务必在某个位置调用（file:line:character）。先搜索已知匹配项的文本， 以此锚定位置。
• 不要只传入符号名称并期待解析。仅按名称调用却返回空结果， 属于使用方式错误，而非服务器故障。
• 务必读取返回位置处的源文本；LSP 返回的是位置和符号， 而不是对应的代码行。
• 冷启动后务必重试一次：启动后的首次调用可能会在服务器索引期间返回空结果。
• 如果服务器声明支持自己的操作，务必优先使用：重命名时使用 rename / prepareRename，查找调用方时使用调用层级——这些操作包含手动处理容易遗漏的 语言特定语义。
• 不要将不受支持的操作报告为发现。服务器不支持某项操作时，应改用其他方式： 用 findReferences（然后筛选调用位置）代替调用层级；列举引用后手动编辑， 代替重命名提供程序。

详情：位置锚定、 不受支持的操作。

降级门槛

有两种不同情况：

• 完全没有 LSP（宿主未提供语言服务器工具，或服务器启动失败）：这才属于不可用。 请在第一行说明（见下文），并使用文本搜索。门槛不适用——没有可供检查的对象。
• **LSP 可调用，但位置锚定的调用返回空结果：**此时不要得出“不可用”的结论。 必须同时满足以下三项：
  1. 对范围内的文件调用 documentSymbol 并返回符号 -> 服务器有响应 （仅表明有响应，并不能证明引用覆盖完整）。
  2. 失败的调用是位置锚定的（而非仅按符号名称调用）。
  3. 冷启动重试后，该锚定调用仍返回空结果。

只有满足以上三项，才有充分理由说明并采用文本回退方案。

详情：降级门槛。

说明替代方案

任何工具替代或省略都必须在回复的第一行说明，而非放在后续总结中 （事后说明违反规则）：

Intended: <tool>. Actual: <tool>. Reason: <why>. Impact: <completeness/confidence>.

详情：说明格式。

不要臆称缺少工具

在声称某个工具（如 rg）被封装、设置了别名或不存在之前，先验证： type -a <tool>、对解析出的路径运行 ls -l，以及 <tool> --version 显示预期的版本标识。 未经验证就声称“工具缺失”并随后采用回退方案， 属于验证失败，而非获准的替代方案。

如果工具确实不存在或设置了别名：语义任务优先使用 LSP；精确文本搜索使用宿主批准的文本搜索工具； 只有在明确说明的情况下，才能将 git grep / grep 作为最后手段使用，绝不能将其作为默认替代方案。

详情：反虚假封装验证。