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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/knowledge/case-studies.md

@@ -0,0 +1,250 @@
+# 鸿蒙 PC 三方库适配案例库
+
+> 面向场景：**鸿蒙 PC 设备本机原生编译（aarch64）**。每个案例提炼自一次真实适配，
+> 聚焦「这类库怎么落地、踩了哪些坑」。命令一律以**设备本机编译**为主线（设备上已装
+> clang/llvm、cmake、ninja、node、git 等 HNP 工具链，见 platform-notes §1）。
+>
+> 每节末尾 `<!-- src: ... -->` 仅供溯源，不是运行时路径。
+
+---
+
+## 1. ripgrep —— Rust CLI，近零改动
+
+- **库类型**：纯 Rust CLI（无 C/C++ FFI 依赖），下游消费者 opencode 通过环境变量
+  `OPENCODE_RG_PATH` 指向二进制。
+- **适配难点**：几乎没有源码难点——纯 Rust、内嵌 regex 引擎、终端色彩走 ANSI escape，
+  全部平台无关。真正的难点在**运行时 exec 限制**，不在编译。
+- **采用方案**：在设备本机用 Rust 工具链直接构建 release 二进制（按需启用 `pcre2`
+  feature；musl 静态链接最省事）。这是「近零改动」类库的范本：能跑通就别改源码。
+- **产物形态**：单个可执行文件 `rg`，装进 HNP 包结构
+  `ripgrep.org/ripgrep_<ver>/bin/rg`，或直接放到下游能 exec 的目录。
+- **关键坑**：
+  1. **HNP exec 限制**：若 `rg` 作为 HNP 包内二进制，被 app 域子进程经 `/bin/sh`
+     拉起会 `Permission denied`（`hnp_file` 标签，见 platform-notes §2、错误图谱 E054）。
+     修复套路：`cp` 物理拷贝到 `/data/local/tmp/<sub>/` 并 `chmod 755`，再让 opencode
+     的 `OPENCODE_RG_PATH` 指向这个拷贝（**软链无效，必须物理拷贝**）。
+  2. **feature 取舍**：是否启用 PCRE2 取决于下游是否用到 `--pcre2`；不需要就别引入额外依赖。
+  3. **不要过度适配**：纯 Rust 库优先「原样编 + 解决运行时」，避免无谓改源码。
+
+<!-- src: new/PC（ripgrep 适配实证） -->
+
+---
+
+## 2. @parcel/watcher —— C++ N-API，inotify 直接复用
+
+- **库类型**：C++ + N-API 原生模块，下游 opencode 文件监听走它。
+- **适配难点**：node-gyp 不认识鸿蒙平台；以及 backend 选型——上游有 inotify / brute-force /
+  watchman / wasm 多套后端。
+- **采用方案**：**inotify 后端零修改复用**（`<sys/inotify.h>` 是 Linux 内核接口，OHOS
+  内核基于 Linux，直接可用）。**用 CMake 直接把 `.cc` 编成 `.node`，绕过 node-gyp 的平台
+  检测**。backend 组合选 `INOTIFY` + `BRUTE_FORCE`（去掉 watchman，鸿蒙 PC 用户不会装
+  watchman 服务）。这是三个原生模块里最简单的，往往第一个跑通。
+- **产物形态**：`prebuilds/openharmony-arm64/watcher.node`，包装成
+  `@parcel/watcher-openharmony-arm64` npm 包雏形——opencode 已按
+  `@parcel/watcher-${platform}-${arch}` 模式加载，**新增此包即自动识别**。
+- **关键坑**：
+  1. **绕开 node-gyp**：node-gyp 平台识别没有鸿蒙分支，用 CMake 直编 `.node`（设置
+     `PREFIX ""` + `SUFFIX ".node"`，include 路径指向 Node hnp 的 `include/node` 与
+     `node-addon-api`），比 fork node-gyp 维护成本低。
+  2. **`<fts.h>` 可能缺失**：brute-force 后端用到 `<fts.h>`，musl 通常不带 fts，**第一步
+     就 `find` sysroot 确认**；缺了就 patch 或链 musl-fts，否则别开 brute-force。
+  3. **N-API 头文件版本对齐**：要跟随设备上 Node hnp 的 N-API 头，版本错位会编译/加载失败。
+  4. **wasm 兜底**：上游自带 wasm 后端，原生 prebuild 在某机型失败时可切 wasm 应急。
+
+<!-- src: new/PC（parcel-watcher 适配实证） -->
+
+---
+
+## 3. node-pty —— C++ N-API，先验 pty.h 再决定 fallback
+
+- **库类型**：C/C++ + N-API + TypeScript wrapper，下游 opencode 的 PTY/TUI 走它。
+- **适配难点**：核心在 `pty.cc` 用到 `forkpty`/`openpty`（来自 `<pty.h>`，glibc/musl 上
+  常需 `-lutil`）——**OHOS 用户态是否提供 `pty.h`/`libutil` 不确定，必须现场验证**。
+- **采用方案**：**先验证再决定路径**。第一步 `find $SYSROOT -name 'pty.h'`：
+  - 有 `pty.h` + libutil → 直接用 `forkpty`/`openpty`。
+  - 没有 → fallback 到标准 POSIX 组合：`posix_openpt(O_RDWR|O_NOCTTY)` → `grantpt` →
+    `unlockpt` → `open(ptsname(fd), O_RDWR)`。
+  同样**用 CMake 直编 `.cc` → `.node` 绕过 node-gyp**；Windows 的 winpty/conpty 部分编译时排除。
+- **产物形态**：`prebuilds/openharmony-arm64/node.napi.node`，对齐 `@lydell/node-pty` 的
+  `<platform>-<arch>` 加载约定。
+- **关键坑**：
+  1. **`pty.h`/`forkpty` 可用性是分水岭**：决定走原生 forkpty 还是 posix_openpt fallback，
+     **第一步就验证**，别盲目假设。
+  2. **`termios`/`ioctl(TIOCSWINSZ)`** 是基础 POSIX，musl 大概率支持；进程管理（waitpid/kill）
+     也是标准。难点集中在 pty 创建那一段。
+  3. **源码加 `__OHOS__` 兼容补丁**：binding.gyp/源码里新增 OHOS 条件分支，必要时把补丁
+     沉到 `patches/` 便于上游升级重放。
+  4. **测试要靠设备上的 sh/bash**：ptyTester 需要鸿蒙 PC 上可用的 shell 才能跑。
+
+<!-- src: new/PC（node-pty 适配实证） -->
+
+---
+
+## 4. cpprestsdk —— C++ 动态库，多依赖整合进单一 .so
+
+- **库类型**：C++ 动态库（HTTP client+listener + WebSocket + OAuth + JSON + PPLX），
+  供 HAR/HAP/Native 应用链接。依赖 Boost / OpenSSL / zlib / websocketpp 一整套。
+- **适配难点**：上游大量用 `#if defined(__ANDROID__) || defined(__linux__)` 区分平台；
+  Boost 的 b2 构建系统对鸿蒙工具链识别脆弱；多个静态依赖要干净地塞进一个 .so 还不能符号冲突。
+- **采用方案**：自底向上 5 层构建（OpenSSL → zlib → Boost 子集 → websocketpp → cpprestsdk），
+  最终交付**单一 `libcpprest.so`**。Boost 只编需要的子集（system/thread/chrono/atomic/
+  date_time/regex），filesystem/iostreams/locale 不编（YAGNI）。
+- **产物形态**：一个 `libcpprest.so` + 一套头文件；应用侧 `add_library(... SHARED IMPORTED)`
+  接入即可。
+- **关键坑**：
+  1. **`__OHOS__` + `__linux__` 双定义**：OHOS clang 同时定义两者，多数 linux 分支可直接
+     复用；少数处要显式加 `|| defined(__OHOS__)`（PPLX 线程调度、asyncrt datetime/locale、
+     http client/listener 的 socket option、websocketpp 桥接）。改动统一 `git format-patch`
+     到 `patches/` 便于升级 rebase。（参见错误图谱 E102 的「把 OHOS 从 linux 条件里排除/纳入」类问题。）
+  2. **Boost b2 的 toolset 必须是 `linux-ohos`**：b2/Jamroot 不会自动识别鸿蒙，需在
+     user-config.jam 里把 toolset 显式配成 `linux-ohos`（对应错误图谱 E099：boost b2
+     无法推断架构）；构建时 `target-os=linux threadapi=pthread`。
+  3. **CA bundle 路径**：HTTPS 验证需要 CA 证书，约定放 `/etc/ssl/certs/cacert.pem`
+     并让 OpenSSL/cpprest 指向它，否则证书校验失败（参见错误图谱 E034）。
+  4. **静态 .a 进单一 .so 的符号隔离**：Boost/OpenSSL/zlib 全部以静态 `.a` 链进
+     `libcpprest.so`，**链接时加 `-Wl,--exclude-libs,ALL`** 隐藏内部符号，避免应用自带的
+     OpenSSL 与库内嵌 OpenSSL 符号冲突。
+  5. **websocketpp 子模块为空**：上游子模块往往拉不到内容，需单独 clone v0.8.2 并 apply
+     SIG 的 OHOS patch。
+
+<!-- src: new/PC（cpprestsdk 适配实证） -->
+
+---
+
+## 5. opencode —— TS monorepo，Bun → Node 运行时迁移
+
+- **库类型**：TypeScript + Solid.js monorepo（pnpm workspaces，上游原生 Bun runtime），
+  终端用户在 HiShell 里直接 `opencode ...` 或 `opencode serve` + 浏览器访问。
+- **适配难点**：上游只支持 Bun runtime + `Bun.build --compile` 出的预编译 binary，无鸿蒙
+  形态；代码深度依赖 Bun API（`Bun.serve`/`bun:sqlite`/`Bun.ffi`）；鸿蒙的 HiShell 环境有
+  一堆路径/权限/uid 特殊性。
+- **采用方案**：把项目里已有但未维护的 **Node 兼容路径补完**（`#db.node.ts`/`#hono.node.ts`/
+  `#pty.node.ts` 条件导出）。用 **Bun 当构建工具**（`bun build --target=node` 出 ESM
+  bundle），但**产物跑在鸿蒙的 Node v24.13.0 hnp** 上。Bun-only 模块（bun:sqlite/bun-pty/
+  web-tree-sitter）用 shim 替换（如 `bun:sqlite → node:sqlite`）。
+- **产物形态**：单文件 ESM bundle `opencode.mjs`（~25 MB），装进 HNP 包
+  `opencode.org/opencode_<ver>/`，配 launcher 脚本 + 公共 bin symlink。
+- **关键坑**：
+  1. **`os.userInfo()` ENOENT**：HiShell 的 app uid 不在 `/etc/passwd`，`os.userInfo()`
+     抛 ENOENT；源码加 try/catch fallback（对应 platform-notes §3 uid 体系）。
+  2. **HNP / XDG / HOME 路径**：`/storage/Users/currentUser` 在 hmdfs union mount 下区分
+     调用源，Node `fs.mkdir` 可能被 deny；HOME fallback 到 `/data/local/tmp/opencode-home/`，
+     工程区也放 `/data/local/tmp/` 下（`/storage` tmpfs noexec，且涉及 hmdfs ACL，见
+     platform-notes §3/§5）。
+  3. **namespace 自引用死锁**：源码大量 `export * as Xxx from "./xxx"` 自引用，esbuild
+     默认输出 ESM 会死锁——所以用 Bun build 工具（它能正确处理）而非 esbuild。
+  4. **原生依赖三件套**：`@parcel/watcher`（案例 2）、`@lydell/node-pty`（案例 3）、
+     ripgrep（案例 1）需各自适配后塞进 `node_modules` / 由环境变量指向。TUI（`@opentui/core`
+     走 `bun:ffi` 加载 Zig 编的 libopentui）当前砍掉——无鸿蒙 prebuild。
+
+<!-- src: new/PC（opencode 适配实证） -->
+
+---
+
+## 6. NotepadNext —— Qt5 应用，交叉编译 + HAP 打包
+
+- **库类型**：Qt 5.15 C++ 应用（代码编辑器，基于 Scintilla），`delivery_form=app`，
+  `capability_dependencies=[qt-toolchain:available]`。
+- **适配难点**：
+  1. Qt6→Qt5 API 降级（`QLatin1StringView`→`QLatin1String`、枚举类型化、`QByteArrayView` 缺失需自定义）
+  2. Scintilla 需要 C++17（`std::optional`）
+  3. `QDockWidget` 在 OHOS 不可用，需整个 DockedEditor 重写为 QTabWidget
+  4. `SingleApplication` / `QFileOpenEvent` / `closeEvent` 等需 OHOS 特有处理
+- **采用方案**：
+  1. **Qt 版本选 5.15.17**（AUTOMOC 可用，API 接近上游，ETS 模板简化）
+  2. **OHOS 适配层**：`DockedEditorOhos`（QTabWidget 替代 QDockWidget）、`#ifdef __OHOS__` 守卫
+  3. **CMake 交叉编译**：`-G Ninja` + AUTOMOC ON + SHARED .so + 不链接平台插件
+  4. **HAP 打包**：`qt5-ohos.py init` 生成工程（自动检测签名），`qt5-ohos.py deploy` 部署 .so，`hvigorw assembleHap` 构建
+  5. **QPA+NAPI 统一插件**：`libplugins_platforms_qopenharmony.so` 同时充当 QPA 和 NAPI 模块，无需双路径部署
+- **产物形态**：`libNotepadNext.so`（~16 MB）+ HAP 包，在鸿蒙 PC 设备安装运行
+- **关键坑**：
+  1. **`appendPlainText` SIGABRT**：`QPlainTextEdit::appendPlainText()` 在 OHOS 上 widget 未完全初始化时触发 Q_ASSERT → SIGABRT。用 `QMetaObject::invokeMethod` + `QueuedConnection` + visibility 检查解决。
+  2. **不要链接 QPA 平台插件**：链接导致 `NEEDED` 写入动态段，运行时加载器在错误路径找库而崩溃。只链接 `Qt5::Core/Gui/Widgets`。
+  3. **`-G Ninja` 不可省略**：CMake 默认选 VS 生成器，回退 MSVC 编出 x86 .dll。
+  4. **Scintilla per-target C++17**：不能全局设，只对 scintilla target 设 `target_compile_features(scintilla PUBLIC cxx_std_17)`。
+  5. **`launchApplication` 必须在 `onCreate()` 中赋值**：ArkTS 类字段初始化器对 NAPI 不可见，QPA 读到空字符串 → dlopen 失败 → 白屏。
+  6. **`pages/Index.ets` 必须存在**：5.15.17 QPA 硬编码 `loadContent('pages/Index')`，缺此文件白屏。
+- **适配耗时**：API 降级 ~1 天，CMake 配置 ~0.5 天，HAP 打包 ~0.5 天，设备调试 ~1 天，总计 ~3 天
+- **经验沉淀**：
+  - Qt5 应用移植到鸿蒙是**可行且可复现的**，5.15.17 比 5.12.12 工作量大幅减少（AUTOMOC ON、无需手动 moc、ETS 简化）
+  - `qt5-ohos.py init/deploy` 脚本自动化了 HAP 工程生成和 .so 部署，零手动编辑
+  - OHOS 特有改动用 `#ifdef __OHOS__` 守卫，不破坏原平台编译
+  - 预构建 .so 方式比试图让 DevEco 直接调 CMake 更可靠
+
+<!-- src: pc-recipe-qt-app（NotepadNext 实测） -->
+
+---
+
+## 7. OpenSSL 3.x 族 C 库（某国密 OpenSSL 分支 实证）—— Provider 自检状态机阻塞 DRBG + 交付链卫生
+
+- **库类型**：C 动态库（OpenSSL 3.x 分支 + 国密 SM2/SM3/SM4/SM9/ZUC + SMTC 模块完整性自检），`delivery_form=cpp-lib`，`host_runtime=hap-dlopen`，构建系统 perl Configure（openssl 标准流程）。
+- **适配难点**：
+  1. provider 自检状态机在 app 域沙箱不可用（读模块文件被沙箱拦截）→ 全部标准算法不可用，但 provider 能加载能 fetch——这是最隐蔽的"链接→运行"断层。
+  2. 多补丁链（0001-0007）积累后，patch 0001 损坏被构建脚本 `|| echo 继续` 静默覆盖两年。
+  3. `cp -p` 保留 mtime 导致构建残留混编入 HNP/交付树，指纹匹配错误。
+  4. 执行器 HAP 的 cwd 只读（`/`），`fopen` 类测试套 `EACCES`。
+  5. no-engine 编译选项未显式关闭，干净重建时暴露的编译缺口。
+- **采用方案**：
+  - **RAND/DRBG 修复**：P0 根因链定位——SMTC 模块完整性自检需读自身 .so 用于完整性验证（`providers/smtc/self_test.c` 的 `do_smtc_self_test_init`），app 域沙箱内不可达 → `smtc_state` 停 `SMTC_STATE_INIT` → `ossl_prov_is_running()` = 0 → provider 侧 DRBG `newctx` 返回 NULL → `evp_rand.c:373` 报 03080006。修复：在 run-once 初始化中直接置 `smtc_state = SMTC_STATE_RUNNING`，前置条件为部署 config 不激活 SMTC provider（自检被跳过是安全的）。该修复路线与 OpenSSL FIPS 模块的沙箱兼容处理属同类问题。
+  - **交付链治理**：补丁应用失败 `exit 1`（去 `|| echo`）、全链 `git apply --check` 跑满、指纹三角验证（dist/HNP/HAP 三方 MD5 一致）、构建残留清理（`rm -rf` 临时文件后再编）。
+  - **执行器部署**：cwd 从 `/` 改可写目录（`/data/local/tmp/ntls-lib-cwd/`），修复 2 条 fopen 类用例。
+  - **半自动化验证**：`provider_diag` 工具（用纯 OpenSSL API 实现：`OSSL_PROVIDER_available`/`EVP_MD_fetch`/`EVP_CIPHER_fetch`/`EVP_RAND_CTX_new`/`RAND_bytes`）+ 测试套的 hilog 格式化（定向前缀 `TAP|`/`RAW|`/`DIAG|`/`FAILLOG|`，按包名过滤）。
+- **产物形态**：`libcrypto.so.3` + `libssl.so.3` + `libprovinit.so`（provider 初始化 shim，dlopen 触发 provider 注册），HAP 执行器 dlopen 加载。
+- **关键坑**：
+  1. **provider 运行态 ≠ provider 已注册**：`OSSL_PROVIDER_available()` 返回 1 只说明 provider 被加载注册了，`ossl_prov_is_running()` 返回 0 才是 DRBG 不可用的根因。Provider 的状态机（INIT/RUNNING/ERROR）是独立于注册状态的——这是在 OpenSSL 3.x 系上第一次遇到的"注册了但运行不起来"的断层。
+  2. **03080006 的错误码阶梯比错误码本身重要**：相邻轮次从 0308010C（fetch 阶段，provider 没注册）→ 03000086（init 阶段，provider 已注册但 init 失败）→ 03080006（RAND context 建不出，自检状态机），反向证明自检状态机是最后一层。这个阶梯指纹可用于排查同类问题。
+  3. **补丁损坏的静默掩盖是最高危的交付缺陷**：构建绿不是"补丁已应用"的证据。必须做 `git apply --check` 全链 + 产物指纹或符号抽样。
+  4. **`cp -p` 保留 mtime 陷阱**：`cp file.so dist/ && cp -p dist/file.so hnp/lib/` → 两个文件 mtime 相同 → `find -newer` 找不出差异 → 构建脚本认为"没变"→ 跳过重建 → 混入旧库。根治：每次构建前清空 dist/ + HNP staging，或在构建脚本里强校验 MD5。
+  5. **HNP 内库需要与应用私有 HAP 的库指纹一致**：dlopen 场景下 HAP 内嵌 HNP 与最终在设备上加载的 .so 必须是同一个文件（MD5 一致），否则算交付不完整。验证方法：本地解包 HAP 计算 MD5，与 dist/ 和 HNP staging 对比。
+  6. **故障注入测试的双重作用**：同一组 provider_diag 同时服务于"验证修复"和"验收门槛"——RAND_bytes > 0 既是修复达线也是验收达线，避免了上下游过失交叉。
+- **适配耗时**：RAND/DRBG 根因定位与修复 ~2 天（含 provider 源码阅读 + 设备诊断 + 错误码阶梯分析），交付链治理 ~0.5 天（补丁重写 + 脚本加固 + 指纹链 + cwd 修复），设备验证 ~1 天（反复冷启动 + 真机取证），总计 ~3.5 天
+- **经验沉淀**：
+  - OpenSSL 3.x 系 provider 的"注册"与"运行态"是两回事——后者依赖模块完整性自检状态机，而自检读模块文件在 app 域沙箱不可达。这一条适用于所有 OpenSSL 3.x 变体（含 FIPS 模块），与具体库名无关。
+  - 构建脚本的补丁应用失败必须 fail-fast。`|| echo 继续` 模式制造的"构建绿但交付物缺改动"是浪费最多排查时间的缺陷类型，必须作为交付红线。
+  - 多步交付链的 fingerprint triangulation（dist/HNP/HAP 三方 MD5 一致）是低成本但高回报的验证方法——cp 时间戳陷阱、构建残留混编、多副本不一致等问题都是一轮 MD5 比对就能暴露的。
+  - `provider_diag` 类工具（纯 API 实现的运行态诊断，不依赖客户端代码）对所有 OpenSSL 3.x 系适配是通用可复用的，建议作为交付标准装备。
+
+<!-- src: repos-pc/某国密OpenSSL分支 适配实证（2026-09-11） -->
+
+---
+
+## 8. 某 C++ 跨平台框架库（Foundation/Net/Data 子集）—— 8 补丁全流程：SysV IPC 桩 + SQLite 沙箱路径 + Foundation SIGSEGV + hap 富用例异常保护
+
+- **库类型**：C++ 跨平台网络/应用框架库（提供线程、文件、网络、XML/JSON、数据库访问等基础能力），`delivery_form=cpp-lib`，`host_runtime=hap-dlopen`，构建系统 CMake。
+- **适配难点**：
+  1. CMake 不识别 OHOS 为 UNIX 平台 → UNIX 源文件全部漏编（CMAKE_SYSTEM_NAME=OHOS 时 CMake `UNIX` 变量为 FALSE，Foundation 组件源文件空）
+  2. musl 缺 `pthread_setaffinity_np`（GNU 扩展）→ Thread_POSIX.cpp 编译 error
+  3. SysV IPC（`ftok`/`semget`/`semop`）在 app 域被 seccomp SIGSYS 拦截 → 静态初始化时即秒退
+  4. 锁文件硬编码 `/tmp`（app 域不存在）
+  5. NDK 路径含空格需引号封装
+  6. SQLite 数据库文件在只读 cwd 下创建失败 → testrunner 全部 ERROR/crash
+  7. `SharedMemory::create` 的 shm_open 命名模式在 app 域 mount namespace 下 `mmap(MAP_SHARED)` 死锁
+  8. 多线程测试（Thread::interrupt）在 musl 退出时 SIGSEGV
+- **采用方案**：
+  1. **toolchain 伪装 Linux**：`CMAKE_SYSTEM_NAME=Linux` + `CMAKE_SYSTEM_PROCESSOR=aarch64`，直调 OHOS NDK clang，951/951 编译任务通过（对照 Android 路径同款做法）
+  2. **8 补丁链**：0001=affinity 守卫 → 0002-0003=NamedMutex/NamedEvent 切 Android 桩后端（空构造/NotImplementedException）+ TMPDIR 分支 → 0004=testsuite 豁免 → 0005=testrunner cwd 改可写沙箱 + 信号捕获 + 数据复制 → 0006=SharedMemory 文件映射代替 shm_open（hap-namedipc-stub 死锁解）→ 0007=cppignore 追加绕过 SIGSEGV 测试 → 0008=hap 富用例分派层 try-catch 保护 + RecordSet 判空 + 编码可用性探测
+  3. **设备验证执行器模式**：ninja 交叉编译 CLI testrunner → 打私有 HNP（含 19 个 testrunner + 3 CLI + 16 动态库）→ HAP 的 napi_stub 层 fork+execv 拉起 → pipe 采集 CppUnit 输出 → hilog 回传 TAP/RAW 行 → 名册对账脚本匹配 Class::method 行
+  4. **运行时数据自举**：zoneinfo + CA bundle 打进 pkg/share/，`TZ`/`SSL_CERT_FILE` 环境变量在 exec 前注入
+  5. **cppignore 绕过不稳定测试**：`CppUnit::TestCaller<ThreadTest>.testInterrupt`（SIGSEGV 崩溃点）和 `testAffinity`（musl 无 setaffinity 缺口）加入忽略列表，Foundation 测试从 555 条 crash 提升到 938 条完整通过（Runs: 938, Failures: 4, Errors: 0）
+- **产物形态**：16 个 .so（Foundation/Net/NetSSL/Crypto/JSON/XML/Data/SQLite/Encodings/Zip/Util/JWT/MongoDB/Redis/Prometheus/ActiveRecord）+ 3 CLI + 16 testrunner → HNP 包（45MB）+ 签名 HAP 执行器
+- **关键坑**：
+  1. **CMAKE_SYSTEM_NAME 的 UNIX 悬崖**：选了 OHOS 作为 `CMAKE_SYSTEM_NAME`，CMake `UNIX` 变量直接 FALSE，`if(UNIX)` 分支的源文件全部不编译。必须用 Linux 伪装——这是 CMake 对 OHOS 平台的根本性不识别，不限于特定库。
+  2. **SysV IPC 静态构造秒退**：NamedMutex/NamedEvent 使用 `ftok`+`semget` 在静态初始化阶段就会被 seccomp SIGSYS 杀死——不等你进 main()、不等你加 try-catch。必须在编译时就切到 Android 桩后端（条件是 `#if defined(__OHOS__)`），运行时 no-op 空构造 + 调用时抛 `NotImplementedException`。
+  3. **shm_open 命名模式死锁**：`SharedMemory(name, size, mode, server=true)` 走 `shm_open("/dev/shm/...")` + `mmap(MAP_SHARED)`，app 域 mount namespace 下 mmap 永久卡住（两轮复现）。替代方案：预创建文件后用 `SharedMemory(File(path), mode)` 文件映射构造函数——走普通文件 `open()`+`mmap()`，不依赖 `/dev/shm`。
+  4. **testrunner cwd 只读**：fork+execv 之后的 cwd 指向 HNP 安装目录（`/data/app/.../bin`），不可写。SQLite 创建 `test.db`、FileStream 创建临时文件全部失败。解法：`kCases[].cwd` 元数据加 `"sandbox"` 标记，exec 前复制数据文件（cppignore/pem/xml/data/）到可写沙箱目录再 chdir。
+  5. **信号捕获补丁**：前几轮调试 `rc=-2`（WIFEXITED=false）只知道进程被信号杀，不知道具体信号。0005 补丁在 `waitpid` 后加 `WIFSIGNALED`/`WTERMSIG`/`WCOREDUMP` 回传——直接锁定 SIGSEGV（signal 11）而非误判的 SIGSYS。这个捕获模式适用于**所有** fork+execv 场景下的崩溃诊断。
+  6. **cppignore 绕过 vs 名册 accounting**：用 cppignore 跳过的测试在 02-baseline 名册里仍存在。跳过不等于豁免——丢失的用例仍在 roster.missing 中，需要登入 exemptions[] 附证据或后续修代码解决。
+  7. **库级测试的 exec 可行性验证**：Foundation 的 `testSelf`（PathTest）和 `testGetExecutablePathRelative`（FileTest）依赖于 `/proc/self/exe` 沙箱路径包含特定子串——app 域 HNP 部署路径不含，导致 FAILURE。这是测试假设了特定部署场景，非库功能缺陷。
+- **适配耗时**：toolchain + 4 补丁 ~1 天，testrunner cwd 沙箱化 ~0.5 天（含 SQLite 问题排查），SharedMemory 死锁排查与修复 ~0.5 天，Foundation SIGSEGV 定位与 cppignore ~1 天（含多轮信号捕获迭代），设备验证与名册对账 ~1 天，总计 ~4 天
+- **经验沉淀**：
+  - OHOS app 域 C++ 库的"编译通过 → 运行正确"之间存在三个断层层：①静态构造中的 SysV SIGSYS（秒退、零输出）②初始化阶段的 shm_open/mmap 死锁（worker 线程不可恢复）③退出时的线程析构 SIGSEGV。每个断层可以在**编译时守卫**（Android 桩）、**运行时构造替换**（文件映射）、**测试框架层绕过**（cppignore）三选一解决。
+  - `waitpid` + `WIFSIGNALED/WTERMSIG` 信号捕获是 fork+execv 执行器中**成本最低回报最高的调试装备**——在 hilog 里看到 `child terminated by signal 11 SIGSEGV core=dumped` 而非 `rc=-2`，可以直接把排查方向从"可能 SIGSYS/seccomp"缩小到"内存访问错误"。
+  - CPPUNIT 类测试框架的 `-ignore` 机制（cppignore.lnx）是绕过不可修复的测试失败、暴露剩余测试结果的合法手段——crashed 测试用 `rc=-2` 截断全部输出，跳过后用 `rc=1` 跑完全部再输出 4 个明确 FAILURE。
+   - CMake `CMAKE_SYSTEM_NAME=Linux` 隐藏是 OHOS NDK 交叉编译的标准路数——Linux 作为一个成熟的分支在 CMake 生态中获得最广泛的 UNIX 条件编译支持。所有用 `if(UNIX)` 或 `if(CMAKE_SYSTEM_NAME MATCHES "Linux")` 做平台分叉的 CMake 项目都可以套用。
+   - **hap 富用例分派层必须 try-catch 兜底**（补丁 0008 实证）：NAPI 壳里 `poco_hap_case()` 分派到各富用例函数，任何用例抛异常（如 `Poco::RangeException`、`NotFoundException`）若不捕获，worker 线程直接 terminate → 整个进程 SIGABRT → 后续所有用例全部丢失。在分派层包 try-catch 后，异常变成 `not ok` 且**进程继续跑完剩余用例**（35 条全套无崩溃实证）。这是 cli-hnp-runner / cpp-lib-demo 骨架的通用改进，scaffold 生成物也应自带。
+   - **富用例内部防御**：①`RecordSet::value(row,col)` 越界抛 `RangeException`——取前先 `rowCount() > 0` 判空；②`TextEncoding::byName("Windows-936")` 等编码/能力类查找在部分构建上抛 `NotFoundException`——先探测可用性，不可用记 `blocked` 而非失败。两类都是「用例写得太脆」的典型，改用例不库。
+   - **注册表类能力必须显式初始化**：`TextEncoding::byName()` 只能查到**已注册**编码。该框架的 Encodings 库把 ISO8859/Windows*/Mac* 等额外编码编进 `libPocoEncodings.so`（符号在、`llvm-nm -D` 可见），但**运行时不会自动注册**——必须先调 `Poco::registerExtraEncodings()`，否则 `byName("Windows-936")` 抛 `NotFoundException` 误判「编码不可用」。规律：凡是「提供方/注册方分离」的能力库（编码、驱动、provider、插件表），链接成功 ≠ 注册成功，第一步先找显式注册入口。
+   - **断言字符串必须匹配真实输出格式**：`PatternFormatter("%p")` 输出优先级为 `"Information"`（首字母大写，见 `PatternFormatter.cpp` 的 `DEFAULT_PRIORITY_NAMES`），测试断言却搜 `"INFORMATION"`（全大写）→ 恒失败。排查顺序：断言不匹配时先看**真实输出长什么样**（`raw` 里已打印），再决定是改断言还是改实现——这里框架行为正确、测试写错，属 testcase-defect 走 fixed-test。
+   - **同一用例集跑两轮结果不同的「偶发崩溃」**：`tn-foundation` 同一 HAP 有时 `rc=1`（938 runs 全跑）有时 `rc=-2`（4 runs 崩）——musl 上多线程析构的非确定性。cppignore 绕过只能缓解不能根除；评估时按「能跑出来的最好结果」计名册、按「偶发风险」记 remaining_blocker。
+
+<!-- src: 某 C++ 框架库适配实证（2026-09），匿名化 -->

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/knowledge/platform-notes.md

