← 文件教學

6 個內建工具

LLM 在評審過程中可呼叫的工具——完整 schema 與範例

各階段工具可用性

工具PlanMain用途
task_done✗✓「我完成了」——終止迴圈
code_comment✗✓發出一條帶行範圍 + 建議的評審評論
file_read✗✓讀變更後快照中某檔的一段
file_read_diff✓✓讀另一檔的 diff 確認跨檔關切
file_find✓✓依檔名關鍵字定位檔案
code_search✓✓全倉 grep（git grep）

task_done 與 code_comment 在 plan 階段有意不可用——plan 是唯讀的。

脈絡工具是唯讀脈絡，不是評論目標。file_read / file_read_diff / file_find / code_search 讓模型更好理解目前檔的 diff；收集脈絡時發現的問題按設計被忽略。跨檔關切只有在目前檔 diff 中可觀察時，才會成為評論。

task_done

{ "name": "task_done", "input": { "state": "DONE" } }

agent 看到 task_done 後停止呼叫 LLM，開始處理已累積的 code_comment。state 可為 DONE 或 FAILED。

code_comment

{
  "name": "code_comment",
  "input": {
    "comments": [{
      "content": "`tx.Rollback()` is never deferred — early returns leak the transaction.",
      "existing_code": "tx, err := db.Begin()\nif err != nil {\n    return err\n}",
      "suggestion_code": "tx, err := db.Begin()\nif err != nil {\n    return err\n}\ndefer tx.Rollback()"
    }]
  }
}

comments 是陣列，一次可發多條。每條錨定到 existing_code 片段，OCR 自動算行號。

錨定演算法

  1. hunk 新側——context + added 行；失敗重試 hunk 舊側。
  2. 全新檔掃描——對整個變更後檔案逐行比對。
  3. 重新定位任務——仍失敗則跑 RE_LOCATION_TASK。

比對對空白不敏感。最後手段以 start_line=0 交付——問題是真的，但需自行定位。

file_read

{ "name": "file_read", "input": { "file_path": "src/foo.go", "start_line": 10, "end_line": 80 } }

讀變更後形式的一段行（每行以 1 起始行號 + | 前綴）。每次最多 500 行。

file_read_diff

{ "name": "file_read_diff", "input": { "path_array": ["src/api/handler.go", "src/db/queries.go"] } }

讀同一變更集中其他檔的 diff。路徑不在變更集則靜默省略。

file_find

{ "name": "file_find", "input": { "query_name": "UserService", "case_sensitive": false } }

與每個檔的 basename 做子串匹配，最多 100 條。無匹配回 // The file was not found。

code_search

{
  "name": "code_search",
  "input": {
    "search_text": "TODO|FIXME",
    "file_patterns": ["*.go", ":(exclude)vendor/"],
    "case_sensitive": false,
    "use_perl_regexp": true
  }
}

由 git grep 驅動，理解 pathspec、遵循 .gitignore。每檔命中上限 100。

pathspec 速查

目標file_patterns
所有 Go 檔["*.go"]
除測試外所有 Go["*.go", ":(exclude)*_test.go"]
僅一個目錄["src/api/"]
多型別、排除 vendor["*.go", "*.ts", ":(exclude)vendor/", ":(exclude)node_modules/"]

自訂工具

新增新工具名需在 Go 側接入（internal/tool/definitions.go）——單靠 JSON 無法加新行為。

📖 教學解說：6 個工具深入

plan 階段的工具可用性

Plan 階段只能用 file_read_diff、file_find、code_search——三個脈絡工具。task_done 和 code_comment 被禁用。為什麼？Plan 是唯讀分析階段——只收集脈絡，不做決策。這確保 plan 產出是純指引，不附帶評論。

code_comment 的錨定三階段

錨定不是一次性嘗試：

  1. hunk 新側——在 diff 的 context + added 行中搜尋 existing_code
  2. 全新檔掃描——如果 hunk 匹配失敗，掃描整個變更後檔案
  3. RE_LOCATION_TASK——仍失敗，跑 RE_LOCATION_TASK 請模型重新錨定

比對對空白不敏感。最後手段以 start_line=0 交付——問題是真的，但需自行定位。

脈絡工具的「忽略」機制

file_read、file_read_diff、file_find、code_search 都是唯讀脈絡工具。它們讓模型更好理解目前檔的 diff，但收集脈絡時發現的問題按設計被忽略。只有在目前檔 diff 中可觀察的跨檔問題才會成為評論。這是刻意的——避免「噪音評論」。

練習 / 驗收清單

  • 能說出 6 個工具各做什麼
  • 能區分哪些在 plan 階段可用
  • 能解釋脈絡工具不會成為評論目標的原因
  • 能描述 code_comment 的錨定三階段
看完這頁你應該能說出：6 個工具各做什麼、哪些在 plan 階段可用、為什麼脈絡工具不會成為評論目標、以及 code_comment 的錨定三階段。

延伸閱讀：架構 · 程式碼：internal/tool · MCP 伺服器