運作原理

一句話

OCR 讀你的 Git diff，把變更檔交給可呼叫工具的 LLM Agent，產生精確到行的結構化評論。它能讀完整檔案、搜尋 codebase、查看其他變更檔做脈絡，產出「深層評論」而非表面的 diff 回饋。

通用 Agent 的問題

如果你用過 Claude Code 這類通用 agent 的 review skill，一定遇過這些痛點：

根因：純語言驅動的架構，對評審流程缺乏硬性約束。

核心設計：確定性工程 × Agent 混合

OCR 把「不能出錯的部分」交給工程邏輯，把「動態決策」交給 Agent。

確定性工程 —— 硬約束

• 精確檔案選擇——精確決定哪些檔案要審、哪些要濾，保證不漏掉重要變更。
• 智慧檔案 bundling——把相關檔案併成單一評審單元（如 message_en.properties 與 message_zh.properties），每個 bundle 以子 agent 隔離執行——大變更集也穩、可並行。
• 細粒度規則匹配——依檔案特性匹配評審規則，讓模型注意力精準聚焦。template 引擎比純語言規則更穩定可預測。
• 外部定位/反思模組——獨立的評論定位與反思模組，系統性提升位置與內容準確度。

Agent —— 動態決策

• 情境調校 prompt——為程式碼評審深度最佳化的 prompt 模板，同時降低 token 消耗。
• 情境調校工具集——從大型生產資料的工具呼叫軌跡中提煉（呼叫頻率分布、工具重複率、新工具對呼叫鏈的影響），得到比通用 agent 工具集更穩定可預測的評審專用工具。

執行流程一覽

ocr review
  → bootstrap         解析 LLM 端點、載入模板/工具/規則
  → diff provider     git diff → []model.Diff（workspace/commit/range）
  → filter & rules    五重門過濾 + 每檔選規則
  → subtask dispatch  每檔一個子 agent（concurrency=8）：plan → main 迴圈
  → output writer     行解析 + 評審過濾，渲染 text 或 JSON

每檔子任務：plan + main

每個通過過濾的檔案，OCR 啟動一個子 agent，在自己的 goroutine 中跑，受 --concurrency（預設 8）約束。

• Plan 階段（可選）——diff 變更行數 ≥ 50（PLAN_MODE_LINE_THRESHOLD）才跑。單次 LLM 呼叫、不給工具，產出清單作為 main prompt 的指引。
• Main 迴圈——與模型展開工具呼叫對話，最多 30 輪（MAX_TOOL_REQUEST_TIMES）。收集 code_comment 呼叫作為評審評論。記憶體超過預算時觸發三分區壓縮。

記憶壓縮：三分區策略

長的工具呼叫迴圈終會溢出 context。OCR 用 MAX_TOKENS = 58888 的預算管理：

訊息分三區：frozen（前 2 則 system+user）、compress（摘要成一則）、active（最近可裝進預算的完整輪次）。compress 區以 XML 渲染交給 MEMORY_COMPRESSION_TASK，摘要包在 <previous_review_summary> 標籤內。

評論處理流水線

1. 行解析——existing_code 用滑動視窗與 diff 比對，算出精確 start_line/end_line。
2. 重新定位（可選回退）——行解析在複雜 diff 上失敗時，跑 RE_LOCATION_TASK 請模型重新錨定。
3. 評審過濾——REVIEW_FILTER_TASK 對照 diff 檢查評論，移除可證明為錯的。
4. 二輪行解析——頂層命令對完整評論集重跑，捕獲跨檔或重新定位的評論。

什麼不自動化

• 端點發現沒有回退——config + env + rc 給不出完整 (URL, token, model) 三元組就非零退出，不猜。
• 子 agent 失敗隔離不重試——一個失敗檔產生警告，其餘繼續；重試屬包住它的 CI 管線。
• 無跨檔推理——每檔在自己的 LLM 對話中審；跨檔問題透過 file_read_diff/code_search 理解，但不對「其他檔」的發現發表評論。

延伸閱讀：架構總覽 · 6 個工具 · 評審規則