@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/platform//351/270/277/350/222/231PC-64KB/351/241/265/345/257/271/351/275/220so/345/264/251/346/272/203.md

@@ -0,0 +1,52 @@
+---
+name: 鸿蒙PC-64KB页对齐so崩溃
+description: 部分 64KB(0x10000)对齐 LOAD 段的 .so 在鸿蒙PC(4KB页)上 dlopen 裸 SIGSEGV，重链 max-page-size=0x1000 可修；但 64KB【不】必然崩（设备自带 .so 多数是 64KB 且正常），只能当嫌疑信号不能当判据
+metadata:
+  type: platform
+  source: new/PC
+---
+
+> 平台机制，与具体库无关。2026-06-26 从源码交叉编译整套 GTK 栈时定位到的**重磅坑**，解释了为什么 cmd-pkgs 一堆预编译 .so 在设备上一加载就崩。任何把第三方 .so 跑到鸿蒙 PC 的场景都可能踩。
+
+## 现象
+某些交叉编译出来的 `.so` 在设备上 **`dlopen`/被 NEEDED 加载时直接 `Signal 11 (core dumped)`**，没有任何错误信息（不是"symbol not found"，是纯段错误，发生在加载/重定位阶段、`main` 之前）。同一个 .so：
+- `file` 正常（ARM aarch64 shared object）
+- 单独 `dlopen` 就崩；静态链接进可执行文件却没事（所以问题在**动态加载**这条路）
+- 小而简单的 .so（trivial、freetype、libpng、libffi 的 4KB 版）能正常加载
+
+## 相关信号：LOAD 段 64KB 对齐 vs 设备 4KB 页
+设备是 **4KB 页**（`getconf PAGE_SIZE` = 4096）。OHOS lld 链接器**默认/有时**把某个 RW 或 RELRO 段按 **64KB(`p_align=0x10000`)** 对齐（Android/OHOS 为兼容 16KB/64KB 页设备的历史默认）。
+
+原始观察：崩的那批（cmd-pkgs 预编译的 pixman/fontconfig/fribidi/libepoxy/libffi(bare)，以及自己源码编的 pcre2、fontconfig）都是 64KB；不崩的（glib/cairo/gtk 同样源码编）是 4KB。**据此曾判定「64KB ⇒ 必崩」，但该判定已被证伪，见下。**
+
+> ### ⚠️ 更正（2026-07-16 实测于 root/可调试机，log build，HongMeng 6.1.0.117）
+>
+> **64KB 对齐【不】必然崩。** 该机 `getconf PAGE_SIZE`=4096，而设备自带 Python 栈的 **418 个 `.so` 里 345 个（占多数）就是 `p_align=0x10000`**，且 `numpy`（19/19 个 `.so` 全 64KB）、`numpy._core._multiarray_umath`、`ctypes`、`ssl`、`_decimal` **全部 import 正常**。若 64KB 对齐必崩，这台机的整个 Python 栈根本起不来。
+>
+> 所以原「一眼判定」是**小样本上的相关性**，不是因果：崩的恰好都 64KB，但 64KB 的绝大多数不崩。**真实成因未定论**（本次未复现出崩溃样本，无法定位），不要臆造新规则。
+>
+> **实践后果**：`p_align=0x10000` 只能当**嫌疑信号**，**绝不可当判据去拒绝一个库**——那会误杀 numpy 这类完全正常的库。`pc-device-verify` 的 `device_verify.py` 据此只在 import 前把 64KB 的 `.so` 记进日志留证（进程被 SIGSEGV 打死时日志已落盘，可据以缩小怀疑范围），**不拦截**。
+
+**怎么看对齐**（判嫌疑用，不判死）：
+```bash
+llvm-readelf -l libfoo.so | awk '/LOAD/{print $NF}' | sort -u | tail -1
+# 0x10000 → 嫌疑（但本机自带 .so 多数如此且正常）；0x1000 → 排除本项
+```
+注意 `llvm-readelf` **宿主机默认不在 PATH**（在 `$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin/`，见 `SKILL.md` 的「定位 DevEco SDK」），直接敲会 `command not found`；若再叠个 `2>/dev/null`，就会把「工具不存在」伪装成「没有匹配」的假阴性。设备侧 root 域同样没有它（工具链只挂在 app mount namespace）——所以 `device_verify.py` 改用纯 Python 解析 ELF program header，不依赖外部工具。
+
+## 修法：强制 4KB 对齐
+**链接时加 `-Wl,-z,max-page-size=0x1000`**，强制所有 LOAD 段 4KB 对齐。
+- meson cross-file：`[built-in options] c_link_args / cpp_link_args` 里追加 `'-Wl,-z,max-page-size=0x1000'`（全局生效，最省事）。
+- autotools：`LDFLAGS="-Wl,-z,max-page-size=0x1000"`（但 libtool 有时吞 flag，可能要直接 `clang -shared ... -Wl,-z,max-page-size=0x1000` 手动重链 .o）。
+- 验证：重编后 `readelf -l` 的 max align 变 `0x1000`，设备 `dlopen` 不再崩。
+
+**对纯预编译 .so（拿不到源码）**：`patchelf` 改不了 `p_align`，只能重编。但**别一见 64KB 就弃包**——先实际 `dlopen`/import 试；绝大多数 64KB 的库是好的（设备自带 numpy 全套即是），只有**确认崩了**才需从源码重编（带上面的 flag）或放弃。
+
+## 配套小坑（同次定位）
+- **bare-name NEEDED 的 64KB 库最隐蔽**：libgobject NEEDED `libffi.so`（裸名），设备上那个 `libffi.so` 恰好是 64KB 的，而同目录 `libffi.so.7.1.0` 是 4KB 好的——把 bare `libffi.so` 换成 4KB 的真文件即可。排查时**逐个 dlopen 每个依赖**定位是哪个库崩。
+- **patchelf 修 baked host 路径 NEEDED**：从源码编的库若链了无 SONAME 的依赖（如 cmd-pkgs 的 `libexpat.so`），会把**编译机绝对路径**写进 NEEDED（`/Users/.../libexpat.so`）。`patchelf --replace-needed <hostpath> libexpat.so.1 libfoo.so` + 给 expat `--set-soname` 修正。
+
+## 相关
+- [[鸿蒙PC-cmd-pkgs预编译GTK栈不可用]] —— 预编译 GTK 栈不可用的另一面（glib 静态烤进每个库）；本坑是它"即使绕过静态-glib 也还会崩"的下一层原因。
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— 另一类 .so 加载限制（标签/SELinux）。
+- [[鸿蒙PC-nmap-autotools交叉编译与真机扫描]] —— shim 目录修 host 工具（diff/ar）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-CLI/345/267/245/345/205/267main/345/207/275/346/225/260/345/271/263/345/217/260/350/203/275/345/212/233/346/243/200/346/237/245/351/231/215/347/272/247/346/250/241/345/274/217.md

