# SubAgent: Search

## 用途

Search 子代理是輕量、唯讀的探索代理。當你需要理解程式碼庫——找出某個東西在哪裡、了解元件如何組合、回答結構性問題——且不希望變動任何檔案時派遣它。它針對跨多個檔案的大量小規模讀取做了最佳化，回傳精簡的摘要而非原始搜尋輸出。

Search 不是通用助理。它無法編輯程式碼、執行建構、提交變更，或開啟除唯讀擷取之外的網路連線。它的價值在於可在不消耗主代理上下文的情況下，平行消化大量探索預算，然後交回精簡答案。

## 使用時機

- 你需要回答的問題需要三個以上獨立的搜尋或讀取。範例：「認證從登入路由一路到 session 儲存是如何串接的？」
- 目標未知——你尚未知道要看哪個檔案、模組或符號。
- 在動手變更之前，需要對 repo 某個不熟區域的結構性概觀。
- 你想交叉比對多個候選（例如多個名稱相近的 helper 中，哪一個在正式環境中實際被呼叫）。
- 你需要一份文獻式摘要：「列出每個 import X 的地方並依呼叫點分類。」

以下情況不要使用 Search：

- 你已知道確切檔案與行號。直接呼叫 `Read`。
- 單一的 `Grep` 或 `Glob` 即可回答問題。直接執行；派遣子代理只會增加成本。
- 任務需要編輯、執行指令或任何副作用。Search 在設計上就是唯讀。
- 你需要工具呼叫的逐字原始輸出。子代理會摘要，不會代轉原始結果。

## 徹底程度等級

挑選符合該問題風險的等級。

- `quick`——少數針對性搜尋，盡力而為的答案。當你需要一個快速指向（例如「env var 解析邏輯在哪裡？」）、且可接受答案不完整時再迭代。
- `medium`——預設。數輪搜尋、交叉檢查候選、完整讀取最相關檔案。用於一般「幫我理解這個區域」的問題。
- `very thorough`——徹底探索。子代理會追蹤每條合理的線索、讀取周邊上下文、在摘要前再次驗證。適用於正確性重要的情境（例如安全審查、遷移規劃），或答案不完整會造成返工的場景。

較高的徹底程度會在子代理內部花更多時間與 tokens，但那些 tokens 留在子代理內——只有最終摘要會回到主代理。

## 可用工具

Search 可存取主代理所用的所有唯讀工具，僅此而已：

- `Read`——讀取特定檔案，包括部分範圍。
- `Grep`——在整個樹狀結構中搜尋內容。
- `Glob`——依名稱模式定位檔案。
- 唯讀模式的 `Bash`——用於檢視狀態而不變更的指令（例如 `git log`、`git show`、`ls`、`wc`）。
- `WebFetch` 與 `WebSearch`——在需要外部說明文件的上下文時使用。

編輯工具（`Write`、`Edit`、`NotebookEdit`）、修改狀態的 shell 指令，以及任務圖工具（`TaskCreate`、`TaskUpdate` 等）刻意不提供。

## 注意事項

- 給 Search 子代理一個具體的問題，而非主題。「列出 `renderMessage` 的每個呼叫者，並註記哪些會傳入自訂主題」會得到有用的答案；「跟我說說 rendering」不會。
- 子代理回傳摘要。若你需要確切的檔案路徑，請在 prompt 中明確要求。
- 多個獨立問題最好以平行 Search 子代理派遣，而非串成一個長 prompt，這樣每個都能聚焦。
- 因為 Search 無法編輯，請在主代理中搭配後續編輯步驟，當你知道要改什麼時再動手。
- 把 Search 輸出當作證據，而非絕對真理。對任何重要決策，行動前請自行開啟引用的檔案。
