90 秒總覽
工具系統的核心概念是「工具契約」與「工具清單」分離。每個工具透過 Tool 介面宣告名稱、描述、參數 schema 與執行邏輯（契約）；可見性則由組裝層與回合層共同決定。要注意：不是所有 gate 都是每回合即時切換，部分條件在載入/打包時就已固定。
執行路徑（主骨架）
export function getAllBaseTools(): Tools {
return [
AgentTool,
BashTool,
FileReadTool,
...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
]
}基礎清單先決定候選工具；回合時還會再套用 deny rules、mode 與 isEnabled() 過濾。
宣告基礎工具清單（每個工具自帶契約）
逐一檢查 feature/env 條件（部分在載入期即決定）
回合階段再套用 deny rules + mode + isEnabled
篩選出本回合可見工具
將可見工具集交給模型
模型決定呼叫哪個工具
該工具進入權限管線檢查
通過後執行工具邏輯flowchart TD
A[工具定義 Tool.ts] --> B[getAllBaseTools]
B --> C{feature flag 檢查}
C --> D{環境條件篩選}
D --> E[本回合可見工具]
E --> F[模型選擇工具]
F --> G{權限檢查}
G -->|通過| H[執行工具邏輯]
G -->|拒絕| I[回報權限不足]
路徑判讀重點
- 工具定義（契約）與工具可見性（清單）是兩個獨立階段。
- 條件分兩類：載入期 gate（例如部分 feature import）與回合期 gate（deny rules、mode、isEnabled）。
- 所有工具呼叫都必須通過權限管線，沒有例外。
- 模型只能看到篩選後的工具集，無法呼叫不可見的工具。
關鍵決策（為什麼這樣設計）
決策 1：工具定義與可見性分離
原因：同一個工具可以依據場景動態開關。例如在受限模式下隱藏危險工具，在完整模式下全部可用，無需維護多份工具定義。
代價：開發者需理解「定義了不代表可用」的間接性，初次接觸時認知負擔較高。
決策 2：混合式 gate（條件載入 + 執行期過濾）
原因：工具系統同時使用 dead-code-elimination 路徑與執行期過濾，兼顧建置體積、效能與可控性。
代價：維運時要分清楚 gate 發生階段，避免把所有可見性都誤判成「每回合即時」。
決策 3：工具必經權限管線
原因：防止未授權操作。即使模型選擇了某個工具，仍需通過權限檢查才能執行，確保安全邊界不被繞過。
代價：每次工具呼叫都有權限檢查開銷，且權限規則設定錯誤會阻擋合法操作。
替代方案與取捨
| 方案 | 優點 | 缺點 | 為何未採用/何時可採用 |
|---|---|---|---|
| 靜態工具清單（啟動時固定，回合中不變） | 邏輯單純，容易推理與除錯 | 無法依場景動態調整，缺乏彈性 | 工具數量少且無模式切換需求時可行，目前場景需要動態組裝 |
| 工具自行檢查權限（無統一管線） | 每個工具可自訂權限邏輯，彈性最高 | 權限邏輯分散，容易遺漏或不一致，安全風險高 | 工具數量極少時可行，規模化後統一管線更可靠 |
| 全量工具註冊（所有工具一律註冊，用時才篩選） | 註冊邏輯簡單，不需管理 flag | 模型看到過多工具會降低選擇品質，token 浪費 | 工具集小時可行，工具數量多時需提前篩選以控制模型輸入 |
失敗路徑與防護
Failure 1：feature flag 設定錯誤導致工具消失
症狀：使用者預期可用的工具在回合中找不到，模型無法呼叫該工具。
防護：加入 flag 狀態日誌，當工具因 flag 被排除時記錄原因；提供診斷指令讓使用者檢視當前可見工具清單。
Failure 2：工具 schema 不符導致模型呼叫失敗
症狀：模型嘗試呼叫工具但參數格式錯誤，工具拋出驗證錯誤或產生非預期結果。
防護：工具註冊時驗證 schema 完整性；執行前對模型傳入的參數做 schema 校驗，並回傳可讀的錯誤訊息。
Failure 3：權限管線阻擋合法工具呼叫
症狀：使用者在正確模式下呼叫工具卻被拒絕，操作中斷且無明確原因。
防護：權限拒絕時回傳具體原因（缺少哪個權限、需要哪個模式）；定期審查權限規則避免過度收緊。
實作驗證（你改完要怎麼確認）
- 確認基礎工具清單完整：呼叫
getAllBaseTools()並檢查回傳的工具數量與預期一致。 - 確認 feature flag 切換後工具可見性改變：開啟／關閉特定 flag，驗證對應工具出現或消失。
- 確認未授權工具被正確攔截：在受限模式下嘗試呼叫需要權限的工具，驗證回傳權限不足錯誤。
- 確認工具 schema 驗證生效：傳入不符 schema 的參數，驗證工具回傳明確的驗證錯誤。
這四步覆蓋「清單完整性、動態可見性、權限攔截、schema 驗證」，是最低可接受驗證集。