技术拆解 011｜OpenCodeReview：阿里开源混合架构代码评审工具——一半工程硬约束，一半 Agent 动态决策

2026 年 9 月 17 日，alibaba/open-code-review 登上 GitHub 热榜，单日新增 3,231 个 star，仓库总量到了 31.8k。这个增速在工具类项目里少见。它做的事一句话说清：读 Git diff，交给一个带工具调用能力的 Agent 去审，产出带行号的结构化评审意见。市面同类产品几十个，它的差异在架构主张——「确定性工程 × Agent 混合」：凡是「绝不能出错」的环节用工程逻辑锁死，凡是需要灵活判断的环节才交给模型。这篇文章按六件事拆：是什么、怎么装、架构拆到源码、Benchmark 怎么读、和通用 Agent 的差异、值不值得接入。

一、这是什么

OpenCodeReview 是阿里集团内部官方 AI 代码评审助手的开源版本，Go 为主实现，Apache 2.0 协议。README 自述：过去两年它在阿里内部服务数万开发者、发现数百万代码缺陷，属官方口径，先注明。全仓 858 个文件，其中 Go 文件 340 个、TypeScript 62 个、Python 8 个——Go 扛主进程与 Git 交互，TypeScript 在 vscode 扩展里，Python 零星分布在脚本侧。仓库还自带 plugins/ 目录、extensions/vscode 目录，以及两个 Agent skill 定义（open-code-review、open-code-review-delegate），说明它从第一天起就打算住进 Claude Code、Codex、Cursor 这类编码 Agent 的工作流里，而不是另起一个孤岛应用。

它的野心不在「又一个 AI 评审」，而在回答一个真问题：通用 Agent 做评审为什么总不稳。

二、怎么装怎么用

安装一条命令：

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

装完全局可用 ocr。除 npm 外还提供六平台预编译二进制（darwin、linux、win32 各分 arm64/x64）和 install 脚本。硬依赖只有一个：Git >= 2.41——diff 生成、代码搜索、仓库操作全压在 Git 上，版本不够直接拒跑。

首次使用先配模型：

ocr config provider    # 选内置服务商或加自定义端点
ocr config model       # 为当前服务商挑模型

评审命令围绕 Git 状态展开：

ocr review                                  # 工作区模式：审全部暂存、未暂存、未跟踪改动
ocr review --from main --to feature-branch  # 分支区间，按 merge-base 算
ocr review --commit abc123                  # 单个提交
ocr scan                                    # 无 diff 审计：整个文件扫描，审陌生代码库
ocr review --preview                        # 干跑：只看会审哪些文件，不烧 token

ocr scan 值得单独记一笔：它不依赖提交历史，直接审计整文件或整个目录，用途是接手陌生代码库时的第一轮体检。中断的评审可以 ocr session list 找回会话，--resume 续跑，长评审不白烧。

三、架构拆解：双引擎各管什么

这是全文重头。README 把设计原则写得很直白：「review steps that must not go wrong」由工程逻辑保证，不由语言模型保证。拆开源码，四件套加两件套每一环都能在代码里找到落点。

3.1 文件选择：一个纯函数锁死入口

internal/agent/selection.go 里的 selectFiles 是评审的唯一确定性入口：对每个改动文件依次套静态路径与扩展名门禁、删除文件检查、单文件 diff 的 token 上限，输出每个文件的裁决（审 / 不审 / 因为什么原因不审）。函数是纯的——不产生副作用、不碰 Git、不碰 LLM——所以 --preview 干跑和真实运行吃的是同一个答案，用户预览到的覆盖面就是实际覆盖面。通用 Agent 评审「大 changeset 偷懒漏文件」的毛病，在这一层被结构性堵死：模型还没上场，哪些文件该审已经定案。

3.2 文件打包：小组本地直分，大组才动模型

