@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/anti-fake-checklist.md

@@ -0,0 +1,184 @@
+---
+description: 验证 demo 反造假十一条：被测产物为主链路禁绕过、成功来自真实返回值而非写死文案、真实输入到真实结果、参数真实传入、渲染验证禁用文本 dump 冒充、能力边界如实记 capability_gaps 禁手写平替、否定性前提必须先取证、页面层禁自动判定、包装器不得吞单步结论、退出码非证据（assert 连作用被 NDEBUG 编译掉，判定必须钉 stdout 证据行与编译期探针）、输入源模式匹配 API 语义（可寻址 API 走 feed 流式返回 -1 被「明确失败即通过」包装是假绿）。含收尾自查清单，防空 stub 假绿与 smoke 假通过。
+---
+
+# 反造假清单：验证 demo 的真实接入闭环
+
+**demo 存在的意义是证明适配产物真的能用，不是演一遍给人看。**
+
+以下十条在写完 demo、跑最终验证之前逐条自查。它们不是「注意事项」——每一条都对应一种已经发生过的假绿。
+
+---
+
+## 1. 被测产物是主链路
+
+同一能力，**禁止**页面直调系统 API、操作系统状态、或手写平替之后宣称「已验证适配产物」。
+
+- ❌ 页面自己调 `pasteboard` 系统接口，然后说剪贴板功能已验证
+- ✅ 调适配出来的库符号，由它去调系统接口
+
+**判据**：`cases[].covered_apis_harmony` 必须记下实际调用的**适配产物侧**符号。空的会被验收规则 `testdemo-wiring-real` 直接告警。
+
+---
+
+## 2. 成功来自证据，不来自文案
+
+「成功 / 已更新 / 已保存 / 已生效」必须建立在**真实返回值 / 回调 / 事件 / 回读验证**之上。
+
+- ❌ `onClick: { this.result = "设置成功" }`
+- ✅ `onClick: { const r = lib.setX(v); this.result = "返回: " + r + "，回读: " + lib.getX() }`
+
+边界用例的结果文案同理：验证「空字符串返回默认值」「最后调用覆盖」时，**不得写死预期**，要基于真实返回值推导。
+
+---
+
+## 3. 真实输入 → 产物 → 真实结果
+
+依赖真实文件 / 媒体 / URI / 序列化产物 / 网络响应的能力，**至少一个验证点走真实链路**；内存合成数据只能做辅助。
+
+设备能力（录音 / 相机 / 传感器 / 定位 / 蓝牙）必须用对应的鸿蒙 API 真实实现，**禁止** `Math.random()`、固定值、模拟数据、占位逻辑。
+
+---
+
+## 4. 参数真实传入
+
+界面上展示的参数必须真的传进被测符号并产生可观察的结果变化。
+
+参数在鸿蒙上不生效 / 产物未实现 / 已被裁掉 → 禁用或隐藏该控件并明确提示，**不得**展示成正常可调。
+
+---
+
+## 5. 渲染验证不许用文本冒充
+
+`checkpoint` 含视觉展示语义词（显示/渲染/绘制/出现/消失/滚动/高亮/颜色/动画/可见/隐藏/展开/收起/上屏）时，
+必须有**真视觉产物**并走**真上屏路径**。测试线不截图——机器管链路，人看画面：
+
+- 机器：载体自打的 `surface created` 与 `GL_RENDERER=` 两行必须在（验收规则 `testdemo-surface-attested`）。
+  它判的是「该答有没有答」，无 GL 上下文如实打 `<none>` 即可，但**渲染类用例判 pass 时打 `<none>` 会被点名**。
+- 人：在 demo 的满屏 surface 上直接看，看完点「符合 / 不符合」。每条用例画完停留 `ohpt-dwell-ms`
+  （页面可调速），别一闪而过。
+
+- ❌ `this.result = JSON.stringify(lib.getItems())` 然后说列表渲染已验证
+- ✅ 把 `getItems()` 的数据绑到真实列表组件渲染出来，人在页面上看得见条目
+- ❌ 机器替人给这类判定点下结论（打一条 `OHPTCASE check`）——**替人下结论**正是假绿的来源，
+  什么都别打、让它落 `pending-human`
+
+---
+
+## 6. 能力边界如实呈现
+
+需要的系统能力在鸿蒙上不存在 / 当前 SDK 不可用 / 只能由宿主完成时：
+
+1. 用例 `result = blocked`
+2. 进 `coverage.capability_gaps[]` 写明 `prd_ref` 与原因
+3. 页面做成可见的「不支持 / 需宿主接入 / 需设备能力」状态
+
+**禁止**手写平替冒充已支持，**禁止**从 `coverage.uncovered[]` 里抹掉。
+
+---
+
+## 7. 否定性前提必须先取证
+
+「设备上没有 X」「平台不支持 X」这类断言会驱动降级或改道，说之前先取证：
+
+- 设备侧可执行 / 运行时 → 走标准位置矩阵（`ohpt-agent env --runtime <eco> --device-only -w "$WORKSPACE"`）。**`which` 探不到 ≠ 不存在**：`hdc shell` 默认 PATH 不含 HNP。
+- 鸿蒙有没有某能力 → `ohpt-agent knowledge -s "<能力名>"` 查 SDK 声明语料再下结论。
+
+实证：曾据 `which git` 断言设备无 git 并造 fake 存根拿到 7/7 PASS，而设备上 `hnppublic/bin/git`（2.45.2）一直都在。
+
+---
+
+## 8. 页面层禁止自动判定（started ≠ pass）
+
+**demo 页面层不得把「启动了」当「通过了」**。页面渲染成功、`onPageShow` 回调触发、任务启动——都只说明应用活着，不说明被测产物行为正确。结果判定的唯一权威是 **native 侧真实返回值 / 退出码 / 结果行**。
+
+- ❌ 页面层 `ohptRunnerAutoJudges=true`（默认把"启动完成"自动判为 pass）——libetpan 测试线实证：首轮 **38/38 全绿**全是假绿，关闭页面判定后真实分布暴露为 10 过 5 败 23 blocked
+- ✅ `ohptRunnerAutoJudges=false`，native 执行完把 `OHPTCASE result=<pass|fail|blocked>` 结果行经 hilog 打出，机器判据**只认结果行**；页面显示真实返回值（`返回: 0` 而非 `成功`）
+
+**接线要求**：
+1. scaffold 的 `ohptRunnerAutoJudges` 一律设 `false`（模板默认值就是 false，改回 true 等于自造假绿）；
+2. 结果区展示**真实返回值**，不是写死文案；
+3. 结果行唯一来源为 native 退出码 / 返回值推导，页面不参与判定。
+
+> 与第 2 条同源（成功来自证据不来自文案），但专门钉死「页面层自动判定」这个最隐蔽的形态——页面代码看起来在跑、日志也在出，判定却被框架代做了。
+
+---
+
+## 9. 包装器不得吞掉单步结论，断言不得 OR 弱化 AND 契约
+
+多步用例（尤其 CLI 形态）委托给 helper / 包装器脚本时，**包装器的整体退出码不能顶替被测二进制单步的真实退出码**——每步的 rc 与 stderr 必须独立捕获、传播、打印。错误契约断言必须保持上游 / 用例契约的**原语义**（说「报错**且**非零退出」就是 AND），禁止用 OR 放宽（`rc != 0 || stderr含error` 会让 rc=0 也判过）。
+
+- ❌ helper 跑完全部步骤只回 `exit(0)`，cp 断言写成 `rc != 0 || cap.find("error")`——AND 契约被 OR 弱化，实测 `actual=zero-but-err` 仍 `ok=1 / result=pass`
+- ✅ 每步独立 fork/exec 被测二进制，捕获该步 rc 与 stderr，逐行打 `stepN … rc=X`；cp 断言用 AND（该步 rc != 0 **且** stderr 含错误提示）；结果行打印单步真实退出码
+
+**判据**：结果行里能看见单步的真实退出码。收紧断言后若实测 rc 与契约不符，先查被测物是否真有缺陷（直接在设备上跑原命令实测），**禁止改断言迁就**。
+
+实证（usbredir F-04-01，2026-09-16）：黑盒 helper `f04-01-client` 整体 rc=0 掩盖了 usbredirect 非法参数步的真实 rc=1，叠加 OR 弱化断言 → 假绿 pass；修复 = 弃用黑盒 helper、每步独立 exec 捕获 rc、断言收紧 AND 后，实测被测物本身 rc=1 非零（无缺陷），问题纯在链路。
+
+---
+
+## 10. 退出码不是证据：assert 会连作用一起被编译掉，判定必须钉住可比对的输出内容
+
+`rc == 0` 只证明「进程活着走完」，不证明「语义对了」。「断言自证 + 零输出」有两类假绿形态：
+
+- 空 stub rc=0（接线层，§1 已覆盖）；
+- **NDEBUG 空洞**（本条专钉）：测试程序是**真的**，但正确性证据只写在 `assert()` 里、stdout 零输出——
+  构建带 `-DNDEBUG`（release 惯配，设备侧 hvigor CMake 默认就带）时 assert 被**整体编译掉**，
+  空实现照样 rc=0，actual 里「退出码 0，类型推导正确，xx 语义生效」全是没有证据的宣称。
+
+判定必须钉住**与预期可比对的 stdout 内容**，且证据不得依赖断言生效：
+
+- ❌ `out` 捕获了却不用，ok 只判 `rc == 0`，actual 写「退出码 0，语义生效」
+- ✅ 测试程序把关键推导结果打**结构化证据行**（`PROBE|对象|标签|实际值`，值写实际观测不写死预期）；
+  接线体对预期行做**带行尾 `\n` 的整行比对**（防子串误配：`int const&` 是 `int const&&` 的前缀），
+  actual 引用观测行原文；**编译期语义（const/不可变/类型推导）用 SFINAE + static_assert 探针**——
+  它是「编译期拒绝」的可执行形式（static_assert 编不掉，语义丢了 ELF 自己构建失败），探针结论照样
+  打印成行供 runner 比对；被测工具自身能产出该产物时（转译/生成类），先在设备上真跑一步产出、
+  再验性质——端到端证据优于纯预编二进制。
+
+配方细节 → `demo-wiring-pc.md` §「证据行与编译期探针」；错误图谱 → E173。
+
+实证（转译器类 C++ 库，2026-09）：某「声明语句经包装获得不可变语义」用例只判 rc==0，评审点名
+「既没展示声明语句的产物、也没展示不可变本身」；补三层证据（设备上真转译看产物行 / 赋值探针
+blocked + 未包装对照组 allowed / 推导类型名逐行比对）后，actual 才第一次可被人工逐项核对。
+
+---
+
+## 11. 输入源模式必须匹配 API 语义：可寻址 API 走 feed 流式返回 -1，被「明确失败即通过」包装是假绿
+
+基于**可寻址输入**的 API（seek / scan / 定位 / 帧号 / 索引）与**流式喂入**（feed）是两种输入源模式，
+语义互斥：feed 模式没有可寻址的输入，这些 API 固定返回 -1。demo 若用 feed 模式去「验证」它们，
+再把「返回 -1 但进程没崩溃」包装成「行为明确、验证通过」，就是假绿——checkpoint 要的是
+**成功后的精确状态**（如「跳转后帧号 == 500」「索引扫描完成且可用」），不是「调用没崩」。
+
+- ❌ `mpg123_open_feed` 喂数据后调 `seek_frame(500)`/`mpg123_scan`，返回 -1，cp 断言写「调用无崩溃（rc=-1）即通过」
+- ✅ 可寻址 API 走文件路径打开（`mpg123_open_fixed` + app 沙箱内真实文件，夹具拼接成长流）；
+  seek_frame(500) 返回 500、tellframe=500，scan rc=0 且索引填充——拿真实返回状态判
+- ✅ 确无能力提供可寻址输入（app 域拿不到真实文件）→ 如实 `result=blocked` + `capability_gaps[]`，
+  禁以「-1 也算明确结果」冒充 pass
+
+判据：checkpoint 要求的是「成功后的精确状态」时，actual 里出现「返回 -1 / 调用无崩溃」这类
+「明确失败但没崩」的字样 = 降级路径被滥用于本该成功的行为断言，是假绿，不是验证。
+
+实证（mpg123 测试线 F-04-02 等 5 条，2026-09-21）：`seek_frame(500)`/`scan` 走 feed 模式 rc=-1 被
+「无崩溃」判 pass；改 `mpg123_open_fixed` 文件打开后 seek_frame 返 500/tellframe=500、scan rc=0
+index fill=520，真实通过。配套坑：拼接 MP3 帧做长流夹具时首帧是 Xing/VBR 头（声明固定帧数），
+跳过它才能真正拼出 >500 帧长流，否则 mpg123 仍只报声明帧数（40 帧）导致 seek_frame(500) 假过。
+
+---
+
+## 收尾自查
+
+> 只列**机器执法覆盖不到**的。已被验收规则关掉的（接线符号回填、覆盖度现算、证据在盘）不重复写。
+
+- [ ] 每条判定点都有一个来自**给得出它的判定者**的结论：机器判得了的带 expect/actual，判不了的留给人
+- [ ] **expect 点名的每个对象都真测了、各有独立的判定点行**（expect 说判 A 和 B，actual 不能只给得出
+      B 的观测；一句多判的合并行按 `demo-wiring-pc` §「判定点粒度」拆分——半测假绿 rttr F-04-04 实证）
+- [ ] 判定点比对的是**可核对的输出内容**（证据行/观测值原文），不是只看退出码——测试程序换成 `-DNDEBUG` 构建证据也还在
+- [ ] 结果区展示的是真实返回值，没有写死的成功文案
+- [ ] 渲染验证类用例在设备屏幕上**真能看见**目标画面（亲自看过，不是读日志推的）
+- [ ] 做不到的功能点进了 `capability_gaps[]`，没有被平替、没有被抹掉
+- [ ] 所有否定性断言都有探测证据
+- [ ] 多步 / CLI 用例的断言保持契约原语义（AND 就是 AND），单步真实退出码在结果行可见，没有包装器整体 rc 顶替单步 rc
+- [ ] 证据文件真在 `test-demo/verify/` 下，且列进了 `artifacts[]`
+- [ ] 可寻址 API（seek/scan/定位）没走 feed 流式验证冒充——actual 里没有「返回 -1 但没崩」冒充「验证了行为」

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/c-lib-upstream-semantics-checklist.md

