@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/references/injection-combination.md

@@ -0,0 +1,60 @@
+---
+description: 注入事件组合用例（一类组合用例）的知识文档：判定一问（断言目标的注入可达性）、注入触发+回调观测的唯一形态、键值必须出自 OHOS 2000 段码表、断言必须引用回调交付的数据、宿主对拍二分。与渲染验证二分法/网络 mock 同级的通解文档，知识承载不进结构化字段。触发词：注入、组合用例、interactivity、键盘鼠标触摸、回调观测、键值码表、PORTING_KIT、2000 段、宿主对拍、注入可达性、活窗即过、注入架空。
+---
+
+# 注入事件组合用例（组合用例的注入形态）
+
+**定位**：组合用例的一类。组合用例的路由二分——断言目标跑完即得（数据自己能到 stdout）→
+普通组合（骨架选型见 `combination-patterns.md`）；断言目标需要注入外部输入事件才可观测 →
+本文件的注入形态。与 `pc-test-design` 的渲染验证二分法、`network-protocol-mock.md` 的网络
+mock 前置同级：都是"这类库/这类断言在鸿蒙上怎么验"的通解知识，不是结构化字段契约。
+
+## 判定一问（逐功能点）
+
+验这个功能点，需要注入外部输入事件（键盘/鼠标/滚轮/触摸/特殊键）才能观测断言对象吗？
+
+- 判据是**断言目标的注入可达性**，与组合 API 数量无关——多 API 组合但跑完即得 = 普通用例；
+  回调注册了但断言对象不注入就不可达 = 注入组合用例
+- **interactivity_hint 判定**：仅当上游 demo **源码注册了输入回调**（键盘/鼠标/触摸 handler
+  在场）才标——设计期看 demo 源码确认，**不自动推断、不误标**
+
+## 操作形态（注入触发 + 回调观测）
+
+1. **回调注册**：注入用例的验证链 = 注册回调 API → 注入事件 → 回调交付数据 → 断言读交付数据。
+   注册与读取的每个符号必须 ∈ api_surface 公共符号（反幻觉锚——编造的注册 API 编译即失败）。
+2. **注入声明**：channel（mouse/touch/wheel/key）+ action（click/down-up/move/scroll/key(<code>)）+
+   target（window-center 等坐标语义）+ wait_ms（注入前等待窗）。通道与动作语义的表单权威在
+   `pc-test-design/references/input-resources.md` 与 05-testcases 的 interaction 枚举。
+3. **键值纪律**：键值出自 **OHOS 2000 段码表**（PORTING_KIT.md，pc-capability-domains）——
+   KEY_0=2000..9、KEY_A=2017..Z、ESCAPE=2070。**凭直觉写键值 = 设计期埋必挂用例**。
+
+## 断言纪律（防"活窗即过"）
+
+- 断言必须**引用回调交付的数据**（计数器/收到参数，如 `key_events >= 1 && cur_key == KEY_A`）——
+  禁 exit_code/frame_count/窗口存活/渲染成功 冒充（不注入也成立的判据 = 注入被架空，是更隐蔽的
+  存活冒烟）；断言读计数器而非 grep demo 输出
+- 钉精确值必带 `出处:`（官方文档/源码枚举定义/宿主实测三选一；`key(N)` 查 PORTING_KIT 键码表）——
+  expected 从 actual 自产 = 设计与判定耦合，空实现也能过
+- 禁存活级空话（"回调被触发/生效/渲染正确"）——可判定谓词（比较/数值/计数/非空/匹配）必须有
+
+## 宿主对拍（二分）
+
+宿主能跑 → 先对拍验"断言目标真的会被注入触发"（`ohpt-agent host-run --probe-recipe <name>`，
+命中后 verified=true 写回；等价注入方式：xdotool / stdin 管道 / 测试程序自测开关）——在烧真机
+前先验断言方向对错。
+
+宿主跑不了 → 省略对拍，进阶段 3 靠真机（`ohpt-agent verify-demo --interact` 冷启动→标定→注入→
+采回调日志）。**"宿主能跑"的判据 = 宿主构建通道①② 产出可执行物（手搓桩③ 产出的也算能跑）**
+——"构建要费点劲"不是"跑不了"，别误判而滥用省略出口。
+
+## 阶段 3 证据四件（verify-demo --interact 取证）
+
+| 件 | 语义 | 缺失即 |
+|---|---|---|
+| waitInput | 载体进过输入等待循环（wait-input 标记行在场） | 注入无效 |
+| injection | 注入命令执行记录（标定 bounds/命令/重试）在案 | 无从触发 |
+| consumed | 事件消费证据（回调触发/计数行） | 注入了但没被消费 = 回调没接上 |
+| resultLine | 结果行（pass/fail；blocked 须可解释） | 判据缺失 |
+
+四件不全 = 「窗口存活即 PASS」的存活冒烟，不构成该条目的过。人工冒烟必须补——见
+pc-device-verify 的「机器验收的交互盲区」节。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-roster-generation/references/upstream-triage.md

