ALIBABA / OPEN-CODE-REVIEW · 核心流程源码拆解

拆解阿里 Open Code Review:
六个 Prompt 串起的代码审查流水线

以一个改动 8 个文件的 PR 为例,看 Go 主程序如何调度六个专用 Prompt 完成分组、查证、行号校准与误报剔除。

仓库:alibaba/open-code-review 阅读约 10 分钟 19 张 SVG 流程图与提示词图解(点击图片可放大)
总览:一次 PR 如何变成审查结果 点击放大
总览:一次 PR 如何穿过六个 Prompt 变成落到具体行号的审查结果 新窗口原图 ↗

背景:为什么要把一次审查拆成六个 Prompt?

如果直接把整个 PR 的 git diff 塞进一个 Prompt 让大模型或通用 Agent 审,工程落地上通常会遇到三个具体问题:

PROBLEM 01

多文件混杂容易漏看

业务实现、单测、配置文件混在同一个长上下文里,模型注意力分散,经常漏审后面的文件。

PROBLEM 02

只看 diff 片段导致误报

不读完整源文件、不查函数调用方,模型靠猜上下文给建议,产生大量与实际代码不符的幻觉评论。

PROBLEM 03

引用代码被改写,行号算不出

模型输出评论时常把引用的原代码写错几个字符,导致程序无法用文本匹配算出对应的 Git 行号。

alibaba/open-code-review 的设计思路:用 Go 代码控制流程状态和本地文件读写,让 6 个职责单一的 Prompt 分工配合。在官方 200 个真实 PR 的评测集(AACR-Bench)上,这套架构比直接用通用 Coding Agent 准得多,且大幅省 Token。
~1/9
Token 消耗(省 89%)
6 Prompts
流水线分工角色
1. GROUPING 分组 2. PLAN 定计划 3. MAIN 查代码 4. RE_LOCATION 修锚点 5. FILTER 删误报 6. COMPRESSION 压历史

本文跟踪的示例 PR:给登录流程增加“会话过期”处理(改了 8 个文件)

索引文件路径改动行数变更内容
0internal/auth/login.go+120 / -20登录主流程实现
1internal/auth/session.go+45 / -10会话过期判断逻辑
2internal/auth/login_test.go+80登录单元测试
3internal/auth/session_test.go+30会话单元测试
4internal/i18n/messages_en.properties+3 / -1英文报错文案
5internal/i18n/messages_zh.properties+3 / -1中文报错文案
6config/auth.yaml+10 / -2会话 TTL 配置项
7docs/auth.md+20鉴权文档说明

0PREPARE · 本地确定性预处理

第 0 站:调模型前,Go 程序先筛文件并冻结清单

把不该审的文件踢掉,建好支持断点续跑的任务账本(Manifest)

执行主体
Go 主程序(不调模型)
输入
本地 Git Diff + 配置
输出
冻结的 manifest.selected
本例结果
8 个文件留存 (8 ≥ 4 触发分组)
01 · 过滤

剔除噪音与超大文件

过滤二进制、密钥、exclude 文件、不支持后缀,以及单文件 diff 超 80% MAX_TOKENS 的文件。

02 · 建账

冻结审查清单

写入 manifest.selected 锁定覆盖范围,后续逐文件记录完成或失败状态。

03 · 续传

复用历史(--resume)

带上 --resume 参数时,直接复用上次账本中已完成的结果,仅补跑未完成部分。

04 · 分发

跳过纯删除并判阈值

剔除纯删除文件;剩余文件数 8 ≥ 4,达到分组阈值,进入 GROUPING。

准备:冻结审查清单 点击放大
流程第 0 步:读 diff、筛选过滤、冻结审查清单 单页打开 →

1GROUPING_TASK · 按关联度分堆

第 1 站 GROUPING:把相关文件配成组,组间并发审

把业务代码和对应的单测放在同一组,避免单审时误报“缺少测试”

触发条件
待审文件数 ≥ 4
模型看到的输入
仅文件编号、路径与行数(无 diff)
模型输出
JSON 分组数组(每组 ≤ 10 文件)
源码位置
internal/agent/grouping.go
输入:{{file_list}}(不传具体 diff)
[0] MODIFIED internal/auth/login.go (+120/-20)
[1] MODIFIED internal/auth/session.go (+45/-10)
[2] MODIFIED internal/auth/login_test.go (+80/-0)
[3] MODIFIED internal/auth/session_test.go (+30/-0)
[4] MODIFIED internal/i18n/messages_en.properties (+3/-1)
[5] MODIFIED internal/i18n/messages_zh.properties (+3/-1)
[6] MODIFIED config/auth.yaml (+10/-2)
[7] MODIFIED docs/auth.md (+20/-0)
输出:JSON 分组结果(共 5 组)
[
  {"label": "login flow",       "files": [0, 2]},
  {"label": "session handling", "files": [1, 3]},
  {"label": "i18n messages",    "files": [4, 5]},
  {"label": "auth config",      "files": [6]},
  {"label": "docs",             "files": [7]}
]
Go 程序的四条校验兜底

