让 Agent 找一个函数定义，工具返回了十几个同名片段：源码、测试、注释和文档都有。模型挑了一个最像的，就把它称作“实现位置”。如果搜索范围与结果语义没有说清楚，定位工具很容易让错误看起来更精确。

符号搜索首先要说明自己做哪种搜索。按名称匹配与语法级定义查询是不同能力。再把仓库、路径与预算限制在已授权范围内，模型才知道哪些结果能直接引用，哪些只是继续读取的候选。

搜索模式写进接口

第一版可以只做字面名称搜索，返回命中位置与上下文。它实现简单，但必须承认可能命中注释、字符串或调用处。不要把工具命名为“查找定义”，实际却只按文本匹配。

如果接入语言服务或语法索引，可以增加定义、引用等模式。每种模式都要说明支持语言、索引版本和失败行为。解析失败时降级为文本搜索，应在响应里标明，不能继续把结果称作已确认定义。

{
  "repository_id": "repo-example",
  "scope": "src",
  "symbol": "load_items",
  "mode": "literal_name",
  "limit": 20
}

这份结构仅作设计示意。模式是枚举，数量由服务端限制，符号名称按文本处理。若支持正则，应单独提供受限模式和资源预算，避免一个普通名称字段被解释成任意搜索表达式。

授权范围先于搜索范围

仓库由服务端资源标识映射，不能让模型传任意机器目录。用户、任务与资源策略决定可访问集合，本次 scope 只能缩小它，不能扩大它。

目录不存在、目录不可访问和目录内无命中要分别返回。模型看到权限不足时，应报告未能查询，而不是改成上级目录或换一种路径形式继续试探。

路径规范化、符号链接和排除目录都在工具端处理。只把“不要越界”写进描述不够，实际文件访问前仍需检查。凭据、依赖缓存和构建产物也不应因为处于项目目录就自动进入符号候选。

固定快照避免位置漂移

静态索引应返回它对应的提交或工作区版本。模型想解释当前实现时，先核对目标版本。若索引落后，重新读取目标快照，或说明当前结果只属于旧版本。

每条结果包含路径、位置、匹配类型和短上下文。位置由工具计算，模型不自行补造。读取完整函数时，继续使用同一快照，避免搜索命中新版本、读取却来自另一个时刻。

工作区能力需要额外标记。文件可能在扫描期间变化，工具应说明一致性边界。若产品先只支持提交快照，反而更容易给出可靠引用，无须一开始承担所有编辑器状态。

同名候选不要自动合并

两个模块各自定义 load，可能完全无关。方法重载、嵌套函数和别名也会让名称相同但身份不同。结果应保留模块或限定名，不要只按短名称去重。

模型选择候选时，可以结合用户提到的入口、路径与调用关系。入口不明就列出少量差异，或继续读取必要位置。不能仅凭排序第一就认定它是用户所问实现。

反向引用也要说明类型。文本命中调用名称，不一定构成可执行调用；动态分派或运行时注册又可能没有直接文本命中。搜索端提供事实，答案端保留检查范围，避免把静态结果说成完整调用图。

资源预算不仅是返回条数

返回二十条不代表扫描成本有限。还需要限制访问文件数、单文件体积、总耗时与返回字节数。到达预算时，响应标记截断或不完整，并给出可以继续的范围信息。

按稳定顺序返回有助于复核，但不要把未知总量写成精确 total。如果只扫描了前一部分文件，最多报告已检查范围与当前命中数。模型不能据此说“全仓库只有这些引用”。

结果上下文也应受限。定位任务通常不需要整个文件，敏感片段可以按资源策略排除。后续确实需要完整内容时，再通过受限读取工具请求，而不是在第一次搜索中一次性返回所有源码。

失败诊断影响后续动作

语法索引不可用、目标不存在、权限不足与预算耗尽对应不同处理。模型可以在解析失败时选择明确的文本降级，也可以缩小范围；但权限失败不能用另一种搜索实现绕过。

检查工具时，可以准备同名定义、注释命中、超多结果和越界路径。再观察 Agent 是否把文本候选当成定义，是否在结果截断后声称搜全，以及是否能引用正确快照。

我倾向于先提供一个诚实的小工具：名称搜索就是名称搜索，定义确认有额外依据。能力边界清楚，模型反而更容易知道下一次该读哪个片段，而不是用一串精确行号掩盖尚未确认的判断。