第三章　工具目錄

本章覆蓋第 11–14 章：智慧程式設計與安全分析工具的參數速查、外部工具服務接入欄位與工具權限政策。

第十一節 智慧程式設計工具

[!ref] 詳解見使用者手冊「智慧程式設計工具」節。

11.1 工具一覽

11.2 一般傳回欄位

讀取 / 搜尋類工具的傳回都包含：

結果瘦身（省 token / 額度）：工作區工具的傳回路徑一律相對工作區根（relPath），錯誤串出口剝除根路徑前綴（不外洩絕對根），去除重復 line_hashes，分頁記賬（next_offset 等）僅在 truncated=true 時才輸出。

11.3 read

11.4 write

11.5 patch

11.6 list

11.7 glob

11.8 grep

11.9 fs.exec / fs.exec.start

11.10 fs.exec.tail / fs.exec.kill / fs.exec.list

本機後台工作階段上限：最多 16 個並行；單工作階段磁碟記錄檔 256 MiB（溢出丟尾）；程序結束後記錄檔可繼續拉取，1 小時後 GC 回收；工作階段隨 Interpreter 生命週期結束。

SSH 遠端後台工作階段不受上述限制：狀態與記錄檔落在遠端 <root>/.avlcode/sessions/，記錄檔為完整文件（無 256 MiB 環形丟尾），且跨斷線重連與應用重新啟動存活（見 §22.4）。

11.11 web.bing / web.fetch

11.12 code.* — 程式碼智慧工具組（基於 LSP）

位置參數對外 1-based（對齊 fs.read 行模式 / cat -n）；進 LSP 前由 interpret 層轉 0-based。

能力降級：可選能力（implementation / type_definition / document_highlight / completion / signature_help / formatting 等）並非每個語言伺服器都實現。是否支持按真實回應判定而非按 server 宣告預判（避免宣告缺失導致的誤拒）；判定為不支持後跨工作階段快取，同一 server 不再重複試探。

11.12.1 內置語言（22 門，按 ID）

go · ts · py · c（cpp） · rust · java · deno · eslint（js 增強） · lua · bash · yaml · php · ruby · vue · zig · dart · kotlin · clojure · elixir · haskell · fsharp · csharp · gleam · astro

每門語言綁定一個 LSP 命令（gopls / typescript-language-server / pyright-langserver / clangd / rust-analyzer / jdtls / …）；缺哪個按需自動下載（go install / npm 等），並顯示安裝進度。

11.12.2 使用者設定文件 lsp.yaml / lsp.json

工作區根目錄 .avlcode/ 或 ~/.avlcode/，按 lsp.yaml > lsp.yml > lsp.json 順序取第一個存在的：

lsp:
  rust:
    disabled: true              # 停用
  go:
    cmd: gopls                  # 覆蓋啟動命令
    args: ["-rpc.trace"]
    root_markers: ["go.mod", "go.work"]
  custom_lang:                  # 增加自定義 server
    extensions: [".myx"]
    cmd: my-langserver
    install_via: npm
    install_pkgs: [my-langserver]

熱重載：文件 mtime/size 變更自動重讀，不必重新啟動工作區。伺服器程序崩了 / SSH 掉線自動重新啟動。

11.12.3 全函式庫 RAG 檢索與問答（code.search / code.ask）

非向量（零 embedding）符號級全函式庫檢索：BM25 + 識別碼切分（駝峰 / 底線 / 連字元）+ 中日韓二元切分（中文註釋 / 中文提問同樣能命中），純本機、可離線。索引落 <base>/.avlcode/rag/symbols.jsonl（遠端工作區僅記憶體），首建後按文件 mtime 增量同步（改 / 增 / 刪）。僅索引定義類符號（函數 / 方法 / 類型 / 接口 / 常數等）。

索引文件數上限 4000（不可配）。超限時如實回報而非靜默截斷：結果裡帶 index_covers_all_files=false、files_not_indexed（未納入索引的文件數）與 truncated_hint 可讀提示，便於判斷"沒搜到"是真不存在還是沒覆蓋到。

code.search 參數

傳回 hits[]（file / start_line / end_line / name / kind / score / why[]（命中的關鍵詞）/ 可選 container·signature）、count、indexed_symbols、indexed_files；空結果給 hint。

code.ask 參數

復用當前工作階段的 provider / model（隱式注入，未取到則回落 AVL-Zero）。傳回 answer + citations[]（file / start_line / end_line / name）+ hit_count + model；檢索不到會直說、不編造。預設對擴充檢索結果做結構感知智慧重排（無需顯式 expand）。

上限：索引文件數 ≤ 4000、全量構建超時 120s、每文件 ≤ 400 符號 / ≤ 4 MiB；結構重排取標頭 8 條。增量重新整理的作用域已修正（文件變更後不多刷、不漏刷）。

11.13 test.run — 測試執行 + 失敗回灌

傳回：failures[]（最多 50 條 {test, file, line, message}） + 一小段原始 tail；未知框架退回到結束碼 + tail 兜底。plan（籌劃）模式停用（執行測試會產生寫副作用）；assess（評估）模式可用，以便驗收階段實際跑測試。