@@ -0,0 +1,78 @@
+---
+description: C 库（协议库/系统库/反射库）用例设计的上游语义核对清单——写 checkpoint 前逐条问「上游代码真是这么写的吗」。usbredir 0.15.0 实证：5 条用例真机失败全部是设计断言与上游实际语义不符（报文头长度随能力协商变化、send 方向性静默丢弃、空串语义、降级模式 no-op 守卫、第三方运行时 NULL 守卫缺失），修复后 24/24 全过。rttr 0.9.7 实证第 6 查：`type::destroy()` 只对裸指针变体生效、`constructor::invoke()` 默认返回 shared_ptr 包装变体，demo 用包装变体 destroy 反被误判成用例缺陷、把预期反向改成违背 PRD 的「destroy 返回 false」。配套 SKILL.md §九的三条红线（错误契约出处 / 量化断言出处 / UB 平台确定性处置）。
+---
+
+# C 库用例设计的上游语义核对清单
+
+usbredir 0.15.0（cpp-lib-demo，24 条用例）实证：**5 条真机失败全是「设计断言 vs 上游实际语义」偏差，零产物缺陷**——4 条是断言写错、1 条是 UB 输入触发第三方运行时崩溃。每条都是设计期读上游源码 5 分钟就能避免的返工（教训烧了一轮真机 + 一轮修复）。
+
+**核对动作**：为 C 库写 checkpoint 前，把断言涉及的每个 API 打开上游源码读一遍调用链，逐条过下面 5 查。凡断言依赖「上游会怎样」的假设，给出 file:line 或删掉断言。
+
+## 一查：报文级断言的 type header 长度是否随能力协商变化
+
+带能力协商的协议库，同一报文类型的 type header 长度可能是**变量**。usbredirparser 的 device_connect：双方都协商 `usb_redir_cap_connect_device_version` 时 type header = 10 字节（含 device_version_bcd），否则 8 字节（`usb_redir_device_connect_header_no_device_version`）。
+
+- **实测翻车**：测试向量按 8 字节构造 device_connect、peer hello 却声明了该 cap → 解析器按 10 字节校验 → `usbredirparser_do_read` 直接返回 `read_parse_error`，回调不触发；且 parse error 后解析器置 `to_skip = 坏包 length`，**下一份测试报文的前 to_skip 字节会被当垃圾跳过**，后续断言连带全错（F-01-03 两个 cp 都挂在这一颗雷上）。
+- **设计规则**：构造报文前按「测试夹具实际声明的能力位」推 type_header_len（引 `usbredirparser.c get_type_header_len`）；长度字段一律 `sizeof(结构体)`，不写魔数。喂坏包后若还继续喂包，先想清楚 to_skip 吃掉多少。
+
+## 二查：send_* 的协议方向——反方向发送被静默丢弃
+
+协议命令有方向（host→guest / guest→host）。usbredirparser 的 `get_type_header_len(type, send)` 按解析器角色（`usbredirparser_fl_usb_host`）+ 方向翻转 `command_for_host`，方向不合法返回 -1，`usbredirparser_queue` 对此**静默 return：不入队、无返回码、无异常**。
+
+- **实测翻车**：guest 侧解析器（无 fl_usb_host）调 `usbredirparser_send_device_disconnect`（host→guest 命令）→ `has_data_to_write` 恒 0、`do_write` 空转，用例以为测的是「写出缓冲」实际什么都没发（F-01-04 cp1-cp3 全挂）。连带坑：**累积式断言（只看 has_data_to_write > 0，从不 do_write）会被先前入队的其他报文掩盖静默丢弃**（F-01-05 的 5 发送只真发了 1 个仍 pass）。
+- **设计规则**：先定解析器角色再选报文类型——host 命令（device_connect/device_disconnect/interface_info/ep_info）用 `fl_usb_host` 解析器发，guest 命令（reset/control/bulk 等）用 guest 解析器发；「每个 send 独立验证入队」（发送→flush→清空→下一个），不做累积式 has_data 断言。
+
+## 三查：空串/边界输入的语义——读解析源码，别凭「非法必报错」直觉
+
+**实测翻车**：`usbredirfilter_string_to_rules("")` 返回 **0（0 条规则）** 而非 -EINVAL——上游规则计数循环对空串得 0、strtok_r 立即返回 NULL，根本走不到校验。用例把空串当非法输入断言 -EINVAL，真机必挂（F-02-02）。
+- **设计规则**：非法输入集合逐个对照上游源码的判错分支（`strlen(sep)==0 → -EINVAL`、字段数≠5 → -EINVAL、strtol 残留 → -EINVAL、verify 越界 → -EINVAL），**空串是不是错误输入以上游为准**；「非法输入」清单里的每一项都要能指到上游的判错代码行。
+
+## 四查：降级模式（无硬件）下，上游守卫让错误码路径不可达
+
+无硬件环境的降级实例（NULL 设备句柄）会命中上游回调入口的守卫，把错误码路径整个短路。usbredirhost 的 reset 回调：
+
+```c
+static void usbredirhost_reset(void *priv) {
+    if (host->disconnected || host->reset) return;   /* 降级实例 disconnected==1，直接空转 */
+    r = usbredirhost_reset_device(host);
+    if (r != 0) host->read_status = usbredirhost_read_device_lost;   /* 不可达 */
+}
+```
+
+- **实测翻车**：用例喂 `usb_redir_reset` 断言 `read_guest_data` 返回 device_lost(-4)——降级 host 上 reset 是 no-op，实际返回 0（F-03-03 cp2）。`device_lost` 需要**真实设备的 reset 失败**才触发，无 USB 硬件的鸿蒙 PC 上该路径不可达。
+- **设计规则**：写「错误码可达」断言前，从入口到错误码赋值逐层找守卫（disconnected/initialized/handle==NULL）；有一条守卫挡住就改断言为守卫后的实际行为（no-op、返回 0、仍可判定「不崩溃+行为确定」），并把「完整路径需硬件」记进用例备注。
+
+## 五查：依赖第三方运行时（libusb 等）的 NULL 守卫不能假设
+
+上游头的注释承诺「获取描述符失败返回 -EIO/-ENOMEM」（usbredirhost_check_device_filter），但该契约依赖 `libusb_get_device_descriptor` 对 dev=NULL 的空指针守卫——**鸿蒙 conan libusb 1.0.27（libusb-1.0.so.0.4.0）实测无守卫**：直接调 `check_device_filter(rules, n, NULL, 0)` → `Signal:SIGSEGV(SEGV_MAPERR)@0x8 NULL pointer dereference`，进程死掉、整条用例无结果行（F-03-05 初版）。上游自身从不传 NULL（调用方总有真实 device），NULL 行为是无背书的臆造契约。
+
+- **设计规则**：断言第三方库对非法指针入参的行为前，先确认**上游自身是否真的这样调用**；上游从不发生的调用 = 无契约，按 SKILL.md §九 UB 红线处理——**子进程隔离执行 + 父进程确定性观测**，且隔离本身要防挂（见下）。
+- **隔离观测的完整姿势**（真机实证两坑）：fork 子进程单次调用，父进程 waitpid **必须 WNOHANG + ~1.2s 时限 + SIGKILL 兜底**——fork 出的子进程崩溃后 faultlogger/processdump 对孤儿态的转储可能无限期不完成，阻塞式 waitpid 实测拖满 121s（主线程卡死、用例超时）；观测结果两种都合法：libusb 有守卫的平台子进程带回 -EIO/-ENOMEM，无守卫平台子进程 SIGSEGV（或被兜底 SIGKILL）——断言写「两种平台形态之一被确定性观测到，主进程存活、用例按时出结果行」。
+
+## 六查：反射/包装类库的变体类型分支——`invoke()` 默认返回包装变体，`destroy()` 只支持裸指针
+
+反射类库的构造/销毁 API 对**变体类型有分支**：`constructor::invoke()` 默认构造策略 `as_std_shared_ptr`
+（注册时没加 `as_raw_ptr` 即此行为）返回 `std::shared_ptr<T>` 包装变体；而 `type::destroy()` →
+`destructor_wrapper<ClassType>::invoke` 只判 `obj.is_type<ClassType*>()`，**只对裸指针变体** `delete` + 清空，
+对 shared_ptr 包装变体恒返 false 且变体仍有效（shared_ptr 还持有着对象）。
+
+- **实测翻车（rttr 0.9.7）**：demo 用 `constructor::invoke(3,7)` 得到的 shared_ptr 包装变体去 `type::destroy()`，
+  「销毁返回成功 / 销毁后判定无效」两条全挂（实得 destroy=false、is_valid=true）。更要命的是，阶段 5 据此把预期
+  **反向改成**「destroy 返回 false」——直接违背 PRD checkpoint「type::destroy(variant) 返回 true」。
+- **设计规则**：写「销毁/实例有效性」断言前，先确认变体的**实际类型**命中上游该 API 支持的分支——
+  上游单测 `constructor_invoke_test.cpp` 的 `as_raw_ptr` 段对裸指针变体 `destroy == true`、`as_std_shared_ptr` 段
+  **从不调 destroy**（作者自己知道 destroy 不适用包装变体）。变体类型由 `constructor::invoke` 的默认策略决定，
+  要验销毁就改用裸指针变体（`variant` 持有 `T*`，或注册 `as_raw_ptr`）。
+- **归因纪律**：`actual ≠ expect` 先二分「demo 接线用错 API/变体」vs「用例预期写错」，别顺手把预期改成
+  「实际所见即预期」（那是把不过的用例改到过最顺手的后门）。amendment 改预期**不得改到违背 PRD checkpoint**——
+  PRD 检查点是判据的锚，改它就是篡改评判标准，而不是修用例。
+
+## 修复对照表（usbredir 0.15.0 真机实证）
+
+| 用例 | 现象 | 根因（上游出处） | 修法 |
+|---|---|---|---|
+| F-01-03 | device_connect 回调不触发；第二包预期 parse_error 实得 0 | type header 随协商为 10B，向量发 8B；to_skip 连带 | length 改 `sizeof(struct usb_redir_device_connect_header)`，缓冲 12+10 |
+| F-01-04 | send 后 has_data 恒 0；write 错误路径测不出 -1 | guest 发 host 命令被 queue 静默丢弃；写回调 stub 永不失败 | 解析器加 `fl_usb_host`；写回调用可失败 stub；错误路径排 2 包（stub 从第 2 次调用起返回 -1） |
+| F-02-02 | 空串预期 -EINVAL 实得 0 | 上游把空串当 0 条规则返回 0 | 空串移出非法集；补「空 token_sep / 非数字字段」两个真非法输入 |
+| F-03-03 | reset 后预期 device_lost(-4) 实得 0 | 降级实例 disconnected=1，reset 回调入口空转 | 断言改为 no-op 语义（返回 0、不崩），备注完整路径需硬件 |
+| F-03-05 | 进程 SIGSEGV @0x8，无结果行 | conan libusb 1.0.27 无 dev=NULL 守卫 | cp2 改 fork 隔离 + WNOHANG/1.2s/SIGKILL 观测，断言两种平台形态 |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/case-design-methods.md

