第三章　工具目錄

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

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

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

11.1 工具一覽

11.2 一般傳回欄位

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

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

11.3 read

編碼識別：優先按 BOM 判定；無 BOM 時識別 GBK / GB18030 / UTF-16 等常見編碼，解碼為 UTF-8 後交付。grep 走同一套解碼。確屬二進位的文件預設拒讀（用 as_text 覆蓋）。

11.4 write

11.5 patch

11.6 list

11.7 glob

11.8 grep

11.9 fs.exec / fs.exec.start

支持的 shell 語法（非無限制模式同樣可用）：

• samples/ 只攔執行，不攔讀取與作為參數傳入。
• test.run / lint.run / sast.run 給出的命令走同一套護欄與同一個分詞器。
• 路徑口徑：工作區內的絕對路徑與相對路徑走同一套判定，不再一律拒絕絕對路徑。
• 白名單已含 cc 家族編譯器（cc / gcc / clang 等）：寫出通道（-o / -MF 等）圈禁工作區內，危險旗標前綴攔截。
• 命令名歸一化（Windows）：大小寫與 .exe 後綴不影響白名單判定；被政策拒絕時錯誤訊息帶上命令與規則上下文。
• 輸出編碼：Windows 下 GBK / UTF-16 輸出在匯聚點統一歸一為 UTF-8（fs.exec 與 fs.exec.tail 均覆蓋）。
• 回顯：結果中的命令按原樣保留引號，不做空格重拼。
• Windows 批處理（.bat / .cmd）參數帶專門的注入護欄。
• 工作目錄不被劫持：工作區下的同名文件不會被解析成待執行程式。

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 內置語言（24 門，按 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 參數

模型：按「模型路由策略」在已啟用且有 API Key 的瀾砥系列模型中選（預設效果優先）；無可用瀾砥模型時用當前會話的 provider / model（隱式注入）；本機模式下只用會話模型；兩者都拿不到時報錯。超時與輸出上限跟隨所選模型配置。檢索片段會發給所選模型。

傳回 answer + citations[]（file / start_line / end_line / name）+ hit_count + model + provider + routed（是否為路由選中的瀾砥模型）；檢索不到會直說、不編造。預設對擴充檢索結果做結構感知智慧重排（無需顯式 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 背景任務請顯式指定直譯器。