prompt 另有三条输出约束:用索引引用文件(不重复完整路径)、每个文件只进一个组、只输出 JSON 数组。模型不守约时由程序纠偏:

  • 模型漏分的文件 → 自动补成单文件组;
  • 单组超过 10 个文件(maxFilesPerGroup)→ 自动拆开;
  • 组内合并 diff 超过 Token 预算 → 拆回单文件组;
  • JSON 解析失败 → 降级为所有文件逐个单审。
并发子任务与对话隔离

还原索引后,5 个审查组作为独立 goroutine 并发执行(默认并发度 8,可通过 --concurrency 修改)。

注意:GROUPING 只决定谁和谁一起审,后续的 PLAN、MAIN、FILTER 都是各自重新发起的独立模型请求。

GROUPING:8 个文件到 5 组 点击放大
流程GROUPING:8 个文件 → 5 个审查组,组间并行 单页打开 →
GROUPING 提示词全量 点击放大
提示词GROUPING 提示词全量图解 单页打开 →

2PLAN_TASK · 审前检索规划

第 2 站 PLAN:改动行数达标时,先列一份排查提纲

不挂载真实工具,快速扫一遍 diff 列出高风险怀疑点和待查文件

触发条件(满足其一)
单文件 ≥ 50 行 / 组 ≥ 2 文件且 ≥ 100 行
模型看到的输入
组外文件清单 + 本组 diff + 背景 + 规则 + 工具文本说明
挂载 Tools 字段
无(防止在规划阶段调工具死循环)
工具说明清单
file_read / code_search / file_read_diff / file_find
本例触发情况
login / session 组触发,其余跳过
PLAN 输出示例:纯文本排查计划(允许回答 Issues (none))
Summary: Add session expiry enforcement to login and refresh flows.

Issues
1. [high] Refresh path does not check whether the session already expired
   → file_read internal/auth/session.go — confirm TTL check location
2. [medium] Login failure message is hardcoded English
   → file_read internal/i18n/messages_en.properties — check new key exists
3. [low] Test does not cover expired-session branch
   → file_read internal/auth/login_test.go — confirm missing case
第 1 轮 MAIN:原样注入作参考

程序把这段文本原样存为 planResult(不做结构化解析,也不自动跑工具),通过 {{plan_guidance}} 塞进第 1 轮 MAIN 帮助快速聚焦重点。

第 2 轮 MAIN:整段移除防锚定

第 2 轮开始时整段删掉这段计划——避免模型产生路径依赖,第二轮还只盯着老计划里的几个怀疑点看。

PLAN:只服务第 1 轮的检索计划 点击放大
流程PLAN:给第 1 轮 MAIN 的检索计划,第 2 轮即移除 单页打开 →
PLAN 提示词全量 点击放大
提示词PLAN 提示词全量图解 单页打开 →

3MAIN_TASK · 第 1 轮主审查

第 3 站 MAIN 第 1 轮:调工具查仓库上下文,提交代码评论

在多轮 Tool Loop 中读取源文件、搜索调用方,通过 code_comment 提交发现的问题

触发条件
每个审查组必跑
输入上下文
本组 diff + 规则 + PLAN 计划
单轮工具上限
默认最多 100 次工具调用
评论处理方式
后台 Worker 异步算行号
file_read参数: file_path

读取仓库中的完整源文件,补齐 diff 片段之外的上下文逻辑。

code_search参数: search_text

全局搜索函数定义或调用方,确认改动是否破坏上下游调用。

code_commentpath / existing_code / content

提交一条审查评论。调用后立即向模型返回成功,定位任务交由后台 Worker 异步执行。

task_done结束信号

宣告本组审查完成。程序随后调用 AwaitKey(groupKey) 等待后台评论 Worker 排空。

本例第 1 轮产出:login flow 组共提交 3 条评论。其中 1 条的 existing_code 与 diff 原文不完全一致,后台 Worker 文本匹配失败,触发第 4 站重定位。