@@ -0,0 +1,141 @@
+---
+description: 上游测试套件收编与剔除的完整判定程序：全量清点（机器提取）、三类剔除（原平台专有 4a / 鸿蒙不可执行 4b 三值分诊 / PRD scope_out，逐条附证据）、可执行性正向三层模型（语言薄提取器需求提取 → 域能力矩阵匹配信号 → 纯函数判定）、套件级先行与框架前置表、剔除纪律与扣账。触发词：上游剔除、platform_exclusive、guard 扫描、条件编译栈、executability、可执行性分诊、runnable degraded blocked、unknown 回填、套件级先行、suite_executability、criterion gtest cmocka automake 前置。
+---
+
+# 上游用例剔除与可执行性分诊
+
+**目标**：把上游测试套件转化为"必跑名册的上游部分"。原则：**能收尽收**——上游用例是免费的回归资产（CI 背书、断言保真），剔除必须逐条有据。
+
+## 1. 全量清点
+
+- 枚举上游测试套件：测试目录、CI 配置（.github/workflows）、构建系统 test target
+- 用例清单优先机器提取（gtest `--list-test-names-only`、CTestTestfile、automake TESTS）；
+  agent 现写临时脚本按测试框架定制提取逻辑（TEST 宏形态 + 条件编译 guard 栈追踪），
+  脚本与中间产物放 %TEMP%，不污染工作区
+- 每条用例登记：名称、所属二进制/套件、官方运行命令及出处（file:line）
+
+**无套件出口**：清点的合法结论之一是"上游没有自动化测试套件"（CI 只做构建验证、构建系统无
+TESTS/check target、无测试目录——三者都要查到并留证据才算数，libmtp 实证：CI 只有
+configure→make→distcheck、Makefile.am 无 TESTS）。此时**跳过第 2/3 节**（没有可剔除的对象，
+可执行性分诊只辖上游用例），`discovery` 记结论 + 证据，下游缺口账走无套件捷径
+（触达账恒空 → 全部 L0 = full-case，见 `gap-ledger.md`）——不存在"没有用例所以多补点"的推论。
+
+## 2. 三类剔除（逐条附证据，两分支互斥、先后有序）
+
+| 类别 | 判什么 | 处置 |
+|---|---|---|
+| **4a 原平台专有** | 上游自己就没打算在别的平台跑 | `platform_exclusive: true` + evidence → 剔除（原样保留） |
+| **4b 鸿蒙不可执行** | 上游想多平台跑但鸿蒙 app 域满足不了前置 | `executability` 三值分诊 → runnable 收编 / degraded 收编+留账 / blocked 剔除+台账 |
+| scope_out | PRD 明确排除的功能域 | 不入册 |
+
+**4a 执行方式（两段式）**：
+
+第一段：机器提取（agent 现写一次性临时脚本，放 %TEMP%，按测试框架定制）——逐行扫测试源文件，
+正则抓 TEST/TEST_F/TEST_P 宏，同时维护 `#if/#ifdef/#ifndef/#else/#endif` 条件编译栈——每条用例
+记录其所处的 guard 上下文（如 VK_USE_PLATFORM_WAYLAND、_WIN32），产出"用例 → guard 上下文"分组中间 JSON。
+
+第二段：agent 判读分组结果（脚本只管"哪条用例在哪个 guard 下"，guard 语义是 agent 的活）：
+
+| guard 形态 | 判定 | 依据 |
+|---|---|---|
+| `_WIN32` / `__APPLE__` / `Q_OS_WIN` 等平台宏门控 | platform_exclusive（4a） | 上游 CI 矩阵同构排除——上游自己在 Linux CI 里就不跑这些 |
+| 平台专有夹具/设备引用（winrt、注册表、X11 display、Fortran 工具链） | platform_exclusive | 上游 src/ 树的平台目录结构佐证 |
+| 依赖 shm_open/MAP_FIXED/GAS/专用服务端等**非平台专有但 app 域受限**的前置 | 不判 4a → 转入 4b 三值分诊 | 词表里没有平台宏，是 app 域沙箱问题（scip 教训：只认 4a 时 blocked 占坑造成假绿） |
+
+第三段：证据行取证——判定需要依据时用 grep 精确到 file:line。
+
+**边界与纪律**：4a 只认**原平台专有**；权限/框架/依赖类的鸿蒙侧不可执行**不在词表里**——
+误用 4a 剔除会绕过 4b 的 blocked 闭环（覆盖缺口不触发补写），两类必须分流。
+
+## 3. 可执行性判定（正向需求驱动，非判例驱动）
+
+### 第 0 步：判定对象归位——分清"被验证的属性"与"上游的取证手段"
+
+逐条上游用例先回答：这条测试**守护的属性**是什么（一句话）？属性常见四族——
+**导出面/符号纪律**（查符号表/导出集）、**输出正确性**（固定输入比对输出）、
+**布局/ABI 契约**（sizeof/offsetof 类断言）、**编译期配置组合**（宏/特性开关检查）。
+
+然后问：**属性在设备上可观测吗**？
+
+```
+├─ 属性可观测、只是上游的取证手段在设备上不存在
+│   （nm/objdump/宿主编译器/make dist 产物/外部脚本工具……）
+│   → 手段替换：需求清单里写的是属性的取证需求
+│     （如"查交付产物的符号表"），不是上游的手段（"nm 查 .o"）。
+│     设备工具链（llvm-nm/llvm-readelf/clang）与交付产物本身，
+│     是取证需求的合法供给 → 按替换后的需求走第 1-3 层（通常 runnable/degraded）
+└─ 属性本身不可观测（被测的就是受限前置本身，如沙箱拒绝的能力）
+    → 才进第 1 层需求提取
+```
+
+**检验句**：把上游手段换成设备等价工具后，属性还能取到证吗？能 → 不是 blocked。
+
+**配套两查**（同一判定点）：
+- 查 01-scan 的 `recommended_path` 与工作区沉淀是否有该属性的已证构造，有 → 直接 degraded（收编 + 等价构造义务）
+- 判 blocked 前逐条 blocker 自检：这个 blocker 是"设备域不可满足的**前置**"（能力/权限/数据），还是"**上游选择的做法**"（工具选择/产物形态）？后者不算 blocker——它该在第 0 步被手段替换掉，留到这一步说明第 0 步没做
+
+**判定层级错误的形态**：把"手段缺失"当"属性不可观测"——需求清单里写了上游工具名，矩阵当然查不到，blocked 就是错判。分诊要**松不要严**：判不准往 runnable/degraded 收（收编进名册，构造细节阶段 3 执行时验证，跑不了由归因 `testenv-limited` 接）；代价只是设备红一轮，漏判的代价是整条免费守卫被扔掉。
+
+### 三层模型
+
+```
+第 1 层：需求提取 → 统一 schema 的"执行需求清单"
+  - 每语言一个薄提取器（C/C++、Python、Node、Rust、Java 各一，约 100-200 行），
+    扫描进程启动、syscall FFI、路径常量、网络调用、外部工具调用
+  - 外部工具调用记入需求清单前先过第 0 步：该工具是属性取证手段（可替换，
+    不进清单——改为记属性的取证需求）还是被测对象/运行前置（不可替换，进清单）
+  - 脚本沿 source/include 链扫（libunistring 教训：chmod 藏在被 source 的 init.sh 里）
+  - 可选增强：对可疑框架做局部试编（只交叉编译测试 harness，不编完整交付），
+    对 harness ELF 跑 llvm-nm -u 未定义符号表——符号面不撒谎，
+    预编译第三方依赖（criterion/cmocka 等源码不在树里的框架）只有此路可扫
+第 2 层：域能力矩阵（三值：可用 / 可等价构造+方法 / 不可满足）
+  - 每行带"匹配信号"正则（shm_open(/、mkstemp、"/tmp、posix_openpt、symlink(…）
+  - 查不到的 unknown 项不许放行：agent 判定后必须回填矩阵行
+第 3 层：判定（纯函数）
+  需求全可用 = runnable；有等价构造 = degraded；任一不可满足且无构造法 = blocked
+  （blocked 收口自检见第 0 步配套两查）
+```
+
+判据三源（只引用不复制）：知识库双矩阵（`pc-knowledge-base/platform/鸿蒙PC-app域测试前置条件矩阵.md`、
+`鸿蒙PC-POSIX-NDK能力探针矩阵.md`、`鸿蒙PC-app域执行二进制与JIT限制.md`）、
+01-scan 的 `capability_dependencies`、上游 harness 静态审查。
+
+**三值语义**：
+- **runnable**：静态审查未发现阻塞。不承诺运行时行为（SELinux 竞态/HMDFS 语义/时序仍归阶段 3 `testenv-limited`）
+- **degraded**：矩阵部分行不可满足**但有等价构造法** → 收编 + `blockers[]` 引用矩阵行 + notes 写等价构造义务
+- **blocked**：矩阵确认不可满足且**无等价构造法**（如 Criterion arena 依赖 shm_open+MAP_FIXED）→ **剔除** +
+  `executability_evidence[]` 指向知识库文档行 + prd_refs/api_refs 从覆盖分子让出（闭环执法
+  `roster-blocked-upstream-coverage` / `-symbol-coverage`：两锚同守，剩余载体或留账，否则不许 planned）
+
+**判例**：
+
+| 库 | 形态 | 判定 |
+|---|---|---|
+| scip（Criterion） | harness arena 依赖 shm_open/MAP_FIXED，知识库已文档化 | blocked（套件级）→ 剔除 → 功能点强制补写/留账 |
+| Vulkan-Loader | UnknownFunction 族依赖 GAS 汇编、WSI 依赖框架 OHOS 分支 | degraded → 收编 + blockers 留账 |
+| 运行时差异 | SELinux 竞态 / HMDFS 语义 | 不在 4b 辖区（runnable 不承诺运行时），归阶段 3 归因 |
+
+## 4. 宿主预跑口径（上游用例不在宿主跑）
+
+上游用例**不做宿主预跑**——不预跑、不预筛 UB。理由：上游 CI 背书覆盖断言语义（`validation:
+upstream-backed`）；宿主预跑与设备结果相关性弱（不拿宿主预判设备终局）；UB/平台差异风险由
+阶段 3 真机轮的六值归因兜底（归因时宿主没有底牌，就按"设备红 → 先查产物再查用例"的默认推定走）。
+分诊要松不要严的代价核算因此更轻：判错往 runnable 收，最多烧一轮设备环，没有宿主侧的重复成本。
+
+## 5. 套件级先行 + 用例继承
+
+- 权限/框架依赖多是 harness 级 → 先判 `discovery.suite_executability[]`（一次判整族），
+  用例级 `executability` 默认继承、只记特例
+- 框架级前置表（测试框架 → 已知前置/修复模板）：
+  - criterion/boxfort → arena 沙箱不兼容（套件级 blocked 候选）
+  - gtest → 检查 gtest-port.cc 的 /tmp 硬编码，收编时预防性打 TMPDIR patch
+  - cmocka → CMake generator 问题
+  - automake TESTS sh → 系统工具依赖 + HNP mini 工具集预备
+
+## 6. 剔除纪律与扣账
+
+- 剔除逐条附证据（file:line 或工具输出），禁整批"看起来跑不了"式剔除；
+  套件级同因的（如整个 fortran-api-test）一次判定 + notes 引用即可，不逐条重写
+- **剔除时同步扣账**：被剔用例触达的 API 从覆盖集划除（补写用例集在 gap-ledger 记触达账时消费——
+  只读本步落好的 `platform_exclusive`/`executability.verdict` 字段，不重复判定）
+- 判定结果写 `executability.verdict` + `blockers[]` + `evidence[]`（schema 字段契约见 02-baseline.schema.json）

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

