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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L052.md

@@ -0,0 +1,65 @@
+<!-- 来源：IfcOpenShell 0.9.0 交叉编译 from_chars 实证（2026-09-20） | 原编号 E175 --> 一句话定位：交叉编译含浮点字符串解析的 C++ 项目时，`std::from_chars` 的 float/double 重载在 OHOS NDK clang 15 libc++ 被**标记为 deleted**（与 Apple/macOS 同行为）——报错指向 from_chars 无法实例化/deleted 函数引用，修法是复用上游已有的 `__APPLE__` 分支 strtod_l 兜底（追加 `|| defined(__OHOS__)`）。
+
+# L052: OHOS NDK clang 15 libc++ 的 float from_chars 被标记为 deleted——复用 __APPLE__ 分支 strtod_l 兜底
+
+> **严重度**: 2 major | **领域**: compile/libc++ | **自动修复**: patch（`#if defined(__APPLE__)` 分支追加 `|| defined(__OHOS__)`，include 与调用两处同步）
+
+---
+
+## 问题现象
+
+交叉编译 C++ 项目（含浮点字符串→数值解析，如 IFC STEP 文件解析器）到 OHOS aarch64 时，编译报错指向 `std::from_chars` 的浮点重载：
+
+- `no matching function for call to 'from_chars(...)'` / deleted function 引用；
+- 报错位置在库自己的浮点解析辅助函数处（IfcOpenShell 案是 `src/ifcparse/parse.cpp` 的 `parse_num_` 与 `src/svgfill/src/arrange_polygons.cpp`）。
+
+## 根因
+
+OHOS NDK clang 15 自带的 libc++ 与 Apple libc++ 行为一致：**浮点 `from_chars` 特化被 `=delete`**（上游 libc++ 15 未实现浮点 from_chars，Apple 分支显式 delete 防止误用低精度实现）。而上游库通常**已经为 `__APPLE__` 写好了 strtod_l 兜底分支**——
+locale 无关的 `strtod_l` + `newlocale(LC_NUMERIC_MASK, "C", ...)`（普通 `strtod` 受当前 locale 影响，解析结果不稳定，所以上游才专门写了这条路径）。libstdc++/MSVC STL 的浮点 from_chars 正常，走不到这条分支。
+
+同门平台：`__EMSCRIPTEN__` 也被上游列在同一分支里——**「libc++ 浮点 from_chars 缺失」是一族平台共性，不是 OHOS 独有**。
+
+## 判别方法
+
+1. 编译报错指向 `from_chars`（float/double 实参）；
+2. `grep -rn "defined(__APPLE__)" <报错源文件>` ——上游代码里能找到 `__APPLE__` 条件分支，分支内是 `strtod_l`/`xlocale.h` 兜底实现。
+
+两条全中 → 复用上游 Apple 分支，不要自己造解析函数。
+
+## 解决方案
+
+在**上游已有的** `#if defined(__APPLE__)` 条件编译分支追加 `|| defined(__OHOS__)`，注意通常要改**两处**（include 分支 + 调用分支）：
+
+```cpp
+// ① 头文件 include 分支
+#if defined(__APPLE__)
+#include <xlocale.h>
+#include <locale.h>
++#elif defined(__OHOS__)
++#include <locale.h>
+#endif
+
+// ② 调用分支（strtod_l 兜底）
+-#if defined(__APPLE__) || defined(__EMSCRIPTEN__)
++#if defined(__APPLE__) || defined(__EMSCRIPTEN__) || defined(__OHOS__)
+ double parse_double_c(const char* start, char** end) {
+     static const locale_t loc = newlocale(LC_NUMERIC_MASK, "C", (locale_t)0);
+     return strtod_l(start, end, loc);
+```
+
+**反模式**：看到报错就自己写一个 `std::from_chars` 替代实现或把解析改成裸 `strtod`——前者重复造轮子且 locale 语义容易错，后者引入 locale 依赖导致解析结果随设备 locale 漂移（浮点阈值类测试会因此翻车，参见 E132 的确定性纪律）。
+
+## 影响范围
+
+OHOS NDK clang 15（libc++ 15）交叉编译**所有含浮点字符串解析**的 C++ 项目：数值格式解析器、CAD/几何数据格式（STEP/IFC）、科学计算输入、配置文件解析。随 NDK libc++ 升级实现浮点 from_chars 后本条自然失效——升级 NDK 后可先用 30 行 TU 验证（`#include <charconv>` + `std::from_chars(p, e, 1.5f)` 过编译即已修复）。
+
+## 关联
+
+- `pc-knowledge-base/adaptation/鸿蒙PC-OHOS-NDK-clang15-C++新特性兼容缺口清单.md` 缺口 8——同域（NDK clang 15 C++ 兼容缺口族，E146/E147/E148 同门）
+- E131：iconv/CJK 是 musl 分支裁剪，属**运行时**编码域；本条是 libc++ **编译期**浮点解析域，勿混
+- E132：locale 依赖会破坏确定性测试——strtod_l 的 "C" locale 锚定正是为了避开它
+
+## 实证
+
+IfcOpenShell 0.9.0 交叉编译（2026-09-20）：编译报 from_chars 浮点重载 deleted；`patches/0001-IfcOpenShell-OHOS-adaptation.patch` 对 `src/ifcparse/parse.cpp`（9 行）与 `src/svgfill/src/arrange_polygons.cpp`（13 行）同修，均为 `__APPLE__` 分支追加 `__OHOS__`。修后两文件编译通过，svgfill 几何 .so 产出并装机。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L053.md

