工具系統 ToolRegistry

源码版本v2026.7.20

職責

Tool 是 agent 能呼叫的原子函式(終端、瀏覽器、檔案、MCP、技能呼叫……)。ToolRegistry 在模組匯入時透過 AST 掃描自動發現 tools/*.py 裡的工具並註冊,提供一個 name → ToolEntry 的查詢表給主迴圈做工具分發。工具是靜態的——與技能的「可演化」相對。

關鍵檔案

• discover_builtin_tools:67-86 — AST 掃描 tools/*.py 找出註冊了工具的模組
• _is_registry_register_call / _module_registers_tools:30-43 — 判斷某模組是否呼叫 registry.register
• class ToolEntry:87-153 — 單個工具的元資料(handler、schema、toolset、快取標記)
• class ToolRegistry:217-365 — 註冊表本體
• def register:365-436 — 註冊一個工具,內部建構 ToolEntry
• get_entry / register_toolset_alias:274-290 — 查詢與 toolset 別名
• register_plugin_override_policy:316-365 — 外掛工具的命名空間准入策略
• registry 單例:765 — registry = ToolRegistry()(模組級單例)
• tool_error / tool_result:784-810 — 工具回傳值標準封裝
• tools/ 目錄 — 約 80 個工具檔案(terminal/browser/web/file/mcp/skills/delegate…)

資料流

1. 啟動期 init_agent:276 觸發 toolsets 設定。
2. discover_builtin_tools:67 遍歷 tools/ 目錄,用 AST 判斷每個模組是否呼叫 registry.register(tools/registry.py:30)。
3. 命中的模組被匯入,其模組級 registry.register(...) 呼叫執行,把 ToolEntry 寫入 registry 單例:765。
4. 主迴圈每輪把啟用的 toolsets 對應的 ToolEntry.schema 收集進發給 provider 的 tools 欄位。
5. provider 回傳 tool_call → 主迴圈用 get_entry(name)(tools/registry.py:274)查到 handler 執行 → 結果用 tool_result:798 封裝回填。

小結

工具系統的關鍵在「匯入即註冊」——靠 AST 掃描避免手動維護清單,新增工具只需往 tools/ 丟一個呼叫 register 的檔案。registry 單例是全域唯一真相,主迴圈只讀它。和技能的區別:工具是死的函式,技能是可被學習迴圈改寫的流程。