@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-cptf-test-run/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: rnoh-cptf-test-run
+description: >-
+  基于 rnoh-cptf-demo-test 生成的 CPTF 测试文件，在鸿蒙设备上实机运行并调试至全部步骤通过。当用户说"运行 CPTF 测试"、"调试 CPTF 测试"、"CPTF 测试失败了怎么修"、"实机跑一下 CPTF"时使用。覆盖：前置环境检查（设备/hap/依赖解析）、运行测试（单用例/全量）、失败诊断（级联取消/全角冒号/步骤超时/模块解析）、修复迭代至全绿、交付确认。
+  关键词：CPTF、RNOH、实机调试、步骤超时、级联取消、UIAutomation、harmony、hdc、测试报告。
+license: Apache-2.0
+compatibility: 需要 CPTF 测试工程（已由 rnoh-cptf-demo-test 生成）、hdc 工具、鸿蒙真机/模拟器、pnpm、cptf CLI
+allowed-tools: Read Grep Glob Bash
+metadata:
+  version: "1.0.0"
+  category: rnoh-testing
+---
+
+# RNOH 三方库 CPTF 测试实机运行与调试
+
+基于已生成的 CPTF 测试文件，在鸿蒙设备上实机运行并调试至全部步骤通过。前置 SKILL 为 `rnoh-cptf-demo-test`（负责生成测试工程文件）。
+
+> ⚠️ **核心原则：看到批量"用例已取消"时只诊断第一个超时步骤（级联取消机制）；断言文本必须逐字符核对 demo 源码（全角/半角冒号是头号失败根因）；每轮修复只针对第一个失败步骤，修复后完整重跑。**
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `workspaceDir` | string | ✅ | CPTF 测试工程目录（含 cptf.config.json + 测试文件，由 rnoh-cptf-demo-test 生成） |
+| `exampleDir` | string | ❌ | RN example 工程目录（含 package.json + metro.config.js），用于 HAP 构建。默认从 `workspaceDir` 上溯推导（如 `workspaceDir` 为 `example/cptf/` 则 `exampleDir` 为 `example/`） |
+| `testId` | string | ❌ | 指定运行的测试 ID（`@Test` 的 id），不传则全量运行 |
+| `deviceId` | string | ❌ | 鸿蒙设备 SN（默认取 cptf.config.json 中第一个设备） |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: `rnoh-cptf-demo-test`（已生成 cptf.config.json + package.json + tests/cases/functional/*.test.ts）
+- **输入文件**:
+  - 测试工程配置：`{workspaceDir}/cptf.config.json`
+  - 测试用例文件：`{workspaceDir}/tests/cases/functional/*.test.ts`
+  - demo hap 产物：`{demoPath}/harmony/entry/build/default/outputs/default/entry-default-signed.hap`
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 前置环境检查与构建（设备/依赖/hap 构建+安装）
+    ↓
+Phase 2: 运行测试（cptf run）
+    ↓
+Phase 3: 失败诊断与修复迭代（逐步骤修复至通过）
+    ↓
+Phase 4: 交付确认（全绿 + 稳定性验证）
+```
+
+---
+
+## Phase 1：前置环境检查与构建
+
+### 1.1 运行环境校验脚本
+
+```bash
+bash {workspaceDir}/../rnoh-cptf-test-run/scripts/validate-run-env.sh '{"workspaceDir":"<绝对路径>"}'
+```
+
+或手动逐项检查：
+
+| 检查项 | 命令 | 预期 |
+|--------|------|------|
+| 设备已连接 | `hdc list targets` 或 `devecocli device list` | 输出设备 SN |
+| hap 文件存在 | `ls {cptf.config.json → platforms.harmony.appPath}` | 文件存在且为绝对路径 |
+| 框架依赖已 link | `node -e "require.resolve('@cptf/framework')"` (在 workspaceDir 下) | 输出解析路径 |
+| reflect-metadata 已 link | `ls {workspaceDir}/node_modules/reflect-metadata` | 目录存在 |
+| 测试文件存在 | `ls {workspaceDir}/tests/cases/functional/*.test.ts` | 至少 1 个文件 |
+
+### 1.2 HAP 构建与安装
+
+> ⚠️ **若 Demo 代码已变更（如通过 `rnoh-cptf-api-test` 生成/修改了 Demo 页面或入口文件），必须重新构建 HAP。** 旧 HAP 中的 `bundle.harmony.js` 不含新 Demo 代码，测试将找不到按钮。
+
+**构建分两步：RN Bundle 编译 + 鸿蒙 HAP 打包。**
+
+#### 步骤 1：RN Bundle 编译
+
+在 `{exampleDir}`（含 `package.json` 和 `metro.config.js` 的目录）下执行：
+
+```bash
+cd {exampleDir} && npm run dev
+```
+
+> `npm run dev` 内部执行 `codegen` + `react-native bundle-harmony --dev --minify=false`，产出 `harmony/entry/src/main/resources/rawfile/bundle.harmony.js`。
+>
+> 若 `npm run dev` 不存在，检查 `example/package.json` 的 `scripts` 字段，可能叫 `bundle:harmony` 或类似名称。核心是执行 codegen + bundle-harmony 两步。
+
+#### 步骤 2：鸿蒙 HAP 打包
+
+在 `{exampleDir}/harmony` 目录下执行：
+
+```bash
+devecocli build
+```
+
+> `devecocli build` 调用 hvigor 编译 ArkTS + C++ + 打包签名，产出 `entry/build/default/outputs/default/entry-default-signed.hap`。
+>
+> 构建成功标志：输出 `BUILD SUCCESSFUL` 且 `SignHap` 任务完成。
+>
+> 若 `devecocli` 不可用，也可在 DevEco Studio 中 Build → Build Hap(s)。
+
+#### 步骤 3：安装 HAP 到设备
+
+```bash
+hdc install "{appPath 绝对路径}"
+```
+
+若已安装旧版本，先卸载再安装（签名变更时必需）：
+
+```bash
+hdc uninstall {bundleId} && hdc install "{appPath 绝对路径}"
+```
+
+或使用 `devecocli run --uninstall` 一步完成卸载+安装。
+
+> 详细环境检查与故障排查参见 [实战调试手册](references/DEBUG_PLAYBOOK.md) §6
+
+---
+
+## Phase 2：运行测试
+
+### 2.1 单用例运行
+
+```bash
+cd {workspaceDir} && cptf run -p harmony -t {testId}
+```
+
+### 2.2 全量运行
+
+```bash
+cd {workspaceDir} && cptf run -p harmony
+```
+
+### 2.3 报告定位
+
+```bash
+ls test-reports/{timestamp}/harmony/
+#   execution.log      —— 逐步骤日志（首要诊断材料）
+#   screenshots/       —— 每步骤截图（失败步骤必有 -fail.jpeg）
+#   report.html        —— 汇总报告
+```
+
+> 运行命令详情与报告分析技巧参见 [实战调试手册](references/DEBUG_PLAYBOOK.md) §4
+
+---
+
+## Phase 3：失败诊断与修复迭代
+
+### 3.1 诊断决策树
+
+```
+运行失败
+├─ Cannot find module '@cptf/framework'
+│   → workspace 未正确 link 依赖（参见 rnoh-cptf-demo-test/references/CPTF_SETUP.md §3）
+├─ `Invalid or unexpected token` 或 `File '@react-native/typescript-config/tsconfig.json' not found`
+│   → ts-node 拾取了上级 RN 工程的 tsconfig.json
+│   → 在 workspaceDir 下生成独立 tsconfig.json（不 extends 任何外部配置）
+├─ `context.addInitializer is not a function`
+│   → tsconfig.json 设了 `experimentalDecorators: true`
+│   → 移除 `experimentalDecorators` 和 `emitDecoratorMetadata`（框架用 Stage 3 装饰器）
+├─ 报告只显示 1 个用例（N 个步骤全在一个 @Test 里）
+│   → 测试文件未按 API 分类拆分
+│   → 每个分类拆为独立 .test.ts 文件，各自含 @Test + export testCaseExecutor
+├─ 某步骤 "步骤超时(NNNNNms)"，其后全部 "UIAutomation: 用例已取消"
+│   → 级联取消机制：只诊断第一个超时步骤
+│   ├─ 截图显示按钮已点击、结果已渲染 → waitForText 文本不匹配 → 全角冒号问题
+│   ├─ 截图显示按钮未找到/未点击 → textContains 关键字错 或 未滚动到位
+│   └─ 截图显示结果渲染异常 → demo 已知 bug 或 API 未实现，放宽断言（容错模式）
+├─ 回调类 API 步骤超时（按钮已点击但结果不出现）
+│   → API 通过 (Module as any) 调用，JS 层可能未实现，回调不触发
+│   → 使用容错断言：先等结果文本，再等错误信息，两者皆无才报错
+├─ 步骤通过但断言值错误
+│   → 检查动态值推断（如 isSameState ? '' : 'false' 的空串分支）
+└─ 设备/hap 安装错误
+    → 参见 rnoh-cptf-demo-test/references/CPTF_SETUP.md §5
+```
+
+### 3.2 级联取消机制（调试前必读）
+
+CPTF 框架的 `FunctionalTest.execute()` 在步骤超时时设置 `_cancelled = true`，此后所有 UIAutomation 调用经 `throwIfCancelled()` 抛 `'UIAutomation: 用例已取消'`。
+
+**结论：一个步骤超时 → 后续全部步骤级联失败。看到批量"用例已取消"，只需诊断第一个超时步骤。**
+
+### 3.3 常见失败速查
+
+| 现象 | 根因 | 修复方向 |
+|------|------|----------|
+| `Cannot find module '@cptf/framework'` | shim NODE_PATH 失效 | workspace 本地 link 依赖 |
+| `Invalid or unexpected token` | ts-node 拾取上级 RN tsconfig | 生成 workspace 独立 tsconfig.json |
+| `context.addInitializer is not a function` | tsconfig 设了 `experimentalDecorators` | 移除该选项（框架用 Stage 3 装饰器） |
+| `File '@react-native/typescript-config/tsconfig.json' not found` | 同上，tsconfig 继承链断裂 | 同上 |
+| 报告只显示 1 个用例 | 所有 @Step 在同一个 @Test 类 | 按 API 分类拆分多文件 |
+| 步骤超时后批量"用例已取消" | 级联取消 | 修第一个超时步骤 |
+| 单步超时但按钮已点击成功 | waitForText 匹配串错误（全角冒号） | 逐字符对照源码修断言文本 |
+| 回调类 API 超时（按钮已点击结果不出现） | API 未实现，回调不触发 | 使用容错断言（等结果或错误信息） |
+| 报告时间戳差 8 小时 | cptf.config.json 未设置 `timezone` | 添加 `"timezone": "BeiJing"` |
+| 未找到按钮 | textContains 关键字不精确或未滚动到位 | 核对按钮 title，增大 maxScrolls |
+| 步骤通过但值错误 | 动态值推断错误 | 检查三元表达式空串分支 |
+
+### 3.4 迭代修复节奏
+
+1. 修复**只针对第一个失败步骤**（后续失败多为级联）
+2. 每轮修复后完整重跑（不要跳步骤）
+3. 全部通过后，再跑一轮确认稳定性（随机数/异步渲染可能有偶发）
+4. 连续两轮全绿 → 交付
+
+> 完整失败案例全记录与诊断决策树参见 [实战调试手册](references/DEBUG_PLAYBOOK.md)
+
+---
+
+## Phase 4：交付确认
+
+确认测试全部通过：
+
+```bash
+cd {workspaceDir} && cptf run -p harmony -t {testId}
+```
+
+确认最终报告：
+
+```
+{workspaceDir}/
+└── test-reports/{timestamp}/harmony/
+    ├── execution.log      # 逐步骤日志
+    ├── screenshots/       # 每步骤截图
+    └── report.html        # 汇总报告
+```
+
+报告内容：
+- 总步骤数 / 通过数 / 每步骤耗时
+- 截图目录（test-reports/{timestamp}/harmony/screenshots/）
+- 连续两轮全绿 → 交付完成

package/vendor/Server/Skills/rnoh-cptf-test-run/references/DEBUG_PLAYBOOK.md

@@ -0,0 +1,261 @@
+# 实战调试手册
+
+> Phase 3 的详细手册。记录 react-native-get-random-values 实战中的完整失败现象 → 根因 → 修复链路，供失败诊断时对照。
+
+## 1. CPTF 框架关键机制（调试前必读）
+
+### 1.1 级联取消机制
+
+`FunctionalTest.execute()` 入口设置 `ui.setCancelCheck(() => this._cancelled)`；每个步骤用 `Promise.race([doStep(), stepCapPromise])` 包装，**超时回调置 `this._cancelled = true`** 并 reject `步骤超时(${stepTimeout}ms)`；此后所有 UIAutomation 调用经 `throwIfCancelled()` 抛 `'UIAutomation: 用例已取消'`。
+
+**结论：一个步骤超时 → 后续全部步骤级联失败。看到批量"用例已取消"，只需诊断第一个超时步骤。**
+
+### 1.2 步骤超时默认值（decorators.ts DEFAULT_NAVIGATION_CONFIG）
+
+| 级别 | 默认值 |
+|------|--------|
+| stepDefault | 10000 |
+| stepAction | 20000 |
+| stepComplex | 30000 |
+| stepMax | 45000 |
+
+`getStepTimeout(step)` 优先取 `step.stepTimeout`。**滚动查找（最多 12 次 × 300ms）+ 点击 + 等待渲染 + waitForText 轮询（最长 8s）的步骤，10s 默认值必然不够**，统一显式设 30000。
+
+### 1.3 findByText 匹配语义
+
+```typescript
+async findByText(text: string, exact = false) {
+  return exact ? findElement({ text }) : findElement({ textContains: text });
+}
+```
+
+`textContains` 是**子串精确匹配**（区分全角/半角冒号、空格、大小写）。
+
+## 2. 实战失败案例全记录
+
+### 案例 1：模块解析失败
+
+```
+现象: Error: Cannot find module '@cptf/framework'
+根因: cptf CLI shim 的 NODE_PATH 含 .pnpm/node_modules 等不存在目录，
+      全局 link 安装的框架不在测试文件的解析路径上
+修复: workspace 本地 package.json link 依赖 + pnpm install
+      （详见 rnoh-cptf-demo-test/references/CPTF_SETUP.md §3）
+```
+
+### 案例 2：步骤 8 超时引发级联取消（核心案例）
+
+```
+现象: 步骤 1-7 通过；步骤 8 "步骤超时(10000ms): 普通数组输入应抛出 TypeMismatchError"；
+      步骤 9-18 全部 "UIAutomation: 用例已取消"
+根因链:
+  1. demo 源码是 <Text>错误信息：{errorInfo}</Text>（全角冒号）
+  2. 测试写了 waitForText('错误信息:')（半角冒号）
+  3. findByText 子串匹配失败 → waitForText 8 秒轮询空转
+  4. 步骤总耗时超过默认 10s → 超时 → _cancelled = true → 级联
+修复:
+  - waitForText('错误信息')  ← 去掉冒号，两种冒号均兼容
+  - '数组长度：' / '视图长度：' 等前缀类断言保留全角冒号（源码原样）
+  - 全部 @Step 加 stepTimeout: 30000
+教训: 断言文本必须从 demo 源码逐字符复制，绝不手写
+```
+
+### 案例 3：demo 已知渲染 bug（普通数组用例）
+
+```
+现象: 点击"测试普通数组应抛出"后，错误信息区域出现的是
+      "Text strings must be rendered within a <Text> component"
+      而非预期的 TypeMismatchError
+根因: demo 的 arrange 存在 RN 渲染 bug（setState 传非字符串对象直接渲染），
+      错误组件触发 RN 顶层渲染错误，LogBox 覆盖了业务错误文本
+修复: 断言放宽——验证 '错误信息' 文本出现 且 内容匹配
+      /TypeMismatchError/i 或 /<Text>|rendered within/i（渲染错误特征）
+      代码注释注明 demo 已知 bug
+教训: 测试对象是三方库行为；demo 自身 bug 时断言降级为"错误输出已触发"
+```
+
+### 案例 4：bundle 中 grep 中文失败
+
+```
+现象: 在 bundle.harmony.js 中 grep '两次生成数据是否一致' 返回 0 条，
+      误以为 demo 没有该文案
+根因: bundle 打包后中文可能被转义/分包，grep 不可靠
+修复: 一律以 src/**/*.tsx 源码为唯一事实来源
+```
+
+### 案例 5：无固定前缀的结果断言（裸数字）
+
+```
+现象: 7 种 TypedArray 基本用例的渲染是 {arr.map(item => <Text>{item}</Text>)}，
+      没有可 waitForText 的前缀
+修复: 快照差集法:
+  1. scrollAndClick 前不快照——在 scrollAndClick 内部滚动定位完成后、点击前，
+      由 collectNumbersAfter 依赖 lastSnapshot（上一步骤末尾的全量快照）
+  2. 点击+sleep(600) 后 getLayout(true) 全量快照
+  3. 差集（after - before）中过滤 /^-?\d+$/ 提取新增数字
+  4. 断言: 数量 ≥ 1 且每个值落在该 TypedArray 的值域内
+```
+
+### 案例 6：ts-node 拾取上级 tsconfig 导致编译失败
+
+```
+现象: executor执行失败: jpush-func - Invalid or unexpected token
+      日志首行: ts-node not available, TypeScript executor files may not work
+      (⨯ Unable to compile TypeScript:
+       error TS6053: File '@react-native/typescript-config/tsconfig.json' not found.)
+根因: cptf workspace 位于 RN 工程子目录（example/cptf/），ts-node register() 后
+      向上遍历找到 example/tsconfig.json，该文件 extends '@react-native/typescript-config'，
+      但该包未安装 in cptf workspace 的 node_modules，编译直接失败
+修复: 在 {workspaceDir} 下生成独立 tsconfig.json，不 extends 任何外部配置，
+      仅包含最小编译选项（target/module/moduleResolution/esModuleInterop/skipLibCheck）
+教训: cptf workspace 必须有独立 tsconfig.json，隔离上级 RN 工程的 TS 配置
+```
+
+### 案例 7：Stage 3 装饰器与 experimentalDecorators 冲突
+
+```
+现象: executor执行失败: jpush-func - context.addInitializer is not a function
+根因: CPTF 框架的 @Step 装饰器使用 Stage 3 装饰器规范：
+      - Step 装饰器返回的函数接收 (originalMethod, context) 两个参数
+      - 内部调用 context.addInitializer() 注册初始化回调
+      若 tsconfig.json 设了 experimentalDecorators: true，TypeScript 编译器
+      使用旧版（Stage 1/2）装饰器格式，方法装饰器只接收
+      (target, propertyKey, descriptor)，不提供 context 对象
+修复: tsconfig.json 中移除 experimentalDecorators 和 emitDecoratorMetadata
+      框架的 registerTsNode() 使用 transpileOnly 模式，compilerOptions 不含
+      experimentalDecorators，但 tsconfig.json 的设置会覆盖
+教训: CPTF 测试工程的 tsconfig.json 绝不能设置 experimentalDecorators
+```
+
+### 案例 8：回调类 API 未实现导致步骤超时
+
+```
+现象: 步骤 "调用 getPushStatus 失败: 点击后未出现getPushStatus最终结果文本"
+      截图显示按钮已点击，但结果区域仍显示"查询中..."
+根因: getPushStatus 在 index.js 中通过 (JPush as any).getPushStatus() 调用，
+      但 NativeJPush.ts TurboModule Spec 未声明该方法，原生侧不响应，
+      回调永不触发，waitForText 轮询 10s 后超时
+修复: 对此类 API 使用容错断言：
+      1. 点击后 sleep(2000) 等待可能的结果渲染
+      2. 先 waitForText('{apiName}结果', 8000) 尝试匹配成功
+      3. 若未找到，再 waitForText('错误信息', 3000) 尝试匹配 catch 块输出
+      4. 两者皆无才报错；report 断言接受 结果 或 错误信息
+教训: 通过 (Module as any) 调用的 API 可能未实现，断言需容错
+```
+
+## 3. 诊断决策树
+
+```
+运行失败
+├─ Cannot find module '@cptf/framework'
+│   → 案例 1（本地 link，参见 rnoh-cptf-demo-test/references/CPTF_SETUP.md §3）
+├─ `Invalid or unexpected token` 或 `File '@react-native/typescript-config/tsconfig.json' not found`
+│   → 案例 6（ts-node 拾取上级 tsconfig，生成独立 tsconfig.json）
+├─ `context.addInitializer is not a function`
+│   → 案例 7（tsconfig 设了 experimentalDecorators，移除该选项）
+├─ 报告只显示 1 个用例（N 步骤全在一个 @Test 里）
+│   → 测试文件未拆分，按 API 分类拆为多文件（每文件一个 @Test）
+├─ 某步骤 "步骤超时(NNNNNms)"，其后全部 "UIAutomation: 用例已取消"
+│   → 级联取消（§1.1），只诊断第一个超时步骤：
+│   ├─ 截图显示按钮已点击、结果已渲染 → waitForText 文本不匹配 → 案例 2（全角冒号）
+│   ├─ 截图显示按钮已点击、结果仍"查询中..."或空 → 案例 8（API 未实现，容错断言）
+│   ├─ 截图显示按钮未找到/未点击 → textContains 关键字错 或 未滚动到位
+│   │   → 核对按钮 title；maxScrolls 增大；确认 type: 'Button' 过滤
+│   └─ 截图显示结果渲染异常 → 案例 3（demo bug，放宽断言）
+├─ 步骤通过但断言值错误
+│   → 检查动态值推断（如 isSameState ? '' : 'false' 的空串分支）
+└─ 设备/hap 安装错误
+    → 参见 rnoh-cptf-demo-test/references/CPTF_SETUP.md §5
+```
+
+## 4. 运行命令与报告定位
+
+```bash
+cd {workspaceDir}
+cptf run -p harmony -t {testId}          # 单用例运行
+# 或全量: cptf run -p harmony
+
+# 报告位置
+ls test-reports/{timestamp}/harmony/
+#   execution.log      —— 逐步骤日志（首要诊断材料）
+#   screenshots/       —— 每步骤截图（失败步骤必有 -fail.jpeg）
+#   report.html        —— 汇总报告
+```
+
+**看日志技巧**：
+- 搜 `步骤超时` 定位第一个超时步骤
+- 搜 `通过` / `失败` 统计步骤结果
+- 步骤失败时先看该步骤 `-fail.jpeg` 截图：UI 实际渲染状态 vs 断言预期的差异即为根因
+
+## 5. 迭代修复节奏
+
+1. 修复**只针对第一个失败步骤**（后续失败多为级联）
+2. 每轮修复后完整重跑（不要跳步骤）
+3. 全部通过后，再跑一轮确认稳定性（随机数/异步渲染可能有偶发）
+4. 连续两轮全绿 → 交付
+
+## 6. HAP 构建与安装
+
+### 6.1 何时需要构建
+
+| 场景 | 是否需要构建 | 原因 |
+|------|-------------|------|
+| 首次运行 CPTF 测试 | ✅ | HAP 可能不存在或不含 CPTF Demo |
+| `rnoh-cptf-api-test` 生成/修改了 Demo 代码 | ✅ | `bundle.harmony.js` 不含新 Demo 页面 |
+| 修改了测试文件（.test.ts） | ❌ | 测试文件由 ts-node 在宿主机执行，不打包进 HAP |
+| 修改了 `cptf.config.json` | ❌ | 运行时配置，不打包进 HAP |
+| 修改了 Demo 页面代码（.tsx） | ✅ | 需重新编译 RN Bundle + 打包 HAP |
+| HAP 已存在且 Demo 未变更 | ❌ | 直接安装即可 |
+
+### 6.2 构建命令
+
+**步骤 1：RN Bundle 编译**
+
+```bash
+cd {exampleDir} && npm run dev
+```
+
+`npm run dev` 内部执行 `codegen` + `react-native bundle-harmony --dev --minify=false`，产出 `harmony/entry/src/main/resources/rawfile/bundle.harmony.js`。
+
+> 若 `npm run dev` 脚本不存在，检查 `example/package.json` 的 `scripts` 字段。核心是执行 codegen + bundle-harmony 两步：
+> ```bash
+> npm run codegen && react-native bundle-harmony --dev --minify=false
+> ```
+
+**步骤 2：鸿蒙 HAP 打包**
+
+```bash
+cd {exampleDir}/harmony && devecocli build
+```
+
+`devecocli build` 调用 hvigor 编译 ArkTS + C++ + 打包签名，产出 `entry/build/default/outputs/default/entry-default-signed.hap`。
+
+构建成功标志：输出 `BUILD SUCCESSFUL` 且 `SignHap` 任务完成。
+
+> 若 `devecocli` 不可用，替代方案：
+> - DevEco Studio → Build → Build Hap(s)
+> - 或直接 `hvigorw assembleHap`（需配置 HarmonyOS SDK 环境变量）
+
+### 6.3 安装到设备
+
+```bash
+# 首次安装
+hdc install "{hapPath}"
+
+# 签名变更或覆盖安装失败时，先卸载
+hdc uninstall {bundleId} && hdc install "{hapPath}"
+
+# 或使用 devecocli 一步完成
+devecocli run --uninstall
+```
+
+### 6.4 构建故障速查
+
+| 现象 | 根因 | 修复 |
+|------|------|------|
+| `npm run dev` 报 `Cannot find module '@react-native-oh/react-native-harmony'` | 依赖未安装 | `cd {exampleDir} && npm install` |
+| `npm run dev` 报 codegen 失败 | `oh_modules` 中 RNOH 框架缺失 | 检查 `harmony/entry/oh_modules/@rnoh/react-native-openharmony` 是否存在 |
+| `devecocli build` 报 `No entry module` | 工程结构异常 | 检查 `harmony/entry/src/main/module.json5` 是否存在 |
+| `devecocli build` 报签名失败 | 签名配置过期 | 在 DevEco Studio 中重新配置签名，或 `devecocli build --build-mode release` |
+| `hdc install` 报 `install sign info inconsistent` | 签名 key 变更 | `hdc uninstall {bundleId}` 后重新安装 |
+| HAP 构建成功但测试找不到按钮 | RN Bundle 未更新就打包了 HAP | 先 `npm run dev`，再 `devecocli build`，顺序不能反 |

package/vendor/Server/Skills/rnoh-cptf-test-run/scripts/validate-run-env.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# @tool validate-run-env
+# @description 校验 CPTF 测试运行环境就绪性（设备连接/hap文件/依赖解析/测试文件），输出诊断报告
+# @param workspaceDir: string - CPTF 测试工程目录绝对路径
+
+ARGS_JSON="$1"
+workspaceDir=$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('workspaceDir',''))" "$ARGS_JSON" 2>/dev/null || echo "")
+
+if [ -z "$workspaceDir" ]; then
+    echo "Usage: validate-run-env.sh <workspaceDir>"
+    echo "Error: workspaceDir parameter is required"
+    exit 1
+fi
+
+if [ ! -d "$workspaceDir" ]; then
+    echo "Error: Directory does not exist: $workspaceDir"
+    exit 1
+fi
+
+PASS=0
+FAIL=0
+
+check_pass() { echo "  ✅ $1"; PASS=$((PASS + 1)); }
+check_fail() { echo "  ❌ $1"; FAIL=$((FAIL + 1)); }
+
+echo "=== CPTF 运行环境校验 ==="
+echo "目录: $workspaceDir"
+echo ""
+
+# ─── 1. 配置文件 ───
+echo "--- 1. 配置文件检查 ---"
+configFile="$workspaceDir/cptf.config.json"
+if [ -f "$configFile" ]; then
+    check_pass "cptf.config.json 存在"
+    appPath=$(python3 -c "import json; cfg=json.load(open('$configFile')); print(cfg.get('platforms',{}).get('harmony',{}).get('appPath',''))" 2>/dev/null)
+    bundleId=$(python3 -c "import json; cfg=json.load(open('$configFile')); print(cfg.get('bundleId',''))" 2>/dev/null)
+    if [ -n "$appPath" ]; then
+        check_pass "appPath 配置: $appPath"
+    else
+        check_fail "cptf.config.json 缺少 platforms.harmony.appPath"
+    fi
+    if [ -n "$bundleId" ]; then
+        check_pass "bundleId 配置: $bundleId"
+    else
+        check_fail "cptf.config.json 缺少 bundleId"
+    fi
+else
+    check_fail "cptf.config.json 不存在（请先运行 rnoh-cptf-demo-test 生成测试工程）"
+fi
+
+# ─── 2. hap 文件 ───
+echo ""
+echo "--- 2. hap 文件检查 ---"
+if [ -n "$appPath" ]; then
+    if [ -f "$appPath" ]; then
+        check_pass "hap 文件存在: $appPath"
+    else
+        check_fail "hap 文件不存在: $appPath（需先构建 demo）"
+    fi
+else
+    check_fail "无法检查 hap 文件（appPath 未配置）"
+fi
+
+# ─── 3. 依赖解析 ───
+echo ""
+echo "--- 3. 依赖解析检查 ---"
+if [ -d "$workspaceDir/node_modules/@cptf/framework" ]; then
+    check_pass "node_modules/@cptf/framework 已建立"
+else
+    check_fail "node_modules/@cptf/framework 不存在（运行 pnpm install）"
+fi
+if [ -d "$workspaceDir/node_modules/reflect-metadata" ]; then
+    check_pass "node_modules/reflect-metadata 已建立"
+else
+    check_fail "node_modules/reflect-metadata 不存在（装饰器将不生效）"
+fi
+
+# ─── 4. 测试文件 ───
+echo ""
+echo "--- 4. 测试文件检查 ---"
+testFiles=$(find "$workspaceDir/tests/cases" -name '*.test.ts' 2>/dev/null)
+if [ -n "$testFiles" ]; then
+    testCount=$(echo "$testFiles" | wc -l | tr -d ' ')
+    check_pass "发现测试文件: $testCount 个"
+    for tf in $testFiles; do
+        echo "  检查: $(basename "$tf")"
+        grep -q "import 'reflect-metadata'" "$tf" && check_pass "  首行 import reflect-metadata" || check_fail "  缺少 import 'reflect-metadata'"
+        grep -q 'stepTimeout' "$tf" && check_pass "  已设置 stepTimeout" || check_fail "  存在未设置 stepTimeout 的步骤风险"
+        grep -q 'testCaseExecutor' "$tf" && check_pass "  导出 testCaseExecutor" || check_fail "  缺少 testCaseExecutor 导出"
+    done
+else
+    check_fail "tests/cases 下未发现 .test.ts 文件（请先运行 rnoh-cptf-demo-test 生成）"
+fi
+
+# ─── 5. 设备连接 ───
+echo ""
+echo "--- 5. 设备连接检查 ---"
+if command -v hdc &>/dev/null; then
+    check_pass "hdc 工具可用"
+    devices=$(hdc list targets 2>/dev/null | grep -v '^\[Empty\]' | grep -v '^$')
+    if [ -n "$devices" ]; then
+        check_pass "设备已连接: $devices"
+    else
+        check_fail "无设备连接（hdc list targets 为空）"
+    fi
+else
+    check_fail "hdc 工具不可用（需配置 HarmonyOS SDK 环境变量）"
+fi
+
+echo ""
+echo "=== 结果: PASS=$PASS FAIL=$FAIL ==="
+[ $FAIL -eq 0 ] && exit 0 || exit 1