Flutter 仓库的 AI 代码评审工作流：reidbaker-agent 的 code-review 技能深度解析

在 Flutter 开源仓库中，.agents/agents/reidbaker-agent/skills/code-review/SKILL.md 定义了一套面向 AI 代理（Agent）的多步骤、迭代式代码评审工作流：先收集变更、再做上下文补全、生成初版评审、对"评审本身"进行自我批判，最后综合去重并输出结构化的评审报告。本文完整还原这套工作流的五步流程、严重程度分级、评论过滤规则与大型 diff 切分工具的实现细节，读完你可以理解如何把一次泛泛的 AI 评审约束为"只评变更行、可编译建议、按严重度排序"的可落地评审过程，并据此在自己的项目中复制这套"生成 → 批判 → 综合"的迭代模式。

技能定位：一次评审，五个阶段的迭代精炼

该技能位于 code-review/SKILL.md，其 YAML frontmatter 声明了技能名称与用途：

name: code-review
description: Performs a comprehensive, multi-step code review of pull requests
  or local code changes, using iterative refinement (generation, critique,
  synthesis) to ensure high-quality, actionable feedback.

它的设计目标是产出"彻底、可执行、格式规范"的评审反馈，同时规避 AI 评审的典型缺陷：对未改动的代码说"看起来不错"、在上下文行上贴评论、给出无法编译的代码建议。技能为 Agent 设定了一个角色——专精代码评审与迭代开发的资深软件工程师，要求"一丝不苟、协作导向、严格遵守项目规范"。

该技能由 reidbaker-agent 承载。从 config.yaml 的 prompt_section_customization 配置可以看到，这个 Agent 被附加了一段"Expert"人格提示词：要求给出完整、具体、分步骤的答案，先给出最强反驳意见，使用显式的置信等级（high/moderate/low/unknown），不做无谓的免责声明，"准确率是你的成功指标，而不是我的认可"。这正是 code-review 技能所需的"严苛、坦率"评审基调。另外，config.yaml 中有一段"Environment Verification"提示，要求 Agent 在新会话第一步检查本地技能目录是否已安装，未安装时提示执行 cd .agents/agents/reidbaker-agent && npx skills experimental_install——这与 skills-lock.json 中锁定的外部技能（如 dart-best-practices、dart-test-fundamentals 等来自 kevmoo/dash_skills 与 dart-lang/skills 仓库的技能）共同构成评审时的领域参考。

核心原则：只在有问题时说话

工作流之前，技能先确立了五条核心原则，它们约束着整个评审过程：

• 聚焦问题（Focus on Issues）：只有存在真实问题、bug 或明确的改进机会时才添加评审评论，不要为验证或解释代码而加评论。
• 建议对准目标行（Targeted Suggestions）：建议只限定在 diff 中实际修改的行。
• 可执行反馈（Actionable Feedback）：尽可能给出具体的代码建议。
• 自然写作（Natural Writing）：所有书面反馈遵循 natural-writing 技能的规则。
• 借助专项技能（Leverage Specialized Skills）：若代码库、语言或框架存在专项技能（如 angular-component、typescript-advanced-types），应引用它们以保证反馈符合最佳实践。

其中"自然写作"这条原则指向同 Agent 下的另一份技能 natural-writing/SKILL.md。该文件列出了一份"AI 腔"禁用词表（如 delve、underscore、tapestry、pivotal 等）、禁止用花哨表述替换 is/are 系动词、禁止在代码与注释中使用 now/old/new 这类相对时间词、禁止"尽管面临挑战……依然蓬勃发展"式结尾等规则。code-review 在生成阶段和综合阶段两处都显式引用它，意味着评审意见不仅内容要准，文字也要像人写的：不吹捧、不堆砌形容词、结尾不写空话。

五步工作流

技能要求按顺序执行以下五步。每一步都有明确的输入、动作和输出。

Step 1：收集变更

开始评审前先拿到待评审的变更，分两种场景：

针对 GitHub Pull Request：

• 用 gh pr view 读取标题与描述，理解 PR 意图；
• 用 gh pr diff 获取实际的代码变更。

针对本地变更：

• 用 git status 查看被修改的文件；
• 用 git diff 查看未暂存的变更，或 git diff --staged 查看已暂存变更；
• 评审本地分支时，用 git log -p 查看最近提交。

这一步的关键是把"意图"和"变更"分开拿：PR 描述告诉你作者想做什么，diff 告诉你实际改了什么。后续步骤中所有评论都必须锚定在 diff 上，而意图信息则用于判断"实现是否与描述一致"这类正确性问题。

Step 2：上下文补全

在评审 diff 之前，先识别仓库中哪些额外文件对理解改动有帮助。技能列出的考虑清单包括：

• 被导入或被引用的文件；
• 父类或接口；
• 相关的工具文件；
• 与变更文件对应的测试文件。

