SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场flutter-verification

flutter-verification

测试与质量

查看项目

更新于 10-16 02:11

技能介绍

用途

Flutter Verification 用于在开发者或智能体声称 Flutter 工作“已完成”“已修复”或“通过”之前，强制要求先运行验证命令并确认输出。其核心原则是：证据先于声明，始终如此。违反规则的字面要求，就是违反规则的精神。

核心法则

没有新鲜的验证证据，不得做出完成声明。如果在本条消息中没有运行验证命令，就不能声称它通过。

注意：这是一项由工作流强制执行的智能体纪律约定，而非机械门控——flutter-craft 仅提供一个 SessionStart 钩子，因此工具层面不会阻止过早的完成声明。该规则仅在智能体遵守时才成立。

Flutter 验证命令

1. 静态分析（始终必需）

flutter analyze

预期输出：

Analyzing <project>...
No issues found!

如果发现问题：

Analyzing <project>...
   info • ... • lib/path/file.dart:42:10 • ...
   warning • ... • lib/path/file.dart:50:5 • ...

3 issues found. (1 warning, 2 hints)

2. 单元测试（优先级 1 和 2）

# 所有测试
flutter test

# 特定功能测试
flutter test test/features/<feature>/

# 特定测试文件
flutter test test/features/<feature>/data/repositories/user_repository_test.dart

预期输出：

00:05 +12: All tests passed!

如果测试失败：

00:03 +10 -2: Some tests failed.

3. 构建验证（仅在收尾阶段运行一次——不是每次完成声明都运行）

仅针对项目实际的目标平台运行：

# Android
flutter build apk --debug

# iOS（仅 macOS）
flutter build ios --debug --no-codesign

# Web
flutter build web

# 桌面
flutter build windows / macos / linux

预期输出（示例，Android）：

✓ Built build/app/outputs/flutter-apk/app-debug.apk (XX.XMB)

4. 格式检查（可选）

dart format --set-exit-if-changed lib/

门控函数

在声称任何状态或表达满意之前：

  1. 识别：什么命令能证明这个声明？
  2. 运行：执行完整命令（新鲜、完整）
  3. 读取：完整输出，检查退出码，统计失败数
  4. 验证：输出是否确认了声明？
    • 如果否：用证据说明实际状态
    • 如果是：用证据说明声明
  5. 只有到这时：才做出声明

跳过任何一步 = 撒谎，而不是验证。

常见 Flutter 失败

声明 需要 不充分
“代码是干净的” flutter analyze：无问题 “我写了正确的代码”
“测试通过” flutter test：全部通过 “应该通过”“看起来正确”
“构建成功” flutter build：构建成功 “分析通过了”
“功能完成” 所有验证 + 需求检查 “测试通过”
“Bug 已修复” 测试原始症状 + 验证 “代码已更改”
“Widget 正常工作” Widget 测试或手动验证 “代码看起来正确”

危险信号——停止

如果你发现自己想或说：

  • “现在应该能工作了”
  • “大概能通过”
  • “看起来正确”
  • “我有信心”
  • “就这一次”
  • “分析通过了，所以构建也能工作”
  • “代码是对的”
  • 任何暗示成功但未运行验证的措辞

停止。运行验证命令。

验证清单

在声称完成之前：

验证结果

静态分析：

$ flutter analyze
Analyzing flutter_app...
No issues found!

✅ 通过

单元测试：

$ flutter test test/features/<feature>/
00:05 +12: All tests passed!

✅ 12/12 通过

构建：

$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk

✅ 构建成功

准备声称完成。

关键模式

静态分析：

✅ [运行 flutter analyze] [看到：No issues found!] “分析通过” ❌ “代码看起来很干净” / “我写对了”

测试：

✅ [运行 flutter test] [看到：34/34 通过] “所有测试通过” ❌ “现在应该通过了” / “测试看起来正确”

构建：

✅ [运行 flutter build] [看到：构建成功] “构建通过” ❌ “分析通过了”（分析不检查构建）

功能完成：

✅ 重读计划 → 验证每个需求 → 运行所有验证 → 报告 ❌ “测试通过，功能完成”

合理化预防

借口 现实
“现在应该能工作了” 运行 flutter analyze/test
“我有信心” 信心 ≠ 证据
“就这一次” 没有例外
“分析通过了” 分析 ≠ 构建 ≠ 测试
“代码看起来正确” 独立验证
“我累了” 疲惫 ≠ 借口
“这是简单代码” 简单代码也可能失败

为什么这很重要

  • 信任：如果你没有运行测试就声称“测试通过”，信任就被破坏了
  • 时间：虚假完成 → 返工 → 重做浪费所有人的时间
  • 质量：未验证的代码可能在生产环境中崩溃
  • 诚信：诚实是核心价值

何时应用

始终在以下情况之前：

  • 任何形式的成功/完成声明
  • 任何满意表达（“完成！”“修复了！”“能用了！”）
  • 提交代码
  • 创建 PR
  • 移动到下一个任务
  • 向用户报告

底线

验证没有捷径。

运行命令。读取输出。然后声称结果。

# 在声称完成之前始终运行这些：
flutter analyze
flutter test

这是不可协商的。

每次完成声明并不需要完整的 flutter build——它很慢且依赖平台。它只在 flutter-finishing 中针对项目实际目标平台运行一次。

5. 视觉验证（可选——Flutter Web）

对于包含 UI 更改的工作，如果安装了 design-polish 插件，则执行视觉验证。如果未安装，跳过此步骤（SOFT_FAIL）。

前提条件

  • 已安装 design-polish 插件（~/.claude/plugins/marketplaces/design-polish 或 ~/.claude/plugins/design-polish）
  • scripts/capture.cjs 存在
  • Node.js + npx 可用

流程

构建 Flutter Web：

flutter build web

在本地提供构建输出：

npx serve build/web -l 3000 &
SERVER_PID=$!

截图 + WCAG 检查：

BASE_URL=http://localhost:3000 node <design-polish-path>/scripts/capture.cjs --wcag /

检查结果：

  • .design-polish/health-score.json：设计健康分数（0-100）
  • .design-polish/accessibility/wcag-report.json：WCAG 违规
  • .design-polish/screenshots/current-main.png：当前截图

停止服务器：

kill $SERVER_PID 2>/dev/null

判定标准

结果 条件 操作
PASS 0 个 WCAG 违规，健康分数 ≥ 60 完成
WARN 1-3 个 WCAG 违规（轻微/中等） 建议改进，不阻塞
FAIL 存在严重 WCAG 违规 建议修复（SOFT_FAIL：不阻塞）
SKIP 未安装 design-polish 跳过

证据记录

视觉验证：

  • 健康分数：85/100
  • WCAG：0 违规
  • 截图：.design-polish/screenshots/current-main.png ✅ 视觉检查通过（或 ⚠️ 跳过 / ⚠️ 发现警告）