調整代理的工具上下文

本指南涵蓋兩層式工具介面的實務工作：看清一次執行送出了什麼、如何更改它，以及診斷一個拿錯了工具的代理。若要了解它為何這樣設計，請參閱工具上下文與提示快取。

檢視一次執行實際送出的內容

開啟一則對話，然後點按對話頁首的上下文用量指示器。它會重建下一次派發將會送出的確切介面，而不會實際執行任何東西。查看更多（或 /context 指令）會開啟完整的上下文瀏覽器，讓你逐一檢視每個工具。

這裡有兩個區段值得留意：

• 工具定義與 MCP 與動態工具——即常駐集合，並顯示每個工具實際的 token 成本。
• 隨需載入的工具——即隨需載入索引。每一筆只按名稱計費，因為請求所攜帶的僅是名稱；展開某一項仍會顯示完整的描述與 schema，讓你看到這次執行若把它拉進來原本會付出多少成本。

如果隨需載入區段是空的，表示這部伺服器已關閉隨需載入。請查閱 cc_server CLI 上的 --tool-deferral。

變更哪些工具會預先載入

常駐集合是政策，而非設定——它存在於 ModeToolPolicy（packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart）之中，並套用於每一次執行：

• residentBuiltins——檔案與 shell 詞彙。
• residentDiscovery——search_tools 與 list_my_tools。請勿移除它們；它們是代理觸及所有其他工具的方式。
• residentMcpTools——少數幾個值得在每次請求都帶上其 schema 的 Control Center 工具。
• 一個按模式劃分的區塊，用於某個指定模式幾乎每個回合都會用到的工具。

編輯它時有兩條規則：

只在大多數執行都會用到某個工具時，才把它加進去。 每一個名稱都會在每一次執行的每一個請求中，永遠付出其 schema 的成本。一個在用到時很重要、但整體而言罕見的工具，屬於隨需載入的那一半——代理仍然找得到它。

使用工具的真實名稱。 對應不到任何工具的常駐名稱是沒有作用的：不會報錯、不會警告，該工具只會被隨需載入。test/tooling/resident_tool_names_test.dart 會捕捉這種情況，也會讓每個模式的常駐工具數維持在 40 個以下，而這正是這項練習的重點——超出這個區間之後，工具選擇的表現會明顯變差。

模式所需的與釘選的動詞會自動加入，所以你永遠不需要列出模式自身的輸出動詞。

診斷差劣的工具選擇

當代理用錯了工具，或聲稱自己做不了某件事時，請判斷究竟是以下三種情況中的哪一種。

1. 它有沒有找過？

每一次執行都會記錄它載入了哪些隨需載入工具，以及觸發載入的原因——直接按名稱呼叫，或一次 search_tools 查詢。開啟該次執行的事件串流（設定 → 工作區 → 代理 → 該代理 → 日誌 → 檢視），並尋找 [harness] loaded N deferred tool(s)。

• 沒有記錄任何東西，而代理說這項能力不存在——它根本沒有找過。這是提示的問題，而不是檢索的問題：隨需載入索引就在它的系統提示中，並附有指示，要求在搜尋回傳空結果之前，不得宣稱某項能力不存在。
• 記錄了一次搜尋，但沒有載入任何東西——這是真正的檢索未命中。請前往第 2 步。
• 載入了工具，卻用錯了其中一個——它找到的工具太相似了。請前往第 3 步。

2. 修正檢索未命中

search_tools 會比對名稱、描述與引數名稱。檢索未命中幾乎總是意味著描述裡沒有代理所用的字詞。

請把它們加進去。描述就是檢索索引，所以寧可加長，也不要裁剪——要寫下操作者真正會輸入的詞彙（“assign”、“hand off”、“give to”），而不只是內部用的名詞。為了節省 token 而裁剪描述，會同時賠上搜尋命中與選擇準確度，而相對於 schema 而言幾乎省不了什麼。

如果正確的工具確實存在，但排名偏低，那正是 limit 引數的用途；工具自身的描述會告訴代理，當搜尋看似接近卻仍落空時要擴大搜尋範圍。

3. 修正過於相似的工具

如果兩個工具的描述，對於本來就不知道其中差異的人來說讀起來一模一樣，那麼模型就只是在猜。請把它們合併成一個帶有區辨引數的工具。

ticket_relation 與 ticket_pr_link 就遵循這個模式：兩者都透過一個區辨引數來處理連結與取消連結。在單一次呼叫之中、手握請求完整上下文所作的選擇，比在兩個雷同描述之間所作的選擇更可靠。

當工具需要不同的核准閘門、不同的稽核或不同的呈現方式時，就讓它們保持分開——這些都是合併會讓你付出真實代價的理由。

確認提示快取運作正常

快取命中率會顯示在 可觀測性 → 洞察 中，名為 快取率。一段健康、長時間運作的對話會維持在偏高的水平；如果它持續偏低，那就是有東西在每個回合改寫前綴。

常見成因，按可能性排序：

• 提示前段的任何非確定性內容。 一個時間戳、一個請求 id，或以不同順序反覆運算的集合，都足以造成這個情況。
• 對話中途更換模型或推理力度。 兩者都會改變前綴。子代理在這方面特別容易出錯：為了省錢而以較低的力度執行子代理，因失去快取共用而付出的代價，可能比省下來的還多。
• 頻繁壓縮。 壓縮本來就會改寫歷史，所以它的代價是真實的；解決之道是少而深地壓縮，而不是多而淺。

以 --tool-deferral=off 關閉隨需載入，是隔離某項行為改變是否源自兩層式介面的有效 A/B 做法。它會完全重現隨需載入出現之前的請求，因此如果關掉之後該行為仍然持續，那麼這個介面就不是成因。