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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: pc-roster-generation
+description: 生成侧用例方法论（阶段 2 必跑名册专用）：上游用例剔除与可执行性分诊、补写用例集判定（gap-ledger，API 粒度）、用例写作流程（粒度三问 → 断言五步法 → 四澄清 → S2 前提）、五源决策表、覆盖证据两档判据、宿主构建通道与自证、探针校准、组合骨架（非注入五骨架 + 注入形态）。由 pc-02-dev-test-cases 注入使用；触发词包括 oracle_plan、五源表、S1 S2 S3 S4 S5、证据等级、E1 E2 E3、版本锚核对、缺口账、gap-ledger、disposition、full-case gap-case supporting、触达账、粒度三问、拆合序列、组合骨架、实例隔离、运行中更新、中途恢复、重入、持久化、注入组合、注入可达性、键值码表、断言五步、四澄清、类型单位结构失败形态、澄清、关系前提、roundtrip 守恒幂等单调、可执行性、executability、runnable degraded blocked、分诊、unknown 回填、构建通道、build-once、设备预算、no-op 对照、断言架空、强档、弱档、observable_via、ref≥symbol、指纹链、tests_generated_hashes、探针、差异面、三向对照、闸A 闸B。
+---
+
+# pc-roster-generation：生成侧用例方法论（阶段 2 专用）
+
+**要解决的问题**：补写用例/无上游场景没有 CI 背书——断言预期值从哪来、覆盖怎么核销、补什么不补什么、失败怎么归因，四件事此前无统一方法，执行全凭口味。
+
+**适用**：`pc-02-dev-test-cases` 生成 `02-baseline.json` 的全名册定稿。上游用例（`source=upstream`）沿用上游 CI 背书，**不适用**断言/预算纪律（但适用上游剔除与可执行性分诊）。
+
+## 使用方式（按需读对应 reference，不全读）
+
+| 你在做 | 读哪 | 关键判据 |
+|---|---|---|
+| 发现上游套件、剔除三类（平台专有/不可执行/scope_out） | `references/upstream-triage.md` | 两出口：有套件→三值分诊 runnable/degraded/blocked；无套件→记结论+证据跳过分诊；unknown 不许放行 |
+| 定补写用例集（哪些 L0 功能点/API 要补） | `references/gap-ledger.md` | 五步 + 无套件捷径；API 粒度三分类；supporting ≤50%；L1/L2 同步登记台账——本步是唯一范围裁决点 |
+| 判用例粒度（合/拆/序列 + 组合形态） | `references/case-granularity.md`（粒度轴权威：拆留三问/三种前置/横切归账/输入域/状态面派生） | 写用例**之前**先定边界 |
+| 补写用例铺边界（测什么想全） | pc-knowledge-base「鸿蒙PC-C库设备验证测试设计」 | 五族边界模板（数值解析/编码往返/fd 生命周期/流操作/格式化）+ API 族三分法 |
+| 写断言（五步法/四澄清/S2 前提/五源表） | `references/assertion-authoring.md` | 定对象→取预期→找佐证→判差异面→选形态；L0 禁 S5 |
+| 组合用例选骨架（非注入） | `references/combination-patterns.md` | 五骨架选型；骨架是工具箱不是配额 |
+| 注入组合用例（键盘/鼠标/触摸可达的断言目标） | `references/injection-combination.md` | 注入可达性判定；键值查 2000 段码表；断言引用回调交付数据 |
+| 宿主自证（通道选择/结局处置/no-op 对照） | `references/host-selfvalidation.md` | 通道①②③序；编译器探测做全；no-op 对照拦恒真 |
+| 探针校准（S1 钉值落平台差异面） | 本文件 §差异面探针校准 | 观测物落闸B + 三来源哑火 → 探针唯一合法定案路径 |
+| 覆盖核销与预算（两档判据/L1L2 登记/设备预算） | `references/budget-and-coverage.md` | L0 恒强档 / 弱档占比护栏 / cap-out 台账 |
+
+## 预期值五源决策表（逐观测物按序指派）
+
+每条断言预期值必须来自五源之一；**五源取不到 → 不许钉值**，降行为级或删断言。
+
+| 源 | 取什么 | source/grade/ref_note 写法 |
+|---|---|---|
+| S1 PRD checkpoint+evidence | 阶段1 已钉的可判定预期 | `S1/n-a/出处: prd F-xx-xx + file:line` |
+| S2 属性（平台无关真值） | 逆运算/幂等/确定性/守恒 | `S2/n-a/属性: roundtrip（前提: …）`——免出处**不免论证**，前提表见 `references/assertion-authoring.md` |
+| S3 平台实测契约 | E1 分歧表条目 / E2 官方声明 / 探针校准回填 | `S3/E1|E2/分歧表族N + musl 版本锚 + 版本核对: V_dev=… ✓` |
+| S4 宿主实测 | 宿主实际值（须过闸A/闸B） | `S4/host/宿主实测 <命令> → <值>` |
+| S5 行为级 | 「非零」「失败且不崩溃」 | `S5/n-a/行为级`；**UB 禁用；L0 禁用** |
+
+**证据等级**：E1=设备实测 / E2=官方声明（存在性可定案、行为初筛）/ E3=上游 musl 源码（**永不定案**）/ host=宿主实测 / n-a=属性或行为级。
+**合法 source-grade 组合**：S1→n-a、S2→n-a、S3→E1|E2、S4→host、S5→n-a。S3/E2 仅限存在性类定案。
+
+**版本锚核对（源3 固定子步骤，E2/E1 引用定案前必过）**：
+```
+① 取 V_doc（条目版本锚/条目 fingerprint）
+② 取 V_dev（00-env.json device_fingerprint OS 版本 → 版本链换算：1.2.0@4.0→1.2.3@5.0→1.2.5@6.x）
+③ V_dev 与 V_doc 覆盖同一版本段 → 定案有效；不同段/无 fingerprint → 降探针校准或行为级
+```
+ref_note 必须留 `版本核对: V_dev=1.2.3 ✓`（presence 扫描，语义人审）。
+
+**宿主实测授权（闸A/闸B）**：观测物库自有（不经过 libc）→ 任意宿主可 S4；经过 libc → 宿主 libc 族在分歧面覆盖表内才可作 A3 参照，表外（ucrt/bionic）禁止拿宿主值当设备预期。
+
+## 差异面探针校准（S1 钉值落平台差异面时的定案通道）
+
+**要解决的问题**：S1 钉的是 PRD 在上游语义下的预期值。观测物落平台差异面（浮点跨架构舍入 SSE vs NEON、errno、本地化、文件语义、时序）时，该值在设备上可能不同——宿主自证发现不了（Windows 宿主 ucrt 本身在闸B 表外，宿主值与设备值**都**≠PRD 值），机扫也拦不住（S1+n-a 合法组合直接放行）。漏网的代价被归因契约放大：S1+宿主绿+设备红 → 自动归因产物缺陷 → 阶段3 修产物修不到 → 烧完有界环才翻案。
+
+**触发决策树**：
+```
+这条断言的观测物经过 libc / 平台语义区（闸B）？
+├─ 否（闸A：纯计算/库自有）→ 不需要探针：S1 保值 或 S4 宿主参照+tolerance
+└─ 是 → 宿主值被禁（尤其 Windows 表外宿主），必须从设备侧拿真值：
+    ① 查分歧表 → E1 条目命中且 fingerprint 同设备？命中 → 引用 E1（不需探针）
+    ② 分歧表未命中 → 查 E2 官方文档 → 命中且版本锚核对通过且存在性类 → E2 定案
+    ③ 两处都未命中 → ★触发探针（禁止臆断：musl 文档/源码都不算数）
+    ④ L0 功能点走到底要落 S5 → 回修一轮，重查五源时 ★触发探针
+    ⑤ 宿主自证升格：闸B 观测物宿主值稳定想升格 → ★触发探针拿设备值对照
+```
+一句话判据：**观测物落闸B ＋ E1/E2/S4 三个现成来源有一个给不出 → 探针是唯一合法定案路径。**
+
+**跳过条件（合法省略，二分语义）**：设备不在位 → 省略探针，降行为级 + `分诊:` 留阶段3（或 S3/E2-待复验）；闸A 观测物 → S1/S4 + tolerance 足够；`ohpt-agent knowledge -s` 检索命中同 musl 版本段的既有探针结论 → 直接引用（跨库复用）。**引用了探针结论/E1 声称而无证据文件 = 假承诺**，`roster-probe-evidence-exists` 点名。
+
+**探针操作（最小闭环）**：clang 直链编译最小 C 程序（单断言单值，不依赖库自身构建系统）→ `hdc file send` 推设备 → `hdc shell` 执行 → 抓 stdout 值。**划界**：探针 = 单断言预期值校准，不是用例执行（不进名册、不占 device_budget 分母）、不是载体（不装 HAP、不走 OHPTCASE）、不是运行期归因（阶段3 只读结论）；秒级，与设备租锁无交叠。操作细节见 pc-knowledge-base「鸿蒙PC-最小真机探针校准」。
+
+**三向对照与回填**：结论 = 上游期望系 / musl 推导 / 设备实测 三向对照，落工作区 `knowledge/`（E1 待审，绑 device_fingerprint + musl 版本锚）；oracle_plan 回填二选一——S1 → S3/E1（ref_note 记 `探针: <knowledge/probe-xxx.json>`）或加 `tolerance: { metric, eps }`（实测值 ± 容差带）。结论经 04-summary promote 跨库复用，永不直写包内分歧表。
+
+**差异面论证义务（执法 `roster-pin-evidence-gap`）**：S1/S4 钉精确值 → ref_note 必须三选一：`差异面: 无（闸A，库自有观测物）` / `差异面: 有 → 探针: <path>` / `差异面: 有 → E1/E2: <分歧表族N|官方条目>`。**三样都没有 = 点名**（"钉了精确值却没论证为什么跨平台必然一致"）。agent 可以判错（把闸B 说成闸A），但不许沉默。
+
+## 指纹链（tests_generated_hashes → state_fingerprint）
+
+阶段 2 名册定稿时对 `tests-generated/` 全文件算 sha256 存 `02-baseline.tests_generated_hashes`（存档 1）；verify 每次验收通过重算全量指纹写 `verify-verdict.state_fingerprint`（存档 2）。每轮固定核对：当前指纹 == 上一份 verdict 指纹？不一致 → 逐文件 diff——有 failures 条目 + fixed-test + amendment 申报 → 合法进内容审查；无申报 → 静默改动实锤判 false（执法 `verify-testcode-fingerprint`）。上游源码侧已有防护（补丁可逆性 reverse-apply、git 状态核验）不变。
+
+## 归因置信度契约表（阶段 3 分诊路由输入）
+
+oracle_plan 的 source/grade/host_result 组合 = 阶段3 分诊路由输入：
+- S1/S3-E2/S4-host + 宿主绿 + 设备红 → 自动归因（S1 对照 PRD evidence；S3 核版本核对与分歧表；S4 高置信产物缺陷）
+- **S5 + 设备红 → 人工三向对照（路径 = ref_note `分诊:` 预告）**
+
+## 异常场景预期精度裁决
+
+跟 **oracle 来源**走，不跟场景类别走：
+- E2 命中（受限接口清单）+ 版本核对通过 → 钉精确 errno 是义务（EACCES/ENOENT/EPERM）
+- E2 命中核对不过 → 行为级 + ref_note 标「复验」
+- 未命中 → 行为级（五源取不到不许钉值）
+- **行为级是兜底档不是默认档**：有出处而写行为级 = 故意放弃证据强度。
+
+## 参考
+
+- 断言观测层 plane（oracle_plan[].plane 层地板语义）→ `02-baseline.schema.json` 的 plane description 为权威；机判表 PLANE_EVIDENCE 在 lib/verification-policy.ts
+- 执法规则（acceptance-checks，命中即点名）：`roster-l0-gap-ledger` / `roster-assertion-four-clarify` / `roster-assertion-symbol-floor` / `verify-testcode-fingerprint` / `roster-assertion-provenance-tier` / `roster-symbol-budget` / `roster-device-budget` / `roster-p0-hard-assert` / `roster-api-ref-observable` / `roster-prd-ref-verdict-linked` / `roster-family-exception-path` / `roster-pin-evidence-gap` / `roster-probe-evidence-exists` / `roster-blocked-upstream-coverage` / `roster-blocked-upstream-symbol-coverage`
+- 判定句粒度 / 断言出处红线 / 渲染二分法 / 对偶可达红线 → `pc-test-design`（测试线侧规则照旧，本 skill 只管阶段 2 生成侧）
+- 键值码表：PORTING_KIT.md（pc-capability-domains）；探针操作知识：pc-knowledge-base「鸿蒙PC-最小真机探针校准」

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/assertion-authoring.md