@@ -0,0 +1,62 @@
+<!-- 来源：IfcOpenShell 0.9.0 svgfill 重链实证（2026-09-20） | 原编号 E176 --> 一句话定位：给交叉编译产物重链追加 `.codesign` 段（链接期自签）时，ld.lld 报 `error: xxx.o:(.debug_gdb_scripts): string is not null terminated`——clang -g 生成的调试段内 GDB 脚本字符串未 NUL 终止，构建配置带 `--fatal-warnings` 时 warning 被升级为 error；剥段 + 关 fatal-warnings 后重链即过。
+
+# L053: ld.lld 的 .debug_gdb_scripts 段与 --fatal-warnings 冲突——重链加 codesign 场景
+
+> **严重度**: 2 major | **领域**: link/sign | **自动修复**: script（`llvm-objcopy --remove-section .debug_gdb_scripts` 剥段 + 链接命令追加 `-Wl,--no-fatal-warnings` 后重链）
+
+---
+
+## 问题现象
+
+给已编好的 .so **重链追加 `-Wl,--code-sign`**（链接期自签，E077/E129 签名链路的标准动作）时，链接报错：
+
+```
+ld.lld: error: svgfill/CMakeFiles/svgfill.dir/src/arrange_polygons.cpp.o:(.debug_gdb_scripts): string is not null terminated
+ld.lld: error: svgfill/CMakeFiles/svgfill.dir/src/svgfill.cpp.o:(.debug_gdb_scripts): string is not null terminated
+```
+
+单看报错像「目标文件损坏」，实为调试信息段的已知特征 + 构建旗标组合问题。
+
+## 根因
+
+| # | 条件 | 说明 |
+|---|---|---|
+| 1 | `clang -g` 自动生成 `.debug_gdb_scripts` 段 | 段内是喂给 GDB 的调试辅助脚本字符串，**clang 15 生成的该段字符串未以 NUL 终止**——lld 对此发 warning（不终止本身不影响运行，调试段不参与加载） |
+| 2 | 构建配置带 `--fatal-warnings` | 上游 CMake 配置把 warning 升级为 error，链接失败 |
+
+两个条件叠加才炸：**只开 `-g` 没 fatal-warnings 不会挂**（只有 warning），**不带 -g 没有 `.debug_gdb_scripts` 段也没事**。所以它专挑「上游构建配置严格（fatal-warnings）+ 调试信息在场」的重链场景。
+
+## 判别方法
+
+1. 报错特征串：`.debug_gdb_scripts` + `string is not null terminated`；
+2. 检查链接命令是否带 `--fatal-warnings`（`ninja -t commands <target>` 提取链接命令核对）。
+
+两条全中 → 本条，剥段重链，不要试图「修复目标文件内容」或关 `-g` 重编全树。
+
+## 解决方案
+
+```bash
+# ① 剥掉调试脚本段（纯调试用途，不影响 .so 运行与 .codesign 签名）
+llvm-objcopy --remove-section .debug_gdb_scripts <xxx>.o   # 逐个报错的 .o
+
+# ② 重链时关闭 fatal-warnings（链接命令其余旗标原样保留）
+<原链接命令> -Wl,--no-fatal-warnings -Wl,--code-sign
+```
+
+批量场景用构建系统提取链接命令后改旗标重跑（实证脚本模式：`ninja -C <build_dir> -t commands <target>` 取含 `-shared` 的链接行 → 写成 .cmd 执行并回读 `EXITCODE=%ERRORLEVEL%`）。
+
+**注意**：剥 `.debug_gdb_scripts` 与签名链路的既有纪律不冲突——E077 说的是 **post-link `strip` 会破坏已有 `.codesign` 段**（strip 必须在签名**前**）；本条的 objcopy 剥段同样必须在重链（签名）**前**对 `.o`/旧产物做，顺序是「剥段 → 重链带 --code-sign → 不再 strip」。
+
+## 影响范围
+
+所有「重链加 codesign 段」场景：漏签 .so 补签（E077 表象是设备侧 Permission denied/加载失败）、native-extension 交叉产物签名补齐、CGAL/几何类大模板库分批产出后的补签重链。
+
+## 关联
+
+- E077：签名段与 strip/patchelf 的顺序纪律（本条是其「重链」路径上的前置坑）
+- E129 / E083：设备侧 exec/加载强制代码签名——重链补签的需求来源
+- E154：补丁卫生（构建脚本静默继续掩盖链接失败——重链脚本要回读退出码）
+
+## 实证
+
+IfcOpenShell 0.9.0 svgfill .so 重链（2026-09-20）：`build/ninja-svgfill.log` L11-12 报错原文（两个 .o 的 `.debug_gdb_scripts` 未终止字符串）；`build/_relink_svgfill2.py` + `_relink_svgfill.cmd` 提取链接命令追加 `-Wl,--no-fatal-warnings` 重链，`build/ninja-svgfill2.log` 通过，产物带 `.codesign` 段装机。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L054.md