这 3 条评论分别说了什么?

模型通过 code_comment 提交评论,每条带 path / content / existing_code / category / severity。本例 3 条的最终去向:

ID文件评论内容级别去向
c-0login.go刷新路径没有检查会话是否已过期,过期会话仍能续期。bug · highFILTER 保留 → 成为 confirmed
c-1login.go讨论的 auth.yaml 配置项变化不在本文件 diff 中—FILTER 删除(理由 A:代码不存在)
c-2login.go称 retryCount 声明了两次—FILTER 删除(理由 B:diff 直接反驳)
模型提交 c-0 时的 tool_calls(请求 3)
{
  "tool_calls": [
    {
      "name": "code_comment",
      "arguments": {
        "comments": [
          {
            "path": "internal/auth/login.go",
            "content": "刷新路径没有检查会话是否已过期,过期会话仍能续期。",
            "existing_code": "if refreshed, err := refreshSession(token); err == nil {",
            "category": "bug",
            "severity": "high"
          }
        ]
      }
    }
  ]
}
MAIN 第 1 轮:工具循环与评论闸门 点击放大
流程MAIN R1:工具循环 + code_comment 闸门 + task_done 单页打开 →
评论定位:path 匹配与跨文件命中 点击放大
流程评论定位:本文件匹配、跨文件唯一命中、行号确定 单页打开 →
MAIN 提示词全量 点击放大
提示词MAIN 主审查提示词全量图解 单页打开 →

4RE_LOCATION_TASK · 修复评论代码锚点

第 4 站 RE_LOCATION:代码片段匹配不上时,从 diff 里重新抠原文

解决模型凭记忆改写代码片段导致算不出 Git 行号的问题

触发时机
后台评论 Worker 处理单条评论时
前置条件
本文件与跨文件匹配均失败,且原 path 有 diff
模型输出
从 diff 逐字复制的代码块
源码位置
internal/diff/relocation.go
本地文件匹配
先在原文件 login.go 的 diff 中直接检索代码片段
本例失败 → 降级
跨文件全库搜
在本次 PR 其他文件 diff 中搜索,仅当全局唯一命中时才自动迁移 path
本例未命中 → 降级
RE_LOCATION
把 unified diff、匹配失败的片段和评论正文发给轻量模型,逐字复制原代码
调用 LLM 修复锚点
MAIN 提交的片段(被模型改写,匹配失败)
if user == nil {
    return errors.New("invalid credentials")
}
RE_LOCATION 从 diff 逐字提取的片段(匹配成功)
if user == nil {
    return nil, ErrInvalidCredentials
}
提示词对输出的四条硬要求
  • 从 diff 中逐字复制,不改写、不重排;
  • 去掉行首的 + / - 或空格;
  • 只保留与问题直接相关的代码;
  • 只输出代码块,不多说一句。
后续处理:替换片段后重新执行行号匹配。就算依然匹配不上,评论也不会被丢弃,而是记为 start_line: 0, end_line: 0 保留在结果集中。RE_LOCATION 只找位置,不判断评论对错。
RE_LOCATION:修锚点不裁决 点击放大
流程RE_LOCATION:重写代码片段 → 重匹配 → 成败都有归宿 单页打开 →
RE_LOCATION 提示词全量 点击放大
提示词RE_LOCATION 提示词全量图解 单页打开 →

5REVIEW_FILTER_TASK · 误报过滤

第 5 站 FILTER:对照本组 diff,删掉能被事实证伪的评论

用 baseline 切片只审本轮新增评论,屏蔽原模型的 severity 和 thinking 防带偏

触发条件
本轮有新评论且未加 --no-filter
可见字段
id / path / content / existing_code + diff
屏蔽字段
severity / category / thinking
工具二选一
report_incorrect / approve_all
仅在两种情况下允许删除
  • 理由 A(代码不存在):评论描述的代码在所属文件 diff 里不存在(本例 c-1 在 login.go 下讨论 auth.yaml 配置,被删)。
  • 理由 B(diff 直接反驳):某行 diff 直接证伪评论说法(本例 c-2 称 retryCount 声明了两次,实际 diff 只有一次,被删)。
五类问题优先保留(免删保护)
内存安全 并发竞态 链接与声明一致性 行为/兼容性变更 未使用参数

“无法确认、价值不高、代码风格建议”均不是删除理由。本例 c-0(刷新路径未校验过期) 保留并标记为 confirmed。

