审查者 Agent:建造者与打分者分离

审查者 Agent:建造者与打分者分离

本节摘要:写了代码的 Agent 不能给它打分。审查者(reviewer)是第二个循环,带不同的系统提示、不同的目标、对建造者产出的一切只读访问。建造者与审查者之间的这道鸿沟,是大多数可靠性栖身的地方。诊断很经典:你让 Agent 修 bug,它编辑四个文件、跑测试、报告完成;验证门(第 38 节)确认验收跑了、范围守住了,门说 passed: true,你合并。两天后你发现——这个修法解了 bug 的错误那一半。验收是必要不充分的。审查者问验收问不了的问题:这解了对的问题吗?没标记地扩了范围吗?把本该质疑的假设写成文档了吗?留给下一会话的状态能干净接上吗?本节定义审查者的五维量表(问题契合度/范围纪律/假设/验证质量/交接就绪,每维 0-2,满分 10,<7 软失败、<5 硬失败),并立三条铁律:审查者是独立角色,不是独立模型(同模型即可,纪律在角色分离——不同系统提示、不同输入、对 diff 无写权限,姿态的改变即信号的改变);审查者不能编辑 diff(读 diff/状态/反馈/裁决,写报告,不补丁——若报告说「修这个」,下一轮建造者去修,审查者回去审查);审查者量表 vs 验证门(门查确定性事实:验收跑了没、规则过了没、范围守了没;审查者做定性判断:这是对的工作吗、文档了吗、交接能用吗——两者都要)。本节用标准库实现审查者循环(读建造者工件、五维打分、发 review_report.json),并给四条让它在规模上工作的生产模式:专家池非单一审查者(Cloudflare 2026-04 跑 13 万次评审/48k 合并请求/5169 仓,最多 7 个专家并行 + 协调者去重判严重度,顶级模型只给协调者)、偏差缓解作为设计要求(四种 LLM judge 偏差:位置偏差/冗长偏差/自我偏好/权威偏差,各有缓解)、校准集非凭感觉(10-20 任务历史集,每次提示改动跑,与历史一致率<80% 即量表要修再交付)、与门的 Hybrid Norm(门管确定性,审查者管语义,别让审查者重做门已证明的)。读完本节,你能把「建造者批自己作业」变成「同行评审」,让人的评审从一份书面报告而非空白页开始。

对应原课程:Phase 14 · Lesson 39 · reviewer-agent(原英文 phases/14-agent-engineering/39-reviewer-agent/docs/en.md)。前置:第 38 节(验证门)。

学习目标

阅读完本节,你应当能够:

1. 说明为什么同一个 Agent 不能可靠地审查自己的工作。
2. 构建一个消费建造者工件、发结构化审查报告的审查者 Agent 循环。
3. 编写一个给具体维度而非凭感觉打分的审查者量表。
4. 把审查者接进工作台,让人的评审步骤从真实工件起步。
5. 说出四条让审查者在规模上工作的生产模式。

一、问题与直觉

你让 Agent 修 bug。它编辑四个文件,跑测试,报告完成。验证门(第 38 节)确认验收跑了、范围守住了。门说 passed: true。你合并。两天后你发现,这个修法解了 bug 的错误那一半。

验收必要,不充分。审查者问验收问不了的问题:这解了对的问题吗?没标记地扩了范围吗?把本该质疑的假设写成文档了吗?留给下一会话的状态能干净接上吗?

这正是第 26 节「级联错误」里「Agent 分不清失败与不可能」的定性补充——验证门拦住了「没完成却声称完成」(成功幻觉),审查者拦住了「完成了却解错了问题」(问题契合度)。两者互补。

审查者量表

五个维度,每维 0 到 2 打分。

满分 10。<7 软失败;<5 硬失败。

审查者是独立角色,不是独立模型

你可以用与建造者同款模型跑审查者。纪律在角色分离:不同系统提示、不同输入、对 diff 无写权限。姿态的改变即信号的改变。

审查者不能编辑 diff

审查者读 diff、状态、反馈、裁决。它写报告。它不补丁 diff。若报告说「修这个」,下一轮建造者去做修;审查者回去审查。混角色会毁掉这道鸿沟。

审查者量表 vs 验证门

门(第 38 节)查确定性事实:验收跑了没、规则过了没、范围守了没。审查者做定性判断:这是对的工作吗、文档了吗、交接能用吗。两者都要。

二、从零实现

原课程 code/main.py 实现:

• 一个 ReviewerInputs 数据类,打包审查者读的工件。
• 一个量表打分器,每维一个函数(确定性、stub 级;真实实现会调 LLM)。
• 一个 review_report.json 写入器,带五个分、总分、裁决(pass/soft_fail/hard_fail)。
• 两个演示案例:一个干净改动,一个「对的测试、错的问题」改动。

Step 1:五维打分(每维一函数)

def score_problem_fit(inputs):
    # 改动是否解了 goal 所述问题,而非附近问题?stub: 比 diff 与 goal 语义
    return 2 if addresses(inputs.diff, inputs.goal) else 0

def score_scope_discipline(inputs):
    return 2 if not inputs.scope_report["off_scope"] else 1

def score_assumptions(inputs):
    return 2 if inputs.state.get("assumptions") else 0

def score_verification_quality(inputs):
    # 验收命令证的是目标还是更弱版本?
    return 2 if proves(inputs.acceptance, inputs.goal) else 1

def score_handoff_readiness(inputs):
    return 2 if inputs.state.get("next_action") else 0
​

Step 2:聚合 + 裁决

