# SubAgent: Search

## 用途

Search 子代理是一个轻量级、只读的探索代理。当你需要理解代码库——找到某物的位置、了解组件如何协作或回答结构性问题——且不改动任何文件时派发它。它针对跨多个文件的多次小量读取做了优化，返回简洁摘要而非原始搜索输出。

Search 不是通用助手。它不能编辑代码、运行构建、提交变更，也不能打开除只读抓取以外的网络连接。它的价值在于可以在并行下消耗大量探索预算，却不占用主代理的上下文，然后交回一个紧凑的答案。

## 何时使用

- 你需要回答需要三次或更多独立搜索或读取的问题。例如：「从登录路由到会话存储，认证是如何串联起来的？」
- 目标未知——你还不知道要看哪个文件、模块或符号。
- 你在做出改动前需要对仓库陌生区域的结构性概览。
- 你要交叉比对多个候选（例如几个名字相似的 helper 中，哪一个实际在生产中被调用）。
- 你需要文献式总结：「列出每一处 import X 的位置，并按调用点分类。」

不要在以下情况使用 Search：

- 你已经知道确切的文件和行号。直接调用 `Read`。
- 一次 `Grep` 或 `Glob` 就能回答问题。直接执行；派发子代理会增加开销。
- 任务需要编辑、运行命令或任何副作用。Search 按设计是只读的。
- 你需要某次工具调用的精确逐字输出。子代理做摘要；它们不转发原始结果。

## 彻底程度

根据问题的利害选择级别。

- `quick` —— 数次有针对性的搜索，尽力而为的答案。适用于需要快速指针（如「env 变量解析逻辑在哪？」）且能接受不完整答案后自行迭代的场景。
- `medium` —— 默认值。若干轮搜索、交叉核对候选并完整阅读最相关的文件。适用于典型「帮我理解这个区域」的问题。
- `very thorough` —— 穷尽式探索。子代理会追查每条可信线索、阅读周围上下文、在总结前再次核对结论。当正确性重要（例如安全审查、迁移规划），或不完整的答案会导致返工时使用。

更高的彻底度在子代理内消耗更多时间和 token，但那些 token 都留在子代理内——只有最终摘要回到主代理。

## 可用工具

Search 可访问主代理所用的所有只读工具，仅限于此：

- `Read` —— 读取具体文件，包括部分范围。
- `Grep` —— 在整树上做内容搜索。
- `Glob` —— 按名称模式定位文件。
- 只读模式的 `Bash` —— 用于检查状态而不变更状态的命令（例如 `git log`、`git show`、`ls`、`wc`）。
- `WebFetch` 和 `WebSearch` —— 当需要时阅读外部文档。

编辑类工具（`Write`、`Edit`、`NotebookEdit`）、修改状态的 shell 命令，以及任务图工具（`TaskCreate`、`TaskUpdate` 等）被刻意禁用。

## 注意事项

- 给 Search 子代理一个具体的问题，而不是一个主题。「List every caller of `renderMessage` and note which ones pass a custom theme」会返回有用的答案；「tell me about rendering」不会。
- 子代理返回摘要。若需要精确文件路径，请在提示中显式要求。
- 多个独立问题最好作为多个并行的 Search 子代理派发，而非一个长 prompt，这样每个都能聚焦。
- 因为 Search 不能编辑，请在主代理中配以后续的编辑步骤，等你知道该改什么后再动手。
- 把 Search 输出当作证据，而非真理。对任何承载决策的内容，动作前请自行打开引用的文件。