@@ -0,0 +1,134 @@
+# 平台模式：CLI 工具 main() 函数平台能力检查降级模式
+
+## 问题
+
+许多 CLI 工具（C/C++ 编写的命令行工具）的 `main()` 函数第一条关键操作就是**检查某个平台能力**是否可用：
+
+```c
+main(int argc, char *argv[]) {
+    if (libusb_init(NULL)) {        // 检查 USB 能力
+        fprintf(stderr, "USB 不可用\n");
+        return 1;
+    }
+    // 只有在 USB 可用后才解析 CLI 参数
+    parse_opts(&argc, &argv);
+    ...
+}
+```
+
+当该平台能力在鸿蒙 PC 上**不可用或部分可用**时（如 HAP 应用域无 USB 设备访问权限、无 X11 显示服务器、无 ALSA 音频设备、无 /dev/dri 渲染节点等），工具在**第一条检查就退出了**，导致：
+- CLI 参数解析（`--help`、`--version`、设备标识格式校验等）无法测试
+- TCP 连接/监听等网络行为无法测试（即使这些功能不依赖该平台能力）
+- 后续的适配验证只能看到"工具退出码 1"，无法区分是平台能力缺失还是 CLI 参数错误
+
+## 核心模式：降级重构
+
+### 原则
+
+1. **CLI 参数解析先于平台能力检查**：把 `parse_opts()` 提到 `libusb_init()` / `XInitThreads()` / `SDL_Init()` 等平台能力检查之前
+2. **平台能力检查非致命化**：能力不可用时，工具降级运行而不是退出
+3. **能力依赖段用标志守卫**：所有依赖该能力的代码段用 `if (have_xxx)` 保护
+4. **回调函数 NULL 安全**：依赖能力数据的回调（IO 回调、事件回调）加 NULL 守卫
+
+### 改造模板
+
+```c
+main(int argc, char *argv[])
+{
+    GError *err = NULL;
+
+    /* 1. 先解析 CLI 参数 */
+    Options *opts = parse_opts(&argc, &argv);
+    if (!opts) {
+        return 1;  // 参数错误，退出
+    }
+
+    /* 2. 平台能力初始化——非致命 */
+    gboolean have_capability = FALSE;
+    if (platform_init(NULL) == 0) {
+        have_capability = TRUE;
+    } else {
+        g_warning("平台能力不可用，降级运行（TCP/CLI 功能仍可用）\n");
+    }
+
+    /* 3. 能力依赖段用标志守卫 */
+    if (have_capability) {
+        // 平台能力设置、回调注册、资源打开等
+        platform_set_log_cb(...);
+        resource_handle = open_resource(opts);
+        if (!resource_handle) {
+            goto cleanup;
+        }
+        // 能力依赖的工作线程
+        ...
+    }
+
+    /* 4. 不依赖能力的子功能照常执行 */
+    if (opts->is_client) {
+        // TCP 客户端连接
+        tcp_connect(opts->addr, opts->port);
+        if (have_capability) {
+            install_io_watch(self);  // 只有能力可用时才安装 IO 回调
+        }
+    } else {
+        // TCP 服务端监听
+        tcp_listen(opts->addr, opts->port);
+    }
+
+    /* 主循环 */
+    main_loop_run();
+
+cleanup:
+    if (have_capability) {
+        // 能力相关的清理
+        platform_exit();
+    }
+    // 通用清理
+    g_free(opts);
+    return 0;
+}
+```
+
+### 回调函数 NULL 守卫
+
+能力依赖的 IO 回调函数必须做 NULL 安全检查：
+
+```c
+gboolean io_callback(GIOChannel *source, GIOCondition condition, gpointer user_data) {
+    Context *self = (Context *) user_data;
+
+    /* 降级模式：无平台能力，不处理 IO 数据 */
+    if (!self->platform_resource) {
+        return G_SOURCE_CONTINUE;  // 或 G_SOURCE_REMOVE
+    }
+
+    // 正常的 IO 处理逻辑
+    platform_read_data(self->platform_resource, ...);
+    ...
+}
+```
+
+## 故障注入
+
+降级模式下，对端断开/端口不可达/格式错误等**失败路径**可以直接测试（工具不再因平台能力检查失败而提前退出）。成功路径（如 TCP 连接建立后持续运行）需在测试侧处理：
+- 测试 runner 用 `alarm(90)` 看门狗杀进程
+- 或测试侧主动发送 SIGTERM 后检查日志
+
+## 适用的平台能力（典型触发）
+
+| 能力检查 | 鸿蒙状态 | 典型工具 |
+|---------|---------|---------|
+| `libusb_init(NULL)` | partial（HAP 应用域不可达） | usbredirect、dfu-util、openocd |
+| `XOpenDisplay(NULL)` | unavailable（无 X11） | 命令行工具含 X11 检测 |
+| `SDL_Init(SDL_INIT_VIDEO)` | partial | SDL 命令行工具 |
+| `gst_init(NULL)` | partial | GStreamer 工具 |
+| `gtk_init(NULL)` | unavailable | GTK+ 工具 |
+| `alcOpenDevice(NULL)` | partial（OHAudio 后端） | OpenAL 工具 |
+| `pa_mainloop_new()` | unavailable（无 PulseAudio） | PulseAudio 工具 |
+
+## 注意事项
+
+1. **本模式是降级，不是完整功能**：平台能力不可用=降级，仅用于测试不依赖该能力的那部分 CLI 行为（参数解析、网络连接、格式校验、错误处理等）
+2. **补丁需独立打，不污染上游**：降级改造属于适配补丁，应打在 `patches/` 中，不提交到上游
+3. **降级模式日志**：在降级入口加 `g_warning` 日志，便于测试取证时区分"降级成功"与"正常崩溃"
+4. **成功路径日志**：在 TCP 连接成功/服务端监听成功等关键节点加 `g_message` 日志，让 hilog 取证可观测到"已连接"与"挂死"的区别

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-GNU-make-4.4.1/344/272/244/345/217/211/347/274/226/350/257/221/351/232/217/345/214/205.md