FILTER:diff 证据对照 点击放大
流程FILTER:拿 diff 当证据,只删能证明错误的评论 单页打开 →
FILTER 提示词全量 点击放大
提示词FILTER 提示词全量图解 单页打开 →

6MAIN_TASK · 第 2 轮复查

第 6 站 MAIN 第 2 轮:新开对话,带上已确认结论再查一遍

不继承第 1 轮聊天记录、移除 PLAN 引导,避免重复报告已知问题

轮数上限(--effort)
low: 1 轮 / medium: 2 轮 / high: 3 轮
Prompt 变化 1
移除 {{plan_guidance}}
Prompt 变化 2
注入 {{confirmed_comments}}
本轮新发现
login_test.go 缺少过期测试分支
跨轮次如何传递状态?

第 2 轮是一个全新的 MAIN 对话,不带第 1 轮读文件、搜代码的历史消息。只把前序存活的评论摘要塞进 Previously Confirmed Findings(代码限 200 字符、正文限 300 字符、最多 30 条),提示模型不要重复报告。

停止条件与 Grace Round
  • 达到最大轮数 / 本轮无新增存活评论 / confirmed 满 30 条;
  • 连续 3 轮无有效工具结果(maxConsecutiveEmptyRounds = 3);
  • 若因工具次数或 Token 预算耗尽中断,会先进入 Grace Round(只准调 code_comment 和 task_done 补交已发现的问题)。

第 2 轮的新发现

不再受 PLAN 引导后,模型在测试文件里找到了一个新问题——第 1 轮计划里提过、但当时没提交:

第 2 轮 code_comment(FILTER 返回 approve_all 后保留)
{
  "tool_calls": [
    {
      "name": "code_comment",
      "arguments": {
        "comments": [
          {
            "path": "internal/auth/login_test.go",
            "content": "缺少过期会话的测试分支。",
            "existing_code": "func TestLoginSuccess(t *testing.T) {",
            "category": "test",
            "severity": "low"
          }
        ]
      }
    }
  ]
}
MAIN 第 2 轮:继承结论不继承对话 点击放大
流程MAIN R2:重新开对话,带 confirmed,不带 PLAN 单页打开 →
轮次控制:六个停止条件 点击放大
流程轮次控制:六个停止条件与 grace round 单页打开 →

7MEMORY_COMPRESSION_TASK · 单轮上下文压缩

第 7 站 COMPRESSION:单轮工具调用太多时,压缩中间旧轮次

保留开头指令和最近几轮交互,把中间读文件/搜代码的历史压成 5 维摘要

60% ~ 80% 水位
后台异步压缩,主循环继续
≥ 80% 水位
同步阻塞压缩(压完仍 ≥ 80% 则停本轮)
摘要作用范围
仅限当前轮次内有效(不跨轮)
源码位置
internal/llmloop/compression.go
1. frozen 区system + 初始 user(保留)
2. compress 区较早的完整工具轮次 → 提炼为 <previous_review_summary>
3. active 区最近几轮工具交互(原样保留)
重组方式:frozen + 追加在初始 user 末尾的摘要标签 + active 区;若压缩失败或摘要为空则保留原消息。
COMPRESSION 摘要输出示例(五个固定维度,空维度可省略)
### Identified Code Issues
- [HIGH] session.go:45 — 过期会话仍可能被刷新
### Tool Call Conclusions
- file_read(session.go): 确认 Refresh 方法没有检查过期时间
### Completed Tasks
- 已检查 session.go 的刷新实现
### Pending Tasks
- 还需要确认 session_test.go 是否覆盖该分支
### Current Focus
- 正在确认过期会话是否能通过刷新继续有效。
COMPRESSION:压缩旧历史 点击放大
流程COMPRESSION:frozen / compress / active 三区重组 单页打开 →
COMPRESSION 提示词全量 点击放大
提示词COMPRESSION 提示词全量图解 单页打开 →

8FINALIZE · 全局九步收尾

第 8 站 收尾:等待并发任务、落盘日志并渲染报告

所有组完成后按固定顺序执行 9 步收尾,产出 manifest 与 session JSONL

