---
name: sdk-hardemo-generator
description: "基于 04-test-cases.json 生成完整的 HAR Demo ETS 代码（三级页面 + ResultPanel），包括骨架生成和根据 PRD 公开 API 规格及测试信息填充完整的功能实现。"
---

# SDK HAR Demo 生成 Skill

## 执行前：Todo 清单（MANDATORY）

- [ ] Step 0：加载必要skill与知识准备
- [ ] Step 1：删除存量ohos-hardemo-auto，调用代码生成器生成骨架结构
- [ ] Step 2：根据 PRD 公开 API 规格和测试信息实现完整功能逻辑
- [ ] Step 3：FIXED SECTION 校验
- [ ] Step 4：增量编译验证与修复循环
- [ ] Step 5：生成 Demo 结果文件

## Step 0：加载必要skill与知识准备

### 加载必要skill（按顺序）

1. `android-sdk-to-arkts`
2. `arkts-rules`
3. `ohos-coding-guide` 涉及 Want / startAbility 页面跳转、蓝牙、文件处理、音视频播放、音视频录制、位置权限、动画、ArkTS API 易错点、await 异步调用竞态等场景读取。
4. 需要查鸿蒙工程、API、权限、设备能力或依赖规范时，使用 `harmonyos-docs-lookup` / `harmonyos-sdk-api-lookup` Skill。

### Demo 编码前知识准备与官方文档核实

先查阅 `ohos-coding-guide/arkui-state-reference.md`：

| Demo 场景 | 推荐章节 |
|----------|---------|
| 任何交互控件（必读） | 第六章（回调签名） + 第一章（装饰器规则） |
| 列表页 / 多项渲染 | 第五章（渲染控制） |
| 手势交互 / 拖拽 | 第七章（手势系统） |
| Demo 不生效 / 状态不刷新 | 第八章（常见坑 5 步定位） |
| @Builder / UI 复用 | 第四章（组件扩展） |
| 跨页面状态 / 全局配置 | 第二章（应用级状态） |

涉及到 HarmonyOS 系统 API 用法，不能编造，必须使用 `harmonyos-docs-lookup` / `harmonyos-sdk-api-lookup` / `ohos-coding-guide` Skill 查询相关知识。

以下内容不能凭 Android 经验或模糊记忆处理，必须通过本地 Skill 核实一次：

- HarmonyOS Kit 接入方式、模块名、import 路径、类型签名、枚举值、错误码和 syscap。
- 权限声明、动态授权、通知授权、受限权限、设置页引导。
- 应用沙盒目录、Context 路径、用户文件、公共目录、媒体库、Picker、安全控件、URI / fd / 持久化授权。
- `module.json5`、`oh-package.json5`、HAR 资源路径、HAR/HAP 相关配置。
- Want / `startAbility` 跳转、文件/沙盒/URI/Picker、蓝牙、定位、音视频、后台任务等场景化陷阱。

使用Skill检索方式：

- API 签名和类型：优先使用 `harmonyos-sdk-api-lookup`。
- 开发指导和场景规则：优先使用 `harmonyos-docs-lookup` 与 `ohos-coding-guide`。
- Native/NAPI：使用 `arkts-native-bridge` 及其 details。
- 原生三方库 OHPM 包详情 / 依赖关系：按需使用 `native-library-substitution` 做正向查询；用途是补齐包信息和辅助构建修复，不是重新改写 02 已确定的主方案。
- 华为生态能力：使用 `huawei-ecosystem-compliance`，并按其 Coding 章节读取对应 `docs/*-integration.md` 指南后再落代码。
- `ohos-coding-guide`，涉及 Want / startAbility 页面跳转、蓝牙、文件处理、音视频播放、音视频录制、位置权限、动画、ArkTS API 易错点、await 异步调用竞态等场景时

如果官方文档与 02 规划冲突，以官方文档为准。

再查阅 `${SKILLS_ROOT_ABS}/ohos-coding-guide/ui-coding.md`，编码前先读以下板块：

- **C 板块（第 346–520 行）**：Demo 控件绑定模式（必读，每个 Demo 交互控件必须按 C 板块的模板回写 @State）
- **D 板块**：按下方表格确认需要读哪些章节：

| 如果 HAR 组件或 Demo 涉及... | 必须读 D 板块 |
|----------------------------|-------------|
| Dialog/Popup/Modal | D1 — CustomDialog 规则 |
| 列表/ForEach 渲染 | D2 — ForEach key 规则 |
| Canvas/自绘组件 | D3 + D5 — 自绘坐标 + Canvas/像素 |
| RelativeContainer | D4 — RelativeContainer 规则 |
| 旋转动画/颜色值转换 | D5 — Canvas/像素/旋转 |
| @BuilderParam 插槽 | D6 — @BuilderParam 上下文 |
| 遮罩/浮层/overlay/抽屉/zIndex 层叠 | D7 — Stack 层叠触摸 |