internal/agent/grouping.go 负责把相关文件拼成评审单元。设计上有三层节制。第一，小 change set 根本不发 LLM 请求：模板里的 GroupingPlan 按文件数和改动行数决定本地直分策略，几个文件直接打包成一组或逐文件派发，注释里写明理由是「too few files for the call to buy any information」——一次 LLM 往返买不到信息，就不花这个钱。第二，大 change set 交给模型分组，但回传的是索引而不是路径：prompt 里每个文件前面印 [i] 编号，模型只回 JSON 里的整数下标，注释说得很直白——一个索引花几个 output token，一条路径花它完整长度，输出体积缩一个量级，大 change set 不再被 completion 上限截断。第三，两道阀门兜底：maxFilesPerGroup = 10 把超限的组切碎，token 预算再砍一刀，任何一步失败统一回退成单文件分组——分组失败意味着每个文件至少被审到一次，只是失去「相关性同审」的收益。

「上下文隔离、可并发」的承诺也在这里兑现：每个 FileGroup 跑一次独立的子 Agent，组与组之间互不看见对方上下文，天然可以并行。

3.3 规则匹配：模板引擎，不靠自然语言叮嘱

internal/config/template/prompts/ 下按任务拆了一排模板：main、grouping、plan、re_location、review_filter、memory_compression，每个任务独立 system 加 user 两份。规则侧有 internal/config/rules/system_rules.json 做默认规则与按路径匹配的规则表，配合 allowlist 目录里的扩展名白名单、默认排除模式、密钥路径模式。规则是「哪类文件配哪类检查」的结构化数据，由模板引擎渲染进 prompt，而不是把要求写成一段自然语言指望模型牢记。README 的判断很硬：纯语言驱动的规则引导难调试、质量随 prompt 微调波动，模板引擎驱动的匹配「更稳定、更可预测」。评审输出还带结构化的 severity（critical 到 low）与 category（bug、security、performance 等），下游可按级别过滤——低级别误报多的问题在格式层就被允许丢弃。

3.4 评论定位与反思：两级重试，失败回滚

评论位置漂移是通用 Agent 评审的第二大痛点，OpenCodeReview 把它拆成两级。第一级在 internal/diff/resolver.go：每条评论带着模型给出的 ExistingCode 片段，先拿它在 diff hunk 里做文本匹配定行号，匹配不上再降级扫全文件逐行比对。第二级在 relocation.go：两级文本匹配都失败后，再调一次 LLM，把原始 diff、现有片段、建议内容一起塞进 re_location 模板，让模型重新生成一个精确代码块，然后拿新片段重试解析；重试仍失败就把 ExistingCode 回滚成原文，宁可这条评论定位失败也不写错行号。「外部定位加反思模块」在源码里就是这么朴素的两级重试加回滚。所谓反思，对应的是模板目录里的 review_filter 任务：一轮评审产出后，再过一次过滤，把站不住的评论拦在输出之前。定位管「评论钉在哪一行」，反思管「这条评论配不配得上输出」，两件事都被拆成独立任务、独立模板，互不掺水。

3.5 Agent 侧：prompt 深调，工具集从生产 trace 蒸馏

模型被允许发挥的只有两件事：动态决策和动态取上下文。prompt 是按评审场景深调的模板，官方口径是效果更好且省 token。工具集（读全文件、代码搜索、看同 change set 的其他文件）宣称从大规模生产的 tool-call trace 里蒸馏出来——分析调用频率分布、单工具重复率、新工具对整条调用链的影响，再裁出一份为评审专用的工具清单。这部分源自内部生产数据的结论属官方口径，外部无法复核，但它解释了为什么 token 消耗能压到通用 Agent 的约九分之一：工具少而专用，每次调用的目的性强，绕路少。

四、Benchmark 怎么读

官方 benchmark 叫 AACR-Bench：50 个开源仓库、200 个真实 PR、10 种语言，80 多位资深工程师交叉验证，标出 1,505 条真值问题，数据集开放在 HuggingFace（Alibaba-Aone/aacr-bench）。对比对象是同底模的 Claude Code，结论三个：Precision 和 F1 显著更高，token 消耗约 1/9，速度更快。README 同时主动交代 Recall 更低——「宁精勿噪」的刻意取舍。