对大型或复杂的评审，技能要求参考 splitting_reviews.md 的指南将评审切分，具体切分策略与配套脚本见下文"大型 diff 的切分策略"一节。

Step 3：生成初版评审

基于补全后的上下文生成评审评论，评审围绕四个标准展开：

• 正确性（Correctness）：验证功能、处理边界情况、检查 API 用法；
• 效率（Efficiency）：识别瓶颈与冗余计算；
• 可维护性（Maintainability）：评估可读性与风格规范遵循度；
• 安全性（Security）：识别潜在漏洞。

这一步还有几条硬性指南：必须使用 review_criteria.md 中的既定标准；API 设计问题参照 api-review 技能的正典 API 设计指南，文档问题参照 code-documentation 技能；以及一条标记为 CRITICAL 的规则——不要添加任何告诉用户"你做了好改进"的评论。

review_criteria.md 把上述四个标准展开为可核查的清单：

1. 正确性：逻辑错误（有缺陷的逻辑或错误算法）、错误处理（错误应被优雅处理而非被吞掉）、竞态条件（潜在并发问题）、数据校验（输入是否正确校验）、API 用法（是否正确高效地使用 API）。
2. 效率：避免不必要的循环、迭代或计算；警惕内存泄漏或低效数据结构；避免在性能关键路径上过度打日志。
3. 可维护性：命名要有描述性；识别过于复杂、应当重构的函数；寻找代码复用机会；遵循指定风格规范——并特别规定：当组织级与仓库级风格规范冲突时，永远优先并执行仓库级规范。
4. 安全性：敏感数据的不安全存储；注入攻击（SQL、命令等）；访问控制或校验不足。

该参考文件同时定义了四级严重程度，这是整篇评审输出的排序依据：

• critical：必须立即处理，可能给正确性、安全性或性能带来严重后果；
• high：应尽快处理，未来很可能引发问题；
• medium：应考虑的未来改进，不紧急也不关键；
• low：轻微或风格问题，可由作者自行决定。

最后是一份"关键约束"清单，与核心原则呼应：只评论以 + 或 - 开头的变更行；不写"空话"（fluff）；不写解释性评论（作者知道自己写了什么）；建议要简短可直接套用；建议必须是可编译的有效代码片段。

Step 4：批判与精炼（评审你的评审）

这是该工作流与"一次性生成"式 AI 评审最大的差异：对初版评论再做一遍自我批判，依据 critique_rules.md 过滤或修改评论。

应丢弃（drop）的评论——满足任一条件即丢弃：

• 评论不在实际变更的行上（diff 中以 + 或 - 开头的行）；
• 只是信息性的，解释代码在做什么；
• 是恭维性的（如 "Good job"、"Nice fix"）；
• 让用户去"check"、"confirm"、"verify" 或 "ensure" 某事，却没有指向具体问题；
• 超出了 SCM API 允许的行范围（out of bounds）。

应保留或修改的评论：

• 指出了真实问题或 bug；
• 内容可以更简洁或更可执行；
• 严重程度可以按指南调整得更准确。

该参考文件还给出了严重程度校准的"提醒清单"，防止评审者系统性地把小问题标高：

• 重构硬编码字符串/数字：一般 low；
• 日志消息或日志增强：一般 low；
• Markdown 文件中的注释：通常 medium 或 low；
• 添加/扩展文档字符串：通常 low；
• 抑制警告或 TODO：通常 low；
• 拼写错误：通常 low 或 medium；
• 测试文件：评论通常是 low，除非指向覆盖上的关键缺口。

对"代码建议"本身的质量，参考文件要求四条：建议要精确锚定到它打算替换的行；保留原始代码的缩进与空格；对目标语言而言可编译或至少语法正确；简短易懂。

Step 5：综合（最终评审）

把精炼后的评论合并为最终输出，具体动作包括：

• 去除重复的、重叠的评论；
• 高严重度问题（critical、high）优先；
• 生成一段总括摘要段落：最终输出以一段简洁的话开始，总结整体变更和评审的关键发现；
• 生成建议（recommendations）章节：汇总评审中发现的关键可执行建议；
• 生成文件摘要：多文件评审时，列出每个变更文件，用一句简洁的话描述其变更，以过去分词开头（如 "Added"、"Updated"）；
• 文件路径要写成 Markdown 链接；
• 最终输出保持连贯，并遵循 natural-writing 技能的写作规则。

输出格式：评审报告的固定结构

技能规定，最终综合出的评审必须写入会话 artifact 目录下的一个 Markdown 文件（例如 <appDataDir>/brain/<conversation-id>/ 中的 review_results.md），同时展示给用户。报告应包含四部分：

1. 高层摘要段落；
2. 文件摘要（如适用）；
3. 按严重度排序的评审评论列表；
4. 汇总关键可执行反馈的建议章节。