@@ -0,0 +1,80 @@
+---
+description: 断言写作五步法全文与预期钉值纪律：定对象→取预期（五源表+四澄清）→找佐证→判差异面（闸A/闸B）→选形态；预期四澄清表（类型/单位/结构/失败形态，跨五语言形态配平）；S2 关系失效前提表（往返/守恒/幂等/单调/等价表示）；设计期质量红线。触发词：断言五步、定对象、取预期、找佐证、判差异面、选形态、四澄清、澄清、类型歧义、单位歧义、结构、失败形态、errno、哨兵值、S2 前提、roundtrip 前提、守恒前提、幂等前提、单调依据、等价表示、oracle_plan、一句一判、ref≥symbol。
+---
+
+# 断言写作五步法与预期钉值纪律
+
+**执行时点**：粒度判定（三问）定完边界**之后**，逐 checkpoint 过一遍。粒度判定见
+`case-granularity.md`（拆留三问的权威）——先判边界再写断言。
+
+## 五步法
+
+```
+1. 定对象：这条 cp 判定哪个符号的哪个行为？（symbol 字段，一句一判）
+   禁一句多判（rttr 实证：合并判定暴露静态半边从未真测）
+2. 取预期：五源表，S1 优先——PRD checkpoint 有没有现成可判定预期？
+   反例：「返回正确结果」——PRD 没写清 → 回修阶段 1，不许脑补
+   正例：「小于所需值返回 false、恰好返回 true」（PRD 钉了边界语义）
+   钉值前过四澄清（见下）
+3. 找佐证：ref_note 给 file:line（PRD evidence / 上游测试基线 / 官方文档）
+4. 判差异面：观测物走闸 A（库自有，不碰 libc）还是闸 B（经过 libc/平台语义区）？
+   闸 B 且无现成 E1/E2 → 真机探针定案，不许沉默（可判错，不许不论证；见 SKILL §探针校准）
+5. 选形态：精确钉值 / 序关系 / 行为级——能用序关系就不用浮点精确值，
+   能钉值就不留行为级。L0 禁 S5（「非零/不崩溃」连空 stub 都能 PASS）
+```
+
+每条断言落 `oracle_plan[] = {ref: cp:N, symbol, source, grade, plane, ref_note}`（schema 字段契约
+见 02-baseline.schema.json 的 oracle_plan description）。
+
+## 预期四澄清（钉值前的歧义消解，步骤 2 的固定子步骤）
+
+各交付形态通用，澄清的是**该 API 的约定**而非某语言语法，结论写进 ref_note
+（`澄清: 类型=… 单位=… 结构=… 失败形态=…`，`roster-assertion-four-clarify` 执法 presence）。
+
+| 澄清项 | 问什么 | 跨形态实例 |
+|---|---|---|
+| 类型 | 返回值/输出参数代表什么？void/None/undefined/Unit 不能判非空；数字与字符串真等价吗 | C 指针 / Python None / Rust Option / Node undefined / Java null 装箱 |
+| 单位 | 秒/毫秒、字节/字符/元素、长度含不含终止符 | C 字节缓冲 / Python str vs bytes / Node UTF-16 code unit（中文长度陷阱）/ Rust String vs &[u8] |
+| 结构 | 记录/列表/嵌套对象的关键语义字段；不用另一版本的结构替代 | struct 布局 / dict 键名 / 接口版本 schema / POJO 字段 |
+| 失败形态 | 错误码/异常/空值/哨兵值——哪个是本版本公开约定 | C errno+返回码 / Python exception vs None / Rust Result::Err vs panic / Node throw vs reject vs 错误回调 |
+
+**为何前移**：这四项在旧流程里是**设备红之后**由 platform-divergence 分诊补做（libunistring 71 条
+wchar 失败全是字符/字节语义、libbsd strtoi ECANCELED vs EINVAL 是失败形态未澄清）；钉值前澄清，
+此类失败根本不发生。
+
+## S2 关系失效前提（免出处 ≠ 免论证）
+
+S2 属性断言 ref_note 必须带 `属性: <关系>（前提: …）`（`roster-assertion-four-clarify` 执法 presence）。
+前提写什么，按关系查表：
+
+| 关系 | 失效模式（不核对即假通过） |
+|---|---|
+| 往返一致 | 编码/解码**共享错误路径**时两边一起错、往返照样一致 → 关键场景配已知样本；对偶 API 存在之外还要查路径独立 |
+| 守恒 | 分项与总量**不同源不同单位**——"拿同一缓存值自证"（读回自己刚写的缓存不是守恒验证） |
+| 幂等 | close/free/destroy **不自动幂等**——先核对契约声明幂等，二次释放不当地正常场景 |
+| 单调 | 不凭"看起来应该"推导——单调性必须有契约依据 |
+| 等价表示 | 不默认数字字符串与数值、path 与 URI 通用——契约声明等价才等价 |
+
+## 设计期质量红线（落盘前逐条自查，三条带实证的都是已发生过的假用例形态）
+
+- **导出面核对**：补写用例调用的每个 API 符号必须 ⊆ `api_surface` 的 `header_declared` 或
+  `declared` 集合，且构建系统会安装它（`include_HEADERS`/`PUBLIC_HEADER`/安装集）。调不存在的
+  API → 编译即失败，不入名册（libetpan 实证：6/16 调用 `maildir_new`/`mailmh_new` 等
+  不在导出面的符号）。
+- **禁绝对路径 / 宿主路径假设**：不得硬编码 `/tmp`、`/var/tmp`、`/etc`；临时目录一律经
+  `TMPDIR` 环境变量获取（`mkdtemp(getenv("TMPDIR"))`），上层 runner 注入沙箱可写目录
+  （libetpan 实证：4/16 生成用例 `mkdtemp("/tmp/libetpan-...")` 在设备上必失败）。
+- **宿主语法级冒烟**（可选，看宿主编译器）：`clang -fsyntax-only` 过一遍前端解析，确认无
+  隐式声明/类型错误——不求链接过，只求语法正确。
+- checkpoint 一句一判、具体可判定；黑盒表述、平台无关
+- 行为路径断言先宿主验证可触发（host_probe 对拍）；往返/对偶断言核对对偶 API 存在
+  （对偶可达红线的权威在 `pc-test-design` §九）
+- UB 类操作预期只写平台确定性处置（「不崩溃」不是合法预期）
+- **断言符号下限（ref≥symbol，兜底执法）**：len(distinct oracle_plan.symbol ∪ 声明支持性) ≥
+  len(covered_apis_source)——声明支持性 = observable_via[].symbol 显式声明（占比 ≤50%）；
+  口径两端 distinct（同 symbol 多行为断言合法，多 cp 验 1 symbol 不违例）；上游用例豁免
+  （`roster-assertion-symbol-floor` 执法；42 库实测 41% 用例有"17 API 5 断言"形态）
+
+## 对齐样例
+
+basis_universal 的 02-baseline（16 用例 87 条 oracle_plan，多行为同符号、序关系断言、闸 A 论证的完整实例库）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/budget-and-coverage.md

