OpenCodeReview 架构拆解：AI Code Review 为什么不能只是 Git Diff + LLM？

随着 Claude Code、Codex 这类 Coding Agent 的能力越来越强，现在让 AI 帮我们做 Code Review 已经不是什么新鲜事了。

最简单的实现甚至只需要几十行代码：

makefile 复制代码

diff = git_diff()

result = llm.chat(
    f"""
    请 Review 以下代码修改，
    找出 Bug、安全风险和性能问题：

    {diff}
    """
)

整体流程看起来也非常简单：

flowchart LR A[Git Diff] --> B[构造 Prompt] B --> C[LLM] C --> D[Review Result]

对于一个只修改十几行代码的小 PR，这种方式可能已经够用了。

但当 Code Review 真正进入大型项目、多人协作和 CI/CD 流程以后，问题很快就会出现：一个 PR 修改几十个文件时，模型是否真的认真检查了每一个文件？Java、SQL、配置文件是否应该使用同一套 Review 规则？某个 Bug 需要读取没有发生修改的代码才能判断时怎么办？模型发现的问题如何精确定位到 GitHub PR 的某一行？

这些问题说明，真正的 Code Review 并不是简单的一次 Prompt 调用，而是一条完整的工程 Workflow。

最近 Alibaba 开源的 OpenCodeReview 就在尝试解决这个问题。研究这个项目以后，我认为它真正值得关注的并不是"又多了一个 AI Code Review 工具"，而是它背后体现出来的一套 Agent Engineering 思路：

能够通过确定性程序解决的问题，就不要交给 LLM；只有真正需要代码语义理解和动态判断的部分，才交给 Agent。

这也是本文真正想讨论的内容。

一、为什么 Git Diff + LLM 不够？

假设一个真实的 PR 修改了下面这些文件：

matlab 复制代码

src/
├── controller/
│   └── UserController.java
├── service/
│   └── UserService.java
├── repository/
│   └── UserRepository.java
├── mapper/
│   └── UserMapper.xml
├── config/
│   └── application.yml
└── i18n/
    ├── messages_zh.properties
    └── messages_en.properties

如果直接把整个 Git Diff 丢给模型，LLM 实际上不仅需要理解代码，还需要顺便解决一系列 Workflow 问题：哪些文件值得重点检查、哪些文件之间存在关联、不同类型文件应该应用什么规则、当前上下文是否足够，以及最终问题应该定位在哪一行。

整个过程实际上更接近下面这样：

flowchart TD A[Git Diff] --> B{哪些文件需要 Review} B --> C{哪些文件之间存在关联} C --> D{当前文件应该使用什么规则} D --> E{当前上下文是否足够} E -->|不够| F[搜索相关代码] F --> E E -->|足够| G[分析代码问题] G --> H{问题应该定位在哪里} H --> I[输出 Review Result]

这里真正需要 LLM 推理能力的，主要是代码语义理解、Bug 判断、安全风险分析以及上下文是否充分等问题。

而另外一些事情，比如文件类型识别、文件路径检查、Review Scope、规则匹配、JSON Schema 校验、行号合法性验证，本身都是确定性问题。如果这些同样交给 LLM，就相当于把原本确定的问题重新变成了概率问题。

这也是很多 Agent 系统不稳定的根源之一。

二、OpenCodeReview 真正解决的是什么？

OpenCodeReview 可以读取 Git Diff，让具备 Tool Calling 能力的 Agent 对代码进行分析，并生成结构化 Review Comment。Agent 在分析过程中不仅能看到 Diff，还可以根据需要继续读取完整文件、搜索 Repository 中的其他代码，以及补充关联上下文。

如果只看功能，它和很多 AI Review 工具似乎差别不大。但 OpenCodeReview 更值得研究的地方是它采用了一种 Hybrid Architecture，也就是：

Deterministic Engineering × LLM Agent

可以简单理解为：确定性工程负责建立 Workflow、边界和校验机制，而 LLM 只负责真正需要语义理解的部分。

整个流程可以抽象为：