@@ -0,0 +1,75 @@
+<!-- 来源：new/PC（某国密 OpenSSL 分支 8.5.0-pre2 测试线阶段 6 断点续跑实证 2026-09-21） | 原编号 E177 --> 一句话定位：显式 EVP_RAND 接线创建 CTR-DRBG 后**不设 `OSSL_DRBG_PARAM_CIPHER` 直接 instantiate**——`drbg_ctr_new` 只置 `use_df=1`、`cipher_ctr/cipher_ecb` 为空、strength=0，`drbg_ctr_instantiate` 里 `EVP_CipherInit_ex(NULL)` 裸 return 0，报 `error:1C8000BC:Provider routines::error instantiating drbg`（**仅包装层错误、错误队列无内层、child_strength=0**，三重指纹）；生产全局链一直正常，正因为它创建 DRBG 时都 set CIPHER（`rand_lib.c` 的 `rand_new_drbg` 同款）。同族误用：给生产 CTR-DRBG 传 `OSSL_RAND_PARAM_TEST_ENTROPY` 求确定性输出——报 `error:030000EA provider signature failure`，该参数**只被 test-only 的 TEST-RAND provider 消费**，「同种子→同输出」不是生产 API 契约。
+
+# L054: CTR-DRBG 创建后未设 CIPHER 参数——instantiate 静默失败（wrapper-only 错误码）
+
+> **严重度**: 2 major | **领域**: crypto/rand wiring | **自动修复**: none（补 `EVP_RAND_CTX_set_params(CIPHER)`；依据回指 `drbg_ctr.c`/`rand_lib.c`）
+
+---
+
+## 问题现象
+
+显式 EVP_RAND 接线（demo 富用例体 / 直跑上游 rand_test）拿 CTR-DRBG 实例化失败：
+
+```
+hilog: error:1C8000BC:Provider routines::error instantiating drbg
+设备诊断: parent=CTR-DRBG、child_strength=0、错误队列无内层错误
+```
+
+或换了多种接法（全局 `RAND_get0_private` 作父源 / 无父源 + TEST_ENTROPY 当种子）仍全部失败：
+
+```
+hilog: error:030000EA:digital envelope routines::provider signature failure
+```
+
+特征：换 parent、换熵源、换 ctx 组合都救不了——因为根因不在熵源侧，在**密码没加载**。
+
+## 根因
+
+| # | 误诊（都排除过） | 真根因 |
+|---|---|---|
+| 1 | 「无 parent → app 域沙箱无熵源可种」（E156 原表述） | 不成立：设备诊断 `parent=CTR-DRBG` 实证该构建全局链与子实例同型；换父源无效 |
+| 2 | 「SMTC_MODULE 下独立 ctx 走 `ossl_smtc_get_entropy()` 拿不到 CRNGT 数据」（源码推断） | 不成立：该构建未定义 SMTC_MODULE；**源码推断不当结论，先设备诊断** |
+| 3 | — | **`drbg_ctr_new` 只置 `use_df=1`，不自动加载密码**：`cipher_ctr/cipher_ecb` 为空、strength=0。跳过 `set_ctx_params` 直接 instantiate → `drbg_ctr_instantiate` 里 `EVP_CipherInit_ex(NULL)` 裸 return 0（不抛内层错误）→ 只有包装层 1C8000BC |
+| 4 | 「给 CTR-DRBG 传 TEST_ENTROPY 即得确定性输出」（用例设计假设） | `OSSL_RAND_PARAM_TEST_ENTROPY` **只被 test-only 的 TEST-RAND provider 消费**（`test_rng.c` 的 `test_rng_set_ctx_params`）；生产 CTR-DRBG 的 `set_ctx_params` 只认 `use_df`/`cipher`/`properties`（`drbg_ctr.c:724-802`），`ossl_drbg_set_ctx_params` 只认 `reseed_requests`/`reseed_time_interval`（`drbg.c:997-1005`）——传了不认的参数 → 030000EA |
+
+生产 `RAND_bytes` 一直正常的对照：全局链创建 DRBG 时都 set `OSSL_DRBG_PARAM_CIPHER`（`crypto/rand/rand_lib.c` 的 `rand_new_drbg` 同款）。
+
+## 判别方法
+
+1. `error:1C8000BC ... error instantiating drbg` 且**错误队列无内层错误** + `child_strength=0` → 密码未加载（本条）；
+2. 核对接线体：`EVP_RAND_CTX_new` 之后、`EVP_RAND_instantiate` 之前有没有 `EVP_RAND_CTX_set_params` 设 **CIPHER**；
+3. `error:030000EA provider signature failure` 且接法里给 DRBG 传了 TEST_ENTROPY/TEST_NONCE → 参数喂错对象（只归 TEST-RAND provider）；
+4. 下根因前先设备诊断（读 `parent`/`strength` 参数打印），**源码推断（SMTC/CRNGT 之类）必须被设备实证背书才能当结论**——本轮「SMTC 推断」即被 `parent=CTR-DRBG` 诊断推翻。
+
+## 解决方案
+
+生产契约接线（无 test provider 依赖）：
+
+```c
+rand = EVP_RAND_fetch(libctx, "CTR-DRBG", NULL);        // 算法可 fetch
+parent = RAND_get0_private(libctx);                     // 生产用法：系统熵源链
+                                                       // SEED-SRC→primary→private 的次级 DRBG
+drbg = EVP_RAND_CTX_new(rand, parent);
+/* ★ 承重参数：不设必挂在 instantiate（1C8000BC） */
+params[0] = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER, "AES-256-CTR", 0);
+EVP_RAND_CTX_set_params(drbg, params);
+EVP_RAND_instantiate(drbg, 0, 0, NULL, 0, NULL);        // 父源供熵，无需 TEST_ENTROPY
+EVP_RAND_generate(drbg, out, 32, 256, 0, NULL, 0);      // 强度 256 生成
+```
+
+- **确定性（同种子→同输出）断言**：只有经 TEST-RAND provider（`EVP_RAND_fetch(NULL,"TEST-RAND",NULL)` 作 parent，TEST_ENTROPY/TEST_NONCE 喂给 **TEST-RAND 的 ctx**）可达，且属**测试期能力**——用例设计不得把 test-only 参数当生产 API 契约钉断言（testcase-defect 家族，见 E139）；生产契约改验「可 fetch + 可实例化 + 强度 256 生成 32 字节非全零 + 两次输出互不相同」。
+
+## 影响范围
+
+OpenSSL 3.x 系 / 某国密 OpenSSL 分支 / BoringSSL 衍生库的一切**显式 EVP_RAND DRBG 接线**：demo 富用例体（`napi_stub.cpp`）、直跑上游 `rand_test` 前的自建 DRBG、任何「拿 CTR-DRBG 自己 instantiate」的场景。
+
+## 关联
+
+- E156：demo 接线五类错 bundle——其第 4 类（DRBG）根因表述由本条修正（「无 parent 无熵源」不成立，承重参数是 CIPHER）
+- E153：provider 自检状态机卡 INIT 拖垮 DRBG（同族不同根因：那边是 fetch 成功 init 全败的状态机问题，这边是密码参数缺失）
+- E139：testcase-defect（确定性断言钉在不存在的参数面上 → 回阶段 5 修用例）
+- `pc-knowledge-base/adaptation/鸿蒙PC-OpenSSL系密码库交叉编译.md` §4.4
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2 测试线阶段 6 断点续跑（2026-09-21，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64）：F-05-01 三轮 instantiate 失败（换父源/换熵源/TEST_ENTROPY 三种接法）同属根因 3；补 `set_ctx_params(CIPHER=AES-256-CTR)` + `RAND_get0_private` 父源后真机 4/4 判定点 pass（取证 4.4s 出结果行）。源码依据：`source/providers/implementations/rands/drbg_ctr.c:724-802`（set_ctx_params 只认 use_df/cipher/properties）、`drbg.c:997-1005`（不认 test_entropy）、`test_rng.c:240-249`（TEST_ENTROPY 唯一消费者）、`crypto/rand/rand_lib.c`（rand_new_drbg 设 CIPHER）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L055.md

