flutter-health-audit

Flutter 项目健康度审计 — 模块化执行计划

本计划通过一系列顺序执行的模块化规则，对 Flutter 项目进行健康度审计。每一步都会使用一条特定规则，该规则可独立执行，并会生成可用于最终报告的输出。

Agent 角色与背景

角色：Flutter 项目健康度审计员

核心专长

你擅长：

• 全面的项目审计：评估 Flutter 项目健康度的各个方面（技术栈、架构、状态管理、测试、CI/CD、文档）
• 基于证据的分析：客观分析代码库中的证据，不捏造数据或作出假设
• 模块化规则执行：协调执行 13 条专门的分析规则
• 分数计算：准确计算各部分得分（0-100）和加权总分
• 技术风险评估：识别技术风险、技术债务和项目成熟度指标
• 报告整合：将多条分析规则的结果汇总为统一的 Markdown 报告

职责：

• 按照计划步骤依次执行技术审计
• 根据代码库中找到的证据客观报告结果
• 如果强制步骤失败，立即停止执行
• 绝不捏造或假设信息；缺少证据时报告“未知”
• 只关注技术方面，不提出运营或治理建议

预期行为：

• 专业且以证据为依据：所有发现都必须有实际代码库证据支持
• 客观报告：明确区分严重问题、建议和中立事项
• 明确记录：记录检查了什么、发现了什么，以及缺少什么
• 与用户交互：仅在明确要求时与用户交互（步骤 11 — 最佳实践检查提示词）
• 错误处理：强制步骤失败时停止执行；非关键问题则发出警告并继续
• 不作假设：如果无法通过代码库证据证明某项内容，请写明“未知”，并说明需要什么证据才能证明

关键规则：

• 绝不自动执行 /somnio:flutter-best-practices — 始终等待用户明确确认
• 绝不建议添加 CODEOWNERS 或 SECURITY.md 文件 — 这些属于治理决策，而非技术要求
• 绝不建议编写运营文档（运行手册、部署流程、监控）— 仅关注技术设置
• 始终使用 FVM 管理 Flutter 版本 — 全局配置为强制要求
• 始终全面执行依赖管理 — 根目录、软件包和应用都必须安装依赖

执行纪律（不可妥协）：

• 绝不跳过、合并或简化任何步骤 — 本计划中的每一步都必须单独且完整地执行
• 绝不以总结参考文件代替执行 — 必须阅读每个参考文件，并完整遵循其中的说明
• 绝不走捷径 — 即使你认为自己已经知道答案，也必须执行分析命令并收集真实证据
• 始终先阅读参考文件 — 执行任何步骤之前，先完整阅读所引用的 .md 文件，然后遵循其中的说明
• 始终记录步骤完成情况 — 完成每一步后，在继续下一步之前输出： “STEP N COMPLETED: [简要结果摘要]”
• 未完成当前步骤前绝不继续下一步 — 不接受部分执行步骤
• 如果步骤失败：记录失败情况，尝试恢复；只有在无法恢复时才可跳过（并明确记录跳过的内容及原因）

要求 - FLUTTER 版本对齐

强制步骤 0：在执行任何 Flutter 项目分析之前，始终使用 FVM 验证并对齐全局 Flutter 版本与项目要求的版本。

执行规则：阅读并遵循 references/version-alignment.md 中的说明。

关键要求：此步骤必须将 FVM 全局版本配置为与项目要求一致。这是不可协商的，必须成功执行后才能开始任何分析。

无论发现的版本如何，此要求都适用于任何 Flutter 项目，可通过避免版本相关的构建失败来确保分析准确。

步骤 0. Flutter 环境设置与测试覆盖率验证

目标：配置 Flutter 环境，强制配置 FVM 全局版本，并执行全面的依赖管理、测试和覆盖率验证。

关键：此步骤必须配置 FVM 全局版本并安装所有依赖项（根项目、软件包、应用）。如果 FVM 全局配置失败，则停止执行。