flowchart TD A[Git Repository] --> B[Git Diff / Scan] B --> C[Review Scope] C --> D[File Filtering] D --> E[File Bundling] E --> F[Rule Resolution] F --> G1[Review Bundle 1] F --> G2[Review Bundle 2] F --> G3[Review Bundle N] G1 --> H1[LLM Agent] G2 --> H2[LLM Agent] G3 --> H3[LLM Agent] H1 --> I[Structured Comments] H2 --> I H3 --> I I --> J[Positioning] J --> K[Reflection / Validation] K --> L[Final Review Result] L --> M1[CLI] L --> M2[JSON] L --> M3[PR Comments]

这里有一个非常关键的细节：LLM 并没有出现在整个 Workflow 的最前面。

在 Agent 开始推理之前，系统已经完成了 Review Scope、File Filtering、File Bundling 和 Rule Resolution 等工作；Agent 输出结果以后，也不是直接交给 GitHub，而是继续经过结构校验、位置处理和结果验证。

因此 OpenCodeReview 的核心思路可以概括成一句话：

不是让 LLM 驱动 Workflow，而是让 Workflow 驱动 LLM。

三、Review Scope：大型 PR 不应该只有一个巨大 Prompt

大型 PR 对 AI Review 最大的挑战之一，就是 Context。

假设一次提交修改了 40 个文件，最简单的方案通常是把全部 Diff 拼到一起：

flowchart LR A[40 Changed Files] --> B[Huge Prompt] B --> C[LLM] C --> D[Review Result]

这样虽然实现简单，但随着 Context 增大，很容易出现 Attention 被稀释、Token 消耗增加、重要文件被忽略以及不同 Review 规则互相干扰的问题。

OpenCodeReview 更接近一种 Divide and Conquer 的思路：先确定 Review Scope，再将相关文件组织成多个 Review Bundle，每个 Bundle 分别进入独立的 Agent Context。

flowchart TD A[40 Changed Files] --> B[Scope Detection] B --> C[File Filtering] C --> D1[Bundle A] C --> D2[Bundle B] C --> D3[Bundle C] C --> D4[Bundle D] D1 --> E1[Sub Agent] D2 --> E2[Sub Agent] D3 --> E3[Sub Agent] D4 --> E4[Sub Agent] E1 --> F[Merge Results] E2 --> F E3 --> F E4 --> F

例如下面两个国际化资源文件：

matlab 复制代码

messages_zh.properties
messages_en.properties

如果分别 Review，模型可能只会判断两个文件本身是否存在语法错误；但如果它们被放进同一个 Bundle，模型就更容易发现中文文件新增了 user.login.failed，英文资源文件却没有同步增加的问题。

所以这里的 Multi-Agent 并不是为了让多个 Agent 相互讨论，而是利用任务拆分来隔离 Context。

这也是我认为 Multi-Agent 在工程系统里真正有价值的一个方向：

通过任务边界控制上下文，而不是简单增加 Agent 数量。

四、AI Code Review 真正困难的是 Context Engineering

很多人会把 AI Code Review 的效果差异归因于模型能力，比如 GPT 是否更强、Claude 是否更适合代码、Reasoning Token 是否足够。

这些当然重要，但真实工程场景中的另外一个关键因素是：模型到底拿到了什么 Context。

假设 Diff 中只有这样一段代码：

kotlin 复制代码

public UserVO getUser(Long id) {
    return userService.getUser(id);
}

仅仅通过这一行代码，模型其实无法判断它是否存在真正的问题。

它可能还需要知道 UserService#getUser 的实现、id 是否允许为空、Repository 在查询失败时返回什么、UserVO 在哪里转换，以及这个接口本身是否需要权限校验。

因此一次真正有效的 Review，输入往往并不是单纯的 Git Diff，而是：

flowchart LR A[Git Diff] --> F[Review Context] B[Current File] --> F C[Related Files] --> F D[Review Rules] --> F E[Business Background] --> F F --> G[LLM Agent] G --> H[Review Result]

OpenCodeReview 的 Agent 可以在分析过程中根据需要继续搜索 Repository 和读取其他代码，因此整个过程更接近动态 Context Retrieval：

rust 复制代码