列表中的每条评论必须标注四个字段：

• File：文件路径；
• Line：行号（以 diff 为锚点）；
• Severity：critical、high、medium 或 low；
• Body：问题描述；
• Suggestion（可选）：具体的代码替换内容。

这种"文件 + diff 行号 + 严重度 + 正文 + 可选建议"的结构，使输出既能被人类直接阅读，也能被工具解析回贴到 PR 的具体行上。

大型 diff 的切分策略与 split_diff.py 实现

splitting_reviews.md 解释了何时以及如何切分评审。

何时切分：

• diff 很大（例如超过 500 行或超过 10 个文件）；
• 变更跨越多个不同组件或层（如前端、后端、数据库）；
• PR 包含多个不相关的功能或 bug 修复；
• 你注意到评审评论开始变得肤浅、对后面的文件遗漏细节。

切分策略分两个维度：

按文件或组件切分（最常见）：按目录评审（项目按功能/组件组织时）；按层评审（先数据库变更，再后端逻辑，再前端 UI，最后测试，顺序建立上下文）；按文件类型评审（核心逻辑文件与配置文件、文档分开）。

按关注点或视角做多轮评审：第一遍只看正确性与架构（代码是否做它该做的事、是否契合整体设计）；第二遍看风格与可维护性（可读性、命名约定、风格规范）；第三遍看安全与性能（漏洞与优化机会）。

工具支持：技能自带 Python 脚本 split_diff.py，支持从 stdin 或文件读取 diff，支持从 JSON 中提取 diff（当 diff 被包在 JSON 里时），并把 diff 按变更文件切分成独立文件写入指定输出目录。文档给出的用法示例：

python3 agents/skills/code-review/scripts/split_diff.py --output-dir scratch/diff_chunks < diff.txt

JSON 输入：

python3 agents/skills/code-review/scripts/split_diff.py --json --json-key diff --output-dir scratch/diff_chunks < input.json

从源码实现看，这个脚本的行为可以精确描述为：

• 切分标记优先使用 unified diff 的 diff --git 行：脚本用正则 ^(?=diff --git )（MULTILINE 模式）做前瞻切分；若整个输入里只有一个这样的切分块，则回退到 --- a/ 风格的 ^(?=--- ) 标记（见 split_diff.py 第 21–28 行）。
• 文件名提取优先匹配 ^diff --git a/(.*?) b/，回退匹配 ^--- a/(.*?)$；路径中的 / 会被替换为 _ 以避免子目录问题，完全无法识别时命名为 chunk_N.diff（第 36–45 行）。
• JSON 模式下，若未指定 --json-key，会依次尝试 diff、patch、content 三个常见键（第 9–18 行）；JSON 解析失败或找不到 diff 键都会向 stderr 报错并以非零码退出。
• 脚本最后打印 Successfully split diff into N files in <dir> 及每个"原始文件名 -> 切分文件"的映射摘要，方便评审者对照切分结果。

切分之后，各子评审的结果通过"综合"步骤（Step 5）合并，参考文件给出三条合并原则：去重（同一问题在多轮或文件中出现时不要重复报告，除非表现形态不同）；优先级（按严重度分组，critical 和 high 置顶）；连贯性（所有评论语气风格一致，遵循 natural-writing 技能）。

工作流全景与设计要点回顾

把整个技能串起来看，它实际上是把人类资深评审员的工作习惯编码成了对 LLM 的约束链：

1. 输入侧（Step 1–2）：先意图后代码，先 diff 后上下文，确保评论有仓库级依据而不是孤立看 hunk；
2. 生成侧（Step 3）：用 review_criteria.md 的四标准四严重度框定产出范围，"只评变更行、不夸、不解释"作为硬约束；
3. 质量门（Step 4）：用 critique_rules.md 做一遍"评审的评审"，把恭维、信息性、越界评论全部滤掉，并校准严重度；
4. 输出侧（Step 5）：固定四段式报告结构 + 五字段评论格式，保证结果可被人和工具共同消费；
5. 规模管理：splitting_reviews.md 与 split_diff.py 处理"上下文过载"这一 LLM 评审的固有短板；
6. 文字风格：natural-writing 贯穿生成与综合两个阶段，保证评审意见本身可读。

这套结构对复用也有直接参考价值：若要在其他项目中落地类似的 AI 评审能力，最小可复制单元就是"SKILL.md 五步流程 + review_criteria.md 的严重程度定义 + critique_rules.md 的丢弃规则"这三件套，外加一个按 diff --git 标记切分 diff 的脚本；而 reidbaker-agent 的 agent.json/config.yaml 则展示了如何把技能挂到具体 Agent 上——通过 skills_paths 指向本地技能目录、通过 skills-lock.json 锁定外部技能来源与内容哈希，保证评审所依赖的最佳实践参考是可追溯、可校验的。