@@ -0,0 +1,79 @@
+<!-- 来源：new/PC（某交叉工具链工程 test-demo 多轮实证 2026-09-21） | 原编号 E178 --> 一句话定位：native runner 的超时看门狗用 `alarm(N)`（默认 SIGTERM）只能杀**直接子进程**（bash 映像）——`bash -c "make → sh -c → curl"` 调用链里的孙进程被孤儿化后**持有 stdout pipe 的写端**，父侧 `read()` 永不返回，该用例挂死数分钟而捕采侧只见「安静」（失效模式 1）。**失效模式 2**（2026-10-11 对偶 runner 实证）：被测物是**无 shell 链、无孙进程的单进程 ELF** 时 alarm 同样可能完全不生效——alarm 到点进程不死（最可能机制：exec 前只重置 SIG_IGN 处置、未清空 blocked 信号掩码，宿主掩码里的 SIGTERM/SIGALRM 永远 pending，机制归属见关卡⑥）；串行 worker 队列被堵死，后续用例/summary/end 永不产出。解法同一套：子进程 `setpgid(0,0)` 自成进程组 + 父侧 poll 1s 粒度计时 + 超时 `kill(-pid, SIGKILL)` 杀全组；子进程 exec 前补 `sigprocmask(SIG_SETMASK, &empty)` 清掩码。
+
+# L055: 看门狗只杀直接子进程——孙进程持 pipe 致 run-all 挂死（孤儿进程现场）
+
+> **严重度**: 2 major | **领域**: device-runner / 进程组 | **自动修复**: ✅ 模板已固化（2026-10-13：`cli-hnp-runner` / `cpp-terminal-demo` / `python-app-subprocess` 三模板 exec 均已改为 setpgid + 父进程 poll 计时 + 超时 `kill(-pid, SIGKILL)`，另加名册总预算 20min 兜底 `tmo=0` 显式豁免；生成物天然免疫两种失效模式。依据 `.spec/spec-设备名册执行器总能收尾（basis_universal+vulkan实证）.md`；模板代码见 `pc-device-verify/references/runner-script-wiring.md` §5）
+
+---
+
+## 问题现象
+
+demo run-all 在某条用例上挂数分钟、整表 summary 迟迟不出：
+
+```
+hilog: ... 某用例 result=pass 后长时间无新行
+捕采: poll.stopped_by=stalled（waited_ms 远小于 timeout_ms）
+设备进程树: 孤儿 curl / make 进程仍存活，持 pipe
+```
+
+特征：挂的用例**不是最长的那条**；单跑该例可能复现也可能因时序逃逸；杀掉 HAP 重启后复跑又挂在别处（谁持有 pipe 谁挂）。
+
+**失效模式 2（alarm 对直接子进程也不生效，无孙进程也会挂死）**：
+
+```
+hilog: 某单进程 ELF 用例 result=pass 后长时间无新行，后续用例/summary/end 全部不产出
+设备进程树: 被测 ELF 进程本身仍存活（ps 可见，无孤儿 shell 链、无孙进程）
+宿主侧: 已远超该条 exec 的看门狗预算（600/900s），进程照活——alarm 兜底形同虚设
+连锁: runner worker 串行队列卡死在该条 → 后续全部用例不跑、OHPTCASE summary 与
+      end 标记永不出现 → 每轮捕采等到 deadline 仍无合法 results.json → 整轮判失败
+```
+
+## 根因
+
+| # | 误诊（都排除过） | 真根因 |
+|---|---|---|
+| 1 | 「app 域 seccomp 杀进程」（与 E167/SIGSYS 家族混淆） | 不成立：没有 SIGSYS/crash 日志，进程是**活着但不退出** |
+| 2 | 「捕采侧 stall 阈值太紧」（工具问题） | 不成立：阈值放宽后照样挂——挂的是 runner 的 `read()`，不是取证 |
+| 3 | — | **`alarm(N)` 到期 SIGTERM 只送达直接子进程**：`fork → execv(bash -c "...")` 的 bash 被 TERM，但它 fork 出的 make→sh→curl 孙进程不受 alarm 影响，被孤儿化后继承并持有 stdout pipe 写端；父进程 runner 阻塞在 `read()` 等管道 EOF，而管道永不 EOF（还有存活写端）→ 挂死 |
+| 4 | 「alarm 时长设短了/预算不够」（调大预算或传 0 继续等） | **失效模式 2：alarm 对直接子进程也完全不生效**——被测物是单进程 ELF（无 shell 链）时同样挂死。根因：run_cmd 子进程 exec 前只调 `reset_inherited_signal_ignore()`（仅把 SIG_IGN 处置重置回 SIG_DFL），**未清空 blocked 信号掩码**；POSIX 规定 SIG_IGN 处置与 blocked set 原样跨 fork+exec 保留，宿主（NAPI 宿主线程）掩码若含 SIGTERM/SIGALRM，alarm 到点信号永远 pending 不递送 → 进程不死。机制详解见 `pc-knowledge-base` 的 [[鸿蒙PC-app域执行二进制与JIT限制]] 关卡⑥ |
+
+## 判别方法
+
+1. 挂死时看设备进程树：`hdc shell "ps -ef | grep <bundle>"`——发现已无 bash 但仍有孤儿工具进程（curl/make/tar）持连接 → 失效模式 1；
+2. **失效模式 2 判别**：`ps -ef` 见被测 ELF **单进程本身**存活（无孤儿 shell 链/孙进程）、已过该条 exec 的看门狗预算仍活 → alarm 兜底对直接子进程已失效，本条模式 2；
+3. 宿主侧复现：`fork` + `execv("bash", ["bash","-c","sleep 300 | cat"])` + `alarm(2)`，观察 `read()` 不返回、`ps` 见孤儿 `sleep`（模式 1）；
+4. 与 E167（fork 无 exec 继承状态被 SIGSYS 杀）区分：那边有 SIGSYS/信号终止痕迹，这边是纯挂死无信号日志；
+5. **区分「挂死」与「真慢」——修复方向不同，先判别再动手**：两次采样 `cat /proc/<pid>/stat` 看 utime 字段是否增长——增长 = 在算（真慢），不动 = 挂死/IO 阻塞（结合 wchan 看）。
+   - 真慢（aarch64 标量路径的重度自测 20min~h 级是常态）：**名册选型问题**——host 预演为主、设备侧降级 blocked 带原因或减规模重设计，别靠调大预算硬扛；
+   - 挂死：**兜底机制问题**——按本条解法修看门狗（父进程计时 + 组杀），两条腿都要落。
+
+## 解决方案
+
+```cpp
+// 子进程（fork 后、execv 前）：进程组自首——孙进程随组
+setpgid(0, 0);
+// 父进程：不用 alarm。poll()/select() 1s 粒度计时，超时杀全组再收割
+if (elapsed >= timeout_sec) {
+    kill(-pid, SIGKILL);          // 负号 = 组信号，孙进程一并死于组
+    waitpid(pid, &st, 0);         // 回收，管道写端全关，read() 立即 EOF
+}
+```
+
+- 心跳行（`pc-device-verify` §2）与看门狗配合：心跳证明「runner 活着、正在等 exec」，看门狗保证「exec 链一定会被收割」——两者合起来捕采侧的 stalled 才根除。
+- **勿再依赖子进程 alarm 作兜底**（两种失效模式都指向同一结论；**2026-10-13 起三份模板已按此固化，alarm 实现不复存在**）：若历史/自研 runner 仍保留 alarm，子进程 exec 前需补 `sigprocmask(SIG_SETMASK, &empty)` 清空掩码（即 [[鸿蒙PC-app域执行二进制与JIT限制]] 关卡⑥的 `child_pre_exec()` 完整版，比 `reset_inherited_signal_ignore()` 只重置 SIG_IGN 多修了掩码这一半）——但这只让 alarm 在掩码干净时可用，**不解决模式 1（孙进程持 pipe）**；主解始终是父进程计时 + 组杀。
+
+## 影响范围
+
+一切「native runner fork/execv 跑 shell 链 + 超时兜底」的载体：cli-hnp-runner 富用例体、device-roster.sh 外层调度、任何 `alarm`/`SIGALRM` 兜底的长 exec 场景。**串行 worker 队列模型下危害放大**（失效模式 2 实证）：一条 exec 卡死 = 后续全部用例不跑 + summary/end 永不产出 = 每轮捕采超时无 results.json，整轮判失败且现象是「无结果」而非「报错」，极易误判为捕采问题。
+
+## 关联
+
+- E167：fork 无 exec 的隔离子进程 SIGABRT（同族不同根因：那边是 exec 缺失放大崩溃，这边是信号送达范围不足/掩码阻断挂死）
+- `pc-device-verify/references/runner-script-wiring.md` §5（模板代码）/ §2（心跳行协议）
+- `pc-knowledge-base/platform/鸿蒙PC-app域执行二进制与JIT限制.md` **关卡⑥**（blocked 掩码跨 fork+exec 保留、`child_pre_exec()` 完整修复——失效模式 2 的机制权威归属）
+
+## 实证
+
+某交叉工具链工程 test-demo（2026-09-21，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64）：fix4 轮 F-02-01 挂 6 分钟、设备孤儿进程现场实证；fix6 轮 `setpgid(0,0)` + poll 1s + `kill(-pid, SIGKILL)` 重构后 run-all 全程无挂起，15/15 出 summary。上一版 alarm 实现仍在 `verify-fix4` 轮 device-raw.log 可考。
+
+**失效模式 2 实证**（某图像编解码库全流水线，2026-10-11，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64）：阶段 3 设备名册循环连续七轮无一份合法 results.json。loop5 hilog 取证：四条快用例逐条 pass（19:15:02→19:21:21），随后某单进程 ELF 重度自测用例（alarm 900s 预算）开始**再也不出结果**——设备进程树见被测 ELF 单进程存活 2.5h+、无孤儿 shell 链，alarm(900s) 到点未收割（是挂死还是重度慢跑按判别 5 区分；无论哪种，兜底失效与名册预算超支两个问题都成立，修复各按各的腿走）。诊断日志明确记录「alarm(600) 未生效，串行队列被堵死」。其余 20 条快用例因队列阻塞从未执行。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L056.md