@@ -0,0 +1,71 @@
+---
+description: 覆盖核销与预算判据（L0-only 补写口径）：补写范围由补写用例集承接（L0 API 粒度）、覆盖证据两档（强档机扫 / observable_via 弱档声明 + L0 恒强档）、断言符号下限、L1/L2 缺口登记义务（cap-out 台账）、设备预算。触发词：覆盖核销、强档、弱档、observable_via、verdict_ref、L0 恒强档、L1 L2 登记、cap-out、cap-out-ledger、设备预算、device_budget、降级阶梯、degraded、ref≥symbol。
+---
+
+# 覆盖核销与预算（L0-only 补写口径）
+
+**口径前提**：本方案的补写范围 = **只补 L0**（补写用例集 gap-ledger 承接，见 `gap-ledger.md`）。
+上游用例全量收编提供广度，L0 缺口补写提供深度兜底。本文件包含：两档覆盖判据、L1/L2 登记义务、设备预算。
+
+## 1. 覆盖证据两档判据
+
+每个 api_refs 符号必须按两档之一提供覆盖证据：
+
+- **强档（机扫）**：符号名字面出现在本用例断言表达式/证据行锚点。`roster-api-ref-observable` 主执法。
+- **弱档（显式声明+人审）**：`observable_via: [{ symbol, via_symbol, verdict_ref }]`。三道机扫
+  结构检查（symbol ∈ api_refs / via_symbol ∈ api_surface / verdict_ref 可达）+ 一道人审
+  （verdict_ref 必须是失败传播路径——"symbol 失效该判定行会红"）。弱档占比 >30% 告警。
+- **L0 恒强档**：L0 符号只认强档，弱档声明不采信——L0 是补写的核心盘，"经过别的符号可见"的
+  弱声明在这里没有生存空间。
+- **配对推理不在机扫范围**：get_/set_ 命名启发式仅供人工抽查。
+
+弱档声明与 `roster-assertion-symbol-floor` 的"声明支持性"是同一批字段（observable_via）——
+声明一次，两处消费。
+
+**断言符号下限（ref≥symbol，兜底执法）**：len(distinct oracle_plan.symbol ∪ 声明支持性) ≥
+len(covered_apis_source)；支持性占比 ≤50%（防整条用例全是挂名）。详见
+`assertion-authoring.md` 的红线节。
+
+## 2. L1/L2 缺口登记义务
+
+**补写范围 = 只补 L0**——机制上由流程保证：pc-02 步骤 3 是**唯一的范围裁决点**（L0 进
+gap-ledger.json、L1/L2 未覆盖符号同步登记 cap-out 台账，两个 JSON 白纸黑字），步骤 4 **写哪些**
+只读 gap-ledger.json（disposition ∈ {full-case, gap-case} 的条目），不在清单内的功能点不写用例；
+**怎么写**照常回 PRD checkpoint/evidence 与源码取证据（范围封闭 ≠ 证据封闭，S1 入口不受影响）。为什么只补 L0：
+- 上游全量收编已经提供广度（42 库实证 10.4:1 的上游:补写条数比）；L1/L2 的功能等价性
+  由存活上游用例覆盖，设备红时归因链（六值分诊）会暴露真缺口
+- 补写用例没有 CI 背书，每条都要走断言五步法 + 宿主自证 + 阶段 3 修到过——范围外补写 =
+  阶段 2/3 工作量激增，换来的只是 feature_coverage 数字好看
+
+L1/L2 功能点的缺口不补写、在步骤 3 登记——静默缺口在两个锚都被点名：
+
+- **符号面**：符号 ∈ api_surface 却无任何名册用例覆盖 → `baseline-roster-anchored` 现算点名
+  （uncovered 如实列，不许为凑 planned 手写空集）。
+- **功能面**：L1/L2 功能点无名册用例覆盖 → `feature_coverage.uncovered` 如实列（合法终态，
+  不是要消除的缺口），登记 cap-out 台账（`.ohos-adaptation-pc/cap-out-ledger.json`）承接：
+
+```json
+{"entries":[{"symbols":["g_string_free"],"family":"g_string","representative":"g_string_append","tier":"L2","reason":"…"}]}
+```
+
+- 台账是**自报豁免通道**，规则层对账（`roster-symbol-budget`）：条目符号必须 ∈ api_surface.symbols
+  （存在性）；**L0 符号写进台账无效**——L0 只能走 gap-ledger 的 disposition（补/申报/scope_out），
+  台账承接不了 L0；条目符号不在 api_surface 里会被点名。
+- 台账是 L1/L2 缺口的正常归宿——"全补了就不需要台账"是把义务当选项。
+- L1/L2 缺口登记不拦 planned（planned 判据只看 L0 层归零——补写用例集 + 台账一起看）。
+- 上游收编变化下最可能的 L1/L2 缺口来源：上游剔除步 blocked 剔掉的用例独有的符号/功能点
+  （`roster-blocked-upstream-coverage` / `-symbol-coverage` 两锚闭环执法：剩余载体或留账，
+  否则不许 planned）。
+- 认为某个 L1 功能点级别判错（应升 L0）→ 回报走阶段 1 修订，不自行补写。
+
+## 3. 设备预算
+
+`device_budget: { cap_min(默认20), estimated_min, degraded[] }`，验收 `estimated_min ≤ cap_min`。
+名册含 generated 用例 → 必填（D3 条件）；纯 upstream 名册 optional（上游 CI 背书即 provenance）。
+
+超限触发降级（不静默砍主覆盖，逐层记 degraded[]）：
+① L0 用例**不降**（补写范围已经是最低盘）→ ② 上游长尾套件采样（按套件/分组截选集，official
+选集仍一字不改可复跑）→ ③ 上报 meta.warnings 人工裁决。
+
+降级与超限双向绑定：超限必附 degraded[]；未超限有 degraded[] = 无依据降级
+（`roster-device-budget` 执法）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/case-granularity.md

