Flutter 仓库 reidbaker-agent 代码评审准则详解：四大审查维度、严重度分级与硬性约束

本文围绕 Flutter 仓库 reidbaker-agent 代码评审技能中的核心参考文档 review_criteria.md，完整拆解其四大评审维度（正确性、效率、可维护性、安全）、四级严重度体系以及五条硬性约束，并结合 SKILL.md 定义的五步评审工作流、critique_rules.md 的评论过滤规则与 split_diff.py 大 diff 拆分脚本，还原一套可直接用于 Flutter/Dart 项目 Pull Request 评审的完整方法论。读完本文，你将掌握：如何按优先级组织评审关注点、如何给每条反馈定级、如何用约束条款过滤无效评论，以及大 PR 场景下的拆分与合并策略。

一、评审准则文档在 reidbaker-agent 中的定位

review_criteria.md 是 code-review 技能 的参考文档之一，该技能定义了一套"生成 → 批判 → 综合"（generation, critique, synthesis）的迭代式评审工作流，目标是产出彻底、可执行、格式规范的评审反馈，同时规避 AI 评审的典型陷阱——比如"看起来不错"式的评论，或在未改动的行上发表评论。

在 SKILL.md 的五步工作流中，这份准则文档被直接引用为第三步行（"Generate Initial Review"）的评审依据：

### Step 3: Generate Initial Review

Generate review comments focusing on the following criteria:

- **Correctness**: Verify functionality, handle edge cases, check API usage.
- **Efficiency**: Identify bottlenecks, redundant calculations.
- **Maintainability**: Assess readability, adherence to style guides.
- **Security**: Identify potential vulnerabilities.

对应的工作流五步为：

1. Step 1 Gather Changes（收集变更）：GitHub PR 场景用 gh pr view 读标题与描述、用 gh pr diff 取变更；本地场景用 git status、git diff、git diff --staged 或 git log -p。
2. Step 2 Context Enrichment（上下文补全）：评审 diff 前先识别需要一并查看的文件——被 import 的文件、父类与接口、相关工具文件、与变更对应的测试文件；diff 过大时按 splitting_reviews.md 拆分子评审。
3. Step 3 Generate Initial Review（生成初版评论）：即使用本文讲解的评审准则，逐项聚焦正确性、效率、可维护性、安全四个维度。
4. Step 4 Critique and Refine（评审评审）：用 critique_rules.md 的规则自审过滤，确保评论只落在 diff 中以 + 或 - 开头的行上、不含有信息性/夸赞性内容、代码建议可编译且缩进与目标代码一致。
5. Step 5 Synthesis（综合输出）：去重、按严重度排序（critical/high 优先）、生成高层摘要段落、建议清单和逐文件变更摘要（每个文件一句话，以过去时动词如 "Added"、"Updated" 开头），文件路径以 Markdown 链接形式书写。

reidbaker-agent 本身是一个采用"Expert"人格、预置 code-review 与 natural-writing 等专项技能的智能体，见其 README。其技能目录由 npx skills experimental_install 按 skills-lock.json 安装，本地托管在 skills/ 目录下。

二、优先级评审维度详解

准则文档开头即声明其用途："outlines the criteria to prioritize when performing a code review"。四个维度按重要性排序，前两个维度聚焦"代码是否做对了、做得快"，后两个维度聚焦"代码能否长期存活"。以下逐项展开原文内容，并补充在 Flutter 仓库语境下的落点。

1. Correctness（正确性）

Verify code functionality, handle edge cases, and ensure alignment between function descriptions and implementations.

正确性被放在第一位，包含五个具体检查点：

• 逻辑错误（Logic errors）：检查有缺陷的逻辑或错误的算法。
• 错误处理（Error handling）：确保错误被优雅处理、不被静默吞掉。
• 竞态条件（Race conditions）：排查潜在的并发问题。
• 数据校验（Data validation）：验证输入是否被正确校验。
• API 使用（API usage）：确保 API 被正确且高效地使用。

其中"function descriptions and implementations 一致"这一条要求评审者对照文档注释与实际实现：如果一个 getter 声称返回不可变副本却直接返回内部可变更引用，属于此类问题。在 Flutter 仓库中，评审时还需要叠加仓库自身的强约束，例如 .agents/rules/dart-editing.md 中声明的层依赖规则：

• material (package:flutter/material.dart ... ) can only be used in material code and tests (packages/flutter/lib/src/material/ and packages/flutter/test/material/).
• cupertino ... can only be used in cupertino code and tests.