@@ -0,0 +1,102 @@
+# GNU make 4.4.1 鸿蒙 PC 交叉编译（随包 CLI 框架的 make 解释器）
+
+> 一句话：需要给鸿蒙 PC 的 CLI/框架**随包一个 GNU make**（HNP CLI 场景）时，走 autotools 交叉编译四条铁律——config.sub 换成 ohos 支持版（**可直接从 某交叉工具链工程 源码取**，比手打补丁省事）、**静态链接**（否则 musl 动态加载缺 libc++_shared.so 全家桶）、链接期 `-Wl,--code-sign` 自签（否则设备 exec 报 Permission denied/avc denied）、`make -jN` 遇 ld.lld 并行崩溃降 `-j1` 续编不重来。产物 `dist/bin/make` 在设备上退出码正确，可作框架的 make 解释器。
+
+## 适用场景（先判这个）
+
+| 场景 | 是否本文档 |
+|---|---|
+| 鸿蒙 PC 上跑 CLI 框架，其脚本链要调 `make`（如 ct-ng 的 `ct-ng build` 解释器、构建系统随包） | ✅ 本文档（HNP 随包） |
+| 宿主交叉编译**别的 autotools 库**时 `make` 只是构建工具 | 不需要——构建机用原生 make（见 `鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译.md`） |
+| 宿主连 make 都没有（纯 makefile 工程） | `鸿蒙PC-宿主无GNU-make的确定性构建驱动.md`（Python 驱动路线，不编 make 本身） |
+
+## 配方（五步，端到端实证 2026-09，某交叉工具链工程 随包场景）
+
+### 0) 编译器 wrapper（E143：NDK 封装脚本 Program Files 空格断裂）
+
+Windows 宿主 DevEco 装在 `C:\Program Files\...`，NDK 官方 `aarch64-unknown-linux-ohos-clang` 封装脚本
+`exec $SOURCE/clang` 未加引号 → configure 报 `C compiler cannot create executables`（config.log 里
+`/c/Program: No such file or directory`）。自建无空格路径的引号封装（详见 `pc-error-atlas` E143）：
+
+```bash
+# build/toolchain/aarch64-linux-ohos-clang
+NDK="$DEVECO_SDK_HOME/default/openharmony/native"
+exec "$NDK/llvm/bin/clang" -target aarch64-unknown-linux-ohos --sysroot="$NDK/sysroot" -D__MUSL__ "$@"
+```
+
+AR/RANLIB/STRIP 同样用 wrapper 指 `$NDK/llvm/bin/llvm-ar|llvm-ranlib|llvm-strip`。
+
+### 1) config.sub 替换（E007 的增量做法：从 某交叉工具链工程 源码取）
+
+`./configure --host=aarch64-unknown-linux-ohos` 时 GNU make 4.4.1 自带 config.sub 不识别 ohos 三元组
+（报 `cannot guess build type` / `Invalid configuration`）。**标准做法**是给 config.guess/config.sub 打
+`__OHOS__` 分支补丁（见 E007）；**省事做法**：`某交叉工具链工程` 源码树自带的 config.sub 已支持
+`linux-ohos*-`（它自己就是交叉编译工具链项目，目标覆盖 OHOS），直接拷来替换 make 的同名文件：
+
+```bash
+cp <某交叉工具链工程-src>/config.sub deps/make-4.x/make-4.4.1/config.sub
+cp <某交叉工具链工程-src>/config.sub deps/make-4.x/make-4.4.1/build-aux/config.sub
+# 验证：grep -c 'linux-ohos' config.sub  # ≥ 1
+```
+
+> ⚠️ config.sub 有两处都要改到位：内核-OS 组合列表（`linux-uclibc*- | linux-ohos*-`）与基本 OS 类型
+> 列表（`case $os in ... ohos*`），某交叉工具链工程 版两者都齐（make 4.4.1 实证单替换即可过 configure）。
+
+### 2) configure（static + 关闭不需要的特性）
+
+```bash
+./configure \
+  --host=aarch64-unknown-linux-ohos --build=x86_64-pc-linux-gnu \
+  --prefix=/usr --disable-nls --without-guile --without-gettext \
+  CC=$WRAP/aarch64-linux-ohos-clang \
+  AR=$WRAP/aarch64-linux-ohos-ar RANLIB=$WRAP/aarch64-linux-ohos-ranlib \
+  CFLAGS='-O2 -D__MUSL__' \
+  LDFLAGS='-static -Wl,--code-sign -Wl,-z,max-page-size=0x1000'
+```
+
+**为什么 static**：设备上没有 `libc++_shared.so` 这类动态依赖可加载（动态链接 make 在 HNP 外找
+libc++ 全家桶，`Error loading shared library`），静态链接一了百了——同时绕开 musl 动态链接器
+RUNPATH `$ORIGIN` 的坑。
+
+**为什么 `--code-sign`**：app 域 exec 强制 ELF 代码签名，未签名二进制 `execv` 报 Permission
+denied / avc denied；链接期自签（`-Wl,--code-sign`）是最省事的签法，post-link 后**不要 strip**
+（会破坏签名段）。
+
+**为什么 `max-page-size=0x1000`**：NDK 默认 64KB 页对齐的 LOAD 段 .so/.elf 在 4KB 页设备上
+dlopen/exec 直接 SIGSEGV（见 `鸿蒙PC-64KB页对齐so崩溃.md`）。
+
+### 3) make 编译（ld.lld 并行崩溃 → 续编）
+
+```bash
+make -j4 2>&1 | tee build/make.log
+```
+
+Windows 宿主上 `make -jN` 偶发 `ld.lld` 并行链接崩溃（0xC0000005，NDK 链接器缺陷）——**降 `-j1`
+续编即可，不要清掉已编对象重来**（四坑文档实证：续编能编完）。`-j1` 慢但稳。
+
+### 4) install 与验证
+
+```bash
+make install DESTDIR=$DIST
+# 产物 $DIST/bin/make —— ELF 检查：
+file $DIST/bin/make    # ELF 64-bit ... ARM aarch64
+llvm-readelf -S $DIST/bin/make | grep -i codesign   # 签名段在位
+```
+
+打包期随 HNP 部署到 `bin/`（HNP 布局契约见 `pc-knowledge-base`）。设备侧验证：`execv` 调用
+make 解释器跑一个真实 makefile，退出码正确即算数（ct-ng 实证：`dist/bin/make` 设备退出码正确，
+可作框架 make 解释器；`/bin/sh` 设备有、bash 用 HNP 内 bash 绝对路径）。
+
+## 反例锚点
+
+- **错**：不打 config.sub 补丁 → configure 死（E007）；或打了但只改内核列表漏 OS 列表 → `OS ohos not recognized`。
+- **错**：动态链接 + 不随 libc++_shared → 设备 `Error loading shared library`。
+- **错**：编完 strip / 不带 `--code-sign` → 设备 exec `Permission denied`（与"权限"无关，是签名）。
+- **错**：`make -jN` 崩溃后清树重编 → 白费一轮；`-j1` 续编即过。
+
+## 关联
+
+- `pc-error-atlas` E007（config.sub ohos 补丁标准做法）/ E143（NDK 封装脚本空格断裂，本文配方 0）
+- `pc-capability-domains/references/capability-domains/subprocess-exec.md` —— shell 密集型 CLI 全家桶私有 HNP 三位随包方案（make 是第 3 层「自编译关键工具」的典型）
+- `鸿蒙PC-Windows宿主构建环境四坑.md` —— ld.lld 并行崩溃续编、pkg-config 模拟器等宿主坑
+- `鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译.md` —— 同是 autotools 交叉编译，但那是「库」路线（直链绕 libtool），本文是「make 解释器本身随包」路线

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-HAP/350/260/203/350/257/225/347/255/276/345/220/215/344/270/216/350/256/276/345/244/207/345/256/211/350/243/205/344/277/241/344/273/273/351/223/276.md