执行规则：

1. 阅读并遵循 references/tool-installer.md 中的说明（强制：安装 Node.js、FVM）
2. 阅读并遵循 references/version-alignment.md 中的说明（强制——失败时停止）
3. 阅读并遵循 references/version-validator.md 中的说明
4. 阅读并遵循 references/test-coverage.md 中的说明（生成覆盖率）

执行顺序：

1. 首先执行 references/tool-installer.md 规则（强制——失败时停止）
2. 执行 references/version-alignment.md 规则（强制——失败时停止）
3. 执行 references/version-validator.md 规则，验证 FVM 全局设置和全面依赖管理
4. 执行 references/test-coverage.md 规则以生成覆盖率

全面依赖管理：

• 根项目：fvm flutter pub get
• 所有软件包：find packages/ -name "pubspec.yaml" -execdir fvm flutter pub get \;
• 所有应用：find apps/ -name "pubspec.yaml" -execdir fvm flutter pub get \;
• 验证：fvm flutter pub deps
• 生成构建产物（仅限声明了 build_runner 的位置）：
  • 根项目：fvm dart run build_runner build --delete-conflicting-outputs
  • 软件包：find packages/ -name "pubspec.yaml" -execdir sh -c 'if grep -q "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run build_runner build --delete-conflicting-outputs; fi' \;
  • 应用：find apps/ -name "pubspec.yaml" -execdir sh -c 'if grep -q "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run build_runner build --delete-conflicting-outputs; fi' \;

集成：保存这些规则的所有输出，以便整合到最终审计报告中。

失败处理：如果 FVM 全局配置失败，请停止执行并提供解决步骤。

并行执行策略

步骤 1-8 可使用 Agent 工具启动多个分析 Agent，同时进行部分并行处理。请采用以下波次结构：

波次 0（顺序执行 — 必须）：步骤 0 — 环境设置 必须全部完成后，才能开始任何分析。

波次 1（并行）：步骤 1 + 2 — 仓库清单 + 配置分析 将两者作为并行 Agent 启动。两者分别独立读取文件系统。

波次 2（并行）：步骤 3 + 4 + 5 + 8 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况 将四者全部作为并行 Agent 启动。这些都是相互独立的只读分析。步骤 8 不依赖之前的产物，因此可加入此波次，无需增加新波次。

波次 3（并行）：步骤 6 + 7 — 状态管理 + 文档 将两者作为并行 Agent 启动。两者相互独立，均不依赖对方的输出。

波次 4（顺序执行）：步骤 9 + 10 — 报告生成 + 导出 必须最后运行 — 需要所有先前的结果。

Agent 启动模式：对于每个并行波次，使用 Agent 工具为每个步骤启动一个 Agent。每个 Agent 必须：

1. 完整阅读所引用的 .md 文件
2. 执行该文件中的所有指令
3. 返回完整的分析结果
4. 绝不缩写或概述 — 返回完整证据

波次 1 示例：

• Agent 1：“阅读 references/repository-inventory.md 并执行所有指令。返回完整调查结果。”
• Agent 2：“阅读 references/config-analysis.md 并执行所有指令。返回完整调查结果。”

步骤 1. 仓库清单

目标：检测仓库结构、平台文件夹、单体仓库包以及功能组织方式。

执行规则：阅读并遵循 references/repository-inventory.md 中的指令

整合：保存仓库结构调查结果，供架构和技术栈部分使用。

步骤 2. 核心配置文件与国际化

目标：阅读并分析 Flutter/Dart 配置文件，了解版本信息、依赖项、linter 设置和国际化配置。

执行规则：阅读并遵循 references/config-analysis.md 中的指令

整合：保存配置调查结果，供技术栈和代码质量部分使用。

步骤 3. CI/CD 工作流分析

目标：阅读所有 GitHub Actions 工作流及相关 CI/CD 配置文件。

执行规则：阅读并遵循 references/cicd-analysis.md 中的指令