@@ -0,0 +1,42 @@
+---
+name: pc-schemas
+description: 各阶段产物 JSON Schema 知识库。当需要输出 01-scan.json / 02-baseline.json / 03-adapt.json / 04-summary.json / 05-testcases.json / 06-testdemo.json / verify-verdict.json 前查字段契约时使用。触发词：schema、字段契约、输出格式、01-scan、02-baseline、03-adapt、04-summary、05-testcases、06-testdemo、verify-verdict、prd、功能点、测试用例、用例清单、覆盖度、执行结果、required 字段、enum 值、JSON Schema。
+---
+
+# pc-schemas：各阶段产物 JSON Schema
+
+各阶段输出 JSON 的完整 Schema 在 `references/schemas/` 下；报告模板 `references/templates/` 由 Hook 渲染时使用，agent 不读也不写。
+
+## Schema 索引
+
+按**流水线位序**列（阶段号是身份不是序号）：
+
+| 阶段 | schema 文件 | 产物 | 说明 |
+|------|------------|------|------|
+| scan | `references/schemas/01-scan.schema.json` | 01-scan.json | 扫描分析与可行性评估 + **PRD 功能点清单**（`prd`，阶段 5 的需求面；顶层选填，写了就得合格） |
+| baseline | `references/schemas/02-baseline.schema.json` | 02-baseline.json | **必跑名册**＝阶段 3 的分母（原库用例 − 平台独有 + 覆盖缺口补齐；不要求在宿主跑通） |
+| adapt | `references/schemas/03-adapt.schema.json` | 03-adapt.json | 适配验证 + 照名册逐条跑（`test_run.roster` 交代下落、`exemptions[]` 取证豁免） |
+| summary | `references/schemas/04-summary.schema.json` | 04-summary.json | 沉淀总结（**主线出口**；判定输入里没有任何测试产物） |
+| testcases | `references/schemas/05-testcases.schema.json` | 05-testcases.json | **测试设计**（**测试线，默认关**）：用例 1:1 绑 PRD 功能点、PRD 覆盖度、自评审。只吃需求面，不吃被测面 |
+| testdemo | `references/schemas/06-testdemo.schema.json` | 06-testdemo.json | **Demo 生成与真机验证**（**测试线出口**）：逐用例执行结果、执行覆盖度、能力缺口、设备证据 |
+| verdict | `references/schemas/verify-verdict.schema.json` | verify-verdict.json | 独立验收裁决（pc-03-dev-verify，非编号阶段） |
+| manifest | `references/schemas/manifest.schema.json` | manifest.json | 工作区清单（Hook 自动同步，agent 不写） |
+
+CLI 评审另有 `references/schemas/test-change-proposal.schema.json`（修改前提案）与 `references/schemas/human-review.schema.json`（请求/答复/恢复记录）。两者由 `ohpt-agent human-review` 命令校验，不作为阶段报告触发 PostWrite 渲染；记录文件不由 agent 直接改写。操作协议见 `pc-workspace-layout` 的 `references/human-review.md`。
+
+## 语义参考（按需查）
+
+| 文件 | 内容 |
+|------|------|
+| `references/semantics/enum-semantics.md` | 所有 enum 的语义说明与选择条件（porting_class / feasibility / effort / delivery_form / native_class / category / harmony_status 等） |
+| `references/semantics/language-signals.md` | 各语言的清单文件位置、原生扩展检测信号、扩展后缀、鸿蒙运行时状态 |
+| `references/semantics/adaptation-report-mapping.md` | **报告驱动模式**（Electron 场景，阶段 1）：适配点分析报告（ohos-migration-analysis 产出）→ 01-scan.json 逐字段映射 + feasibility 推导 + PRD 归纳 |
+
+## 使用方式
+
+1. 调用本 skill 获取 skill 目录路径
+2. Read 对应阶段的 schema 文件确认字段契约（required 字段、enum 值、类型）
+3. 严格按 schema 输出 JSON
+4. 写入后 PostWrite Hook 自动用同一份 schema 校验，失败则 edit 修订
+
+> Schema 是单一真源——agent prompt 不内联 schema，PostWrite Hook 也不另存副本，全部以此为准。