该规则文件标注 trigger: always_on，即在 Dart 编辑场景中始终生效；违反层依赖的变更在正确性维度即可定级为需要拦截的问题。同文件还要求任务完成前运行 dart analyze --fatal-infos <files> 并 dart format 修改过的文件，这为"API 使用是否合规"提供了可验证的命令级依据。

2. Efficiency（效率）

Identify performance bottlenecks and optimize for efficiency.

效率维度的三条要点：

• 避免不必要的循环、迭代或计算；
• 警惕内存泄漏或低效的数据结构；
• 避免在性能关键路径上过度打日志。

对 Flutter 项目而言，这几条有非常具体的对应场景：在构建阶段（build 方法）执行可缓存的计算、在 build 中分配对象、在高频帧路径里做冗长日志，都属于该维度关注的"瓶颈与冗余计算"。评审时不必给出微基准数据（准则也未要求量化），但应指出"这段计算在每次 build 都会执行且结果可缓存"这类可执行的观察。

3. Maintainability（可维护性）

Assess code readability, modularity, and adherence to language idioms.

可维护性维度包含四个常规检查点和一条冲突裁决规则：

• 命名（Naming）：变量、函数、类是否具有描述性名称；
• 复杂度（Complexity）：识别过于复杂、应当重构的函数；
• 代码重复（Code duplication）：寻找复用机会；
• 风格（Style）：遵循既定风格指南，违规必须被指出；
• 风格指南冲突（Style Guide Conflict）：当组织级与仓库级风格指南冲突时，永远优先并执行仓库级风格指南中规定的规则。