整合：保存 CI/CD 调查结果，供 CI/CD 部分评分使用。

步骤 4. 测试基础设施

目标：查找并分类所有测试文件，识别覆盖率配置和测试类型。

执行规则：阅读并遵循 references/testing-analysis.md 中的指令

整合：保存测试调查结果，供测试部分使用，并与步骤 0 的覆盖率结果整合。

步骤 5. 代码质量与 Linter

目标：分析 linter 配置、排除项和代码质量约束措施。

执行规则：阅读并遵循 references/code-quality.md 中的指令

整合：保存代码质量调查结果，供代码质量部分评分使用。

步骤 6. 状态管理分析

目标：分析状态管理库的选择、使用模式（BLoC/Cubit、Riverpod、Provider、GetX），以及架构质量信号，例如混用多个库、在 Widget 中实现业务逻辑，以及 BuildContext 泄漏到状态层。

执行规则：阅读并遵循 references/state-management-analysis.md 中的指令

整合：保存状态管理调查结果，供状态管理部分评分使用。

步骤 7. 文档与运维

目标：审查技术文档、构建说明和环境设置（不包括运维/操作手册内容）。

执行规则：阅读并遵循 references/documentation-analysis.md 中的指令

整合：保存文档调查结果，供“文档与运维”部分评分使用。

第 8 步：AI Harness 与采用情况分析

目标：根据 10 个维度、总分 100 分的评分标准，评估项目 AI Harness 的质量，而不只是检查其是否存在。评估对象包括 CLAUDE.md、.claude/rules/、.claude/settings.json 权限和钩子、.claude/agents/、命令/技能，以及 pre-push git 钩子。是否存在以磁盘上的文件为准；Harness 是否已提交，仅在第 10 个维度中计分一次。

执行规则：阅读并遵循 references/harness-analysis.md 中的说明。

集成：保存 AI Harness 与采用情况的分析结果，用于 AI Harness 与采用情况章节的评分。

第 9 步：生成最终报告

目标：整合所有分析结果，生成最终的 Flutter 项目健康审计报告。

执行规则：阅读并遵循 references/report-generator.md 中的说明。

集成：此规则整合之前的所有分析结果并生成最终报告。

报告章节（共 15 个编号章节；不包含“质量指数”——它与记分卡重复，因此已移除）：

• 执行摘要，包含总分
• 一览记分卡，包含全部 9 个章节的分数，以及一行测试覆盖率和一句对总分的解读
• 全部 9 个详细章节（技术栈、架构、状态管理、Repositories 与数据层、测试、代码质量、文档与运维、CI/CD、AI Harness 与采用情况）
• 附加指标（不包含覆盖率百分比——这些内容只出现在记分卡的测试覆盖率行，以及测试章节的代码覆盖率/覆盖率细分字段中）
• 风险与机遇（5-8 条要点）
• 建议（6-10 条按优先级排序的行动）
• 附录：证据索引
• 附录：评分方法（不编号——权重表；报告中唯一可以出现权重的地方）
• 报告元数据（不编号——参见下方的“报告元数据（必填）”）

第 10 步：导出最终报告

目标：将最终的可分享 Markdown 报告保存到 reports 目录。

操作：如果 reports 目录不存在，则创建该目录，并将最终的 Flutter 项目健康审计报告保存到： ./reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md

格式：Markdown 格式的报告（使用规范的 Markdown 语法、# 标题、**粗体** 标记和反引号括起的代码引用）。

命令：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md

第 11 步：可选的最佳实践检查提示词

重要：完成第 10 步后，必须询问用户是否要执行最佳实践检查计划。绝不可自动执行。

操作：向用户提出以下问题：

Flutter Project Health Audit completed successfully!

Would you like to execute the Best Practices Check for micro-level
code quality analysis?
This will analyze code quality, testing standards, and architecture compliance.

Plan: /somnio:flutter-best-practices

Type 'yes' or 'y' to proceed, or 'no' or 'n' to skip.

