@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-cptf-api-test/references/SPEC_PARSING_GUIDE.md

@@ -0,0 +1,274 @@
+# 接口规格解析指南
+
+> Phase 1 的详细操作手册。目标是解析接口规格说明书，提取结构化 API 清单，并探查工程目录结构。
+
+---
+
+## 1. 规格文档格式
+
+### 1.1 Markdown 格式（来自 script_rn_render_spec_doc）
+
+典型结构：
+
+```markdown
+# {库名} 接口规格说明书
+
+## 模块信息
+- 包名: @react-native-ohos/react-native-xxx
+- 版本: x.y.z
+- 平台: HarmonyOS
+
+## API 清单
+
+### TurboModule 方法
+
+#### methodA(param1: string, param2?: number): Promise<Result>
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| param1 | string | 是 | ... |
+| param2 | number | 否 | ... |
+
+- 返回值: Promise<Result>
+- 平台: harmony
+- 权限: ohos.permission.xxx
+
+### 组件
+
+#### ComponentA
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| prop1 | string | - | ... |
+
+### 事件
+
+#### onEventA
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| data | { value: number } | ... |
+
+### 常量
+
+#### CONSTANT_A: string
+- 值: "fixed_value"
+- 平台: harmony
+```
+
+### 1.2 JSON 格式（来自 script_rn_extract_interfaces）
+
+典型结构：
+
+```json
+{
+  "moduleName": "react-native-xxx",
+  "version": "x.y.z",
+  "exports": {
+    "methods": [
+      {
+        "name": "methodA",
+        "params": [
+          { "name": "param1", "type": "string", "required": true },
+          { "name": "param2", "type": "number", "required": false }
+        ],
+        "returnType": "Promise<Result>",
+        "isAsync": true
+      }
+    ],
+    "components": [
+      {
+        "name": "ComponentA",
+        "props": [
+          { "name": "prop1", "type": "string", "default": null }
+        ]
+      }
+    ],
+    "constants": [
+      { "name": "CONSTANT_A", "type": "string", "value": "fixed_value" }
+    ],
+    "events": [
+      { "name": "onEventA", "payload": { "value": "number" } }
+    ]
+  }
+}
+```
+
+---
+
+## 2. API 清单提取方法
+
+### 2.1 Markdown 解析
+
+按标题层级提取：
+
+| 标题级别 | 提取内容 |
+|----------|----------|
+| `##` | API 分类（TurboModule 方法/组件/事件/常量） |
+| `###` | API 名称 |
+| `####` | 方法签名（参数、返回值） |
+| 表格 | 参数详情、属性详情 |
+| 列表项 | 平台、权限、返回值说明 |
+
+提取步骤：
+
+1. 识别 `## API 清单` 下的所有 `###` 标题 → API 分类
+2. 对每个分类下的 `####` 标题 → 提取方法签名
+3. 解析签名中的参数列表（`param: type` 格式，`?` 表示可选）
+4. 解析返回值（`Promise<X>` → 异步，`X` → 同步）
+5. 提取表格中的参数详情
+6. 提取列表项中的平台和权限信息
+
+### 2.2 JSON 解析
+
+直接遍历 `exports` 对象的各字段：
+
+| JSON 字段 | 对应 API 类型 |
+|-----------|--------------|
+| `exports.methods` | TurboModule 方法 |
+| `exports.components` | 组件 |
+| `exports.events` | 事件回调 |
+| `exports.constants` | 常量/枚举 |
+| `exports.hooks` | React Hooks |
+| `exports.types` | 类型定义（不生成 Demo/Test） |
+
+### 2.3 MCP 工具辅助
+
+若规格文档不存在或不完整，调用 MCP 工具从源码提取：
+
+**提取接口规格**：
+调用 `script_rn_extract_interfaces`，传入：
+- `libroot`：RN 三方库的鸿蒙化仓库根目录
+- `output`：输出 JSON 路径（如 `interface-spec.json`）
+- `version`：上游 npm 版本号（可选，自动推断）
+
+**渲染为 Markdown**：
+调用 `script_rn_render_spec_doc`，传入：
+- `spec`：已有的 interface-spec.json 路径
+- `output`：输出 Markdown 路径
+
+**交叉验证导出接口**：
+调用 `script_rn_scan_exports`，传入：
+- `dir`：源码目录路径
+- `compare`：false（单目录扫描模式）
+
+---
+
+## 3. 工程目录探查
+
+### 3.1 探查 example/demo 目录
+
+```bash
+# 按优先级搜索
+for dir in \
+  "{projectRoot}/rn-tester/examples" \
+  "{projectRoot}/example/src" \
+  "{projectRoot}/examples/src" \
+  "{projectRoot}/example" \
+  "{projectRoot}/demo/src" \
+  "{projectRoot}/demo"; do
+  if [ -d "$dir" ]; then
+    echo "FOUND: $dir"
+    break
+  fi
+done
+```
+
+探查到的目录赋值给 `exampleDir`。Demo 页面文件和 CPTF 测试工程统一生成在 `{exampleDir}/cptf/` 下。
+
+### 3.2 探查 Demo 注册入口
+
+```bash
+# 按优先级搜索注册文件
+find {projectRoot} -name "RNTesterList.*" -o -name "TesterList.*" | head -5
+# 备选
+find {projectRoot} -name "App.tsx" -path "*/example/*" | head -5
+```
+
+读取 `registerFile` 内容，分析现有注册模式：
+
+| 模式 | 识别特征 | 追加方式 |
+|------|----------|----------|
+| 模式 A | `require(...)` + 数组对象含 `module` 字段 | 追加 `{ key, category, module: require(...) }` |
+| 模式 B | `import ... from ...` + 导航/路由配置 | 添加 import + 路由配置 |
+| 模式 C | `demos`/`items` 数组 + `Component` 字段 | 添加 import + 追加数组项 |
+
+### 3.3 提取构建信息
+
+```bash
+# bundleId
+cat {exampleDir}/harmony/AppScope/app.json5 | grep bundleName
+
+# hap 路径
+ls {exampleDir}/harmony/entry/build/default/outputs/default/entry-default-signed.hap
+
+# 依赖检查
+cat {exampleDir}/package.json | grep "{harmonyPkgName}"
+```
+
+### 3.4 缺失处理
+
+| 探查项 | 缺失处理 |
+|--------|----------|
+| `package.json` | 停止，提示非 RN 工程 |
+| example/demo 目录 | 停止，提示用户指定 Demo 目录 |
+| 注册入口文件 | 停止，提示用户指定注册文件 |
+| `harmonyPkgName` 依赖 | 停止，提示先安装依赖 |
+| hap 构建产物 | 警告，继续生成代码（Phase 6 交付后需构建，参见 `rnoh-cptf-test-run` Phase 1.2） |
+| AppScope/app.json5 | 警告，bundleId 用占位符 |
+
+---
+
+## 4. API 清单产出物
+
+Phase 1 结束时必须产出以下结构化清单（Phase 2-5 的输入）：
+
+```markdown
+## API 清单
+
+### TurboModule 方法
+| # | 方法名 | 签名 | 异步 | 参数 | 返回值 | 平台 | 权限 |
+|---|--------|------|------|------|--------|------|------|
+| 1 | methodA | methodA(p1: string, p2?: number) | 是 | p1(string,必填), p2(number,可选) | Promise<Result> | harmony | - |
+| 2 | methodB | methodB(): string | 否 | 无 | string | harmony | - |
+
+### 组件
+| # | 组件名 | Props | 平台 |
+|---|--------|-------|------|
+| 1 | ComponentA | prop1(string), prop2(boolean) | harmony |
+
+### 事件
+| # | 事件名 | Payload | 平台 |
+|---|--------|---------|------|
+| 1 | onEventA | { value: number } | harmony |
+
+### 常量
+| # | 常量名 | 类型 | 值 | 平台 |
+|---|--------|------|-----|------|
+| 1 | CONSTANT_A | string | "fixed_value" | harmony |
+
+## 工程信息
+- exampleDir: {探查到的路径}
+- workspaceDir: {exampleDir}/cptf/
+- indexFile: {exampleDir}/cptf/index.tsx
+- demoDir: {exampleDir}/cptf/demo/
+- bundleId: {从 app.json5 提取}
+- hapPath: {exampleDir}/harmony/entry/build/default/outputs/default/entry-default-signed.hap
+- dependencies: {已确认依赖存在}
+```
+
+---
+
+## 5. 知识库查询
+
+当涉及鸿蒙平台特定约束时，调用 `kb_search` 查询：
+
+| 场景 | 检索词 |
+|------|--------|
+| 权限要求 | `HarmonyOS 权限 {功能}` |
+| ArkTS 限制 | `ArkTS 限制 {主题}` |
+| TurboModule 适配 | `RNOH TurboModule 适配` |
+| 事件机制 | `RNOH 事件 NativeEventEmitter` |
+
+调用要点：
+- 一次查询一个关键词
+- 对返回结果提取：知识点、注意事项、代码示例
+- 若返回不相关，调整关键词重试（最多3轮）
+- 不照搬全文，提取核心要点精简引用

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

@@ -0,0 +1,185 @@
+#!/bin/bash
+# @tool validate-rnoh-cptf-api-test
+# @description 校验接口规格驱动的 Demo + CPTF 测试工程结构完整性（Demo testID/前缀 + CPTF config/package/测试文件骨架 + Demo-Test 对齐）
+# @param workspaceDir: string - CPTF 测试工程目录绝对路径
+# @param demoDir: string - Demo 页面目录绝对路径（{exampleDir}/{libName}/）
+
+ARGS_JSON="$1"
+workspaceDir=$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('workspaceDir',''))" "$ARGS_JSON" 2>/dev/null || echo "")
+demoDir=$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('demoDir',''))" "$ARGS_JSON" 2>/dev/null || echo "")
+
+if [ -z "$workspaceDir" ]; then
+    echo "Usage: validate-rnoh-cptf-api-test.sh '{\"workspaceDir\":\"<路径>\",\"demoDir\":\"<路径>\"}'"
+    echo "Error: workspaceDir parameter is required"
+    exit 1
+fi
+
+if [ ! -d "$workspaceDir" ]; then
+    echo "Error: workspaceDir does not exist: $workspaceDir"
+    exit 1
+fi
+
+PASS=0
+FAIL=0
+WARN=0
+
+check_pass() { echo "  PASS $1"; PASS=$((PASS + 1)); }
+check_fail() { echo "  FAIL $1"; FAIL=$((FAIL + 1)); }
+check_warn() { echo "  WARN $1"; WARN=$((WARN + 1)); }
+
+echo "=== RNOH CPTF API Test Validation ==="
+echo "workspaceDir: $workspaceDir"
+if [ -n "$demoDir" ] && [ -d "$demoDir" ]; then
+    echo "demoDir: $demoDir"
+else
+    echo "demoDir: (not provided or not found, skipping Demo checks)"
+fi
+echo ""
+
+# --- 1. Demo checks ---
+if [ -n "$demoDir" ] && [ -d "$demoDir" ]; then
+    echo "--- 1. Demo Code Checks ---"
+
+    # 1.1 index.tsx
+    indexFile="$demoDir/index.tsx"
+    if [ -f "$indexFile" ]; then
+        check_pass "index.tsx exists"
+        grep -q 'Tester' "$indexFile" && check_pass "index.tsx has Tester framework" || check_fail "index.tsx missing Tester framework"
+        grep -q 'displayName' "$indexFile" && check_pass "index.tsx has metadata export" || check_warn "index.tsx missing metadata export"
+    else
+        check_fail "index.tsx not found"
+    fi
+
+    # 1.2 Demo page files
+    demoPages=$(find "$demoDir/demo" -name '*.tsx' 2>/dev/null)
+    if [ -n "$demoPages" ]; then
+        pageCount=$(echo "$demoPages" | wc -l | tr -d ' ')
+        check_pass "Demo page files found: $pageCount"
+
+        for tf in $demoPages; do
+            echo "  Checking: $(basename "$tf")"
+
+            # testID check
+            testIdCount=$(grep -c 'testID=' "$tf" 2>/dev/null || echo 0)
+            if [ "$testIdCount" -gt 0 ]; then
+                check_pass "  Has testID ($testIdCount)"
+            else
+                check_warn "  No testID found (CPTF will use textContains fallback)"
+            fi
+
+            # Fixed prefix check
+            if grep -qE '(结果|错误信息|状态|常量|属性)' "$tf" 2>/dev/null; then
+                check_pass "  Has fixed text prefix"
+            else
+                check_warn "  No fixed text prefix pattern found"
+            fi
+
+            # ScrollView root check
+            firstComp=$(head -20 "$tf" | grep -oE '<(View|ScrollView)' | head -1)
+            if [ "$firstComp" = "<ScrollView" ]; then
+                check_fail "  Root component is ScrollView (should be View)"
+            else
+                check_pass "  Root component is View"
+            fi
+
+            # Slider check
+            grep -q 'Slider' "$tf" 2>/dev/null && check_fail "  Uses Slider (not supported on HarmonyOS)" || check_pass "  No Slider"
+
+            # console.error check
+            grep -q 'console.error' "$tf" 2>/dev/null && check_fail "  Uses console.error" || check_pass "  No console.error"
+        done
+    else
+        check_fail "No Demo page files found in $demoDir/demo/"
+    fi
+    echo ""
+fi
+
+# --- 2. CPTF config ---
+echo "--- 2. CPTF Config Checks ---"
+if [ -f "$workspaceDir/cptf.config.json" ]; then
+    check_pass "cptf.config.json exists"
+    python3 - "$workspaceDir/cptf.config.json" <<'EOF'
+import json, sys
+with open(sys.argv[1]) as f:
+    cfg = json.load(f)
+issues = []
+if 'bundleId' not in cfg: issues.append('missing bundleId')
+if 'casesDir' not in cfg: issues.append('missing casesDir')
+h = cfg.get('platforms', {}).get('harmony', {})
+if 'appPath' not in h: issues.append('missing platforms.harmony.appPath')
+elif not h['appPath'].startswith('/'): issues.append('appPath not absolute path')
+if not h.get('devices'): issues.append('missing platforms.harmony.devices')
+for i in issues:
+    print(f"  FAIL cptf.config.json: {i}")
+if not issues:
+    print("  PASS cptf.config.json key fields complete")
+sys.exit(1 if issues else 0)
+EOF
+    [ $? -eq 0 ] && PASS=$((PASS + 1)) || FAIL=$((FAIL + 1))
+else
+    check_fail "cptf.config.json not found"
+fi
+
+# --- 3. package.json link ---
+echo ""
+echo "--- 3. Link Dependency Checks ---"
+if [ -f "$workspaceDir/package.json" ]; then
+    grep -q '"@cptf/framework": "link:' "$workspaceDir/package.json" && check_pass "@cptf/framework link declared" || check_fail "@cptf/framework link not declared"
+    grep -q '"reflect-metadata": "link:' "$workspaceDir/package.json" && check_pass "reflect-metadata link declared" || check_fail "reflect-metadata link not declared"
+else
+    check_fail "package.json not found"
+fi
+
+# --- 4. node_modules ---
+echo ""
+echo "--- 4. Module Resolution Checks ---"
+if [ -d "$workspaceDir/node_modules/@cptf/framework" ]; then
+    check_pass "node_modules/@cptf/framework established"
+else
+    check_fail "node_modules/@cptf/framework not found (run pnpm install)"
+fi
+
+# --- 5. Test file ---
+echo ""
+echo "--- 5. Test File Checks ---"
+testFiles=$(find "$workspaceDir/tests/cases" -name '*.test.ts' 2>/dev/null)
+if [ -n "$testFiles" ]; then
+    testCount=$(echo "$testFiles" | wc -l | tr -d ' ')
+    check_pass "Test files found: $testCount"
+
+    for tf in $testFiles; do
+        echo "  Checking: $(basename "$tf")"
+        grep -q "import 'reflect-metadata'" "$tf" && check_pass "  First line import reflect-metadata" || check_fail "  Missing import 'reflect-metadata'"
+        grep -q 'stepTimeout' "$tf" && check_pass "  Has stepTimeout" || check_fail "  No stepTimeout found"
+        grep -q 'testCaseExecutor' "$tf" && check_pass "  Exports testCaseExecutor" || check_fail "  Missing testCaseExecutor export"
+        grep -q 'single-page' "$tf" && check_pass "  Has single-page navigation strategy" || check_warn "  No single-page navigation strategy"
+
+        # testID usage in test
+        grep -q 'scrollAndClickByTestId' "$tf" && check_pass "  Uses testID-based locating" || check_warn "  Not using testID locating (textContains only)"
+
+        # Halfwidth colon risk scan
+        halfwidth=$(grep -o "waitForText('[^']*:[^']*')" "$tf" 2>/dev/null | head -5)
+        if [ -n "$halfwidth" ]; then
+            check_warn "  waitForText with halfwidth colon (verify Demo uses same):"
+            echo "$halfwidth" | sed 's/^/      /'
+        fi
+    done
+else
+    check_fail "No .test.ts files found in tests/cases/"
+fi
+
+# --- 6. Summary ---
+echo ""
+echo "=== Summary ==="
+echo "  PASS: $PASS"
+echo "  FAIL: $FAIL"
+echo "  WARN: $WARN"
+echo ""
+
+if [ "$FAIL" -eq 0 ]; then
+    echo "ALL CHECKS PASSED"
+    exit 0
+else
+    echo "VALIDATION FAILED: $FAIL issue(s) must be fixed"
+    exit 1
+fi

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

@@ -0,0 +1,191 @@
+---
+name: rnoh-cptf-demo-test
+description: >-
+  分析 RN 鸿蒙三方库已有 demo（testerino 单页应用）源码，按 CPTF 规范自动生成测试工程文件（cptf.config.json + package.json + 测试用例 .ts），保证格式与结构正确。当用户说"给这个三方库 demo 生成 CPTF 测试文件"、"用 CPTF 规范生成测试用例"、"分析 demo 源码生成测试文件"时使用。覆盖：demo 源码勘察（按钮 title/结果 Text/testID）、测试工程搭建（cptf.config.json + link 依赖）、测试文件编写（导航策略/滚动定位/文本断言）、格式校验。实机运行调试请使用 rnoh-cptf-test-run。
+  关键词：CPTF、RNOH、RN 三方库、自动化测试、testerino、harmony、
+  FunctionalTest、测试文件生成。
+license: Apache-2.0
+compatibility: 需要 CPTF 框架源码（@cptf/framework 可 link）、pnpm、demo 构建产物路径（用于配置 appPath）
+allowed-tools: Read Grep Glob Bash
+metadata:
+  version: "1.0.0"
+  category: rnoh-testing
+---
+
+# RNOH 三方库 Demo CPTF 测试文件生成
+
+分析单个 RN 鸿蒙三方库已有 demo 源码，按 CPTF（`@cptf/framework`）规范生成对应的测试工程文件（配置 + 依赖 + 测试用例），保证格式与结构正确。实机运行与调试由后续 SKILL `rnoh-cptf-test-run` 负责。
+
+> ⚠️ **核心原则：断言文本必须逐字符核对 demo 源码（特别是全角/半角冒号）；每个 @Step 必须显式设置 stepTimeout ≥ 30000；生成的 package.json 必须本地 link 依赖（不依赖 CLI shim 的 NODE_PATH）；所有文件格式必须通过校验脚本验证。**
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `demoPath` | string | ✅ | 三方库 demo 工程根目录（含 `src/`、`harmony/`） |
+| `libName` | string | ✅ | 三方库名（如 `react-native-get-random-values`） |
+| `workspaceDir` | string | ✅ | CPTF 测试工程目录（含 cptf.config.json，可新建） |
+| `frameworkPath` | string | ❌ | @cptf/framework 源码路径（默认从全局 pnpm link 推导） |
+| `deviceId` | string | ❌ | 鸿蒙设备 SN（写入 cptf.config.json，默认占位待填） |
+
+## 输入依赖
+
+- **前置SKILL**: 无（可独立使用；demo 应已通过 rnoh-lib-demo-create 等流程构建出 hap）
+- **后续SKILL**: `rnoh-cptf-test-run`（实机运行与调试）
+- **输入文件**:
+  - demo 源码：`{demoPath}/src/**/*.tsx`（testerino 用例定义）
+  - 构建产物路径：`{demoPath}/harmony/entry/build/default/outputs/default/entry-default-signed.hap`
+  - demo 配置：`{demoPath}/AppScope/app.json5`（提取 bundleName）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: Demo 源码勘察（提取用例清单+精确文本）
+    ↓
+Phase 2: 测试工程搭建（生成 cptf.config.json + package.json link 依赖）
+    ↓
+Phase 3: 测试文件生成（导航策略 + @Test + @Step）
+    ↓
+Phase 4: 格式校验与交付（结构完整性检查 + 输出确认）
+```
+
+---
+
+## Phase 1：Demo 源码勘察
+
+### 1.1 定位用例定义文件
+
+在 `{demoPath}/src/` 下查找 testerino 用例（`TestCase`/`TestSuite`/`Tester` 关键字），通常在单个 `.tsx` 文件中。
+
+> 勘察项明细与提取方法参见 [Demo 源码勘察指南](references/DEMO_ANALYSIS.md)
+
+### 1.2 提取三要素清单
+
+对每个 TestCase 提取（**逐字符精确记录，不凭记忆**）：
+
+| 要素 | 来源 | 用途 |
+|------|------|------|
+| 按钮 title | `<Button title="...">` | `scrollToFindElement({ textContains })` 定位 |
+| 结果文本 | `<Text>前缀:{值}</Text>` | `waitForText` 断言 |
+| testID | `testID` 属性（如有） | 优先用 testID 定位；无则全部走文本定位 |
+
+### 1.3 全角/半角冒号核对（最高优先）
+
+在源码中区分 `：`（全角）与 `:`（半角）。**`waitForText` 是子串精确匹配，半角搜索串永远匹配不到全角文本**——这是最常见的隐性失败根因。记录每个结果文本前缀时保留原始字符，直接复制源码字符串。
+
+### 1.4 识别 demo 结构特征
+
+- 单页 ScrollView（无 deep link、无模块首页）→ 需注册 `single-page` 导航策略
+- 按钮是否在屏幕外 → 需要 `scrollToFindElement` 智能滚动
+- 结果文本有无固定前缀（裸数字等）→ 决定断言策略（waitForText vs 快照差集）
+
+---
+
+## Phase 2：测试工程搭建
+
+### 2.1 生成 cptf.config.json
+
+```json
+{
+  "bundleId": "<demo bundleId，见 AppScope/app.json5>",
+  "reportDir": "test-reports",
+  "reportFormat": "html",
+  "casesDir": "tests/cases",
+  "platforms": {
+    "harmony": {
+      "toolPath": "hdc",
+      "bundleId": "<同上>",
+      "appPath": "<demoPath>/harmony/entry/build/default/outputs/default/entry-default-signed.hap",
+      "devices": [{ "id": "<设备SN>", "screenWidth": 1280, "screenHeight": 2832 }]
+    }
+  }
+}
+```
+
+### 2.2 建立 link 依赖（关键）
+
+> ⚠️ cptf CLI shim 的 NODE_PATH 不可靠（pnpm link 全局安装后 `.pnpm/node_modules` 可能不存在），**必须在测试工程本地建立 node_modules**。
+
+生成 `{workspaceDir}/package.json`：
+
+```json
+{
+  "name": "cptf-workspace",
+  "private": true,
+  "dependencies": {
+    "@cptf/framework": "link:<frameworkPath>",
+    "reflect-metadata": "link:<frameworkPath>/node_modules/reflect-metadata"
+  }
+}
+```
+
+执行 `pnpm install`，然后用 `node -e "require.resolve('@cptf/framework')"` 验证解析成功。
+
+> 详细步骤与故障排查参见 [CPTF 工程搭建指南](references/CPTF_SETUP.md)
+
+---
+
+## Phase 3：测试文件生成
+
+### 3.1 文件骨架
+
+生成 `tests/cases/functional/{libName 短名}.test.ts`，结构：
+
+```
+import 'reflect-metadata' + @cptf/framework 导入
+  → NavigationStrategyFactory.registerStrategy('single-page', ...)
+  → @Test({... navigationStrategy: 'single-page', waitAfterAction: 300})
+  → class XxxTest extends FunctionalTest
+  → 辅助方法（scrollAndClick / waitForText / report / snapshot 差集）
+  → 每个 TestCase 一个 @Step
+  → export const testCaseExecutor = new XxxTest()
+```
+
+### 3.2 编码规则（全部来自实战踩坑）
+
+1. **每个 @Step 显式 `stepTimeout: 30000`**——默认 10s 不够滚动+点击+等待
+2. **断言文本从 Phase 1 清单逐字符复制**，全角冒号原样保留
+3. **无固定前缀的结果**（如裸数字）用快照差集：点击前 `getLayout(true)` 快照 → 点击后再快照 → 差集中提取
+4. **demo 已知渲染 bug**（如 "Text strings must be rendered within a <Text>"）时断言放宽为"错误输出已触发"，代码注释注明原因
+5. **步骤失败即 throw**（经 report 辅助方法），保证报告准确归因
+
+> 完整可运行模板参见 [测试文件模板](assets/TEST_TEMPLATE.md)
+
+---
+
+## Phase 4：格式校验与交付
+
+### 4.1 运行校验脚本
+
+```bash
+bash {skillDir}/scripts/validate-rnoh-cptf-test.sh '{"workspaceDir":"<绝对路径>"}'
+```
+
+校验项：
+
+| 检查项 | 规则 |
+|--------|------|
+| cptf.config.json | 存在且含 bundleId / casesDir / platforms.harmony.appPath（绝对路径）/ devices |
+| package.json | 声明 @cptf/framework link + reflect-metadata link |
+| node_modules | @cptf/framework + reflect-metadata 已建立 |
+| 测试文件 | 首行 import reflect-metadata / 已设 stepTimeout / 导出 testCaseExecutor |
+| 全角冒号风险 | 扫描 waitForText 参数含半角冒号的行（警告） |
+
+### 4.2 交付物确认
+
+确认输出目录包含所有文件：
+
+```
+{workspaceDir}/
+├── cptf.config.json          # 设备/应用配置
+├── package.json              # link 依赖
+├── node_modules/             # pnpm install 产物
+└── tests/cases/functional/
+    └── {libName}.test.ts     # 测试文件（格式校验通过）
+```
+
+校验脚本全部 PASS 后，交付完成。后续实机运行调试使用 `rnoh-cptf-test-run` SKILL。