## Step 1：删除存量ohos-hardemo-auto，调用代码生成器生成骨架结构

**先删除当前android sdk库下的ohos-hardemo-auto目录（若有）**

```bash
python ".claude/skills/sdk-hardemo-generator/tool/generate_hardemo_ets.py"
```

生成三级页面结构：
- **第一级** Index.ets：功能模块列表（F-01、F-02...）
- **第二级** ModuleF##Page.ets：测试用例列表
- **第三级** TestCaseF##_##Page.ets：测试用例详情页

输出：pages/*.ets + widgets/ResultPanel.ets + widgets/TestInfoPanel.ets

---

## Step 2：根据 PRD 公开 API 规格和测试信息实现完整功能逻辑

**严格执行以下实现步骤**：
---
1. step1已将ohos-hardemo/library（若有）的内容拷贝到现有的ohos-hardemo-auto/library，**后续测试用例的实现都要基于ohos-hardemo-auto，绝不允许在ohos-hardemo实现**。禁止修改除了ohos-hardemo-auto/library/Index.ets的library下的其他文件。
2. 实现该步骤必须先阅读**参考资料**、**实现要求**和**常见错误**。之后对每个测试用例详情页 pages/TestCaseF##_##Page.ets，实现完整的功能逻辑; 根据测试步骤中的 API 调用信息，创建对应的操作按钮和实现逻辑，确保每个操作都能满足测试用例的预期结果。当测试用例数量 ≥ 5 时，必须使用 Task 工具**批量**实现，避免逐个编辑导致超时。
3. 权限声明和同步（该步骤必须，否则影响真机验证）：
**权限声明规则**：
- 需要查权限时，使用 `harmonyos-docs-lookup` / `harmonyos-sdk-api-lookup` Skill，禁止凭 Android 经验或模糊记忆类推（如剪贴板权限是 `READ_PASTEBOARD` 而非 `READ_CLIPBOARD`）
- HAP 权限声明以 `entry/src/main/module.json5` 为准；`library/module.json5` 不能替代 entry 声明。
- `ohos.permission.INTERNET` 等 `system_grant` 权限不需要运行时申请，但必须声明，并通过 HAR 的真实网络/系统能力调用验证。
- 定位、相机、麦克风、蓝牙扫描等 `user_grant` 权限必须使用真实 `UIAbilityContext` 请求；禁止用 `new Object()`、空对象或伪 context 传给 HAR/host contract。
- 若 HAR 通过 host contract 委托权限或设备开关，Demo 必须实现该 contract，并在调用 HAR 能力前先执行授权/开关检查；不能只声明 contract 类型但不接到页面流程。
- 权限被拒绝、系统开关关闭或 context 不可用时，Demo 必须停止本次 HAR 能力调用并展示可读状态，不得显示固定成功。

**权限同步规则**
此为补充项，防止权限遗漏，详见`references/resource-mapping.md`中**权限声明同步**

4. **运行实现完整性检查脚本**（MANDATORY - 禁止跳过）：
    ```bash
    python ".claude/skills/sdk-hardemo-generator/tool/check_implementation_status.py" \
      --test-cases ".ohos-adaptation/04-test-cases.json" \
      --pages-dir "ohos-hardemo-auto/entry/src/main/ets/pages"
    ```
    脚本输出 `PASS: 所有测试用例已实现` 才可继续
    若输出 `FAIL: 有X个测试用例未实现`，必须逐一完成未实现文件后再继续
    **判定标准**：Actions区不含"待实现"/"TODO(actions)"占位符，且有实际控件（Button/Toggle/Checkbox/Slider/TextInput/Image等）或预览组件
---

**参考资料**：
- 阅读 01-analysis-prd.md 的第 3 章公开 API 规格
- 阅读 .ohos-adaptation 目录下的测试用例 JSON 文件中的测试用例信息
- 阅读生成的 pages/TestCaseF##_##Page.ets 中的测试信息（优先级、前置条件、测试步骤、预期结果），位于TestInfoPanel
- 阅读../primary-sdk-04-har-demo.md 中 “3.3 Demo 编写原则（必读）”“步骤 4：Demo 运行态质量门禁（必做）”和“步骤 5：直板机与视觉（必读）”
- 不用阅读ohos-hardemo/entry的实现，因为开发demo的实现可能不正确

**实现要求**：

---
### 测试信息区（FIXED - 禁止修改）

禁止行为：删除TestInfoPanel、修改参数名/值、替换为自定义组件

正确：`TestInfoPanel({ level: 'L0', preconditions: '...', test_steps: '...', expected_result: '...', postconditions: '' })`

错误：`Text('用例ID: F-01')` ← 禁止

**TestInfoPanel布局要求**：内部Column必须设置`.alignItems(HorizontalAlign.Start)`，确保"测试步骤"等内容左对齐，与其他字段一致。


### Action区设计规范（MANDATORY）

1. 操作流程设计规范
---
**Action区操作流程需严格按照测试步骤（从第3点起）设计**

每一页 TestCasePage 的 TestInfoPanel.test_steps 中，步骤 1~2 为导航（忽略），
步骤 3 之后的每条步骤中“【】”中的内容为 Actions 区**必须出现**的 UI 元素，**不允许出现**除【】中的内容之外的UI元素。

解析规则举例（对于不在例子中的【】，也要映射为对应的Action区生成物）：

| test_steps 中的模式 | Actions 区生成物 |
|---|---|
| `在【xxx】输入框中输入...` | `Text('xxx')` 标签 + `TextInput` |
| `在【xxx】下拉菜单中...` | `Text('xxx')` 标签 + `Select([...])` 下拉菜单 |
| `点击【xxx】按钮` | `Button('xxx')` |
| ... | ... |

**严格约束：**
- Actions 区按钮的 **text 必须与【】内的名称一致**（例：`点击【匹配】按钮` → `Button('匹配')`，不得写成 `Button('执行测试操作')`）
- 输入框/下拉菜单必须有对应的 `Text('xxx')` 标签文字描述
- 步骤中每一个【】名词都必须一对一映射为 UI 元素，不允许遗漏，也不可一对多
- 禁止使用占位按钮名
- 不允许出现除【】中的内容之外的UI元素

**校验方式**：
对每个 TestCasePage，提取 test_steps 中第 3 条起所有【】内的名词，
确认 Actions 区存在对应的 Button('xx') 或 Text('xx') + TextInput/Select。

**示例代码**见 references/code-patterns.md 中的“Action区示例代码” 示例代码一、二
---

2. 边界用例设计规范
---
- 边界测试用例可能需要输入负数、小数等特殊值，需根据测试步骤预判，输入校验应在逻辑层（onChange/onClick）完成，而非依赖 UI 层类型限制（例如在UI层依旧使用 InputType.Normal 而非 InputType.Number）
- 设计的方法不要在`onChange`中即时响应，需要区分中间输入状态和最终确认状态。例如`onChange`只更新输入显示，`onClick/onSubmit/onBlur`执行边界检查和业务逻辑

**示例代码**见 references/code-patterns.md 中的“Action区示例代码” 示例代码三、五
---

3. 回调逻辑设计规范
---
- onClick职责单一：onClick 回调只负责调用 API、更新 result、触发一次性操作。禁止修改与视觉样式相关的 @State 变量
- 临时状态管理：按压态等临时状态由 onTouch(TouchType.Down/Up/Cancel) 管理，Up/Cancel 时必须恢复
- 组件事件绑定规范（MANDATORY）：
  - 当组件内部已定义事件处理器（如 onClick、onTouch）时，外部禁止使用同名方法覆盖
  - 必须使用组件提供的回调属性接口（如 onItemClick、onTouchStateChange）接收事件通知
  - 覆盖组件内部事件会导致：动画不触发、状态不更新、内部逻辑失效
- 组件尺寸约束规范（MANDATORY）：
  - 当组件内部已定义固定尺寸（width/height）时，外部禁止设置更小的尺寸覆盖，例如列表场景下，多个 ListItem 因尺寸冲突会导致内容叠加显示

**示例代码**见 references/code-patterns.md 示例代码四、六、七
---

4. 输入控件状态绑定规范
---
- **状态声明**：每个 TextInput 必须绑定对应的 @State 变量，变量名建议为 `inputXxx` 或对应字段名
- **onChange 必须保存输入**：onChange 回调必须将输入值保存到 @State 变量，空回调（如 `onChange((v) => {})`)是严重实现缺陷
- **计算时使用绑定值，不得硬编码**：onClick 等 API 调用必须使用 `this.inputXxx` 状态值，不得硬编码字符串
- **TextInput 绑定模式**：`TextInput({ text: this.inputXxx })` 实现双向显示，onChange 保存输入

**典型错误模式**：
```typescript
// ✗ 错误：onChange 空回调，输入被丢弃
TextInput({ text: '' })
  .onChange((v: string) => { })

// ✗ 错误：distance 调用使用硬编码字符串
Button('计算')
  .onClick(() => {
    ngram.distance('night', 'day');  // 不是用户输入
  })
```

**示例代码**见 references/code-patterns.md 示例代码九
---

5. HAR API 调用前必须核实签名：
- HAR 库方法调用前，必须查阅 `library/src/main/ets/core/` 下的源码确认是方法还是属性。例如若获取长度是方法而不是属性：`length()`，则必须加 `()`
- 错误表现：模板字符串输出 `"Cannot get source code"` 而非预期值

**示例代码**见 references/code-patterns.md 示例代码十

6. 资源类API禁止硬编码ID：
- 对于有编译器生成的资源ID，禁止硬编码数值如 `Res.getColor(0x01060001)`
- 正确方式：在资源文件定义资源名，使用 `getXxxByName('name')` 或 `$r('app.color.xxx')` 获取

### result区设计规范（MANDATORY）

result **必须覆盖** test_steps 中所有包含了"观察【XXX】"的步骤中的要求，遗漏即为实现缺陷。

| 观察点类型 | result 必须包含 |
|-----------|----------------|
| 数值显示 | 具体数值 |
| 文本显示 | 对应文本 |
| 状态显示 | 状态值 |
| ... | ... |

观察点的结果在result中禁止硬编码，需真实返回

**示例代码**见 references/code-patterns.md 中的“Action区示例代码” 示例代码八

其他要求详见references/result-format.md


### 资源依赖同步（必须同步，否则影响真机验证）

扫描所有 `.ets` 代码中的资源引用（`getRawFileContent('xxx')`、`$r('app.media.xxx')` 等），从原项目对应目录（`res/drawable/`、`res/raw/`、`assets/`、`sample/` 等，需将res目录下内容全部剖析）定位源文件，复制到鸿蒙目标目录。映射关系见 `references/resource-mapping.md`。例如 `getRawFileContent('wallace.jpg')` → 源文件 `res/drawable/wallace.jpg` → 目标 `entry/src/main/resources/rawfile/wallace.jpg`。**验证**：确认目标文件存在后才算完成此步骤；缺失资源文件将导致真机运行时原图/配置加载失败。
---

**常见错误**：
见references/common-errors.md

## Step 3：FIXED SECTION 校验

```bash
python ".claude/skills/sdk-hardemo-generator/tool/validate_fixed_section.py"
```

检查：TestInfoPanel导入、组件调用、参数值与test-cases.json一致

校验失败必须修正后才可进入Step 4。


## Step 4：增量编译验证与修复循环（MANDATORY - 编译必须通过才算完成，禁止未实际执行就写 pass）

1. **hvigorw 查找方式**：
   - Windows / PowerShell 下禁止使用 `where hvigorw` 或 `where.exe hvigorw` 判断工具是否存在；必须使用 `Get-Command hvigorw`
2. **运行命令**
```bash
cd ohos-hardemo-auto
ohpm install
hvigorw assembleHap --mode module -p module=entry@default -p product=default --no-daemon
```

**编译失败时修改entry侧代码，循环直至退出码为0**。

最终验证：检查HAP产物 + 功能验证 + 所有用例确认

## Step 5：生成结果文件

生成：
1. **生成.ohos-adaptation/05-demo-gen.json**：
- 包含 Demo 生成的状态、结果、统计信息
   - 格式示例：
   ```json
   {
     "status": "success",
     "message": "Demo App 生成成功",
     "generatedAt": "2026-03-28T10:00:00+08:00",
     "statistics": {
       "modules": 2,
       "testCases": 10,
       "p0TestCases": 5,
       "generatedFiles": 15
     },
     "generatedFiles": [
      ...
     ]
   }

2. **生成.ohos-adaptation/05-demo-gen-report.md**：
   - 包含 Demo 生成的详细报告
   - 格式示例：
   ```markdown
   # Demo 生成报告

   ## 生成状态
   - 状态：成功
   - 生成时间：2026-03-28 10:00:00

   ## 生成统计
   - 功能模块数：2
   - 测试用例数：10
   - P0 测试用例数：5
   - 生成文件数：15

   ## 生成文件列表
   ...

   ## 验证结果
   - 编译状态：通过
   - P0 测试用例验证：全部通过

   ## 注意事项
   - Demo App 已成功生成，可以在 OHOS 真机上安装运行
   - 请按照 README.md 中的说明进行测试
   ```

## 参考文件
- references/code-patterns.md：完整示例代码
- references/result-format.md：result格式速查表
- tool/generate_hardemo_ets.py：骨架生成器
- tool/validate_fixed_section.py：FIXED校验脚本
- references/common-errors.md：常见错误