@@ -0,0 +1,66 @@
+<!-- 来源：new/PC（某交叉工具链工程 test-demo 多轮实证 2026-09-21） | 原编号 E179 --> 一句话定位：`bash -c` 里把 `VAR=val` 写成**独立命令**（`VAR=val && cmd` 或换行两段）只设置 shell 变量、**不 export、不进子进程环境**——proxy/夹具类 env 全部静默失效：断网模拟空转成 rc=0、下载夹具不触发、curl 绕过代理直连真网；现象层呈现为「平台网络受限」「夹具无效」的假象，直接污染 capability gap 归因。解法：前缀赋值**直接修饰命令**（`VAR=val cmd`）或显式 `export`；判别走 `/proc/<pid>/environ` 查子进程实际环境。
+
+# L056: bash VAR=val 独立成行不 export——环境变量静默失效误诊平台限制
+
+> **严重度**: 2 major | **领域**: device-runner / shell 语义 | **自动修复**: none（改前缀赋值直修饰命令；判别与正反例见 `pc-device-verify/references/runner-script-wiring.md` §5）
+
+---
+
+## 问题现象
+
+设备用例里的环境变量**不生效**，且随用途不同呈现三种假象：
+
+```
+1. 断网模拟（http_proxy=127.0.0.1:1）不生效：curl 真联网成功 → rc=0、无网络签名
+   → 用例被判「断网路径未达网络层」，实际是代理根本没传给 curl
+2. 下载夹具（CTNG_FIXTURE_CORRUPT=xxx）不触发：wget shim 走真下载
+   → 「校验失败路径不可达」，实际是夹具变量没传进 shim
+3. 设备进程树出现绕过代理的孤儿 curl（真在联网）
+   → 被误记成「app 域 seccomp 限制出网 / musl TLS 不兼容」级平台能力缺口
+```
+
+特征：变量拼写完全正确、同一变量在**宿主 bash 里验证是好的**——只有设备侧 `bash -c` 组装的长命令里失效。
+
+## 根因
+
+| # | 误诊（都排除过） | 真根因 |
+|---|---|---|
+| 1 | 「app 域 seccomp 对 connect() 有限制」（写进了 capability_gaps） | 不成立：shell 域 ping 通、curl 换对代理后可达——**变量没到 curl 手里** |
+| 2 | 「musl TLS 栈与目标服务器不兼容」 | 不成立：同一 URL 用对代理后下载成功（fix3 轮真下载 sha512 通过） |
+| 3 | — | **bash 语义**：`VAR=val` 作为独立命令（`VAR=val` 换行/`;`/`&&` 分隔）只在**当前 shell** 设置变量，不进环境；`bash -c "A=1 && cmd"` 里的 `cmd` 看不到 A。前缀赋值 `A=1 cmd` 才是「修改 cmd 的环境」 |
+
+## 判别方法
+
+1. 设备上直接查子进程**实际**环境：`hdc shell "cat /proc/<pid>/environ | tr '\0' '\n' | grep <VAR>"`——空即本条（别查 shell 的 `set`，那是另一层）；
+2. 宿主最小复现：`bash -c "FOO=bar && env | grep FOO"` 输出为空 vs `bash -c "FOO=bar env | grep FOO"` 输出 bar；
+3. 凡「同一命令换写法结果突变」且怀疑对象是平台网络/沙箱策略时，**先验环境传递再下平台结论**——capability gap 归因必须排除断链假象。
+
+## 解决方案
+
+```bash
+# ✓ 前缀赋值直接修饰命令（每个子命令各自带）
+http_proxy=http://127.0.0.1:1 https_proxy=http://127.0.0.1:1 \
+  ftp_proxy=http://127.0.0.1:1 all_proxy=http://127.0.0.1:1 \
+  make -f ct-ng.in source
+
+# ✓ 或显式 export（同一 shell 内后续命令可见）
+export http_proxy=http://127.0.0.1:1 CTNG_FIXTURE_CORRUPT='m4-'
+make -f ct-ng.in source
+```
+
+- ftp:// 场景 curl 只认 `ftp_proxy`（http 系代理变量拦不住 ftp scheme）——拦截面要按 scheme 配齐；
+- 原生 runner 侧不要依赖 `setenv()` 后再拼 `bash -c` 长串的隐式继承：拼接层重排命令时最容易把前缀赋值拆成独立行（本轮根因即模板重排所致），**env 传递写在被修饰命令的同一段里**。
+
+## 影响范围
+
+一切「`bash -c` 拼长命令 + 靠 env 传参」的设备接线：proxy 断网模拟、下载夹具注入（E178 同门）、`LD_LIBRARY_PATH` 清空（`unset` 同样要防被重排丢掉）、TLS 证书自举（`SSL_CERT_FILE`/`CURL_CA_FALLBACK`）等。归因面：任何「env 类配置不生效」先查传递链，再谈平台限制。
+
+## 关联
+
+- E178：同轮修复的看门狗挂死（同属 runner 基础设施，且同样以「捕采 stalled」为表象）
+- `pc-device-verify/references/runner-script-wiring.md` §5（正反例与判别口令）/ §4（capability gap 归因纪律：precondition-unmet 与平台缺陷分开记）
+- `pc-knowledge-base/platform/鸿蒙PC-交叉libcurl空CA信任锚与SSL_CERT_FILE.md`（env 自举家族的另一员）
+
+## 实证
+
+某交叉工具链工程 test-demo（2026-09-21，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64）：某用例「校验失败路径不可达」、某用例断网模拟 rc=0 空转，设备孤儿 curl 现场实证代理未传递；改前缀赋值直修饰命令后下载校验正确触发、夹具真实触发 digest 拒绝，能力缺口清零（全量通过）。上一版错误归因（「app 沙箱域 outbound TCP 受限」）已留档。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L057.md