sequenceDiagram
    participant O as OpenCodeReview
    participant A as Review Agent
    participant R as Repository
    participant L as LLM

    O->>A: Diff + Rule + Background
    A->>L: 分析当前修改
    L-->>A: 当前上下文不足
    A->>R: Search / Read Related Code
    R-->>A: 返回相关代码
    A->>L: 补充 Context 后继续分析
    L-->>A: 输出候选问题
    A-->>O: Structured Comment

这里实际上体现了一种非常典型的 Context Engineering 思路。

与其把整个 Repository、所有 Diff、全部 Rule 一次性塞进 Prompt，不如先过滤、路由和拆分，只向模型提供当前任务真正需要的信息。

flowchart TD A[Large Context] --> B[Filter] B --> C[Route] C --> D[Bundle] D --> E[Relevant Context] E --> F[LLM]

这也是为什么在很多 Agent 系统里，Relevant Context 往往比 Maximum Context 更重要。模型能力决定了推理上限，而 Context Engineering 决定系统能不能稳定接近这个上限。

五、为什么不能只写一个超级 Review Prompt？

另外一种很常见的实现方式，是把所有 Review 规则全部写进同一个 Prompt：

markdown 复制代码

请检查：

1. 空指针
2. SQL Injection
3. XSS
4. 内存泄漏
5. 并发安全
6. React Hook
7. 数据库事务
8. REST API
9. GraphQL
10. Terraform
11. Kubernetes
...

问题在于，当模型正在 Review 一个 Java 文件时，React Hook、CSS、Terraform、GraphQL 等规则都只是额外噪声。Prompt 越长，并不代表模型会 Review 得越好。

OpenCodeReview 使用的是更接近 Rule Routing 的方式，根据文件路径和类型解析当前真正需要的 Review Rule：

flowchart TD A[Changed File] --> B{File Type / Path} B -->|Java| C[Java Rules] B -->|Mapper XML| D[SQL / Mapper Rules] B -->|TypeScript| E[TypeScript Rules] B -->|Terraform| F[Terraform Rules] B -->|Proto| G[Protocol Rules] C --> H[Review Agent] D --> H E --> H F --> H G --> H

项目还可以定义自己的 Review Rule，例如：

json 复制代码

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "新增接口需要重点检查参数空值、异常处理以及事务边界"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "重点检查 SQL 注入、参数映射错误以及查询性能"
    }
  ]
}

这种设计和 RAG 中的 Routing 很相似。与其把所有知识全部塞给模型，不如先判断当前任务需要什么，再把相关规则提供给 Agent。

最终得到的收益不仅是减少 Token，更重要的是减少无关信息对模型 Attention 的干扰。

六、不要完全相信 LLM 输出

假设 Agent 返回下面这样的结果：

json 复制代码

{
  "path": "src/UserService.java",
  "start_line": 128,
  "end_line": 128,
  "severity": "high",
  "category": "bug",
  "content": "这里可能产生空指针异常"
}

这并不意味着系统可以立刻把这条评论提交到 GitHub。

还需要继续确认几个问题：这个文件是否真的存在？路径是否位于当前 Repository 中？第 128 行是否属于当前 Diff？severity 是否属于允许值？返回结构是不是符合预期 Schema？

因此生产环境中的 Agent 输出应该被当成 Untrusted Input。

OpenCodeReview 对应的处理方式可以抽象成：

flowchart LR A[LLM Output] --> B[Schema Validation] B --> C[Path Validation] C --> D[Line Range Check] D --> E[Positioning] E --> F[Reflection] F --> G[Final Comment]

这其实是一条很通用的 LLM 应用设计原则：

css 复制代码

Input Validation
        ↓
       LLM
        ↓
Output Validation
        ↓
Production System

LLM 可以负责推理，但不应该天然拥有系统信任。

这一点不仅适用于 Code Review，也适用于 RAG、Data Agent、Research Agent、Coding Agent 等任何最终需要产生真实系统行为的场景。

七、为什么 Comment Positioning 值得单独做？

AI Code Review 还有一个很容易被忽略的问题：发现正确的问题，并不等于能生成正确的 PR Comment。

假设模型判断：

复制代码

UserService.java 第 73 行可能产生 NPE

但实际发生问题的位置是第 76 行。

