@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/SKILL.md

@@ -0,0 +1,529 @@
+---
+name: pc-test-design
+description: 从 PRD 功能点清单设计用例、再由用例清单落地「功能验证 demo」的方法论（涵盖功能点模型与一个用户可感知能力=一个功能点=一条用例、多 API 协同合并不硬拆，IBO 分析，L0/L1/L2 分级与数量上限，功能点→用例逐字段转化规则，步骤 input 字段作为阶段 6 生成输入框的合同源，自评审四维检查单，黑盒表述规范，渲染验证 vs 数据验证二分法，按交付形态选验证载体与达标证据，入口模式与载体分档，反造假接线清单，错误契约断言的上游出处红线，量化断言的出处与等价条件红线，UB 类操作的平台确定性处置红线），可供 pc-01-scan / pc-01-analyze 写 01-scan.json 的 prd 字段（职责可由 scan 前移至 analyze，二者兼容），以及测试线阶段 5 设计用例、阶段 6 生成 test-demo/ 工程并真机验证时使用，触发词包括 PRD、功能点、测试设计、用例设计、用例清单、测试 demo、覆盖度、验证点、checkpoint、IBO、等价类、边界值、状态迁移、L0 L1 L2、黑盒用例、渲染验证、渲染预览页、PreviewPage、按用例出图、功能覆盖、漏识别、空 stub、假绿、smoke 假通过、prd_ref、case_ref、coverage、capability_gaps、自评审、cases.json、caseId、一把执行、run_all、错误契约、退出码、错误码、exit code、errno、断言出处、量化断言、阈值、等价条件、宿主预演、预期写错、input 字段、输入框、double-free、二次释放、SIGTRAP、UB 预期、未定义行为、不崩溃断言、NDEBUG、assert 假绿、static_assert、SFINAE、编译期探针、证据行、类型推导、不可变、行锚定、子串误配、输入源模式选错、feed 模式假绿、可寻址 API、明确失败冒充通过。
+---
+
+
+# pc-test-design：功能点驱动的适配验证设计
+
+**要解决的问题**：编得出、跑得起来，不等于原库的功能还在。
+
+实证（GLFW 3.5.0 案例）：`01-scan` 用 4 个粗能力域概括了整个库，剪贴板、光标形状、拖放、窗口标题、真实监视器枚举全被吞掉；适配阶段把它们静默 stub 掉，零预警；而冒烟用例连空 stub 都能 PASS。**没有一份机器可追溯的功能点清单，就没有任何一环能判「覆盖够不够」。**
+
+本 skill 就是那份清单的写法与消费法。
+
+## 谁在用我
+
+| 用法 | 阶段 | 产出 |
+|---|---|---|
+| 写 PRD 功能点清单 | `pc-01-analyze`（主线） | `01-scan.json` 的 `prd`（schema 见 `pc-schemas`） |
+| 构建**必跑名册**（原库用例 − 平台独有 + 覆盖缺口补齐） | `pc-02-dev-test-cases`（主线） | `02-baseline.json` |
+| 功能点 → 1:1 黑盒用例 + 自评审 | 阶段 5 测试设计（测试线） | `05-testcases.json` |
+| 用例 → demo 工程 → 逐条真机跑 | 阶段 6 Demo 生成与真机验证（测试线出口） | `06-testdemo.json` + `test-demo/` 工程 |
+
+> **两套用例，两个问题，别混**：阶段 2 的名册是**接口级**、来自原库源码与上游套件，验的是
+> 「**接口没丢**」（分母＝公共导出面）；测试线的用例是**功能点级**、来自 PRD、黑盒表述，验的是
+> 「**功能没丢**」（分母＝`prd.features[]` 减去有证据且已接受的上游限制 `exclusions[]`）。两者会各自漏：libbsd 的 `sl_delete`「声明了没人测」
+> 是前者的洞，GLFW 的剪贴板/光标形状/拖放被 4 个粗能力域吞掉是后者的洞。
+
+> **设计与生成分成两个阶段**：用例对不对必须在编译、跑机**之前**就能判定。合成一步时用例只是
+> 执行结果的附属字段，错了要等跑完才发现，返工代价是整个 demo。
+>
+> **测试线与适配主线平级**：它读主线的 PRD 与适配产物，但测试结论**不改变适配终态**，
+> 主线的沉淀总结也不读测试产物。
+>
+> **阶段 5 不以适配验收为前置**：以 PRD 定验证目标，以当前版本源码及既有证据核实预期；
+> 不按适配失败缩减需求。设计可与适配并行，不需要设备——这是 gate 把两阶段前置分开判的原因。
+
+---
+
+## 〇、必跑名册的构建（阶段 2）
+
+名册是「阶段 3 必须在鸿蒙上跑通哪些用例」的**分母**。判定的分母不能由被判定者提供——
+没有它，适配阶段就会自己挑几条冒烟用例当全部（实证：手挑 25 个 API 冒烟全绿，
+同一个库换成上游 25 个官方用例完整移植，抓出 72 个 FAIL/CRASH）。
+
+### 三步
+
+1. **发现上游套件**：先读 CI 配置（`.github/workflows/*.yml`、`tox.ini`、`noxfile.py`、`Makefile`）
+   拿官方测试命令、markers 与排除集，再逐目录扫。**`run_command` 必须带上游的用例选集与防挂参数**——
+   适配阶段只做设备路径改写、一字不改地复跑。上游有测试却不收进名册，就是自选分母。
+2. **枚举公共导出面**（覆盖度锚一）：C/C++ 取 `source/include/**` 的头文件函数声明
+   （`provenance: machine-symbol`，验收会用同一份重算）；其他生态取各自的导出清单
+   （Python `__all__`、Java public 类、Rust `pub`、Node `exports`），填 `declared` + `source_refs` 供抽查。
+   **下界恒为** `01-scan.json` 里 `prd.features[].covered_apis.source[]` 的并集——阶段 1 已逐功能点
+   列过的原库符号，语言无关，少于它即为漏枚举。
+3. **判平台独有**：命中下面任一条且能给出证据，才标 `platform_exclusive: true`（**不进名册**）。
+
+| 信号 | 证据写什么 |
+|---|---|
+| 用例被 `#ifdef _WIN32` / `#ifndef __linux__` 之类包住 | `tests/win32.c:88 #ifdef _WIN32` |
+| 依赖原平台专有夹具/设备（注册表、systemd、/proc 特有项、平台专属 API） | 依赖点的 file:line |
+| 上游 CI 的平台矩阵里本就排除了该用例 | CI 配置的排除项位置 |
+
+**判不出就不标。** 宁可让适配阶段去碰一碰，也不要凭猜把用例移出分母——豁免不带证据就是放水通道。
+
+### 覆盖缺口怎么补
+
+符号面或 PRD 功能点没有任何用例覆盖到的，在 `tests-generated/` 补写（用与仓库一致的测试框架），
+填 `source: generated`。补到 `api_surface.uncovered` 与 `feature_coverage.uncovered` 都为空——
+这就是「功能（接口）100% 覆盖」的可判定形式，两者都空才写得出 `baseline_status: planned`。
+
+**每条补写用例必须有可判定的断言**（返回值/状态/错误码）。只调用不断言的用例，空实现也能让它「通过」——
+过了也证明不了任何事。验收规则会扫 `tests-generated/` 下的文件，找不到断言语句就点名。
+
+### 补写用例要自证（这决定下游能不能「修到过为止」）
+
+名册是适配阶段的**评判标准**。原库用例有上游 CI 背书，**补写用例没有任何背书**——它的断言可能就是
+补写时的臆断。带着错的断言进名册，适配阶段会为了让它过而去改本来正确的产物。
+
+所以补写用例要先在一个已知正确的环境里证明自己：
+
+| `host_run.status` | 做什么 | 结果 |
+|---|---|---|
+| `ran`（宿主能跑该库） | **只跑补写的那批**，不必跑全量上游套件 | 通过 → `validation: self-validated`；**没通过就在这里修到通过**，修不好就别入册（缺口如实留 `uncovered[]`、名册记 `partial`） |
+| `unavailable`（交叉编译目标、宿主编不出） | 如实写 `reason` | 全部 `validation: unvalidated`——这批**允许**适配阶段判「用例本身写错」并修正，另两档不允许 |
+
+三档都要求最终在鸿蒙上通过。**分档决定的是「失败时允许改什么」，不是放松要求**：
+`upstream-backed` 与 `self-validated` 的断言都有背书，判它们写错要指向上游 issue 或 musl 事实差异。
+
+> 原库用例宿主跑不过很正常（平台独有、上游自身损坏），**不因此降级 `baseline_status`**。
+> 这里要求自证的只有补写的那批。
+
+---
+
+## 一、功能点模型（最重要的一条）
+
+**一个有效功能点 = 一个用户可感知的单一能力 = 一个验证目标 = 一条用例。** 已接受的上游缺陷独立进入 exclusions，不生成执行用例。
+
+API 不是划分单位，只是功能点的实现线索（记进 `covered_apis.source` / `covered_apis.harmony`，数组）。
+
+> 为什么锚定功能点而非 API：同一能力在原平台与鸿蒙上往往由**不同的 API 集合**实现，无法一一映射。锚 API 会让用例在适配后失去对应物。
+
+### ❌ 反模式：按 API 个数硬拆
+
+| 错（按 API 拆） | 对（按能力合并） |
+|---|---|
+| `F-01-01 设置进度最大值`<br>`F-01-02 设置当前进度` | `F-01-01 显示指定进度`<br>`covered_apis.source: [setMax, setProgress]` |
+
+### ✅ 该拆的要拆：独立验证目标各算一条
+
+| 错（塞成一条） | 对（分开） |
+|---|---|
+| `F-02-01 查询总空间、已用、可用` | `F-02-01 查询总空间`<br>`F-02-02 查询已用空间`<br>`F-02-03 查询可用空间` |
+
+判据只有一句：**它们会不会各自独立地坏掉？** 会 → 拆。
+
+### 枚举值全覆盖
+
+参数是枚举/有限取值集且不同取值产生**不同可观测行为**时，每个取值一个功能点。≤5 个逐个覆盖；>10 个取代表性值（首、末、缺省、特殊）。
+
+---
+
+## 二、可观测路径枚举（决定覆盖完备性）
+
+功能模块不能停在「列出 API 签名」。对每个公开符号，回到定义处**读方法体、识别分支**，把每条会产生**不同可观测结果**的路径记进 `observable_paths[]`：
+
+| 路径类别 | 说明 |
+|---|---|
+| 正常路径 | 典型合法输入下的成功返回 / 状态变化 / 回调 / 上屏效果 |
+| 分支路径 | `if/else`、`switch`、三元、提前 `return`、循环空/非空——各自产生不同可观测结果的算一条 |
+| 异常/错误路径 | `throw`、错误码、参数非法（空/null/负数/越界/类型不符）、前置不满足（未初始化、权限缺失、资源不可用） |
+| 取值路径 | 枚举/有限取值集里各产生不同行为的取值 |
+| 异步双路径 | 回调/Future/线程至少「成功 + 失败」两条 |
+| 可见状态路径 | 视觉组件：不同属性取值 → 不同渲染（显隐/颜色/尺寸/动画目标/边界反馈） |
+
+**白盒读、黑盒写**：你能读到源码分支，但路径必须表达为**黑盒可观测的结果**（返回值/状态/回调/上屏/错误），下游才生成得出可执行用例。
+
+稳定 id 格式：`<符号>::<结果标签>`，如 `glfwCreateWindow::ok`、`glfwCreateWindow::nullMonitor`、`parseConfig::malformed`。
+
+---
+
+## 三、IBO 分析（怎么把模块拆成功能点）
+
+对每个功能模块走一遍 Input / Behavior / Output 三维：
+
+| 维度 | 识别什么 | 选什么方法 |
+|---|---|---|
+| **I**nput | 参数类型、取值域、必选/可选、来源（用户/文件/设备/网络） | 等价类划分、边界值、空值/异常值 |
+| **B**ehavior | 有无状态机、有无判定条件组合、有无并发/时序 | 状态迁移覆盖、判定表、并发场景 |
+| **O**utput | 返回值、状态变化、回调、上屏、落盘、错误 | 空集合、边界值、格式验证 |
+
+### 状态迁移覆盖深度
+
+| 模块优先级 | 覆盖等级 | 退化条件 | 路径上限 |
+|---|---|---|---|
+| P0 | 2-switch | 状态数 ≤3 降 1-switch | ≤12 |
+| P1 | 1-switch | 状态数 ≤3 降 0-switch | ≤8 |
+| P2 | 1-switch | 状态数 ≤3 降 0-switch | ≤5 |
+
+路径生成：对状态迁移表的每条边 `A --e1--> B`，再取 B 的每条出边 `B --e2--> C`，得 1-switch 路径 `[A,e1,B,e2,C]`；再嵌一层得 2-switch。
+
+**无状态模块跳过本节**，写明「本模块无状态机，不适用状态迁移覆盖」。
+
+---
+
+## 四、优先级与级别
+
+### 模块优先级（PRD 不给时按能力特征判）
+
+| 能力特征 | 优先级 | 依据 |
+|---|---|---|
+| 核心能力闭环（主功能、上屏渲染、状态转换、平台能力映射） | P0 | 缺失则本库不可用 |
+| 辅助能力（配置、查询、构建契约、可选扩展） | P1 | 影响主要场景，不阻断核心 |
+| 示例/工具/演示代码 | P2 | 可降级或延后 |
+
+判不出时默认 P1（避免过度生成 P0 异常用例）。
+
+### 用例级别（由优先级 × 场景推出，**不做二次调整**）
+
+| | normal | exception | boundary |
+|---|---|---|---|
+| **P0** | L0 | L1 | L1 |
+| **P1** | L0（核心）/ L1（其他） | L2 | L1 |
+| **P2** | L1（核心）/ L2（其他） | 不生成 | 不生成 |
+
+### 数量上限（按功能点统计，防用例爆炸）
+
+| 优先级 | 异常场景上限 | 边界场景上限 |
+|---|---|---|
+| P0 | 2 | 2 |
+| P1 | 1 | 1 |
+| P2 | 0 | 0 |
+
+健康分布参考：L0 占 25%~50%，L1 占 30%~50%，L2 ≤15%。
+
+---
+
+## 五、黑盒表述规范
+
+**功能点名 / checkpoint / 用例步骤一律用户视角、平台无关。**
+
+- 禁用 API 词汇：调用、访问、返回、注册、创建、设置、传入、执行、加载、订阅。
+- 禁止在步骤文本里点名 API 或写 `(API: xxx)`——API 一律进 `covered_apis` 字段。
+- 禁止出现原平台特定词汇（Windows/Linux/X11/Win32/Android…）。
+- `checkpoint` 必须**具体、可判定**。
+
+| ❌ 模糊 | ✅ 具体 |
+|---|---|
+| 功能正常 | 设备上出现非全黑的 640×480 窗口内容 |
+| 正确返回 | 写入 "hello" 后读回的字符串等于 "hello" |
+| 无异常 | 传入负数尺寸时返回空句柄且不崩溃 |
+
+> 「功能正常/正确/无异常/符合预期」这几个词会被验收规则 `prd-shape-sane` 直接告警——它们等于没写。
+
+**一条 checkpoint 只下一个对象的判定结论（禁一句多判）**：判定句断言了**多个不同对象**各自的判定
+（「A 判为 X、B 判为 Y」）时，拆成多条 checkpoint——每对象一条自己的结论，跨对象的比较（「两者判定为
+不同」）再单列一条。合并成一句，demo 报告行就只能塞一坨合并观测（`A=T B=F`），哪个对象出错、错在哪个
+结论上，人工逐项核对对不上号；且接线侧无法在不改设计的前提下补拆——分母来自本文件的 steps[].checkpoint
+（rttr F-01-01 实证：整数/浮点类型对象合并成一句「判定为不同」，测试同学要求分别输出两类对象各自的判定
+结果再给比较结论；F-01-03 五类类型合一句、F-04-04 静态/非静态合一句，同批拆分时还暴露了静态半边从未
+真测的接线缺陷）。拆分细则见 `demo-wiring-pc` §「判定点粒度」。
+
+| ❌ 一句多判 | ✅ 一句一判 |
+|---|---|
+| 整数类型对象与浮点类型对象判定为不同 | 整数类型对象判定为有效且名称为 int；浮点类型对象判定为有效且名称为 double；整数类型对象与浮点类型对象判定为不同（三条） |
+| 枚举类型判为枚举、指针类型判为指针、包装类型判为包装、…（五类合一句） | 每类一条：枚举类型判为枚举／指针类型判为指针／… |
+| 静态方法判为静态、非静态方法判为非静态 | 静态方法判为静态；非静态方法判为非静态（两条） |
+
+单对象的复合谓词不算合并、不必拆（「判定为算术类型且不是类类型」= 同一对象的一个类别判定）。
+
+异常场景的预期结果写**行为级描述**，不绑定具体错误文案（如「返回失败且不崩溃，以实际错误返回为准」）。
+
+**平台特定字面量先查分歧表**：expected_result 含**边界值**（LLONG/INT 邻域、溢出）、**字节序列**（编码/转义输出）、**长度语义**（返回长度含不含结尾符/换行）三类断言时——预期值来自 BSD/glibc 世界（man 手册、上游测试）≠ musl 的事实行为，**先查 `pc-knowledge-base` 的「musl与BSD-glibc语义分歧表」族 2-4 按实测事实写**，否则档位写错要等真机轮才暴露（libbsd 实证：strtonum ERANGE 预期、fgetln 长度含 `\n`、vis 响铃符输出三条全在真机 FAIL 后才回头改——各烧一轮）；**UB 类操作（double-free 等）的处置预期同表族 6，另有红线（见 §九）**。错误契约类（非零退出码/errno 精确值）另有红线要求出处，见验收规则 `testcases-error-contract-provenance`。
+
+**边界类用例的预期字面量必须引上游源码依据**：checkpoint 里的边界预期值（"超范围→饱和/截断/回绕"这类）须指明依据（上游源码行/文档）；**含平台条件的预期（32 位 time_t/字长/endian 假设）必须标注适用条件**，并给当前平台（aarch64 64 位）的对照写法——平台条件不同时上游实现常是两套分支（libbsd F-14-01 反例：checkpoint 照抄"饱和到 0x7FFFFFFF"的 32 位假设，64 位 time_t 上游实现是 `return((int32_t)t)` 直接截断——预期写错，测试程序又照错误预期跳过了真测，双重错误直到测试同学人肉发现，2026-09）。
+
+---
+
+## 六、渲染验证 vs 数据验证（防「dump 数据冒充上屏」）
+
+对每条用例扫 `checkpoint` / `expected_result`，含以下**视觉展示语义词**即为**渲染验证类**：
+
+> 显示、渲染、绘制、展示、出现、消失、刷新、布局、滚动、高亮、颜色、动画、样式、可见、隐藏、展开、收起、上屏
+
+判定：
+
+- 被测能力本身就有可渲染产物（窗口、画面、图元、图标、PixelMap）→ **必须在页面挂真视觉组件、走真上屏路径**；机器判据为结果行日志（`OHPTCASE result=…`），上屏效果由人工在 demo 页面上验收。
+- 被测能力是逻辑/数据类（解析、计算、查询、管理器）但 checkpoint 讲的是展示 → 用逻辑 API 产出数据后，**用可用的视觉组件把它渲染出来**再取证。
+- **禁止**仅把数据拼成文本 dump 到 result 区冒充渲染验证——上屏路径必须真，只是机器不判图。
+
+无视觉语义的用例（纯数据正确性：数量一致/值正确/返回匹配）→ **数据验证类**，result 展示真实返回值即可。
+
+### 产物是图像的用例：声明它，执行器负责上屏（机制，不是纪律）
+
+被测能力是**数据类**（生成/处理/编解码/栅格化）但**产物是一张图**的用例，在 `steps[].output` 声明
+`{kind: image, label}`（与 `steps[].input` 对称，schema 见 `pc-schemas`）。之后没有任何手写步骤：
+执行器在每条用例前后**对比用例沙箱**，用例写下的文件即其产物（bytes/FNV-1a64 由执行器算并打
+`OHPTCASE artifact` 行——证据不由被测程序自报），生成的结果区按登记行 `Image('file://'+path)` 上屏、
+「全部执行」页给缩略图，验收规则 `testdemo-artifact-evidenced`（声明 ⊆ 登记）与
+`testdemo-artifact-distinct`（各用例的图字节级互异）执法。接线方唯一要做的：**把结果图写进用例沙箱**。
+libaribcaption 三条手写红线（参数端到端 / 字节可区分 / 文件名互撞）由此按构造关闭；
+渲染走 exec 子进程还是主进程的取舍见 `references/render-preview-page.md`。
+
+---
+
+## 七、验证载体与达标证据（按交付形态路由）
+
+载体模板一律走 `ohpt-agent scaffold --kind <k> -w <ws> --out test-demo`（`--list` 看全表）。
+**证据落 `test-demo/verify/`，不要落 `build/`**——那会让阶段 3 的验收裁决被判过期、白跑一轮。
+
+| 交付形态 / 命中能力域 | scaffold kind | 载体形态 | 达标证据 |
+|---|---|---|---|
+| `app`、`graphical-window`、`gl-context`、`ui` | `cpp-gui-owb-demo` / `python-gui-owb` | HAP + OWB + 满屏 XComponent，浮层浏览用例 | `demo-verify.json` + 用例结果行日志 + 载体自证的 surface/GL 身份行（画面由人工验收） |
+| `audio` | 见 `pc-capability-domains` 的 `solutions/ohaudio-backend` | OHAudio 后端接入 | `audio-verify.json`（renderer 真拿到 + 真写出帧） |
+| `cli` | `cli-hnp-runner` | 私有 HNP + fork/execv + TAP/hilog 回传 | 设备端原始输出日志 |
+| `cpp-lib` / `native-extension` / `pure-runtime`（非上屏） | `cpp-lib-demo` / `python-app-*` | NAPI 壳按功能点逐个调符号 | 设备端原始输出日志 |
+
+证据档由命中的能力域算出（`DOMAIN_EVIDENCE` 归属表），**不由你自选**——gate 与验收规则用同一张表核对。
+设备侧验证载体（该造什么工程）照 `ohpt-agent state -w <ws> --json` 的 `workspaces[].verify_carriers` 走（只读；gate env 块同源），不现场试探；具体操作见 `pc-device-verify`。
+
+---
+
+## 八、真实接入闭环（反造假十条）
+
+见 `references/anti-fake-checklist.md`。核心一句：**demo 存在的意义是证明适配产物真的能用，不是演一遍给人看。**
+
+每条 `result=pass` 的用例都必须记下它实际调用的鸿蒙侧符号（`06-testdemo.json` 的 `case_results[].covered_apis_harmony`）——验收规则 `testdemo-wiring-real` 会核对，空的直接告警。
+
+---
+
+## 九、功能点 → 用例的转化规则（阶段 5）
+
+**1 个有效功能点 = 1 条用例**（已接受的限制单列 exclusions），编号沿用、级别继承，不另立体系。逐字段的转化关系：
+
+| 功能点字段（`01-scan.json` 的 `prd.features[]`） | 转化规则 | 用例字段（`05-testcases.json` 的 `cases[]`） |
+|---|---|---|
+| `id` | 直接继承 | `id` **和** `prd_ref`（两者必须相等） |
+| `module` | 直接继承 | `module`（`modules[]` 照抄 `prd.modules`） |
+| `name` | 直接继承 | `title` |
+| `level` / `scenario` | **原样继承，不做二次划分** | `level` / `scenario` |
+| `checkpoint` | 核实源码契约后落到触发步骤；错误字面量须有据修正 | `steps[].checkpoint` |
+| `description` + `observable_paths` | 转成操作序列 | `steps[].action` |
+| `checkpoint`（可判定化） | 写成能直接判 pass/fail 的结果 | `expected_result` |
+| `covered_apis.source` | 直接继承 | `covered_apis_source`（阶段 6 找鸿蒙侧符号的线索） |
+| — | 载体就绪状态，如「应用已启动」 | `preconditions` |
+
+### 契约审查与有效范围
+
+阶段 5 读取 [通用契约审查清单](references/test-contract-regressions.md)，只读当前版本源码、上游测试与既有证据，
+核实每个有效用例的最终输出分支，填写 `oracle.basis` / `oracle.conditions`；并发计数补 `oracle.state_control`。
+不以 PRD 原文代替接口契约，不要求设备、不创建 demo。当前规则审查完成后记录 `meta.test_policy_version=3`。
+
+只有已证实来自原始上游版本、且当前任务或既有明确决定接受暂不修复的缺陷，才记录为 `exclusions[]`。
+原因、源码依据与实际证据留在当前库产物中；排除按 feature/case 为单位，复合用例说明受影响子路径及其余路径的验证情况，
+不宣称整个模块全覆盖。测试载体问题、预期错误、未知失败及鸿蒙新增缺陷不能作为上游缺陷排除。
+
+排除项不进入 `cases[]` 或 `uncovered[]`；保留 `coverage.prd_features_original`，有效分母
+`prd_features_total=原始功能点数−排除数`，`coverage.excluded` 单列。阶段 6 原样继承排除清单，不为其生成执行结果。
+字段结构以 `pc-schemas` 为准，排除不等于通过。
+
+**这四条由验收规则机器执法**（`testcases-traceable`），不是提醒：`prd_ref` 悬空、`id ≠ prd_ref`、
+`level`/`scenario` 与功能点不符、`coverage` 与现算不符——任一不成立即告警。所以别手写覆盖度数字。
+
+### 步骤按载体形态写
+
+操作路径要跟目标载体对得上（路由表见 `references/demo-wiring-pc.md`）：
+
+| 载体 | 步骤形态 |
+|---|---|
+| GUI（`cpp-gui-owb-demo` / `python-gui-owb`） | 进入用例场景 → 配置参数 → 触发 → 观察上屏 |
+| CLI / 库（`cli-hnp-runner` / `cpp-lib-demo`） | 以某参数执行 → 观察 stdout / 退出码 / 产物文件 |
+
+两种都**只写功能语义**：不点名 API、不写代码级描述（「调用 xxx()」「传入 NULL」一律不行）。
+API 信息一律只出现在 `covered_apis_source`。
+
+**步骤含用户输入语义时必须填 `steps[].input` 字段**（kind: text/codes/pair + label + default）：
+「输入某域名/某参数/某码点序列进行转换」类步骤不填 input，阶段 6 生成的 demo 页面就只有执行按钮、
+没有输入框（测试同学无从按步骤操作）。input 是 schema 可选字段，但**步骤语义是输入的就是必填**——
+kind 三选一：text=普通字符串（域名/文件名/命令行参数）、codes=码点/数值序列（`U+00D6,U+00FC` 形态）、
+pair=双值对（`U标签|A标签` 形态）；default 是页面预填及 ArkTS 自判跑批共同使用的向量。
+往返验证先确定原始数据，再由前一步实际编码结果计算后一步 default；原始数据与
+生成规则记录在 oracle.conditions，阶段 6 必须按同一规则接线并核对实际输出。
+文件路径输入的 `input.file`、默认值边界的 `input.constraints` 及阶段 6 资源准备、入口验证细则，
+见 [默认输入与资源契约](references/input-resources.md)。
+
+### 异常/边界场景的预期结果
+
+正常场景写预期输出；异常场景写**行为级结果**，不绑定具体错误文案
+（「返回失败且不崩溃，错误信息以实际返回为准」优于「弹出『参数错误』提示」）。
+
+### 错误契约类断言必须有上游出处（红线）
+
+**非零退出码 / 错误码 / errno / 异常分类的精确值断言**（如「退出码为 2」「errno 为 ENOENT」）是
+**错误契约断言**——它钉死了上游契约的档位，预期写错一个档位整条用例必 fail，且要到真机轮才
+暴露。写这类断言**必须先核对上游权威出处**，三选一：
+
+| 出处 | 例子 | 记法（写进该用例的 `notes`） |
+|---|---|---|
+| 官方文档的错误码/退出码表 | 7-Zip 手册的 Exit Codes 表 | `出处: docs/exit-codes 表` |
+| 源码枚举/常量定义 | `NExitCode::kFatalError = 2` | `出处: CPP/7zip/ExitCode.h NExitCode` |
+| 宿主实测（原平台跑一次） | `7zz a bad.7z no-such-input.txt; echo $?` → 1 | `出处: 宿主实测 rc=1（warning 档）` |
+
+> 豁免两类：钉 **0**（成功档，普适约定，无档位错分风险）；**行为级**断言（「非零」「失败且不
+> 崩溃」——不钉档位值就没有风险面）。
+>
+> 反例（7zip F-09-02，2026-09-04）：设计时把「压缩输入文件缺失」预期为致命错误（退出码 2），
+> 上游契约实为 **warning → 退出码 1**（退出码 2 是「归档不可打开」档）。真机一轮才发现，
+> 代价 = 一轮设备验证 + 用户裁决 + 阶段 5/6 双返工。宿主侧 1 秒就能实测出来的事实，
+> 不该花一轮真机去发现。
+>
+> 「同一症状在不同档位」是高频错区：**输入缺失 ≠ 致命**、**打开失败 ≠ 用户错误**——
+> 恰恰这些"看起来显然"的映射最依赖出处核对。
+
+钩子（acceptance 规则 `testcases-error-contract-provenance`）会扫：钉了非零值的错误契约断言
+若在该用例 `notes` 里找不到出处标记（`出处:` / `provenance` / `上游` / 实测记录），点名告警。
+
+### 量化断言必须有出处 + 等价条件（红线）
+
+**数字界线断言**——「次数不少于 N」「帧数 ≥ N」「BER ≤ x」「命中率 ≥ N%」——是错误契约红线在
+同一病灶上的第二张脸：数字钉死了上游实测结果，**而实测结果只在特定条件下成立**。写这类断言
+必须同时核对两样东西，记进 `notes`：
+
+| 要核什么 | 例子 | 记法（写进 `notes`） |
+|---|---|---|
+| **出处**：数字从哪来 | 上游 `reliable_text_fade.sh` 用完整语料实测命中 20 次 | `出处: unittest/reliable_text_fade.sh 1600 -28 3 0` |
+| **等价条件**：在什么条件下测得 | 112 秒完整语料（899584 样本）、1600 模式 | `条件: 112 秒语料 ve9qrp.raw、模式 1600` |
+
+> 豁免：行为级断言（「非零」「不崩溃」）；钉 0 的成功档。
+>
+> 反例（codec2，2026-09-05，两条同场）：F-06-01 把 112 秒语料实测的「≥20 次」绑到 **10 秒**
+> 样例——250 帧连 2 个 128 帧消息包周期都不够，物理不可达；F-05-06 把仅 VHF 模式（2400A/B/800XA）
+> 生效的回调断言钉在 **DATAC0** 模式上——上游该模式下是空操作。两条都拖到真机轮才暴露，
+> 修复要动用编排方授权的**设计修正轮**（换模式/换时长/对齐上游真基线数字）。
+>
+> 数字有出处 ≠ 安全——**出处里的条件没跟着数字走**，正是错配的形态。模式/参数组合同理：
+> 断言钉死某个模式/变体时，先确认预期行为在该模式下真的生效（查上游的模式守卫代码）。
+
+钩子（acceptance 规则 `testcases-numeric-expectation-anchored`）会扫：钉了数字界线的断言若
+`notes` 凑不齐「出处 + 等价条件」两个标记，点名告警。
+
+### 请求-响应与观察-事件型 API 不得混接（红线）
+
+为交互模型不同的两类 API 设计用例时，**步骤与接线必须遵循 API 自己的模型**——先到上游源码的
+注册表核对交互形态，`file:line` 记进该用例 `notes`：
+
+| 交互模型 | 判据（上游源码/文档） | 用例步骤的正确形态 |
+|---|---|---|
+| 请求-响应（命令 / 带返回值的函数） | 上游**命令注册表**或函数声明；结果经调用的返回节点/返回值**同步**带回 | 调用后立即读返回结果并断言（宽度/长度/数据量） |
+| 观察-事件（可订阅属性 / 回调） | 上游**属性表**或回调注册；变更经事件循环**异步**送达 | 先订阅 → 触发变更 → 在事件循环里等事件送达 |
+
+**把命令名当可观察属性**（「注册 X 属性观察 → 触发 X 命令 → 等属性事件携带数据」）是结构性死局：
+命令不产生属性事件，事件永远不来——而失败形态又恰好像「平台能力缺失」，至少烧一轮真机 +
+一轮 amendment。无返回值的命令调用即使 rc=0 也只说明「已执行」，结果已被丢弃。
+
+> 反例（某播放器库截图到内存用例，2026-09）：设计写「注册截图属性观察，触发截图命令后读取像素
+> 数据」——截图实为**命令**（像素数据经命令的结果节点同步返回），上游属性表中不存在该名字；
+> 接线照设计用「无返回节点 command 形式 + 等待属性事件」，命令返回 0 但事件永不送达，还被误归因
+> 「平台无帧缓冲能力」。修正只动接线：改用**带结果节点的命令调用**同步读像素（数据量/宽高/步长
+> 校验原样保留），checkpoint 一字未动；烧掉一轮真机 + 一轮 amendment。
+
+设计侧自查：`covered_apis_source` 里**同时**出现「带结果的命令/函数」与「属性观察/订阅」时，
+逐个核对每个 API 在步骤里扮演的角色——**结果从哪条通道回来、事件在等谁**；核对不到注册表出处
+的交互假设不要落笔。
+
+### UB 类操作的预期只能写平台确定性处置（红线）
+
+double-free、野指针/use-after-free 这类 **C 标准未定义行为（UB）** 的操作，**「不崩溃」「不输出
+段错误」「程序存活」不是合法预期**——UB 无契约保证，且 glibc 与 musl 的处置都是终止进程、分歧仅
+在信号形态（glibc `abort()` SIGABRT；OHOS musl **SIGTRAP/TRAP_BRKPT**）。区别于上节：非法输入的
+「失败且不崩溃」是合法行为级断言（错误处理路径是契约内行为）；UB 操作没有「不崩溃」这个档位可选。
+
+预期写法：**只锚「确定性处置被触发」**——执行释放的进程被信号终止（不钉具体信号值）；执行形态必须
+**子进程隔离**（UB 会终止执行进程），父进程按子进程退出信号判定。库若是 free 透传封装（如 libidn2
+的 `idn2_free`），行为 100% 委托平台 libc，上游测试套件对此零断言。
+
+> 子进程隔离的判读陷阱（2026-09 实证，图谱 E167）：HAP 多线程进程里 **fork 无 exec** 的子进程继承
+> 整张进程状态，可恢复错误会被放大成「信号终止」——隔离子进程崩溃**不能**直接归因产物/平台缺陷，
+> 须先以「进程内直跑对照」复核（直跑不崩 = 隔离机制或用例自身的问题）。非 UB 的普通崩溃风险用例
+> （异常传播、反射查询等）优先依赖 per-case 拉起做隔离，不叠 fork。
+
+> 反例（libidn2 F-01-03，2026-09）：round-1 用 glibc 容忍前提写「二次释放不触发 double-free 崩溃、
+> 不输出段错误」，真机实测二次释放触发 musl SIGTRAP——判**用例设计缺陷**（非产物缺陷），多烧一整轮
+> amendment 才修正。同一直觉缺失若发生在移植期（构建检查/上游测试假设 glibc 行为），就会变成真适配
+> 缺陷——同一张分歧表两条线共用。
+
+> 反例（libaribcaption 补写用例，2026-09）：生成器补写的 C API 用例加 `aribcc_image_cleanup(NULL);
+> /* should not crash */`——头文件契约明文仅接受从 API 获得的 image（"Otherwise it may cause a
+> crash"），NULL 清理是**契约外 UB**，真机 SIGSEGV（fault_addr=0x18，反汇编 `ldr x0,[x0,#24]` 无
+> NULL 保护），一度被误判为库缺陷。**注释不构成契约**：`/* should not crash */` 不是 API 规范，
+> validation=unvalidated 的补写用例必须逐条核对断言出处；处置是删断言，不是改库加 NULL 保护。
+> （E160 / E159 同一实证：前者契约外断言崩、后者纯 C TU init 期崩，两条根因独立，三段定位法拆解。）
+
+权威归属：`pc-knowledge-base/platform/鸿蒙PC-musl与BSD-glibc语义分歧表.md` **族 6（堆处置）**；
+契约外断言归属 `pc-error-atlas` **E160**；纯 C TU 调 C++ .so 的 init 期崩归属 **E159**。
+
+### 能力域 partial 的功能点：默认对降级路径设计（红线）
+
+scan 把某能力域判 `harmony_status: partial`（编译链路通、运行时在 app 域受限，如 usb-host）时，
+受影响功能点的用例**默认对降级/无硬件路径设计**——预期写「降级行为被正确触发」
+（初始化失败后功能安全跳过、空句柄路径正常返回、无设备时网络/参数功能完整可用），
+而不是「硬件交互成功」。四条子规则：
+
+0. **先找不依赖该能力的构造路径**：库里常有绕过能力初始化的降级入口（如
+   `usbredirhost_open(NULL, NULL)` 不需要 `libusb_init` 成功——host 生命周期、客机读写、
+   断开全由 parser 持有）。把整个模块的用例挂在能力初始化调用上（libusb_init 成功才继续）
+   是设计缺陷，不是能力缺口（usbredir 首轮 F-02 五条全 blocked 实证，改走降级构造后全 pass）。
+1. **硬件判定点不写成普通 pass 判定**：确需真实硬件的，要么由阶段 1 把该路径写进
+   `prd.scope_out`（schema 已注：scope_out 对应 blockers/unadaptable_apis，阶段 5 不为它生成用例），
+   要么用例预期里显式标注能力缺口——不许写成一条注定 blocked 的普通用例充数。
+   **阶段 1 配套义务**：scan 判了 `adaptability=partial/unadaptable` 的 blocker 或非空
+   `unadaptable_apis`，就要在 `prd.scope_out` 收编它（写清哪条路径、为什么、待什么条件），
+   否则验收规则 `scope-out-coverage-consistent` 不允许下游再报 `target_path_covered=covered`——
+   「出范围」与「全覆盖」二选一，不许两头都不落。
+2. **平台确定性崩溃按 UB 红线同法取证**：硬件缺失导致的信号终止（如 libusb 无 NULL 守卫的
+   SIGSEGV）是平台确定性结果，用子进程隔离执行，父进程按子进程退出信号判定。
+3. **CLI 类用例先核对载体再写步骤**：hap 载体（cpp-lib-demo）没有 exec 通道，跑不了 CLI 二进制；
+   涉及可执行文件的用例走 `cli-hnp-runner` 载体（`ohpt-agent state --json` 的 `verify_carriers`
+   会给出本轮该产哪些载体，设计时就查，别等阶段 6 接线时才发现无处跑）。
+
+> 反例（usbredir 0.15.0，2026-09，同库两轮对照）：一轮 scan 未把「物理 USB I/O」写进
+> scope_out，阶段 5 把 host 模块 6 条 + CLI 2 条写成需真实设备的判定——7/21 blocked、
+> demo 终态 partial；另一轮把同一限制写进 scope_out、host 用例走空句柄/降级路径、
+> CLI 补「无 USB 降级运行」用例——24/24 pass。**同一平台限制，两种终态，分野只在设计取向。**
+> 配套机器执法：验收规则 `scope-out-coverage-consistent` 不许「partial 阻塞未出范围」
+> 与「target_path_covered=covered」共存。
+
+## 十、自评审四维检查单（阶段 5 收尾）
+
+两方比对（1:1 绑定、级别继承、覆盖度对账）已由验收规则机器执法，**不要再人工核一遍**。
+自评审只管机器判不了的四个维度，结论填进 `review`：
+
+| 维度 | 检查什么 | 不达标的样子 |
+|---|---|---|
+| 覆盖率 `coverage` | 模块是否都有用例；正常/异常/边界三类场景是否齐；枚举值是否全覆盖 | 只有 happy path |
+| 可执行性 `executability` | 每一步在目标载体上真做得出来吗；参数从哪来；**输入语义的步骤填了 `steps[].input` 吗**（缺了阶段 6 生成的页面就没有输入框，测试同学无从按步骤操作） | 「观察内存占用」这类载体上没有的观察手段；步骤写「输入 X」却没有 input 字段 |
+| 可判定性 `decidability` | 预期结果能直接判 pass/fail 吗；**错误契约断言（钉了退出码/错误码精确值）核对过上游出处吗**、**量化断言（次数/帧数/阈值）带齐出处与等价条件吗**、**UB 类操作的预期是平台确定性处置吗**、**partial 能力域的功能点对降级路径设计了吗**（四条红线，见 §九） | 「功能正常」「符合预期」「应该没问题」；退出码预期凭直觉写；阈值数字不带实测条件；double-free 预期写「不崩溃」；需要真实硬件的判定点写成普通 pass 判定 |
+| 规范性 `conformance` | 黑盒表述、平台无关、步骤不点名 API | 步骤里写 `glfwCreateWindow(...)`、出现 Windows/Linux 字样 |
+
+发现问题**当场改用例**；改不了的写进 `review.issues[]`（指名 `case_ref`）。
+`verdict=fail` 时写不出 `status=designed`（schema 执法）。
+
+## 十一、断点续跑
+
+**阶段 5**：`05-testcases.json` 已存在时只补 `coverage.uncovered[]` 里的功能点与 `review.issues[]`
+指名的用例；gate 要求规则升级审查时，保留已有设计并按 `reason` 核实当前清单及失败/受阻证据。
+源码证伪的 checkpoint 字面量或条件可修正，保留验证目标，逐条记录 amendment（before/after/basis/evidence_before）；
+同时同步受影响的 default。不以「checkpoint 不可变」保留错误标准。
+
+**阶段 6**：保留工程与接线。设计未变且证据仍有效时只补 `result ≠ pass` 与 `not-run`；
+设计修订、证据过期或 gate 要求本轮取证时，同步名册、页面、默认输入及断言，重新构建并全量运行当前有效 cases。
+阶段 6 读取通用清单的接线与取证要求，不代做阶段 5 审查；历史 pass 不能免除输入契约检查或代替本轮证据。
+
+确实做不到的用例：`result` 记 `blocked`，写进 `coverage.capability_gaps[]` 并说明原因——
+**不要**让它从 `case_results[]` 里消失（验收规则会点名缺结果行的用例），也不要手写平替冒充支持。
+
+---
+
+## 参考
+
+- `references/input-resources.md` — 文件资源契约、稳定沙箱准备、默认输入两入口验证与完成门禁
+- `references/test-contract-regressions.md` — 阶段 5 契约审查与阶段 6 接线、取证的通用清单
+- `references/case-design-methods.md` — 等价类 / 边界值 / 判定表 / 状态迁移路径生成 / 执行成本意识与等价替换（清单命令逐项全量解析陷阱、short 变体、非 defect 替换的留痕四件套）
+- `references/demo-wiring-pc.md` — 按形态的接线细则与常见坑
+- `references/anti-fake-checklist.md` — 反造假十条（含页面层自动判定禁条、包装器吞单步结论、退出码非证据/assert 的 NDEBUG 空洞）
+- `references/network-protocol-mock.md` — 网络协议库（IMAP/POP3/SMTP/HTTP）验证前置：hdc rport + 宿主 mock 服务器，把「无对端 blocked」转成可执行的正常/异常路径用例
+- `references/c-lib-upstream-semantics-checklist.md` —— C 库用例设计的上游语义核对清单（报文头随能力协商变化 / send 方向性静默丢弃 / 空串语义 / 降级 no-op 守卫 / 第三方运行时 NULL 守卫 / 反射库变体类型分支——type::destroy 只对裸指针生效、invoke 默认返回包装变体；usbredir 5 条 + rttr 1 条真机失败全根因）
+- `pc-schemas` — `01-scan.schema.json` 的 `prd`、`05-testcases.schema.json`、`06-testdemo.schema.json` 的字段契约
+- `pc-device-verify` — 设备通道、签名装机、失败归因
+- `pc-capability-domains` — 能力域替换方案（GUI/音频等载体的实现来源）