@@ -0,0 +1,48 @@
+<!-- 来源：ipv6toolkit 适配实战复盘（2026-10-13 工作区经验候选整理） | 新增沉淀（非迁移条目）
+evidence_level: E2
+summary_plain: 带 setuid/setgid 降权代码的 C 程序在鸿蒙 app 域会被 seccomp 静默击杀（SIGSYS=-31，不可捕获、日志无声）；非 root 分支要直接跳过降权调用。
+trigger: SIGSYS -31 seccomp setgid setuid privilege-dropping 静默死亡 带参死亡 无参存活
+verify: 修复后带参执行退出码 0 且功能输出正确；设备日志无 SIGSYS 记录
+status: active
+related: E051（通用「未实现 syscall 触发 SIGSYS」机制，本条是 app 域 setgid/setuid 的实案与落地修法，互补不重复） -->
+
+> 适用性：执行器 HAP（app 域 fork+execv）运行 C/C++ CLI/库适用
+
+# L057: OHOS app 域 seccomp 禁 setgid/setuid——privilege-dropping 代码被静默击杀（SIGSYS=-31）
+
+> **严重度**: 🔴 blocking | **分类**: kernel/seccomp/app-domain | **自动修复**: ❌ none
+
+---
+
+## 错误特征
+
+进程**随机静默死亡**，尤以带参路径为甚：
+
+```
+退出码 -31（SIGSYS）
+不可捕获（signal handler 装不上）、系统日志无声、无任何报错输出
+典型假象：「无参存活、带参死亡」——像参数解析 bug，实为 seccomp 击杀
+```
+
+实案（ipv6toolkit）：`libipv6.c release_privileges()` 非 root 分支调 `setgid()+setuid()`（本 id→本 id，Linux 语义为 no-op），在 app 域被 seccomp 策略直接击杀。
+
+## 根因
+
+OHOS app 域（HAP 沙箱）的 seccomp 过滤器**禁止 setgid/setuid 系 syscall**——即使参数是「本 id→本 id」的 no-op 调用也照杀（策略按 syscall 号拦截，不看语义）。进程死于 SIGSYS：不可捕获、不可掩码、内核级终止。与 E051（通用「未实现 syscall 触发 SIGSYS」）同一机制面，本条是该机制在 app 域 privilege-dropping 场景的具体实案。
+
+**诊断假象**：若 `usage`/argc 分支在 `geteuid()` 门**之前** return，无参调用在到达降权代码前已退出 → 「无参能跑、带参才死」，极易误诊为参数逻辑 bug（实案对应 03-adapt.json issues_resolved SIGSYS-31-addr6-argv）。先定位「进程死于 seccomp」再查参数路径，别反着来。
+
+## 修法
+
+- **非 root 分支直接 `return`**：进程本就以真实 uid/gid 运行，降权调用是纯冗余（实案落在全部工具共享的唯一入口 patches/002，一次修复全部工具受益）。
+- root→nobody 分支保持不变（该分支在 app 域本来也到不了——app 域进程不以 root 启动）。
+- 排查清单：库里凡 `setuid/setgid/seteuid/setgroups/initgroups` 或 capabilities 调用，以执行器 HAP 在 app 域 fork+execv 运行时都要过一遍。
+
+## 验证
+
+修复后带参执行退出码 0 且功能输出正确；`hilog` / 设备日志无 SIGSYS 记录。
+
+## 相关条目
+
+- E051：未实现 syscall 触发 SIGSYS 导致进程崩溃（通用机制与词表）
+- pc-knowledge-base：app 域 exec 与 seccomp 限制（平台机制详文）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L058.md

