@ohos-cpf/3rdloop 0.0.12 → 0.0.13

package/vendor/Server/Skills/flutter-demo-code-generator/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: flutter-demo-code-generator
+description: 根据 Flutter 三方库的 Demo 描述文档生成可编译运行的测试 Demo Dart 代码。每个 Demo 独立页面（{三位序号}_{snake_case} 目录 + {描述}_page.dart 文件），统一主导航入口；代码含 dev.log 日志、try/catch 错误处理、mounted 检查与 dispose 资源释放，遵循 Flutter/Dart 最佳实践；支持通过 MCP 接口提取工具校验接口真实性，产物可通过 flutter build hap 构建到鸿蒙设备。当需要将 Flutter 测试 Demo 描述文档（*Flutter测试demo描述.md）转化为可运行工程代码时使用。
+license: Apache-2.0
+compatibility: 需要 Flutter SDK（≥3.0）与鸿蒙 Flutter 工具链（flutter build hap）；可选 MCP Gateway 运行中（script_flutter_extract_interfaces 接口真实性校验、script_flutter_analyze_demo_coverage 覆盖率验证、kb_search 知识检索）
+metadata:
+  author: LoopEngine
+  version: "2.0.0"
+  category: code-generation
+  language: Dart/Flutter
+  upstream-skill: ohos-flutter-demo-code-generator@1.0.0
+---
+
+# Flutter Demo Code Generator — Flutter 测试 Demo 代码生成
+
+读取 Flutter 三方库的 Demo 描述说明文档，为每个 Demo 生成独立的 Dart 页面实现与统一主导航，产物可通过 `flutter build hap` 编译，并在鸿蒙设备上正确运行、展示三方库的功能和使用方法。
+
+> ⚠️ **核心原则（强制）**
+> 1. **接口真实性**：所有代码必须基于描述文档与库源码中真实存在的接口，严禁凭空捏造接口、参数或行为。提供库源码时必须先经 Phase 2 校验。
+> 2. **数量一致**：Demo 页面数量必须与描述文档条目数量完全一致，严禁以任何理由减少、合并或跳过。
+> 3. **命名规范**：目录 `{三位补零序号}_{snake_case}`（如 `001_check_support`），文件 `{snake_case}_page.dart`，类名 `{UpperCamelCase}Page`。
+> 4. **Flutter 最佳实践**：`const` 构造优化、`setState` 最小化、`try/catch(e, stack)` 错误处理、`await` 后 `mounted` 检查、`dispose` 资源释放、`dev.log` 日志全覆盖。
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `docPath` | string | ✅ | Demo 描述文档路径（`*Flutter测试demo描述.md`，含名称/步骤/预期结果/接口） |
+| `projectDir` | string | ✅ | 目标 Flutter 工程根目录（含 `lib/` 与 `pubspec.yaml`，可 `flutter pub get`） |
+| `libroot` | string | ❌ | 三方库源码根目录（含 `lib/` 与 `pubspec.yaml`），用于 Phase 2 接口校验与 Phase 5 覆盖率验证 |
+| `packageName` | string | ❌ | 三方库包名（如 `flutter_video_player`），不传时从 pubspec.yaml dependencies 推断 |
+
+---
+
+## 输入依赖
+
+- **前置SKILL（可选）**: `flutter-interface`（产出的接口规格文档可作为接口校验的替代输入）
+- **输入文件**: Demo 描述文档（通常由 Demo 描述文档生成技能产出）
+- **输入工程**: 已配置目标三方库依赖的 Flutter 工程
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 输入解析与工程探查
+    ↓
+Phase 2: 接口真实性校验（MCP，有库源码时）
+    ↓
+Phase 3: Demo 页面代码生成（逐个）
+    ↓
+Phase 4: 主导航与应用入口生成
+    ↓
+Phase 5: 质量校验（脚本 + analyze + 覆盖率）
+    ↓
+Phase 6: 汇总输出
+```
+
+---
+
+## Phase 1：输入解析与工程探查
+
+### 1.1 解析 Demo 描述文档
+
+读取 `docPath` 全文，提取：
+
+- **库基本信息**（名称、版本）— 用于日志 TAG 与类名推导
+- **Demo 条目表** — 每行的序号、中文名称、描述、步骤、预期结果、对应函数接口
+- **接口覆盖矩阵** — 每个接口所属的 Demo
+
+> 表格字段映射、中文名→英文 snake_case 推导规则、接口签名解析规则、步骤→UI 控件映射规则，参见 [Demo 描述文档解析规范](references/DEMO_DOC_PARSING.md)
+
+### 1.2 探查 Flutter 工程
+
+1. 列出 `projectDir`，确认 `lib/`、`pubspec.yaml` 存在
+2. 读取 `pubspec.yaml`：获取工程名（用于 import 路径）；确认目标三方库已在 `dependencies` — **不在则提示用户先添加依赖并终止生成，不得继续**
+3. 查看 `lib/` 现有代码组织，记录已存在文件；若 `main.dart` 已存在且内容复杂，记录待 Phase 4 处理
+4. **定位库的真实导出路径**：读取库的 `pubspec.yaml` 或 `lib/` 主导出文件，确定 `package:{包名}/{文件}.dart` 导入路径，**禁止猜测导入路径**
+
+### 1.3 建立文件规划表
+
+内部规划（不写入输出）：主入口 `lib/main.dart`、主导航 `lib/pages/demo_home_page.dart`、每个 Demo 的 `lib/pages/{序号}_{描述}/{描述}_page.dart`。
+
+> 规划表格式参见 [Demo 描述文档解析规范](references/DEMO_DOC_PARSING.md) 第 6 节
+
+---
+
+## Phase 2：接口真实性校验（有 `libroot` 时执行）
+
+> **目标：把"严禁捏造接口"变成工具保障。** 描述文档中的每个接口签名必须与库源码实际导出一致。
+
+### 2.1 调用 MCP 工具提取接口规格
+
+调用 MCP 脚本工具 `script_flutter_extract_interfaces`，传入参数：
+
+- `libroot`: 三方库源码根目录
+- `output`: 接口规格 JSON 输出路径（建议 `{projectDir}/.demo-gen/interface-spec.json`）
+
+### 2.2 逐一比对接口签名
+
+将描述文档中的接口与规格 JSON 比对：
+
+| 比对结果 | 处理方式 |
+|----------|----------|
+| 匹配 | 记录到规划表，Phase 3 直接使用 |
+| 签名不一致（参数/返回值） | 以源码规格为准，向用户说明差异后再生成 |
+| 接口不存在 | 标记为可疑接口，向用户确认后删除或替换，**禁止直接生成调用** |
+
+### 2.3 无 `libroot` 时回退
+
+1. 读取工程内依赖的库源码（path 依赖或 `.pub-cache` 中包目录）的主导出文件人工核对
+2. 两者都不可用时继续生成，但**必须在 Phase 6 输出报告中明确标注"接口未经源码校验"**
+
+---
+
+## Phase 3：Demo 页面代码生成
+
+对每个 Demo 条目，生成对应的 Dart 页面文件。
+
+### 3.1 推导命名
+
+| 序号 | 中文 Demo 名称 | 目录名 | 文件名 | 类名 |
+|------|--------------|--------|--------|------|
+| 1 | 环境检测与版本查询 Demo | `001_check_support` | `check_support_page.dart` | `CheckSupportPage` |
+| 2 | 控制器初始化与资源释放 Demo | `002_controller_lifecycle` | `controller_lifecycle_page.dart` | `ControllerLifecyclePage` |
+| 3 | 播放控制与进度管理 Demo | `003_playback_control` | `playback_control_page.dart` | `PlaybackControlPage` |
+
+规则：序号三位补零保证排序；snake_case 描述 3-5 个单词体现核心功能；同一文档内目录名不得重复；辅助 Widget/数据类可在同目录添加（`{snake_case}_widget.dart` / `{snake_case}_model.dart`）。
+
+### 3.2 按接口类型选择代码模式
+
+| 接口类型 | 模式要点 | 模板位置 |
+|----------|----------|----------|
+| 异步（返回 `Future`） | Loading 状态 + `await` 后 `mounted` 检查 + 单次合并 `setState` | [assets/PAGE_TEMPLATES.md](assets/PAGE_TEMPLATES.md) 模板一 |
+| 同步（无 `Future`） | `try/catch(e, stack)` + `setState`，无 Loading，无需 mounted 检查 | 模板二 |
+| 监听器/回调/Stream | `StreamSubscription` 非响应式声明 + 双计数器诊断 + 回调内 mounted 检查 | 模板三 |
+
+### 3.3 代码质量要求（逐条强制检查）
+
+| 要求 | 检查标准 |
+|------|---------|
+| 日志覆盖 | `initState`/`dispose` 有 `dev.log`；每个操作方法入口/成功/异常有日志；异常传 `error` + `stackTrace` |
+| 错误处理 | 所有异步调用用 `try/catch(e, stack)` 包裹，错误经 `setState()` 更新到 UI |
+| 资源释放 | `dispose()` 中释放库实例、取消 StreamSubscription、清理 Timer，最后调用 `super.dispose()` |
+| mounted 检查 | 所有 `async` 方法 `await` 之后、`setState()` 之前必须 `if (!mounted) return`；Stream/Future 回调同理 |
+| setState 最小化 | 只在状态变量更改时调用；Loading 与结果同批合并到一次 `setState()` |
+| const 优化 | 不依赖运行时状态的 Widget 使用 `const` 构造 |
+| 注释完整性 | 文件头 Dart doc（序号/功能说明/接口签名列表）+ 方法 doc 注释 + 关键逻辑行内注释 |
+| UI 完整性 | AppBar 标题 + 功能说明卡片 + 操作控件区（按 Demo 步骤生成）+ CircularProgressIndicator + `SelectableText` 结果区 |
+| 无魔法字符串 | 日志 Tag 使用常量 `_kTag`，格式 `{LibraryName}_{ComponentName}` |
+| 无残留占位 | 无 TODO/FIXME 或空占位注释，需填充实际内容 |
+
+> 完整规范（类型声明、Null Safety、Widget 提取、日志位置速查表）参见 [Flutter Demo 代码规范速查](references/CODE_STANDARDS.md)
+
+### 3.4 知识检索（可选）
+
+生成过程中遇到不确定的 Flutter/Dart 用法时，调用 MCP 内置工具 `kb_search` 检索知识库：
+
+- 一次查询一个关键词（如 `Flutter mounted setState`、`Dart StreamSubscription 取消`）
+- 返回不相关时调整关键词重试，最多 3 轮
+- 命中的最佳实践精简融入代码，引用时标注来源
+
+---
+
+## Phase 4：主导航与应用入口生成
+
+### 4.1 生成 lib/pages/demo_home_page.dart
+
+- 文件级 Dart doc 注释 + **按序号顺序 import 全部 Demo 页面**
+- 私有数据类 `_DemoEntry`：`id`（三位序号）、`title`（中文名称）、`description`（一句话描述）、`builder`（`WidgetBuilder`）
+- Demo 列表常量按序排列，**条目数量与描述文档严格一致**
+- 主页 Widget 为 `StatelessWidget`：`ListView.separated` 渲染，`Navigator.push` + `MaterialPageRoute` 跳转，跳转前记录 `dev.log`
+- 私有卡片 Widget `_DemoCard`：展示序号、标题、描述和右箭头图标
+
+> 完整模板参见 [assets/PAGE_TEMPLATES.md](assets/PAGE_TEMPLATES.md) 模板四
+
+### 4.2 处理 lib/main.dart
+
+处理前**必须先检查 `lib/main.dart` 是否已存在**：
+
+| 场景 | 处理方式 |
+|------|----------|
+| 不存在 | 按模板生成（`home: DemoHomePage`、`useMaterial3: true`、`debugShowCheckedModeBanner: false`） |
+| 已存在且简单（仅 `runApp`） | 直接替换为标准模板 |
+| 已存在且复杂（含路由/多页面） | **不直接覆盖**，改为在现有 `home` 页面添加跳转 `DemoHomePage` 的入口按钮，向用户说明改动范围，确认后再写入 |
+
+> 完整模板参见 [assets/PAGE_TEMPLATES.md](assets/PAGE_TEMPLATES.md) 模板五
+
+---
+
+## Phase 5：质量校验
+
+### 5.1 接口覆盖完整性（人工核对）
+
+```
+□ 描述文档中每个 Demo 条目都对应生成了一个 Dart 页面文件
+□ 接口覆盖矩阵中每个接口都在对应页面代码中有实际调用
+□ 生成文件数量 = 描述文档 Demo 条目数量（不多不少）
+```
+
+### 5.2 运行自动化校验脚本
+
+```bash
+node {skillDir}/scripts/validate-flutter-demo.cjs {projectDir} {expectedDemoCount}
+```
+
+（MCP Gateway 模式传 JSON：`{"projectDir":"...","expectedDemoCount":N}`）
+
+脚本自动检查：目录/文件命名合规、`_kTag` 常量、`dart:developer` 导入、`initState`/`dispose` 完整性、`mounted` 检查、TODO/FIXME 残留、主导航 import 数量与 Demo 目录数一致、Demo 数量与预期一致。输出 `ALL CHECKS PASSED` 表示通过。
+
+### 5.3 编译预检
+
+提示用户执行（或环境允许时自动执行）：
+
+```bash
+cd {projectDir}
+flutter pub get
+flutter analyze
+flutter build hap
+```
+
+静态分析须确认：import 路径与 pubspec.yaml 一致、无未使用 import、无未定义引用、Null safety 正确（`?` / `!` / `??`）。
+
+### 5.4 覆盖率验证（可选，`projectDir` 为库仓库 `example/` 时）
+
+调用 MCP 脚本工具 `script_flutter_analyze_demo_coverage`，传入参数：
+
+- `libroot`: 三方库仓库根目录（其 `example/` 即本次生成的工程）
+- `output`: 覆盖率报告输出路径
+
+核对报告中未覆盖的接口是否属于本次描述文档范围之外（范围内的接口未覆盖说明生成有遗漏）。
+
+---
+
+## Phase 6：汇总输出
+
+完成所有文件生成与校验后，向用户输出汇总信息：
+
+```
+生成完成！共生成 {N} 个 Demo 页面文件。
+
+📁 文件清单：
+  lib/main.dart                                       ← 应用入口（已更新/新生成）
+  lib/pages/demo_home_page.dart                       ← 主导航页
+  lib/pages/001_check_support/check_support_page.dart
+  lib/pages/002_controller_lifecycle/controller_lifecycle_page.dart
+  ...
+
+🔍 接口校验：{已通过 script_flutter_extract_interfaces 校验，M 个接口全部真实 | 未经源码校验（未提供 libroot）}
+✅ 质量校验：validate-flutter-demo.cjs {ALL CHECKS PASSED | 问题清单}
+📊 覆盖率：{报告路径与结论 | 未执行}
+
+▶ 验证步骤：
+  cd {projectDir}
+  flutter pub get
+  flutter analyze
+  flutter build hap
+```
+
+---
+
+## 参考资料
+
+- [Demo 描述文档解析规范](references/DEMO_DOC_PARSING.md) — 字段映射、命名推导、接口签名解析、步骤→UI 映射
+- [Flutter Demo 代码规范速查](references/CODE_STANDARDS.md) — 命名/日志/错误处理/资源管理/双计数器
+- [完整生成示例](references/EXAMPLES.md) — 基于 flutter_video_player 的端到端示例
+- [页面代码模板](assets/PAGE_TEMPLATES.md) — 异步/同步/监听器页面 + 主导航 + main.dart 模板
+- [自动化校验脚本](scripts/validate-flutter-demo.cjs) — 工程规范静态检查