OpenCodeReview：用 Deterministic × Agent 混合架構，讓 AI Code Review 更可控

AI Code Review 最難的問題，通常不是「模型能不能看懂程式碼」，而是每一次 review 是否都能穩定地看完該看的檔案、把問題標在正確位置，並且讓團隊能在成本與噪音之間取得可接受的平衡。Alibaba 開源的 OpenCodeReview 選擇了一條務實路線：讓 deterministic engineering 負責不能出錯的流程約束，再讓 agent 負責需要判斷與取上下文的部分。

這個設計使它不只是「把 diff 丟給 LLM 的 CLI」，而是一個可以接到本機工作區、CI/CD、GitHub Actions 以及 coding agent 的 code review 工具。本文會從架構、實際使用方式與限制三個角度拆解它，並說明為什麼「工程護欄與 agent 分工」可能比單純堆疊更長 prompt 更適合程式碼審查。

先看查證結果

截至 2026-09-17 23:06 UTC，GitHub API 顯示 OpenCodeReview 有 34,626 顆 stars、2,461 個 forks；最近一次 push 為 2026-09-17。專案使用 Go，授權為 Apache-2.0，並提供 npm package 與跨平台 release binary。以上數字會隨 GitHub 即時變動，本文只把它們當作本次選題時的快照。

GitHub：<https://github.com/alibaba/open-code-review>
最新 release 查證：<https://github.com/alibaba/open-code-review/releases>
npm package：<https://www.npmjs.com/package/@alibaba-group/open-code-review>

本文閱讀路線

先理解 deterministic engineering 與 agent 的責任邊界。
再用 ocr review、ocr scan 與 ocr delegate 對照三種執行模式。
最後從 CI、成本、召回率與資料治理角度評估它是否適合導入。

OpenCodeReview 解決的是哪一層問題？

一般的 AI review skill 往往以自然語言描述流程：讀 diff、找 bug、回報檔案與行號。這種方式很快能做出 prototype，但在大型變更上容易出現三種不穩定：部分檔案沒有被看完、問題位置漂移，以及 prompt 稍微變動就造成輸出品質波動。

OpenCodeReview 的核心取捨，是把 review 流程拆成兩層：

Deterministic engineering：決定哪些檔案需要 review、哪些檔案應排除、如何把相關檔案分組，以及如何做規則匹配。這些是程式邏輯可以明確保證的事情。
Agent：在已經整理好的 review unit 中進行動態判斷，讀取完整檔案、搜尋 repository、取得其他變更檔案的上下文，最後產生 review finding。

這個邊界很重要。模型不再單獨負責「記得所有流程」，而是被放在它比較擅長的區域：理解語意、追蹤上下文，以及判斷某段程式是否有實際風險。

四個讓 review 更可控的工程護欄

1. 先做精確的檔案選擇

工具不直接要求 agent 自己決定整個 review 範圍，而是先透過 Git diff 與 repository 操作找出應處理的檔案。這可以降低大型 changeset 被模型跳過一部分的風險，也能把排除規則集中在可測試的程式碼中。

2. 相關檔案分組，再平行處理

OpenCodeReview 會把有關聯的檔案組成 review unit，例如不同語系的 properties 檔案可以放在同一組。每一組交給隔離的 sub-agent，形成 divide-and-conquer 的處理方式。這種分組同時服務兩個目標：保留必要上下文，以及避免單一 prompt 無限制膨脹。

3. 用規則匹配縮小模型注意力

專案內建依檔案特徵匹配 review rules 的機制，並支援多種語言與設定檔格式。與把所有規則放在一段自然語言指示相比，template-engine-based 的匹配方式更容易重現，也更容易針對特定檔案類型檢查。

4. 把定位與反思拆成獨立模組

AI 找到問題不代表它能把 comment 放在正確的 diff 行上。OpenCodeReview 另外處理 comment positioning 與 comment reflection，讓「問題內容是否成立」與「應該顯示在哪裡」不必完全交給同一次模型輸出。

這些設計不會讓 AI review 變成形式化驗證，也不能保證零誤報；它們的價值是把容易失控的流程改成可觀測、可測試、可重跑的步驟。

三種使用模式

模式一：直接 review Git 變更

先安裝 npm launcher：

npm install -g @alibaba-group/open-code-review

進入專案後，第一次使用要設定 LLM provider 與 model：

ocr config provider
ocr config model

接著可以依工作情境選擇 review 範圍：

# 審查 staged、unstaged 與 untracked changes
ocr review

# 審查兩個 branch 之間、從 merge-base 開始的變更
ocr review --from main --to feature-branch

# 審查單一 commit
ocr review --commit abc123

如果中途中斷，專案有 session 概念可以列出並恢復工作：

ocr session list
ocr review --from main --to feature-branch --resume <session-id>

模式二：做整個檔案或目錄的 scan

當目標不是某個 PR，而是第一次接手陌生 repository、或要審查沒有明確 Git diff 的目錄，可以使用 ocr scan：

# 掃描整個 repository
ocr scan

# 只掃描指定目錄或檔案
ocr scan --path internal/agent

# 恢復被中斷的 scan
ocr scan --resume <session-id>

review 與 scan 的差異，是前者以變更範圍為中心，後者以檔案內容為中心。導入團隊流程時，這兩者應分開設計 budget 與執行頻率：每個 PR 的 review 需要低延遲，整個 codebase 的 scan 則更適合排程或人工觸發。

模式三：把選檔與規則交給 coding agent

