用途
本技能用于对 Flutter/Dart 项目执行结构化、客观的代码审查，遵循一套可重复的检查清单。适用场景包括：被要求审查 pull request、merge request 或分支；评估新增、修改或删除文件的正确性与质量；在合并前审计 diff；检查新代码是否符合项目标准。
审查工作流
第 1 步 — 校验分支与合并目标
确认当前分支是功能、缺陷修复或 PR/MR 分支，而非项目主分支（如 main、master、develop）。验证分支与目标分支保持同步（无未解决冲突）。识别合并的目标分支。检查点：若分支落后于目标分支，在继续前标记出来。
第 2 步 — 发现变更
列出所有变更、新增和删除的文件。对每项变更，查找提交标题并审查相关组件的实现方式。分析变更：变更原因是否清晰？若不清晰，深入相关方法和文件直至弄清。报告时说明分析了哪些相关文件/方法及原因，以表明变更被理解而非假设。切勿在未调查实现的情况下假定变更正确。若调查后仍不清楚，在报告中明确注明。
第 3 步 — 逐文件审查
遍历每个变更文件，逐项验证：理解变更（为何做此变更，审查相关方法/文件并注明分析了哪些及原因）、位置（文件位于正确目录）、命名（文件名遵循项目命名约定）、职责（文件职责清晰，变更原因可理解）、可读性（变量、函数、类名具描述性且一致）、逻辑与正确性（无逻辑错误或遗漏边界情况）、代码坏味道（扫描下方参考表中的坏味道）、可维护性（代码模块化，无不必要重复）、错误处理（错误与异常处理得当）、安全（无输入验证缺口，无提交到代码中的密钥）、性能（无明显低效，如不必要的重建、大列表上的 O(n^2) 循环）、SOLID 原则（评估遵循情况，但不强加不必要的样板或过度抽象）、Flutter/Dart 模式（与项目已加载的指南和约定匹配）、文档（公共 API、复杂逻辑和新模块有文档）、测试覆盖（新增或变更逻辑有足够测试，见第 4 步）、风格（代码符合项目风格指南和 lint 规则）、既有代码（若新变更看起来没问题，也审查周边未变更的既有代码，发现坏味道时提出重构建议）。
对生成文件（如 .g.dart、.freezed.dart）：确认其为最新且未被手动修改。
范围纪律：任务不是对每处变更都评论，而是找出错误和具体改进点并就此评论。代码没问题时不要制造评论。
Flutter 专项检查
（以下仅为使用 Bloc/Cubit 的示例；对 Riverpod、Provider 或所选状态管理包应用类似原则。）
// BAD — 每次状态变化都重建整棵树
BlocBuilder<MyCubit, MyState>(
builder: (context, state) => EntireScreen(state: state),
);
// GOOD — 将重建范围限定到实际变化的 widget
BlocSelector<MyCubit, MyState, String>(
selector: (state) => state.title,
builder: (context, title) => Text(title),
);
验证动态生成 widget 上的 Key 使用。检查控制器、流和动画控制器是否调用了 dispose()。确认尽可能使用 const 构造函数。
代码坏味道参考
对每个文件检查常见代码坏味道。定义与建议重构参见 refactoring.guru/refactoring/smells。
- Bloaters（膨胀类）：Long Method、Large Class、Primitive Obsession、Long Parameter List、Data Clumps
- Object-Orientation Abusers（面向对象滥用）：Alternative Classes with Different Interfaces、Refused Bequest、Temporary Field、Switch Statements
- Change Preventers（变更阻碍）：Divergent Change、Parallel Inheritance Hierarchies、Shotgun Surgery
- Dispensables（可丢弃）：Comments（冗余）、Duplicate Code、Data Class、Dead Code、Lazy Class、Speculative Generality
- Couplers（耦合）：Feature Envy、Inappropriate Intimacy、Incomplete Library Class、Message Chains、Middle Man
第 4 步 — 评估整体变更集
验证变更集聚焦且限定于其声明的目的，无无关变更。检查 PR/MR 描述是否准确反映变更。
测试覆盖：明确验证测试覆盖——这容易被跳过也容易被伪造，因此要有意为之：对任何新逻辑或重大变更，搜索对应测试文件并确认测试确实存在；检查测试覆盖变更功能包括边界情况，而非仅快乐路径；评估测试是否真能对真实代码失败，还是仅验证 mock 行为（断言 mock 返回被告知返回的内容的测试证明不了任何东西）。若测试缺失或不足，就覆盖不足发表评论，不要让其静默通过。
第 5 步 — 验证 CI 与测试
确保所有测试在 CI 中通过。检查是否有新的分析器警告或 lint 违规。对包的最佳实践不确定时获取官方文档。检查点：若 CI 为红或新逻辑缺少测试，标记为阻塞问题。
收尾
逐文件审查后决定结果：若一切良好且无需变更，发布总体结论评论，总结 MR 内容（做了什么）及任何观察，并批准 MR；若新变更干净但在既有代码中发现坏味道，将其作为可选重构建议而非阻塞项；若发现问题，清晰总结关键关注点，让作者知道优先处理什么。
反馈标准
客观合理，避免自动赞美或奉承。采取魔鬼代言人方式：给出诚实、深思熟虑的反馈。对每个发现的问题提供清晰、建设性的建议。对任何不清楚之处请求澄清。按严重程度分类每个发现：suggestion、minor 或 major。
输出格式
默认以聊天回复形式提供审查——覆盖每个文件的结构化回复：
- Summary — 变更内容及原因。
- Issues — 每项含严重程度（suggestion / minor / major）和具体修复建议。
- Questions — 每个文件的具体澄清请求。
- Verdict — 以下之一：Approved、Approved with suggestions 或 Changes requested。
在线发布评论（仅限主动选择加入）。在呈现聊天审查后，询问用户是否希望也将这些评论在线发布到 PR/MR，以便团队查看、审查和回复。仅在用户明确同意后才在线发布。切勿自行主动发布到平台。
当用户选择加入时，将问题作为内联评论锚定到正确的文件和行（使用正确的 position 字段），将结论/关键关注点作为顶层审查评论，并在必要时批准。这需要平台（GitHub/GitLab）的 review-bot 访问令牌；若未配置，告知用户并要求其在发布前设置。
令牌安全。令牌是机密。可以检查其是否存在并报告长度以确认已配置，但绝不读取、回显、记录、打印或以其他方式泄露令牌值——不在聊天中、不在文件中、不在提交中。仅通过引用环境变量（如 $GITLAB_TOKEN）将令牌传给 curl，绝不内联字面值，并避免 curl -v/--verbose（它会打印认证头）。这由 PreToolUse 钩子（scripts/protect-token.sh）强制执行，该钩子会阻止任何可能暴露该值的 Bash 命令。各参考文件的“Handling the token safely”部分说明了安全的存续/长度检查。
该钩子在 Claude Code CLI 和 Agent SDK 中均会触发。（显式设置 settingSources/setting_sources 的 SDK 应用必须包含 "project" 才能加载技能钩子；默认已包含。）
平台特定 API 细节、curl 格式和批准步骤，请遵循：
- GitLab → references/gitlab-posting.md（使用 GITLAB_TOKEN 环境变量）
- GitHub → references/github-posting.md（使用 GITHUB_TOKEN 环境变量）
适用场景与限制
适用于 Flutter/Dart 项目的代码审查，尤其是 PR/MR、分支或 diff 的审查与合并前审计。限制：在线发布评论需用户明确同意且需配置平台访问令牌；令牌值不得以任何形式泄露；具体平台 API 细节需参考对应参考文件。