如果只是 ChatGPT 里的普通聊天，这种偏差可能问题不大；但如果 AI 正在 GitHub PR 中自动添加 Inline Comment，那么评论挂错行会明显降低开发者的信任。

因此 Problem Detection 和 Problem Positioning 本身就是两个不同的问题：

flowchart TD A[LLM 发现问题] --> B[生成候选 Comment] B --> C[Positioning] C --> D{能否精确定位} D -->|Yes| E[Line-level Comment] D -->|No| F[General Comment] E --> G[Final Review] F --> G

专业 AI Code Review 系统与"让 Coding Agent 顺便看一下代码"的差距，很多时候并不只存在于模型能力本身，也存在于这些看起来并不起眼的工程环节。

八、Business Context 也是 Review Context

只理解代码本身，有时候仍然无法完成真正的 Code Review。

例如需求明确规定：

复制代码

只有管理员才能删除用户。

开发者实现了：

less 复制代码

@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    userService.delete(id);
}

如果只从代码语法和调用链来看，这段代码可能完全没有问题。但如果结合 Requirement，就会发现权限校验被遗漏了。

所以 Code Review 的目标不应该只是判断：

复制代码

这段代码有没有 Bug？

而应该进一步判断：

复制代码

这段代码是否正确实现了需求？

OpenCodeReview 支持把 Business Background 作为 Review Context 提供给 Agent。例如：

arduino 复制代码

ocr review \
  --background "新增管理员删除用户能力，普通用户禁止调用"

此时 Review Agent 获得的不再只是 Code Context，还包含 Requirement Context。

这其实非常接近未来 Coding Agent 的质量验证方式：真正高质量的 Review 不应该只验证"代码能不能运行"，还应该验证"代码是不是实现了我们原本想实现的东西"。

九、Delegation Mode：专业工具未必还需要自己运行一个完整 Agent

OpenCodeReview 中另一个很有意思的方向是 Delegation Mode。

传统模式下，OpenCodeReview 自己负责 Workflow、Agent Runtime 和 LLM 调用：

flowchart TD A[Developer] --> B[OpenCodeReview] B --> C[Review Workflow] C --> D[OCR Agent] D --> E[LLM] E --> F[Review Result]

但今天很多开发者本身已经在使用 Claude Code、Codex、Cursor 等 Coding Agent。这些宿主 Agent 已经具备 LLM、Tool Calling、Repository Context 和 Agent Loop，再让每一个专业工具重新实现一套 Agent Runtime，可能会产生大量重复能力。

Delegation Mode 的思路则是让 OpenCodeReview 只负责自己真正专业的部分，比如文件筛选、Rule Resolution、Review Scope 和 Context 组织，再把结构化任务交给宿主 Coding Agent。

css 复制代码

flowchart TD
    A[Codex / Claude Code] --> B[OpenCodeReview]

    B --> C[File Selection]
    B --> D[File Exclusion]
    B --> E[Rule Resolution]

    C --> F[Structured Review Context]
    D --> F
    E --> F

    F --> G[Host Coding Agent]
    G --> H[Host LLM]
    H --> I[Review Result]

在这种模式下，OpenCodeReview 更像一个 Review Harness，而 Codex 或 Claude Code 提供统一的智能能力。

这可能代表了一种值得关注的 Agent 工具形态：专业工具不一定需要自己实现完整的 Planner、Memory、Tool Loop 和 LLM Runtime，而可以集中建设更有领域价值的 Domain Workflow、Rules、Tools、Validation 和 Observability。宿主 Agent 则统一提供 Reasoning、Planning 和 Tool Orchestration。

最终整个生态可能会变成：

css 复制代码

flowchart TD
    A[Host Coding Agent]

    A --> B[Review Harness]
    A --> C[Test Harness]
    A --> D[Security Harness]
    A --> E[Research Harness]

    B --> F[Code Review Tooling]
    C --> G[Test Framework]
    D --> H[Security Scanner]
    E --> I[Search / RAG]

相比"每个工具自己再造一个 Agent"，这种方式可能更容易形成稳定的 Agent Tool Ecosystem。

十、Skill 不只是 Prompt，更像 Workflow Contract

