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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/channel-hishell.md

@@ -0,0 +1,63 @@
+# 兜底：HiShell 手动通道
+
+**适用**：`hdc shell id` = uid2000。hdc 进不去 App 沙箱，跑不了设备 Python。
+
+**平台事实（为什么这条路走得通）不在本文**——归属 `pc-knowledge-base` 的 `platform/鸿蒙PC-不可调试设备用HiShell自动化测试.md`（HiShell 在 App 上下文、`uitest`/`uinput` 原语、IME 默认中文、桌面路径映射，**以及它的 DevBox 前提**）与 `platform/鸿蒙PC-hdc能力边界与取证通道.md`。本文只讲**脚本怎么可靠地用它**。
+
+> **定位：手动兜底，不是首选自动化通道。** 自动化路线是私有 HNP 执行器 HAP（`ohpt-agent scaffold --kind cli-hnp-runner`）——全程 hdc 可驱动、无需 IME 与坐标点击。HiShell 只用于**人工排查**（在 App 上下文里手动看一眼）；**别指望用它拿到设备侧签名工具**——见下。
+
+`/data/service/hnp/bin/` 下的 `binary-sign-tool`/`llvm-objcopy`，hdc 侧 `ls` 一律 `No such file or directory`。**这一个现象有两种成因，别混**：
+- **装了 DevBox 的机器**：工具在，只挂在 app mount namespace，hdc 侧够不着（2026-07-16 实测确认）→ 让 HiShell 去执行。
+- **鸿蒙 PC 商用机**：`/data/service/hnp` 整个目录都不存在，**HiShell 里同样没有**（公共 HNP 在鸿蒙 PC 上不存在，见 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`）。此时**不是通道问题，是根本不需要设备侧签名工具**：ELF 走宿主链接期 `LDFLAGS='-Wl,--code-sign'`，HAP 走 `ohpt-agent sign-demo`，要跑的二进制走私有 HNP 执行器。**"找不到 binary-sign-tool" 不构成阻塞，更不构成换设备的理由**（错误图谱 E129）。
+
+## `hs_exec`：可靠执行（非持久 / 不截图 / 自纠错）
+
+`scripts/hishell_driver.sh`，`source` 后可用。核心机制：
+
+1. 命令写进工作区 `.cmd.sh` + 固定 `.runner.sh`（claim 后跑，把 stdout/stderr/退出码写 `.cmd.out`）
+2. **冷启 HiShell**（`force-stop` + `start`）——保证开窗 + 拿到全新 shell
+3. 切输入法 → 点焦点 → 打**固定短命令** `zsh .../.runner.sh` + 回车
+4. **判定靠文件，不靠截图**，两层：
+   - `.heartbeat` 出现 = runner 自身起来了
+   - `.cmd.out` 出现 = cmd 开跑，等 `__EXIT__=` 即完成
+5. ~15s 内 `.heartbeat` 没出现（IME 乱码 / 没回车）→ 切输入法重发，**最多 5 次**
+6. `.heartbeat` 有但 `.cmd.out` 始终没有 → runner 内部错，拉 `.cmd.out` 看 `NO_CMD`/`CLAIM_FAIL`
+
+**为什么打固定短命令而不是直接打真命令**：真命令可能很长，IME 一乱码就全废且难诊断；固定短串 `zsh .../.runner.sh` 出错概率最低，真命令走文件通道传。
+
+**为什么 IME 要循环重试**：`Ctrl+Space` 是**切换**不是**确保英文**，可能越切越乱。所以不能"切一次就假定英文"，只能靠 `.heartbeat` 反馈闭环——没反应就再切再发。
+
+## 工作区：桌面下的隐藏目录
+
+桌面是 hdc 与 App **唯一**的双向桥（App 的 Documents/Download/tmp 都是沙箱私有，hdc 看不到）。故用 `.pc-adapt-verify/`——双向可读写、又不污染可见桌面。
+
+- App 视角：`/storage/Users/currentUser/Desktop/.pc-adapt-verify/`
+- hdc 视角：`/storage/media/$HS_USERID/local/files/Docs/Desktop/.pc-adapt-verify/`
+
+`hs_init` 建它并**校验**、`hs_push`/`hs_pull` 自动收发、`hs_clean` 清掉。改路径调 `HS_WORK_NAME`。
+
+**`HS_USERID` 因设备而异**（常见 100）。要改就在 `source` **之前** `export HS_USERID=<值>`；不确定跑 `hs_probe_userid`。`hs_init` 会先验桌面存在再 `mkdir`——**顺序不能反**：`mkdir -p` 会把不存在的父目录一路造出来，userId 写错时会在 `/storage/media/<错值>/` 下凭空长出垃圾树，事后再查"目录在不在"永远是"在"（实测 `HS_USERID=999` 照样 mkdir 成功）。
+
+## ⚠️ 本 driver 的已知弱点：静默吞错
+
+`hishell_driver.sh` 里几乎每个 `hdc` 调用都挂着 `>/dev/null 2>&1`，而 **`hdc shell` 即使远端命令失败通常也返回 0**——两者叠加 = 失败被伪装成正常。目前只有 `hs_init` 做了显式校验。**排查诡异现象时，先把可疑那行的重定向去掉再跑一遍。**
+
+同类坑（都实测踩过，非理论）：
+- 宿主机 `diff` 被 DevEco stub（`.../toolchains/diff`）抢占 PATH，对**不同**的文件返回空 + exit 0 → 用 `/usr/bin/diff`。见 `pc-knowledge-base` 的 `adaptation/鸿蒙PC-autotools-C二进制-goaccess.md`。
+- `llvm-readelf` 宿主机默认不在 PATH（在 `$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin/`，见 `pc-knowledge-base` 的 `SKILL.md`「定位 DevEco SDK」），叠个 `2>/dev/null` 就把"工具不存在"伪装成"没匹配到"。
+
+## 宿主机侧的坑
+
+| 坑 | 现象 | 解 |
+|---|---|---|
+| **hdc 路径被 MSYS 改写** | `path:D:/Program Files/Git/storage/...` | Git Bash 调 hdc 加 `MSYS_NO_PATHCONV=1`（driver 已内置）；本地 wheel 用反斜杠 Windows 绝对路径 |
+| **CRLF 换行符** | 推送的 `.sh`/`.py` 含 `\r`，zsh 报 `command not found`/语法错，heartbeat 不出现 | 确保 LF；PowerShell 用 `[IO.File]::WriteAllText()` 而非 `Set-Content`（后者写 CRLF）；driver 用 `printf`/`echo` 生成临时文件天生 LF |
+| **macOS AppleDouble** | 打包/推送带出一堆 `._*` 伴随文件 | `COPYFILE_DISABLE=1 tar -czf ...` |
+
+## 为什么不用别的方式（都实测否决）
+
+- `aa start -U file://脚本 -t general.shell-script`（viewData）：**只打开不执行**。
+- `aa start --ps cmd ...` 等命令参数：HiShell **不接受**。
+- 改 `~/.zshrc` 装看门狗：零输入，但**持久化改设备配置**，需显式授权。
+
+所以 `hs_exec` 是目前**唯一非持久、可自纠错、不靠截图**的可靠通道。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/cli-batch-exec.md

