用途：在 Flutter/Dart 项目中以确定性方式重新生成所有注解驱动的代码，适用于源文件带有 @freezed、@JsonSerializable、@riverpod、@DriftDatabase 或 drift 表注解，而对应的 .g.dart、.freezed.dart、*.drift.dart part 文件缺失或过期时。
主要能力与规则：先运行代码生成，再运行 flutter analyze；固定命令必须原样执行，不加参数、不手改生成文件。命令为 dart run build_runner build --delete-conflicting-outputs，需在包根目录（单包应用）或工作区根目录（多包仓库）执行。不要对生成文件执行 git add -f；watch 仅用于本地开发，不得用于 CI 或 pre-commit 钩子。生成器读取已解析的 AST，手写源码存在分析错误会阻断生成，应先修复手写源码。
标准流程：flutter pub get 解析依赖，然后运行上述固定命令重新生成，最后才执行 flutter analyze。新克隆、拉取或切换分支后跳过第二步是分析器报错的常见原因。
开发迭代：可在编辑注解源码时运行 dart run build_runner watch --delete-conflicting-outputs，但运行一次性构建前需先停止 watcher，避免两个 build_runner 进程竞争输出。
多包工作区：build_runner 按包运行，一次调用只重新生成当前包及其路径依赖包，不会自动覆盖所有同级成员；需要全量重新生成时使用仓库级 fan-out 包装器（如 melos run gen），或进入目标包目录单独执行。
限制与排错：分析器与代码生成不一致通常意味着磁盘输出落后，应重新运行固定构建并重启分析服务器，不要修改调用点；生成文件内报错说明文件过期或分析器排除配置有误，应重新生成而非手改；出现 conflicting outputs 时用 --delete-conflicting-outputs 清理重命名或删除源文件留下的陈旧输出。
完成标准：固定命令在包/工作区根目录无冲突错误地运行，且在 flutter analyze 之前执行并使其通过；没有手改或强制添加生成文件；CI 或钩子中未接入 build_runner watch。相关技能包括 codegen-and-toolchain、run-migration、ci-pipeline-and-gates、lint-and-style-config。参考链接：build_runner（https://pub.dev/packages/build_runner）、Dart build_runner 用法（https://dart.dev/tools/build_runner）、drift codegen（https://drift.simonbinder.eu/docs/getting-started/）、freezed（https://pub.dev/packages/freezed）、riverpod_generator（https://pub.dev/packages/riverpod_generator）。