@@ -0,0 +1,74 @@
+<!-- 来源：new/PC（某图像编解码库全流水线多轮实证 2026-10-11） | 原编号 E180（重编号：L057 让位给 ipv6toolkit 沉淀条目） --> 一句话定位：宿主侧 hilog 捕获的过滤链三坑叠加，让「设备侧明明在出结果行」呈现为「捕获 0 字节 / 结果行丢失 / raw 巨量噪声」三种假象——①`-e` 正则里的 `|` 未整体加引号被设备 shell 拆成管道（raw 头部出现 `/bin/sh: XXX: inaccessible or not found` 即中招，捕获退化为 0 字节）；②按 bundle **全名**过滤必漏行（hilog 把长 bundleName 缩写为首字符+…，如 `com.example.superlong.runner.app` 显示为 `c_example.superlong.runner.app`），且结果行的 tag 是 OHPTCASE（runner 约定 tag），过滤表达式不含它就全滤掉；③过滤失效后退化全量捕获（MB/min 级系统噪声涌入），环形缓冲目标行被挤掉 + 宿主 raw 膨胀，残留捕获进程还会长期抢占设备日志流。解法：优先 `-T <tag>` 按 tag 精确过滤（无 shell 特殊字符）；必须正则时整体加引号且必含 `OHPTCASE`；捕获进程记 pid 收尾 + 清设备侧残留 hilog。
+
+# L058: hilog 捕获过滤三坑——`-e` 拆管 / bundle 名缩写漏行 / 过滤失效全量噪声
+
+> **严重度**: 2 major | **领域**: device-runner / 捕获取证 | **自动修复**: none（捕获脚本按 §解决方案 改写；标准取证姿势见 `pc-knowledge-base` 的 [[鸿蒙PC-hdc能力边界与取证通道.md]]）
+
+---
+
+## 问题现象
+
+设备侧 runner 实际在打 `OHPTCASE result=…` 行，宿主侧捕获却三种坏法（可叠加）：
+
+```
+1. raw 0 字节或仅几行，内容形如：
+   /bin/sh: OHPTCASE: inaccessible or not found
+   /bin/sh: JSAPP: inaccessible or not found
+   → -e 表达式里的 | 被设备端 /bin/sh 当管道拆开，hilog 输出接到了不存在的命令上
+2. raw 正常增长但 grep 不到任何 result/check/summary 行
+   → 过滤表达式按 bundle 全名（如 com.example.superlong.runner.app）匹配，而 hilog 显示的是缩写 tagpath
+     （s_universal.harmony_cli_runner/OHPTCASE），全名一个字符都对不上；且结果行
+     的 tag 是 OHPTCASE，表达式不含它则整行被滤
+3. raw 膨胀到百 MB 级（实测 1.3GB）、全是系统噪声（bluetooth/sceneboard 等），
+   目标行即使出现过也被环形缓冲挤出
+   → 过滤未生效退化全量捕获；上次中断的捕获进程（宿主 Start-Process / 设备侧
+     hilog）若未收尾，还会持续写盘并抢占日志流
+```
+
+特征：同一脚本上一轮能抓到行、下一轮 0 字节（表达式改动即踩坑 1）；「明明 result=pass 过几条却 grep 不到」（踩坑 2）；设备跑得越久 raw 越大越找不到目标（踩坑 3）。
+
+## 根因
+
+| # | 误诊（都排除过） | 真根因 |
+|---|---|---|
+| 1 | 「hilog -e 不支持正则 / 设备 hilog 坏了」 | `-e` 支持正则；坏在**参数没到达 hilog**——宿主 `Start-Process` 拼参后 `myrun\|OHPTCASE\|JSAPP` 裸传给设备 shell，`\|` 被 /bin/sh 解释为管道：`hilog -e myrun \| OHPTCASE \| JSAPP` → 后两段成了不存在的命令 |
+| 2 | 「设备侧没打结果行」（往 runner 排查） | runner 在打（设备直抓 `hilog -x -T OHPTCASE` 可见）；坏在**过滤表达式匹配不上**——hilog 把长 bundleName 压缩显示（首字符+…，如 `com.example.superlong.runner.app` 显示为 `c_example.superlong.runner.app`），按完整 bundle 名匹配必落空；结果行 tag 是 OHPTCASE，表达式漏了它整行被滤 |
+| 3 | 「设备日志系统有问题 / 缓冲太小」 | 过滤失效 → 全量系统日志涌入（几十 KB/s 级），环形缓冲几分钟就把目标行挤掉；宿主侧捕获进程是后台长驻进程（Start-Process PassThru），脚本异常退出不自动收尾，设备侧也可能残留 hilog 持续消费日志流 |
+
+## 判别方法
+
+1. raw 头部/尾部 grep `inaccessible or not found` ——命中即踩坑 1（拆管）；
+2. 设备直抓对照：`hdc shell "hilog -x -T OHPTCASE"` 能看到 result 行、而宿主 raw 里没有 → 踩坑 2（表达式匹配不上）；
+3. raw 抽样看内容构成：大量 bluetooth/sceneboard 等系统噪声 → 踩坑 3（过滤未生效）；`hdc shell "ps -ef | grep hilog"` 见残留捕获进程 → 需清理。
+
+## 解决方案
+
+```bash
+# ✅ 首选：-T 按 tag 精确过滤（无 shell 特殊字符，三个坑全避开）
+hdc shell "hilog -x -T OHPTCASE"
+
+# ✅ 次选：-e 正则必须整体引号包裹（引号要活到设备 shell 那层）
+hdc shell "hilog -e 'OHPTCASE|myrun'"
+
+# ❌ 反例（Start-Process 裸传参）：| 被设备 shell 拆管
+#    Start-Process hdc -ArgumentList @('shell','hilog','-e','myrun|OHPTCASE|JSAPP')
+```
+
+- 过滤表达式**必含 `OHPTCASE`**（结果行/summary 的约定 tag）；心跳/进度类的自定义 tag 按需并列。
+- 别按 bundle **全名**匹配 tagpath——hilog 会缩写；要么按 tag，要么匹配 tagpath 里稳定不变的**后缀**（如 `harmony_cli_runner`）。
+- 宿主捕获进程记 pid（`Start-Process -PassThru`）收尾 `Stop-Process`；设备侧收尾清残留：`ps -ef | grep hilog | grep -v grep | awk '{print $2}' | xargs kill`。
+- 长轮询脚本对 raw 抽**尾部增量**判进度，别全量读（GB 级文件会把轮询本身拖垮）。
+
+## 影响范围
+
+一切「宿主侧起捕获进程 + hilog 过滤回传证据」的路径：阶段 3 设备名册循环、verify-demo 取证、任何手写捕获脚本。三坑叠加时与 L055（看门狗失效整队卡死）互相掩护——队列卡死本就无新行，捕获再漏行，取证侧完全失明，极难分辨「没跑」与「没抓到」；同族取证断链 L056（env 传递）同样以「平台限制假象」污染归因。
+
+## 关联
+
+- L055：同库同轮的看门狗两种失效（队列卡死的上游根因；本条是取证侧放大器）
+- [[鸿蒙PC-hdc能力边界与取证通道.md]] —— hilog 取证标准姿势（提级/冷启动/清缓冲顺序）与共享设备混流双过滤；本条是其「-e 过滤与捕获进程收尾」的深化
+- L056：同族取证断链（env 传递），同样以「平台限制假象」污染归因
+
+## 实证
+
+某图像编解码库全流水线阶段 3（2026-10-11，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64）：连续多轮捕获全部失明——一轮 1.3GB 噪声（踩坑 3，过滤失效全量涌入）、一轮按 bundle 全名过滤 60 分钟 0 结果行（踩坑 2，tagpath 缩写匹配落空）、一轮 `-e` 三段正则裸传参 raw 仅 89 字节且含 `/bin/sh: OHPTCASE: inaccessible or not found`（踩坑 1，拆管）——与 L055 失效模式 2 叠加，构成连续七轮无一份合法 results.json 的完整根因链。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L059.md