@@ -0,0 +1,65 @@
+---
+description: 在真机批量跑交叉编译的测试 ELF 的可复用模式：EXTRA_BIN/EXTRA_LIB/EXTRA_DIR 打包私有 HNP + per-case cwd 契约 + 90s 看门狗 + TAP 实时 hilog 回传。libetpan 37 测试 ELF 一次装机逐案真跑实证。
+---
+
+# cli-hnp-runner 多二进制批量测试执行法
+
+## 适用场景
+
+官方测试套件有 **30+ 个独立测试 ELF**（如 libetpan 的 `unittest/` 29 个 + `tests/` 8 个 + 补写用例），需要在真机 app 域逐条 `fork/execv` 执行并拿到逐条判定。
+
+## 打包契约
+
+私有 HNP 的打包分三类：
+
+| 类型 | 内容 | 打包参数 |
+|------|------|---------|
+| 测试二进制 | 全部测试 ELF（含依赖 .so 的同名兄弟） | `EXTRA_BIN`（38 项） |
+| 依赖动态库 | 被测试 ELF `NEEDED` 的 .so（如 libetpan.so.26、libxml2.so.16、libsasl2.so.3、libjson-c.so.5） | `EXTRA_LIB`（4 项） |
+| fixture 树 | 测试读取的相对路径数据（mbox/mime/imap/smime 数据） | `EXTRA_DIR`（整棵树） |
+
+> **SONAME 别名坑**（案例实证）：被测试 ELF 的 `DT_NEEDED` 写的是 **SONAME**（主版本号，如 usbredir 的 `libusbredirhost.so.1`），但交叉编译产物的文件名是全版本 `libusbredirhost.so.1.0.3`。动态链接器按 SONAME 找 `libusbredirhost.so.1`，lib 目录里只有全版本名时就报 `Error loading shared library libusbredirhost.so.1`。**EXTRA_LIB 里必须额外落一份 SONAME 别名**（把全版本文件再按 SONAME 名拷一份进 `pkg/bin`）。核对方法：打包前用 `llvm-readelf -d <bin>` 看 `NEEDED` 列表，逐条对 pkg/bin 里的文件名；glib/libusb 的 SONAME 恰好等于文件名（`libglib-2.0.so.0`）所以不用别名，**只有主版本号形如 `.so.N` 的库（libusbredir*、libetpan.so.26 等）要补**。
+
+> **漏收 EXTRA_BIN = rc=127 全挂**：测试 ELF 已成功交叉编译、确认在宿主产物目录，但没列入
+> EXTRA_BIN → HNP bin/ 里根本没有该文件，execv errno=2 → 该用例 rc=127（某国密 OpenSSL 分支 33 个测试
+> 子二进制补齐 EXTRA_BIN 后 rc=127 全部消除，2026-09 实证；同症状不同场景见 E158——
+> 判别分叉点：装机后 `hdc shell ls /data/app/bin/` **看不到**文件 → 查打包清单（本坑），
+> **看得到**但 exec 不中 → 查 exec 名与打包名是否一致（E158 主场景））。
+
+⚠️ **fixture 树是最大返工源**：测试内部用相对路径 `fopen`（如 smime 用 `unittest/mime-parser/data/input/mbox/jwz/...`，imap 用 `data/response-data/...`）。staging 前先静态 grep 所有 `fopen/open` 的相对路径，把树一次性收全，避免设备上三轮迭代补目录。
+
+## per-case cwd 契约
+
+HNP 内是 `/data/app/bin/<tool>` 与平铺的 fixture 树。不同测试的 fixture 根不同（smime 以 `ut/` 为根、imap 以 `ut/imap` 为根、imf/mime 以 `ut/` 下 `data/` 为根）——**kCases 表里每条用例带 `cwd` 字段**，执行器先 `chdir(cwd)` 再 fork。staging 时按用例表把对应 fixture 子树放对位置，别靠猜。
+
+## 执行与取证
+
+```
+for each case in kCases:
+    pid = fork()
+    child: chdir(cwd) + execv("/data/app/bin/<tool>", argv)
+    alarm(90)                    # 看门狗防网络用例挂死
+    waitpid → 退出码
+    TAP 逐条实时 hlog()          # 不要跑完一锅端——hilog 缓冲会滚失
+```
+
+- 每条用例独立 90s alarm 看门狗
+- ⚠️ **app 域平台看门狗比 90s alarm 更狠**：app 域线程阻塞 >3s 触发 `THREAD_BLOCK_3S`、
+  持续到 6s 触发 `THREAD_BLOCK_6S`，随后 appfreeze（HiCollie/FreezeManager）`processExit:1`
+  直接杀进程（mpg123 实证：`build/test-device-tap-rerun3.log` PID 连环 3S→6S→退出）。
+  **单条用例墙钟预算按 <3s 设计**：>6s 的用例（长扫频+重采样、噪声表生成、大数据集基准）
+  在 app 域跑不完——设计期就拆成短耗时子测试，或取证豁免（platform-exclusive-fixture，
+  附看门狗日志佐证），别等设备上被杀三轮才认。
+- TAP 结果行**逐条实时**打 hilog（`Tap::add` 即时 hlog），否则长套件输出会把早先的 TAP 行挤出缓冲（见 SKILL.md 慢用例捕获节）
+- 证据：`hilog -x -P <pid>` 或整段 grep 回传；`tap-rN.txt` 留存
+- 整体跑法：`ohpt-agent sign-demo --demo-dir test-demo --install` → `hdc shell aa start -a EntryAbility -b <bundle> -m entry --ps ohptRun all` → 轮询结果行
+
+## 实测规模（libetpan）
+
+37 个测试 ELF + 4 依赖 .so + fixture 树 → 31 条名册用例（扣除豁免）90s×31 ≈ 30s 跑完，四轮设备迭代收敛（R1 暴露 exec 通道 E129 + staging 缺失、R4 达 30/31）。
+
+## 关联
+
+- E129：私有 HNP + 执行器 HAP 是设备侧 exec 用户二进制的唯一通道
+- E134：HNP zip 布局（pkg 前缀/目录条目顺序）
+- `pc-device-verify/SKILL.md`：慢用例轮询三停模式、设备租约

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/domain-hdc-shell.md