@@ -0,0 +1,86 @@
+---
+name: 鸿蒙PC-HAP调试签名与设备安装信任链
+description: HAP 装机签名（bm/hdc install 校验 PKCS7 profile 信任链）与二进制/ELF 签名是两套机制。首选路线：用 SDK 自带 OpenHarmony 默认材料 headless 自签（ohpt-agent sign-demo，零账号、任意 bundle——设备信任根含 OpenHarmony Application Root CA，真机实测通过），账号自动签名/模拟器为兜底。自签「野 CA」必被拒，症状 code:9568257 fail to verify pkcs7 file
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：HAP 调试签名与设备安装信任链
+
+## 适用与结论先行
+
+**读我的时机**：交付需要在设备上**安装并拉起一个 HAP**（`delivery_form=app`；或 `cpp-lib`/`native-extension` 命中 GUI 面能力域 `graphical-window`/`gl-context`/`ui`——其目标能力只有装 demo HAP 上屏才能验）。
+
+两条铁律，先记住：
+
+1. **HAP 安装签名 ≠ 二进制/ELF `.codesign` 签名**——两套机制、两个工具、两个校验方、两种失败面。历史文档里「免签名」「放宽签名」的说法讲的是 `.so`/可执行文件，**不是 `bm install` 的 HAP**；而鸿蒙 PC 上两者都要签。
+2. **别造自签「野 CA」，用 SDK 的 OpenHarmony CA 材料**——`hap-sign-tool generate-ca` 造的新根不链任何受信根，必被拒（`9568257`，GLFW 案例空耗两轮的死路）。正解：`ohpt-agent sign-demo -w <ws> --install`——它用 SDK 自带 `OpenHarmony.p12` 里的 CA 私钥本地签发，链到设备信任的 `OpenHarmony Application Root CA`，**零账号、零一次性设置、任意 bundleName**（真机实测通过）。也别试图关设备签名强制（`param set …install_no_sign` 在 user/release 版不生效）。
+
+## 两套签名机制对比
+
+| 维度 | 二进制/ELF 签名 | **HAP 安装签名** |
+|---|---|---|
+| 对象 | 可执行文件 / `.so` | 整个 `.hap` 应用包 |
+| 工具 | `binary-sign-tool -selfSign 1` | `hap-sign-tool.jar`（`ohpt-agent sign-demo` 封装）/ DevEco 自动签名 |
+| 校验方 | 内核代码签名 / JVM `System.load`（E083） | **BundleManager 装机时校验 PKCS7 profile 信任链** |
+| 自签可用? | **可**（DevBox 自签即用，见 E077/E083） | **野 CA 不可**（不链受信根，必拒）；**用 SDK OpenHarmony CA 材料签可**（链到设备信任的 OpenHarmony 根） |
+| 与 shell uid 关系 | root 域可绕 | **无关**——root shell 装 HAP 一样校验 |
+| 失败症状 | `Permission denied` / `Operation not permitted` | **`code:9568257 error: fail to verify pkcs7 file`** |
+| 权威文档 | 本 skill「签名（看设备策略）」节 / E077 / E083 | 本文 / E120 |
+
+## 为什么 root 也拦不住、自签必败
+
+- `hdc install`（→ `bm install`）在 **user/release 版**一律校验 HAP 的 PKCS7 profile 证书链是否链到设备信任根，**与 `hdc shell id` 是不是 root 无关**（实测：`uid=0(root) su` 的可调试机，装自签 HAP 仍报 `9568257`）。
+- 自签 CA 不在设备 `/system/etc/security/trusted_root_ca.json`，而 `/system` 是**只读 erofs**，无法注入根证书。
+- `param set persist.bm.install_no_sign true` / `const.bms.install_no_sign true` **只在 eng/userdebug 版生效**；零售/user 版设置不生效（GLFW 案例实测无效）。
+
+## 判定：本轮是否需要可信 HAP 安装签名（与 gate/env 同源）
+
+`requiresInstallSigning` = `delivery_form=app` **或** `capability_domains ∩ {graphical-window, gl-context, ui} ≠ ∅`。
+
+- 显式**不需要**：`cli`/`pure-runtime`；纯输入库（evdev/uitest）；baseline 的 Null-smoke 裸二进制（**不装 HAP**，故不涉 PKCS7；但 ELF 本身仍要 `-Wl,--code-sign`，且鸿蒙 PC 上要经私有 HNP 执行器跑——`/data/local/tmp` 不可执行）。
+- 需要时：`ohpt-agent env` 的 `signing` 能力若 `found=false`，gate 会前置 `ask`（见「与流水线接口」）。
+
+## 签名路线表（首选 S1，其余兜底）
+
+| 路线 | 何时用 | 怎么做 | `signing.route` |
+|---|---|---|---|
+| **S1 OpenHarmony 默认材料自签（首选、零账号、任意 bundle）** | 装了 DevEco/SDK + 连了鸿蒙 PC 设备（设备信任根含 `OpenHarmony Application Root CA`——标配） | **`ohpt-agent sign-demo -w <ws> --install`**（下「S1 机制」是其手工等价） | `ohos-default-material` |
+| **S2 DevEco 账号自动签名** | 设备**不认** OpenHarmony 根，或要上架/受限权限 | DevEco 开 Automatic Signing（账号云签发 Huawei 根 profile，落 `~/.ohos/config`），接入 signingConfigs | `deveco-auto-sign` |
+| **S0 无材料** | 连 SDK 都没有 | 不要自签野 CA——如实降级 `built-pending-verification`（**非 built-and-verified**），`remaining_blockers` 写「缺签名材料」 | `none` |
+
+### S1 机制（`ohpt-agent sign-demo` 自动做，手工等价供理解；真机实测通过）
+
+**关键事实**：鸿蒙 PC 设备 `/system/etc/security/trusted_root_ca.json` 含 `OpenHarmony Application Root CA`；SDK 自带 `$DEVECO_SDK_HOME/default/openharmony/toolchains/lib/{OpenHarmony.p12（内含 App/Profile/Root CA 私钥）, OpenHarmonyProfileDebug.pem, UnsgnedDebugProfileTemplate.json, hap-sign-tool.jar}`。用这套 CA 材料本地签发 → 链到受信根 → 装机通过。**无需华为账号、无需 DevEco GUI、无需固定/匹配 bundle**——DevEco 账号签名只为上架/权限，调试装机不需要。
+
+手工等价（`ohpt-agent sign-demo` 走的就是这套流程）：
+1. 从 `OpenHarmonyProfileDebug.pem` 拆 Root CA(cert0)+App CA(cert1)。
+2. `hap-sign-tool generate-app-cert`（`-issuerKeyAlias "openharmony application ca"`，口令 `123456`）→ 真 app 证书链。
+3. 填 `UnsgnedDebugProfileTemplate.json`：`bundle-name`=demo bundle、`device-ids`=[`hdc shell bm get --udid`]、`development-certificate`=上步 app 叶证书、放宽 `validity`。
+4. `sign-profile`（`-keyAlias "openharmony application profile debug"`）→ profile.p7b。
+5. `sign-app`（`-keyAlias "openharmony application release"` + app 链 + profile）→ 签名 HAP → `hdc install`。
+
+## 可复用证据
+
+- 症状串：`fail to install bundle. code:9568257 error: fail to verify pkcs7 file`（＝签名链不达受信根，多因自签野 CA）；`code:9568329 error: verify signature failed`（＝zip 重复条目 或 profile 证书不匹配，见 E164）。
+- 材料位置：`$DEVECO_SDK_HOME/default/openharmony/toolchains/lib/`；p12 公知口令 `123456`；关键 keyAlias：`openharmony application ca`（签发）/`openharmony application profile debug`（签 profile）/`openharmony application release`（签 app）。
+- 设备信任根查看：`hdc shell cat /system/etc/security/trusted_root_ca.json | grep OpenHarmony`。
+- **9568329 诊断**：先跑 `python -c "import zipfile,collections;print([n for n,c in collections.Counter(zipfile.ZipFile(r'<hap>').namelist()).items() if c>1])"` 排除重条目；再用 `hap-sign-tool.jar verify-app` 查看 `certificate #0 Subject`——Debug profile 下必须为 `CN=<App Name>`（Debug 证书），若为 `CN=OpenHarmony Application Release`（Release 证书）则 profile 内嵌证书与签名证书不匹配。
+
+## 与流水线接口
+
+- **`ohpt-agent env`** 探 `signing` 能力 = **SDK OpenHarmony 材料是否在位**（`found`），写 `00-env.json`。
+- **`ohpt-agent sign-demo -w <ws> [--install]`**：确定性完成 S1 全流程（定位材料+取 udid+签发+签 profile+签 app+可选装机）。模型只需：构建 demo（hvigor 出 `*-unsigned.hap`）→ `ohpt-agent sign-demo`。**测试线/子目录 demo 必须带 `--demo-dir test-demo`**（bundleName 从该目录的 app.json5 推断，漏传回退读 harmony-demo → profile bundle 不匹配 → 9568329，见反模式第 6 条）；签名前守卫会比对 `--hap` 里 module.json 的 bundleName 与推断值，不一致直接拒绝并给修法（cximage 2026-09-20 实测加入）。
+- **`ohpt-agent gate`**：`requiresInstallSigning` 且 `signing` 缺失（≈只有连 SDK 都没有时）→ 软 `ask`。探测规则与 `pc-knowledge-base/SKILL.md`「环境能力探测判定程序」双呈现。
+- **状态语义**：签名+装机+上屏通过 → `built-and-verified`；材料缺失、demo HAP 已产出但没装机 → `built-pending-verification`（**非 partial**，无真实回归时）。
+
+## 反模式（GLFW 案例血泪）
+
+- ✗ `hap-sign-tool generate-ca` 造**自签野 CA**去签装机——不链任何受信根，必拒（`9568257`）。**根因就是这个**：要用 SDK 里 OpenHarmony 的 CA 私钥签发，别造新根。
+- ✗ 满世界找"匹配 demo 自身 bundleName 的 profile"——S1 任意 bundle 都能签，不需要匹配。
+- ✗ `param set …install_no_sign` 关设备签名强制——user/release 版不生效；翻 `/system/.../trusted_root_ca.json` 注根——erofs 只读。
+- ✗ 给 baseline 的 Null-smoke 裸二进制签 HAP——那不装 HAP（ELF 另走 `-Wl,--code-sign`）。
+- ✗ **用 DevEco 自动签名/其他链的 Release 证书签 Debug-profile 的 HAP**——profile 内嵌证书与签名证书不匹配，`verify-app` 看似 Verify success，装机仍报 `9568329`（libaribcaption 实证）。Debug profile 必须配 Debug 证书（S1 签出的 `CN=<App Name>` 叶证书），统一走 `sign_hap_s1.ps1` / `ohpt-agent sign-demo`。
+- ✗ **给 test-demo/子目录 demo 签名时漏传 `--demo-dir`**——bundleName 回退读 harmony-demo 的 app.json5，profile bundle-name 与 HAP 实际 bundle 不符，装机报 `9568329`（cximage 2026-09-20 实证，详见 platform/鸿蒙PC-ohpt-sign-demo必须传demo-dir参数.md 与 E172）。CLI 现在签名前比对 `--hap` 的 module.json bundleName 与推断值，不一致即拒签并提示补 `--demo-dir`。
+- ✓ 直接 `ohpt-agent sign-demo -w <ws> --install`。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-HNP/344/272/214/350/277/233/345/210/266SELinux-exec/351/231/220/345/210/266.md

