第三章　工具體系

本章覆蓋第 9–13 章：先總覽工具體系，再分述智慧程式設計工具與安全分析工具，隨後是外部工具服務的接入方式，以及貫穿所有工具的權限與簽核機制。

第九節 工具體系總覽

工具（Tool）是 AI 在你電腦上"動手"的載體。

9.1 三類工具

• 智慧程式設計工具：讀寫文件、跑命令、版本控制、尋找等（詳見第十節）。
• 安全分析工具：雜湊、字串、IOC、可執行格式解析、反匯編、規則匹配、流量元資料等（詳見第十一節）。
• 外部工具服務：連線外部系統的工具，如 Notion、內部 API、私有知識庫等（詳見第十二節）。

9.2 工具開關

每個工具都可以設置為：

• 啟用：直接放行。
• 詢問：每次呼叫前彈窗簽核。
• 停用：直接拒絕。

入口在輸入區模式滑塊旁的齒輪（智慧體管理器）→「配置工具」Tab，可按工作模式獨立配置。三態真實約束執行：「停用」在主代理與子代理兩側一並生效；「詢問」接入實際確認流程，呼叫前暫停等你批准；解除安裝外掛或外部工具服務時會一並清理殘留的工具配置，盤上配置與實際可用工具保持一致。

工具列表更穩：工具列表拉取失敗時自動退避重試，多次重試仍失敗才提示；兜底工具表與內置工具同源生成，不會莫名少一截。

9.2.1 工具分類延遲載入（預設開啟）

工具總數已過百，若每輪都把全部工具描述發送給模型，既佔上下文又拖慢回應。因此預設只攜帶常用的一小部分（二十餘個），其餘按分類在需要時才載入。

• 常駐分類：文件讀寫與搜尋、命令執行、工具自省、子任務委派與待辦規劃 —— 這些幾乎每輪都要用。
• 按需載入的分類（16 類）：程式碼理解、git、安全分析、威脅情報、SBOM、外部工具服務、連網檢索、技能、測試、lint、SAST、外掛市集、外掛管理、GitHub、系統資訊、時間。
• 兩種載入方式：你的提問裡出現相關詞彙時自動預載入對應分類；助手也可以主動呼叫 tools.load 點名載入。中途新連上的外部工具服務會自動放行。
• 助手知道工具表是不全的：系統提示詞裡會說明這一點並給出分類目錄，助手不會因為"表裡沒有"就認定某項能力不存在；查詢自身可用工具時，傳回結果也會提示"看不見 ≠ 不存在，可以先載入"。

開關：智慧體管理器 →「配置工具」Tab →「工具分類延遲載入」。關掉後所有工具恆常駐。當可用工具本就不多（不超過 32 個）時，系統會直接整表放行，不做延遲載入。

若某個外部工具服務你用得很頻繁，可以在同一面板裡單獨為它關閉延遲載入，讓它的工具始終可用 — 見 §12.4。

9.3 工具命名空間

外部工具服務暴露的工具會被自動加上前綴（例如 notion.*），與內置工具區分，互不衝突。

9.4 工具呼叫的視覺化

每一次工具呼叫都會以可折疊卡片形式顯示在訊息流中，包含：

• 工具名 + 入參摘要
• 執行耗時
• 結果（成功 / 失敗 / 截斷）

你可以獨立檢視每個工具呼叫的細節，便於稽核與回溯。

9.4.1 Hook 執行過程可見

每次掛鉤（hook）執行都會在對話流裡出現一條系統訊息，渲染成類似工具呼叫的可折疊條（內容按 Markdown 顯示），方便確認掛鉤到底跑沒跑、跑了什麼、是否影響了下一步動作 — 不再是黑盒。

9.4.1.1 工具執行空閒超時（預設 10 分鐘）

給工具執行加了「空閒超時」兜底：某個工具或子任務長時間沒有任何進展（沒有 stream 輸出 / 狀態變化）時會被安全收尾，不再讓整輪一直掛着乾等。

• 觸發條件：連續空閒 ≥ 預設 10 分鐘。正常的長任務只要還在持續產出就不受影響。
• 豁免：子 Agent 家族單獨走 §15.2.1 的空閒視窗 + 絕對兜底，不被這道 10 分鐘空閒超時誤殺。

9.4.1.2 重複呼叫提醒（疑似空轉）

助手偶爾會陷入"用同樣的參數把同一個工具反覆呼叫"的循環 —— 它一直在動，所以空閒超時抓不到，但其實毫無進展，額度卻在持續消耗。

• 連續 3 次同參呼叫同一工具即在工具結果裡提示助手，請它換個思路；次數繼續增加會逐級加重措辭。
• 工作階段列表上標記「疑似空轉」，滑鼠停留可見已重複的次數與工具名；側邊欄與頂部分頁兩種佈局都會標記。同時發出通知，即使你切到別的工作階段也能第一時間發現。
• 重新啟動應用後標記依然保留，不會因為重新啟動而漏掉；等你在該工作階段發出新的一條訊息後自動清除。
• 輪詢類工具（等待子任務、拉取命令輸出等）本就需要反覆呼叫，不在此列。

9.4.2 軌跡面板（Trace）

工作階段頂部的統計氣泡（StatsPopover）裡和原「Stats」面板並列新增了 「軌跡」（Trace）面板：把 AI 一次執行裡呼叫了哪些工具、按什麼順序、各自的輸入輸出與耗時攤開成時間線，方便回看它到底怎麼一步步把活做完的，也方便排查「哪步走偏 / 燒在哪」。

每個步驟顯示：

• 序號 / 角色 / 類型 / 來源 / 工具名
• 耗時、prompt / completion / total token 數、模型、finish reason
• 是否成功 / 錯誤訊息 / 內容預覽

頂部聚合卡顯示這一次執行的：總步數、assistant 輪數、工具呼叫次數 / 失敗數、錯誤數、門禁注入次數、token 用量、工具總耗時、牆鐘時長、用到的模型清單；下面還有工具維度的統計表（每個工具的呼叫數 / 失敗數 / P50 / P95 / 最長耗時）。

資料來自工作階段 JSONL 的伺服器端聚合（GetSessionTrace），按需開啟 popover 時載入一次，不做實時輪詢。

時間線步驟可點擊跳轉：點軌跡時間線上的某一步，會直接跳到訊息流中對應的位置並定位過去，回看「哪步走偏 / 燒在哪」更方便。

9.5 讓助手自己配置 MCP 服務

除了在設置面板裡手動新增外部服務，助手還可以在對話裡直接幫你配置 MCP server。AVL Code 提供 9 個 mcp.* 工具，常配合內置 mcp-admin 助手使用：

兩步制（dry-run）：寫類工具（add / remove / toggle / import）必須顯式傳 confirm=true 才會真正落配置；首次呼叫預設傳回 dry-run 預覽（完整命令列、路由、預設後端變更、衝突清單）讓你審完再確認。這是沒有 PreToolUse defer hook 時的兜底閘門 — LLM 單步不可直接做破壞。

金鑰脫敏：所有讀類工具傳回的 authToken 一律只顯示尾 4 位（其餘字元以星號佔位），環境變數值整體打碼，避免在對話流裡洩露憑證。

典型對話：

「幫我把 mcp-trends-hub@1.6.0 接進來。」

助手 → 調 mcp.add_server（dry-run）→ 傳回預覽 → 你確認 → 助手再調 mcp.add_server(confirm=true) → 落配置 → 用 mcp.test_server 真交握探活 → 報告 21 個 trending 工具可用。