@@ -0,0 +1,95 @@
+# 粒度轴与生成清单派生（阶段 2 生成侧）
+
+> 辖区：`pc-02-dev-test-cases` 生成用例时的**用例边界判断**与**生成清单派生**。拆分判据①、
+> 渲染验证二分法、对偶可达红线的**权威**在 `pc-test-design`（§一/§六/§九）——本文只写
+> 生成侧增量与 pc-test-design 没有的判据，不复制权威内容（同一知识点只有一个权威归属）。
+> 方法论出处：补写用例生成体系方案文档 §2.1 粒度轴 / §3.4 六面核销 / §四步骤3。
+
+## 一、API 级组合的拆/留三问（设计期逐组合结论走，按序问到即停）
+
+一个功能点的验证链经过多个 API 时，用例边界按三问定：
+
+1. **组合结论能拆成各自独立成立的结论吗？** 能 → 拆（拆后每条各自走五源表 + 判定链可观察）。
+   判据与功能点级拆分**同源不同粒度**：功能点级看"能力会不会各自独立地坏掉"（`pc-test-design` §一），
+   API 级看"这条结论能不能不依赖另一条调用而独立成立"。
+2. **拆开后剩下的关系结论有单边意义吗？** 没有（相等/顺序/还原类纯关系）→ 留在一条用例；
+   落盘格式强制：**每步一行单对象判定（各占独立 `[cp:N]` 锚点）+ 末行关系判定单独成行**
+   ——禁"还原成功"式单行空判定（anti-fake 名录老病：单行判定既不证明 write 对也不证明 read 对）。
+3. **输出依赖调用顺序吗？** 依赖 → **必须序列级一条用例**（共享进程/前置），禁拆成互不相干的单调用用例
+   ——序列被拆后各条单跑都可能绿（状态残留假绿），阶段3 真机才暴露，且会被归因契约表
+   （SKILL §归因置信度契约表）自动归因"产物缺陷"——错怪库。序列级用例把自身各步登进 `blocked_by`，
+   中途步失败归因"前置步"而非产物。
+
+## 二、三种前置，记账不同（生成骨架时逐前置归类）
+
+| 前置类型 | 例子 | 记账 |
+|---|---|---|
+| **载体环境前置** | 起屏幕、创建 window/GL 上下文、装 HAP | 不进 `prd_refs` 不占分母；失败 → 整组 blocked，`blocked_by` 登记并归因"载体前置失败"，阶段3 不重诊断库 |
+| **库功能点前置** | 先"开始下载"再测"断点续传" | 步骤带独立判定行才可挂 `prd_refs`；依赖链登记 `blocked_by`（归因从运行期前移到设计期） |
+| **纯铺路** | 只是"走到位"，无独立判定价值 | 不挂，该功能点仍需自己的用例 |
+
+登记形态：`blocked_by: string[]`（schema description 为权威——载体前置失败与功能点前置依赖都可登记）。
+
+**依赖链前置归因的推导**（步骤 5 补写时逐用例走一遍）：哪些**其他功能点**的 API 出现在本用例的
+非判定步骤里 → 把那些功能点 id 登进本用例 `blocked_by` 候选。真机轮前置功能点挂 → 本用例直接
+归因 blocked-by，不烧分诊。
+
+**记账防虚高**（方案文档 §2.1 组合三规则 1）：`prd_refs` 只挂"在本用例里有自己判定行"的功能点。
+判据一句话：**把这步骤的判定行拿掉，对应功能点还剩独立判定吗？没有 → 不许挂。** 两条机扫护栏
+（`roster-prd-ref-verdict-linked`）：prd_refs **不跨模块**（同用例的功能点必须同 module——跨模块
+挂 refs = 覆盖分子好看、验证目标只有一条）；prd_refs **>2 软护栏**（超限逐个核上述判据，合法
+多行判定集中在关系判定的少量步骤内，超 2 条大概率是凑覆盖）。
+
+**独立构造路径优先**：能独立测的功能点不挂链（usbredir 实证：改走降级构造路径 7/21 blocked →
+24/24 pass）。本质不可独立到达的（状态链型，如"暂停后恢复"）才允许链，且 setup 链选最短——
+链条每长一节，blocked 传播面大一分。
+
+## 三、实现手段 vs 横切属性（组合结论的记账归属）
+
+判据一问：**这个组合结论，是 PRD 认领的一个用户能力，还是"库表现得正常"的横切性质？**
+
+- **实现手段型**（PRD 认领，如"写入后读回一致"）→ 主用例群：1 用例多步执行（按 §一三问定边界），
+  占功能点分母，预期值要 PRD 证据（S1）。
+- **横切属性型**（幂等/守恒/确定性，PRD 没有）→ 宿主用例的**后缀断言**（基线证据纪律：printf 实际值 + [cp:N] 锚点 + 整行比对 + AND 契约），不占功能点分母；属性断言免出处（逻辑必然，S2/n-a）。
+
+分类跟着 PRD 走，不跟测试作者口味走：同一个 roundtrip，阶段1 写进了 features → 实现手段型；
+没写 → 横切属性型。
+
+## 四、输入域实例化（每条用例的确定性输入向量）
+
+- **normal** → 稳定可复现代表值（"合法域名"具体化成钉死的字符串）。
+- **boundary** → **跨边界改变可观测行为的值对**（max 成功 / max+1 失败），不是随便取中间值
+  ——取中间值的边界用例永远绿，什么都没验到。
+- **exception** → 无效等价类，多条同型非法值合并一个步骤（数量上限约束下的合法合并）。
+- 枚举 ≤5 全覆盖 / >10 取代表值（首、末、缺省、特殊）；等价类/边界值/判定表的方法本体见
+  `pc-test-design/references/case-design-methods.md`（权威，不复制）。
+- 注入类键值出自 PORTING_KIT 2000 段码表（凭直觉写键值 = 设计期埋必挂用例，SKILL §注入事件组合用例 同款）。
+
+## 五、状态面 / 属性面生成清单派生（补写不只是填 uncovered 差集）
+
+符号面 uncovered 求差之外，以下功能点**强制进生成清单**（派生自 `prd.features[].observable_paths`）：
+
+- **状态面**：有状态机的功能点，非法迁移路径（未初始化就用 / 销毁后再用 / 重复 init）各 ≥1 条
+  exception 用例——uncovered 差集抓不到它们（正常路径已覆盖时 uncovered 为空，非法路径仍缺）。
+- **属性面**：有配对 API 的功能点 ≥1 条 roundtrip（**对偶 API 存在性先核** `pc-test-design`
+  对偶可达红线——对偶不存在就别造 roundtrip）；纯函数 ≥1 条确定性核验（出处义务按
+  `assertion-authoring.md` 五源表；roundtrip/幂等属 S2，前提表同文件）。
+
+## 六、渲染类用例生成侧动作（图形/GL 库 generated 场景）
+
+**判定**：补写用例 checkpoint 含上屏语义（显示/渲染/绘制/颜色/刷新）→ 渲染类。
+渲染验证 vs 数据验证二分法、两层证据（像素读回 + 真上屏人工判定）的**权威在 `pc-test-design` §六**——本节只写生成侧动作：
+
+1. **surface 留痕**：结果行带 `surface=window|offscreen`（真上屏 / 离屏读回）——像素断言通过
+   不构成上屏证据，两层缺一不可。
+2. **观测层挂账**：oracle_plan 对应条目 `plane=screen`（层地板：terminal 走
+   buffer-assert / gui 走 demo-verify 渲染记录）。
+3. **可对拍分级**：按 02-baseline.schema.json 的 plane_probe——screen-terminal/log/environment 宿主有等价管线
+   先对拍；**screen-gui 宿主无等价管线**，不声明 plane_probe、勿伪装自证，真机首跑取证；
+   写不出宿主对拍的强像素断言落人判（human-visual），禁硬造机器断言。
+
+## 参考
+
+- 拆分判据①（功能点级）/ 渲染二分法 / 对偶可达红线 / 等价类方法本体 → `pc-test-design`（§一/§六/§九/references/case-design-methods.md）
+- 断言预期值五源 / 归因契约表 → 本 skill SKILL.md §预期值五源决策表 / §归因置信度契约表；观测层 plane → 02-baseline.schema.json 的 plane description（权威）
+- blocked_by 登记形态权威 → `02-baseline.schema.json` 的 `blocked_by` description

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/combination-patterns.md