执行主体
Go 主程序
状态文件 1
manifest.json(文件级完成状态)
状态文件 2
session.jsonl(全量请求与事件轨迹)
报告输出格式
text / JSON / SARIF
阶段一:并发汇聚
01等所有审查组完成—— 汇合全部并发 goroutine
02等评论 Worker 排空—— 确保后台定位队列全部处理完
03收尾后台压缩任务—— 清理未结束的异步压缩协程
阶段二:状态落盘
04生成最终 manifest—— 记录选中、完成、复用、失败与排除文件
05写入 session_end—— 调用 session.Finalize 封存全量运行轨迹
06Agent.Run 返回—— 核心审查调度引擎退出
07冻结 Retry Report—— 固定失败重试信息,供 --resume 使用
阶段三:校准输出
08兜底全量行号解析—— 在落盘之后、渲染之前,对仍未定位的评论再试一次行号解析
09渲染输出最终报告—— 写出 text / JSON / SARIF 格式结果
收尾:严格九步 点击放大
流程收尾:等待、manifest、Finalize、最终行号解析、渲染输出 单页打开 →

最终报告长什么样?

两轮 MAIN、两轮 FILTER 之后,本例存活 2 条评论:c-0(bug · high)和第 2 轮新增的测试缺失(test · low)。第 09 步把它们渲染成三种格式,text 按文件分节、带定位行号:

text 输出示例(review.txt)
─── internal/auth/login.go:31-33 ───
[bug · high] 刷新路径没有检查会话是否已过期,过期会话仍能续期。

─── internal/auth/login_test.go:12-14 ───
[test · low] 缺少过期会话的测试分支。
JSON 输出节选(review.json)
{
  "status": "success",
  "comments": [
    {
      "path": "internal/auth/login.go",
      "content": "刷新路径没有检查会话是否已过期,过期会话仍能续期。",
      "existing_code": "if refreshed, err := refreshSession(token); err == nil {",
      "start_line": 31,
      "end_line": 33,
      "category": "bug",
      "severity": "high"
    }
  ],
  "manifest": {
    "terminal_state": "complete"
  }
}
真实结果还会带:模型与 provider 信息、分组信息、token 与工具调用统计、warnings、session_id、resume 信息、retry report。manifest 回答"计划审什么、完成了什么、复用了什么、失败了什么";session JSONL 记录每次模型请求、工具调用、评论和事件的完整经过。

9RECAP · 全流程速查

第 9 站 复盘:主干数据流与六个 Prompt 速查表

一张调用链 + 一张对照表,看完即可对应到仓库源码

open-code-review 主流程调用链
8 个变更文件
   │  [Go 程序] 读 diff、筛选文件、冻结 manifest.selected
   ▼
GROUPING_TASK(文件元数据 → JSON 分组)
   │  [Go 程序] 拆出 5 个审查组,组间并行
   ▼
PLAN_TASK(大改动触发:本组 diff + 规则 + 工具文本说明 → 纯文本计划)
   ▼
MAIN_TASK 第 1 轮(带工具对话:file_read / code_search … → code_comment → task_done)
   │  ├─ [评论 Worker] 本文件匹配 → 跨文件唯一命中 → 失败时调 RE_LOCATION_TASK
   │  └─ [上下文监控] 超过 60%/80% 阈值时调 MEMORY_COMPRESSION_TASK 压缩旧轮次
   ▼
等本组评论 Worker 排空 → REVIEW_FILTER_TASK 第 1 轮(本组 diff + 本轮新评论 → 删误报或放行)
   │  存活评论标记为 confirmed
   ▼
MAIN_TASK 第 2 轮(同一组 diff + 规则 + confirmed;移除 PLAN,不继承第 1 轮对话历史)
   ▼
REVIEW_FILTER_TASK 第 2 轮(只过滤第 2 轮新增评论)
   ▼
[Go 程序九步收尾] 等所有组/Worker/压缩 → manifest → session_end → retry report
   → 最终行号解析 → 输出 text / JSON / SARIF
Prompt(源码常量)触发条件只负责什么
GROUPING_TASK待审文件数 ≥ 4决定哪些文件放在同一组一起审
PLAN_TASK单文件 ≥ 50 行,或组 ≥ 2 文件且合计 ≥ 100 行给第 1 轮 MAIN 提供排查路线图
MAIN_TASK每组、每轮必跑读代码、调工具查上下文、提交评论
REVIEW_FILTER_TASK本轮有新评论,且未加 --no-filter只删除能被 diff 事实证伪的本轮新增评论
MEMORY_COMPRESSION_TASK单轮 MAIN 对话超过 60% / 80% 阈值保留头尾,把中间较早的工具轮次压成摘要
RE_LOCATION_TASK评论未定位、跨文件未命中,且原 path 有 diff从 diff 原文中逐字提取代码片段以匹配行号
复盘:主链、六 Prompt 与数据寿命 点击放大
流程复盘:主链、六 Prompt 出场条件与数据寿命 单页打开 →