@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/demo-wiring-pc.md

@@ -0,0 +1,620 @@
+---
+description: 功能验证 demo 的接线细则：test-demo/ 工程与 test-demo/verify/ 证据落位硬约束、按交付形态选 scaffold kind（cpp-gui-owb-demo / python-gui-owb / cli-hnp-runner / cpp-lib-demo）、入口模式（人工分级浏览 / 一把全部执行 / 直达单条）与驱动器分档、cases.json 清单、GUI 上屏与 CLI HNP 与库形态各自的达标证据、用例到载体的对应关系、能力缺口 capability_gaps 记法。
+---
+
+# 验证 demo 接线细则（鸿蒙 PC）
+
+配套 `SKILL.md` 第七节的路由表。这里讲**怎么接**，载体本身的实现来源在 `pc-capability-domains` 与 `templates/hap/`。
+
+---
+
+## 0. 工程与证据的落位（硬约束）
+
+```
+<workspace>/
+  harmony-demo/          ← 阶段 3 的上屏取证 demo（不要碰）
+  build/                 ← 阶段 3 的证据与脚本（不要写）
+  test-demo/             ← 阶段 5 独占
+    entry/…              工程本体
+    scripts/             构建脚本（scaffold --out 非缺省时放这里；build/ 归 hvigor 管会被清空）
+    deps/                仅在工作区顶层 deps/ 没有时才装配
+    dist/app/*.hap       未签 / 已签 HAP
+    cases.json           ★ 入口清单 + run_all.supported 声明（scaffold --test-cases 生成）
+    verify/              ★ 所有设备证据落这里：一用例一份 <case-id>.json（含逐判定点 checks[]）
+                           + demo-verify.json 汇总 + device-raw.log 完整设备日志（**测试线不截图**）
+```
+
+**证据绝不能落 `build/`**：上屏证据判定会匹配 `build/` 下任意 `.jpg/.png/.webp`（递归 3 层），阶段 6 往那里写截图会让阶段 3 的 `verify-verdict.json` 被时效表判过期，白白触发一轮 `pc-03-dev-verify` 重跑。
+
+**单条用例墙钟预算 <3s（app 域平台看门狗）**：app 域线程阻塞 >3s 触发 `THREAD_BLOCK_3S`、
+>6s 触发 `THREAD_BLOCK_6S` 后 `processExit:1` 杀进程（mpg123 sweeper/noise 实证）。
+设计用例时就拆开长耗时场景（长扫频、噪声表生成、大数据集基准）；拆不了的如实
+`platform-exclusive-fixture` 豁免并附看门狗日志，别指望 `--case-timeout` 救——
+机制详见 `pc-device-verify/references/cli-batch-exec.md`。
+
+标准命令序：
+
+```bash
+ohpt-agent scaffold --kind <k> -w "$WORKSPACE" --out test-demo \
+                    --test-cases .ohos-adaptation-pc/05-testcases.json
+# …按用例逐条接线、编译…
+ohpt-agent sign-demo   -w "$WORKSPACE" --demo-dir test-demo --install
+ohpt-agent verify-demo -w "$WORKSPACE" --demo-dir test-demo --out-dir test-demo/verify \
+                       --cases test-demo/cases.json
+# ↑ 一次冷启动跑完全部用例（--ps ohptRun all），轮询到 OHPTCASE summary 行收证
+#   复现单条 / 要进程隔离对照用 --per-case；整轮超时 --run-timeout（默认 900s）
+```
+
+### demo 应用身份与显示名（app_name / bundle）
+
+scaffold 生成工程时**自动**定两样设备侧身份（**不需要你在接线里手工改**，命名权威在 `scaffold.ts`）：
+
+| 身份 | 规则 | 主线（缺省 out） | 测试线（`--out test-demo --test-cases`） |
+|---|---|---|---|
+| bundleName | `com.ohpt.<lib>.<out>`（`deriveBundle`） | `com.ohpt.<lib>.harmony_demo` | `com.ohpt.<lib>.test_demo` |
+| 显示名（launcher 应用名） | `<lib> demo` / `<lib> test demo` | `<lib> demo` | `<lib> test demo` |
+
+- 显示名落到 `AppScope/resources/base/element/string.json` 的 `app_name`（模板占位 `__APPNAME__` 经 substitute 替换）；`app.json5` 与 `module.json5` 的 ability 都 `$string:app_name`，launcher 显示的就是 AppScope 这份。（cximage 2026-09-16 反馈：主线/测试线两个 demo 桌面同名难分辨，遂加 `test demo` 后缀。）
+- **显式 `--name` 仍最优先**：段 6 不传 `--name`，走默认命名。
+
+**四条会让「生成对、装机显示却不对」的边**（命名 fix 管不到的地方，逐一排查）：
+
+1. **增量/断点续跑不重写 string.json**：`test-demo/` 已存在时 scaffold 走增量同步（只重生成用例表 + 页面树），模板、`string.json`、`app.json5`、`module.json5` 一概不动。旧版 scaffold 生成的工程盘上 `app_name` 恒为 `<lib> demo`，重跑也不会变。**scaffold 已加告警**（增量模式下盘上 `app_name` 与应得名不一致时点名），看到告警就移走 `test-demo/` 重建（或手工改 AppScope `app_name`）再重构建。
+2. **`dist/app` 是构建产物，hvigor 有增量缓存**：scaffold 重写源码后若没真重新 `build-hap.sh`（或 hvigor 命中缓存），HAP 里仍是旧名。改名后**必须重新构建**。
+3. **启动器缓存显示名**：同名 bundle 覆盖安装时 old 名可能残留，改完名后重启设备刷新缓存（electron recipe 的 `case-marktext` 同款经验）；测试线/主线 bundle 不同名，若同库装了旧 demo 也先卸载旧 bundle（同名 HNP 符号链接会撞，见 §3）。
+4. **`sign-demo` 缺省签的是阶段 3 工程**（E172，libaribcaption 2026-09-17 实证）：`--demo-dir` 缺省按 `harmony-demo`/`harmony-app` 探测——测试线工作区两棵子树并存时，手工执行省掉 `--demo-dir test-demo` 会签错包（signedHap 落在 `<ws>/dist/app/` 而非 `<ws>/test-demo/dist/app/`），装机"成功"但 test_demo bundle 上仍是旧包，表现为「改了没生效」。对账方法：signedHap 路径必须落在被验证的 demo 子树内；装机后 `bm dump -n <bundle>` 看 installTime 刷新。
+
+---
+
+## 1.1 单页 demo：生成物长什么样，你要改哪里
+
+生成物按**执行驱动器**分两档（`cases.json` 的 `driver` 字段声明；它也是 `run_all.supported` 的唯一判据）。
+
+**自驱档**（`native-c`/`python`：被测代码由 native/解释器主循环驱动，ArkTS 点不到入口）——**单页浮层**：
+
+```
+entry/src/main/ets/
+  pages/Index.ets              唯一 @Entry：满屏 XComponent（上屏 surface + 线程壳启动点）+ 可收起浮层
+  common/OhptCaseBus.ets       ★ 唯一适配点：页面发指令 / 读回结果镜像
+  common/OhptCases.ets         ★ 用例与模块表（单一真源，勿手改）
+  common/OhptTestInfoPanel.ets 测试信息区——**只吃 caseId**，字段（含每步判定点）从表里查
+entry/src/main/cpp/ohpt_cases.h  ★ 用例表 + 驱动器：循环/结果行/汇总行/停留/自愈全归生成器
+```
+
+**不走 router**（XComponent 只能挂一次，被路由顶掉即 surface 注销），三级浏览用页内状态切换。
+接线者只实现头文件声明的那几个函数——**设计了却没接线的用例会链接失败**，不会静默漏跑。
+
+**生命周期归驱动器**（各钩子契约见生成的 `ohpt_cases.h` 头注释，照它做即可）。唯一要你判断的是
+**前置条件写着「库处于未初始化状态」的用例**：先释放共享 init 再自行初始化，否则被测路径根本不执行
+（glfw F-10-03 实证：分配器只在 init 期间被调用，共享 init 下 `glfwInit()` 直接返回真、计数恒 0）。
+这是**恢复用例自己的前置条件，不是放宽断言**。
+
+**ArkTS 驱动档**（`arkts`）生成的页面树（差异只在 `OhptCaseRunner.ets`）：
+
+```
+entry/src/main/ets/
+  pages/Index.ets              ★ 唯一页面：底层是被测物的常驻画面，上层浮层承载
+                                 模块列表 → 用例列表 → 用例详情（说明 / 操作 / 结果 / 人工结论）
+  common/OhptCases.ets         ★ 用例与模块表（单一真源，勿手改）
+  common/OhptTestInfoPanel.ets 测试信息区——**只吃 caseId**，字段（含每步判定点）从表里查
+  common/OhptResultPanel.ets   结果区
+  common/OhptCaseRunner.ets    ★ 唯一的 kind 适配点：按 caseId 调到被测物
+```
+
+**为什么是一个页面而不是三级 router 页**：**载体不得成为被测物的一部分**。
+router 切页会销毁 XComponent surface，而 native 侧的常驻循环正持着被测物的窗口；
+更要命的是 surface 尺寸此前等于「该用例说明面板之外剩下的那块」——GLFW 真机实测同一个
+`glfwCreateWindow(640,480)` 在不同用例页拿到 2030x381 或 2030x310，差值就是说明文字的行数，
+于是窗口几何类用例测的是 ArkTS 布局而不是被测库。单页后 surface 铺满整页、尺寸恒定、跨用例常驻。
+
+**三个入口共用这一套视图状态**（不是 pushUrl），分流细则见 §5。
+
+**测试信息区与操作控件都不需要你写、也不需要你核对**：信息区只接收 caseId、字段从
+`OhptCases.ets` 查；操作控件由生成器按 `steps[].action` 的语义直接产出（输入型的步骤给参数框），
+参数经请求行的 `p1/p2…` **真传进被测物**。**别手改它们，也别改 `OhptCases.ets`**（重跑会覆盖）。
+
+**你要改的只有一处**——按 caseId 分派到该用例真正要验的符号（`covered_apis_source` 是找符号的线索）：
+
+- `cli-hnp-runner` 档：`entry/src/main/cpp/napi_stub.cpp` 的 `ohpt_custom_case()`——kCases 表行与
+  分发骨架已按 05-testcases 生成，只填执行体（多步调用+内容断言；单测试二进制形态改表行 bin/cwd 即可）。
+  **线程模型已内置勿改**：runCase 入队即回 + worker 线程逐条跑 + ArkTS 轮询 pollStatus——把执行改回
+  同步等待会冻屏并触发系统 ANR（7zip 26.03 三用例真机实证：F-01-05 218s/F-02-05 50s/F-06-01 43s
+  全弹「没有响应」，2026-09-10）。长 exec 预算给足——富用例体 `run(args, tmo)` 的 tmo 按
+  host 实测 × 设备慢化系数标定（默认 90s 会腰斩分钟级用例，7zip mmt1 ~200s 实证）；
+  兜底纪律见 §3「每条 exec 必须有兜底」（alarm 兜底不可靠，E178）。
+- 其他 `cli` 档：`common/OhptCaseRunner.ets` 的 `ohptRunCase()`；执行体在模板
+  `napi_stub.cpp` 里用**自带的 `CaseReport` 报告器**组织返回值（`step()` 过程行 + `check()`
+  判定行，格式契约见 §5——别手搓格式，页面着色与判定解析都按它来）
+- `gui` 档：`entry/src/main/cpp/gui_shell.cpp` 的 `ohpt_run_case()`（常驻循环已生成）
+
+**每条判定点都要有一个来自给得出它的判定者的结论**（验收规则 `checkpoint-verdict-complete`
+拿阶段 5 的 `steps[].checkpoint` 当分母逐条对账）：
+
+- 机器判得了（观测值能从被测物取回来）→ `OHPT_CHECK(id, cp, ok, expect, actual)`。
+  **读了值、打了日志、然后 return true 不算判定**——expect/actual 是「比对过」的唯一凭据。
+  **内容口径（codec2 测试同学三轮反馈收敛，2026-09-12）**——测试同学在页面上对照的是
+  上方「预期:」那一行整文本，所以：
+  - `expect` 传**预期文本的子句**（与 05-testcases 的 `expected_result` 逐词一致，按语义分条），
+    **不传 `steps[].checkpoint` 文案**——判定点措辞与预期行不同，等于给人工对照又加一层翻译；
+  - `actual` 写**人话陈述「实际发生了预期里的什么事」**（如「ZIP 归档已创建」「每帧编码 64 比特，
+    与 1600 模式预期值一致」），**不写裸机器值**（`rc=0`/`ptr=non-null` 要人脑翻译）；
+  - 关键步骤随手补 `OHPT_NOTE(id, "以 1600 模式创建编码器实例")` 一类**过程叙述**（每层发生了啥，
+    不参与判定，只进页面的【执行过程】段）——测试同学排障不用翻 hilog。
+  机器对账不受口径影响：`checkpoint-verdict-complete` 按 cp 序号+ok 对账，expect 仅查非空。
+- 机器判不了（上屏对不对、要人先按键才触发的回调）→ **什么都别打**，让它落 `pending-human`，
+  由人在页面上点「符合 / 不符合」（打 `OHPTCASE human` 行）。**替人下结论**正是假绿的来源。
+
+**TAP 行格式硬契约**（codec2 2026-09-15 实证）：native stub 的 TAP 拼装**必须**遵循
+`ok <N> <id>`（pass 不带 detail）/ `not ok <N> <id> -- <detail>`（fail 才带，前 300 字符）——
+RunAll 页解析器剥序号后直取 id。**禁止自创分隔符**（如 TAP13 惯例的 `ok N - <id> # <detail>`）：
+解析器会把 `-` 当 id，16 行全部不回填 → 全部执行页恒显 0/16（单条页不受影响因它不解析 TAP）。
+验收规则 `demo-tap-format-valid` 在 PostWrite 时对 napi_stub 的 TAP 拼装代码做机器校验。
+
+---
+
+## 1. GUI / 上屏形态（`app`、`graphical-window`、`gl-context`、`ui`）
+
+**kind**：`cpp-gui-owb-demo`（C/C++）、`python-gui-owb`（Python）
+
+- 载体是 HAP + OWB（`ohos-window-bridge`）+ XComponent，原生侧直连 GLES。
+- **页面由 `scaffold --test-cases` 直接生成**（六个 kind 共用一份生成器），你不必手搓骨架。生成物见 §1.1。
+- native 侧是 `_shared/ohpt_case_loop.h` 的**常驻循环**：跑完一条继续等下一条，画面一直在。
+  它只用 OWB 的公开 API——**OWB 是适配产物的一部分**（被测库的鸿蒙后端直接调它，交付面
+  `harmony-demo/` 也编译它），载体不得为了自己好写去改它。
+- 取证：`verify-demo` 会装机 → 拉起 → 等渲染稳定 → 抓 GL 身份 + hilog（解析 `OHPTCASE` 结果行）。
+- **结果判定读 `verify/<case-id>.json`**：`case_result=pass` 且 `log_channel=open` 才达标（结果行协议：
+  `OHPTCASE` tag 打 `result=<pass|fail|blocked> id=<case-id>`，自驱档由**生成的驱动器**在 `ohpt_serve()`
+  的循环里打、接线者不经手；能力缺失/前置不满足用 blocked helper 打 `result=blocked`，别手搓 hilog 行）。
+- **上屏效果由人工在 demo 页面上验收**，机器不判图、测试线也不再存截图。自驱档的 demo 是
+  **满屏 surface + 可收起的浮层**，每条用例画完停留 `ohpt-dwell-ms`（页面可调速）——人一眼看得出这条画对没有。
+  而且**页面就是人下结论的入口**：看完点「符合 / 不符合」，结论走同一条 hilog 通道回到产物。
+- 链路真假由机器管：载体自打的 `surface created` 与 `GL_RENDERER=` 两行缺席即告警
+  （验收规则 `testdemo-surface-attested`）。**判据是「该答有没有答」而不是「必须有 GL」**——纯计算/CPU
+  像素路径如实打 `<none>` 即通过，所以它不误杀非上屏载体。
+
+常见坑：
+- 窗口创建有竞态——拉起后要等渲染稳定再取证（`verify-demo` 已内置等待）。
+- 结果行缺失的 pass 会被验收规则点名（`testdemo-case-result-logged`）；`log_channel≠open` 时判 blocked，先修通道。
+- **某条用例污染进程状态**（典型：`terminate` 连带清掉宿主线程拥有的资源注册表，之后再也建不出窗口）时，
+  载体自报 `OHPTCASE aborted` 行、宿主在新进程里续跑残余——**不必预先知道是哪条**，也不要按载体名整档判死。
+- OWB 源码唯一权威在 `pc-capability-domains/references/solutions/ohos-window-bridge/`，工作区里的是构建副本，别改副本。
+- **scaffold 生成的 `cpp-gui-owb-demo` 模板默认不含 `<XComponent>` 元素**，OWB 线程的 `OWB_WaitForSurface(-1)` 会永久阻塞。必须在 `Index.ets` 中手动添加 XComponent 提供 surface 登记通道（某图像库 实证，2026-09-09）：
+  ```typescript
+  // entry/src/main/ets/pages/Index.ets
+  XComponent({ id: 'xcomponentId', type: 'surface', libraryname: '' })
+    .width('100%').height('160px')
+    .onLoad(() => { /* OWB surface 就绪回调 */ })
+  ```
+- **存量旧版 gui test-demo（2026-09-16 前的 scaffold）用例执行通道识别与升级**：若 `common/OhptCaseRunner.ets` 的 `ohptRunCase()` 内容为「把 caseId 写进沙箱文件 + 提示 `aa start --ps caseId` 命令行拉起」、且 `gui_shell.cpp` 的 `main()` 读文件跑一条即退、`OhptRunAllPage` 的 `start()` 是空桩——这是旧版载体的「点击执行不了」缺陷，不是功能缺失。升级配方（NAPI 用例桥：`exports.runCase(caseId)` Promise + 常驻渲染循环 + `std::once_flag` 去重双 worker + 步骤痕迹结果区）见
+  `pc-knowledge-base/adaptation/鸿蒙PC-gui-test-demo-旧版OhptCaseRunner升级NAPI桥.md`；
+  升级后把 `cases.json` 的 `run_all.supported` 翻成 `true`。**新版 scaffold 已无此问题**（自驱档走 `OhptCaseBus.ets` + `ohpt_case_loop.h` 常驻循环），不要给新版再叠加 NAPI 桥。
+- 已知两个 NAPI 桥自身的 C++ 坑（过编译、真机才暴露）：`char[] == const char*` 比地址不比内容 → E162；`g_case_busy.store(false)` 必须在 `napi_resolve_deferred` 之前（await 续延可能先于晚清位）→ E163。
+
+---
+
+## 2. 音频形态（`audio`）
+
+**方案**：`pc-capability-domains` 的 `solutions/ohaudio-backend`
+
+- 必须真接 OHAudio 后端并捕获 `audio-verify.json`：**renderer 真拿到 + 真写出帧**。
+- 「编得出但后端被裁掉」不算达标；只看播放行为也是假绿——判据要钉在设备枚举与帧写入上。
+
+---
+
+## 3. CLI 形态（`cli`）
+
+**kind**：`cli-hnp-runner`
+
+- 载体是私有 HNP 包 + `fork`/`execv` 执行器 HAP，输出经 hilog 回传。
+- **商用机（零售 / 不可调试）唯一已实证的 exec 通道就是它**——`hdc shell` 是 uid2000，进不去应用沙箱。
+- 主证据是 hilog 里的 **TAP / 原始 stdout**（完整一份落 `verify/device-raw.log`）。
+- 用例两种接法（kCases 表）：**单测试二进制**（bin/cwd，rc==0 即 pass——libetpan 37 ELF 实证）；
+  **富用例体**（bin=nullptr → `ohpt_custom_case()`：多步 exec + 内容断言——7zip 的 a→l→x→h 带参数
+  调用、哈希比对、计时比较类）。`--test-cases` 生成表行与分发骨架，接线者只填体。
+- **上游测试程序的接法优先级**（上游带 `test/` 目录时）：①上游测试**原样编成真二进制**走
+  单测试接法（每个测试独立 ELF，fork/execv 自带合法 argv——最忠实上游语义）；②上游语义
+  需组合断言时才重写富用例体。**禁止把上游测试的 `main` 编进载体进程**做 combined-driver
+  以 `fn(0, NULL)` 调用——argv[0] 解引用、退出码传递、atexit、进程名（argv[0] 派生）四类
+  语义全被载体破坏，nlist/errwarn/progname 三连 SIGSEGV + 假 FAIL（libbsd 9/9 实证 3/8 FAIL
+  同根因）。
+- **bin 型测试 ELF 必须自备实际值输出**：ELF 的 stdout 经 run_cmd 管道原样回传页面结果区——
+  它是富用例体 OHPT_CHECK 双落点在 bin 型下的**等价物**（逐断言 `printf("<函数名> → %格式符\n", 值)`，
+  写法纪律见 [[鸿蒙PC-C库设备验证测试设计]] §2）。无输出的静默 assert 型在页面上只有
+  `rc=0` 一行，测试同学无法人工核对（libbsd 2026-09 实证）。
+- **接上游 ELF 且其为静默 assert 型时，结果如实标注**：上游 `test/*.c` 原样跑是设计原则
+  （不手改上游源码），静默型的结果区没有值流水属正常——narration/notes 标注「上游原样
+  静默测试（无中间值输出），判定依据为断言+rc」，别让测试同学误以为坏了；确需人工核对
+  值时改接 gen-\* 或补 printf 补丁（走 patches/）。
+- **bin 型结果展示组装规范**（与 cpp-lib-demo 的 CaseReport 共用视觉语法，语义不伪装）：
+  `【id 标题】` 分节头（加粗）+ raw 值行加 `· ` 前缀（灰过程行）+ `[cp:N]` 锚点行按步骤
+  归属着色；**叙述段与 TAP 保留**（前者列全部 checkpoint 供对照，后者是机器判据单源）；
+  判定如实为整条级（`√ 断言通过（rc=0）`）——**不逐点标 √/×**（判定点级机器判定只属于
+  富用例体形态，bin 型伪装逐点绿红会误导：一条 rc 定所有行的颜色）。
+- **环境归因必须在目标形态下实测**：同一 API 在 in-process（HAP 宿主）被判「seccomp 拦截/
+  不可测」，换 bin 型独立进程实测可能一次通过（libbsd getpeereid：in-process 判 SO_PEERCRED
+  被 seccomp、独立 ELF rc=0——载体形态才是变量）。「平台不让跑」的结论对载体敏感，换形态
+  先实测再定性，别拿 in-process 的失败直接填 capability_gaps。
+- **多族合一用例接单 ELF 时避开分歧族**：用例覆盖多个 API 族、kCases 只能接一个 bin 时，
+  选**非分歧族**的 ELF——分歧族（musl/BSD 语义差异，查 [[鸿蒙PC-musl与BSD-glibc语义分歧表]]）
+  的上游断言在 musl 上天然不过，接它等于给用例埋雷（libbsd F-06-02 接 funopen 撞 fclose==0
+  分歧，换 gen-flopen 即过）。
+- **线程模型契约**：runCase 入队即回，worker 线程串行消化，ArkTS 轮询 pollStatus——主线程零阻塞。
+  禁止把执行改回同步等待（冻屏 + ANR）。worker 长阻塞（分钟级 exec 等待）已被 7zip 397s 全套实证安全。
+- **每条 exec 必须有兜底，但兜底不是 alarm**：alarm 作 exec 兜底有两种实证失效（E178：
+  孙进程持 pipe / blocked 掩码阻断信号递送），到点杀不掉时一条 exec 就堵死串行队列、
+  整轮无 summary/end。兜底由**父进程 poll 计时 + 超时 `kill(-pid, SIGKILL)` 杀全组**承担
+  ——**已固化进模板**：cli-hnp-runner /
+  cpp-terminal-demo / python-app-subprocess 三模板生成物天然免疫，agent 不再现场实现。
+  另有**名册总预算 20min**（对齐 device_budget.cap_min / 租约上限）作最终安全网：到点
+  收当前条、清剩余队列、照常打 summary/end——名册永远有结局。
+  预算按用例度量标定、可调大（网络类默认 90s，分钟级压缩/基准类给足）；**`run(args, 0)`
+  = 显式豁免**（语义不变，仍可传），但豁免由总预算兜底——**豁免 ≠ 无兜底**。被收条目记
+  **blocked**（非 fail，detail 含 killed 标记可回标预算）。设备侧重度自测先判「真慢还是
+  挂死」（E178 判别 5）：真慢属名册选型问题，降级 blocked 或减规模，别调大预算硬扛。
+
+常见坑：
+- **CLI stdout 内容断言在 exec 管道下不可靠**：HNP 执行器 fork/execv 走管道、无 TTY
+  （`isatty(0/1/2)=false`，机制见 `pc-capability-domains` terminal-tui），部分 CLI 工具在
+  非 TTY 下 stdout 行为与终端不同——某国密 OpenSSL 分支 `openssl genrsa 2048` 无 `-out` 时 stdout 为空，
+  钉 stdout 内容的 PEM 断言全挂。断言改钉**产物文件**：`genrsa -out key.pem 2048` +
+  `stat(key.pem)` 存在且尺寸合理（某国密 OpenSSL 分支 test_gensm2 实证，2026-09-17）。
+- **`entry/libs/` 放自编交叉 .so 会毒化同 bundle 的 HNP exec 白名单**（libbsd 9/12 实证，11 组对照）：
+  三态指纹 = **装机 success + in-process dlopen 正常 + 所有 HNP ELF exec 即 SIGSEGV**（零输出、
+  无 faultlog——进程死在启动前）。改名、去 `.codesign` 都不解——`libs/` 只允许系统库
+  （`libc++_shared.so`）与 napi 模块。**同 bundle 内 in-process dlopen 型与 HNP exec 型互斥**
+  （dlopen 只认装机登记的 so；HNP bin/ 直读、沙箱拷贝全被 loader 拒：Invalid argument /
+  File exists）——**cpp-lib 双载体混跑时全部用例统一走 exec（bin 型）是唯一共存形态**。
+  典型误诊：「XPM/代码签名 per-bundle 拦截」——对照实验前先核两份 HNP/产物是否真同字节。
+- **bin 型用例 `cwd='writable'` 必须映射到沙箱可写目录**：scaffold 生成的 test-demo 骨架
+  可能缺 `g_tmp_dir` 映射（原 harmony-cli-runner 有、新 scaffold 版本没有），bin 型用例
+  `chdir(cwd)` 落到不可写/不存在目录 → `rc=126` 全挂。首跑若整批 bin 型 rc=126，先核
+  执行器 worker 里 `g_tmp_dir`/`TMPDIR` 是否指向 `/data/local/tmp/...`（libaribcaption
+  test-demo 实证，2026-09-15）。
+- **test-demo 与 harmony-demo 共用 HNP 名会撞设备全局符号链接**：同库的两个 HAP（阶段 3
+  的 harmony-demo 与阶段 6 的 test-demo）若打同一 HNP 名，`/data/app/bin/<tool>` 符号链接
+  冲突，新装者 exec 旧名 → rc=127 找不到。安装 test-demo 前先卸载旧 bundle（libaribcaption
+  实证：test_demo_cases ELF 找不到 rc=127，卸载旧 HAP 后恢复）。
+- **bin 型可复用主线已验 ELF 作为 demo 用例证据**：cpp-lib 且阶段 3 已产出测试 ELF
+  （如 test_capi/test_decode/test_gen_*）时，05-testcases 中与这些 ELF 语义重叠的用例
+  **直接以 bin/cwd 接主线 ELF**，不用重写富用例体——`rc==0` + ELF 内部自断言即等价于
+  逐判定点 OHPT_CHECK（libaribcaption 实证：49 条用例中 12 条 bin 型映射主线 ELF、
+  37 条富用例体 exec 综合 ELF 按 caseId 分派，49/49 全过）。**前提是 ELF 自备实际值输出**
+  （逐断言 printf 到 stdout，页面可核对），静默 assert 型仍需富用例体。
+- 设备默认 PATH 不含 HNP：`which <tool>` 探不到 ≠ 设备上没有。断言「设备缺 X」前先走标准位置矩阵（`ohpt-agent env --runtime <eco> --device-only`）。
+- 别为了让用例过而造 fake 存根——git-lfs 案例据此拿到 7/7 PASS，而设备上 git 2.45.2 一直在。
+
+### 测试程序准备
+
+阶段 6 接线前，逐条按 `cases[].covered_apis_source` 在 `tests-generated/` 与 `source/src/tests/` 查找对应 `.c`：
+
+| 源码与包内二进制 | 动作 |
+|---|---|
+| 有源码，且 `dist/testbins/` 或 HNP `pkg/bin/tests/` 有二进制 | 正常接线 |
+| 有源码但未编译进 HNP | 补命令到 `build/build_tests.cmd` 或现有测试构建脚本，编译并重新打包，不直接记 blocked |
+| 无对应程序 | 按下述范围补最小程序；依赖未具备的外部能力时如实记录缺口 |
+
+若 API 在 `03-adapt.json` 产物中存在（用 `nm` 或头文件核实）、且属无需网络或特殊设备的纯计算/内存类，
+补写 `tests-generated/test_<lib>_<feature>.c`，沿用同库已有测试风格：逐条 stderr PASS/FAIL、末尾 stdout PASS/FAIL 及 `assert(ret==0)`。
+断言钉数据/行为（数值范围、往返一致、非空输出），不凭空钉外部阈值或错误码；追加编译命令时带 `-Wl,--code-sign`，重新打包后接线。
+这是阶段 6 最小验证程序的归属例外，不能改被测产物或适配代码。
+
+依赖网络、流源或设备能力而缺少验证前提时，不按此例外补写程序；记录 `result=blocked`、
+`suspected_cause=missing-capability` 及 `coverage.capability_gaps[]`，说明真实库级限制（如 `NETWORK=#undef`），不只写「无测试程序」。
+cmd 编译脚本避免中间变量套嵌套引号，路径含空格时会碎裂成 `clang: error: no input files`；使用内联 flags，见 `pc-error-atlas` E144。
+
+---
+
+## 4. 库形态（`cpp-lib` / `native-extension` / `pure-runtime`，非上屏）
+
+> **本形态要双载体**：HAP 内调用 + CLI 执行两条路径都要跑通。该产哪些、各用哪个 kind，
+> 由 `ohpt-agent state -w <ws> --json` 的 `workspaces[].verify_carriers` 给出（只读；gate env
+> 块同源，两个都免费查），**本文不复述路由**，只讲怎么接线。
+
+**kind**：`cpp-lib-demo`（C/C++ NAPI 壳）、`python-app-embedded` / `python-app-subprocess`（Python）；
+CLI 那一半统一走 `cli-hnp-runner`（见 §3）
+
+- NAPI 壳里**逐个功能点**调适配产物的代表符号，返回值回显到页面并同时打 hilog。
+- **全局分配符号的隔离接线**：库若实现并导出
+  `malloc/free` 或 C++ `operator new/delete`，不能沿用普通库的 `target_link_libraries` 接线。
+  `.so` 仍由 `NATIVE_LIBS` 随 HAP 打包，但不放进 NAPI 壳的 `DT_NEEDED`；壳中用
+  `dlopen(..., RTLD_NOW | RTLD_LOCAL)`，所有被测函数、C++ 操作符和可写全局变量均通过同一
+  句柄 `dlsym` 获取。用 `dladdr` 核对符号来自被测库，防止缺符号时回落到 libc 而假绿；
+  加载或必要符号解析失败要返回真实 fail，构造期探针也必须检查，禁止继续调用空函数指针。
+  库内可写配置变量通过句柄取得地址后访问；不要再依靠测试壳强定义
+  同名全局或保留直接引用。初始化配置所用字符串、回调必须长期存活，库句柄保留至进程退出。
+  测试壳自己的 `std::string/vector` 与显式被测分配各自保持分配/释放配对；涉及 C++
+  操作符的用例仍须真实调用库内符号，不能改成系统 new/delete 来回避测试。
+  公共产物通道使用单次调用的独立缓冲，避免为每条用例固定申请大块 C++ 堆内存；
+  缓冲区调整不能代替分配器隔离。已有 `test-demo` 按增量保留策略不会自动获得
+  新模板，重跑时须同步迁移其 CMake、NAPI 接线及公共 OhptCaseEnd 缓冲实现，保留已实现的用例分派。
+  构建后检查壳 ELF 不再依赖被测分配器、
+  不再直接引用其配置全局；真机验收应同 PID 连续执行全部用例（冷 1 + 暖 2），再执行单项，
+  不能靠重启进程或禁用按钮判定已修复；异常须通过隔离前后的行为差分定位。
+  `verify-demo --cases` 在装机前静态核对 HAP 原生库的 NEEDED 链，阶段 6 验收也执行
+  `demo-allocator-isolation` 检查；按已定义导出符号识别分配器，不按被测库名称配置规则。
+  新建和增量工程均须检查，历史 pass 不免检。通过 demo 同进程入口完成各轮，保留日志；
+  重复调用 force-stop 的 verify-demo 不算暖重跑。闪退、轮次未完成或缺少同进程证据时，不能宣布回归通过，报告 notes 写明结果及证据路径。
+- **NAPI 壳的线程模型（禁止主线程同步跑用例）**：`OhptCaseRunner.ets` 的 `ohptRunCase` 若在主线程
+  同步调 `demo.callCase`，native 侧含 fork/exec + waitpid/usleep 轮询（exec_capture 超时上限可达
+  30s+）时主线程被阻塞——执行中用户再点「执行本用例」，输入事件排队超时 → 弹「应用未响应」ANR
+  （usbredir test-demo 实证，2026-09-16）。native 侧改 `napi_async_work` + Promise（或 ArkTS Worker）
+  把执行移出主线程，回调回主线程更新 UI 与 `running` 守卫；**hilog 的 OHPTCASE check/result 行保持
+  native 单点发出、语义与顺序不变**（机器验收只认它）。页面层已有的 running 守卫 + `enabled(!running)`
+  是必要不充分——主线程被阻塞时守卫来不及生效。
+- 证据是设备端**原始输出**（完整 stdout / TAP），落 `test-demo/verify/*-raw.log`。聚合数字不构成证据。
+- 纯运行时库若设备侧缺解释器/运行时，先按 `pc-knowledge-base` 的「设备语言运行时探测与供给」供给，再跑。
+- **CLI 用例在双载体分配时的通道限制**：当 `delivery_form=cpp-lib` 且 `verify_carriers` 为 `hap`（如 `cpp-gui-owb-demo`）时，该载体无私有 HNP exec 通道，只能调 `lib*.so` 的 API 符号。CLI 侧用例（某图像库相关功能点实证，2026-09-09）应通过同源解释器 API（如 `某图像库::run`）验证，CLI 二进制本身的独立 exec 已在阶段 3 通过 `cli-hnp-runner` 完成。**不要试图在 hap 载体中 execv CLI 二进制**——app 域无 `exec` 权限（除非显式带 HNP 执行器）。
+- **混合载体：给 cpp-lib-demo 自带私有 HNP（CLI 用例不再依赖第二个工程）**：库形态同时带 CLI 工具时，可以把 CLI 二进制 + 其依赖 .so 打进 **demo 自己的**私有 HNP——`module.json5` 加 `hnpPackages: [{package: "usbredirect.hnp", type: "private"}]`，build 脚本把 HNP（hnp.json + bin/，Unix 权限条目 0o100667 + 目录条目先行）zip 注入未签名 HAP 的 `hnp/arm64-v8a/`；native 侧 `fork/execv("/data/app/bin/<tool>")` 直跑，`LD_LIBRARY_PATH` 指向同目录。设备侧落位 `/data/app/bin/`，`realpath` 拿实际路径。usbredir 0.15.0 第二轮实证（2026-09-17）：F-04 两条 CLI 用例首轮因「hap 无 exec 通道」blocked，补混合载体后与库用例同一次 run-all 跑完（21/21 pass）——比另起 cli-hnp-runner 工程省一个 HAP 的签名/装机/来回。
+- **渲染/出图类库的结果图上屏**：05 在 `steps[].output` 声明图像产物，接线把结果图写进用例沙箱，其余（登记/上屏/验收）全归执行器与生成器——机制见 `pc-test-design` SKILL.md §六；确需 exec 子进程渲染的理由见 `render-preview-page.md`。
+- **计算类 kernel 的输出缓冲必须初始化（E174）**：给 OpenCL/CUDA/Vulkan/GL compute 接线时，凡 kernel 对输出缓冲做**读-改-写**（`atomic_add` 原子累加/桶计数/归约），缓冲创建就必须初始化——`CL_MEM_WRITE_ONLY + nullptr` 未初始化时，冷启驱动零页恰好从 0 累加、暖复跑（同进程二次「全部执行」/复跑）复用脏内存累加到垃圾值，表现为「串跑挂/单条过」的状态泄漏假象（OpenCL-SDK F-04-04 直方图实证 2026-09-20）。修法：`CL_MEM_COPY_HOST_PTR` + 已清零宿主向量做源，或建完 `clEnqueueFillBuffer` 填 0。**回归要连跑暖复跑（冷 1 + 暖 ≥2），别只跑一轮冷启就定稿——这类 bug 只在暖复跑暴露。**
+
+---
+
+## 5. 入口模式（用例清单 → 载体）
+
+阶段 6 的载体形态是**用例驱动**的：`ohpt-agent scaffold --test-cases <05-testcases.json>` 生成
+单页 demo 与分发骨架，并产出 `test-demo/cases.json`——入口清单 + `run_all.supported` 声明。
+
+**一个 HAP 三个入口，各自服务各自的消费者**（人 / 报告），互不改写对方的页面栈：
+
+| 入口 | 谁用 | 落到哪里 |
+|---|---|---|
+| 无参拉起（点图标） | 人工验收 | 模块 → 用例，逐级可回退（自驱档是页内浮层，画面常驻可见） |
+| `--ps ohptRun all` | 宿主默认 + 人点「全部执行」 | 全部跑完并给出「多少条没过」 |
+| `--ps caseId <id>` | 宿主复现单条 / 续跑残余 | 该用例，自动执行一次 |
+
+**一把执行由驱动器决定**（`cases.json` 的 `driver`，scaffold 按 kind 写、宿主照读）：生成器给了驱动器
+就支持一把执行，没给就逐条——**与 carrier 无关**。gui 档不再因「OWB 线程壳的 `main()` 跑完就退」
+被整档排除（那是载体写法问题，常驻循环即可解），但也不无条件当成支持。跑不完不靠静态分档预判：
+载体自报 `OHPTCASE aborted` 行，宿主在同一把设备租约里续跑残余（`mode=run-all+resume`，`launches=1+k`）。
+`--per-case` 仍是复现单条 / 做进程隔离对照的逃生口。
+
+### 用例字段 → demo 里的对应物
+
+| `05-testcases.json` 字段 | demo 里的对应物 |
+|---|---|
+| `modules[].code` / `.name` | 分组标题 / 场景命名空间 |
+| `cases[].id` | 拉起参数 `caseId`；写进 `06-testdemo.json` 的 `case_results[].case_ref` |
+| `cases[].steps[].action` | 该场景要依次做的事（按因果顺序） |
+| `cases[].steps[].checkpoint` | **判定的分母**：每条都要有一个结论（`OHPTCASE check` 机器判 / `OHPTCASE human` 人判），少一条该用例就不得 pass |
+| `cases[].steps[].input` | 页面「步骤N 输入」输入框（预填 default，pair 双框）→ `ohptRunCase` 的 `input` 形参（各步按步骤序 `\n` 连接）→ native 按段拆（空段=该步内置向量）——消费参考见下文「步骤输入的 native 消费」 |
+| `cases[].steps[].output` | 步骤行标「产物：图像·label」；**执行器在用例前后对比沙箱**登记用例写下的文件（`OHPTCASE artifact` 行，bytes/sha 执行器算），结果区按 kind=image 上屏、RunAll 行缩略图；验收 `testdemo-artifact-evidenced` 以它为分母——接线只需把图写进沙箱 |
+| `cases[].covered_apis_source` | 找对应鸿蒙侧符号的**线索**（不是答案） |
+| 实际调用的鸿蒙侧符号 | 回填 `case_results[].covered_apis_harmony` ← 验收规则会核对 |
+
+**多符号协同的用例**：按因果顺序依次接线全部相关符号（如先设上限再设当前值），顺序错等于没验。
+
+### 结果区报告格式（页面显示线）
+
+native 侧返回给结果区的字符串是**给人核对的证据**，按多行报告组织——`OhptResultPanel`
+按行首 `√`/`×`/`·`/`【` 着色解析；cpp-lib-demo 的 `napi_stub.cpp` 模板自带 `CaseReport`
+骨架，**用它，别自由发挥格式**：
+
+```text
+【F-04-01 字符串大小写转换】
+· u8_toupper("Straße", de) → "STRASSE"（7 字节）
+√ [1] 预期子句 —— 实际: "STRASSE"
+× [2] 预期子句 —— 实际: <真实观测>
+—— 1/2 判定点符合，用例 FAIL
+```
+
+- **actual 一律真实观测值**（转换字节/码点/数值/名称/返回串原文）——「ok/成功/一致」这类
+  空文案让人无法核对实际返回是否正确（2026-09 libunistring 测试提单的根因）。
+- **措辞与判定语义一致**：符合预期的异常行为必须显式标「符合预期」——UB 类用例的实际观测
+  （如「子进程被 SIG5(SIGTRAP) 终止」）在通过场景下**必须**写成「符合预期：…（musl libc
+  double-free 确定性处置），主进程正常」，裸写「异常终止」测试同学会当缺陷提单
+  （libidn2 F-01-03 实证，2026-09）；fail 场景对称地标「不符合预期」。
+- √/× 行的 expect/actual 与 hilog 机器线（`OHPT_CHECK`）**同一份**——机器判据照旧走
+  OHPTCASE 行，页面不是第二套判定；页面自动判定按 √/× 行解析（有 × 即 fail）。
+- 过程行（`·`）放关键调用的真实返回；一用例多行 · 可行，但 √/× 行数必须等于判定点数。
+
+**页面判定与机器判据同源（两入口一谓词）**：用例页与「全部执行」页的自动判定必须共用同一
+谓词——有 `× ` 判定点行即 fail、仅有 `√ ` 行即 pass，「非空且不含失败字样」启发式只兜底
+（直接扫「失败」会把预期/实际文本里的叙事词误判成失败，usbredir F-02-03 实证 2026-09-17；
+某图像库相关用例实证（2026-09-21）为镜像方向——runner/用例页已对齐新版、唯 RunAll 页滞留在旧启发式，
+预期文本含「失败」的异常类用例 run-all 误判 fail 而单条 pass，症状为「run-all fail / 单条 pass」）。
+carrier=cli（ArkTS 拿得到同步返回值）时 `OhptCaseRunner.ets` 的 `ohptRunnerAutoJudges()` 必须
+返回 `true`——返回 false 会把用例页的 √/× 判定分支整个挡死：页面永远停在「已出结果」、
+不打 `result=` 行，而 RunAll 页照常出结论，两个入口结论不一致（E171，libaribcaption 2026-09-17
+实证：24 个用例页被 runner 的一个 false 全部命中）。
+
+**存量偏移（版本偏移）**：scaffold 对 `OhptCaseRunner.ets`/`OhptRunAllPage.ets`/case 页走
+「内容有差异即保留」策略（阶段 6 接线点保护）——**模板升级不会自动跟进存量工作区**，「改了
+模板」≠「存量已修」。重跑 scaffold 时被保留的文件会被点名，按点名手工合并；确认无定制可
+丢弃时 `--force` 重生成（E171）。
+
+**多步输入用例**（`steps[].input`）：结果**仍走 CaseReport**，用分节表达步骤对齐——每个输入
+步骤一组「`· 步骤N [输入值]→真实观测` 过程行 + 该步的 `√/× [判定点 N]` 行」，与测试信息区的
+步骤逐条对照（libidn2 测试同学诉求：多场景一次测完、结果按步骤顺序、与预期一一对应）。native
+侧消费约定与拆段参考见下节。
+
+### 步骤输入的 native 消费（`steps[].input` 的对端）
+
+文件路径资源与输入证据按 [默认输入与资源契约](input-resources.md) 执行。生成包装层在 native
+清理临时目录前已准备稳定目录并传绝对路径，接线须消费该路径，不能重新选择另一个内置夹具。
+
+页面把声明了 input 的步骤按顺序以换行字符（`\n`）连接传给被测物入口（`runCase(caseId, input)`）。
+ArkTS 自判批量执行从生成的 `OhptDefaultInputs.ets` 读取相同 default 并显式传入；
+不能传空输入绕开页面默认样本。用户清空输入时回落内置向量，内置向量须与设计 default
+满足同一预期；native/GUI 全套入队档仍须另用单条页面验证默认输入。
+native 侧的三条约定（libidn2 实证的参考实现，
+`napi_stub.cpp` 可直接照此写）：
+
+1. **拆段**：按 `\n` 拆成段数组（段序=步骤序、每段去首尾空白；空段保留占位）。第 i 步的输入
+   为空/缺段 → 该步回落 demo 内置向量——**不静默吞**：解析格式错（如码点序列写坏）要显式打
+   fail 的 check 行（「无法解析输入: …」），用户需要知道输入没生效。
+2. **形态解析**：`codes` 段宽容解析码点/数值序列（`U+00D6, 00FC, e4`——前缀 U+/0x 可省、
+   分隔逗号/分号/空白均可、超 U+10FFFF 或非十六进制判格式错）；`pair` 段按首个 `|` 拆双值。
+3. **报告**：用模板的 CaseReport——每步骤一节（`· 步骤N [输入]→真实观测` + `√/×` 判定行），
+   **不要**另造 `"; "` 拼接之类的平行格式（页面 ResultPanel 按 √/×/·/【 逐行着色，其他格式
+   会失去着色与判定解析）。
+
+**往返用例的数据关联**：第一步原始数据及其生成规则以阶段 5 的 oracle.conditions 为准，
+第二步 default 必须等于第一步实际编码结果。接线后用真实 API 核对，不得分别维护两套
+无关联的向量。正常默认操作必须实际满足全部判据；`rc=0` 和长度正确不能替代内容一致。
+失败报告分别列出这些条件，内容不一致时显示首个差异位置及预期/实际值。
+修改 default 后重跑 scaffold；被保留的旧单条页及批量页须合并更新后再构建。
+
+**UB 类步骤（double-free/野指针）的执行形态**：必须在**隔离子进程**中执行——fork 后子进程
+执行危险操作、经管道回报进度信号、父进程 `waitpid` 按 `WIFSIGNALED/WTERMSIG` 判定（预期 =
+确定性处置被触发，不钉具体信号值）；父进程与 demo 不受爆炸半径波及（libidn2 F-01-03 的
+fork/pipe/waitpid 实证实现，预期写法见 musl 分歧表族 6 与 pc-test-design §九 UB 红线）。
+
+### 接线前宿主预演（预期自证的最后一道闸）
+
+**宿主能跑原工具/原库时**（原平台二进制、或宿主自编的等价物），接线前把每条用例的命令与
+预期在宿主上预演一遍——**只对拍预期，不要求宿主环境与设备一致**：
+
+1. 逐条用例：按 `steps[].action` 在宿主执行等价命令，比对 `checkpoint` / `expected_result`；
+2. 预期不符 → 回阶段 5 修用例预期（记 notes 出处），**不要**带着已知错的预期上真机；
+3. 宿主跑不了的场景（平台独有命令、设备侧夹具）如实跳过，不硬凑。
+
+> 实证（7zip F-09-02，2026-09-04）：「压缩缺失输入文件 → 预期退出码 2」，上游契约实为
+> **warning → 1**（宿主 `7zz a bad.7z no-such-input.txt; echo $?` 一秒实测），真机一轮才暴露，
+> 双阶段返工。阶段 2 名册有「宿主自证」纪律、测试线用例此前没有——本节即测试线的对应闸门。
+> 预演发现的**真差异**（musl/glibc 语义分歧类）按 pc-knowledge-base 的 musl 分歧表处理，
+> 预期改写须在 06 的 notes 留痕（class=basis 指回分歧来源）。
+
+### 断言要件覆盖（弱断言=假绿，测试提单的整类根因）
+
+预演除了对拍「预期对不对」，还要**把实际观测转成断言素材**：checkpoint 里的每个可观测
+要件——**数量、大小、内容、顺序、上限**——都必须有对应断言。**只验存在 = 弱断言**：它只
+证明「生成了」，不证明「生成对」；机器判据照样全绿，测试同学看到的是与预期不符的呈现。
+
+> 实证（7zip F-08-01，2026-09-14）：checkpoint =「生成**多个**分卷文件，**各卷**大小不超过
+> 指定分卷尺寸」，断言只写 `exists(vol.7z.001)`——两个要件（多卷、尺寸上限）全漏。真机
+> 6 卷全部正确生成（`Volumes: 6, Everything is Ok`），页面上却只见「vol.7z.001 在盘」，
+> 测试同学按字面理解为「只生成了一个分卷」提单。修复即正例：
+
+```cpp
+// 正例：数卷循环（后缀递增计数）+ 每卷尺寸上限 + actual 带观测清单
+int volumes = 0; long long max_vol = 0; std::string vol_list;
+while (true) {
+  char suf[16]; snprintf(suf, sizeof(suf), ".%03d", volumes + 1);
+  const std::string vp = path_of("f08_01/vol.7z") + suf;
+  if (!exists(vp)) break;
+  ++volumes; long long sz = fsize(vp);
+  if (sz > max_vol) max_vol = sz;
+  vol_list += (vol_list.empty() ? "" : " ") + std::string("vol.7z") + suf + "(" + std::to_string(sz) + "B)";
+}
+const bool ok = (rc == 0) && volumes >= 2 && max_vol <= 10 * 1024;  // 两个要件都断言
+OHPT_CHECK(id, 0, ok, "生成多个分卷文件，各卷大小不超过指定分卷尺寸",
+           ok ? "生成 " + std::to_string(volumes) + " 个分卷，各卷 ≤10240B: " + vol_list : ...);
+```
+
+配套纪律：
+
+- **actual 必须带观测清单**（文件名/大小/行原文/数量），不是「在盘/成功/一致」这类无核对
+  价值的词——测试同学核对的是清单本身（同型正例：7zip F-01-01 从「列表含 a.txt」升级为
+  「名称+大小+日期三要素齐验 + actual 带列表行原文」）。
+- **数量类要件**（多个/全部/N 个）用计数断言（循环 exists、readdir 计数）；**上限类要件**
+  （不超过/至少）用 `min/max` 对边界值断言，不是 contains 一个值了事。
+- checkpoint 文本含「多个/每/各/全部/不超过/一致」这类量词时**逐个自问**：这个要件在断言
+  里对应哪一行？答不上来就是弱断言，补上再上真机。
+
+### 判定点粒度：一句一判（多对象合并判定=结论不可核对，拆到对象级）
+
+要件覆盖管「一条判定点的断言全不全」；这节管**一条判定点里装了几个结论**。expect 文本断言了
+**多个不同对象**各自的判定（「A 判为 X、B 判为 Y」「合并结果同时包含两个标志位」）时，接线必须拆成
+多条 `OHPT_CHECK`——每对象一条，actual 只给该对象自己的观测值；跨对象比较（「两者判定为不同」）
+单列一条放在各对象判定之后。理由：报告行是逐条核对的单位，一行两个结论时 actual 只能塞合并观测，
+哪个对象出错、错在哪个结论上，人工逐项核对无从下笔；合并行失败时排查还得先人工拆一遍。
+
+```cpp
+// ❌ 一句两判：expect 两个结论，actual 一坨合并观测
+r.check(0, hasPub && hasStat, "合并结果同时包含两个标志位",
+        std::string("public=") + (hasPub ? "T" : "F") + " static=" + (hasStat ? "T" : "F"));
+
+// ✅ 每个标志位一条自己的判定，actual 是该位的观测值
+r.check(0, hasPub,  "合并结果包含 public 标志位", std::string("public=") + (hasPub ? "T" : "F"));
+r.check(1, hasStat, "合并结果包含 static 标志位", std::string("static=") + (hasStat ? "T" : "F"));
+```
+
+- **expect 点名的每个对象都必须真测**，actual 不得含糊成单侧观测——只真测一半是「半测假绿」：
+  实证（rttr F-04-04，2026-09-17）：expect=「静态方法判为静态、非静态方法判为非静态」，实现只判了
+  非静态方法的 `is_static()`，静态半边是死代码（取了个属性又 `(void)` 丢掉），actual 永远只可能是
+  `non-static`，整轮 50/50 pass 无人察觉——直到按输出质量逐条看判定点才暴露。拆分逼着每个对象有
+  自己的 check 行，半测当场现形（缺静态方法 fixture 就补注册，让两侧都真测）。
+- **拆分是设计侧动作，不是接线侧私改**：判定点分母来自 05-testcases.json（scaffold 生成
+  `ohpt_cases.h` 的 OHPT_CHECKPOINTS 表；验收规则 checkpoint-verdict-complete 拿它逐条对账）。
+  设计里已合并的，走 05 修订（steps 拆分 + expected_result 同步）→ 重跑
+  `scaffold --test-cases` 增量同步 → 接线按新表实现 → 重建装机重跑取证；只在 napi_stub.cpp 里悄悄
+  拆、不改设计，分母就对不上账。
+- **单对象复合谓词不拆**（「判定为算术类型且不是类类型」= 同一对象的一个类别判定）；actual 里
+  顺带逐项展开（`key=int val=std::string`）也不等于合并判定——判的仍是一条谓词。
+
+> 实证（rttr 测试线，2026-09-17 两轮）：F-01-01（整数/浮点类型对象合一句「判定为不同」）与
+> F-01-03（五类类型合一句）、F-02-05（三个属性判定合一句）、F-04-04（静态/非静态合一句）、
+> F-12-03（两个标志位、存在/不存在位各合一句）按此拆分（判定点 149→158），真机全量重跑 50/50 pass。
+
+### 证据行与编译期探针（assert 会连作用一起被编译掉——assert 型证据的 NDEBUG 空洞）
+
+要件覆盖管「断言全不全」，本节管**证据活不活**：测试程序的正确性证据只写在 `assert()` 里时，
+构建带 `-DNDEBUG`（release 惯配，设备侧 hvigor CMake 默认就带）会把 assert **整体编译掉**——
+空实现照样 rc=0。接线体此时若只判 `rc == 0`、actual 写「退出码 0，语义生效」，整条判定链零证据
+（错误图谱 E173）。三段配方：
+
+1. **测试程序 stdout 证据行**：把每个关键推导结果按 `PROBE|对象|标签|实际值` 打一行
+   （如 `PROBE|x|deduced-type|int const&&`），**值写实际观测、不写死预期**——NDEBUG 下证据行照打，
+   同时供 runner 机器比对与测试同学人工核对；
+2. **编译期语义用 SFINAE + static_assert 探针**：「变量不可赋值/某重载不可达/类型推导形态」
+   没有运行时可观测值，用 trait 探针把事实写成可编译的判定（`std::declval<T&>() = …` 替换失败
+   即「不可赋值」），`static_assert` 执法——它编不掉，语义丢了 ELF 自己构建失败；探针结论照常
+   printf 成证据行。c++14 无 `std::void_t`，本地别名 `template <class...> using void_sink = void;` 代替；
+3. **接线体逐行锚定比对 + 分层判定点**：比对带上行尾 `\n`（`int const&` 是 `int const&&` 的前缀，
+   裸 contains 会把 const 右值引用形态误判成 const 左值引用形态）；一层证据一个 `OHPT_CHECK`
+   （产物行/探针行/类型名行各占一个 cp），actual 引用本层观测行原文；被测工具自身能在设备上
+   产出该产物时（转译/生成类），先真跑一步产出、再验性质——端到端证据优于纯预编二进制。
+
+### 判定确定性（接线代码自身的 UB——冷跑 pass、热跑翻车的整类根因）
+
+预演管「预期对不对」、要件覆盖管「断言全不全」；这节管**判定本身可不可复现**——接线代码
+自己就是 C/C++，它犯内存错误时的形态往往不是崩溃，而是**冷启动单次跑批 pass、同进程反复
+执行翻车**，且宿主预演抓不到（分配器行为不同，见节末指针）。两条红线：
+
+1. **库返回的内部缓冲指针，跨调用即失效**：`*_get_buffer` 类 API 返回的是库内部缓冲的
+   指针，随后的 clear/reset/writecopy/继续写入都可能 free 或 realloc 它。要跨调用使用
+   （比对/读回），**先快照拷进自己的内存**，且快照必须在任何可能失效的调用**之前**取。
+2. **断言「两种实现输出应不同」时，输入必须非退化**：全 1 位型/全对称输入会让两种实现的
+   有效数据位完全相同，唯一差异落在补位/填充位——而补位常是分配器残留（上游对半写字节
+   多为 `|=` 语义，写入前不清零）。选混合位型/非对称输入，让差异落在**确定写入的数据位**上。
+
+> 实证（libogg 阶段 6，2026-09，F-01-05/F-01-04 同类两例）：writecopy 触发内部扩容 realloc
+> 后用旧指针读悬垂内存，真机复跑轮暴露；writeclear 释放后拿旧指针与同尺寸新缓冲 memcmp、
+> 且输入恰为全 1 位型——两条红线同时违反，冷启动 run-all 判「不同」通过、人工同进程多轮
+> 点击翻成「相同」，宿主同代码连跑 4 轮全不翻转。单违反任一条即可让判定随堆状态漂移。
+
+平台根源（musl 对刚释放的同尺寸块在热进程内回收再利用、桌面分配器复现不可靠）见
+[[鸿蒙PC-musl与BSD-glibc语义分歧表]] 族 6。测试提单出现「跑批过、反复操作结果变」形态时，
+按堆状态依赖优先对照这两条排查。
+
+---
+
+## 6. 能力缺口怎么记
+
+适配产物确实没有该能力时：
+
+0. **先查降级路径可达性，再谈 blocked**：能力域 partial（编译通、运行时缺硬件/权限）时，库里往往存在不依赖该能力的构造/降级路径（如 `usbredirhost_open(NULL, NULL)` 不需要 `libusb_init` 成功，host 生命周期/读写/断开全由 parser 持有）。把整条用例挂在能力初始化调用上（libusb_init 成功才继续）是接线缺陷不是能力缺口——首轮 usbredir F-02 五条全 blocked 正属此类，改走降级构造后全 pass（SKILL.md §九「能力域 partial 的用例设计」红线）。确认降级路径也不可达，才走下面的 blocked 五件
+1. 用例 `result` 记 `blocked`（不是 `fail`，也不是 `pass`）
+2. **打 `result=blocked` 结果行**（native `ohpt_report_case_blocked()` / ArkTS `ohptReportCaseBlocked()`），
+   reason 写清缺哪块能力——机器判据认得它，和「没打结果行」是两码事
+3. 写进 `coverage.capability_gaps[]`：`{ prd_ref, reason }`
+4. 页面上做成「不支持 / 需宿主接入 / 需设备能力」的**可见状态**，不要静默失败
+5. **禁止**手写平替冒充支持（自己实现一个假的剪贴板、`Math.random()` 造传感器数据等）
+
+`uncovered[]` 与 `capability_gaps[]` 的分工：前者是「没测到」，后者是「测了但产物没这能力」。两者都要如实填——验收规则会拿 `cases[].prd_ref` 反算真实差集比对。
+
+---
+
+## 附：接线师开发过程纪律（防自我欺骗）
+
+**① 改 TS 源必重打包 bundle**：用 esbuild 临时 bundle 驱动生成器/验证脚本时，**改完 TS 源必须
+重新 esbuild 再跑**——旧 bundle 会用旧逻辑跑出假结果（codec2 2026-09-15 三次实证：栈守卫、
+单行式占位都曾因旧 bundle 假装生效，每次都被端到端验证当场戳穿）。规律：bundle 产物不含
+源码 mtime，不会有任何"过期"提示，唯一防线是纪律。
+
+**② PowerShell 管道截断会杀进程于写文件前**：诊断脚本输出接 `| Select-Object -First N`
+会在拿到 N 行后关闭管道 → node 的 stdout 写失败（EPIPE）→ **进程在写完目标文件之前就被
+终止**，表现为"脚本跑完了但文件没更新/更新了一半"（codec2 2026-09-15 实证：regen 输出
+正常但 Index.ets 未写入）。正确做法：输出重定向到文件（`> out.txt`）或 `Out-Null`，禁用
+`-First N` 截断。