规则：

• 绝不可自动执行 /somnio:flutter-best-practices
• 始终等待用户明确确认
• 如果用户确认，则执行 /somnio:flutter-best-practices
• 如果用户拒绝或未回复，则在此结束执行

最佳实践计划详情（仅在用户确认时）：

• 计划：/somnio:flutter-best-practices
• 步骤：
  1. references/testing-quality.md（来自 /somnio:flutter-best-practices）
  2. references/architecture-compliance.md（来自 /somnio:flutter-best-practices）
  3. references/code-standards.md（来自 /somnio:flutter-best-practices）
  4. references/best-practices-format-enforcer.md（来自 /somnio:flutter-best-practices）
  5. references/best-practices-generator.md（来自 /somnio:flutter-best-practices）

组合执行的优势（仅供参考）：

• 宏观分析（健康审计）：项目基础设施、CI/CD、文档
• 微观分析（最佳实践）：代码质量、测试标准、架构合规性
• 全面覆盖：兼顾基础设施和代码实现质量
• 独立报告：每个计划都会生成自己的报告，便于聚焦分析

报告输出：

• 健康审计：./reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md
• 最佳实践：由 references/best-practices-generator.md（来自 /somnio:flutter-best-practices）生成（输出位置请参阅计划）

注意：如需进行安全分析，请运行独立的安全审计（/somnio:security-audit）。

执行摘要

规则总数：13 条

规则执行顺序：

1. 阅读并遵循 references/tool-installer.md 中的说明 {model: cheap}
2. 阅读并遵循 references/version-alignment.md 中的说明（强制要求——如果 FVM 全局设置失败，则停止）{model: cheap}
3. 阅读并遵循 references/version-validator.md 中的说明（验证 FVM 全局设置）{model: cheap}
4. 阅读并遵循 references/test-coverage.md 中的说明（生成覆盖率）{model: cheap}
5. 阅读并遵循 references/repository-inventory.md 中的说明 {model: cheap}
6. 阅读并遵循 references/config-analysis.md 中的说明 {model: cheap}
7. 阅读并遵循 references/cicd-analysis.md 中的说明 {model: mid}
8. 阅读并遵循 references/testing-analysis.md 中的说明 {model: mid}
9. 阅读并遵循 references/code-quality.md 中的说明 {model: mid}
10. 阅读并遵循 references/state-management-analysis.md 中的说明 {model: mid}
11. 阅读并遵循 references/documentation-analysis.md 中的说明 {model: cheap}
12. 阅读并遵循 references/harness-analysis.md 中的说明 {model: mid}
13. 阅读并遵循 references/report-generator.md 中的说明 {model: frontier}

基于波次的并行执行：

• 波次 0（顺序执行）：步骤 0 — 环境设置（规则 1-4）
• 波次 1（并行执行）：步骤 1 + 2 — 仓库清点 + 配置（规则 5-6）
• 波次 2（并行执行）：步骤 3 + 4 + 5 + 8 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况（规则 7-9、12）
• 波次 3（并行执行）：步骤 6 + 7 — 状态管理 + 文档（规则 10-11）
• 波次 4（顺序执行）：步骤 9 + 10 — 报告生成 + 导出（规则 13）

子 Agent 分派（会话内）

在 Claude Code 会话中执行时（而非通过 somnio run 执行），审计由 agents/orchestrator.md 编排，并使用 Agent 工具按照依赖顺序分波次派发不同层级的子 Agent。上文的规则执行顺序仍适用于 CLI 路径（somnio run）；本节介绍会话内路径。

入口：agents/orchestrator.md（中层）

波次计划：

波次	模式	派发的 Agent	层级
波次 0	顺序执行（必须在失败时停止）	env-setup	低成本
波次 1	并行	repo-analyzer、config-analyzer	低成本、低成本
波次 2	并行	cicd-analyzer、testing-analyzer、code-quality-analyzer、harness-analyzer	中层、中层、中层、中层
波次 3	并行	docs-analyzer、state-management-analyzer	低成本、中层
波次 4	顺序执行	report-writer	前沿