@@ -0,0 +1,30 @@
+---
+description: 非注入组合用例的五骨架选型库：实例隔离、运行中配置更新、中途失败恢复、重复重入、持久化跨界。每骨架 = 操作骨架 + 判定要点 + 库适配场景实例。与注入形态（injection-combination.md）的路由二分。触发词：组合骨架、实例隔离、A→B→A、运行中配置更新、中途失败恢复、重复重入、持久化跨界、重读、公开读取入口、组合用例、状态残留、非注入组合。
+---
+
+# 组合用例骨架库（非注入组合）
+
+**组合用例的路由二分**：断言目标需要注入外部输入事件才可观测 → 注入形态（见
+`injection-combination.md`）；**跑完即得的组合结论**（多 API 协作完成一个使用目的，数据自己
+能到 stdout）→ 本文件的五骨架选型。
+横切属性（幂等/守恒/确定性，PRD 未认领）→ 后缀断言，不占功能点分母（记账归属判据见
+`case-granularity.md` §三）。
+
+## 五骨架
+
+| 骨架 | 操作骨架 | 判定要点 | 库适配场景实例 |
+|---|---|---|---|
+| **实例隔离** | 同时建立 A/B 两实例 → 只操作 A → 观察双方 | 输出与状态各自归属——B 的输出/状态不受 A 操作影响 | 两个连接 / 两个解码器并行：各自配置、各自输出 |
+| **运行中配置更新** | 同一实例 A→B→A，每步观察（不重建实例） | 配置真实生效、无旧状态残留——第二步的输出证明 B 生效，第三步证明 A 能回来 | SDL_image 状态污染的用例级预防：换格式→换回→再输出 |
+| **中途失败恢复** | 正常资源 → 坏资源 → 观察错误归属 → 恢复 → 再完成真实功能 | 区分"正确拒绝"与"功能永久失效"——坏资源只产生当次错误，恢复后功能照常 | rabbitmq 恢复场景：坏消息 → 错误返回 → 正常消息 → 照常收发 |
+| **重复/重入** | 完成一次 → 再执行 → 观察末态 | 资源/监听不残留、行为符合公开约定（第二次与第一次结果一致或契约声明的差异） | mmap_allocator keep_forever_reuse；二次 init/finalize 成对 |
+| **持久化跨界** | 保存 → 关闭/重进 → **经公开读取入口**重读 → 删除后重开 | 不回显写入缓存冒充读取——必须走被测的公开读取路径（与对偶可达红线互补） | 配置文件保存重读；数据库 commit 后新连接查询 |
+
+## 使用纪律
+
+- 骨架是**选场景工具箱**，不是数量配额——某骨架对本功能点无可区分观察就不选，不要为了凑形态硬套
+- 判定行逐一落到每个协作参与者的行为上（禁"压缩成功"式单行总判定——四 API 协作的用例
+  每步一行单对象判定 + 末行关系判定，格式权威见 `case-granularity.md` §一）
+- 组合结论记账归属（实现手段型 vs 横切属性型）按 `case-granularity.md` §三：PRD 认领的组合能力
+  占功能点分母（S1 证据），未认领的横切属性走后缀断言（S2 免出处不免论证）
+- 序列依赖（输出依赖调用顺序）用例把自身各步登进 `blocked_by`——中途步失败归因"前置步"而非产物

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/gap-ledger.md