OpenCodeReview 可以接入 Codex、Claude Code、Cursor 等 Coding Agent，而它提供的 Skill 也不仅是在告诉模型"你是一个 Code Reviewer"。

更准确地说，Skill 描述的是一套执行流程：什么时候应该调用 OCR、执行之前需要准备什么 Context、Review 结果应该如何处理，以及用户要求修复问题时应该执行什么后续动作。

可以抽象成：

flowchart TD A[User: Review my changes] --> B[检查 OCR CLI] B --> C[准备 Review Context] C --> D[提取 Business Background] D --> E[运行 OCR] E --> F[读取 Structured Result] F --> G[按 Severity 分类] G --> H{用户是否要求修复} H -->|Yes| I[Fix] H -->|No| J[Report]

从这个角度看，Skill 正在从传统意义上的 Prompt，逐渐演变成 Agent 的 Workflow Contract。

它不仅定义"模型应该以什么身份回答"，还在定义执行顺序、工具使用方式、失败路径、输出格式以及权限边界。

这比单纯的 System Prompt 更接近真正的软件工程。

十一、CI/CD 才是 AI Code Review 真正工程化的地方

如果 Code Review 的使用方式仍然是：

css 复制代码

打开 Claude Code
→ 手动输入「帮我 Review」
→ 看结果

那么它更多还是一个个人效率工具。

当 AI Code Review 真正进入软件工程体系以后，它应该成为 Software Delivery Pipeline 的一部分：

flowchart TD A[Developer Push] --> B[Create / Update PR] B --> C[GitHub Actions] C --> D[OpenCodeReview] D --> E[Review Diff] E --> F[Structured Result] F --> G[Inline PR Comments] G --> H[Developer Fix]

OpenCodeReview 可以直接 Review Workspace Changes：

复制代码

ocr review

也可以比较两个 Branch：

css 复制代码

ocr review \
  --from main \
  --to feature-branch

或者 Review 某个 Commit：

css 复制代码

ocr review \
  --commit abc123

机器消费结果时，可以直接输出 JSON：

css 复制代码

ocr review \
  --from main \
  --to feature-branch \
  --format json

这样 AI Review 才从一个可选的聊天工具，逐渐变成 CI Pipeline 中真正的 Quality Gate。

十二、Code Review 并不是发现的问题越多越好

OpenCodeReview 官方也提供了自己的 Benchmark。官方测试结果显示，在使用相同底层模型时，相比通用 Coding Agent，它更倾向于获得更高的 Precision 和 F1，同时降低 Token 消耗，但 Recall 会有所下降。

这里先不讨论 Benchmark 是否能够覆盖所有真实项目，这个结果本身体现了一种很值得思考的产品取舍。

Code Review 并不是发现的问题越多越好。

假设 AI 每个 PR 都输出 30 个问题，但里面只有两个真正重要，其余都是 Style Suggestion、边缘问题和误报，开发者很快就会产生 AI Comment Fatigue。一旦团队形成"AI 评论大多数不用看"的认知，再高的 Recall 也没有实际价值。

这和传统监控系统非常相似：一个每天产生大量误报的告警系统，最终等同于没有告警系统。

因此在企业 Code Review 场景中，降低 Noise、提高 Precision，有时候比单纯追求"尽可能发现所有问题"更加重要。

十三、OpenCodeReview 给 Agent Engineering 带来了什么启发？

如果只是把 OpenCodeReview 当成一个 AI Code Review CLI，其实会错过这个项目最值得研究的部分。

它体现出来的很多设计原则都可以迁移到其他 Agent 系统。

首先，能够通过程序确定的事情不应该交给 LLM。文件范围、路径、规则、Schema、权限和状态等信息都应该尽量通过确定性逻辑解决，LLM 只负责语义理解和动态决策。

其次，大 Context 并不等于好 Context。一个 Agent 真正需要的不是无限扩大的上下文，而是经过 Filter、Route 和 Bundle 之后得到的 Relevant Context。

flowchart TD A[Large Context] --> B[Filter] B --> C[Route] C --> D[Bundle] D --> E[Relevant Context] E --> F[LLM]