OpenCodeReview 也提供 delegation mode：由既有的 coding agent 執行 review，但仍由 OCR 負責檔案選擇與規則解析：

ocr delegate preview
ocr delegate rule src/main.go src/handler.go

這種模式的意義不是再造一個 agent，而是把 review 的可重現部分抽出來，讓 Claude Code、Codex、Cursor、Kimi Code、OpenCode 或其他 skill-compatible agent 共享同一套選擇與規則邏輯。對已經有 coding agent 的團隊來說，這通常比要求大家各自維護一份 review prompt 更容易治理。

從 CLI 走進 CI/CD

專案根目錄的 action.yml 提供 GitHub Action，能把 OpenCodeReview 接到 PR review 流程。Action 的輸入包括 LLM endpoint、model、認證資訊、review language、timeout、concurrency、規則檔，以及是否上傳 JSON 結果與 stderr artifact 等設定。

實務上可以分成兩階段導入：

觀察期：先輸出 JSON、保存 artifact，只把 finding 放到 summary 或報告中，讓團隊量測誤報率與平均延遲。
門禁期：確認規則、模型與 budget 穩定後，再依嚴重度把部分 finding 發佈成 inline comment，並保留人工覆核。

這裡不宜一開始就把 AI finding 當成硬性 merge blocker。OpenCodeReview README 自己也把 benchmark 的重點描述為偏高 precision、較低 recall 的取捨；這表示它更像「降低 review 噪音的輔助層」，而不是取代測試、靜態分析器與資深工程師判斷的單一閘門。

Benchmark 要怎麼讀？

README 公布的 AACR-Bench 包含 50 個熱門開源 repository、200 個真實 Pull Request、10 種程式語言，以及 80 多位資深工程師交叉驗證的 1,505 個標註問題。專案宣稱，在相同底層模型下，相較於一般用途 agent，OpenCodeReview 有更高的 precision 與 F1，約使用九分之一的 token，並能更快完成 review；同時 recall 較低，這是刻意偏向減少噪音的設計。

這些是專案 README 的自述結果，不是本文獨立重跑的實驗。閱讀時應特別注意三件事：測試資料是否符合自己的語言與 repository、模型與 prompt 是否相同，以及 precision/recall 與團隊真正關心的修復成本是否一致。最可靠的做法，是拿自己過去已由人工確認的 PR 建立小型 replay set，再比較 false positive、漏報、延遲與 token 成本。

內部實作與擴充面

從 repository 結構可以看出，OpenCodeReview 並非單一 CLI 檔案：

cmd/opencodereview：Cobra CLI、provider 設定、review、scan、delegate、session 與輸出格式。
internal/diff：Git diff 解析、hunk 與 comment relocation。
internal/agent：review unit 分組、檔案選擇與 agent 執行。
internal/scan：全檔案掃描的 batch、budget、provider 與 resume 邏輯。
internal/llm：OpenAI-compatible、Anthropic、Bedrock 等 LLM client 與 retry 邊界。
internal/mcp：MCP client 與外部工具整合。
internal/session：review session、歷史與結果保存。
internal/telemetry：OpenTelemetry metrics 與 traces。

go.mod 顯示專案以 Go 1.25.5 建置，並直接依賴 Anthropic SDK、OpenAI SDK、MCP Go SDK、Cobra 與 OpenTelemetry。這種拆分讓它有幾個適合工程團隊的擴充點：可以加入新的 provider、調整規則與檔案 allowlist、替換輸出或 telemetry exporter，而不必把所有邏輯塞進 prompt。

導入前的限制與風險

LLM 設定與成本仍然是必要前提

一般模式需要先設定 provider 與 model，review 內容也會送往設定的 LLM endpoint。API key 不應寫進 repository 或 CI log；應使用 secret manager，並先確認程式碼、設定檔與個資能否送到該 provider。若採用 delegation mode，則可由外部 coding agent 執行模型部分，但仍要理解該 agent 的資料流與權限。

高 precision 不等於完整覆蓋

偏向少噪音的工具可能漏掉部分真實問題。安全性、資料庫 migration、權限邊界等高風險變更，不應只靠 AI review。應與 compiler、unit test、SAST、dependency scanning 及人工審查並用。

Token budget 與延遲需要實測

分組與平行處理能改善大型變更的穩定性，但每個 review unit 仍可能觸發多輪 tool use。導入時要記錄每次 review 的檔案數、token、wall-clock time、重試次數與人工確認結果，再設定 concurrency、timeout 和 max token budget，而不是直接套用預設值。

專案仍在快速演進

本次查證時最新 release 為 v1.12.5，且 repository 在近期仍有更新。CLI flags、provider 行為與整合方式可能快速變化；正式導入應鎖定版本，並把 upgrade 放進可回滾的 CI 變更流程。

結語：把 agent 放在它擅長的地方

OpenCodeReview 值得注意的地方，不只是它能用 LLM 寫 code review comment，而是它把「流程正確性」與「語意判斷」拆開：檔案選擇、分組、規則匹配、定位與 session 管理由工程程式負責；模型則集中處理上下文理解與動態決策。

這是一個適合 AI 工程化的設計訊號：當 agent 要進入 CI/CD，不要只問模型夠不夠聰明，也要問哪些步驟可以被 deterministic 地約束、測試與重跑。對想把 AI review 從一次性 demo 推進到團隊流程的人，OpenCodeReview 提供了一個值得研究的 Go 實作案例；但是否適合正式擋 PR，仍應以自己的 replay set、成本資料與人工確認結果作最後判斷。