@@ -0,0 +1,107 @@
+---
+description: 定补写用例集的五步法（gap-ledger 承载）：L0 功能点 × API 的补写范围判定——建账、记触达账（只读剔除产物）、三分类、supporting 申报、对账钩子。判定粒度是 API 缺口不是功能点有无。触发词：gap-ledger、补写用例集、缺口账、建账、触达账、touched_apis、gap_apis、三分类、full-case、gap-case、covered、supporting 申报、静默缺口、Hook 三查、roster-l0-gap-ledger。
+---
+
+# 定补写用例集（gap-ledger）：补写范围的 API 粒度判定
+
+**要解决的问题**：补写范围以"功能点有无"判定会漏网——功能点标"上游覆盖"≠ 其 API 全被覆盖
+（42 库实测：697 个已覆盖功能点中 235 个有 API 漏网，HiGHS F-08-02 四回调 API 仅触达 1）；
+部分剔除后剩余用例也未必触达全部 API。**判定粒度是 API 缺口，不是功能点有无。**
+
+**产物**：`.ohos-adaptation-pc/gap-ledger.json`——键 = 功能点 id，值 = 补写范围条目
+（文件名 gap-ledger 保留，全链统一叫"补写用例集"）。
+落 `02-baseline.gap_ledger_ref` 引用；`roster-l0-gap-ledger` 执法对账；planned 判据消费本账（L0 层归零）。
+
+## 五步
+
+**无套件捷径**（上游剔除步判定"无测试套件"时）：跳过第 2 步（触达账恒空），第 3 步三分类
+塌缩为全部 L0 = full-case——整条流程只剩"建账 → 全 full-case → 落盘"。
+
+### 第 1 步：建账（底账）
+
+从 01-scan.json 读 `prd.features[]`，过滤 `level=="L0"` 且非 scope_out，每点提取
+`covered_apis.source` 作全量 API 集（`all_apis`）。落文件骨架：
+
+```json
+{
+  "F-08-02": {
+    "level": "L0",
+    "all_apis": ["highs_setCallback", "highs_clearCallback", "highs_getCallback", "highs_userCallback"],
+    "touched_apis": [],
+    "gap_apis": [],
+    "disposition": "full-case",
+    "supporting_reason": "",
+    "supporting_apis": []
+  }
+}
+```
+
+### 第 2 步：记触达账（只消费上游剔除产物，不重复判定）
+
+```
+遍历 02-baseline 的 source==upstream 条目：
+  platform_exclusive == true        → 跳过，不记账
+  executability.verdict == blocked  → 跳过，不记账
+  其余                              → 对每条 prd_refs[F]：
+                                        ledger[F].touched_apis ∪= (api_refs ∩ F 的 covered_apis)
+```
+
+- 排除的"为什么"上游剔除步已裁定，此处只读字段——触达账与剔除裁定**同源零漂移**
+- 字段缺失的用例（旧版产物）不许自行补判 → 挂起"待分诊"，回填上游剔除步重走
+- api_refs 与 covered_apis **求交集再记**（内部符号/框架符号不虚增触达集）；
+  一条用例挂多个 prd_refs 时记到每一个被挂功能点（保守记账，缺口只少报不虚报）
+- 触达集 ⊆ all_apis（越界会被 roster-l0-gap-ledger 点名）
+
+### 第 3 步：算缺口，三分类（定每点怎么补）
+
+```
+缺口 = covered_apis.source − touched_apis
+A 整点空白：touched = ∅           → 补完整用例（disposition=full-case，covered_apis_source = 全量）
+B 部分缺口：touched ≠ ∅ 且缺口 ≠ ∅ → 补缺口用例（disposition=gap-case，covered_apis_source = 仅缺口 API）
+C 无缺口                          → 不补写（disposition=covered）
+```
+
+### 第 4 步：无行为契约的缺口 API 申报 supporting
+
+B 类缺口 API 逐个判断：**纯前置/清理/参数准备且自身无可观测行为契约**的，可申报 supporting
+（带 reason，逐个列 `supporting_apis[]`）。
+
+约束：
+- supporting 占该功能点缺口 **≤50%**（过半 = 核心行为大概率没被判定，人工复核）
+- 未申报又未补写的缺口 = **静默缺口**，对账逐个点名——缺口允许存在（补或申报），不允许沉默
+
+### 第 5 步：对账钩子（Hook 三查，不过则补写设计不许开跑）
+
+1. 每个 L0 功能点都有 disposition（四值之一：full-case/gap-case/supporting/covered）
+2. gap-case 用例的 `covered_apis_source` 与 `gap_apis` 一致（gap-case 只补缺口；全量重补请改 full-case）
+3. supporting 占比 ≤50%
+
+## 消费关系（谁读这份用例集）
+
+| 消费者 | 读什么 |
+|---|---|
+| 补写用例（pc-02 步骤 4） | **写哪些以本文件为准**：只写 disposition ∈ {full-case, gap-case} 的功能点；不在清单内的功能点不写（级别判错 → 回报阶段 1 修订，不自行补）；清单内每条照常回 PRD/源码取证据（范围封闭 ≠ 证据封闭） |
+| `roster-l0-gap-ledger` | 三查 + 静默缺口点名 + 触达账越界点名 |
+| `baseline-roster-anchored` planned 口径 | planned ⇔ 每个 L0 功能点 disposition ∈ {covered, full-case, gap-case}（L1/L2 缺口走 cap-out 台账不拦 planned） |
+| 04-summary | L1/L2 缺口登记情况（cap-out 台账 + gap-ledger 联合看） |
+
+**L1/L2 功能点**：不建账，也不为它们补写用例——补写用例的唯一来源是本文件落盘的
+gap-ledger.json（why 见 `budget-and-coverage.md` §2）。L1/L2 功能点无覆盖 →
+`feature_coverage.uncovered` 如实列（合法终态，不是要消除的缺口）+ cap-out 台账在步骤 3
+一并登记承接；认为某个 L1 功能点级别判错（应升 L0）→ 回报走阶段 1 修订，不自行补写。
+
+## 关模式（generated_backfill=off）
+
+注入的 `generated_backfill` 为 false 时的二值判定（无中间态，不按功能点挑）：
+
+```
+第 1 步产出里存在存活上游载体（source=upstream 且 platform_exclusive≠true 且 executability≠blocked）？
+├─ 是 → 一条都不补：不落 gap-ledger.json，跳过补写步；
+│       02-baseline 落 meta.generated_backfill=false（豁免标记，roster-l0-gap-ledger 据此豁免账缺失告警）
+└─ 否（上游用例不存在或全被剔除）→ 全部 L0 = full-case，正常落账并补写（= 无套件捷径原样生效）
+```
+
+- 判定**整体相燃**：不按功能点逐个挑"这条有没有被挂"——那是开模式（API 粒度）才做的事。
+  关模式+存活上游下，L0 功能点里上游未触达的 API 洞不记录（不为不打算修的洞记账）。
+- 账的 schema 形状不变：关模式落账的形态（全 full-case）与无套件捷径完全一致，三查照走。
+- 与无套件捷径的关系：关+无存活 = 捷径原样生效，不是第三条路。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/host-selfvalidation.md