第三，Agent 的价值应该集中在那些程序无法预先确定的问题，例如"我是否还缺少某个类的信息""应该搜索哪个模块""这段实现是否违反业务逻辑""这个问题是否真的值得阻塞 Merge"。

最后，LLM 的输入和输出都应该被视为不可信数据。Agent 可以参与推理，但进入生产系统之前仍然需要 Schema、Rule、Permission 和 Validation 建立确定性边界。

这些设计组合到一起，其实可以归纳成一个更大的趋势：

未来 Agent 系统真正重要的竞争力，可能不只是 Agent 本身，而是包裹 Agent 的 Harness。

十四、从 Code Review 继续往前走

OpenCodeReview 解决的只是软件开发 Workflow 中的一环：Code Review。

如果继续沿着这个思路扩展，一个更完整的 AI Software Development Workflow 可能是：

flowchart TD A[Requirement] --> B[Research Agent] B --> C[Planning Agent] C --> D{Human Review Plan} D -->|Reject| C D -->|Approve| E[Coding Agent] E --> F[Test Agent] F --> G{Tests Pass} G -->|No| E G -->|Yes| H[OpenCodeReview] H --> I{Issues Found} I -->|Yes| J[Fix Agent] J --> F I -->|No| K{Human Approval} K -->|Reject| E K -->|Approve| L[Commit / Pull Request]

在这套 Workflow 中，Codex 或 Claude Code 可以负责 Coding，JUnit、pytest、Playwright 等测试框架负责 Test，OpenCodeReview 负责 Review，Semgrep 或其他 SAST 工具负责 Security。

Human 不需要参与每一次机械操作，而是集中在真正需要判断的 Gate，例如 Plan Approval、Architecture Decision、高风险修改和最终 Merge。

此时 AI Coding 才真正从"帮我写一段代码"，逐渐演进成 Agent-native Software Engineering Workflow。

十五、为什么 OpenCodeReview 值得研究？

现在 GitHub 上已经有大量 AI Coding 项目，很多项目的基本结构都非常相似：

diff 复制代码

Prompt
+
Tool Calling
+
LLM

但当 Agent 真正进入生产以后，需要解决的问题会完全不同：Context 应该如何控制，大型任务应该怎么拆，Rule 如何路由，LLM 输出如何校验，Comment 如何精确定位，如何减少误报，如何接入 CI，以及如何与已经存在的 Coding Agent 协作。

这些问题已经不再属于单纯的 Prompt Engineering。

它们属于：

Agent Engineering。

OpenCodeReview 最值得研究的地方，也正是它开始认真处理这些模型之外的工程问题。

总结

回到文章最开始的问题：

Claude Code 和 Codex 已经可以 Review Code，为什么还需要 OpenCodeReview？

原因是"模型能够 Review 代码"和"系统能够稳定、可控、低噪音地运行在真实工程 Workflow 中"，其实是两件完全不同的事情。

最简单的 AI Code Review 可能只有三步：

css 复制代码

flowchart LR
    A[Git Diff] --> B[LLM]
    B --> C[Review]

而工程化以后，整个流程会变成：

flowchart LR A[Git Diff] --> B[Scope] B --> C[Filter] C --> D[Bundle] D --> E[Rule Routing] E --> F[Agent] F --> G[Context Retrieval] G --> H[Structured Output] H --> I[Validation] I --> J[Positioning] J --> K[Review]

真正把 Demo 和 Production Agent 拉开差距的，往往就是中间增加的这些东西：Scope、Filtering、Bundling、Rule Routing、Context Engineering、Validation、Positioning 和 Observability。

所以 OpenCodeReview 给我的最大启发，并不是如何让模型变得更聪明，而是：

如何让 LLM 只负责它真正擅长的事情，并用确定性工程约束那些它并不擅长的部分。

这可能也是未来 Agent 工程化中最重要的设计原则之一。

参考资料

OpenCodeReview：

github.com/alibaba/ope...

本文主要参考项目当前 README、Agent Skill、Delegation Mode、Review Rules、GitHub Actions Integration 以及 Security Assurance Case 等文档。

OpenCodeReview 仍处于快速迭代阶段，本文基于 2026 年 9 月项目实现与公开文档进行分析，具体 CLI 参数和集成方式请以最新主分支为准。