Aperant PR Follow-up 新代码审查 Agent:增量 Diff 专精审查与回归防线实战指南

原创2026-10-04 20:41:392,337 阅读
文章标签:人工智能AI Agent代码智能体多智能体Agent 框架开发工具

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"展开专项审查,覆盖五类问题:

  1. Security vulnerabilities(安全漏洞)
  2. Logic errors and edge cases(逻辑错误与边界情况)
  3. Code quality issues(代码质量问题)
  4. Potential regressions(潜在回归)
  5. Incomplete implementations(不完整实现)

在 parallel-followup.ts 中,该 Agent 的触发条件非常明确:只有 diffSinceReview.length > 100(增量 diff 超过 100 字符)时,编排器才通过 Promise.allSettled() 并行拉起 new-code-reviewer 任务;如果没有实质性的新增改动,就直接跳过,避免无意义的重复审查。

二、CRITICAL:PR 范围界定——什么该报、什么不该报

增量审查最容易翻车的地方是"报错了范围"。该 Agent 用两套清单硬性约束边界:

在范围内(应当报告)

  1. 变更代码中的问题:PR 实际修改文件/行中存在的问题;
  2. 对未变更代码的影响:"这个改动破坏了 other_file.ts 里的调用方";
  3. 缺失的相关修改:"utils.ts 里类似的模式没有同步更新";
  4. 不完整实现:"新增了字段但序列化器里没有处理"。

不在范围内(禁止报告)

  1. 存量 bug:PR 没碰过的代码里早就存在的旧 bug;
  2. 已合并分支的代码:提交信息里带 PR 引用(如 (#584))的提交属于其他 PR;
  3. 无关改进:不要建议重构未被触碰的代码。

Prompt 给出了决定性的区分示例:

  • ✅ "Your change breaks the caller in auth.ts" —— 好的(影响分析)
  • ❌ "The old code in legacy.ts has 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"。

四条"绝不"

  1. 绝不假设代码有漏洞——读实际实现;
  2. 绝不假设校验缺失——检查调用方和周边代码;
  3. 绝不基于函数名臆断——unsafeQuery() 实际上可能是安全的;
  4. 绝不未读代码就报告——必须核实问题确实存在于所指的那一行。

必须做到

  • 实际 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 前必须执行的强制流程:

  1. 使用 Read 工具查看 finding 位置的实际代码:

    • 绝不只凭 diff 报告;
    • 在被标记行前后各取 ±20 行上下文;
    • 核实该行号在文件中真实存在。
  2. 验证问题确实存在,而非假设:

    • 该行真的存在所述问题模式吗?
    • 附近是否有你遗漏的校验/消毒?
    • 框架是否提供了自动保护?
  3. 提供代码证据:

    • evidence 字段必须包含来自文件的真实代码;
    • 不是"这段代码做了 X"的描述,而是真实的 const query = ...;
    • 拿不出真实代码,就等于没有验证问题。
  4. 用 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)

  1. 先扫描红旗:

    • eval()、exec()、dangerouslySetInnerHTML;
    • 硬编码密码、API key;
    • SQL 字符串拼接;
    • shell 命令构造。
  2. 检查修复正确性:

    • 修复是否真正解决了上报的问题?
    • 所有代码路径是否都被覆盖?
    • 错误场景是否已处理?
  3. 寻找附带损伤(collateral damage):

    • 同一批文件里还改了哪些地方?
    • 修复是否影响其他功能?
    • 是否存在需要联动的依赖修改?
  4. 验证完整性:

    • 是否遗留 TODO?
    • 变更是否有测试覆盖?
    • 需要时文档是否同步更新?

十二、重要原则(Important Notes)

  1. 保持聚焦:只审查新改动,不审整个 PR;
  2. 考虑上下文:理解修复试图达成的目标;
  3. 建设性:给出修复建议,而不只是罗列问题;
  4. 避免吹毛求疵:聚焦功能性缺陷;
  5. 串联回归:若修复引发了新问题,必须引用原始 finding。

十三、Agent 在并行编排中的真实调用链路

从 parallel-followup.ts 可以看到 new-code-reviewer 在生产环境中的完整执行链路,可作为该 Prompt 落地形态的源码级佐证:

  1. 上下文组装:编排器把 filesChangedSinceReview(变更文件清单)与 diffSinceReview(增量 diff,超过 100,000 字符时截断)注入 Prompt(buildNewCodeReviewerPrompt(),第 251-284 行);
  2. 并行调度:通过 Promise.allSettled() 与 resolution-verifier、comment-analyzer 并行执行,hasSubstantialDiff(diff > 100 字符)是该 Agent 的启动门槛;
  3. 结构化输出:runSpecialist() 用 Output.object({ schema: ReviewFindingsOutputSchema }) 约束解码,获得 { findings: [...] };
  4. 二次校验:编排器对返回结果用 ReviewFindingsArraySchema.safeParse() 再校验,并跳过缺少 title/file 的无效条目;
  5. ID 生成与去重:每个新 finding 经 MD5 哈希生成 FU-xxxxxxxx 形式的 ID(generateFindingId(),第 122-130 行),再经 deduplicateFindings() 按 file:line:title 去重;
  6. 合并出 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。

登录后查看全文
Aperant