@@ -0,0 +1,349 @@
+# 鸿蒙 PC 平台机制速查（hdc shell 视角）
+
+> 面向场景：通过 hdc 操作鸿蒙 PC 设备时必须懂的系统底座机制。这些机制与具体跑哪个库无关。
+>
+> ⚠️ **本篇部分内容成文于够得到 `/data/app` 的环境**。鸿蒙 PC 上 hdc shell 是 uid 2000：
+> `/data/app/el1|el2` 与 `/data/log/faultlog` 均 Permission denied、`/data/service/hnp` 不存在、
+> `/data/local/tmp` 可写但**不可执行**、`nsenter` 用不了。凡标 ⛔ 的小节在本机上**不适用**，
+> 已就地标死并给出替代路线。能力边界权威：[[鸿蒙PC-hdc能力边界与取证通道]]。
+>
+> 每个事实块末尾的 `<!-- src: ... -->` 是来源标注，仅供溯源，不是运行时路径。
+
+---
+
+## 1. HNP 包与 PATH
+
+**HNP（Harmony Native Package）= 鸿蒙的原生命令行包格式。** 公共包统一装在：
+
+```
+/data/app/el1/bundle/<userId>/hnppublic/<pkg>.org/<pkg>_<version>/
+```
+
+其中 `<pkg>.org` 是包目录、`<pkg>_<ver>` 是版本目录，内部是标准 `bin/`、`lib/`、
+`share/` 结构。常见已装包：`node.org`、`git.org`、`python.org`、`ruby.org`、
+`perl.org`、`cmake.org`、`ninja.org`、`make.org`、`gawk.org`、`grep.org`、
+`bash.org`、`binutils.org`、`ohos-sdk.org`、`hdc.org` 等（含原生编译要用的
+clang/llvm 工具链与构建工具）。
+
+**PATH 差异（关键，最常踩坑）：**
+
+| 环境 | PATH |
+|---|---|
+| hdc shell 默认 | `/usr/local/bin:/bin:/usr/bin:/system/bin:/vendor/bin` |
+| HNP 应用进程 | `/usr/local/bin:/data/app/bin:/data/service/hnp/bin:/usr/bin:/vendor/bin` |
+
+`/data/service/hnp/bin/` 是 HNP 各包可执行文件的统一汇总目录，**只在应用 mount
+namespace 里挂出**。后果：
+
+- hdc shell 默认 `which git`、`which node` 会**找不到**（不在默认 PATH，且该目录在
+  hdc shell 视图里也不存在，见 §4）。
+- HNP 应用进程的 PATH 里才有 `git`、`node`、`cmake` 等命令。
+
+**⛔ 在 hdc shell 里调用设备已装 HNP 工具：鸿蒙 PC 上两种方法都不通**
+
+```bash
+# 方法一：走物理绝对路径 —— /data/app/el1 对 uid2000 是 Permission denied
+/data/app/el1/bundle/<userId>/hnppublic/git.org/git_2.45.2/bin/git --version
+# 方法二：进 namespace 用 PATH —— nsenter: /proc/<pid>/ns/mnt: Permission denied
+nsenter -t <pid> -m -- /data/service/hnp/bin/git --version
+```
+
+**替代**：需要哪个工具就**自带**——打成私有 HNP 随执行器 HAP 装机，在 app 域 `fork/execv`
+（`ohpt-agent scaffold --kind cli-hnp-runner`）。别据"够不到"判定"设备上没有"。
+
+**排查清单（够得到 `/data/app` 的环境才可用）：**
+
+1. `ls /data/app/el1/bundle/<userId>/hnppublic/` —— 看哪些包已装。
+2. `ls /data/app/el1/bundle/<userId>/hnppublic/<pkg>.org/<pkg>_<ver>/bin/` —— 看包提供的具体命令。
+3. `cat /proc/<pid>/environ | tr '\0' '\n' | grep ^PATH` —— 看应用进程真实 PATH，确认能否找到工具。
+4. HNP 安装的应用，`/proc/<pid>/cmdline` 一般指向 `/data/service/hnp/<pkg>.org/<pkg>_<ver>/...`。
+
+<!-- src: memory/platform/鸿蒙PC-HNP包与PATH.md -->
+
+---
+
+## 2. SELinux/MAC exec 限制（`hnp_file` 标签）
+
+**机制：** 任何 HNP 包内的二进制，若被 **app 域进程 fork 出的子进程**（典型是经
+`/bin/sh -c` 再 exec）拉起，会撞上 OHOS MAC（`hmmac`）的 exec 限制。
+
+**现象：**
+
+```
+/bin/sh: /data/service/hnp/<pkg>.org/<pkg>_<ver>/bin/<tool>: Permission denied
+```
+
+该二进制实际是 `-rwxr-xr-x root:root`（DAC 权限没问题），`ls -Z` 显示标签
+`u:object_r:hnp_file:s0`。**`dmesg | grep avc` 看不到任何 avc denied** —— `hmmac`
+走 OHOS 私有 hook，不打标准 SELinux audit，排查时别指望 dmesg。
+
+**根因：**
+
+- 挂载本身没有 `noexec`（`/data/service/hnp` 是 `rw,nosuid,nodev,noatime`），问题不在挂载选项。
+- `hnp_file:s0` 标签对 app 域**只允许「宿主进程入口直接 exec」**（如 `node opencode.mjs`
+  自身能跑），但**不允许 app 域子进程再经 `/bin/sh` 去 exec 别的 `hnp_file`**。
+- 物理路径 `/data/app/.../hnppublic/...` 与 app NS 视图 `/data/service/hnp/...` 是同一份
+  文件的不同视图（见 §1、§4），**标签相同，从哪条路径 exec 都 deny**。
+
+**通用修复套路：把二进制物理拷贝（不是软链）到 `data_local_tmp` 标签目录：**
+
+```bash
+hdc shell "cp <hnp物理路径>/bin/<tool> /data/local/tmp/<sub>/<tool> && chmod 755 /data/local/tmp/<sub>/<tool>"
+```
+
+`/data/local/tmp/<sub>/` 下文件标签继承为 `data_local_tmp:s0`，app 域子进程可 exec。
+随后让目标程序通过环境变量 / 配置 / PATH 指向它（属各库适配范畴）。
+
+**反例（都不行）：** ❌ `chmod 777`（权限位本就 755，问题不在 DAC）；❌ `chcon` 改标签
+（OHOS 无标准 chcon，且系统 HNP 文件不能动）；❌ **软链到 `/data/local/tmp`**（软链对
+exec 时的标签解析无效，最终 exec 的还是 `hnp_file` 目标，**必须 `cp` 物理拷贝**）；
+❌ 改 HNP 包内文件 / launcher（系统级文件，升级会被覆盖）。
+
+<!-- src: memory/platform/鸿蒙PC-HNP二进制SELinux-exec限制.md -->
+
+---
+
+## 3. uid 体系与文件归属
+
+**关键 uid：**
+
+| uid | 身份 | 说明 |
+|---|---|---|
+| `0` | root | 系统进程；**hdc shell 不是它**（鸿蒙 PC 上 hdc shell 恒为 2000） |
+| `20001006` | file_manager（系统服务） | 拥有 `/storage/Users/currentUser` 整个 HOME 树（Desktop/Documents/.ssh/.ohos_git/...）及 `/storage/media/<userId>/local/files/Docs/Desktop` 物理路径下所有文件 |
+| `200xxxxx` | 普通应用 | 每个 HNP/HAP 应用一个独立 uid（如 OpenCode = `20020107`） |
+
+uid 计算规则：`uid = 100 * 200000 + appId`，例如 `20020107 = 100*200000 + 20107`（user 100 的应用）。
+
+**桌面/HOME 目录权限模式：**
+
+```
+drwxrws--x 20001006 file_manager   # setgid（s 位），others 只有 x
+-rw-rw---- 20001006 file_manager   # 文件 660
+```
+
+**普通应用 uid 在标准 POSIX 权限下既不能 read 也不能 ls。** 但应用实际能访问，是因为：
+
+1. HarmonyOS 通过 FilePicker / SAF（Storage Access Framework）/ ACL 给应用授权。
+2. hmdfs/sharefs 挂载时附加 `hmmac=use_task` 等扩展安全模块，按 task 维度判权限。
+
+**这就是「硬编码物理路径写文件」经常翻车的原因——绕过了授权层。** 应用访问桌面/HOME
+应走 FilePicker/SAF（配合 `hmmac=use_task`），**不要硬编码物理路径**。
+
+**排查清单：**
+
+- 写文件失败 / 应用读不到：先确认 uid 与 owner 是否一致。
+- 应用进程能访问、但 hdc shell 写完应用看不到：不是权限问题，是 namespace 视图问题（见 §4）。
+- Git 报 dubious ownership：基本是 uid 不一致触发的安全策略，用 `safe.directory` 放行（见 §6）。
+
+<!-- src: memory/platform/鸿蒙PC-uid与文件归属.md -->
+
+---
+
+## 4. 进程视角与 mount namespace
+
+**核心结论：hdc shell（uid 2000）和应用进程看到的文件系统不是同一个视图。** 同一条
+绝对路径，可能在 hdc shell 里 "No such file or directory"，在应用进程里却是合法路径。
+
+原因：每个应用进程有独立的 mount namespace，鸿蒙通过 hmdfs/sharefs 把 HOME、桌面等挂
+进应用 namespace；hdc shell 不在那个 namespace。
+
+**典型「hdc shell 看不见」的路径：**
+
+| 应用视角 | hdc shell 视角 |
+|---|---|
+| `/storage/Users/currentUser` | unreachable（`/proc/<pid>/cwd` 显示 `(unreachable)/...`） |
+| `/data/service/hnp/bin/` | No such file or directory |
+| `/data/service/hnp/<pkg>.org/...` | No such file or directory |
+
+**定位映射关系（关键三件套）：**
+
+```bash
+cat /proc/<pid>/environ  | tr '\0' '\n' | grep -E '^(HOME|PATH|XDG)'
+cat /proc/<pid>/status   | grep -E '^(Uid|Name|PPid)'
+cat /proc/<pid>/mountinfo
+```
+
+`mountinfo` 能看到如 `/storage/Users/currentUser → hmdfs /data/service/el2/100/hmdfs/account`。
+**但物理路径写入 hmdfs 后端，不会自动出现在应用视图**（hmdfs 是双向同步分布式文件系统，
+不是简单 bind mount）。要写应用能直接读到的位置，必须从应用 namespace 写。
+
+**⛔ 跨 namespace 执行命令：鸿蒙 PC 上做不到**
+
+```bash
+# /bin/nsenter 存在，但 uid2000 用不了：/proc/<pid>/ns/mnt: Permission denied
+nsenter -t <pid> -m -- <command>
+```
+
+**替代**：让应用自己做（要给宿主看就写公共目录 `/storage/media/<userId>/local/files/Docs/…`，
+宿主侧可读写），或把东西打进 HAP/私有 HNP 随装机带入。
+**诊断不受影响**：`/proc/<pid>/{environ,status,mountinfo}` 对 hdc shell 可读。
+
+
+**常见误判：** hdc shell 里 `ls /storage/Users/currentUser` 报错 ≠ 应用看不到 HOME；
+`hdc file send` 推到物理 hmdfs 后端 ≠ 应用立即可见；`which git` 在 hdc shell 找不到 ≠
+应用进程找不到。
+
+<!-- src: memory/platform/鸿蒙PC-进程视角与mount-namespace.md -->
+
+---
+
+## 5. 桌面路径映射
+
+电脑端逻辑路径与 hdc shell 真实路径**不一致**，主用户 `userId=100`：
+
+| 视角 | 路径 |
+|---|---|
+| 电脑端 / 应用逻辑路径 | `/storage/Users/currentUser/Desktop` |
+| hdc shell 真实物理路径 | `/storage/media/<userId>/local/files/Docs/Desktop` |
+
+- 推/拉文件：`hdc file send <本地> <设备>` / `hdc file recv <设备> <本地>`。
+- `/storage/cloud/<userId>/...` 是云空间镜像，**不要写入**。
+- 应用进程访问桌面应走 FilePicker/SAF，不要硬编码物理路径（见 §3）。
+- hdc shell（uid 2000，属 `file_manager` 组）看到的是底层物理路径，**这棵树可读可写**
+  （2026-09-01 实测：`/storage/media/100/local/files/Docs/` 下 Desktop/Documents/Download 齐全，
+  宿主侧能读能写）；电脑端文件管理器看到的是沙箱化逻辑路径，两者不一致。
+- **这条是宿主 ↔ 应用之间唯一的机器可读文件通道**：应用申请
+  `READ_WRITE_DOCUMENTS_DIRECTORY`/`READ_WRITE_DOWNLOAD_DIRECTORY`（normal 级、user_grant）后写进去，
+  宿主从物理路径读回。见 [[鸿蒙PC-app访问PC用户目录]]。
+
+<!-- src: memory/platform/鸿蒙PC-进程视角与mount-namespace.md -->
+
+---
+
+## 6. git safe.directory（跨 uid dubious ownership）
+
+**两点与上游不同：**
+
+**(1) global gitconfig 路径被改了。** 鸿蒙 PC 上 HNP 装的 git 把 `--global` 配置文件
+改成 `$HOME/.ohos_git/.gitconfig`（不是标准 `~/.gitconfig`）。直接写 `~/.gitconfig`
+**无效**。验证：`git config --global --list` 会报 `unable to read '$HOME/.ohos_git/.gitconfig'`。
+
+**(2) safe.directory 跨 uid 拦截。** file_manager 服务（uid 20001006）拥有桌面/HOME 下
+所有文件，应用进程是别的 uid。Git ≥ 2.35.2 的 CVE-2022-24765 防御会拒绝跨 owner 仓库：
+
+```
+fatal: detected dubious ownership in repository at '/storage/.../xxx'
+```
+
+**修复（必须在应用 namespace 下执行，因为要写到应用 HOME 的 `.ohos_git/`）：**
+
+```bash
+nsenter -t <pid> -m -- env HOME=/storage/Users/currentUser \
+  /data/service/hnp/bin/git config --global --add safe.directory '*'
+```
+
+写出的文件内容：
+
+```
+[safe]
+	directory = *
+```
+
+**别用 printf 手拼**配置（常把 `\n`/`\t` 当字面量写进去，git 报 `bad config line`）。
+要么用 `git config` 命令，要么写 here-doc。
+
+**持久性提醒：** `.ohos_git/.gitconfig` 在 hmdfs 用户视图里，**应用更新或恢复出厂会丢**。
+桌面项目反复出现「非 git 仓库」误判时，重跑同样命令即可。
+
+<!-- src: memory/platform/鸿蒙PC-定制git行为.md -->
+
+---
+
+## 附录：从 Mac 访问设备网络服务（hdc fport）
+
+文件系统跨域用 `nsenter`（§4），**网络服务跨域用 `hdc fport`**，两套机制独立。
+
+- 鸿蒙 PC wlan0 上的 IP 多半是 `100.125.x.x`（华为内部 CGNAT 段），从 Mac **ping 不通、
+  直连超时**。
+- 正确姿势：`hdc fport tcp:<本地端口> tcp:<设备端口>` 把设备端口转发到 Mac
+  `127.0.0.1`，客户端工具都连 `127.0.0.1`；`hdc fport ls` 查看现有转发。hdc 重启会丢，需重建。
+- 设备端口要靠 `netstat -tlnp` / `ss -tlnp` 实测，别信 UI 占位符文案。
+- **Mac 上 curl 可能被本机 socks5 代理（ClashX/Stash）劫持**，即便连 `127.0.0.1` 也超时。
+  务必加 `--noproxy '*'`，或先 `unset all_proxy http_proxy https_proxy ALL_PROXY HTTP_PROXY HTTPS_PROXY`。
+
+<!-- src: memory/platform/鸿蒙PC-从Mac访问设备网络服务.md -->
+
+---
+
+## 附录：HAP 装机签名 9568329 三根因速查
+
+`hdc install` 报 `code:9568329 verify signature failed` 时，先分根因再动手（详细见 E164）：
+
+| 根因 | 特征 | 验证 | 修复 |
+|---|---|---|---|
+| **zip 重复条目** | 构建期 zip 注入未查重（libc++_shared 进两次） | `python -c "import zipfile,collections;print([n for n,c in collections.Counter(zipfile.ZipFile(r'<hap>').namelist()).items() if c>1])"` 非空 | 注入前 `zip_has_entry` 查重，重建重签 |
+| **profile 内嵌证书 ≠ 签名证书** | 用 DevEco/Release 证书签 Debug-profile HAP；`verify-app` 却报 Verify success | `hap-sign-tool.jar verify-app` 看 `certificate #0 Subject`——Debug profile 下必须是 `CN=<App>`（Debug 证书），是 `CN=OpenHarmony Application Release` 即错配 | 重跑 `sign_hap_s1.ps1`（S1 流程，Debug 证书 + 匹配 profile） |
+| **profile bundleName ≠ HAP bundle** | `ohpt-agent sign-demo` 未传 `--demo-dir` 读到别的工程 | 对比 profile.json 的 bundle-name 与 HAP module.json 的 bundleName | 签名时传对工程目录 |
+
+**一句话**：HAP 签名链要同时满足「链到设备信任根（9568257 侧）+ 无重复 zip 条目 + profile 与签名证书/bundle 一致（9568329 侧）」。装机失败别只盯着信任链，先跑 E164 的三步诊断。
+
+<!-- src: repos-pc/某库 适配实证（2026-09-16） -->
+
+---
+
+## 附录：app 域 fork+execv 子进程的 cwd 只读与 SysV/shm 断层（C++ testrunner 实证）
+
+HAP 内 NAPI 层 `fork()+execv()` 拉起私有 HNP 里的 CLI/testrunner 时，子进程继承的
+**cwd = HNP 安装目录（`/data/app/.../bin`），只读**。由此引出一整族「运行时文件失败」：
+
+| 症状 | 根因 | 解法 |
+|------|------|------|
+| SQLite `Can't open DB file: unable to open database file`、FileStream `ERROR` | testrunner 按相对路径 `test.db`/临时文件写 cwd，cwd 只读 | `kCases[].cwd` 加 `"sandbox"` 标记，exec 前复制数据文件（cppignore/pem/xml/data/）到**可写沙箱目录**再 `chdir` |
+| 启动即 SIGSYS 秒退（零输出） | SysV 信号量（`ftok`/`semget`/`semop`）在**静态全局构造**中被 seccomp 拦截 | 编译时切 Android 桩后端（`#if defined(__OHOS__)`），不能靠运行时 try-catch |
+| `SharedMemory(name,...)` worker 线程死锁 | `shm_open` 命名共享内存 + `mmap(MAP_SHARED)` 在 app 域 mount namespace 下挂起 | 换文件映射构造 `SharedMemory(File(path), mode)`（预创建文件后 open+mmap 普通文件） |
+| `rc=-2` 只知道被信号杀 | fork+execv 后 `waitpid` 只看 WIFEXITED | 补 `WIFSIGNALED/WTERMSIG/WCOREDUMP` 回传 hilog，直接锁定信号类型 |
+| 多线程测试退出 SIGSEGV | musl 上 Thread::interrupt/join 析构触发（特定测试） | `-ignore` 机制（cppignore.lnx）跳过崩溃点，让剩余测试完整跑完 |
+
+**关键原则**：
+1. **exec 子进程的 cwd 必须显式指向可写目录**——别假设继承的 cwd 可写。凡 testrunner 建
+   临时文件/数据库/锁文件，一律走 sandbox-cwd + 数据复制模式。
+2. **SysV IPC 静态构造秒退 = 编译期问题**，运行时任何 try-catch 都救不了——`__OHOS__`
+   条件编译切桩是唯一解。
+3. **信号捕获是 exec 调试的第一装备**：`waitpid` 后补 `WIFSIGNALED` 回传，`rc=-2` 就能
+   分解成「SIGSEGV 内存错 / SIGSYS seccomp / SIGALRM 看门狗」，省掉一整轮盲猜。
+
+---
+
+## 附录：hap 富用例异常与进程存活（worker 线程 terminate = SIGABRT）
+
+NAPI 壳的 worker 线程里跑富用例（dlopen/进程内直调库 API），**任何用例函数抛出的异常
+若不在分派层捕获，worker 线程 terminate → 整个进程 SIGABRT → 后续全部用例丢失**。
+实证：`RecordSet::value()` 越界抛 `Poco::RangeException`、`TextEncoding::byName()` 对
+未注册编码抛 `Poco::NotFoundException`，都会把进程杀死。
+
+解法（2026-09 实证，全套 35 条无崩溃跑完）：
+1. **分派层 try-catch 兜底**：`poco_hap_case()` 调用点包
+   `catch (const Poco::Exception&)` + `catch (const std::exception&)`，异常转 `not ok`
+   并记录 `HANGS: <异常文本>`——进程继续跑剩余用例。这是 cli-hnp-runner / cpp-lib-demo
+   骨架的**通用改进**，scaffold 生成物应自带。
+2. **富用例内部防御**：
+   - `RecordSet::value(row, col)` 取前先 `rowCount() > 0` 判空；
+   - 编码/能力类查找（`TextEncoding::byName` 等）先探测可用性，不可用记 `blocked`。
+3. **进程是否存活是可观测的**：hilog 里后续用例继续出 `TAP|` 行 = 异常被兜住了；
+   卡在 `CRASHED:` 后再无新行 = 进程没了，查 cppcrash。
+
+---
+
+## 附录：Windows 宿主抓设备日志的两个坑（UTF-16LE + cppcrash）
+
+1. **PowerShell 重定向 `hdc shell "hilog -x" > file.log` 产出 UTF-16LE**（带 BOM），
+   node/Python `readFileSync(utf8)` 读出来全是 `\u0000` 间杂——正则匹配直接失败（症状：
+   "extracted 0 lines" 但文件明明有内容）。修法：
+   - node：`buf.toString('utf16le')` 而不是 `'utf8'`；
+   - 或 PowerShell 用 `hdc shell "hilog -x | grep xxx" > file`（`| grep` 在设备端过滤，
+     输出经管道仍可能转码）——最稳的是**在设备端落文件再 `hdc file recv`**，
+     `hdc shell "hilog -x > /data/local/tmp/x.log"` 保持 UTF-8。
+   - 判据：`buf[0]===0xFF && buf[1]===0xFE` 即 UTF-16LE。
+2. **崩溃取证走 cppcrash**：app 进程崩溃后 AnalyticsKit 会记录
+   `cppcrash-<bundle>-<uid>-<时间戳>.log`（含信号名、`LastFatalMessage`、完整调用栈、
+   线程列表）。抓取：
+   ```bash
+   hdc file recv /data/log/faultlog/faultlogger/cppcrash-<name>.log .
+   ```
+   `LastFatalMessage` 一行就是崩溃根因的浓缩（如 `terminating due to uncaught
+   exception of type Poco::RangeException: Out of range`），比猜 hilog 高效得多。
+   与 platform-notes 的信号捕获补丁（WIFSIGNALED 回传）互为补充：一个看子进程、
+   一个看宿主进程。
+
+<!-- src: 某 C++ 框架库适配实证（2026-09），匿名化 -->