@@ -0,0 +1,42 @@
+---
+name: 鸿蒙PC-HNP二进制SELinux-exec限制
+description: HNP 包内二进制带 `hnp_file:s0` 标签，app 域子进程经 `/bin/sh` 再 exec 会被 hmmac 拒（dmesg 无 avc）；物理 `cp` 到 data_local_tmp 标签目录才能 exec，软链无效
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：HNP 二进制的 SELinux/MAC exec 限制（`hnp_file` 标签）
+
+> 这是与具体应用无关的平台机制：任何 HNP 包内的二进制，想被 app 域进程 **fork 出的子进程**（典型是经 `/bin/sh -c` 再 exec）拉起，都会撞上这条限制。从 opencode 的 rg `Permission denied`（见 [[鸿蒙PC-opencode-rg-exec-denied]]）里抽取沉淀。
+
+## 现象
+app 域进程通过 `/bin/sh` 去 exec 一个 HNP 包里的二进制，报：
+```
+/bin/sh: /data/service/hnp/<pkg>.org/<pkg>_<ver>/bin/<tool>: Permission denied
+```
+而该 binary 实际是 `-rwxr-xr-x root:root`（DAC 权限没问题），`ls -Z` 显示标签 `u:object_r:hnp_file:s0`。
+**dmesg 里看不到 avc denied**——`hmmac` 走的是 OHOS 私有 hook，不打标准 SELinux audit，所以排查时不要指望 `dmesg | grep avc`。
+
+## 根因
+- `/data/service/hnp` 挂载本身**没有 noexec**（`rw,nosuid,nodev,noatime`），问题不在挂载选项。
+- HNP 包内文件的 MAC 标签 `hnp_file:s0` 对 app 域**只允许"宿主进程入口直接 exec"**（例如 opencode 自身 `node opencode.mjs` 就是这条路径起来的，能跑），但**不允许 app 域子进程再经 `/bin/sh` 去 exec 别的 `hnp_file`**。
+- 物理路径 `/data/app/el1/bundle/<userId>/hnppublic/<pkg>.org/...` 与 app NS 视图 `/data/service/hnp/<pkg>.org/...` 是同一份文件的不同视图（见 [[鸿蒙PC-HNP包与PATH]]、[[鸿蒙PC-进程视角与mount-namespace]]），**SELinux 标签也是同一个**，所以这条 exec 限制**不分视图，从哪条路径 exec 都 deny**。
+
+## 通用修复套路
+把二进制**物理拷贝**（不是软链）到 `data_local_tmp` 标签的目录，app 域对它明确允许 exec：
+```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：属系统级 HNP 文件，需 root 且升级会被覆盖，普通用户做不了。
+
+## 另一面：私有 HNP（随 HAP 分发）则可直接 exec
+
+本条讲的是**公共 HNP**（`hnp_file:s0`，HiShell/命令行装的）。如果是 HAP 应用自带的**私有 HNP**（`module.json5` 声明 `hnpPackages` type=private，装到 `/data/app`，标签 `private_hnp_file:s0`），app 域**可直接 `execve`**（不必经 /bin/sh、不必 cp）。把可执行二进制塞进 HAP 内分发，私有 HNP 是唯一正路，详见 [[鸿蒙PC-app域执行二进制与JIT限制]]。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-HNP/345/214/205/344/270/216PATH.md

@@ -0,0 +1,47 @@
+---
+name: 鸿蒙PC-HNP包与PATH
+description: HNP 包安装位置、应用与 hdc shell 的 PATH 差异、调用 HNP 工具的方法
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：HNP（Harmony Native Package）与 PATH
+
+## 包安装位置
+所有 HNP 公共包安装在：
+```
+/data/app/el1/bundle/<userId>/hnppublic/<pkg>.org/<pkg>_<version>/
+```
+其中 `<pkg>.org` 是包目录、`<pkg>_<ver>` 是版本目录，内部一般是 `bin/`、`share/`、`lib/` 等标准结构。
+
+观察到的常见包：
+`node.org`、`git.org`、`opencode.org`、`python.org`、`ruby.org`、`perl.org`、
+`cmake.org`、`ninja.org`、`make.org`、`gawk.org`、`grep.org`、`neovim.org`、
+`bash.org`、`busybox.org`、`gdb.org`、`binutils.org`、`ohos-sdk.org`、`hdc.org` 等。
+
+## 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 各包可执行文件的统一汇总（softlink 风格），但**只在应用 mount namespace 里挂出**。所以：
+- hdc shell 默认 `which git` 找不到。
+- HNP 应用进程 PATH 里有 `git`、`node` 等命令。
+
+## 调用 HNP 工具的两种方法
+1. **绝对路径**（在 hdc shell root 下可用）：
+   ```bash
+   /data/app/el1/bundle/<userId>/hnppublic/git.org/git_2.45.2/bin/git --version
+   ```
+2. **进入应用 namespace 后用 PATH**（模拟应用真实运行环境）：
+   ```bash
+   nsenter -t <pid> -m -- /data/service/hnp/bin/git ...
+   ```
+
+## 排查思路
+1. `ls /data/app/el1/bundle/<userId>/hnppublic/` 看哪些包已装。
+2. `ls /data/app/el1/bundle/<userId>/hnppublic/<pkg>.org/<pkg>_<ver>/bin/` 看包提供的具体命令。
+3. 应用进程 PATH 看 `/proc/<pid>/environ`，确认是否真的能找到工具。
+4. 如果应用是 HNP 安装的，`/proc/<pid>/cmdline` 一般指向 `/data/service/hnp/<pkg>.org/<pkg>_<ver>/...`。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-HNP/346/211/247/350/241/214/345/231/250cwd/344/270/215/345/217/257/345/206/231/344/270/216/346/262/231/347/256/261/345/206/231/345/205/245/346/226/271/346/241/210.md

@@ -0,0 +1,71 @@
+---
+name: 鸿蒙PC-HNP执行器cwd不可写与沙箱写入方案
+description: app 域 HNP pkg/bin/ 目录在 mount namespace 限制下只读——C/C++ 程序在当前 cwd 写文件（fopen("wb")）返回 EACCES 或 CL_INVALID_VALUE。解决方案：cli-hnp-runner 执行器在 exec 用例前将 cwd 路由至沙箱可写目录（g_tmp_dir = /data/storage/el2/base/temp/），通过 napi_stub.cpp 的用例表 cwd 字段实现按需路由。触发词：cwd 不可写、HNP 写入限制、app 域 fopen 失败、沙箱写入、g_tmp_dir、TMPDIR、/data/storage/el2/base/temp、fopen wb EACCES、CL_INVALID_VALUE 写入、binaries cwd。
+metadata:
+  type: platform
+  source: OpenCL-SDK 2026.05.29 (binaries C版 cwd修复实证, HAD-W32, OpenHarmony 6.1.1.135)
+  relates_to: E131
+---
+
+# 鸿蒙 PC：HNP 执行器 cwd 不可写与沙箱写入方案
+
+> app 域 HNP pkg/bin/ 目录是只读的（mount namespace 限制），任何 fopen("wb") 在当前 cwd
+> 写文件的尝试都会失败。必须在 fork+execv 前将 cwd 改为沙箱可写目录。
+
+## 一、问题
+
+OpenCL-SDK 的 binaries(C) 用例调用 `cl_util_write_binaries`：
+```c
+fopen_s("wb", filename)  // 在 HNP pkg/bin/ 下写 .bin 文件
+```
+返回 `CL_INVALID_VALUE`（rc=226），原因是 cwd 在 `HNP pkg/bin/`（app 域只读）。
+
+C++ 版 binariescpp 反而通过——因为 OpenCL-CLHPP 的 C++ wrapper 内部实现走 `fstream` 而非 `fopen`，文件写入行为不同。
+
+## 二、修复方案
+
+在 cli-hnp-runner 的 `napi_stub.cpp` 中，用例表增加 `cwd` 字段：
+
+```cpp
+// napi_stub.cpp — 用例表
+struct Case { const char* name; int (*fn)(int,char**); const char* cwd; };
+Case kCases[] = {
+  // 不需要写文件的用例：保持默认 cwd（HNP pkg/bin/，只读但可读）
+  {"enumopencl", run_enumopencl, nullptr},
+  // 需要写文件的用例：cwd 路由至沙箱可写目录
+  {"binaries",   run_binaries,   "writable"},
+  {"binariescpp", run_binariescpp, "writable"},
+  // ...
+};
+```
+
+执行逻辑：
+```cpp
+// child_pre_exec 阶段
+if (c->cwd && strcmp(c->cwd, "writable") == 0) {
+    const char* tmpdir = getenv("TMPDIR");
+    if (!tmpdir) tmpdir = "/data/storage/el2/base/temp/";
+    chdir(tmpdir);  // 切换 cwd 到沙箱可写目录
+}
+```
+
+round3+round4 两轮稳定 PASS，hilog 确认 `Binary file written.` + `Saved program found` + Collatz 完整计算。
+
+## 三、app 域可写路径
+
+| 路径 | 说明 | 可用性 |
+|------|------|--------|
+| `/data/storage/el2/base/temp/` | aa 自动分配的沙箱临时目录 | available（推荐） |
+| `getenv("TMPDIR")` | 若存在则指向可写临时目录 | available |
+| `/data/storage/el2/base/haps/<bundleName>/cache/` | HAP 沙箱缓存目录 | available |
+| HNP pkg/bin/ | 运行时 cwd 默认值 | **只读**（fopen("wb") = EACCES） |
+| `/data/local/tmp/` | shell 域目录 | **不可写**（app 域无权限） |
+
+## 四、适用范围
+
+任何通过 HNP 执行的 cpp-lib/cli 在 app 域需要写文件的用例：
+1. 需要 fopen/write 输出结果文件的库（如程序二进制持久化、日志写出、缓存生成）
+2. 需要 mkstemp/tmpfile 的库（可参考 `鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址.md`）
+3. 测试框架要求写临时文件的用例
+
+Runner 侧在 fork+execv 前的 `child_pre_exec` 阶段按需 chdir 至沙箱可写目录，不影响只读的用例（保持默认 cwd）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-HNP/346/225/260/346/215/256/350/265/204/346/272/220/346/226/207/344/273/266/346/211/223/345/214/205EXTRA_DATA.md

@@ -0,0 +1,45 @@
+---
+name: 鸿蒙PC-HNP数据资源文件打包EXTRA_DATA
+description: 携带数据文件（kernel 源码、模型权重、配置文件等）的 cpp-lib/cli 交付物打包 HNP 时，必须通过 EXTRA_DATA 或 HNP zip 布局将数据文件与 ELF 一同打入 pkg/bin/ 目录——HNP zip 包中 pkg/ 目录是运行时 cwd，资源文件不打包则 ELF 在 app 域找不到文件（表现为文件打开失败、CL_INVALID_VALUE 等）。触发词：EXTRA_DATA、HNP 数据文件、.cl kernel、数据资源打包、run-time 资源不可达、HNP pkg/bin 数据、clCreateProgramWithSource NULL、cannot read、数据随包、运行时 cwd。
+metadata:
+  type: platform
+  source: OpenCL-SDK 2026.05.29 (cli-hnp-runner, 9条GPU样本因EXTRA_DATA为空全部失败实证)
+  relates_to: E131
+---
+
+# 鸿蒙 PC：HNP 数据资源文件打包
+
+> 只要交叉编译产物运行时需读取外部数据文件（kernel 源码、模型权重、配置文件、字典文件），
+> 这些文件就必须**与 ELF 一起打入 HNP 包**，否则 app 域进程找不到它们。
+
+## 一、问题现象
+
+9 条 GPU samples 在 HNP 第二轮前全部失败：
+- C++ 变体报 `cannot read saxpy.cl`
+- C 变体报 `CL_INVALID_VALUE`（`clCreateProgramWithSource(NULL)`）
+
+根因：`build-hap.sh` 的 `EXTRA_DATA` 数组为空——`.cl` kernel 文件（saxpy.cl, reduce.cl, histogram.cl 等）未打入 HNP zip 包。
+
+## 二、修复方式
+
+将 `dist/bin/` 下的 `.cl` 文件复制到 `harmony-cli-runner/dist/hnp/pkg/bin/` 后重打包 HNP：
+
+```bash
+# dist/bin/ 下是交叉编译产物（ELF + .cl 数据文件）
+cp dist/bin/*.cl harmony-cli-runner/dist/hnp/pkg/bin/
+# 然后重新 zip 打包 HNP
+cd harmony-cli-runner/dist/hnp && zip -r ../../hnp/pkg.zip pkg/
+```
+
+修复后第二轮 6 条转 PASS（3 条因 cwd 不可写仍有其他平台问题）。
+
+## 三、原理
+
+HNP zip 包中的 `pkg/` 目录是 app 域运行时进程的初始 cwd。ELF 通过相对路径（如 `"saxpy.cl"`）加载数据文件时，实际在 `pkg/bin/` 下查找。未打包则文件不存在，所有读文件调用失败。
+
+## 四、适用范围
+
+任何携带数据文件的 cpp-lib/cli 交付物打包 HNP 时：
+1. 确保 EXTRA_DATA 或 HNP zip 布局包含 `pkg/bin/` 下的所有运行时所需数据文件
+2. 自查：`unzip -l <hnp-package>.hnp | grep -c "\.cl$"`（或其他扩展名）验证文件已入包
+3. 不走 `EXTRA_DATA` 而直接修改 HNP zip 时，注意 zip 内的 Unix 权限位与目录条目（见 `鸿蒙PC-私有HNP打包与exec平台差异.md`）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-NAPI-so/346/211/213/345/212/250/344/272/244/345/217/211/347/274/226/350/257/221/345/277/205/351/241/273/351/223/276/346/216/245ace_napi/344/270/216hilog_ndk.md

@@ -0,0 +1,41 @@
+---
+name: NAPI-so手动交叉编译必须链接ace_napi与hilog_ndk
+description: 用 NDK clang++ 手动编译 HarmonyOS NAPI 模块 .so 时，必须显式链接 -lace_napi.z -lhilog_ndk.z（必要时 -lc++_shared），否则 .so 虽然编译通过但 HAP 安装后 app 启动卡死（NAPI 模块注册/加载失败且无崩溃日志，进程 0% CPU 睡眠）。编译输出还须 -Wl,-z,max-page-size=0x1000。
+metadata:
+  type: platform
+  source_lib: openocd
+  source_commit: bedefa238476ad852b1fafd927230e38e2092282
+  proposed_at: 2026-09-15T15:58:00.000Z
+---
+
+## 现象
+
+用 NDK clang++ 手动编译 napi_stub.cpp 生成 libxxx_demo.so，编译器不报错、产物 .so 也生成，但替换进 HAP 后安装成功、app 启动后完全无输出（连 NAPI 模块的构造函数日志都没有），进程处于 S（睡眠）态 0% CPU。逐条跑用例也毫无反应。
+
+## 根因
+
+编译命令缺少 NAPI 运行时库链接。NAPI 模块注册（napi_module_register）、属性定义、hilog 打印等符号都来自系统 .z 库：
+
+- -lace_napi.z — NAPI（Node-API for HarmonyOS）核心运行时
+- -lhilog_ndk.z — hilog 打印（OH_LOG_Print 等）
+- -lc++_shared — C++ 运行时（std::string/vector 等）
+
+缺少这些链接时 .so 的未定义符号延迟绑定，dlopen 阶段不报错，但 app 侧无法正确完成模块注册，表现为「装上了但什么都不跑」。
+
+## 修复
+
+编译命令补齐链接参数：
+
+`
+clang++ -std=c++17 -O2 -fPIC -shared \
+  -I<entry>/src/main/cpp -I/llvm/include -I/sysroot/usr/include \
+  -L/llvm/lib -L/sysroot/usr/lib/aarch64-linux-ohos \
+  napi_stub.cpp -o libxxx_demo.so \
+  -lc++_shared -lhilog_ndk.z -lace_napi.z \
+  -Wl,-z,max-page-size=0x1000
+`
+
+## 检出条件
+
+- 手动（非 hvigor）交叉编译 NAPI 模块 .so
+- 症状是 HAP 装了、app 能启动、但 NAPI 功能完全没有反应且无日志