實戰指南:讓宿主 Agent 用自己的 LLM 完成代碼審查)
OpenCode Review 委托模式Delegation Mode實戰指南讓宿主 Agent 用自己的 LLM 完成代碼審查【免費下載鏈接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.項目地址: https://gitcode.com/GitHub_Trending/op/open-code-review本文檔為委托模式Delegation Mode的完整技術指南。委托模式是 OpenCode ReviewOCR為訂閱制 AI 編碼 Agent 設計的一種集成方式OCR 只負責文件篩選、規則解析等確定性工程實際的代碼審查推理由宿主 Agent如 Claude Code、Codex、Cursor、Open Code、Qoder借助其自身的 LLM 訂閱額度完成OCR 側完全不調用任何 LLM 端點。讀完本文你將掌握ocr delegate preview/ocr delegate rule兩個子命令的完整用法、共享 flag 的語義與限制、JSON 輸出契約以及如何把委托模式接入自己的 Agent 工作流。什么是委托模式OCR 做腳手架Agent 做審查在 OCR 的三種集成模式中委托模式是唯一一種「LLM 調用方」不在 OCR 側的模式模式誰調用 LLM典型使用場景Agent SkillOCRAgent 調用ocr reviewOCR 驅動完整審查流程Command (Claude Code)OCRClaude Code 中的斜杠命令OCR 驅動審查委托模式Delegation Mode宿主 AgentOCR 提供腳手架Agent 驅動審查委托模式的設計動機非常直白如果你已經在使用按訂閱付費的 AI 編碼 Agent那么與其再為 OCR 單獨配置一套模型端點ocr config set …或環境變量不如直接復用宿主 Agent 已有的訂閱額度。OCR 退居幕后只輸出兩份「審查規格」review specocr delegate preview—— 決定審什么輸出審查模式、ref 元數據和可審查文件清單ocr delegate rule path...—— 提供審查依據為文件清單解析出按內容分組的審查規則。從源碼結構看委托模式在 cmd/opencodereview/delegate_cmd.go 中被實現為delegate命令下的兩個子命令其 Long 描述直接點明了設計意圖“Output review spec for host-agent delegation (no LLM required)”。何時使用委托模式委托模式針對以下三類場景設計你的 AI 編碼 Agent 是訂閱制希望復用已有配額做代碼審查——無需額外 API Key 或模型配置你只想讓 OCR 提供工程腳手架文件過濾、規則解析、排除邏輯LLM 推理全部交給宿主 Agent你在構建自定義 Agent 流水線需要一個結構化的輸入文件清單 規則來驅動自己的審查步驟。前置條件只需安裝ocrCLI無需任何 LLM 配置which ocr || npm install -g alibaba-group/open-code-review委托模式在 OCR 側從不調用 LLM因此不需要ocr config set …也不需要設置任何模型相關的環境變量。這一點在 skills/open-code-review-delegate/SKILL.md 的compatibility字段中有明確聲明“Does NOT require a configured LLM endpoint — delegation mode is LLM-free on the OCR side”。安裝 Skill / CommandClaude Code —— Command 方式mkdir -p .claude/commands curl -o .claude/commands/delegate-review.md \ https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md安裝后Claude Code 中即可通過該命令觸發委托模式。命令的 manifest 位于 plugins/open-code-review/claude-code/commands/delegate-review.md其中內置了完整的五步工作流指引先ocr delegate preview拿到模式/ref 元數據再ocr delegate rule獲取規則清單然后按模式構造 git diff 命令逐個文件審查最后按嚴重級別分類并自動修復 High/Medium 問題。任意 Agent —— Skill 方式推薦使用 skills CLI 安裝npx skills add alibaba/open-code-review --skill open-code-review-delegate也可以手動拷貝 manifestcp -R /path/to/open-code-review/skills/open-code-review-delegate ~/.claude/skills/Skill 的完整定義在 skills/open-code-review-delegate/SKILL.md它是一個純指令型 skill不依賴任何外部工具調用只是把「預覽 → 取規則 → 取 diff → 審查 → 報告」這一套協議寫清楚讓宿主 Agent 照著執行。工作流五步完成委托審查Step 1Preview —— 確定要審查什么ocr delegate preview [--from ref --to ref] [--commit hash] [--exclude patterns]輸出內容包括mode—— workspace / range / commit 三種之一ref 元數據—— from、to、commit、merge_base可審查文件清單—— 路徑、狀態、增刪行數被排除文件—— 附排除原因。常用調用方式場景命令工作區改動ocr delegate preview分支對比ocr delegate preview --from main --to feature單個提交ocr delegate preview -c abc123模式判定邏輯從 delegate_cmd.go 的reviewMode()實現可以看到三種模式的優先級是commitrangeworkspace只要提供了--commit就是 commit 模式否則若--from與--to同時給出則是 range 模式兩者都沒有則為 workspace 模式。對應的組合校驗在 delegate_helpers_test.go 的TestValidateDelegateOptions中覆蓋from缺to、to缺from、commit 與 range 混用都會被拒絕。merge_base 的計算range 模式下mergeBase()見 delegate_cmd.go通過diff.NewProvider計算兩個 ref 的合并基點并寫入輸出。這個merge_base正是 Step 3 構造git diff命令的關鍵參數其他模式下它為空字符串。安全性loadDelegateContext在加載上下文時會調用validateReviewRefs拒絕 ref 選項注入見 delegate_cmd.go防止通過--from/--to/--commit注入惡意參數。無副作用保證preview 既不運行也不落盤審查會話。測試 delegate_exec_test.go 中的TestExecuteDelegatePreviewCreatesNoSession專門斷言preview 之后~/.opencodereview/sessions目錄不會被創建——因為 preview 階段根本沒有打開持久化。Step 2獲取文件規則ocr delegate rule path1 path2 ...把 Step 1 輸出的可審查路徑作為參數傳入。輸出按規則內容分組共享同一條規則的文件會歸入同一組避免重復輸出。分組算法位于 internal/delegate/rulegroup.go 的GroupRules它要求sourcecustom/project/global/system、matched pattern、規則文本三者完全一致才歸為同一組以source\x00pattern\x00text作為分組 key。也就是說兩條規則文本完全相同但來源不同的文件例如分別命中項目規則和系統默認規則會留在不同的組從而保證每組內Source/Pattern元數據對每個文件都準確。Markdown 輸出由 internal/delegate/format.go 的RuleGroupsMarkdown渲染每個組以### Rule Group N: source / pattern標題開頭列出適用文件后給出#### Content規則正文組之間以---分隔。對應的渲染斷言見 internal/delegate/format_test.go。Step 3獲取 Diff根據 Step 1 的 mode / ref 信息直接用 git 取 diffRange 模式preview 輸出中提供了 merge_basegit diff merge_base..to -- pathCommit 模式git show commit -- pathWorkspace 模式git diff HEAD -- path # 已跟蹤文件 cat path # 新增的未跟蹤文件注意 workspace 模式下preview 會把未跟蹤文件一并納入清單對于這些文件git diff 拿不到內容直接讀取文件本身即可整個文件都是新代碼。Step 4逐個文件審查對每個可審查文件獲取其 diffStep 3對照其所屬 Rule Group 的規則正文Step 2作為審查清單結合上下文探索工具進行徹底審查只評論變更行 行。審查維度建議覆蓋正確性、安全性、性能、錯誤處理、并發、可維護性。對于大型變更按共享規則與 diff 大小分批處理不要在發現第一個 High 級問題后就停止。Step 5報告按嚴重級別分類每個發現Critical/High—— bug、安全問題、數據丟失風險。必須報告Medium—— 性能隱患、錯誤處理缺口、可維護性問題。帶上上下文報告Low—— 風格 nit、小建議。除非明顯有價值否則靜默丟棄。Skill 對輸出格式有更嚴格的要求見 SKILL.md每條評論應遵循path / content / start_line / end_line / category / severity字段結構其中category取值于bug, security, performance, maintainability, test, style, documentation, otherseverity取值于critical, high, medium, low。報告前必須核對每個 preview 文件都已覆蓋reviewed 或帶原因的 skipped并在總結中給出total_files、reviewed_files、skipped_files、coverage_rate。子命令參考命令用途ocr delegate preview列出可審查文件 mode/ref 元數據ocr delegate rule path...按內容分組的審查規則解析兩個子命令共享同一套 flag 注冊邏輯registerDelegateFlags見 cmd/opencodereview/shared_flags.go。共享 FlagsFlag說明--from refrange 模式的源 ref--to refrange 模式的目標 ref-c, --commit hash單提交模式--repo path倉庫根目錄默認當前目錄 cwd--rule path自定義 rule.json 路徑--exclude patterns逗號分隔的排除模式-b, --background text業務上下文-B, --background-file path從 Markdown 文件讀取業務上下文優先于-b--max-git-procs最大并發 git 子進程數默認 16源碼注冊于 shared_flags.go-f, --format text\|json輸出格式Agent 集成請用json幾點需要注意的語義細節--background-file優先于-b測試 delegate_exec_test.go 的TestLoadDelegateContext_BackgroundFile驗證了同時傳入兩者時文件內容勝出、內聯文本被忽略。背景上下文有雙重上限原始文件不得超過 1 MiB凈化后的內容不得超過 8000 字符任一超限都會中止命令。正確的恢復姿勢是先總結再重試不要靜默截斷源文件而是把原文總結成保留需求、約束、驗收標準的精簡文本作為單個 shell 安全參數傳入或用新的小文件傳入并且不要再傳--background-file若無法忠實總結就直接省略 OCR 背景在審查時自行閱讀原文。--format json需要ocrv1.9.0如果preview/rule報unknown flag: --format說明 CLI 版本過舊去掉該 flag 改用文本輸出繼續跑完委托流程即可不要解析文本當 JSON也不要為其他錯誤去掉 flag 重試。需要schema_version等 JSON 字段的程序化集成應先用ocr --version確認版本必要時npm install -g alibaba-group/open-code-review升級。這個降級與升級策略在 SKILL.md 的 Troubleshooting 一節有完整說明。sarif格式不被委托模式支持validateDelegateOptions只接受text與json見 delegate_helpers_test.go 中{sarif format not supported by delegate, ..., true}用例flag 的 completion 也只提供這兩個枚舉值。JSON 輸出契約Agent 集成要點給 Agent 集成時使用--format json。preview的輸出封套定義于 delegate_cmd.go字段包括schema_version—— 當前為1常量delegateSchemaVersionmode—— workspace / range / commitrepository、from、to、commit、merge_base、backgroundtotal_files、reviewable_count、excluded_counttotal_insertions、total_deletionsreviewable_files[]/excluded_files[]—— 每個條目含path、status、insertions、deletions被排除的條目還帶exclude_reason。rule的輸出封套delegate_cmd.go包含schema_version與groups[]每組含group_id、source、pattern、files、rule。測試 delegate_exec_test.go 對 JSON 契約做了斷言JSON 數組必須是非 null 的空數組reviewable_files/excluded_files不能為 nullfiles同樣必須序列化為[]而不是null方便下游程序化消費。writeDelegateJSON使用帶縮進、不轉義 HTML 的編碼器輸出保證可讀性。與其他集成模式的取舍回到開頭的對比表三種模式的本質區別在于「誰在調用 LLM」Agent Skill 模式OCR 驅動完整審查ocr review由 OCR 調用 LLM需要配置模型端點Claude Code Command 模式斜杠命令形式同樣是 OCR 驅動審查且帶自動修復能力委托模式OCR 只做確定性工程LLM 推理完全由宿主 Agent 承擔OCR 側零 LLM 配置。如果你的團隊已經在使用訂閱制 AI 編碼工具且希望審查邏輯與主開發 Agent 保持同一套「智能」委托模式是最省配置的集成路徑如果希望審查獨立于任何特定 Agent、可復現可審計則應選擇 OCR 自驅的 Agent Skill 或 Command 模式。更詳細的對比可參見 Agent Skill 與 Command (Claude Code) 兩篇文檔。【免費下載鏈接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.項目地址: https://gitcode.com/GitHub_Trending/op/open-code-review創作聲明:本文部分內容由AI輔助生成(AIGC),僅供參考