def review(inputs):
    scores = {
      "problem_fit":   score_problem_fit(inputs),
      "scope":         score_scope_discipline(inputs),
      "assumptions":   score_assumptions(inputs),
      "verification":  score_verification_quality(inputs),
      "handoff":       score_handoff_readiness(inputs),
    }
    total = sum(scores.values())
    if any(v == 0 for v in scores.values()) or total < 5:
        verdict = "hard_fail"
    elif total < 7:
        verdict = "soft_fail"
    else:
        verdict = "pass"
    return {"scores": scores, "total": total, "verdict": verdict}
​

Step 3:写报告(人从书面起步)

def emit(report, task_id):
    atomic_write(f"outputs/review/{task_id}.json", json.dumps(report, indent=2))
    # 人的评审从这份报告开始,而非空白页
​

运行 python3 code/main.py 会把两份审查报告写盘,并在控制台打印维度分表。

生产模式(让它在规模上工作)

receipts:Cloudflare 2026-04 的 AI 代码评审系统,30 天跨 5169 仓、48095 合并请求跑了 131246 次评审运行。评审中位数 3 分 39 秒完成。最多七个专家审查者(安全、性能、代码质量、文档、发布管理、合规、Engineering Codex)在一个评审协调者下并行跑,协调者去重发现并判严重度。顶级模型专留给协调者;专家跑更便宜档。

四条模式让它在规模上工作。

专家池,非单一审查者。 一个带 5 维量表的审查者适合单人仓库。一旦代码库有安全关键、性能关键、文档面,拆成带更小提示的专家。协调者做去重;专家从不跑全量表。模型档分离自然掉出来:便宜专家,贵协调者。

偏差缓解作为设计要求,非优化。 LLM judge 显示四种可靠偏差(Adnan Masood,2026-04):位置偏差(GPT-4 在 (A,B) vs (B,A) 排序上约 40% 不一致)、冗长偏差(对更长输出约 15% 评分膨胀)、自我偏好(judge 偏好同模型家族的输出)、权威偏差(judge 高估对已知作者的引用)。缓解:两种排序都评只算一致胜;用明确奖励简洁的 1-4 量表;跨模型家族轮换 judge;打分前剥作者名。

校准集,非凭感觉。 一个 10-20 任务、带已知正确裁决的历史集。每次提示改动在上面跑审查者。若与历史记录的一致率<80%,量表在审查者交付前要修。这是每个团队最终都会重新发现的;不如一开始就有。

与门的 Hybrid Norm。 验证门(第 38 节)处理确定性检查(验收跑了没、测试过了没、范围守了没)。审查者处理语义检查(这是对的工作吗、假设文档了吗、交接能用吗)。Anthropic 2026 指引对这道分拆说得很明白:别让审查者重做门已证明的。

💡 设计要点:审查者补上了验证门留的定性缺口——门拦「没完成却声称完成」(成功幻觉),审查者拦「完成了却解错了问题」(问题契合度)。它的力量不在「换更强模型」,而在角色分离:不同提示、不同输入、对 diff 无写权限——姿态的改变即信号的改变。这与第 25 节「辩论靠多样性」、第 05 节「CRITIC 锚外部工具」同源——独立的第二视角,是单模型自我修正群体思维的工程解药。

三、框架对比

审查者是工作台在人做不了每次评审时长出的第二双眼睛。

四、可复用产物

原课程 outputs/skill-reviewer-agent.md:生成项目特定的审查者量表、一个接好建造者工件的审查者 Agent 桩、一个与验证门的集成,让人评审从书面报告而非空白页开始。

五、练习

1. (Easy) 加一个你产品领域特定的第六维。论证它为何不被现有五维吸收。
2. (Medium) 用两个不同系统提示(简洁、详尽)跑审查者。哪个产出人更可能读的报告?
3. (Medium) 每维加 confidence 字段。最低维置信度<0.6 时拒绝交付报告。
4. (Hard) 建校准集:10 个带已知正确裁决的历史任务收尾。在上面跑审查者。它在哪与历史记录分歧?
5. (Hard) 加「请求更多证据」能力:审查者打分前可向建造者要一次特定测试运行。怎样退避才不循环?

本节要点回顾

1. 写代码的 Agent 不能给它打分:审查者是第二循环,不同提示/目标/对建造者产物只读;鸿沟是可靠性栖身处。
2. 验收必要不充分:门拦「没完成却声称完成」,审查者拦「完成了却解错问题」。
3. 五维量表:问题契合度/范围纪律/假设/验证质量/交接就绪,每维 0-2,满分 10,<7 软失败、<5 硬失败。
4. 独立角色非独立模型:同模型即可,纪律在角色分离——不同提示/输入/无写权限,姿态改变即信号改变。
5. 审查者不能编辑 diff:读工件写报告,不补丁;混角色毁鸿沟。
6. 量表 vs 门:门查确定性事实,审查者做定性判断;两者都要。
7. Cloudflare receipts:13 万次评审/48k MR/5169 仓,7 专家并行 + 协调者去重判严重度,顶级模型只给协调者。
8. 四条生产模式:专家池非单一、偏差缓解作设计要求(四种 judge 偏差各缓解)、校准集非凭感觉(<80% 一致即修量表)、与门 Hybrid Norm(别重做门已证明的)。
9. 四种 judge 偏差:位置、冗长、自我偏好、权威——各有缓解(两排序/简洁量表/轮换模型/剥作者名)。
10. 第二双眼睛:人在做不了每次评审时工作台长出的;与辩论/CRITIC 同源,独立第二视角是群体思维的解药。

下一节,我们把审查者的交接就绪维度做实——多会话交接:会话结束时发什么(改了什么、为什么、还剩什么、下次从哪开始),让下一次会话读交接包而非重新发现一切。