最后一条是本准则文档中唯一显式的"裁决条款"，在多仓库、多团队共用组织级规范的环境中尤为关键。在 Flutter 仓库中，仓库级风格即根目录 analysis_options.yaml 及其引入的 analysis_options_common.yaml（根配置第一行即为 include: analysis_options_common.yaml），以及上文提到的 dart-editing.md。从源码结构看，根 analysis_options.yaml 还明确说明了排除规则（如 bin/cache/**、engine/**）与 analyzer 插件须在子包级配置的注意事项——评审"风格违规"时应以这套实际生效的配置为准，而不是评审者个人的偏好。

4. Security（安全）

Identify potential vulnerabilities.

安全维度列出三类常见漏洞面：

• 敏感数据的不安全存储；
• 注入攻击（SQL、命令注入等）；
• 访问控制或校验不足。

在 Flutter 应用上下文中，典型的对应问题包括：把令牌写入明文共享存储、将用户输入拼接进 shell 命令或 SQL 语句、未校验的深链参数直接驱动导航或权限提升。准则将安全列为第四优先级，意味着在初版生成阶段也要覆盖，但最终综合时其具体问题的严重度按第三节的分级规则定档。

三、四级严重度体系（Severity Levels）

准则文档要求用统一的四级严重度归类所有发现：

级别	原文定义	语义
critical	Must be addressed immediately. Could lead to serious consequences for correctness, security, or performance.	必须立即处理；可能给正确性、安全或性能带来严重后果
high	Should be addressed soon. Likely to cause problems in the future.	应尽快处理；未来很可能引发问题
medium	Should be considered for future improvement. Not critical or urgent.	值得作为后续改进考虑；不紧急
low	Minor or stylistic issues. Can be addressed at the author's discretion.	轻微或风格问题，由作者自行裁量

配套文档 critique_rules.md 在"Severity Guidelines (Reminders)"一节给出了具体定级锚点，可视为对四级体系的操作性解释：

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

这些锚点的价值在于消除评审者之间的定级漂移：同样是"命名不够好"，按锚点应落 low；而测试文件中的问题默认不应喧宾夺主。SKILL.md 的 Step 5 进一步要求最终输出中"Prioritize high-severity issues (critical, high)"，即按严重度排序、高危置顶。

四、五条硬性约束（Critical Constraints）

准则文档的最后一节是五条不可协商的输出约束，直接决定评审反馈是否"可用"：

1. Only comment on changed lines（只评论变更行）：评论只能指向 diff 中以 + 或 - 开头的行。评审一个 diff 时指出未改动行的问题，属于越界。
2. No fluff（拒绝客套）：不得添加"这是个好改进"之类的评论；只在存在改进机会时才评论。
3. No explanations（拒绝解释）：不得添加解释"这段代码做了什么"或"验证它有效"的评论——作者清楚自己写的内容。
4. Succinct suggestions（建议要简练）：代码建议应短小且可直接应用。
5. Compilable suggestions（建议必须可编译）：代码建议必须是可直接落地的有效代码片段。

这五条约束与 critique_rules.md 的过滤规则一一对应：一条评论若落在未变更行上、仅是信息性说明、是恭维（如 "Good job"、"Nice fix"）、是空洞的"请检查/确认/确保 X"而不指向具体问题、或超出 SCM API 允许的行范围，就应被丢弃；若它指出了真实问题、可以更简练、或严重度需要校正，则保留或修改。代码建议部分还要求"精确锚定到被替换的行、保持原有缩进与空格、语法可编译、简洁易懂"。

五、大 diff 场景：拆分评审与脚本支持

当 diff 规模超出单次上下文的有效处理范围时，splitting_reviews.md 给出了拆分判据与策略。

何时拆分：

• diff 很大（例如超过 500 行或超过 10 个文件）；
• 变更跨越多个独立组件或层（前端、后端、数据库）；
• 单个 PR 包含多个不相关的特性或修复；
• 注意到自己的评论在后面的文件里开始变得肤浅、遗漏细节。

两种拆分策略：

• 按文件或组件：按目录（项目按特性组织时逐文件夹评审）、按层（数据库 → 后端 → 前端 UI → 测试，便于顺序建立上下文）、按文件类型（核心逻辑与配置/文档分开）；
• 按关注点分多轮：Pass 1 只做正确性与架构；Pass 2 只做风格与可维护性；Pass 3 只做安全与性能。

工具支持：仓库自带脚本 split_diff.py，支持从 stdin 或文件读入 diff、从 JSON 中提取 diff（--json，可用 --json-key 指定键，缺省时尝试 diff/patch/content 三个常见键），并按文件拆分写入输出目录。实现上它先按 diff --git 标记做正则切分（re.split(r"^(?=diff --git )", ...)），找不到该标记时退回 --- 标记；文件名中的 / 会被替换为 _ 以保证落盘安全，无法识别文件名的块则命名为 chunk_N.diff。用法示例：

# 纯 diff 输入
python3 .agents/agents/reidbaker-agent/skills/code-review/scripts/split_diff.py --output-dir scratch/diff_chunks < diff.txt

# JSON 包裹的 diff 输入
python3 .agents/agents/reidbaker-agent/skills/code-review/scripts/split_diff.py --json --json-key diff --output-dir scratch/diff_chunks < input.json

拆分后的子评审通过 Step 5 的综合步骤合并：去重（同一问题跨轮次/跨文件只报一次，除非表现形式不同）、按严重度分组置顶、语气与风格保持一致。

六、写作规范：评审反馈的语言质量约束

SKILL.md 将 natural-writing 技能 列为所有评审文本的写作标准。该规范的核心是消除"AI 腔"：禁用高频 AI 词汇（如 delve、underscore、leverage、testimony 类名词与 pivotal、crucial 类形容词）、避免"serve as / stand as" 式的系动词替换、禁止在代码与注释中使用相对时间词（now、currently、old、new 等，因为随代码库演进而失效）、禁止夸大修辞与空洞的现在分词从句、标题用 sentence case、不使用表情符号与非常规列表符号、引号一律用直引号。

对评审实践而言，这条规范的实质约束是：评论文本应当短、平、准——与第四条约束"Succinct suggestions"互为表里。

七、落地清单：一次符合准则的评审流程

把文档内容与工作流组合起来，一次完整评审的可执行步骤为：

1. 收集变更：gh pr view + gh pr diff（PR）或 git diff / git diff --staged / git log -p（本地）；
2. 补全上下文：被引用的文件、父类/接口、工具文件、对应测试文件；diff 超过 500 行或 10 个文件时先跑 split_diff.py 拆分；
3. 按四大维度逐项生成评论：正确性（含层依赖等仓库规则）→ 效率 → 可维护性（风格冲突时以仓库级配置为准）→ 安全；
4. 逐条自审过滤：未变更行、信息性、恭维性、空洞"确保 X"、越界行范围的评论一律丢弃；按锚点校正严重度；
5. 综合输出：摘要段落 + 逐文件一句话变更摘要 + 按严重度排序的评论列表（文件、diff 锚定行号、severity、正文、可选的可编译代码建议）+ 建议汇总。

这套准则的显著特点是把"评审者行为"本身也纳入了规范对象——维度定义回答"看什么"，严重度体系回答"多重"，硬性约束与过滤规则回答"怎么说、说多少"，而拆分与综合策略保证了大变更下反馈质量的稳定。对 Flutter/Dart 项目而言，再叠加 dart-editing.md 的 dart analyze --fatal-infos / dart format 要求与根目录 analysis_options.yaml 的实际 lint 配置，这套准则就从纸面标准变成了与仓库工程链路对齐的评审基线。