@@ -0,0 +1,67 @@
+<!-- 来源：无托盘图表编辑器鸿蒙适配返修（HAD-W32 / OpenHarmony-7.0.0.105 / aarch64 真机实证 2026-10-16）
+evidence_level: E4
+summary_plain: Electron 应用鸿蒙 HAP 启动即报 Cannot find module '../xxx'——适配组装脚本把上游 app/ 内容拍平到载荷根（resources/app），改变了 index.js 相对引用解析基准却没同步改写引用字符串；Windows 版源码直跑从未重打包所以不触发。
+trigger: Cannot find module '.., Cannot find module '../, 打包路径错位, 相对路径, assemble-payload, payload 布局, showErrorBox 假活, 启动即报错
+verify: 对组装后的 payload 跑 check-payload-paths.mjs（扫描全部相对引用逐一解析）——断裂引用被 fail-fast 拦截即修复到位；真机冷启动不再报 Cannot find module 且出现完整窗口进程树。
+status: active -->
+一句话定位：Electron 应用打包进 HAP 时，**重打包改布局（把上游 app/ 子目录内容拍平到载荷根 resources/app）改变了 index.js 相对引用的解析基准，引用字符串（`../legacy`）未同步改写**——运行时从载荷根向上解析到 `resources/legacy`（不存在）→ 真机启动即 uncaughtException "Cannot find module '../legacy/ssh/ssh.js'"；Windows 版是 `electron ./app` 源码直跑、从未重打包、目录层级保持，所以不触发。
+
+# L059: Electron 打包目录重构导致相对路径错位——Cannot find module '../xxx' 解析出载荷根
+
+> **严重度**: 3 critical（启动即崩，核心功能不可用） | **领域**: electron-oh / 打包布局 / 载荷组装 | **自动修复**: 保持上游目录结构；确需重组时跑 check-payload-paths.mjs 静态校验
+
+---
+
+## 问题现象
+
+HAP 装机后真机启动即报：
+
+```
+A JavaScript error occurred in the main process
+Uncaught Exception: Error: Cannot find module '../legacy/ssh/ssh.js'
+in paths '/data/storage/el1/bundle/electron/resources/resfile/resources/app'
+Require stack: .../resources/app/index.js
+```
+
+表现：showErrorBox 假活（进程活着但无窗口）、无 BrowserWindow/renderer/GPU 子进程。构建/编译全绿——require 是**运行期**行为，构建不执行它。
+
+## 根因
+
+| 环节 | 事实 |
+|---|---|
+| 上游布局 | `source/app/index.js` 与 `source/legacy/` 是**源码根兄弟目录**——`../legacy` 从 app/ 向上解析到源码根 ✓ 上游 `electron ./app` 正确 |
+| 适配重打包 | 组装脚本（assemble-payload 类）把 **app/ 内容拍平到载荷根**（`resources/app/index.js`）→ index.js 上移一层 |
+| 引用未同步 | `require('../legacy/ssh/ssh.js')` 字符串仍是旧基准 → 从载荷根向上解析到 `resources/legacy`（不存在）✗ |
+| 搬迁做对的一半 | legacy/dist 被搬进载荷根内（`resources/app/legacy`）——因 HAP 载荷要求**应用根内自包含**（`../` 出不了载荷根/asar）——但搬文件 ≠ 改引用字符串 |
+| 同族漏网 | `<script src="./../dist/...">` 等 html/css 相对引用同样按旧基准，**同族必查** |
+
+**本质**：重打包改布局、不改引用——**平台无关的通用 bug 类别**。「文件必须进应用根」是 HAP/asar 自包含的真约束；「拍平 + 漏改引用 + 缺校验」是脚本 bug（拍平可选——保持 `resources/app/app/` 层级 + main 指向 `app/index.js` 完全合法）。
+
+## 判别方法
+
+1. 组装后对 payload 跑 **check-payload-paths.mjs**（扫描载荷内 js/html/css 的相对引用逐一解析，目标不存在或 `../` 逃逸载荷根即 FAIL）；
+2. 源码布局 vs payload 布局**逐引用核对**：从「app/ 内部指向 app/ 外部」的 `../` 引用是高风险（拍平必断）；指向 app/ 内部兄弟子目录的 `../view` 等拍平后关系保持、安全；
+3. Windows 对照：源码直跑（electron ./app）未重打包则引用基准不变——先确认 Windows 版跑通方式再对照。
+
+## 解决方案
+
+**第一原则：能保持上游目录结构就保持**——`resources/app/app/` + `legacy/`、`dist/` 放载荷根内兄弟位置，`package.json main` 指向 `app/index.js`（Electron 合法写法）。**结构不变 = 引用语义不变 = 零风险、零引用改动**。
+
+确需重组（拍平/扁平化）时，必须：
+1. **同步修正所有相对引用**（`../legacy` → `./legacy` 等）——含 html `<script src>`、css `url()` 同族；
+2. 组装后跑 **check-payload-paths.mjs** 作为 fail-fast 门禁（挂载到 assemble-payload/sync-payload 尾部）——无设备/无签阶段唯一能拦住运行期路径错误的静态手段；
+3. 装机后真机冷启动复验：无 Cannot find module + 完整窗口进程树。
+
+## 影响范围
+
+一切「重打包载荷」的 Electron 应用（鸿蒙 HAP 载荷 `resources/app`；electron-builder asar 同理）。Windows/Linux/macOS 源码直跑或保层级的打包不受影响——**触发条件是「重打包改布局 + 引用未同步 + 无人执行校验」**，与宿主平台无关。无设备/无签阶段（manual 档）构建全绿仍可能带此雷，必须静态校验兜底。
+
+## 关联
+
+- **校验工具**：`pc-recipe-electron-app`（build-tools）`check-payload-paths.mjs`——payload 相对引用完整性校验（fail-fast 门禁，挂载于组装脚本尾部）
+- `pc-knowledge-base/electron/guides/migration-guide.md`（载荷布局与相对引用纪律）
+- 正反例对照：drawio（保持 `src/main/electron.js` 层级 ✓ 零引用改动）/ 本案例（拍平 + 漏改引用 ✗）
+
+## 实证
+
+Electron-OH 无托盘图表编辑器（HAD-W32 / OpenHarmony-7.0.0.105 / aarch64，2026-10-16）：签名 HAP 真机启动即 "Cannot find module '../legacy/ssh/ssh.js'"（showErrorBox 假活、无窗口）。逐引用核对 11 处相对引用——仅 `index.js` 的 `../legacy` 与 `index.html` 的 `./../dist` 两处指向 app/ 外部、拍平后断裂。改 `../legacy`→`./legacy`、`./../dist`→`./dist` 后冷启动无此错、窗口链与 renderer/GPU 子进程全部出现。Windows 版（`electron ./app` 源码直跑）全程无此问题——未重打包。