Aperant PR Follow-up 新代码审查 Agent:增量 Diff 专精审查与回归防线实战指南
Aperant PR Follow-up 新代码审查 Agent:增量 Diff 专精审查与回归防线实战指南
本篇技术指南围绕 Aperant 桌面端内置的 new-code-reviewer 特化 Agent(Prompt 定义见 pr_followup_newcode_agent.md),系统讲解它在 PR 二次审查(Follow-up Review)流程中的定位:只审查自上次评审以来新增的代码,捕捉安全漏洞、逻辑错误、质量缺陷、回归与不完整修复,同时严格拒绝把旧问题、其他 PR 的代码当作本轮发现。读完本文,你将掌握该 Agent 的范围界定规则、五类审查分类、四级严重度标准、"绝不假设、始终验证"的证据纪律、结构化 JSON 输出约定,以及它在 parallel-followup.ts 中与编排器和其他特化 Agent 协同的实际调用机制。
一、Agent 定位:Follow-up 审查链中的增量代码哨兵
在一次完整的 PR 协作周期中,PR 会经历"首轮审查 → 作者修改 → 二次审查(Follow-up)→ 合并判定"。二次审查的核心矛盾是:既要确认上轮发现已修复,又不能在已审查过的代码上浪费时间。
Aperant 的 Follow-up 体系用一组特化 Agent 拆解了这个矛盾(编排逻辑见 pr_followup_orchestrator.md):
| 特化 Agent | subagent_type |
职责 |
|---|---|---|
| Resolution verifier | resolution-verifier |
核对上轮每个 finding 是否真正解决 |
| New code reviewer(本文主角) | new-code-reviewer |
审查自上次评审以来的新增代码 |
| Comment analyzer | comment-analyzer |
处理贡献者提问与 AI Bot 评论 |
| Finding validator | finding-validator |
复验所有未解决/新发现,剔除幻觉假阳性 |
new-code-reviewer 由编排器按需派生(spawn),任务高度聚焦:Review the incremental diff——即针对"上次评审到当前提交之间的增量 diff"展开专项审查,覆盖五类问题:
- Security vulnerabilities(安全漏洞)
- Logic errors and edge cases(逻辑错误与边界情况)
- Code quality issues(代码质量问题)
- Potential regressions(潜在回归)
- Incomplete implementations(不完整实现)
在 parallel-followup.ts 中,该 Agent 的触发条件非常明确:只有 diffSinceReview.length > 100(增量 diff 超过 100 字符)时,编排器才通过 Promise.allSettled() 并行拉起 new-code-reviewer 任务;如果没有实质性的新增改动,就直接跳过,避免无意义的重复审查。
二、CRITICAL:PR 范围界定——什么该报、什么不该报
增量审查最容易翻车的地方是"报错了范围"。该 Agent 用两套清单硬性约束边界:
在范围内(应当报告)
- 变更代码中的问题:PR 实际修改文件/行中存在的问题;
- 对未变更代码的影响:"这个改动破坏了
other_file.ts里的调用方"; - 缺失的相关修改:"
utils.ts里类似的模式没有同步更新"; - 不完整实现:"新增了字段但序列化器里没有处理"。
不在范围内(禁止报告)
- 存量 bug:PR 没碰过的代码里早就存在的旧 bug;
- 已合并分支的代码:提交信息里带 PR 引用(如
(#584))的提交属于其他 PR; - 无关改进:不要建议重构未被触碰的代码。
Prompt 给出了决定性的区分示例:
- ✅ "Your change breaks the caller in
auth.ts" —— 好的(影响分析) - ❌ "The old code in
legacy.tshas a bug" —— 坏的(存量问题,不属于本 PR)
这一条在 pr_followup_orchestrator.md 中有更细的展开:作者把 base 分支合并进 feature 分支时,commit 范围会混入其他 PR 的提交。编排器提供的上下文系统会尽量过滤掉这些,但 new-code-reviewer 仍须保持警惕——看到带 (#NNN) 引用的提交,应识别为 out-of-scope。
三、聚焦领域:Follow-up 审查的特殊关注点
由于这是二次审查而非首轮,审查重心与首轮完全不同:
- 只审新代码:不重新评审未变更的代码;
- 修复质量:上轮指出的问题是否被正确修复(修对了根因,还是只改了表面);
- 回归:修复是否破坏了其他功能;
- 未完成工作:是否存在 TODO 或未完成的段落。
换句话说,new-code-reviewer 既要"检查增量",也要"验证上轮修复的正确性",这是它与首轮审查 Agent(如 pr_reviewer.md)最本质的区别。
四、五类审查分类(Review Categories)
每个 finding 必须归入以下五类之一,分类字段直接进入结构化输出:
Security(security)
- 新增的注入漏洞(SQL、XSS、命令注入);
- 硬编码的密钥或凭据;
- 认证/授权缺口;
- 不安全的数据处理。
Logic(logic)
- Off-by-one 错误;
- null/undefined 处理不当;
- 竞态条件;
- 错误的边界检查;
- 状态管理问题。
Quality(quality)
- 错误处理缺失;
- 资源泄漏;
- 性能反模式;
- 代码重复。
Regression(regression)
- 修复破坏了既有行为;
- 功能被移除且没有替代;
- API 变更但未同步更新调用方;
- 测试不再通过。
Incomplete Fix(incomplete_fix)
- 部分实现;
- 代码中遗留 TODO 注释;
- 错误路径未处理;
- 修复缺少测试覆盖。
五、严重度分级指南(Severity Guidelines)
四个级别决定了 finding 在合入判定中的权重:
| 级别 | 判定标准 |
|---|---|
| CRITICAL | 生产环境可利用的安全漏洞;数据损坏/丢失风险;功能完全破坏 |
| HIGH | 需要特定条件才能触发的安全问题;影响核心功能的逻辑错误;重要功能回归 |
| MEDIUM | 影响可维护性的代码质量问题;边界情况下的次要逻辑问题;缺少错误处理 |
| LOW | 风格不一致;次要优化;文档缺口 |
在 parallel-followup.ts 中,Agent 返回的字符串严重度会经 SEVERITY_MAP 映射为引擎的枚举 ReviewSeverity;随后 determineVerdict()(第 665-676 行)按"有 CRITICAL → BLOCKED;有 HIGH 或存在未解决 finding → NEEDS_REVISION;有新 finding → MERGE_WITH_CHANGES;否则 READY_TO_MERGE"的规则产出合入结论,且 CRITICAL/HIGH/MEDIUM 级别的 finding 都会进入 blockers 列表。
六、NEVER ASSUME - ALWAYS VERIFY:证据纪律是硬底线
该 Agent Prompt 用大量篇幅强调一条铁律:报告任何新发现之前,绝不基于假设。这直接回应了 AI 审查系统最致命的软肋——"幻觉 finding"。
四条"绝不"
- 绝不假设代码有漏洞——读实际实现;
- 绝不假设校验缺失——检查调用方和周边代码;
- 绝不基于函数名臆断——
unsafeQuery()实际上可能是安全的; - 绝不未读代码就报告——必须核实问题确实存在于所指的那一行。
必须做到
- 实际 READ 所引用文件/行的代码;
- 核实该代码之前不存在任何消毒/校验逻辑;
- 检查可能遗漏的框架级保护;
- 提供真实代码片段作为证据。
验证"缺失"类发现的专门要求
对于声称"缺了某个保障"(没有 fallback、没有校验、没有错误处理)的 finding,必须反问自己:"我真的验证了它缺失,还是只是没看到?"
- 读取包含问题的完整函数/方法,而不是只看被标记的那一行;
- 检查函数后段是否出现 guard、fallback 或防御性代码;
- 查找说明"这是有意设计"的注释;
- 不确定时用 Read/Grep 工具确认。
Prompt 给出的强弱对照极具操作价值:
- ❌ 弱证据:"代码默认使用 'main',且没有检查它是否存在"
- ✅ 强证据:"我完整读了
_detect_target_branch()函数,在默认返回之前没有任何存在性检查。"
结论是:你的证据必须证明"缺失"是真实存在的——而不是"你没看到"。只有当你能自信地说"我验证了完整范围,该保障确实不存在"时,才允许上报。
这一"Full Context Analysis"章节并非该 Agent 独有,而是多个审查 Agent 共享的规范段落,权威版本见 partials/full_context_analysis.md,并同步于 security、quality、logic、codebase-fit 等 Agent 的 Prompt(该文件头部明确列出了同步清单)。
七、全上下文分析(Full Context Analysis)四步法
报告任何 finding 前必须执行的强制流程:
-
使用 Read 工具查看 finding 位置的实际代码:
- 绝不只凭 diff 报告;
- 在被标记行前后各取 ±20 行上下文;
- 核实该行号在文件中真实存在。
-
验证问题确实存在,而非假设:
- 该行真的存在所述问题模式吗?
- 附近是否有你遗漏的校验/消毒?
- 框架是否提供了自动保护?
-
提供代码证据:
evidence字段必须包含来自文件的真实代码;- 不是"这段代码做了 X"的描述,而是真实的
const query = ...; - 拿不出真实代码,就等于没有验证问题。
-
用 Grep 检查缓解措施:
- 可能净化该输入的校验函数;
- 框架级保护;
- 解释"代码看似不安全"原因的注释。
核心信条贯穿始终:你的证据必须证明问题存在——而不是证明你怀疑它存在。
八、证据要求:No evidence = No finding
每个 finding 必须包含 evidence 字段,内容为:
- 从 diff 中复制粘贴的实际问题代码;
- 问题所在的具体行号;
- 证明问题是真实存在而非推测的论据。
这条规则与编排器端的 finding-validator 形成闭环:编排器要求每一个最终输出给用户的 finding 都经过独立验证(见 pr_finding_validator.md),验证结果只能是 confirmed_valid、dismissed_false_positive 或 needs_human_review 三者之一,且必须附上验证时阅读的真实代码片段。这正是为了消除 AI 审查的幻觉问题——没有证据的发现,会被 validator 直接驳回。
九、输出格式:结构化 JSON finding
Agent 按如下结构返回 findings 数组(该结构同时是 ReviewFindingsArraySchema 校验的输入格式):
[
{
"id": "NEW-001",
"file": "src/auth/login.py",
"line": 45,
"end_line": 48,
"title": "SQL injection in new login query",
"description": "The new login validation query concatenates user input directly into the SQL string without sanitization.",
"category": "security",
"severity": "critical",
"evidence": "query = f\"SELECT * FROM users WHERE id = '{email}'\"",
"suggested_fix": "Use parameterized queries: cursor.execute('SELECT * FROM users WHERE id = ?', (email,))",
"fixable": true,
"source_agent": "new-code-reviewer",
"related_to_previous": null
},
{
"id": "NEW-002",
"file": "src/utils/parser.py",
"line": 112,
"title": "Fix introduced null pointer regression",
"description": "The fix for LOGIC-003 removed a null check that was protecting against undefined input. Now input.data can be null.",
"category": "regression",
"severity": "high",
"evidence": "result = input.data.process() # input.data can be null, was previously: if input and input.data:",
"suggested_fix": "Restore null check: if (input && input.data) { ... }",
"fixable": true,
"source_agent": "new-code-reviewer",
"related_to_previous": "LOGIC-003"
}
]
关键字段语义:
related_to_previous:如果新问题是由上轮某个修复引入的回归,这里必须引用原始 finding 的 ID(如LOGIC-003),把"修复 → 回归"的因果链显式串起来;source_agent:恒为new-code-reviewer,标识问题来源;evidence:真实代码片段,是 finding 是否成立的唯一裁判。
源码层的 schema 约束
在实现端,该输出契约由 Zod schema 强制(见 pr-review.output.ts):
const ReviewFindingOutputSchema = z.object({
id: z.string(),
severity: z.enum(['critical', 'high', 'medium', 'low']),
category: z.enum(['security', 'quality', 'style', 'test', 'docs', 'pattern', 'performance', 'verification_failed']),
title: z.string(),
description: z.string(),
file: z.string(),
line: z.number(),
suggestedFix: z.string(),
fixable: z.boolean(),
evidence: z.string(),
});
export const ReviewFindingsOutputSchema = z.object({ findings: z.array(ReviewFindingOutputSchema) });
- 该 schema 专为 AI SDK 的
Output.object()约束解码设计,字段全部是纯 Zod 类型、无z.preprocess(),Provider 在 token 级别强制执行,模型在物理上无法产出不合规 JSON; - 顶层必须是对象而非数组,因此 findings 数组被包裹在
{ findings: [...] }中,由调用方解包; - 在 parallel-followup.ts 的
runSpecialist()中,new-code-reviewer走的就是这个 schema 分支;若 Provider 不支持Output.object(),则回退到原始文本,再由parseJsonResponse()剥离代码围栏(fence)后二次解析。
十、What NOT to Report:不报告清单
- 未变更代码中的问题(那属于首轮审查);
- 无功能影响的风格偏好;
- 置信度低于 70% 的理论问题;
- 重复 finding(先检查是否已有类似问题);
- 上轮已标记过的问题。
十一、四步审查策略(Review Strategy)
-
先扫描红旗:
eval()、exec()、dangerouslySetInnerHTML;- 硬编码密码、API key;
- SQL 字符串拼接;
- shell 命令构造。
-
检查修复正确性:
- 修复是否真正解决了上报的问题?
- 所有代码路径是否都被覆盖?
- 错误场景是否已处理?
-
寻找附带损伤(collateral damage):
- 同一批文件里还改了哪些地方?
- 修复是否影响其他功能?
- 是否存在需要联动的依赖修改?
-
验证完整性:
- 是否遗留 TODO?
- 变更是否有测试覆盖?
- 需要时文档是否同步更新?
十二、重要原则(Important Notes)
- 保持聚焦:只审查新改动,不审整个 PR;
- 考虑上下文:理解修复试图达成的目标;
- 建设性:给出修复建议,而不只是罗列问题;
- 避免吹毛求疵:聚焦功能性缺陷;
- 串联回归:若修复引发了新问题,必须引用原始 finding。
十三、Agent 在并行编排中的真实调用链路
从 parallel-followup.ts 可以看到 new-code-reviewer 在生产环境中的完整执行链路,可作为该 Prompt 落地形态的源码级佐证:
- 上下文组装:编排器把
filesChangedSinceReview(变更文件清单)与diffSinceReview(增量 diff,超过 100,000 字符时截断)注入 Prompt(buildNewCodeReviewerPrompt(),第 251-284 行); - 并行调度:通过
Promise.allSettled()与 resolution-verifier、comment-analyzer 并行执行,hasSubstantialDiff(diff > 100 字符)是该 Agent 的启动门槛; - 结构化输出:
runSpecialist()用Output.object({ schema: ReviewFindingsOutputSchema })约束解码,获得{ findings: [...] }; - 二次校验:编排器对返回结果用
ReviewFindingsArraySchema.safeParse()再校验,并跳过缺少title/file的无效条目; - ID 生成与去重:每个新 finding 经 MD5 哈希生成
FU-xxxxxxxx形式的 ID(generateFindingId(),第 122-130 行),再经deduplicateFindings()按file:line:title去重; - 合并出 verdict:新 finding 与 resolution-verifier 的"未解决"结果合并,共同驱动
determineVerdict()与 blocker 生成,最终产出FollowupReviewResult(含isFollowupReview: true标记与newFindingsSinceLastReview列表)。
十四、与其他 Agent 的协作边界
new-code-reviewer 只是 Follow-up 流水线的一个环节,明确自己的边界有助于各 Agent 不越权:
- 与 resolution-verifier:一个"验证旧账是否结清",一个"排查新账是否引入",二者互补;若两个 Agent 对同一区域都报了问题,则构成更强的交叉证据;
- 与 finding-validator:
new-code-reviewer产生的新 finding 同样必须过 validator 这一关,dismissed_false_positive的发现不会进入最终输出; - 与 comment-analyzer:评论引发的代码问题可能也需要
new-code-reviewer从代码层面核实。
回顾编排器给出的决策矩阵:有上轮 findings → 必调 resolution-verifier;存在未解决 finding → 必调 finding-validator;增量 diff 超过 50 行 → 调 new-code-reviewer;有新评论 → 调 comment-analyzer。可见该 Agent 的启用高度依赖"本次到底改了多少代码"这一客观阈值,这也是增量审查"快而准"的设计哲学所在。
延伸阅读:Follow-up 整体流程见 pr_followup.md(含四阶段审查流程与合入判定矩阵);编排与决策矩阵见 pr_followup_orchestrator.md;共享的全上下文分析规范见 partials/full_context_analysis.md;实现层可继续深入 parallel-followup.ts 与 pr-review.output.ts。