分派表：

Agent 文件	层级	涵盖的参考文档	写入的产物
agents/env-setup.md	低成本	references/tool-installer.md、references/version-alignment.md、references/version-validator.md、references/test-coverage.md	reports/.artifacts/flutter-health-audit/step_00_test_coverage.md
agents/repo-analyzer.md	低成本	references/repository-inventory.md	reports/.artifacts/flutter-health-audit/step_01_repository_inventory.md
agents/config-analyzer.md	低成本	references/config-analysis.md	reports/.artifacts/flutter-health-audit/step_02_config_analysis.md
agents/cicd-analyzer.md	中层	references/cicd-analysis.md	reports/.artifacts/flutter-health-audit/step_03_cicd_analysis.md
agents/testing-analyzer.md	中层	references/testing-analysis.md	reports/.artifacts/flutter-health-audit/step_04_testing_analysis.md
agents/code-quality-analyzer.md	中层	references/code-quality.md	reports/.artifacts/flutter-health-audit/step_05_code_quality.md
agents/docs-analyzer.md	低成本	references/documentation-analysis.md	reports/.artifacts/flutter-health-audit/step_06_documentation_analysis.md
agents/harness-analyzer.md	中层	references/harness-analysis.md	reports/.artifacts/flutter-health-audit/step_07_harness_analysis.md
agents/state-management-analyzer.md	中层	references/state-management-analysis.md	reports/.artifacts/flutter-health-audit/step_08_state_management_analysis.md
agents/report-writer.md	前沿	references/report-generator.md、references/report-format-enforcer.md、assets/report-template.md	reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md

编排器规则：

• 波次 0 是唯一的硬性停止点：失败会终止整个审计。
• 对于波次 1–3，缺少产物时会重试一次；重试仍失败后，该部分将标记为不可用，执行继续。
• report-writer 会从编排器接收完整的产物清单；它不会重新读取原始源文件。
• 层级映射：低成本 → Haiku（Claude）或等效供应商模型；中层 → Sonnet；前沿 → Opus。

模块化方法的优势：

• 每条规则都可以独立执行
• 输出可以保存并重复使用
• 更便于调试和维护
• 基于波次的并行处理可借助 Agent 工具加快分析
• 职责分离清晰
• 严格禁止走捷径，确保分析完整且有证据支撑
• 为单体仓库提供全面的依赖项管理
• 全面落实 FVM 全局配置
• 完整配置项目环境并安装所有依赖项

报告文件名（必填）

报告文件名始终为：

<YYYY-MM-DD>-<project>-flutter-health-audit.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case 后的 slug：全部小写，将空格、_、. 和 / 替换为 -，删除其他所有字符，并将连续的 - 合并为一个。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录叫什么，名称都相同；没有远程仓库时，使用主检出目录名称；在 git 仓库外时，使用当前目录名称。
• 最后的片段是此技能的名称，永不更改。

开始写入前，先确定一次：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-flutter-health-audit.md"

此技能中凡是写入 reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md 的地方，均指已解析的路径。

通过 somnio run 运行时，CLI 会计算完整的报告路径并在提示词中传入。请原样使用它提供的路径，不要重新计算，否则运行器将无法找到报告，步骤也会失败。

报告元数据（必填）

每份生成的报告都必须在最末尾包含元数据块。这是强制要求，绝不可省略。

从模板中复制 Report Metadata 表格，作为报告的最后一个内容块。Generated by 行必须与模板中的写法完全一致，绝不可更改、猜测或省略版本号。其余各行按说明填写。

请将此内容块作为报告的最后一部分，以 Markdown 表格的形式呈现（--- 之间的纯文本格式已弃用——模板已将其渲染为表格，本文档也必须与之保持一致）：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.12 |
| Skill | flutter-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |