@harmonyos-arkts/d2h 0.1.20 → 0.1.22

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/entry/src/ohosTest/ets/test/FFmpegVerify.test.ets

@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeAll } from '@ohos/hypium';
+import { FFmpeg, FFAbortController, FFAudioPlayer } from '@sj/ffmpeg';
+import { abilityDelegatorRegistry } from '@kit.TestKit';
+import { common } from '@kit.AbilityKit';
+import { fileIo as fs } from '@kit.CoreFileKit';
+
+let filesDir = '';
+let wav = '';
+
+function run(cmd: string[]): Promise<string> {
+  return new Promise<string>((resolve) => {
+    let out = '';
+    FFmpeg.execute(cmd, {
+      logCallback: (m: string) => { out += m; },
+      outputCallback: (m: string) => { out += m; },
+    }).then(() => resolve(out)).catch((e: Error) => resolve('ERR:' + e.message));
+  });
+}
+
+export default function ffmpegVerifyTest() {
+  describe('FFmpegVerify', () => {
+    beforeAll(async () => {
+      const delegator = abilityDelegatorRegistry.getAbilityDelegator();
+      const ability = await delegator.getCurrentTopAbility();
+      const ctx = ability.context as common.UIAbilityContext;
+      filesDir = ctx.filesDir;
+      wav = `${filesDir}/ffmpeg_test.wav`;
+      const raw = await ctx.resourceManager.getRawFileContent('ffmpeg_test.wav');
+      const f = fs.openSync(wav, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
+      fs.writeSync(f.fd, raw.buffer);
+      fs.closeSync(f);
+    });
+
+    // ===== 14 个 verify 用例（对齐 api-map disposition=verify）=====
+
+    // 1. FFmpegCmd.handle → FFmpeg.execute（命令执行）
+    it('01_handle_executes', 0, async () => {
+      const out = await run(['ffmpeg', '-version']);
+      expect(out).assertContain('ffmpeg version');
+    });
+
+    // 2. FFmpegCmd.handleProbe → FFmpeg.execute（探测）
+    it('02_handleProbe_executes', 0, async () => {
+      const out = await run(['ffprobe', '-version']);
+      expect(out).assertContain('ffprobe version');
+    });
+
+    // 3. FFmpegCmd.cancelTaskJni → FFAbortController.abort（取消）
+    it('03_cancelTask_abort', 0, async () => {
+      const c = new FFAbortController();
+      const p = FFmpeg.execute(['ffmpeg', '-i', wav, `${filesDir}/abort.m4a`, '-y'],
+        { signal: c.signal, logCallback: (m: string) => {} });
+      setTimeout(() => { c.abort(); }, 200);
+      let aborted = false;
+      try { await p; } catch (err) { aborted = true; }
+      console.info(`[NATIVE_TEST] 03 abort=${aborted}`);
+      expect(aborted).assertTrue();
+    });
+
+    // 4. AudioPlayer.native_play → FFAudioPlayer（音频播放）
+    it('04_native_play_audio', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 800));
+      const playing = p.playWhenReady;
+      p.pause();
+      expect(playing).assertTrue();
+    });
+
+    // 5. AudioPlayer.native_get_duration → FFAudioPlayer.duration
+    it('05_native_get_duration', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      console.info(`[NATIVE_TEST] 05 duration=${p.duration}`);
+      expect(p.duration).assertLarger(0);
+    });
+
+    // 6. AudioPlayer.native_get_position → FFAudioPlayer.currentTime
+    it('06_native_get_position', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 500));
+      const pos = p.currentTime;
+      p.pause();
+      console.info(`[NATIVE_TEST] 06 pos=${pos}`);
+      expect(pos).assertLargerOrEqual(0);
+    });
+
+    // 7. AudioPlayer.native_again → seek(0)+play（重新播放）
+    it('07_native_again_replay', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 500));
+      p.seek(0);
+      p.play();
+      const playing = p.playWhenReady;
+      p.pause();
+      expect(playing).assertTrue();
+    });
+
+    // 8. VideoPlayer.executeTranscode → FFmpeg.execute（转码）
+    it('08_executeTranscode_output', 0, async () => {
+      const out = `${filesDir}/t.m4a`;
+      await run(['ffmpeg', '-i', wav, out, '-y']);
+      let ok = false;
+      try { fs.accessSync(out); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] 08 transcode=${ok}`);
+      expect(ok).assertTrue();
+    });
+
+    // 9. VideoPlayer.again → FFmpeg.execute（重跑命令）
+    it('09_again_rerun', 0, async () => {
+      const out1 = await run(['ffmpeg', '-version']);
+      const out2 = await run(['ffmpeg', '-version']);
+      expect(out1).assertContain('ffmpeg version');
+      expect(out2).assertContain('ffmpeg version');
+    });
+
+    // 10. VideoPlayer.playAudio → FFAudioPlayer play/pause
+    it('10_playAudio_toggle', 0, async () => {
+      const p = new FFAudioPlayer();
+      p.url = `file://${wav}`;
+      p.prepare();
+      await new Promise<void>((r) => setTimeout(r, 1500));
+      p.play();
+      await new Promise<void>((r) => setTimeout(r, 300));
+      p.pause();
+      expect(p.playWhenReady).assertFalse();
+    });
+
+    // 11. FFmpegMediaRetriever.native_setDataSource → ffprobe -i
+    it('11_setDataSource_probe', 0, async () => {
+      const out = await run(['ffprobe', '-i', wav]);
+      console.info(`[NATIVE_TEST] 11 probe=${out.slice(0, 80)}`);
+      expect(out.length).assertLarger(0);
+    });
+
+    // 12. FFmpegMediaRetriever.native_extractMetadata → ffprobe -show_format
+    it('12_extractMetadata_format', 0, async () => {
+      const out = await run(['ffprobe', '-v', 'info', '-of', 'json', '-show_format', '-i', wav]);
+      console.info(`[NATIVE_TEST] 12 meta=${out.slice(0, 100)}`);
+      expect(out).assertContain('format');
+    });
+
+    // 13. FFmpegMediaRetriever.native_getFrameAtTime → ffmpeg 截帧
+    it('13_getFrameAtTime_screenshot', 0, async () => {
+      await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', `${filesDir}/gen.mp4`, '-y']);
+      await run(['ffmpeg', '-ss', '0', '-i', `${filesDir}/gen.mp4`, '-frames:v', '1', `${filesDir}/frame.jpg`, '-y']);
+      let ok = false;
+      try { fs.accessSync(`${filesDir}/frame.jpg`); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] 13 frame=${ok}`);
+      expect(ok).assertTrue();
+    });
+
+    // 14. FFmpegMediaRetriever.native_getScaleFrameAtTime → ffmpeg 缩放截帧
+    it('14_getScaleFrame_scaled', 0, async () => {
+      await run(['ffmpeg', '-ss', '0', '-i', `${filesDir}/gen.mp4`, '-frames:v', '1',
+        '-vf', 'scale=32:32', `${filesDir}/frame_small.jpg`, '-y']);
+      let ok = false;
+      try { fs.accessSync(`${filesDir}/frame_small.jpg`); ok = true; } catch (e) { ok = false; }
+      console.info(`[NATIVE_TEST] 14 scale=${ok}`);
+      expect(ok).assertTrue();
+    });
+  });
+}

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/entry/src/ohosTest/ets/test/List.test.ets

@@ -0,0 +1,2 @@
+import t from './FFmpegVerify.test';
+export default function testsuite(){t();}

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/entry/src/ohosTest/module.json5

@@ -0,0 +1 @@
+{"module":{"name":"entry_test","type":"feature","deviceTypes":["phone"],"deliveryWithInstall":true,"installationFree":false}}

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/hvigor/hvigor-config.json5

@@ -0,0 +1 @@
+{"modelVersion":"26.0.0","dependencies":{},"execution":{},"logging":{},"debugging":{},"nodeOptions":{}}

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/hvigorfile.ts

@@ -0,0 +1,2 @@
+import { appTasks } from '@ohos/hvigor-ohos-plugin';
+export default { system: appTasks, plugins: [] }

package/skills/cpp/d2h-native-library-verify/references/demo-project-template/oh-package.json5

@@ -0,0 +1,9 @@
+{
+  "modelVersion": "26.0.0",
+  "description": "FFmpeg so verify",
+  "dependencies": {
+    "@sj/ffmpeg": "^2.0.2"
+  },
+  "devDependencies": {},
+  "dynamicDependencies": {}
+}

package/skills/cpp/d2h-native-library-verify/references/demo-template.md

@@ -0,0 +1,176 @@
+# ArkTS/NAPI 验证 Demo 模板
+
+本模板规范 `d2h-native-library-verify` 第 4–6 步的 demo 生成。按 api-map 的用例数生成卡片式验证页；
+`bridge-required` 库先按「二」生成桥接模块。所有代码放验证专用目录，不混入业务实现。
+
+## 一、工程布局
+
+```
+entry/src/main/
+├── libs/arm64-v8a/libdemo.so          # 被验证的 OHOS 库（不入业务模块）
+├── cpp/                                # 仅 bridge-required 库需要
+│   ├── CMakeLists.txt
+│   └── demo_bridge.cpp                 # 纯转发桥接层
+├── ets/pages/NativeVerifyDemo.ets      # 验证页（卡片列表）
+└── resources/base/profile/main_pages.json  # 注册页面
+```
+
+## 二、NAPI 桥接层（仅 bridge-required）
+
+**原则：只做类型转发，不含任何业务逻辑**——桥接层引入的差异会污染验证结论。
+
+```cpp
+// demo_bridge.cpp：libdemo.so 导出 int add(int, int)
+#include "napi/native_api.h"
+
+extern int add(int a, int b);  // 与 .so 导出一一对应（对照 api-map ohos_symbol）
+
+static napi_value Add(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value args[2] = {nullptr};
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    int32_t a = 0, b = 0;
+    napi_get_value_int32(env, args[0], &a);
+    napi_get_value_int32(env, args[1], &b);
+    napi_value result;
+    napi_create_int32(env, add(a, b), &result);   // 转发调用
+    return result;
+}
+
+EXTERN_C_START
+static napi_value Init(napi_env env, napi_value exports) {
+    napi_property_descriptor desc[] = {
+        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
+        // ...api-map 每个 ohos_symbol 一条
+    };
+    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+    return exports;
+}
+EXTERN_C_END
+
+static napi_module demoBridgeModule = {
+    .nm_version = 1, .nm_flags = 0, .nm_filename = nullptr,
+    .nm_register_func = Init, .nm_modname = "demo_bridge",
+    .nm_priv = nullptr, .reserved = { 0 },
+};
+extern "C" __attribute__((constructor)) void RegisterDemoBridge(void) {
+    napi_module_register(&demoBridgeModule);
+}
+```
+
+`CMakeLists.txt`：
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(demo_bridge)
+add_library(demo_bridge SHARED demo_bridge.cpp)
+target_link_libraries(demo_bridge PUBLIC libdemo.so)   # 链接被验证库
+```
+
+类型映射按 `d2h-native-library-build` §6.4（jstring→napi_value 等）。
+
+## 三、类型声明（`.d.ts`）
+
+`entry/src/main/cpp/types/demo_bridge/index.d.ts`（napi-ready 库把模块名换成 `libdemo.so`）：
+
+```typescript
+export const add: (a: number, b: number) => number;
+// ...api-map 每个 API 一条；签名与 ohos_symbol 实际原型一致（从 .h/文档核对，不确定查 d2h-cloud-knowledge）
+```
+
+## 四、验证页（ArkTS）
+
+> 按钮交互的已知坑（真实工程踩过）：
+> ① `List`/`ListItem` 内的 `Button.onClick` 在部分版本被列表点击拦截吞掉——用 `Scroll`+`Column`+`ForEach` 替代；
+> ② ForEach 的 key 用会变的字段（如 `api+input`）会在数据更新时重建条目、闭包 `i` 可能失效——用稳定唯一 key（`api`）；
+> ③ ArkUI V1 `@State` 对**对象数组**深层观察失效——`map` 重赋值新数组仍不刷新条目文本；**改用 V2 状态管理**（`@ObservedV2` class + `@Trace` 字段 + `@ComponentV2`/`@Local`），`this.cases[i].actual = ...` 直接赋值即刷新；
+> ④ `aboutToAppear` 若已自动执行全部用例，按钮重跑同命令结果相同 → 「点击无变化」其实是正常现象；加「运行中...」即时反馈让点击必有可见变化。
+> **且按钮 demo 本就脆弱，功能验证首选 Hypium 测试用例（见 hypium-test-template.md）**。
+
+**结果颜色规范**：`actual` 文本动态着色——`✗`（失败/差异/未实现）与**`异常:`** **红色**、`✓`（通过）**绿色**、`运行中...`/`-` 灰色：
+
+```typescript
+.fontColor(
+  (this.cases[i].actual.startsWith('✗') || this.cases[i].actual.startsWith('异常'))
+    ? Color.Red : Color.Green)
+```
+
+```typescript
+// NativeVerifyDemo.ets：api-map 每条用例一个卡片
+import bridge from 'libdemo_bridge.so';   // napi-ready 库：import demo from 'libdemo.so'
+
+interface ApiCase {
+  api: string;            // 'add'
+  input: string;          // '1, 2'（取 api-map demo_input）
+  expected: string;       // '3'（取 api-map android_expected）
+  actual: string;         // 运行时填写
+}
+
+@Entry
+@Component
+struct NativeVerifyDemo {
+  @State cases: ApiCase[] = [
+    { api: 'add', input: '1, 2', expected: '3', actual: '-' },
+    // ...每条 api-map 用例一顶；多输入场景拆多条
+  ];
+
+  runCase(i: number): void {
+    const c = this.cases[i];
+    try {
+      // 按 api 生成调用（add → bridge.add(1, 2)；参数从 demo_input 解析）
+      const out = bridge.add(1, 2);
+      c.actual = String(out);
+    } catch (e) {
+      c.actual = '异常: ' + JSON.stringify(e);   // 异常路径也是验证对象（Android 侧行为对照）
+    }
+    this.cases[i] = c;
+    // 同步写 hilog：api/input/expected/actual，供证据采集
+    console.info(`[NATIVE_VERIFY] ${c.api} input=${c.input} expected=${c.expected} actual=${c.actual}`);
+  }
+
+  build() {
+    List() {
+      ForEach(this.cases, (c: ApiCase, i: number) => {
+        ListItem() {
+          Column({ space: 6 }) {
+            Text(`${c.api}(${c.input})`).fontSize(16).fontWeight(FontWeight.Bold)
+            Text(`期望: ${c.expected}   实际: ${c.actual}`)
+              .fontColor(c.actual === c.expected ? Color.Green : Color.Red)
+            Button('运行').onClick(() => this.runCase(i))
+          }.width('100%').padding(12)
+        }
+      }, (c: ApiCase) => c.api + c.input)
+    }
+  }
+}
+```
+
+## 四·五、无 UI 交互的自动执行与 CLI 签名
+
+- **自动执行**：验证页 `aboutToAppear()` 里循环触发每个用例，`EntryAbility.loadContent` 直接指向验证页 → 启动即执行，无需人工点击「运行」按钮（无头运行时验证的前提）。
+- **CLI 自动签名 + 部署采集**：见 [demo-build-sign-run.md](demo-build-sign-run.md)——hvigor headless 构建、复用本机 auto-sign 材料签名、`hdc install` + `aa start` + `hilog -x` 采集。
+
+## 五、采集与回填
+
+1. **运行**：逐卡片执行；`hdc shell hilog | grep NATIVE_VERIFY` 抓取输出存
+   `.migration/native-libs/verify-evidence/<lib>/run.log`（日志格式必须保持
+   `[NATIVE_VERIFY] api input=... expected=... actual=...`，采集器按此解析）。
+2. **采集**：
+   ```bash
+   python3 ../d2h-native-library-verify/scripts/verify-ohos-native.py \
+     --collect-diff .migration/native-libs/verify-evidence/<lib>/run.log \
+     --ohos-lib libdemo.so --api-map .migration/native-libs/api-map.json --json
+   ```
+   三态自动判定（一致/不一致/未运行 `-`）、异常路径记 note、证据=日志:行号；
+   同一用例重跑取最后一次。
+3. **复核合并**：AI 核对草稿（期望值来源、未运行用例改 `unverifiable` 并注明原因、
+   差异描述补 note）后合并回 `verify-report.json` 的 `functional_diffs[]`。
+4. **沉淀**：可断言用例交 `d2h-hypium-forge` 生成回归测试；差异项打回 `d2h-native-library-build` 处置。
+
+## 六、检查单
+
+- [ ] api-map 覆盖校验 0 缺失（或缺失项已记 inconsistent/unverifiable）
+- [ ] bridge-required 库桥接层无业务逻辑（纯转发）
+- [ ] 每条用例的证据文件存在（日志/截图）
+- [ ] `android_expected` 的来源已注明（真机采集 / 源码推断）
+- [ ] 差异清单三态齐备，无「猜测为一致」的条目

package/skills/cpp/d2h-native-library-verify/references/hypium-test-template.md

@@ -0,0 +1,163 @@
+# Hypium 测试用例验证模板（断言式，替代按钮 UI demo）
+
+功能一致性验证的**推荐方式**：用 `@ohos/hypium` 写断言式测试用例，`hdc shell aa test` 无头运行。相比「验证页 + 按钮」的 UI demo，测试用例**可断言、可 CI、无 UI 交互、无响应式坑**（ArkTS `@State` 数组原地突变不刷新等）。
+
+## 一、工程结构
+
+```
+entry/src/ohosTest/
+├── module.json5                      # 测试模块（name 必须 "<模块名>_test"）
+└── ets/test/
+    ├── List.test.ets                 # testsuite 聚合
+    └── Ability.test.ets              # 测试用例（断言）
+```
+
+`entry/oh-package.json5` 加 devDependency：
+
+```json5
+"devDependencies": { "@ohos/hypium": "1.0.25" }
+```
+
+`entry/build-profile.json5` 的 `targets` 必须含 `ohosTest`（否则测试 HAP 不产出）：
+
+```json5
+"targets": [ { "name": "default" }, { "name": "ohosTest" } ]
+```
+
+## 二、测试用例写法（Ability.test.ets）
+
+> **用例生成规则（按 Android 使用面全量闭合）**：用例不是挑「好测的」子集，而是从 Android 源码对 so/a 的**全部使用点**生成——每个功能域（命令执行/音频播放/视频滤镜/元数据帧提取/可视化/播放器引擎/推流）每条映射 → 一个 `it` 用例或一条 `unverifiable` 登记，数量对账闭合。无 API 的功能域显式写 `it('xxx_no_ohos_api', ...)` 断言缺失（或登记 functional_diffs `unverifiable`），使差异清单完整覆盖使用面。
+
+```typescript
+import { describe, it, expect } from '@ohos/hypium';
+import { FFmpeg } from '@sj/ffmpeg';
+
+function run(cmd: string[]): Promise<string> {
+  return new Promise<string>((resolve) => {
+    let out = '';
+    FFmpeg.execute(cmd, {
+      logCallback: (msg: string) => { out += msg; },
+      outputCallback: (msg: string) => { out += msg; },
+    }).then(() => resolve(out)).catch(() => resolve(out));
+  });
+}
+
+export default function ffmpegTest() {
+  describe('FFmpegVerify', () => {
+    it('ffmpeg_executes_version', 0, async () => {
+      const out = await run(['ffmpeg', '-version']);
+      expect(out).assertContain('ffmpeg version');
+    });
+    // ...每个功能一个 it 用例，assertContain/assertEqual 断言实际输出
+  });
+}
+```
+
+`List.test.ets`：
+
+```typescript
+import ffmpegTest from './Ability.test';
+export default function testsuite() {
+  ffmpegTest();
+}
+```
+
+**常用用例模式**（按 Android 使用面）：
+
+```typescript
+// 音频播放（AudioPlayer.native_play → FFAudioPlayer）
+it('audio_player_plays_wav', 0, async () => {
+  const player = new FFAudioPlayer();
+  player.url = `file://${filesDir}/test.wav`;
+  player.prepare();
+  await new Promise<void>((r) => setTimeout(r, 1500));
+  expect(player.duration > 0).assertTrue();
+  player.play();
+  await new Promise<void>((r) => setTimeout(r, 1000));
+  expect(player.playWhenReady).assertTrue();
+  player.pause();
+});
+
+// 帧提取/截图（FFmpegMediaRetriever.getFrameAtTime → ffmpeg 截帧，无原生 API 用命令变通）
+it('frame_extract_creates_image', 0, async () => {
+  await run(['ffmpeg', '-f', 'lavfi', '-i', 'color=c=red:s=64x64:d=1', `${filesDir}/gen.mp4`, '-y']);
+  await run(['ffmpeg', '-ss', '0', '-i', `${filesDir}/gen.mp4`, '-frames:v', '1', `${filesDir}/frame.jpg`, '-y']);
+  // fs.accessSync 断言产物存在
+});
+
+// 取消（cancelTaskJni → FFAbortController，实测可能为真实差异——abort 未中断则断言失败=差异证据）
+it('abort_cancels_task', 0, async () => {
+  const c = new FFAbortController();
+  const p = FFmpeg.execute([...转码...], { signal: c.signal });
+  setTimeout(() => c.abort(), 200);
+  try { await p; expect(false).assertTrue(); } catch (e) { /* 中断=符合预期 */ }
+});
+```
+
+测试内获取 filesDir（rawfile 拷贝）用 `abilityDelegatorRegistry`（注意小写开头）：
+
+```typescript
+import { abilityDelegatorRegistry } from '@kit.TestKit';
+const delegator = abilityDelegatorRegistry.getAbilityDelegator();
+const ability = await delegator.getCurrentTopAbility();
+const ctx = ability.context;  // ctx.filesDir / ctx.resourceManager
+```
+
+`module.json5`：
+
+```json5
+{
+  "module": {
+    "name": "entry_test",
+    "type": "feature",
+    "deviceTypes": [ "phone" ],
+    "deliveryWithInstall": true,
+    "installationFree": false
+  }
+}
+```
+
+## 三、构建 · 安装 · 运行（全 CLI）
+
+```bash
+export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
+
+# 应用 HAP
+node <DevEco>/tools/hvigor/bin/hvigorw.js --mode module -p product=default assembleHap
+# 测试 HAP（产物 entry/build/default/outputs/ohosTest/entry-ohosTest-signed.hap）
+node <DevEco>/tools/hvigor/bin/hvigorw.js --mode module -p module=entry@ohosTest -p product=default assembleHap
+
+hdc -t <设备> install -r entry-default-signed.hap
+hdc -t <设备> install -r entry-ohosTest-signed.hap
+
+hdc -t <设备> shell aa test -b <bundleName> -m <模块名>_test -s unittest OpenHarmonyTestRunner -s timeout 20000
+```
+
+## 四、结果判定
+
+`aa test` 输出末尾：
+
+```
+OHOS_REPORT_RESULT: stream=Tests run: 4, Failure: 0, Error: 0, Pass: 4, Ignore: 0
+TestFinished-ResultCode: 0
+```
+
+- `ResultCode: 0` 且 `Failure=0, Error=0` → 全部通过
+- 断言失败 → `Failure>0` 且 `ResultCode` 非 0；结果作为 `functional_diffs[]` 的 `inconsistent` 证据
+
+## 五、与功能差异清单的衔接
+
+**unverifiable 登记规范**（无 API 的功能域不写测试用例，但必须登记——三要素句式）：
+
+| functional_diffs 条目 | 值 |
+|---|---|
+| status | `unverifiable` |
+| ohos_actual | `鸿蒙 so 未实现：未导出 <具体 NAPI 能力>` |
+| note | 处置建议（自实现 / 系统能力替代如 AVPlayer / 裁剪） |
+
+闭合校验：`Hypium 用例数 + unverifiable 登记数 = api-map 条目数`。
+
+每个 `it` 用例对应 api-map 一个 API 的功能验证：
+- 断言「输出含预期标记」→ 功能可用（`consistent`）
+- 断言「不含某 Android 特定值」→ 版本/行为差异（`inconsistent`，如 `ffmpeg version 8` ≠ Android `6.0.1`）
+- 文件级用例（转码产物存在、元数据字段）→ rawfile 拷贝到 `filesDir` 后断言