@@ -0,0 +1,71 @@
+---
+description: 宿主自证的完整执行纪律：构建通道选择序（构建系统宿主通道→库产物链接→手搓桩）、编译器探测做全（6 库假阴性教训）、三结局处置表（ran/fail/unavailable）、no-op 骨架对照（拦"精心写的恒真"）、用例退出纪律（fflush+_exit）、单用例预算标注、可信度三档（Hook 推导，agent 无权自封）。触发词：宿主自证、构建通道、手搓桩、gcc+ar、build-once、编译器探测、msys64、ucrt64、VS BuildTools、假阴性、no-op 对照、断言架空、骨架影子、恒真、退出纪律、fflush、_exit、atexit、tinygltf、单用例预算、timeout 标注、可信度、self-validated、unvalidated。
+---
+
+# 宿主自证（能跑则跑，跑不了留证）
+
+**辖区 = 补写用例**：抓补写用例自身的断言错误——补写用例没有上游 CI 背书，宿主能跑时必须先自证。
+
+**上游用例不在宿主跑**（不预跑、不预筛 UB）：断言可信度由上游 CI 背书（`validation: upstream-backed`），
+UB/平台差异风险由阶段 3 真机轮的六值归因兜底；宿主预跑与设备结果相关性弱，不拿宿主预判设备终局。
+
+## 构建通道选择序（离库自身构建系统最近优先）
+
+```
+① 库的构建系统宿主通道（探测全绿直用）
+② 构建系统仅出库产物（用例链接）
+③ 手搓桩（gcc+ar，仅平铺 C 源回退）
+全不可行 → unavailable（取证义务：逐级留命令+失败首行）
+```
+
+**build-once**：一次构建产物、N 次用例消费（C=ar 逐条链接 / Python=装一次包 import /
+Rust=build 一次 / Node=install 一次）。
+
+**编译器探测必须做全**：PATH 之外必须 Test-Path `C:\msys64\mingw64\bin\gcc.exe`、`ucrt64`、
+VS BuildTools——6 库假阴性教训（只查 PATH 得出"无编译器"错误结论，sentry 实测 mingw 可编出
+全绿却记 unavailable）。禁"试一次 gcc 失败"就说跑不了。
+
+**`host_run.status` 三值之外还有 `not-required`**：唯一触发条件 = 工作区没有任何 `source: generated` 用例
+（宿主自证辖区只辖补写用例，上游用例不在宿主跑）。有 generated 用例就必须给出 `ran`/`unavailable`。
+
+## 三种结局
+
+| 结局 | 判定 | 处置 |
+|---|---|---|
+| ran | 编出并跑通 | 行为级断言宿主值稳定且闸 A → 升格精确钉值（S4）；validation=self-validated |
+| fail | 跑了但断言失败 | **在这里修到过**；修不好不进名册，缺口如实 partial |
+| unavailable | 三通道全试过、每级留命令+报错首行 | validation=unvalidated，全部 not-run；不降级 baseline_status |
+
+## no-op 骨架对照（ran 时加做）
+
+同一骨架**挖掉被测 API 调用**再跑一遍——no-op 输出与正常输出在断言字段上相同 = 断言架空
+（测的是骨架影子不是库），点名修断言。
+
+- 这是"不调用也成立 = 架空"对**非注入用例**的推广（注入用例的对应纪律是 injection-combination.md
+  的断言纪律——必须引用回调交付的数据），唯一能拦"精心写的恒真"的手段
+- 操作：复制测试骨架 → 注释/空转被测调用 → 保持输出结构与断言逻辑 → 对比两轮输出的断言字段
+
+## 用例退出纪律（阶段 2 写用例时就落，阶段 3 才能收尾）
+
+- 用例 main 结束必须 `fflush(stdout/stderr); _exit(0/1)`，禁依赖 atexit/exit 清理路径
+  （tinygltf 实证：musl __stdio_exit 挂 30s，12 条真过的断言被误判 fail）
+- 逐用例输出协议：`[CASE-BEGIN id]` / `[CASE-END id verdict]` 逐行落、逐行 flush；
+  verdict 三态 pass/fail/blocked 与执行器 blocked 映射一致
+- 单用例预算标注：已知重用例（>30s）在 run_command 显式标 timeout；设计期不标 → 总预算兜底 + killed 回标
+
+## 可信度档位（Hook 按公式算，agent 无权自封）
+
+```
+上游用例            → upstream-backed
+补写 + 宿主跑过     → self-validated
+补写 + 没跑过       → unvalidated（只有这档允许阶段 3 判 testcase-defect）
+```
+
+由 source + host_result + host_run.status 推导（`baseline-selfvalidation` 现算对账）——
+把未自证的写成已自证等于给下游开后门。
+
+## 产物
+
+补写用例源码（TMPDIR 纪律、黑盒接线）→ `tests-generated/`；宿主证据 → `run-host.log` +
+`run-host.json`（host-run 自己写）；定稿时对 tests-generated/ 全文件算 sha256 →
+`02-baseline.tests_generated_hashes`（指纹链存档 1，见 SKILL §指纹链）。