第三章　工具體系

本章覆蓋第 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 工具呼叫的視覺化

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

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

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

在途呼叫的行內進度：耗時較長的工具在呼叫行的工具名右側實時顯示進度（轉圈圖示 + 文案，有比例時另帶一條細進度列）；進度文案優先展示，參數摘要讓位截斷。只有真正在途的呼叫才會點亮。

• 子任務派發、等待類工具（Agent / AgentParallel / TaskWait 等）與向你提問不顯示「已執行」。
• 背景會話的進度會以一條原地更新的提示告訴你（「會話名：進度」）；「已執行」只在呼叫行內顯示。
• 「極簡」密度下，正在顯示行內進度的那條呼叫不會被合並進「N 次工具呼叫嘗試」。

9.4.1 Hook 執行過程可見

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

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

給工具執行加了「空閒超時」兜底：某個工具長時間沒有任何回饋時會被安全收尾，不再讓整輪一直掛着乾等。這道兜底按「空閒（無回饋）」判定，不按總時長 —— 只要工具持續有進度回饋，長任務就不會被固定時限打斷。

• 觸發條件：工具連續 ≥ 預設 10 分鐘沒有上報任何進度。判據是工具自己上報的進度，閘道層的保活心跳不算回饋。
• 不剝奪工具自己的時限：聲明了執行時限的工具（如 fs.exec 的 timeout），兜底至少讓到「工具時限 + 6 分鐘」之後才生效 —— 例如 fs.exec 設 timeout=900 的長命令不會再在 10 分鐘處被放棄。
• 外部工具服務（MCP）呼叫同樣改為空閒制：連續 35 分鐘沒有工具回饋才判超時（每次收到回饋即重新計時），不再按 35 分鐘總時長取消仍有回饋的呼叫；有時限通告時至少等到「剩餘時限 + 5 分鐘」。
• 被放棄的呼叫遲到的進度不會記到同名的下一次呼叫上。
• 豁免：子 Agent 家族（Agent / AgentParallel / TaskWait / TaskOutput / TaskStop）單獨走 §15.2.1 的空閒視窗 + 絕對兜底，不被這道空閒超時誤殺。

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

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

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

9.4.1.3 回復複讀檢測（複讀空轉）

與上面"同參反復呼叫工具"不同，這裡看的是不呼叫工具、只在本文裡反復輸出相似內容的情況 —— 模型在一條回復裡同一行刷屏，或者一連幾輪都回同一句話卻不動手。

• 單輪內按行截停：一條回復最近 25 行裡同一行出現 ≥ 3 次（其中至少兩次相鄰），或出現 ≥ 5 次，就當場截停這次輸出 —— 本文保留到複讀區的第一遍，已經流出的思考內容保留。幾句話之間來回輪轉、「好。」「執行。」這類極短句刷屏也能識別；程式碼區塊、表格行、純標點行不計入。已經帶了工具呼叫的回復不截。
• 跨回合提醒與停轉：連續幾輪沒呼叫任何工具、回復內容都一樣時，第 3 次起給模型一句提醒（不落盤），第 5 次加重；第 8 次（或一條鏈上累計 3 次單輪截停）自動停轉，同時暫停自動續跑，並在會話裡留一條說明：「模型最近 N 次回復都是「…」且沒有任何實際動作，判定為複讀空轉，已自動停止……」。補充更具體的指示後繼續，或換個模型再試。你的新輸入、工具結果都會把計數清零。
• 看得見：會話清單上同樣標出「疑似空轉」，背景會話還會彈提示；停轉時即使是當前會話也會提示。

9.4.2 軌跡面板（Trace）

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

按「執行」切分，不再把整個會話糊成一團：面板頂部有一排執行（run）選擇器，按你發出的每條訊息切分成一次次獨立執行，預設看最近一次；每個 run 標籤上直接帶步數、工具呼叫數、token 與失敗數，一眼挑出可疑的那次。

頂部聚合卡顯示這一次執行的：

下面還有工具維度的統計表（每個工具的呼叫數 / 失敗數 / P50 / P95 / 最長耗時），以及一條 「每輪 Prompt」趨勢條 —— prompt token 逐輪等差遞增往往就是"陷入循環 / 上下文在膨脹"的指紋，看這條比逐步翻快得多。

時間線：

• 每步顯示序號 / 角色 / 類型 / 來源 / 工具名、耗時、prompt / completion / total token、模型、finish reason、成敗與錯誤訊息，以及內容與呼叫參數的預覽（工具步能直接看到這次到底傳了什麼參數，不用回訊息流裡翻）。
• 點一步即跳到訊息流中對應位置，回看「哪步走偏」更方便。
• 過濾：全部 / 僅工具 / 僅錯誤 三檔，排障時直接切到「僅錯誤」。
• 長執行只載入末尾一段（預設末 500 步，聚合數字仍是全量），頂部提示「已省略更早的 N 步」，點「載入更早」按窗翻頁，不會一次把超長執行全灌進來。
• 特殊步會單獨標出：「上下文壓縮（SUMMARY）」標明這次收編了多少條；「自報暫停」標明此處模型輸出了停下的信號（該標記不進本文，只在軌跡裡可見）。

子代理下鑽：Agent / AgentParallel 這類派發步上有「子軌跡」入口，點進去看這個子代理自己的完整軌跡，看完點「傳回主軌跡」回來。下鑽態下步驟不提供跳轉（那些行屬於子會話文件，主訊息流裡沒有對應位置）。

匯出：面板右上「匯出」把當前視圖（當前 run / 當前子軌跡）落成文件，旁邊有「脫敏」勾選框，預設勾上 —— 勾上則按 設定 → 資料脫敏 的規則取代後再落盤（沒配規則時等於無變化），取消勾選按原文匯出。成功後 toast 裡給出落盤路徑。子軌跡視圖下不提供匯出與脫敏。

重新整理與錯誤態：資料來自會話 JSONL 的伺服器端聚合，開啟面板時載入一次，不做實時輪詢；這一輪跑完時面板會自動重新整理一次（此時 JSONL 已帶終態），也可以隨時點右上的重新整理按鈕。讀取失敗時面板給出「讀取軌跡失敗，點『重新整理』重試」而不是空白。

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 工具可用。