@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/d2h-hypium-forge/SKILL.md

@@ -1,309 +1,309 @@
----
-name: d2h-hypium-forge
-description: 鸿蒙应用/元服务测试用例设计与 hypium 执行（两阶段流水线第二段，部署于 .opencode 迁移 agent）。宿主 agent 代码理解产出功能场景库（功能/说明/是否已转化）→ 本 skill 按场景测试目的选断言范式、LLM 白盒精写 Python 脚本 → 裸跑执行与失败四簇分析。适用于任何 ArkTS 工程的功能测试自动化。触发词：hypium-forge、功能用例设计、测试用例生成执行、覆盖度评估、鸿蒙 UI 测试全流程。
----
-
-# d2h-hypium-forge — LLM 白盒精写 → 裸跑执行
-
-## 体系边界（先分清）
-
-本 skill **只服务 Python 版 Hypium**（devicetest 框架，`testcases/*.py`，UiDriver 经 uitest RPC 驱动设备）。
-**ArkTS @ohos/hypium 是另一条链路，不在本 skill 范围**——模拟器上应用内 uitest napi 是 stub
-（`Driver.create()` 恒 null，ENV 实证），ArkTS 用例仅适用于真机且需独立工程配置；文档中两套
-API 同名不同构（BY 定位/断言语义有差异），混用必然执行失败。涉及 ArkTS 用例需求请走
-单独链路（ohosTest 模板），禁止在本 skill 产物目录混建。
-
-## 三条铁律
-
-1. **必须先预置控件 ID（写脚本之前）**：`preinject_ids.py` 对全部交互点机械注入，
-   脚本只认 ids.json/既有 ID（BY.key）。文本定位（BY.text）慢 10~100 倍且有歧义。
-2. **Level 0 前置自适应（冷启三件套，launch 原语内置，用例不得自带）**：
-   首启弹窗 dismiss（多文案轮询幂等）+ 首页 tab 归位（HOME_TAB 应用级配置，
-   冷启默认 tab 常与目标 tab 不一致）+ 语义锚等待（禁依赖注入 id 等 Loading 层控件）。
-   隐私弹窗常为内存态（冷启必弹）——每条冷启都必须 dismiss（TD-007）。
-3. **权限和账号前置完成**：precondition.py 预授可授权限/登录策略/首启弹窗 dismiss，
-   绝不留给用例执行时撞。**登录态跨用例保持**：软隔离（stop_app/start_app）不清应用数据；
-   `reset_data=True`（bm clean）只用于首启态用例且**须排尾/独立分组执行**——与登录用例
-   交错会反复清登录态导致重复登录注册（CloudReader TD-004 实证：交错执行重复注册 30 次）。
-
-## 五步流水线
-
-设 `$F = 本skill/scripts`，工程 `$P`，产物目录 `$P/.hypium_forge/`。
-
-### 1. 功能场景库（测试设计的基础输入）
-
-本 skill 是两阶段流水线的第二段：代码理解由宿主 agent（.opencode 迁移 agent）完成，
-产出功能场景清单后调用本 skill 生成并执行测试。**场景库是测试设计的唯一基础**——
-它的完备性与准确度决定下游全部产出的质量，宁可在此多花时间。
-
-**阶段一（宿主 agent）**——按 `references/functional-spec-template.md` 产出功能规格
-`functional_spec.md`，再翻译为 `scenarios.json`：
-```json
-{"id":"WF-01","name":"搜索选中城市并收藏","domain":"位置管理",
- "desc":"用户在搜索页输入关键字，点选结果后返回管理页，列表新增该城市并提示收藏成功",
- "converted":true, "source_ref":"SearchActivity.java:181-195",
- "test_intent":"功能交互类"}
-```
-生成规则：
-- 场景单位 = **用户动宾行为**（禁 Activity/Fragment/surface 类名当场景）；
-- `desc` 写清「输入→动作→**可观察业务效果**」，效果描述到可翻译成断言的程度；
-- 行为预期从源码推导（默认值/联动/守卫），不从直觉——直觉必错；
-- `converted` 与迁移报告对齐，未转化标 false 并跳过。
-
-**阶段二（本 skill）**——先过**场景库质量门禁**再消费：
-```bash
-python3 $F/validate_scenarios.py scenarios.json    # 不通过项入 scenarios_blocker.md
-```
-校验：①必备字段（id/name/desc/converted/test_intent）②desc 含可观察业务效果关键词
-（新增/删除/修改/保存/收藏/取消/成功/失败/提示/计数/状态/切换——纯"进入XX页"类导航词
-无效果=拦截）③入口可定位（深层链路 desc 须写前置路径）④行为预期有源码/PRD 依据标注
-⑤converted=false 必须带 reason（未迁移/能力缺失/暂不测试）。**blocker 场景不进用例生成**，
-退回宿主 agent 修复。通过后：converted=true 逐场景设计用例
-（按 test_intent 选断言范式）→ 白盒精写 → 执行 → 分诊 → defects/报告。
-用例与场景一一对应，无场景不写用例。
-
-### 1.5 机械扫描（覆盖性评估的补充）
-
-```bash
-python3 $F/scan_features.py $P --out $P/.hypium_forge/features.json
-```
-产出：页面（路由+@Entry）× 交互点 × 状态矩阵 + 权限/登录检测。有安卓迁移现场时
-`merge_appgraph.py --features ... --facts <android>/.migration/spec/facts` 注入权威行为语义
-（handler 链揭示联动场景）。
-
-**定位是补充而非基础**：features 条目是定位事实不是业务功能，机械扫描可靠性不足，
-不得直接作为测试设计输入。两个用途：
-1. **覆盖校验**：对照 scenarios.json，找出未被任何场景覆盖的页面/交互点 →
-   反馈宿主 agent 裁决「补场景」或「登记不测并说明理由」——遗漏即测试盲区；
-2. **ID 预置清单**：交互点列表供步骤 3 preinject_ids.py 机械注入。
-
-覆盖结论写入 `coverage.md`，**双口径分列（防机械冒充功能覆盖）**：
-- **场景覆盖度（主口径）** = 被采纳用例触达的场景数 / scenarios.json 中 converted=true 场景数；
-- **控件触达率（辅助口径）** = 已触达交互点 / 全部交互点——仅暴露机械盲区，**不得单独
-  作为功能覆盖率汇报**（把扫到的控件数当功能覆盖是自欺）；
-coverage.md 逐条列出并按规则处置：
-  - 未覆盖场景（如 WF-12, WF-19）→ 必须反馈宿主 agent 补场景或登记不测；
-  - 未触达交互点（如 HomePage.ad_banner）→ 不一定补用例，人工裁决是否为
-    广告位/运营位/未迁移能力（判定理由随条目记录）。
-未覆盖交互点及其裁决结果。
-
-### 2. 运行时文本采集
-```bash
-python3 $F/collect_runtime_pages.py --device <sn> --bundle <b> --out runtime_pages.json
-```
-脚本引用的控件文本**只允许**来自采集结果；断言锚定业务数据，禁止导航回声断言。
-**并行提速**：首页文本采集完成后即可开始写该页用例（其余页面采集继续）——采集与编写
-流水线并行，禁串行等全量采集完再动笔。
-启动参数门控应用：先 `aa start --ps k v` 预热，singleton 的 onNewWant 不重置状态可继续采集。
-
-### 3. ID 预置（铁律①，先于脚本编写）——机械注入的边界与补强
-```bash
-python3 $F/preinject_ids.py --features features.json --out ids.json   # 交互点清单来自 §1.5
-# 之后 rebuild + uninstall&&install
-```
-批量注入 `tc_<page>_<n>`，产出 ids.json 映射表。脚本定位只认 ids.json/既有 ID（BY.key）；
-仅输入框用 BY.hint。
-
-**静态注入三盲区**（preinject 只扫静态代码，以下场景必然漏注）：
-1. 动态列表控件（ForEach 运行时生成，静态无挂载点）→ 用 `collect_runtime_pages.py`
-   的 dumpLayout 控件树交叉核对：dump 中 key 为空但语义可定位的条目，回填至
-   runtime_pages.json 供 BY.text 兜底并登记例外；
-2. 条件渲染分支（if/else 二选一支路）→ 场景变体执行前先 dump 该分支实况；
-3. 异步加载页（网络数据到位才渲染）→ 依赖步骤 2 采集的等待锚，禁用盲等。
-
-**无 ID 例外审批制**：例外必须三件套——docstring 理由 + runtime_pages.json 中的实测
-证据（该控件确实无 id 且文案唯一）+ lint_locate 通过；例外清单汇总进 coverage.md
-「无 ID 例外」章节备查，审计时逐条复核（防例外变成 BY.text 后门）。
-
-### 3.5 输入契约与空库守卫（宿主 agent ↔ 本 skill 的稳定边界）
-
-**只接受以下输入**：scenarios.json / features.json / ids.json / runtime_pages.json /
-_common_template.py / ArkTS 源码路径。**场景库为空或全部 converted=false 时直接报错
-退出，不生成空用例集**（空跑=伪覆盖）。生成规则见步骤 4；执行后必须产出：
-testcases/*.py、results.json、coverage.md、summary.json、test-report.html、失败截图与 hilog 片段。
-
-### 4. LLM 白盒精写 testcases/*.py（核心）
-
-从 `$F/_common_template.py` 复制为 `testcases/_common.py`（launch 带 `--ps k v` 空格分隔、
-3 轮重试探活、首启弹窗 dismiss、强断言原语全套——**写前必读**），逐条编写 `TCxx_<slug>.py`。
-
-**编写规则：**
-
-- **先读源码**：默认值/联动规则/时序以 ArkTS 源码为准——臆断默认值必返工；
-- **按场景测试目的选断言范式**（问"本场景要证明什么"再选型）：
-
-  | 场景类型 | 测试目的 | 正确断言范式 |
-  |---|---|---|
-  | 资源渲染类 | 图标/文案加载成功 | exist/equals 即目的本身 |
-  | 功能交互类 | 操作产生业务效果 | 效果断言（值变化/计数增减/checked 翻转/absent） |
-  | 配置生效类 | 设置改变全局行为 | 生效链断言（改设置→回业务页→断言输出变化） |
-  | 导航流转类 | 状态迁移到目的地 | 终点效果（城市选中→顶栏变新城市名） |
-  | 状态机类 | 状态转移规律 | 前置态断言→触发→后置态断言（成对） |
-  | 数据输入类 | 输入被正确处理 | 输入→输出值断言（搜索词→结果计数） |
-
-- **强断言比例按 test_intent 分档**（全局硬门禁 ≥30% 整体维持 40~70%；比例是目的的
-  结果不是目标——**禁止加"页面存在/按钮可见"类弱断言凑比例**，单条低于档位下限报
-  "弱断言风险"提示、超上限检查是否断言了实现细节）：
-
-  | test_intent | 强断言区间 | 说明 |
-  |---|---|---|
-  | 资源渲染 | 20~40% | 证明图标/文案/占位正确，exist/equals 即目的 |
-  | 功能交互 | 50~70% | 必须断言业务效果，不能只断言按钮存在 |
-  | 配置生效 | 60~80% | 改设置→回业务页→验证输出变化的完整生效链 |
-  | 导航流转 | 40~60% | 终点页面 + 关键状态都要验证 |
-  | 状态机 | 60~80% | 前置态、触发、后置态成对断言 |
-  | 数据输入 | 50~70% | 输入→结果列表/计数/排序必须验证 |
-
-  核心判据：**断言必须证明场景声明的目的**——目的是"功能发生"时仅判存在 = 无效用例；
-- **Toast** 用 hilog 关键字轮询或 toast_text_seen（dump 轮询）、**剪贴板**用 hdc pasteboard、
-  对话框流转逐步断言；
-- **视口外控件**必须用 `touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 原生滚动查找，
-  禁止手工 swipe + find 循环（时序敏感且不稳定）；
-- **深链路用例内显式 setup**：上游状态准备写成用例内步骤，禁止假设页面已就位；
-- **失败 = 信息**：产品缺陷保持 FAIL 暴露，绝不弱化断言换绿灯；用例自身错误可修（≤2 轮）；
-- **用例数量由功能场景覆盖决定**，禁止固定条数或上限——每个 converted=true 场景至少
-  1 条用例真实触达；**不允许脱离场景新增用例、不允许把页面跳转当最终业务效果**；
-  文本断言只能来自 runtime_pages.json 实采，不能臆造文案；
-- **定位门禁**：`lint_locate.py --dir testcases --ids ids.json`，text 定位 >20% FAIL——
-  LLM 常绕过预置 ID 用 text_click，唯机械门禁有效；
-- 每脚本 docstring 写清行为链与覆盖的功能场景 id；
-- 执行后产出 `coverage.md`（含「总覆盖度: N%」行）与 `summary.json`。
-
-### 4.5 前置条件分组编排（共用前置，提升执行效率）
-
-用例文件声明 `PRECOND`（缺省 anonymous），run_direct 按 **anonymous → logged_in →
-first_launch** 分组排序执行（破坏性递增，bm clean 类强制排尾不再回头破坏登录态）。
-组内软隔离共享前置：`launch()` 默认 `reset_data=False`，preferences 保留 → 组首一次
-完整 `ensure_login`，组内后续幂等复用。组首执行时 `FORGE_GROUP_FIRST=1`。
-results.json 每条附 `group` 字段可分组统计。**禁把 reset_data=True 用在 logged_in 组**。
-
-### 5. 裸跑执行 + 四簇分析 + HTML 报告（重跑阶梯 = 硬规范）
-
-**执行命令阶梯（--all 仅限首轮与门禁升级，修复轮禁无脑全量；违反会被 runner 硬阻断）**：
-> TD-LADDER v3 防护（已内置于 run_direct.py）：**所有"显式全量"（`--all` / `--acceptance` / 变相全量的 `--filter`）统一受管**，
-> 不再给 `--acceptance` 开后门。五条规则（任一命中即 exit 2 阻断并输出指引）：
-> ① **R1** 上轮 results.json 存在 FAIL/SKIP → 必须先修（`--case`/`--retry-failed`），禁止全量；
-> ② **R2** 源码 `srcHash` 与上次全量相同 → 重复全量无新结论（仅拦 `--all`）；
-> ③ **R2b** 上次已是**同源验收**（`lastMode=acceptance` 且 srcHash 未变）→ 拒绝重复验收；
-> ④ **R3** 本修复周期显式全量已达上限（默认 2，`FORGE_FULL_BUDGET` 可调）→ 归零条件是"跑出全绿"；
-> ⑤ **L1** `--filter` 覆盖 >50% 用例 = 变相全量，按全量纳管；**L2** 连续两轮失败签名一致且源码未变 → 拒绝重跑（先 probe 定案）。
-> 免检：`--retry-failed` 因源码变更**自动升级**的全量（非显式，不占预算）；`--force-all` 为显式逃生门。
-> droid2hmos CLI 的 `test harmony --runner python --all` 同步受 R1 防护（`--force-all` 放行）。
-> 实证（Grit）：修复期 15 次全量 212min，其中 **`--acceptance` 被当日常全量跑 13 次 157min（占测试时间 65%）**；
-> `--filter TC0` 当"小全量"跑 7 次；同族失败连卡 5 轮。v3 的 R1 覆盖 / R3 计次 / L1 / R2b / L2 即由此固化。
-> 合法全量收敛为：首轮（无历史）+ 终局验收（全绿后一次）+ 逃生门。
-```bash
-# 首轮全量（唯一常规使用 --all 的场景）
-python3 $F/run_direct.py --all --dir testcases --device <sn>
-
-# 修复轮阶梯（Grit 实证：15 次全量 212min，其中 5 轮卡同一 bug 空转 71min）
-python3 $F/run_direct.py --case <失败用例> --dir testcases --device <sn>      # ① 修测试脚本后单条验证（1-4min）
-python3 $F/run_direct.py --retry-failed --dir testcases --device <sn>         # ② 修产品代码后增量重跑（srcHash 门禁自动升级全量）
-python3 $F/run_direct.py --filter TC3 --dir testcases --device <sn>           # ③ 同族用例子集回归（如 TC30/31/35）
-
-python3 $F/analyze_results.py --results results.json --runtime-pages runtime_pages.json
-python3 $F/forge_report.py    # 产出 test-report.html（Allure 风格：概况/用例卡片/关键截图内嵌）
-```
-铁律：修 1 个用例 ≠ 重跑 24 个。run_direct 汇总后 FAIL>0 会直接打印下一步命令——照抄执行。
-
-**范围回归（touched，产品代码变更后的默认门禁策略）**：
-`--retry-failed` 检测到产品代码变更时不再一律全量——按 `results.meta.json` 的**逐文件指纹**
-diff 出改动集，若全部是 ids.json 可定位的 UI 文件，则只重跑 `FAIL/SKIP + 引用这些文件的用例`
-（用例源码中的 id 字面量 → ids.json 文件映射）。改动含共享逻辑（viewmodel/repository）或
-范围超 60% → 自动退化全量。禁手动 `--all` 替代；`--regression-scope full` 仅用于里程碑。
-
-**热启动（组内软复用）**：组内非首条用例 `FORGE_WARM_LAUNCH=1`，`launch()` 探测 HOME_ANCHOR
-已在位即跳过 stop/start/bootstrap（省 8-12s/例）；组首条与 first_launch 组保持冷启；
-`--case` 单条验证默认热启动（`--cold` 强制冷启）。断言冷启行为的用例写 `launch(d, force=True)`。
-单用例挂死由看门狗截断（`--case-timeout 240` 默认，超时记 FAIL 继续下一条）。
-瞬态失败（watchdog/连接类）轮末自动复测一次（`--flake-retry 1` 默认，断言类失败不
-自动复测防掩盖真缺陷）。**零进展检测**：失败签名集与上轮完全一致时 runner 直接亮牌
-警告——停止重跑转 probe 定案（Grit 实证：同族失败连卡 5 轮全量空转 71min）。
-调试迭代期可 `FORGE_WAIT_SCALE=0.5` 把断言超时减半加速失败复现；正式回归保持 1。
-
-**最终质量门（不可跳过）**：所有优化（范围回归/热启动/flake 复测）只加速迭代期；
-**交付/收尾前必须执行一次验收全量**：`run_direct.py --acceptance`（强制 --all + 全程截图 +
-`.acceptance` 标记永久保护，最近 2 次留存），FAIL=0 或全部 FAIL 已登记缺陷并经 probe 定案。
-范围回归的 PASS 保留记录不作为最终结论——它只是迭代加速器，最终覆盖度以这次验收全量为准。
-
-**截图与 reports/ 留存（防体积失控——Grit 实证 5266 张/666MB）**：
-- 迭代期 `--shots fail`（默认）：PASS 用例只留 `<case>_end.jpeg`，过程帧/分步图仅 FAIL 用例保留；
-  连续相同帧自动去重（静止页 8 帧→1 帧）。
-- **中间运行目录即用即弃**（`--keep-reports` 默认 0）：每轮结束只保留本轮供当轮取证，
-  下一轮自动回收上一轮中间目录；需要跨轮对照时 `--keep-reports 3`。
-- **验收全程留存**：`--acceptance`（最终质量门专用）强制全量+全程截图，目录写 `.acceptance`
-  标记，prune 独立保护**最近 2 次**验收目录，永久作为交付证据。
-**取证一条命令（probe.py，禁手写 UiDriver 内联脚本——Grit 实证 69 次手写探针多花一半时间在代码生成上）**：
-```bash
-python3 $F/probe.py texts|ids|find <id>|tree --grep x     # 单次 dumpLayout 本地解析取证
-python3 $F/probe.py click <id|text>                        # uinput 坐标点击（Toggle 等 touch 失效场景可靠）
-python3 $F/probe.py shot / hilog JSAPP 400 / db-pull <pkg> / db-sql <db> '<sql>'
-```
-
-失败四簇：DEVICE（环境，重跑）/ DESIGN-ERROR（脚本定位/步骤错误，修脚本 ≤2 轮）/
-NAV-CONTEXT-LOSS（页面上下文丢失，hilog 定案）/ ASSERT-FAIL（**优先怀疑产品缺陷，保留 FAIL**）。
-
-**自愈边界（允许 vs 禁止，修≠换绿灯）**：
-- 允许：修正错误控件 ID；补缺失等待条件；修正滚动/输入/弹窗关闭方式；调整用例内前置步骤。
-- 禁止：强断言→弱断言；`equals`→`contains` 规避差异；固定等待无限加长；模糊 text 匹配
-  绕过定位失败；把产品缺陷标 SKIP/PASS；**删除失败断言而不是修复原因**。
-- **FAIL 现场证据自动附言**：run_direct 失败时 msg 自动附带当前页面 Text 摘要
-  （`| 现场Text: …`）——下轮分诊直读证据，禁重复现场取证。
-- **原始失败记录保留**：修复重跑前 run_direct 自动把 results.json 滚动备份为
-  results.prev.json——修复轨迹可审计（改了什么、为什么改），防"驯化测试"。
-- **分诊三律（TD-018，防定案实验失控）**：①**同消息聚类**——多例同错误消息（如
-  text not found: X×N）视为同族，一次分析一次定案，禁逐条重复实验；②**同族定案实验
-  ≤2 次**（清数据/冷启/对照类），超限即按现有证据登记缺陷转人工——保留 FAIL 是合规
-  产出，不是未完成；③**成功模式对照先行**——定案前先查同场景已 PASS 用例的断言
-  范式（如冷启持久化断言），判据升级优先于现场重取证。
-- **修复轮增量重试**：`run_direct.py --retry-failed` 只重跑 FAIL/SKIP 条（PASS 保留
-  原结果合并写出）——禁无谓全量重跑浪费设备时间（首轮 11 条全量 286s，增量仅重跑 2 条
-  ~52s，省 80%）。**编写期自检批量做**：全部脚本写完统一 lint+语法批检，禁逐条单跑
-  调试（单条 LLM 往返间隔是隐形大头）。
-- **增量重试回归门禁（TD-019，防旧 PASS 掩盖回归）**：`run_direct.py` 自动对
-  `entry/src/main/ets` 计算内容指纹（srcHash，存 `results.meta.json` 侧车）。增量重试前
-  重算比对：产品代码有变更 / 无上轮指纹 / 定位不到源码目录 → **自动升级全量重跑**
-  （实证：Profiles TC09/TC14 PASS→FAIL 靠全量重跑才抓到，走增量通道会被旧 PASS 掩盖）；
-  确认仅测试脚本变更可 `--force-incremental` 强制增量。顺带修复：--retry-failed 现写入
-  results.json（旧版误写 results-single.json）。
-
-## 度量与沉淀
-
-- 记录：用例数、覆盖度、耗时、首轮通过率、调试轮次、强断言占比。
-- 失败模式沉淀 testability-requirements.md（可测试性需求）。
-
-## References（按需加载）
-
-| 文件 | 内容 | 何时读 |
-|---|---|---|
-| `references/official-api.md` | Hypium 官方 API 速查（BY 定位/模糊匹配/触摸/滑动/输入/断言 Checker/截图） | 编写脚本前查阅定位与断言 API 用法 |
-| `references/pitfalls.md` | 7 项目实证踩坑清单（swipe 百分比/BY.text 全匹配/press_back 语义/系统子窗口不可见/视口外滚动/DatePicker） | 遇到定位/滑动/输入/Toast 问题时查阅 |
-| `references/functional-spec-template.md` | 功能规格文档模板（9 段结构 + test_intent 选型表 + 边界异常） | 阶段一宿主 agent 产出规格时 |
-| `references/testability-template.md` | 可测试性需求模板 | 沉淀失败模式时 |
-
-## 断言能力速查
-
-| 层 | 能力 |
-|---|---|
-| 存在/消失 | BY.key/id/text/hint/type + absent |
-| 属性状态 | BY.checked/selected/enabled/focused/clickable/scrollable |
-| 值断言 | Checker：equal/not_equal/contains/match_regexp/greater/less |
-| 几何关系 | getBounds()/中心点/相对定位 |
-| Toast/系统级 | hilog 轮询 / hdc pasteboard / 外部跳转 absent 级 |
-| 结构断言 | find_all_components 计数 |
-| 边界 | 颜色/像素 diff/性能时序（勿硬造） |
-
-## 定位原语速查
-
-| 场景 | 原语 |
-|---|---|
-| 已注入 ID | `BY.key(tid)` |
-| 输入框 | `BY.hint('占位符')`（BY.text 命中 hint 节点静默失败） |
-| 底部 Tab | find_all(BY.text CONTAINS) 取最靠下 bounds 中心 |
-| 视口外 | `touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 原生滚动查找 |
-| mock 数据 | `hdc rport tcp:8787 tcp:8787` |
-
-## 相关 skill
-
-- `hypium-id-test`：无业务语义 ID 冒烟（转化后即跑）
-- `hypium-test-gen`：白盒逐条精写（7 项目踩坑清单）
+---
+name: d2h-hypium-forge
+description: 鸿蒙应用/元服务测试用例设计与 hypium 执行（两阶段流水线第二段，部署于 .opencode 迁移 agent）。宿主 agent 代码理解产出功能场景库（功能/说明/是否已转化）→ 本 skill 按场景测试目的选断言范式、LLM 白盒精写 Python 脚本 → 裸跑执行与失败四簇分析。适用于任何 ArkTS 工程的功能测试自动化。触发词：hypium-forge、功能用例设计、测试用例生成执行、覆盖度评估、鸿蒙 UI 测试全流程。
+---
+
+# d2h-hypium-forge — LLM 白盒精写 → 裸跑执行
+
+## 体系边界（先分清）
+
+本 skill **只服务 Python 版 Hypium**（devicetest 框架，`testcases/*.py`，UiDriver 经 uitest RPC 驱动设备）。
+**ArkTS @ohos/hypium 是另一条链路，不在本 skill 范围**——模拟器上应用内 uitest napi 是 stub
+（`Driver.create()` 恒 null，ENV 实证），ArkTS 用例仅适用于真机且需独立工程配置；文档中两套
+API 同名不同构（BY 定位/断言语义有差异），混用必然执行失败。涉及 ArkTS 用例需求请走
+单独链路（ohosTest 模板），禁止在本 skill 产物目录混建。
+
+## 三条铁律
+
+1. **必须先预置控件 ID（写脚本之前）**：`preinject_ids.py` 对全部交互点机械注入，
+   脚本只认 ids.json/既有 ID（BY.key）。文本定位（BY.text）慢 10~100 倍且有歧义。
+2. **Level 0 前置自适应（冷启三件套，launch 原语内置，用例不得自带）**：
+   首启弹窗 dismiss（多文案轮询幂等）+ 首页 tab 归位（HOME_TAB 应用级配置，
+   冷启默认 tab 常与目标 tab 不一致）+ 语义锚等待（禁依赖注入 id 等 Loading 层控件）。
+   隐私弹窗常为内存态（冷启必弹）——每条冷启都必须 dismiss（TD-007）。
+3. **权限和账号前置完成**：precondition.py 预授可授权限/登录策略/首启弹窗 dismiss，
+   绝不留给用例执行时撞。**登录态跨用例保持**：软隔离（stop_app/start_app）不清应用数据；
+   `reset_data=True`（bm clean）只用于首启态用例且**须排尾/独立分组执行**——与登录用例
+   交错会反复清登录态导致重复登录注册（CloudReader TD-004 实证：交错执行重复注册 30 次）。
+
+## 五步流水线
+
+设 `$F = 本skill/scripts`，工程 `$P`，产物目录 `$P/.hypium_forge/`。
+
+### 1. 功能场景库（测试设计的基础输入）
+
+本 skill 是两阶段流水线的第二段：代码理解由宿主 agent（.opencode 迁移 agent）完成，
+产出功能场景清单后调用本 skill 生成并执行测试。**场景库是测试设计的唯一基础**——
+它的完备性与准确度决定下游全部产出的质量，宁可在此多花时间。
+
+**阶段一（宿主 agent）**——按 `references/functional-spec-template.md` 产出功能规格
+`functional_spec.md`，再翻译为 `scenarios.json`：
+```json
+{"id":"WF-01","name":"搜索选中城市并收藏","domain":"位置管理",
+ "desc":"用户在搜索页输入关键字，点选结果后返回管理页，列表新增该城市并提示收藏成功",
+ "converted":true, "source_ref":"SearchActivity.java:181-195",
+ "test_intent":"功能交互类"}
+```
+生成规则：
+- 场景单位 = **用户动宾行为**（禁 Activity/Fragment/surface 类名当场景）；
+- `desc` 写清「输入→动作→**可观察业务效果**」，效果描述到可翻译成断言的程度；
+- 行为预期从源码推导（默认值/联动/守卫），不从直觉——直觉必错；
+- `converted` 与迁移报告对齐，未转化标 false 并跳过。
+
+**阶段二（本 skill）**——先过**场景库质量门禁**再消费：
+```bash
+python3 $F/validate_scenarios.py scenarios.json    # 不通过项入 scenarios_blocker.md
+```
+校验：①必备字段（id/name/desc/converted/test_intent）②desc 含可观察业务效果关键词
+（新增/删除/修改/保存/收藏/取消/成功/失败/提示/计数/状态/切换——纯"进入XX页"类导航词
+无效果=拦截）③入口可定位（深层链路 desc 须写前置路径）④行为预期有源码/PRD 依据标注
+⑤converted=false 必须带 reason（未迁移/能力缺失/暂不测试）。**blocker 场景不进用例生成**，
+退回宿主 agent 修复。通过后：converted=true 逐场景设计用例
+（按 test_intent 选断言范式）→ 白盒精写 → 执行 → 分诊 → defects/报告。
+用例与场景一一对应，无场景不写用例。
+
+### 1.5 机械扫描（覆盖性评估的补充）
+
+```bash
+python3 $F/scan_features.py $P --out $P/.hypium_forge/features.json
+```
+产出：页面（路由+@Entry）× 交互点 × 状态矩阵 + 权限/登录检测。有安卓迁移现场时
+`merge_appgraph.py --features ... --facts <android>/.migration/spec/facts` 注入权威行为语义
+（handler 链揭示联动场景）。
+
+**定位是补充而非基础**：features 条目是定位事实不是业务功能，机械扫描可靠性不足，
+不得直接作为测试设计输入。两个用途：
+1. **覆盖校验**：对照 scenarios.json，找出未被任何场景覆盖的页面/交互点 →
+   反馈宿主 agent 裁决「补场景」或「登记不测并说明理由」——遗漏即测试盲区；
+2. **ID 预置清单**：交互点列表供步骤 3 preinject_ids.py 机械注入。
+
+覆盖结论写入 `coverage.md`，**双口径分列（防机械冒充功能覆盖）**：
+- **场景覆盖度（主口径）** = 被采纳用例触达的场景数 / scenarios.json 中 converted=true 场景数；
+- **控件触达率（辅助口径）** = 已触达交互点 / 全部交互点——仅暴露机械盲区，**不得单独
+  作为功能覆盖率汇报**（把扫到的控件数当功能覆盖是自欺）；
+coverage.md 逐条列出并按规则处置：
+  - 未覆盖场景（如 WF-12, WF-19）→ 必须反馈宿主 agent 补场景或登记不测；
+  - 未触达交互点（如 HomePage.ad_banner）→ 不一定补用例，人工裁决是否为
+    广告位/运营位/未迁移能力（判定理由随条目记录）。
+未覆盖交互点及其裁决结果。
+
+### 2. 运行时文本采集
+```bash
+python3 $F/collect_runtime_pages.py --device <sn> --bundle <b> --out runtime_pages.json
+```
+脚本引用的控件文本**只允许**来自采集结果；断言锚定业务数据，禁止导航回声断言。
+**并行提速**：首页文本采集完成后即可开始写该页用例（其余页面采集继续）——采集与编写
+流水线并行，禁串行等全量采集完再动笔。
+启动参数门控应用：先 `aa start --ps k v` 预热，singleton 的 onNewWant 不重置状态可继续采集。
+
+### 3. ID 预置（铁律①，先于脚本编写）——机械注入的边界与补强
+```bash
+python3 $F/preinject_ids.py --features features.json --out ids.json   # 交互点清单来自 §1.5
+# 之后 rebuild + uninstall&&install
+```
+批量注入 `tc_<page>_<n>`，产出 ids.json 映射表。脚本定位只认 ids.json/既有 ID（BY.key）；
+仅输入框用 BY.hint。
+
+**静态注入三盲区**（preinject 只扫静态代码，以下场景必然漏注）：
+1. 动态列表控件（ForEach 运行时生成，静态无挂载点）→ 用 `collect_runtime_pages.py`
+   的 dumpLayout 控件树交叉核对：dump 中 key 为空但语义可定位的条目，回填至
+   runtime_pages.json 供 BY.text 兜底并登记例外；
+2. 条件渲染分支（if/else 二选一支路）→ 场景变体执行前先 dump 该分支实况；
+3. 异步加载页（网络数据到位才渲染）→ 依赖步骤 2 采集的等待锚，禁用盲等。
+
+**无 ID 例外审批制**：例外必须三件套——docstring 理由 + runtime_pages.json 中的实测
+证据（该控件确实无 id 且文案唯一）+ lint_locate 通过；例外清单汇总进 coverage.md
+「无 ID 例外」章节备查，审计时逐条复核（防例外变成 BY.text 后门）。
+
+### 3.5 输入契约与空库守卫（宿主 agent ↔ 本 skill 的稳定边界）
+
+**只接受以下输入**：scenarios.json / features.json / ids.json / runtime_pages.json /
+_common_template.py / ArkTS 源码路径。**场景库为空或全部 converted=false 时直接报错
+退出，不生成空用例集**（空跑=伪覆盖）。生成规则见步骤 4；执行后必须产出：
+testcases/*.py、results.json、coverage.md、summary.json、test-report.html、失败截图与 hilog 片段。
+
+### 4. LLM 白盒精写 testcases/*.py（核心）
+
+从 `$F/_common_template.py` 复制为 `testcases/_common.py`（launch 带 `--ps k v` 空格分隔、
+3 轮重试探活、首启弹窗 dismiss、强断言原语全套——**写前必读**），逐条编写 `TCxx_<slug>.py`。
+
+**编写规则：**
+
+- **先读源码**：默认值/联动规则/时序以 ArkTS 源码为准——臆断默认值必返工；
+- **按场景测试目的选断言范式**（问"本场景要证明什么"再选型）：
+
+  | 场景类型 | 测试目的 | 正确断言范式 |
+  |---|---|---|
+  | 资源渲染类 | 图标/文案加载成功 | exist/equals 即目的本身 |
+  | 功能交互类 | 操作产生业务效果 | 效果断言（值变化/计数增减/checked 翻转/absent） |
+  | 配置生效类 | 设置改变全局行为 | 生效链断言（改设置→回业务页→断言输出变化） |
+  | 导航流转类 | 状态迁移到目的地 | 终点效果（城市选中→顶栏变新城市名） |
+  | 状态机类 | 状态转移规律 | 前置态断言→触发→后置态断言（成对） |
+  | 数据输入类 | 输入被正确处理 | 输入→输出值断言（搜索词→结果计数） |
+
+- **强断言比例按 test_intent 分档**（全局硬门禁 ≥30% 整体维持 40~70%；比例是目的的
+  结果不是目标——**禁止加"页面存在/按钮可见"类弱断言凑比例**，单条低于档位下限报
+  "弱断言风险"提示、超上限检查是否断言了实现细节）：
+
+  | test_intent | 强断言区间 | 说明 |
+  |---|---|---|
+  | 资源渲染 | 20~40% | 证明图标/文案/占位正确，exist/equals 即目的 |
+  | 功能交互 | 50~70% | 必须断言业务效果，不能只断言按钮存在 |
+  | 配置生效 | 60~80% | 改设置→回业务页→验证输出变化的完整生效链 |
+  | 导航流转 | 40~60% | 终点页面 + 关键状态都要验证 |
+  | 状态机 | 60~80% | 前置态、触发、后置态成对断言 |
+  | 数据输入 | 50~70% | 输入→结果列表/计数/排序必须验证 |
+
+  核心判据：**断言必须证明场景声明的目的**——目的是"功能发生"时仅判存在 = 无效用例；
+- **Toast** 用 hilog 关键字轮询或 toast_text_seen（dump 轮询）、**剪贴板**用 hdc pasteboard、
+  对话框流转逐步断言；
+- **视口外控件**必须用 `touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 原生滚动查找，
+  禁止手工 swipe + find 循环（时序敏感且不稳定）；
+- **深链路用例内显式 setup**：上游状态准备写成用例内步骤，禁止假设页面已就位；
+- **失败 = 信息**：产品缺陷保持 FAIL 暴露，绝不弱化断言换绿灯；用例自身错误可修（≤2 轮）；
+- **用例数量由功能场景覆盖决定**，禁止固定条数或上限——每个 converted=true 场景至少
+  1 条用例真实触达；**不允许脱离场景新增用例、不允许把页面跳转当最终业务效果**；
+  文本断言只能来自 runtime_pages.json 实采，不能臆造文案；
+- **定位门禁**：`lint_locate.py --dir testcases --ids ids.json`，text 定位 >20% FAIL——
+  LLM 常绕过预置 ID 用 text_click，唯机械门禁有效；
+- 每脚本 docstring 写清行为链与覆盖的功能场景 id；
+- 执行后产出 `coverage.md`（含「总覆盖度: N%」行）与 `summary.json`。
+
+### 4.5 前置条件分组编排（共用前置，提升执行效率）
+
+用例文件声明 `PRECOND`（缺省 anonymous），run_direct 按 **anonymous → logged_in →
+first_launch** 分组排序执行（破坏性递增，bm clean 类强制排尾不再回头破坏登录态）。
+组内软隔离共享前置：`launch()` 默认 `reset_data=False`，preferences 保留 → 组首一次
+完整 `ensure_login`，组内后续幂等复用。组首执行时 `FORGE_GROUP_FIRST=1`。
+results.json 每条附 `group` 字段可分组统计。**禁把 reset_data=True 用在 logged_in 组**。
+
+### 5. 裸跑执行 + 四簇分析 + HTML 报告（重跑阶梯 = 硬规范）
+
+**执行命令阶梯（--all 仅限首轮与门禁升级，修复轮禁无脑全量；违反会被 runner 硬阻断）**：
+> TD-LADDER v3 防护（已内置于 run_direct.py）：**所有"显式全量"（`--all` / `--acceptance` / 变相全量的 `--filter`）统一受管**，
+> 不再给 `--acceptance` 开后门。五条规则（任一命中即 exit 2 阻断并输出指引）：
+> ① **R1** 上轮 results.json 存在 FAIL/SKIP → 必须先修（`--case`/`--retry-failed`），禁止全量；
+> ② **R2** 源码 `srcHash` 与上次全量相同 → 重复全量无新结论（仅拦 `--all`）；
+> ③ **R2b** 上次已是**同源验收**（`lastMode=acceptance` 且 srcHash 未变）→ 拒绝重复验收；
+> ④ **R3** 本修复周期显式全量已达上限（默认 2，`FORGE_FULL_BUDGET` 可调）→ 归零条件是"跑出全绿"；
+> ⑤ **L1** `--filter` 覆盖 >50% 用例 = 变相全量，按全量纳管；**L2** 连续两轮失败签名一致且源码未变 → 拒绝重跑（先 probe 定案）。
+> 免检：`--retry-failed` 因源码变更**自动升级**的全量（非显式，不占预算）；`--force-all` 为显式逃生门。
+> droid2hmos CLI 的 `test harmony --runner python --all` 同步受 R1 防护（`--force-all` 放行）。
+> 实证（Grit）：修复期 15 次全量 212min，其中 **`--acceptance` 被当日常全量跑 13 次 157min（占测试时间 65%）**；
+> `--filter TC0` 当"小全量"跑 7 次；同族失败连卡 5 轮。v3 的 R1 覆盖 / R3 计次 / L1 / R2b / L2 即由此固化。
+> 合法全量收敛为：首轮（无历史）+ 终局验收（全绿后一次）+ 逃生门。
+```bash
+# 首轮全量（唯一常规使用 --all 的场景）
+python3 $F/run_direct.py --all --dir testcases --device <sn>
+
+# 修复轮阶梯（Grit 实证：15 次全量 212min，其中 5 轮卡同一 bug 空转 71min）
+python3 $F/run_direct.py --case <失败用例> --dir testcases --device <sn>      # ① 修测试脚本后单条验证（1-4min）
+python3 $F/run_direct.py --retry-failed --dir testcases --device <sn>         # ② 修产品代码后增量重跑（srcHash 门禁自动升级全量）
+python3 $F/run_direct.py --filter TC3 --dir testcases --device <sn>           # ③ 同族用例子集回归（如 TC30/31/35）
+
+python3 $F/analyze_results.py --results results.json --runtime-pages runtime_pages.json
+python3 $F/forge_report.py    # 产出 test-report.html（Allure 风格：概况/用例卡片/关键截图内嵌）
+```
+铁律：修 1 个用例 ≠ 重跑 24 个。run_direct 汇总后 FAIL>0 会直接打印下一步命令——照抄执行。
+
+**范围回归（touched，产品代码变更后的默认门禁策略）**：
+`--retry-failed` 检测到产品代码变更时不再一律全量——按 `results.meta.json` 的**逐文件指纹**
+diff 出改动集，若全部是 ids.json 可定位的 UI 文件，则只重跑 `FAIL/SKIP + 引用这些文件的用例`
+（用例源码中的 id 字面量 → ids.json 文件映射）。改动含共享逻辑（viewmodel/repository）或
+范围超 60% → 自动退化全量。禁手动 `--all` 替代；`--regression-scope full` 仅用于里程碑。
+
+**热启动（组内软复用）**：组内非首条用例 `FORGE_WARM_LAUNCH=1`，`launch()` 探测 HOME_ANCHOR
+已在位即跳过 stop/start/bootstrap（省 8-12s/例）；组首条与 first_launch 组保持冷启；
+`--case` 单条验证默认热启动（`--cold` 强制冷启）。断言冷启行为的用例写 `launch(d, force=True)`。
+单用例挂死由看门狗截断（`--case-timeout 240` 默认，超时记 FAIL 继续下一条）。
+瞬态失败（watchdog/连接类）轮末自动复测一次（`--flake-retry 1` 默认，断言类失败不
+自动复测防掩盖真缺陷）。**零进展检测**：失败签名集与上轮完全一致时 runner 直接亮牌
+警告——停止重跑转 probe 定案（Grit 实证：同族失败连卡 5 轮全量空转 71min）。
+调试迭代期可 `FORGE_WAIT_SCALE=0.5` 把断言超时减半加速失败复现；正式回归保持 1。
+
+**最终质量门（不可跳过）**：所有优化（范围回归/热启动/flake 复测）只加速迭代期；
+**交付/收尾前必须执行一次验收全量**：`run_direct.py --acceptance`（强制 --all + 全程截图 +
+`.acceptance` 标记永久保护，最近 2 次留存），FAIL=0 或全部 FAIL 已登记缺陷并经 probe 定案。
+范围回归的 PASS 保留记录不作为最终结论——它只是迭代加速器，最终覆盖度以这次验收全量为准。
+
+**截图与 reports/ 留存（防体积失控——Grit 实证 5266 张/666MB）**：
+- 迭代期 `--shots fail`（默认）：PASS 用例只留 `<case>_end.jpeg`，过程帧/分步图仅 FAIL 用例保留；
+  连续相同帧自动去重（静止页 8 帧→1 帧）。
+- **中间运行目录即用即弃**（`--keep-reports` 默认 0）：每轮结束只保留本轮供当轮取证，
+  下一轮自动回收上一轮中间目录；需要跨轮对照时 `--keep-reports 3`。
+- **验收全程留存**：`--acceptance`（最终质量门专用）强制全量+全程截图，目录写 `.acceptance`
+  标记，prune 独立保护**最近 2 次**验收目录，永久作为交付证据。
+**取证一条命令（probe.py，禁手写 UiDriver 内联脚本——Grit 实证 69 次手写探针多花一半时间在代码生成上）**：
+```bash
+python3 $F/probe.py texts|ids|find <id>|tree --grep x     # 单次 dumpLayout 本地解析取证
+python3 $F/probe.py click <id|text>                        # uinput 坐标点击（Toggle 等 touch 失效场景可靠）
+python3 $F/probe.py shot / hilog JSAPP 400 / db-pull <pkg> / db-sql <db> '<sql>'
+```
+
+失败四簇：DEVICE（环境，重跑）/ DESIGN-ERROR（脚本定位/步骤错误，修脚本 ≤2 轮）/
+NAV-CONTEXT-LOSS（页面上下文丢失，hilog 定案）/ ASSERT-FAIL（**优先怀疑产品缺陷，保留 FAIL**）。
+
+**自愈边界（允许 vs 禁止，修≠换绿灯）**：
+- 允许：修正错误控件 ID；补缺失等待条件；修正滚动/输入/弹窗关闭方式；调整用例内前置步骤。
+- 禁止：强断言→弱断言；`equals`→`contains` 规避差异；固定等待无限加长；模糊 text 匹配
+  绕过定位失败；把产品缺陷标 SKIP/PASS；**删除失败断言而不是修复原因**。
+- **FAIL 现场证据自动附言**：run_direct 失败时 msg 自动附带当前页面 Text 摘要
+  （`| 现场Text: …`）——下轮分诊直读证据，禁重复现场取证。
+- **原始失败记录保留**：修复重跑前 run_direct 自动把 results.json 滚动备份为
+  results.prev.json——修复轨迹可审计（改了什么、为什么改），防"驯化测试"。
+- **分诊三律（TD-018，防定案实验失控）**：①**同消息聚类**——多例同错误消息（如
+  text not found: X×N）视为同族，一次分析一次定案，禁逐条重复实验；②**同族定案实验
+  ≤2 次**（清数据/冷启/对照类），超限即按现有证据登记缺陷转人工——保留 FAIL 是合规
+  产出，不是未完成；③**成功模式对照先行**——定案前先查同场景已 PASS 用例的断言
+  范式（如冷启持久化断言），判据升级优先于现场重取证。
+- **修复轮增量重试**：`run_direct.py --retry-failed` 只重跑 FAIL/SKIP 条（PASS 保留
+  原结果合并写出）——禁无谓全量重跑浪费设备时间（首轮 11 条全量 286s，增量仅重跑 2 条
+  ~52s，省 80%）。**编写期自检批量做**：全部脚本写完统一 lint+语法批检，禁逐条单跑
+  调试（单条 LLM 往返间隔是隐形大头）。
+- **增量重试回归门禁（TD-019，防旧 PASS 掩盖回归）**：`run_direct.py` 自动对
+  `entry/src/main/ets` 计算内容指纹（srcHash，存 `results.meta.json` 侧车）。增量重试前
+  重算比对：产品代码有变更 / 无上轮指纹 / 定位不到源码目录 → **自动升级全量重跑**
+  （实证：Profiles TC09/TC14 PASS→FAIL 靠全量重跑才抓到，走增量通道会被旧 PASS 掩盖）；
+  确认仅测试脚本变更可 `--force-incremental` 强制增量。顺带修复：--retry-failed 现写入
+  results.json（旧版误写 results-single.json）。
+
+## 度量与沉淀
+
+- 记录：用例数、覆盖度、耗时、首轮通过率、调试轮次、强断言占比。
+- 失败模式沉淀 testability-requirements.md（可测试性需求）。
+
+## References（按需加载）
+
+| 文件 | 内容 | 何时读 |
+|---|---|---|
+| `references/official-api.md` | Hypium 官方 API 速查（BY 定位/模糊匹配/触摸/滑动/输入/断言 Checker/截图） | 编写脚本前查阅定位与断言 API 用法 |
+| `references/pitfalls.md` | 7 项目实证踩坑清单（swipe 百分比/BY.text 全匹配/press_back 语义/系统子窗口不可见/视口外滚动/DatePicker） | 遇到定位/滑动/输入/Toast 问题时查阅 |
+| `references/functional-spec-template.md` | 功能规格文档模板（9 段结构 + test_intent 选型表 + 边界异常） | 阶段一宿主 agent 产出规格时 |
+| `references/testability-template.md` | 可测试性需求模板 | 沉淀失败模式时 |
+
+## 断言能力速查
+
+| 层 | 能力 |
+|---|---|
+| 存在/消失 | BY.key/id/text/hint/type + absent |
+| 属性状态 | BY.checked/selected/enabled/focused/clickable/scrollable |
+| 值断言 | Checker：equal/not_equal/contains/match_regexp/greater/less |
+| 几何关系 | getBounds()/中心点/相对定位 |
+| Toast/系统级 | hilog 轮询 / hdc pasteboard / 外部跳转 absent 级 |
+| 结构断言 | find_all_components 计数 |
+| 边界 | 颜色/像素 diff/性能时序（勿硬造） |
+
+## 定位原语速查
+
+| 场景 | 原语 |
+|---|---|
+| 已注入 ID | `BY.key(tid)` |
+| 输入框 | `BY.hint('占位符')`（BY.text 命中 hint 节点静默失败） |
+| 底部 Tab | find_all(BY.text CONTAINS) 取最靠下 bounds 中心 |
+| 视口外 | `touch(BY.text("xx"), scroll_target=BY.type("Scroll"))` 原生滚动查找 |
+| mock 数据 | `hdc rport tcp:8787 tcp:8787` |
+
+## 相关 skill
+
+- `hypium-id-test`：无业务语义 ID 冒烟（转化后即跑）
+- `hypium-test-gen`：白盒逐条精写（7 项目踩坑清单）