11.13.1 自檢門禁（opt-in，泛化的多檢查器）

testgate.yaml 結構：

enabled: true
checks:                              # 檢查器列表（可單選 / 組合）
  - name: test                       # test | diagnostics | lint | sast
    mode: block                      # block | report
    submode: changed                 # test: changed | full
    scope: changed                   # changed | workspace
  - name: lint
    mode: block
    submode: strict                  # lint: strict | lenient
    linters: [errcheck, govet]       # 子集（可選）
  - name: sast
    mode: report
    submode: quick                   # sast: quick | deep
    config: .semgrep.yml             # 離線規則（可選）
modes:                               # 按工作模式分別覆蓋
  plan:    { enabled: false }
  prepare: { enabled: false }

11.13.2 CheckSpec 欄位

11.13.2a testgen — 改動缺測試自動補（opt-in）

• 不在預設集：要顯式把 testgen 加進 checks 才生效。
• 覆蓋語言：Go / Python / JavaScript / TypeScript；其它副檔名（.c / .java 等）不判定。
• 測試文件本身與生成物跳過：避免「給測試寫測試」「給 .pb.go 寫測試」。
• 存在性查詢：經 zMCP 閘道 fs.glob 查測試文件存在性（SSH 遠端也正確）。
• 3 次注入硬上限：復用 MaxTestGateRetries，誤報最多糾纏 3 輪即停門禁。

11.13.2b judge — LLM 收尾自審（opt-in，預設 report）

• 獨立 fresh-context 模型呼叫：復用 agentFacade.CompactSummaryStream；不帶 agent 自己的對話歷史，消除自我合理化偏見。
• 看什麼：本輪目標 + diff，挑出機檢抓不到的邏輯 / 語義 / 安全意圖錯。
• few-shot 提示 + 當輪診斷背景注入到 prompt，判斷更準、誤報更少。
• 門控：judge 在所有便宜檢查器之後、且僅當 block 檢查器全綠時才跑。
• 模型亂報 / JSON 髒 / 超時 → 非權威放行，絕不誤攔。
• 傳回結構：{ok: bool, issues: [{file, line, severity, confidence, message}]} — severity ∈ error / warning / info，confidence ∈ 0..1。block 模式下的 confidence / severity 閾值過濾為 Phase 2 計畫。

11.13.3 lint.run — 靜態檢查（只讀分析）

傳回：findings[]（{file, line, rule, severity, message}），與 test.run 同形。golangci-lint v1 / v2 JSON 輸出參數已自適應。只讀分析，plan / assess 模式可用。

11.13.4 sast.run — 安全靜態分析（只讀分析）

傳回：findings[] 同形。後端：semgrep。只讀分析，plan / assess 模式可用。

11.14 tools.list / tools.describe / tools.load — 工具自省與按需載入

自省結果按本工作階段的實際可用性裁剪（受工具三態與分類延遲載入影響），傳回的說明中會提示"表裡看不見 ≠ 不存在，可先 tools.load"。這兩個自省工具本身穿透子代理白名單恆可用，但輸出仍按名單裁剪，且壓不過使用者設置的停用清單。

11.14.1 工具分類延遲載入

預設開啟（Settings.ToolLazyLoad，schema v9 起）。開關在智慧體管理器 →「配置工具」Tab →「工具分類延遲載入」，不在設置頁。

• 常駐分類：fs（讀寫 / glob / grep / exec）、tools（list / describe / load）、agent（委派 + EnterPlanMode / ExitPlanMode / TodoWrite）。
• 16 個可延遲分類：code / git / sec / vt / sbom / mcp / web / skill / test / lint / sast / market / plugin / gh / sys / time。
• 載入路徑：① 隱式 —— 按新增 user 訊息中的關鍵詞預載入對應分類（中英關鍵詞表）；② 顯式 —— tools.load 點名載入。工作階段中途新連的 MCP 後端分類自動放行。
• 繞行：可見候選 ≤ 32 個時整表放行（子代理白名單模式通常走這條）。
• 開啟時系統提示詞會注入一段說明，告知助手工具表是有意精簡的、可按需載入。
• 每個 MCP 服務可單獨設置是否延遲（Settings.MCPLazyLoad，缺省跟隨全域）—— 見 §13.1。

11.15 Python venv 自動感知

fs.exec / fs.exec.start 在工作區裡跑 Python 相關命令時自動遵循工作區 venv：

機制：把首命令改寫成 venv 裡的絕對路徑 + 注入 VIRTUAL_ENV / PATH。專案外發現快取 5 分鐘 / 探測超時 15 秒。全域關閉：AVLCODE_DISABLE_VENV_AUTODETECT=1。

pyright 語言服務（code.*）也接入 venv 感知，本機 + SSH 遠端一致。

例外：SSH 遠端的後台命令（fs.exec.start）不做 venv 感知 —— venv 探測靠本機目錄結構，在遠端會探到錯誤的本機路徑。遠端跑 Python 後台任務請顯式指定直譯器。