@@ -0,0 +1,68 @@
+# 域：hdc shell（uid 2000）——能做什么、够不到什么
+
+**鸿蒙 PC 上 `hdc shell` 恒为 `uid=2000(shell)`**，这是常态不是异常。本篇讲这个域里能干什么、
+边界在哪；能力边界的权威在 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`，
+这里只讲**验证工作怎么在这个域里落地**。
+
+通用取证/执行/传文件走 `ohpt-agent device`（exec 零宿主转义、files 自动探 userId，动词表 `ohpt-agent device`）。
+
+## 先确认
+
+```bash
+hdc list targets                    # 有目标
+hdc shell id                        # uid=2000(shell)
+hdc shell "uname -m"                # aarch64
+hdc shell "param get const.product.software.version"
+```
+
+## 这个域够不到的三件事（都是**结论**，不是待试探项）
+
+| 想做 | 结果 | 该走哪条 |
+|---|---|---|
+| 读应用沙箱 `/data/app/el1`、`/data/app/el2` | Permission denied | 让应用自己把东西写出来（hilog / 公共目录），见能力边界篇 |
+| 在 `/data/local/tmp` 里执行二进制 | 可写但 **noexec**（Permission denied） | 打成**私有 HNP** 随执行器 HAP 装机，app 域 `fork/execv`：`ohpt-agent scaffold --kind cli-hnp-runner` |
+| 用设备上已装的运行时（Python/JDK/node） | 公共 HNP 不存在（`/data/service/hnp` 无此目录）；别的 App 私有 HNP 在人家沙箱里 | **随交付物自带**成私有 HNP |
+
+> **不要为这三条再写试探代码**。它们是平台属性，不因库而异；试探的唯一后果是把
+> 「我没探到」写成「设备上没有」——那是 git-lfs / jansi 那类假前提的来源。
+
+## 代码签名：**一律要签**
+
+鸿蒙 PC 强制代码签名，未签名 `.so` 加载报 `Permission denied`（`chmod` 无用；设备自带扩展
+`llvm-readelf -S <so> | grep -i codesign` 能看到签名段）。两条签法：
+
+- **链接期自签（默认首选）**：`LDFLAGS='-Wl,--code-sign'`。注意 post-link `strip` 会破坏签名段。
+- **设备自签**：装了 DevBox 的设备，HiShell PATH 上有 `binary-sign-tool`，`-selfSign 1` 自签后可被该设备接受。
+
+装 **HAP** 是另一套（PKCS7 profile 信任链，自签必拒 `code:9568257`）：用 `ohpt-agent sign-demo`，
+见 `pc-knowledge-base` platform/鸿蒙PC-HAP调试签名与设备安装信任链.md。
+
+## 可写目录三件套（**与权限档无关，认域不认路径**）
+
+shell 域下 `/` 和 `/root` **只读**，跑任何 Python/工具前必须把三件套指到 `/data/local/tmp`：
+
+```
+TMPDIR=/data/local/tmp  HOME=/data/local/tmp/home  MPLCONFIGDIR=/data/local/tmp/mpl
+```
+
+`device_verify.py` 已自动处理，且**故意不用 `setdefault`**——`hdc shell` 会把 `HOME` 预设成 `/root`，
+`setdefault` 见 key 已存在就跳过，等于没设。实测报错就是
+`OSError: [Errno 30] Read-only file system: '/root'`。权威：`pc-knowledge-base` 的
+`platform/鸿蒙PC-设备pip部署.md`。
+
+> 反过来：**app 域绝不能**指到 `/data/local/tmp`（那是 shell uid2000 的地盘，app 写不进去），
+> app 域要用自己的沙箱可写区。两个域各有各的可写路径，**认域，别认路径**——
+> 这条与设备权限无关，永远成立。
+
+## 取证：日志为空多半是姿势不对，不是没跑
+
+```bash
+hdc shell "hilog -b D"                    # ① 提级别（商用机默认 W，应用 INFO 写入时即被丢）
+hdc shell "aa force-stop <bundle>"        # ② 冷启动（已在跑的应用 aa start 只切前台，不重打日志）
+hdc shell "hilog -r"                      # ③ 清缓冲
+hdc shell "aa start -a <ability> -b <bundle> -m entry"
+hdc shell "hilog -x -P <pid>"             # ④ 按 pid 取
+```
+
+顺序不能换。等价物是 `ohpt-agent verify-demo`（内置这套顺序并产出 `log_channel` 通道健康字段）。
+`/data/log/faultlog` 在本域 **Permission denied**——**取不到 cppcrash 不等于没崩**，崩溃线索从 hilog 找。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/failure-triage.md

@@ -0,0 +1,164 @@
+# 失败归因
+
+## 铁律：失败先分四类，别一律当"库坏了"
+
+1. **真实平台缺陷**——被测库在鸿蒙 PC 上真算错/崩。要修或记已知限制。
+2. **测试框架/环境**——pytest 版本、缺可选依赖、fixture、只读目录、属主校验。换环境就过。
+3. **交叉编译测试产物**——测试硬编码构建机路径、需要在 host 跑的东西。结构性，非功能缺陷。
+4. **语义分歧**——断言的平台特定字面量（错误文案/字节序列/换行处理/多字节编码行为）来自 BSD/glibc，而鸿蒙 musl 行为不同。产物无缺陷，按 [[鸿蒙PC-musl与BSD-glibc语义分歧表]] 改测试预期。
+5. **用例本身写错**——**只可能发生在补写用例上**。上面四类都预设「预期来自一个可信来源」（上游测试/平台手册），因为它们是为**上游用例**设计的：上游用例在原平台是绿的，不会写错。阶段 2 补写的用例没有这个背书，预期可能就是补写时的臆断。判据是 02-baseline 名册的 `validation`：只有 `unvalidated`（补写且宿主跑不了、无从自证）才可归此档；`self-validated`（宿主跑过并通过）与 `upstream-backed` 的断言都有背书，别拿这一档当出口。
+
+**为什么这条是铁律**：`pc-knowledge-base` 的 `platform/鸿蒙PC-真机跑官方测试套件.md` 记载，9 个库 ~6100+ 官方用例真机跑下来，**曾以为的"唯一真实平台缺陷"（PyWavelets 复数 CWT，4/1037）后来被定位为设备 numpy 的 OpenBLAS bug**——即第 1 类实为 **0**。一上来把 `FAILED` 当真实缺陷，方向就反了。第 4 类同理：一次 C 实用函数库的外部一致性测试实证，72 个 FAIL/CRASH 里语义分歧与测试前置限制占六成——真产物缺陷只是少数，但混在同一张脸上。
+
+误差"**巨大且只错一半（实部对/虚部错，或反之）**"是**粗错信号**，别归因成"精度漂移"——必须上真机量出实际数字。
+
+## 第 0 步（先于四类分诊）：预期来源是否过时
+
+测试同学/人工报「实际与预期不符」时，**先花 10 秒查 demo 展示的预期是不是旧的**，再进四类
+分诊——阶段 5 修正过用例（amendment）而 demo 未重新生成时，页面显示的仍是修正前文案，按旧
+文案判 FAIL 是提单根因而非产物问题：
+
+```bash
+ohpt-agent check -w <workspace> --stage 6
+```
+
+- 命中 `demo-casetable-synced`（cases-sha256 不一致）→ 重跑 `ohpt-agent scaffold --test-cases …`
+  同步 demo 用例表，重新构建装机再看——预期对齐后多数「不符」消失（libidn2 F-01-03 实证，
+  2026-09：机器判定读 hilog check 行全绿，只有 demo 页面停留旧文案，逃过了全部机器链路）。
+- 命中 `step-input-controls-present`（输入框缺失）→ 同步重生成后测试同学才能按步骤操作。
+
+这一步只适用于**测试线 demo 的人工反馈**；机器跑批的 FAIL 直接进四类分诊（hilog check 行用的
+就是当前预期，不存在漂移）。
+
+## 行为分歧三向对照（第 4 类的判定程序）
+
+断言失败、怀疑是语义分歧时，**按序执行、命中即停**：
+
+0. **先核对两个载体链的是不是同一份产物**（某图像库 2026-09 实证）：当「hap 载体（NAPI dlopen）与
+   cli 载体（HNP exec）对同一 API 表现分歧」时，先问——两载体加载的 `.so` 是**同一份**吗？
+   某图像库 案例：demo 用了 `dist/lib/lib某图像库.so`（**动态链 libz**），设备侧 aarch64 `libz.so` 是
+   **stub（所有符号空实现）** → `decompress_stdlib()` 解压失败 → stdlib 全空 → stdlib 专属命令
+   全部「无法识别」；而 stage 3 HNP exec 用的是 `dist/hnp/pkg/bin/lib某图像库.so.1`（**静态链 zlib**），
+   同一条 `flower` 命令可用。于是同一库被误判为「behavior-divergence / missing-capability」——
+   真因只是**产物选型不一致**：动态链版本在设备侧解析到 stub 依赖。修法：两载体统一用静态链
+   依赖（或从设备 pull 真 `.so`）的同一份产物。判据：`llvm-readelf -d <so> | grep NEEDED` 看
+   动态依赖闭包；动态依赖命中 NDK sysroot 桩库（`llvm-nm -D` 全符号同址）即嫌疑。
+1. **先查该 API 是库自带实现还是 libc 提供**（`readelf --dyn-syms` 查产物导出面与 sysroot libc）：库自带 → 预期按其源码；libc 提供 → 预期按 musl。
+2. **diff 上游实现**（`git -C source/ diff` 或对 upstream commit）：实现与上游有差异 → **产物缺陷**（编译配置/补丁引入），修产物。
+3. **实现一致而预期来自其他平台**（BSD/glibc 的 man 手册或上游测试）→ 查 musl 对应行为（musl 源码/手册；NDK sysroot 无源码时查 musl 上游仓库对应版本），定位到行为点 → **语义分歧**，改测试预期并把分歧补进 [[鸿蒙PC-musl与BSD-glibc语义分歧表]]（预期修正必须留证——「改预期」若不附分歧证据，就是掩盖产物缺陷的后门）。
+4. 前三步都不命中，而该用例是**补写且未自证**的（名册 `validation=unvalidated`）→ 回头读被测 API 的契约（头文件声明/上游文档），确认**预期本身**写对了没有 → 写错了就是 `testcase-defect`，修用例后重跑（仍要求通过）。
+5. 查不动 → **unknown**，如实登记（03-adapt.json 的 `test_run.failures[]` 分诊语义见 enum-semantics）。**不要猜一个良性归因蒙混**。
+
+> **改测试预期这个动作要留痕**：`resolution=fixed-test` 必须填 `amendment`（改动类别 / 依据 / 改前改后），依据要指得回 musl 源码行、分歧表条目或上游 issue。「产物有缺陷但改测试让它过」这条路已由 schema 直接堵死（`product-defect` + `fixed-test` 非法）。
+
+## missing-capability 归因的证伪程序（判 blocked / 能力缺口前必过）
+
+把失败判成「平台缺能力」（`suspected_cause=missing-capability`、`capability_gaps`、remaining_blockers
+写「平台不支持」）是**最贵的归因**——它把可修的集成工作误标为不可修：主线不再修、测试线只能
+blocked 收场，而真相往往只是一处接线或一处没做的移植。判之前过三道证伪，**全部不命中才可判**：
+
+1. **同路径旁证**：同一套件里有没有别的用例**经过同一条内部路径**且已通过？有 →「该路径不可用」
+   被证伪，失败在接线或用例设计层。2026-09 某播放器库实证：截图到**文件**用例经软件取帧路径
+   通过，截图到**内存**用例却判「无帧缓冲、平台能力缺口」——同路径旁证直接证伪了缺口结论。
+2. **API 形态核对**：失败用例的接线假设与上游 API 的交互模型一致吗？**命令（请求-响应：结果经
+   调用同步返回）被当成属性（观察-事件：等事件送达）**时，事件永远不来，失败形态恰好像
+   「能力缺失」。判据在上游源码的命令/属性注册表，`file:line` 实证；命令类结果必须从调用的
+   返回节点读，观察通道对命令名不生效（pc-test-design §九「请求-响应与观察-事件型 API
+   不得混接」红线同源）。
+3. **sysroot 能力在位核查**：被「缺」的能力是不是系统能力？查 NDK sysroot 的
+   `usr/include/<域>/`（头文件）与 `usr/lib/aarch64-linux-ohos/`（链接库）——**在位 = 平台能力
+   在位，缺的只是集成**（主线移植活：写后端、接构建系统），不是平台缺口。别把「本轮构建没
+   集成」上报成「平台没有」。
+
+三道都不命中，再问一句：**该能力此前在别的库上接通过吗**（`pc-capability-domains` 各域方案库 +
+个人知识库 `ohpt-agent knowledge -s` 检索）——接过 = 照方抓药重开主线；没接过 = 如实 blocked，
+且 blockers 里写清缺的**具体是哪一层**（头文件 / 链接库 / 系统服务 / 权限 / 集成），禁写笼统的
+「平台不支持」。
+
+## fast-path + fallback：syscall 被沙箱拦时的三级回退决策树
+
+上游代码呈「fast-path（新 syscall）+ fallback（老路径）」结构、fast-path 被 app 域 seccomp 拦（SIGSYS）时，**按序取第一个可行的**：
+
+| 级 | 手段 | 适用 | 实证 |
+|---|---|---|---|
+| ① | **patch 宏/分支选择，编译期强制走 fallback** | 源码有 `#if defined(SYS_xxx)` 式 fast-path 守卫 | closefrom：`SYS_close_range` 分支 patch 掉 → 走 /proc/self/fd 遍历，app 域获得全功能 |
+| ② | 运行时开关关掉 fast-path | 库有环境变量/参数 | libuv 类库的 io_uring 开关（注意有的构建不尊重该变量，须实测） |
+| ③ | LD_PRELOAD 拦 `syscall()` 对受限号返 `ENOSYS`，触发库自身回落 | ①②都没有 | OHOS Node 的 io_uring shim（见 [[鸿蒙PC-app域执行二进制与JIT限制]] 关卡②） |
+
+**验证降级（只取函数地址验证符号可解析、不实际调用）只是三级都不通时的兜底**，且必须在日志透明记录被挡的 syscall 号——不能当第一反应，否则产物带着 app 域功能缺陷照样交付。受限 syscall 名单与定位套路见 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+
+## 症状分流
+
+| 症状 | 判据 | 归属 |
+|---|---|---|
+| `ImportError: ...so: Permission denied` | 零售机**强制**代码签名（`chmod` 无用）。对照：同环境自带扩展有 `.codesign` 段能加载 | 签名。鸿蒙 PC 一律强制签名，**没有免签的机器**。**默认解法：回宿主用 `LDFLAGS='-Wl,--code-sign'` 重新链接**（post-link `strip` 会破坏签名段）；设备侧 `binary-sign-tool -selfSign 1`（签前 `llvm-objcopy --remove-section .codesign`）**只有装了 DevBox 的机器才有**，商用机没有。权威见 `pc-knowledge-base` 的 `SKILL.md` "签名"节 |
+| import 时**裸 SIGSEGV、无任何输出**（进程直接没） | 先看日志里 `device_verify.py` 留的页对齐名单 | **对齐只是嫌疑，不是判据**——见下 |
+| 复数结果诡异 / numpy 系库**成片**失败 | `np.dot(a,b)` vs `np.sum(a*b)` 差 ~1e-3+ **且只错实部** | OpenBLAS armv8sve bug → `OPENBLAS_CORETYPE=ARMV8`。权威：`pc-knowledge-base` 的 `adaptation/鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug.md` |
+| 一片 `NoneType` 假失败 | 库用 nose 风格 `setup()`，pytest 8+ 已移除（设备预装 **9.0.3**） | 钉 `pytest==7.4.4`。第 2 类 |
+| `OSError: temporary directory ... is not owned by the current user` | pytest tmp 属主校验，`*_pickle` 类用例 setup error | `--basetemp=<WORK>/_pt_<PKG>`（脚本已带）。第 2 类，**非功能失败** |
+| `PermissionError: '/data/local/tmp/...'` | **域搞反了**：App 域写不了 shell(uid2000) 的目录 | 认域不认路径，见 `references/domain-hdc-shell.md` 的「可写目录三件套」 |
+| `[Errno 30] Read-only file system: '/root'` | 反向域错：root 域 `/root`、`/` 只读 | 同上 |
+| 少数用例失败、可选依赖缺失（如 slycot） | 属环境 | 能装就装，不能装就 `--deselect`/`--ignore` **并在报告里说明**。第 2 类 |
+| 测试硬编码构建机路径（`CARGO_MANIFEST_DIR` 等） | 跨机执行的结构性失败 | 第 3 类，**不是功能缺陷**，报告里注明 |
+
+## 页对齐：嫌疑信号，不是判据
+
+`p_align=0x10000`（64KB）曾被判为"在 4KB 页设备上 dlopen 必崩"。**该判定已被证伪**（2026-07-16 实测，HongMeng 6.1.0.117）：该机页大小 4096，而自带 Python 栈 **418 个 `.so` 里 345 个就是 64KB 对齐**，numpy（19/19 全 64KB）、ctypes、ssl、`_decimal` **全部 import 正常**。
+
+所以：
+
+- **绝不能**因为 64KB 就拒绝一个库——那会误杀 numpy 这类完全正常的库。`device_verify.py` 据此只**留证不拦截**。
+- 但它仍是**唯一能在 SIGSEGV 后回溯的线索**：`p()` 每次都落盘，进程被打死时名单已在日志里。
+- 真实成因**未定论**，别臆造规则。
+- 若确认某库确因此崩：`-Wl,-z,max-page-size=0x1000` 重链（**`patchelf` 改不了 `p_align`**）。权威：`pc-knowledge-base` 的 `platform/鸿蒙PC-64KB页对齐so崩溃.md`。
+
+## 排查时先怀疑工具本身
+
+本 skill 的调试里**实测踩到两次**"工具静默失败伪装成阴性结果"：
+
+- 宿主机 `diff` 被 DevEco stub 抢占 PATH，对**不同**的文件返回空 + exit 0 → 一律 `/usr/bin/diff`。
+- `llvm-readelf` 宿主机默认不在 PATH（在 `$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin/`，见 `pc-knowledge-base` 的 `SKILL.md`「定位 DevEco SDK」），叠个 `2>/dev/null` 就把"命令不存在"变成"没匹配到"。
+
+同理 `hishell_driver.sh` 里满是 `>/dev/null 2>&1`，而 `hdc shell` 失败也常返回 0。**诡异现象排查第一步：把重定向去掉再跑。**
+
+## HAP 应用侧日志与崩溃取证：走 `ohpt-agent device`，不裸拼 hdc
+
+demo/app「拉起没反应 / 白屏 / 闪退」→ **`ohpt-agent device triage -w <ws> [--bundle] [--shot]`** 一条命令取齐（进程/hilog/cppcrash/应用侧输出文件 → `build/triage.json`）；单项用 `ohpt-agent device log|crash|files|ps|shot`，设备执行/传文件用 `ohpt-agent device exec|send|recv`（`ohpt-agent device` 看动词表）。重新拉起：`hdc shell "aa start -a EntryAbility -b <bundle>"`。
+
+- **为什么必须走它（历史实测坑，每个都吃过）**：hilog 过滤在宿主管道里做会被 shell 抢先解释（连败 6 次，正确姿势是 hilog 自身 `-e`）；应用私有目录的 userId 因设备而异不可硬编（device files 自动 glob 探测）；`exec` 让命令零经宿主 shell，管道/引号/`$变量` 全按设备侧语义（`PY=<路径>` 尖括号语法错案即此类）。
+- Python 类崩溃最常见根因：stdlib 不全（缺 `encodings` = Py_Initialize 即崩）或扩展 .so 放进 resfile（不可执行映射，dlopen 失败）——落位铁律见 OWB `owb_ohos_python_app.h` 头注释。
+## process-gone 无结果行：启动期死亡 vs 用例崩溃，先复现取证再归因
+
+per-case 轮询里 `waited_ms ≈ 4000` 且 `stopped_by=process-gone` 的含义是：**首个 pid 检查（4s 冷启动窗后）就没进程**——进程在启动早期（EntryAbility.onCreate 前）就死了，或者 pidof 抖动。**不能直接归因「用例代码崩溃」**，usbredir F-03-05 实证两种真因都披着同一个症状：
+
+1. **hilog 环形缓冲逐出**：`hilog -G 16M` 下系统日志（render_service/appspawn 每秒数百行）几分钟就能把 cmd= 等应用早期行冲掉——「raw log 里没有 cmd= 行」≠「没走到 onCreate」。per-case 轮询窗口里抓不到 ≠ 没打过。
+2. **force-stop 与 aa start 竞态**：AMS 还持有旧进程记录时拉起（hilog 里 `coldStart:0` + 新进程照常 spawn），新进程可能被启动期清场杀掉——一次性、换条用例对照拉起即可判「caseId 特异 vs 环境抖动」。
+
+**权威取证法**（绕开环形缓冲）：
+
+```
+hdc shell "aa force-stop <bundle>"
+hdc shell "hilog -r"      # 清场 + 清缓冲
+hdc shell "aa start -b <bundle> -a <ability> --ps caseId X"
+# 2s 内立刻全量拉取：
+hdc shell "hilog -x" > crash-window.log
+```
+
+在这份日志里找两层证据：
+
+- `C02D11/processdump` / `C02D11/DfxSignalHandler`——崩溃转储全过程；
+- `C01336/foundation/AMS: app_exit_reason_data_manager`——含权威描述，如
+  `Signal:SIGSEGV(SEGV_MAPERR)@0x0000000000000008 probably caused by NULL pointer dereference`。
+  `/data/log/faultlog/temp/` 的 cppcrash 文件 shell 域 `hdc file recv` 拉**不动**（permission denied），hilog 里的这两层就是可用的完整证据。
+
+## fork 无 exec 隔离是放大器：受阻归因平台/载体前，先做进程内直跑对照
+
+HAP demo 里用 `fork()`（无 exec）隔离子进程跑崩溃风险用例时，**子进程被信号杀死 ≠ 载体/平台不行**：多线程 ArkTS 进程 fork 出的子进程继承整张进程状态（ArkRuntime/GC/hilog 锁与 EH 现场），一条本可恢复的错误传播路径（如 Lua 断言失败、绑定层异常）撞上继承来的不一致状态会被放大成 `foreign exception` → SIGABRT，把「用例代码/接线 bug」掩盖成「hap-dlopen 载体 EH 限制」的假证据（错误图谱 E167 实证：两条受阻用例进程内直跑均不崩，真因是断言写错与默认实现接线错；`cli 载体过、hap 载体崩` 的差异在 fork 语义而不在 dlopen）。
+
+处置纪律：
+
+1. demo 侧给隔离机制留**进程内直跑旁路**（如 caseId 前缀开关），受阻用例先跑对照——直跑也崩才是载体/平台问题，直跑不崩就去查用例与接线。
+2. per-case 拉起的 harness（`aa start --ps caseId` 逐条拉起）本身已提供崩溃隔离，fork 隔离不是必须的；保留 fork 隔离时，其崩溃结论必须经直跑对照复核再写进 `capability_gaps`。
+3. 与 E165 同一铁律：先代码、后平台；归因写进产物前要有对照实验证伪。
+
+**归因后是 UB 隔离的坑**：按 pc-test-design §九红线做「fork 子进程执行 UB 调用 + 父进程 waitpid 观测」时——fork 出的子进程崩溃后，faultlogger/processdump 对这个「继承自多线程 ArkTS 进程的孤儿态」的转储可能**无限期不完成**（实测阻塞 waitpid 121s，用例超时而主进程不死）。隔离代码必须 **WNOHANG + ~1.2s 时限 + SIGKILL 兜底**，超时把 SIGKILL 也当作一种合法观测形态（转储挂起本身就是无守卫平台的伴生事实），保证用例 <3s 预算内必出结果行。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/hap-verify.md