这组数字要读对。第一，它对比的是「通用 Agent 加 skill」形态，不是裸模型，赢面来自工程硬约束把覆盖和定位钉死，属于架构胜利而非模型胜利。第二，Recall 更低意味着漏报更多，适合评审主战场是「减少误报噪音、节省资深工程师 triage 时间」的团队；如果场景是宁可多报不可漏报，这条曲线方向相反。第三，1,505 条真值、80 人交叉验证在评测规模上是认真的，但构建方是阿里自己，标注口径难免偏向自家工具的强项，第三方复现前按「官方口径」对待。这套取舍逻辑本身值得记住：用 Precision 换 Recall，省的是人的注意力，烧的是模型的覆盖率——对 CI 门禁场景，这个交易几乎总是划算的。

五、与通用 Agent 评审的差异

把差异压成一张表：

维度	通用 Agent 评审（Claude Code 等）	OpenCodeReview
覆盖保证	模型自由裁量，大 change set 易漏文件	纯函数选择，覆盖面与 preview 一致
评论定位	模型直报行号，易漂移	文本两级匹配 + LLM 重生成 + 失败回滚
规则方式	自然语言 skill，难调试	模板引擎 + 结构化规则数据
上下文	单一大上下文	按相关性分组，子 Agent 隔离、可并发
工具	通用全套	从生产 trace 蒸馏的评审专用集
token	基线	官方口径约 1/9

差异的本质是哲学分歧：通用 Agent 相信模型能管好全流程，OpenCodeReview 相信凡是能写成代码的约束就不要交给概率。代价也在这张表里——架构绑死了评审这一个场景，通用 Agent 顺手能做的事（改代码、跑测试、写总结）它不做。注意它给出的解法不是硬扛，而是 delegate 模式：把文件选择和规则匹配这两件它擅长的事做完，剩下的执行外包回给你正在用的编码 Agent，两边各干各的强项。这个姿态很聪明——不与通用 Agent 争长短，争的是「谁来做裁判」。

六、值不值得用

按人群分。团队 CI 接入是最顺的场景：diff 驱动、Git 是唯一硬依赖、输出结构化 JSON 可直接喂给门禁或评论机器人，--preview 让成本可预期，中断可续跑，token 只有通用 Agent 的约九分之一意味着同样预算能审更多 PR。个人开发者配一个模型端点就能跑工作区评审，装完即用。已经在用 Claude Code、Codex、Cursor 的人，仓库自带的 skill 和插件目录让 ocr 可以嵌进现有工作流，不需要迁移习惯。

暂缓的情形也清楚：需要「宁可错杀」式高召回审计的安全合规场景，它的低 Recall 是反向指标；想用一个工具同时完成评审加修复的，它不是那个工具；对阿里自报的内部战绩和 benchmark 数字，在第三方复现出现前保持折扣阅读。规则侧「支持多语言规则与多家模型接入」的表述以仓库文档为准，具体规则清单未逐项核对。

结论

OpenCodeReview 的 31.8k star 和单日 3,231 增长，对应的是一条被反复验证的工程常识：LLM Agent 做垂直任务，胜负手往往不在模型，在哪些环节敢用确定性代码锁死。文件选择是纯函数，文件打包先本地后模型、回传索引不传路径、两道阀门加失败回退，规则匹配走模板引擎，评论定位是两级重试加失败回滚——四件套的每一环都在源码里站得住。Agent 只留动态决策和动态取上下文，换来官方口径下约 1/9 的 token 和更高的 Precision，代价是更低的 Recall。对想把 AI 评审接进 CI 的团队，这是目前最完整的开源答案之一；对研究 Agent 架构的人，它是一份可以直接读的「混合架构」教科书。

参考来源

• alibaba/open-code-review README（GitHub；What is / Benchmark / Why / How to Use / Quick Start 各段）
• OpenCodeReview 源码（本地 clone，main 分支）：internal/agent/selection.go、internal/agent/grouping.go、internal/config/rules/system_rules.json、internal/config/template/prompts/、internal/diff/resolver.go、internal/diff/relocation.go、skills/open-code-review/SKILL.md
• AACR-Bench 数据集（HuggingFace，Alibaba-Aone/aacr-bench；README 官方口径）
• 仓库数据：31.8k star、单日 +3,231（用户提供，2026-09-17）