@@ -0,0 +1,199 @@
+---
+description: 用例设计方法总表：等价类划分、边界值分析、判定表、状态迁移 0/1/2-switch 覆盖与路径生成算法；行为差分用例（依赖运行时数据的三段式交付前提检查，terminfo/locale 类）；功能点拆分、优先级 P0/P1/P2、级别 L0/L1/L2、数量上限、覆盖度自检清单。IBO 三维（Input/Behavior/Output）选方法的依据。
+---
+
+# 用例设计方法（等价类 / 边界值 / 判定表 / 状态迁移）
+
+配套 `SKILL.md` 第三节 IBO 分析。选方法的依据是**特征**，不是习惯。
+
+---
+
+## 1. 等价类划分（Input 维，最常用）
+
+把输入域切成「同类输入产生同类可观测结果」的若干块，每块取一个代表值。
+
+| 输入特征 | 有效等价类 | 无效等价类 |
+|---|---|---|
+| 数值范围 `[1, 100]` | 区间内任一值（如 50） | `<1`、`>100`、非数值 |
+| 字符串（有格式约束） | 合法格式 | 空串、超长、非法字符、编码异常 |
+| 枚举 | 每个取值各一类（见 SKILL 枚举全覆盖） | 未定义值 |
+| 对象/句柄 | 有效实例 | null、已释放、未初始化 |
+| 集合 | 非空 | 空集合、单元素、超大 |
+
+**产出**：每个有效类 → 一个 normal 功能点；每个会产生**可区分错误结果**的无效类 → 一个 exception 功能点（受数量上限约束，P0 最多 2 条）。
+
+### 输入步骤的字段化（steps[].input 映射模式）
+
+步骤语义是「输入 X 执行」的必须填 `steps[].input`（kind/label/default——字段定义见 schema，
+何时必填见 SKILL.md §九）。**步骤 → 输入框的映射**有四种模式（libidn2 10 用例实证，
+2026-09——映射错则 demo 输入体验错，测试同学无法按步骤操作）：
+
+| 模式 | 什么时候用 | 实证 |
+|---|---|---|
+| **一对一步骤一框** | 该步骤的输入只服务这一步 | F-02-01 步骤1 合法域名 / 步骤2 纯 ASCII / 步骤3 非法域名各一框（`text`） |
+| **多界面共用一框** | 多个步骤是对**同一输入**经不同 API 界面验证（同一码点数组走三种转换接口）——input 只挂在**首个**步骤，后续步骤不设框（native 侧同段复用） | F-02-02 步骤1-3 共用一个 `codes` 框 |
+| **边界步骤不设框** | 步骤的「输入」是结构性前提（超长 255+ 字符、过小缓冲区、NULL 指针）——不适合输入框承载，由 demo 内置向量执行，不填 input | F-02-02 步骤4 超长 / F-05-01 步骤2 小缓冲 |
+| **双值对双框** | 一步需要两个配对输入（U-label 与 A-label、key 与 value）——`pair`，default 形如 `"值1\|值2"` 按首个 `\|` 拆两框 | F-04-02 匹配对 / 不匹配对各一组 |
+
+三条配套纪律：**default 即机器跑批的回落向量**（无输入 = 用它），要选稳定可复现的代表值；
+**kind 选错解析即失败**（码点/数值序列用 `codes`，别用 `text` 让 native 收到原始字符串）；
+非法/边界输入的**多条同型值**合并到一个步骤（逗号分隔 + demo 内置向量追加），不要一步一条
+拆成十条步骤（用例数量上限不允许，且步骤面板会失去可读性）。
+
+---
+
+## 2. 边界值分析（Input / Output 维）
+
+只在**存在明确边界**时用。取 `min-1, min, min+1, max-1, max, max+1`，按数量上限裁剪为最有价值的 2 条（P0）/ 1 条（P1）。
+
+常见边界来源：
+- 数值上下限、缓冲区大小、数组下标
+- 长度限制（路径长度、字符串长度、队列深度）
+- 时间/超时阈值
+- 分辨率 / 尺寸 / 坐标（窗口、画布、图元）
+- 空 ↔ 非空 的跨越点
+
+> 边界值优先选**跨越边界会改变可观测行为**的那一对（如 `max` 成功 / `max+1` 失败），单纯的「中间值」没有边界价值。
+
+---
+
+## 3. 判定表（Behavior 维：多条件组合）
+
+行为由多个独立条件共同决定时用。列出条件组合与对应动作，合并「结果相同」的列。
+
+```
+条件            C1  C2  C3  C4
+已初始化        Y   Y   N   N
+有可用设备      Y   N   Y   N
+------------------------------
+动作
+正常执行        ✓
+返回无设备错误      ✓
+返回未初始化错误        ✓   ✓      ← C3/C4 结果相同，合并为一条功能点
+```
+
+**产出**：每一个**合并后**的动作列 = 一个功能点。条件数 n 时理论组合 2^n，合并后通常 3~5 条，仍超上限就按优先级砍 exception 类。
+
+---
+
+## 4. 状态迁移覆盖（Behavior 维：有状态机）
+
+### 覆盖等级
+
+- **0-switch**：覆盖每条单边（`A --e--> B`）
+- **1-switch**：覆盖每对相邻边（`A --e1--> B --e2--> C`）
+- **2-switch**：覆盖每三条连续边
+
+深度与上限按 SKILL.md 第三节的表（P0=2-switch/≤12，P1、P2=1-switch/≤8、≤5；状态数 ≤3 各降一级）。
+
+### 路径生成算法
+
+```
+输入：状态迁移表 E = { (from, event, to) }
+
+1-switch:
+  for e1 in E:
+    for e2 in E where e2.from == e1.to:
+      yield [e1.from, e1.event, e1.to, e2.event, e2.to]
+
+2-switch:
+  for e1 in E:
+    for e2 in E where e2.from == e1.to:
+      for e3 in E where e3.from == e2.to:
+        yield [..., e3.event, e3.to]
+```
+
+超上限时的裁剪序：① 先保留经过 P0 状态的路径 ② 再保留含错误/异常迁移的 ③ 最后按路径长度短优先。
+
+### 典型状态机（PC 适配常见）
+
+| 场景 | 状态 | 事件 |
+|---|---|---|
+| 窗口生命周期 | 未初始化 → 已初始化 → 已创建 → 已显示 → 已销毁 | init / create / show / hide / destroy / terminate |
+| 资源句柄 | 未打开 → 已打开 → 已关闭 | open / read / write / close |
+| 播放器 | 空闲 → 就绪 → 播放中 → 暂停 → 停止 | prepare / start / pause / resume / stop / release |
+| 连接 | 断开 → 连接中 → 已连接 → 重连中 | connect / disconnect / timeout / retry |
+
+**重进入与旧回调**是最容易漏的迁移：重复 init、销毁后再调用、旧回调在新状态到达后才回来——这三类各值一条 exception 功能点。
+
+---
+
+## 5. Output 维方法
+
+| 输出特征 | 方法 | 关注点 |
+|---|---|---|
+| 集合/列表 | 空集合验证 | 空、单元素、多元素的渲染与计数 |
+| 数值 | 边界值 | 精度、溢出、负零、NaN |
+| 格式化文本/序列化 | 格式验证 | 编码、转义、换行、超长截断 |
+| 回调/事件 | 时序验证 | 触发次数、顺序、参数完整性、不重复注册 |
+| 上屏产物 | 视觉验证 | 见 SKILL.md 第六节渲染验证 |
+
+---
+
+## 6. 行为差分用例（交付前提检查：依赖运行时数据）
+
+> 这**不是 PRD 功能点用例**——它不占 31 条功能点覆盖度，不按 L0/L1/L2 分级，
+> 挂伪用例通道（与 `__hap_dlopen__` 同级），计 `total_cases` 但独立标注来源。
+
+**触发条件**：delivery 必做项「产物动态符号命中数据访问族」命中（见
+`pc-delivery-forms` 表），即产物运行时会读系统数据目录
+（terminfo/locale/CA/插件数据…）而目标机缺失（判定链见
+`pc-capability-domains/references/capability-domains/runtime-data-assets.md`）。
+
+**为什么常规功能用例测不出来**：PRD 功能点断言锚在库内状态（返回值/缓冲区/计数），
+环境数据缺失走静默降级不触发任何断言失败——全绿与本缺陷共存（readline 实测：
+降级状态下 32/32 全过，E130）。
+
+### 三段式模板（每段失败语义独立）
+
+| 段 | 断言什么 | 反例锚点 |
+|---|---|---|
+| ① 数据可达 | 查询调用真实命中随包数据（如 `tgetent("xterm-256color") == 1`） | stub/恒定值实现在此段即红 |
+| ② 能力真实 | 返回内容**非空且非恒定**——是随包数据的具体值（如 `tgetstr("cm")` 以 `ESC[` 开头、`tgetnum("cols")==80`） | 恒 1 空能力表在此段红 |
+| ③ 行为级证据 | 数据驱动的行为真实发生，输出前后**可区分**（如 PTY 捕获到渲染输出含 `ESC[` 序列） | "随包了但没被读到"在此段红 |
+
+### 命名与接线
+
+- 命名：`__<数据族>__`（如 `__terminfo__`），与伪用例命名惯例一致
+- cli 载体：runner 内实现（含环境自举：`argv[0]` 相对路径 + `setenv`）
+- hap 载体：napi_stub 伪用例分支 dlsym 同一组符号做 ①② 段
+- 失败语义：任何一段不过 → 03-adapt 不得标完整交付态（"链接成功 ≠ 交付可用"）
+
+---
+
+## 7. 自检清单（写完功能点后过一遍）
+
+- [ ] 每个模块都做了 I/B/O 三维，缺一不可
+- [ ] 功能点是「单一能力」，没有按 API 个数硬拆，也没有把多个独立验证目标塞成一条
+- [ ] 枚举参数的取值已覆盖（≤5 全覆盖 / >10 取代表值）
+- [ ] 有状态机的模块出了迁移路径表；无状态机的写明「不适用」
+- [ ] 数量上限没超（P0 ≤2 异常 +2 边界，P1 ≤1+1，P2 不生成异常/边界）
+- [ ] 级别按 优先级 × 场景 的表推出，没有二次调整
+- [ ] `checkpoint` 全部具体可判定，无「功能正常」类模糊词
+- [ ] 功能点名与 checkpoint 无 API 词汇、无平台特定词汇
+- [ ] 每条功能点有稳定 id，`module` 能在 `prd.modules[].code` 里找到
+
+---
+
+## 8. 执行成本意识与等价替换（某交叉工具链工程 实证 2026-09-21）
+
+**选被测命令时警惕「清单类目标逐项做全量解析」的实现**：`ct-ng list-samples` 在
+`samples/samples.mk:65` 展开为 166 个 `list-<sample>` make 目标，**每个目标完整跑一遍 kconfig conf**
+（`:79-86`）——单次在设备上实测 62s~397s（随设备状态波动 6 倍），两条用例各调一次就吃掉整轮 93%
+的时长（14.5 分钟 → F-01-01 397s + F-02-01 393s）。设计断言时先估执行成本：清单/枚举类命令
+可能对每一项做完整解析，样本数 × 单项成本就是用例下界。
+
+**框架常带等价的低成本变体**：`list-samples-short`（`samples/samples.mk:87-92`）只 echo 样例名，
+与 full 版同一样例集（CT_SAMPLES），秒级返回。当断言面只关心「清单内容/格式/退出码」而不需要
+逐项的状态注记时，**优先选 short/quiet 变体**——检查点语义不变，执行方差消失。本轮整轮
+14.5 分钟 → 80 秒。
+
+**换命令的留痕路径（非 defect 修正）**：`amendment` 的 class enum（expectation-condition-mismatch /
+api-contract-mismatch）只为「阶段 6 判 defect 后修正预期」预留——检查点原样保留的等价命令替换
+**不属 defect 修正，不硬套 amendment**。留痕走四件套：
+
+1. `cases[].notes` 记依据（`file:line` 指向两个命令的实现处 + 成本数据）
+2. evidence_before 照样存档（`test-demo/verify-fix<N>/<case-id>.pre-<tag>.json`）
+3. 改完 05-testcases.json 重跑 `ohpt-agent scaffold --test-cases` 同步 OhptCases.ets（cases-sha256 锚点，
+   demo-casetable-synced 规则执法）
+4. 接线体（napi_stub.cpp 的 ck() expect 文案）与用例表同步改，机器 check 行才与页面对得上