@@ -0,0 +1,231 @@
+# GUI 应用（HAP）设备验证详指
+
+> 本文件是 `pc-device-verify` skill 主文档「GUI 应用（HAP）验证」节的深度展开。主文档定义必检三步，本文件覆盖崩溃排查全流程。
+
+## 为什么「启动 ≠ 存活」
+
+`hdc shell aa start -a <ability> -b <bundle>` 返回 `start ability successfully` 只说明 AMS 创建了 Ability 进程。以下所有场景都能让 `aa start` 返回成功，但应用实际上已崩溃：
+
+| 场景 | 崩溃时机 | `aa start` 返回 |
+|------|---------|----------------|
+| Qt 信号→信号无限递归（stack overflow） | 启动后 0.5~2 秒 | 成功 |
+| 主窗口构造函数空指针 | 启动后 <0.5 秒 | 成功 |
+| dlopen 失败（.so 缺失） | 启动后 <0.1 秒 | 成功 |
+| Qt 内部断言失败 | 启动后 0.5~3 秒 | 成功 |
+
+**结论**：`aa start` 成功 ≠ 应用可用。必须做存活检查 + 崩溃日志排查。
+
+## 崩溃日志获取
+
+### 方法 1：hilog 实时过滤
+
+```bash
+hdc shell "hilog -b D"                       # ① 先提级别：商用机默认 W，应用 INFO 写入时即被丢
+hdc shell "aa force-stop com.qt.ohos.app"    # ② 必须冷启动，否则不重走 onCreate、不重打日志
+hdc shell "hilog -r"                         # ③ 清空旧日志
+hdc shell aa start -a QAbility -b com.qt.ohos.app
+sleep 3
+PID=$(hdc shell "ps -ef | grep com.qt.ohos.app | grep -v grep" | awk '{print $2}')
+hdc shell "hilog -x -P $PID"                 # ④ 按 pid 取本应用全部日志
+hdc shell "hilog -x -P $PID | grep -iE 'SIGSEGV|SIGABRT|signal 11|signal 6|FAULT|cppcrash|stack-buffer-overflow'"
+```
+
+**①②③④ 顺序不能换**——少了 ① 或 ② 就会拿到空日志，而空日志极易被误读成"应用没跑/适配造假"。
+机制见 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`；等价物是
+`ohpt-agent verify-demo`（内置该顺序 + `log_channel` 通道健康字段）。
+
+**局限**：仅含摘要信息（信号类型），不含完整调用栈；按 pid 取可避免被其他进程日志淹没。
+
+### 方法 2：cppcrash 日志文件（**鸿蒙 PC 上多半够不到**）
+
+设备上每个原生崩溃都会在 `/data/log/faultlog/faultlogger/` 生成完整的崩溃报告，但
+**该目录对 hdc shell 是 Permission denied**（uid 2000，2026-09-01 实测）——
+**取不到 cppcrash 不等于没崩**，别把它当"无崩溃"的证据。够得到时（如有更高权限的环境）用法如下：
+
+```bash
+# 列出该应用的所有崩溃日志（按时间降序）
+hdc shell "ls -lt /data/log/faultlog/faultlogger/ | grep <bundle_name> | head -5"
+
+# 拉取最新的崩溃日志
+hdc file recv /data/log/faultlog/faultlogger/cppcrash-<bundle_name>-<uid>-<timestamp>.log ./crash.log
+```
+
+cppcrash 日志包含：
+
+| 字段 | 内容 | 用途 |
+|------|------|------|
+| `Reason` | 崩溃信号 + 地址 + 系统推断（如 `probably caused by stack-buffer-overflow`） | 快速分类 |
+| `Fault thread info` | 崩溃线程的 TID + 完整调用栈 | 定位出错代码 |
+| `Registers` | CPU 寄存器快照 | 高级调试 |
+| `Other threads` | 所有线程的调用栈 | 检测死锁、多线程竞争 |
+| `Maps` | 进程内存映射 | 确认 .so 加载情况 |
+
+## cppcrash 日志解读
+
+### Reason 行
+
+```
+Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0000005a5805cff0  current thread stack low address = 0x0000005a5805d000, probably caused by stack-buffer-overflow
+```
+
+| 信号 | 含义 | 常见根因 |
+|------|------|---------|
+| `SIGSEGV(SEGV_MAPERR)@0x0` | 空指针解引用 | 指针未初始化、`new` 返回 nullptr |
+| `SIGSEGV(SEGV_MAPERR)@<非零小地址>` | 接近空指针的偏移解引用 | `obj->member` 中 obj 为 nullptr |
+| `SIGSEGV(SEGV_ACCERR)` + `stack-buffer-overflow` | 栈溢出 | 无限递归（信号死循环、互相调用） |
+| `SIGSEGV(SEGV_ACCERR)` + 无 overflow 提示 | 访问权限错误 | 栈 guard page、只读内存写入 |
+| `SIGABRT` | 程序主动 abort | Qt 断言失败、`Q_ASSERT`、`assert()` |
+| `SIGBUS` | 总线错误 | 未对齐的内存访问 |
+
+### 调用栈解读
+
+#### 模式 1：无限递归（255+ 层重复帧）
+
+```
+#00 pc 0000000000559364 libNotepadNext.so(QtPrivate::FunctionPointer<void (QTabWidget::*)(int)>::call)
+#01 pc 00000000005592c4 libNotepadNext.so(QtPrivate::QSlotObject::impl)
+#02 pc 000000000048c3fc libQt5Core.so
+#03 pc 00000000003a3058 libQt5Widgets.so(QTabWidget::currentChanged(int))
+#04 pc 0000000000559450 libNotepadNext.so(QtPrivate::FunctorCall::call)
+#05 pc 00000000005593a4 libNotepadNext.so(QtPrivate::FunctionPointer::call)
+#06 pc 00000000005592c4 libNotepadNext.so(QtPrivate::QSlotObject::impl)
+#07 pc 000000000048c3fc libQt5Core.so
+#08 pc 00000000003a3058 libQt5Widgets.so(QTabWidget::currentChanged(int))
+... (重复 255+ 层)
+```
+
+**诊断**：调用栈中有 3 个帧为一组循环重复（`QSlotObject::impl` → `FunctionPointer::call` → `QMetaObject::activate` → `signal emit` → `QSlotObject::impl`），这是 Qt 信号→信号无限递归的典型模式。
+
+**根因模式**：子类将基类信号连接到自身的同名信号：
+```cpp
+class Derived : public QTabWidget {
+    Q_OBJECT  // MOC 生成 Derived::currentChanged 信号
+    Derived() {
+        // BUG: Base::currentChanged → Derived::currentChanged → 无限递归
+        connect(this, &QTabWidget::currentChanged, this, &Derived::currentChanged);
+    }
+};
+```
+
+**修复**：删除该 connect。基类信号消费者直接连接即可。
+
+#### 模式 2：dlopen 失败
+
+```
+Reason:Signal:SIGSEGV(SEGV_MAPERR)@0x0000000000000000
+#00 pc ... libc.so(dlopen)
+```
+
+**诊断**：应用尝试加载 .so 但失败。
+
+**排查**：
+1. 检查 HAP 的 `entry/libs/arm64-v8a/` 目录，确认所有 .so 都存在且为 AArch64 ELF（`file *.so` 或 `readelf -h *.so`）
+2. 检查 NEEDED 依赖链：`readelf -d libNotepadNext.so | grep NEEDED`，每个 NEEDED 都必须有对应文件
+3. 常见遗漏：`libc++_shared.so`（NDK C++ 运行时）
+
+#### 模式 3：构造函数崩溃
+
+```
+#00 pc ... libNotepadNext.so(MainWindow::MainWindow(QWidget*))
+```
+
+**诊断**：主窗口构造函数中崩溃。调用栈指向你的代码。
+
+**排查**：
+1. 定位崩溃帧对应的源码行（需要 addr2line 或带符号的 .so）
+2. 常见原因：空指针、未初始化的成员、Qt 对象父子关系错误、资源文件缺失
+
+#### 模式 4：Qt 内部断言
+
+```
+Reason:Signal:SIGABRT
+#00 pc ... libc.so(abort)
+#01 pc ... libQt5Core.so(QAssert)
+```
+
+**诊断**：Qt 内部检查失败。
+
+**排查**：hilog 中 abort 之前通常有 Qt 警告信息（如 `QLayout: Attempting to add QLayout "" to QWidget ""`），这些信息比调用栈更有用。
+
+## 验证状态判定
+
+| 必检三步结果 | 03-adapt.json status | 说明 |
+|-------------|---------------------|------|
+| 进程存活 + 无崩溃日志 | `built-and-verified` | 应用启动并稳定运行 |
+| 进程存活 + 有崩溃日志 | `partial` | 子线程崩溃但主线程未死，需排查 |
+| 进程不存活 | `partial` 或 `failed` | 应用启动后崩溃，需修复后重验 |
+| 无设备无法验证 | `built-pending-verification` | HAP 已构建但无设备验证 |
+
+### 结果誊写
+
+GUI 应用通常无自动化测试套件，设备验证以「启动冒烟」替代（算 `test_source=generated` 的一条用例）。誊写 `03-adapt.json` 的 `test_run`：
+
+```json
+{
+  "executed": true,
+  "test_command": "hdc shell aa start -a <ability> -b <bundle>",
+  "total_cases": 1,
+  "passed": 1,
+  "failed": 0,
+  "pass_rate": 1.0,
+  "test_source": "generated",
+  "notes": "GUI 应用启动冒烟验证：HAP 安装成功 + 进程存活（等待 5s 后 ps 确认）+ hilog 无崩溃信号。"
+}
+```
+
+首次部署崩溃后修复再通过的情况，`notes` 中必须记录崩溃根因和修复内容。
+
+## 经验案例
+
+### NotepadNext 0.14：QTabWidget::currentChanged 信号无限递归
+
+- **现象**：应用启动约 1 秒后崩溃，`aa start` 返回成功
+- **Reason**：`SIGSEGV(SEGV_ACCERR) probably caused by stack-buffer-overflow`
+- **调用栈**：255+ 层 `QTabWidget::currentChanged → QSlotObject::impl → FunctionPointer::call → QMetaObject::activate` 循环
+- **根因**：`DockedEditorOhos.h:20` — `connect(this, &QTabWidget::currentChanged, this, &DockAreaOhos::currentChanged)` 将基类信号连接到子类同名信号
+- **修复**：删除该 connect 行
+- **教训**：`Q_OBJECT` 宏在子类中生成同名信号，`connect(this, &Base::sig, this, &Derived::sameSig)` 会创建信号→信号→信号的无限递归
+
+### 冷启动偶发超时：首条用例 180s 超时 ≠ 产物问题（某图像库 实证，2026-09-09）
+
+- **现象**：设备冷启动后拉起 demo，**首条用例**在 180s 超时窗口内未出结果行，其余用例正常
+- **归因**：**不是产物缺陷**——hilog 通道/系统服务在冷启动首分钟未就绪，属第 2 类（测试框架/环境）
+- **判据**：per-case 重跑一次即通过；若重跑仍失败才进入正常失败归因流程
+- **处理**：整轮跑完若有超时用例，用 `--per-case` 复现单条重跑，**不要**因此改产物或判 fail
+- **教训**：`verify-demo` 的整轮超时（默认 900s）针对的是整体，单条用例的偶发超时要用 per-case 重跑消解——先重跑，再归因，顺序不能反
+
+## Electron-OH 应用专项检查（按形态勾选）
+
+> 标注〔B〕的检查仅「壳 + Node sidecar」形态适用；标注〔spawn〕的仅对「应用会 spawn 子进程/外部工具」适用；无标注的所有形态必查。宿主机制（三关治理触发条件、jitless 连带坑）的权威在 `pc-knowledge-base/electron/electron.md`。
+> **auto 模式（默认）**：机器可判项照常执行；**依赖肉眼/交互的项**（#7 i18n 显示、#8 会话恢复、#9 品牌资源，及 #10 的「UI 挂载无白屏」目测部分）记入验证记录「待人工复核」节并列入 04-summary 的 remaining_todos，不因此单判 failed。
+
+| # | 检查 | 适用 | 通过标准 | 失败排查 |
+|---|---|---|---|---|
+| 1 | sidecar 拉起 | 〔B〕 | 壳日志出现健康检查 200 | SIGSYS→检查 LD_PRELOAD（liburing_block.so）；SIGTRAP→检查 --jitless（utilityProcess 边界见 electron.md #1）；Permission denied→检查私有 HNP 声明与注入 |
+| 2 | 网络/LLM 链路 | 〔B〕 | 业务请求有响应（tokens>0） | `WebAssembly is not defined`→fetch polyfill 未打/激活条件恒 false（electron.md #3） |
+| 3 | 文件写入 | 全部 | 沙箱与授权目录可写 | 无响应→权限 `ask`/external_directory；EACCES→`stat4` 类探测未吞错 |
+| 4 | 外部工具（rg 等） | 〔spawn〕 | exec 正常 | Permission denied→是否误用 HNP 公共区路径（承接形态见 electron.md #1） |
+| 5 | 生命周期 | 全部 | 关窗/退出后业务进程消失 | 检查 window-all-closed/before-quit kill sidecar |
+| 6 | Electron API 差异核验 | 〔A〕 | 形态判定时列出的差异化 API 逐个真机核验通过 | 对照 `ohpt-agent scan-electron` 的 requires_attention 清单与差异矩阵的真机核验义务 |
+| 7 | 资源路径/i18n | 全部 | 菜单/界面显示译文而非 key | `process.resourcesPath` 残留分支，见 electron.md #9（含 OHOS 包布局陷阱） |
+| 8 | 会话恢复 | 〔恢复上次文件的应用〕 | 重启后恢复打开文件无 EPERM | 用户目录权限未声明/未弹窗（picker 授权仅会话级），见 forms/app.md 权限分轨 |
+| 9 | 品牌资源 | 全部 | 启动器名称/图标为应用自身 | scaffold 已替换双端图标与三份 label；名称不刷新→重启设备（启动器显示名缓存） |
+| 10 | argv 污染 | 〔A·入口校验argv〕 | 应用正常启动、UI 挂载、无白屏假活 | 入口 prepend `process.argv` 清洗只留应用 flag，见 electron.md #10 |
+| 11 | loadURL scheme | 〔A·自定义协议/本地服务〕 | 页面加载非白屏、JS/CSS 请求 200、API 请求到达后端 | loadURL scheme 与资源引用不一致（net_error -400）/ baseURL 相对路径，见 electron.md #13 |
+| 12 | const enum 擦除 | 〔A·TS+esbuild〕 | 运行时无 `xxx is not defined` / `Cannot read properties of undefined` | 全仓 grep `export const enum` 改普通 enum + 重出 bundle，见 electron.md #11 |
+
+全过 → 交付；任何一项失败 → 修复 → 重跑构建链 ③④。验证记录写 `<APP>-verification.md`。
+
+### 白屏/静默失败调试三板斧（Electron-OH 标准定位路径）
+
+1. **入口陷阱注入**：探针 prepend 进主进程与 renderer 两份 bundle——uncaughtException/unhandledRejection/exit 三事件捕获 + 双候选路径写沙箱日志。
+2. **executeJavaScript 活体探针**：DOM 检查、远程调用 `Promise.race` 超时竞速、`process._getActiveResourcesInfo()` 快照区分「忙」vs「空等」。
+3. **hilog 流式落盘**：`hilog > file &` 后台抓（环形缓冲秒级轮转）；SIGTRAP=V8 JIT 被拒（faultlog 栈顶 FatalProcessOutOfMemory）、SIGSYS=seccomp（faultlog 给 syscall 号）。
+
+**对照基线法**：同引擎正常渲染的模板 demo 作基线，对本应用 renderer 进程命令行**逐 flag 比对**——差异 flag 即线索（`--enable-sandbox` vs `--no-sandbox` → sandbox 守卫；缺 `UseOzonePlatform` → appendSwitch 覆盖语义）。**判定纪律**：白屏炸点可能成链——修掉一个不等于到头。
+
+### UI 自动化受限时的替代验证通道
+
+- **uitest uiInput 完整可用**（click/inputText/keyEvent）；但 `dumpLayout` 对 Chromium 窗口返回空布局 → 能发事件、不能精确定位。
+- **本地 API 层测试**：应用内嵌本地服务直接 `wget -O - 'http://localhost:<port>/<endpoint>'`（或 `hdc fport` 端口转发后宿主 curl）——验证后端链路的首选通道。
+- **验证诚实性**：冒烟级（进程存活 + 端口 LISTEN）≠ 功能级；每条 PASS 要有 hilog 实锤。