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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-POSIX-NDK/350/203/275/345/212/233/346/216/242/351/222/210/347/237/251/351/230/265.md

@@ -0,0 +1,59 @@
+---
+name: 鸿蒙PC-POSIX-NDK能力探针矩阵
+description: 一个综合 C++ 探针 root 域实测 46 项 POSIX/NDK 能力（45 OK / 仅 robust mutex 缺）：fork/mmap-RWX/shm/sem/AF_UNIX/PTY/getrandom/dlopen/epoll/inotify/信号/文件锁全 OK；判底层接口能不能用，不必逐库重测。口径=root/NDK 层，app 域另有 SELinux/seccomp/XPM 限制
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：POSIX / NDK 能力探针矩阵（root 域实测）
+
+> 平台机制，与具体库无关：一个综合 C++ 探针（`aarch64-unknown-linux-ohos-clang++ -std=c++17`）交叉编译后推真机跑一遍（**当年经 hdc shell 直跑；鸿蒙 PC 上 `/data/local/tmp` 不可执行，要复跑请打进私有 HNP 由执行器 HAP 跑**），一次性核实 OHOS NDK / musl / 内核对 46 项 POSIX/NDK 能力的支持。root/可调试机，HarmonyOS **HongMeng Kernel 1.12.0**，aarch64，4KB 页。结果 **45 OK / 1 MISSING / 0 FAIL**。用于判"某库需要的底层 POSIX 接口在鸿蒙能不能用"，不必逐库重测。
+
+## 口径（关键）
+
+探针在 **root 域**跑，测的是 **NDK/内核层是否具备该能力**。**app 域（HAP 沙箱）另有 SELinux/seccomp/XPM 限制**（见 [[鸿蒙PC-app域执行二进制与JIT限制]]）——root 能用 ≠ app 能用。下面凡标 ⚠app 的，root 实测 OK 但 app 域受限。
+
+## 能力矩阵（root 实测）
+
+| 能力 | 结果 | 备注 / app 域 |
+|---|---|---|
+| fork + exec(`/bin/sh`) / setsid / posix_spawn | ✅OK | ⚠app：exec 仅私有 HNP（见 [[鸿蒙PC-HNP二进制SELinux-exec限制]]） |
+| mmap(RWX) / mprotect→EXEC / madvise / mlock | ✅OK | **1.12.0 放开 W^X**（root）；⚠app：非系统进程仍不能 JIT（mprotect EXEC EINVAL） |
+| shm_open + mmap(MAP_SHARED) | ✅OK | POSIX 共享内存；app 域 /dev/shm 可写 |
+| pthread 进程共享互斥锁(PTHREAD_PROCESS_SHARED) | ✅OK | |
+| **pthread robust mutex** (`pthread_mutexattr_setrobust`) | ❌**MISSING** | musl 子集唯一缺项 |
+| sem_open / sem_close / sem_unlink | ✅OK | 命名信号量；**⚠app：实测失败**（`sem_open() failed`，namefs MAC，Poco NamedEvent/NamedMutex 实证，见 [[鸿蒙PC-app域命名POSIX信号量受限]]） |
+| thread_local / __thread | ✅OK | |
+| **pthread_cancel** 符号 | ✅OK（存在） | **纠正旧记录**：旧 musl 缺，**1.12.0 符号存在**（dlsym 命中） |
+| **pthread_attr_setaffinity_np** 符号 | ✅OK（存在） | **纠正旧记录**：同上 |
+| AF_UNIX bind(pathname)+listen | ✅OK | ⚠app：bind SELinux EPERM→TCP 回退（见 errors/E024） |
+| **AF_UNIX 抽象命名空间**(\0 前缀) | ✅OK | **纠正 KB「无证据」**：root 实测通 |
+| **SCM_RIGHTS fd 传递**(sendmsg/recvmsg) | ✅OK | **纠正 KB「无证据」**：root 实测通 |
+| AF_INET socket/bind/listen | ✅OK | ⚠app：raw socket 需系统权限 |
+| termios / posix_openpt / **openpty / forkpty** | ✅OK | PTY 完整（node-pty 佐证）；⚠纯 TUI 无 HAP 窗口交付形态 |
+| getrandom / getentropy | ✅OK | 1.12.0 已补 getrandom（errors/E014） |
+| dlopen / dlsym / dlclose | ✅OK | ctypes.util.find_library 需补丁（无 ldconfig，E068） |
+| epoll_create1 / timerfd_create / eventfd / signalfd / memfd_create | ✅OK | ⚠app：io_uring 被 seccomp 杀→回落 epoll |
+| /proc/self/mem / /proc/self/maps 读 | ✅OK | ⚠app：/proc 部分 SELinux 受限；跨进程 ptrace 未证 |
+| sigaction / sigaltstack / sigprocmask / SIGWINCH | ✅OK | |
+| 文件 I/O：open/read/write / fdatasync / fcntl(F_SETLK) / flock / link / symlink | ✅OK | |
+| inotify_init1 / inotify_add_watch | ✅OK | FSEvents/ReadDirectoryChanges 等价 |
+| statx 符号（birthtime 可查） | ✅OK（存在） | musl 头不给 struct，dlsym 命中 |
+| C++17 std::filesystem | ✅OK | libc++；NDK clang 支持 C++11/14/17 |
+
+## 复现
+
+- 探针源码/产物见分析仓 scratchpad（`probe.cpp`）；构建 `aarch64-unknown-linux-ohos-clang++ -std=c++17 probe.cpp -o probe -ldl -lpthread -Wl,-z,max-page-size=0x1000`（**页对齐必带**，否则 dlopen 崩，见 [[鸿蒙PC-64KB页对齐so崩溃]]）。
+- 推送 `hdc file send probe /data/local/tmp/probe`，跑 `hdc shell "/data/local/tmp/probe"`（root 域 /data/local/tmp **可执行**，无需 Documents 兜底）。
+- maybe-missing 符号一律 `dlsym(RTLD_DEFAULT,...)` 探测，避免链接失败。
+
+## 结论要点
+
+1. **OHOS NDK/musl 的 POSIX 覆盖在 root 域近乎完整**——45/46，仅 robust mutex 缺。绝大多数纯 POSIX C/C++ 库的底层接口担忧（socket/线程/共享内存/信号量/PTY/inotify/dlopen/mmap/信号/文件锁）**在 NDK 层都成立**。
+2. **纠正三处旧认知**：pthread_cancel/affinity 符号 1.12.0 存在；AF_UNIX 抽象套接字、SCM_RIGHTS fd 传递 root 域可用。
+3. **真正的门槛在 app 域**（SELinux/seccomp/XPM）与**无对应实现**（robust mutex、raw socket 权限、跨进程 ptrace、JIT），不在 NDK 基础 POSIX。
+
+> ⚠️ **app 域实测修正（Poco 1.15.3 实证）**：`sem_open`（命名信号量）在本表标 root OK，
+> 但 app 域实测失败（`/dev/shm` namefs MAC 拦），Poco NamedEvent/NamedMutex 因此 static-init 崩溃。
+> 判 app 域能不能用命名信号量，看 [[鸿蒙PC-app域命名POSIX信号量受限]]，别拿本表 root 结果推断。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-Vulkan/344/270/212/345/261/217/351/200/232/350/267/257.md

@@ -0,0 +1,43 @@
+---
+name: 鸿蒙PC-Vulkan上屏通路
+description: GPU 渲染 API 在鸿蒙 PC 的上屏通路机制：surface（窗口域出 OHNativeWindow）→ swapchain→present（系统 swapchain layer + 驱动 ICD 承接）。dlopen 与链接互斥（符号冲突）、系统内部接口应用不调、验证载体只有真窗口表面算数、app 域 present/fence 同步路径同源风险。触发词：Vulkan、swapchain、交换链、present、vkCreateSurfaceOHOS、VK_OHOS_surface、VK_LAYER_OHOS_surface、Gralloc、上屏黑屏、渲染通路、GPU 渲染栈、surface、呈现。
+metadata:
+  type: platform
+  source: new/PC
+---
+
+> 平台机制，语言无关。讲的是"GPU 显式渲染栈在鸿蒙 PC 怎么把帧送上屏"的**通路结构**——谁负责哪一步、依赖哪些系统侧组件、验证时什么算数什么不算。与具体 GPU API 无关（Vulkan 是当前唯一在册实例；其他同类 API 命中时按同构映射）。窗口 surface 的获取与判定见 `pc-capability-domains` 的 `graphical-window.md`（窗口域只到 surface 为止）；GPU 驱动发现/装载规则见 `gpu-compute.md`。
+
+## 通路结构（谁负责哪一步）
+
+上屏链路 = 三段，各归各的组件，任何一段缺失都表现为"编得出、跑得起、黑屏"：
+
+| 段 | 职责 | 承接方 |
+|---|---|---|
+| ① surface | 在窗口表面建立渲染 API 的对接点 | 窗口域：XComponent/OWB 出 OHNativeWindow → API 的平台 surface 扩展（Vulkan 为 `vkCreateSurfaceOHOS`，须启用 `VK_KHR_surface`+`VK_OHOS_surface`） |
+| ② swapchain | 交换链创建/取图/acquire | API 标准扩展（KHR 系列）；**实际实现由系统 swapchain layer + 驱动 ICD 提供**，加载器/分派链须能发现并激活 |
+| ③ present | 提交队列呈现上屏 | 同上——系统 swapchain layer + 驱动 ICD |
+
+**关键认知**：②③不是应用代码能独占的——设备上由**系统 swapchain layer（如 `VK_LAYER_OHOS_surface`）+ 厂商驱动 ICD** 承接。自交付"驱动加载器"形态产物的库，端到端上屏成功 = 它能否发现并激活系统 layer + 真 ICD 清单（发现规则见 `gpu-compute.md` 设备发现子面）。
+
+## 通用规则
+
+1. **dlopen 与链接互斥**：官方 Surface 指导明确——*"通过 dlopen 函数链接 libvulkan.so 时不需要在 CMake 中增加依赖，否则会导致符号冲突"*。消费方要么 dlopen、要么链，不兼得。产物名为 `libvulkan.so` 的加载器尤其要守：宿主壳只 dlopen；.so 进 HAP libs 遵循宿主壳共享链禁令（`pc-capability-domains/references/capability-domains/gl-rendering/00-overview.md`）。
+2. **系统内部接口应用不调**：gralloc/图像 acquire/release 类接口（Vulkan 侧为 `vkGetSwapchainGrallocUsageOHOS`/`vkAcquireImageOHOS`/`vkQueueSignalReleaseImageOHOS`，API 23 起废弃）是系统内部组件（swapchain layer/驱动）之间的通路，"应用开发者无需使用"；适配的库若调用它们，视为越层依赖，按不可用面处理而非重实现。
+3. **验证载体只有真窗口表面算数**：XComponent SURFACE → OHNativeWindow → 平台 surface 扩展 → swapchain/present 这条链证「画到屏幕」；`surfaceless+FBO` 离屏逐像素断言通过 ≠ 上屏能力。载体优先级与逐像素取证纪律见 `pc-capability-domains/references/capability-domains/gl-rendering/04-verification-pitfalls.md`；设备侧归因三分类见 `pc-device-verify`。
+4. **app 域同步路径同源风险**：厂商 ICD 在 app 域创建驱动内事件/同步对象可能受限（OpenCL 实证：cqEvent 创建失败 → `CL_OUT_OF_HOST_MEMORY`，见 `gpu-compute.md`）。present/fence 类路径命中同源风险时，先以最小探针（建 surface → 建 swapchain → acquire/present 一帧）验证通路，再决定归因；避免"名册全绿但上屏未验"的假验收。
+5. **surface 入参契约**：平台 surface 创建接口的窗口指针为空必须返回错误码而非崩溃（Vulkan 侧 `VkSurfaceCreateInfoOHOS.window` 判空）；`flags=0`、`pNext=nullptr` 按官方约定传。
+
+## 排障入口（黑屏/呈现失败时的差分顺序）
+
+1. GL_RENDERER/API 版本打点确认渲染栈在哪套（Mesa/Zink vs 闭源栈，切换与探测见 `gl-rendering/01-route-gles-vs-gl4es.md`「OHOS PC 镜像自带双 GL/EGL 栈」）。
+2. surface 段：扩展是否启用、窗口指针是否非空、surface 创建返回码。
+3. swapchain/present 段：系统 layer + ICD 是否被分派链发现（加载器日志）；app 域同步路径是否受限（规则 4 探针）。
+4. 载体：换真窗口表面 HAP 重验（规则 3），离屏证据不作数。
+
+## 相关
+
+- `pc-capability-domains/graphical-window.md` — surface 一步的窗口域职责与触发特征
+- `pc-capability-domains/gpu-compute.md` — GPU 设备发现与驱动通路（环境变量注入/SYSCONFDIR/app 域事件限制）
+- `gl-rendering/00-overview.md` — 宿主壳共享链禁令；`gl-rendering/01-route-gles-vs-gl4es.md` — 双 GL/EGL 栈（Mesa 栈 = libvulkan→Zink→Maleoon）
+- `pc-device-verify` — 设备侧取证与三分类归因

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-aarch64/346/214/207/344/273/244/346/241/243/344/275/215/344/270/216/350/277/220/350/241/214/346/227/266/345/210/206/345/217/221.md

@@ -0,0 +1,77 @@
+# 鸿蒙 PC aarch64 指令档位与运行时分发
+
+> **一句话**：给 OHOS aarch64 交叉编译选 `-march`，安全基线是 `armv8-a+crypto+crc`；更高的档位
+> （v8.2+ 的 sha3/sm4、LSE、SVE…）**只能**经 `getauxval(AT_HWCAP/AT_HWCAP2)` 运行时分发使用——
+> 编死在全局 `-march` 会在低档设备上直接 SIGILL（非法指令），验证阶段整批用例崩。
+
+## 为什么这是个必答题
+
+- 鸿蒙 PC 设备全是 aarch64，但**基线不统一**：老设备 v8.0、主流 v8.2（HAD-W32 实测 Kirin 级）、
+  新设备更高。产物要跨设备分发就不能假设高端特性人人都有。
+- 带 SIMD/crypto/crc 加速的库（压缩、哈希、加密、媒体编解码、数学库）收益就在这些指令上——
+  全用基线档等于自废武功，全用高档档等于只能在少数设备跑。**解法只有一个：编译期分档 + 运行时分发。**
+- `-mcpu=native` 在交叉编译里是错的（编的是宿主 x86 的特性）；`-mcpu=<具体 SoC>` 会把产物绑死在
+  一种设备上，分发场景禁用。
+
+## 档位表（实测口径，2026-09）
+
+| 档位 | 写法 | 依据 | 适用 |
+|---|---|---|---|
+| **安全基线** | `-march=armv8-a+crypto+crc` | v8.0 mandatory AES/PMULL/SHA1/SHA2/CRC32 扩展；所有鸿蒙 PC 均支持 | 全局编译默认值 |
+| v8.1 | `armv8-a+crc+crypto+lse` | LSE 原子指令 | 仅运行时分发 |
+| v8.2 | `armv8.2-a+crypto+crc`（+sha3/sm4 可选） | HAD-W32 实测支持 | 仅运行时分发 |
+| 更高 | `+sve` / `+sve2` / `+i8mm` | 设备差异大，须逐特性探测 | 仅运行时分发 |
+
+配套安全选项：`-mbranch-protection`（BTI/PAC）在 OHOS 加载器上**默认不启用也不要求**——加上
+未经验证可能加载失败，没有明确需要就别动。
+
+## 运行时分发怎么做
+
+musl 提供 `getauxval()`（`<sys/auxv.h>`），与 glibc 同名同义：
+
+```c
+#include <sys/auxv.h>
+unsigned long hw = getauxval(AT_HWCAP);   // v8.0 特性
+unsigned long hw2 = getauxval(AT_HWCAP2); // v8.1+ 特性
+
+bool has_crc32 = hw & HWCAP_CRC32;
+bool has_aes   = hw & HWCAP_AES;
+bool has_sha2  = hw & HWCAP_SHA2;
+bool has_lse   = hw2 & HWCAP2_ATOMICS;    // v8.1 LSE
+```
+
+分发模式（编译期把不同档位的实现编成**多个函数**，运行时挑一个）：
+
+```cmake
+# 每个档位一个编译单元 + 各自的 -march，基础版不带扩展
+set_source_files_properties(crc32_base.c PROPERTIES COMPILE_OPTIONS "-march=armv8-a")
+set_source_files_properties(crc32_armv8.c PROPERTIES COMPILE_OPTIONS "-march=armv8-a+crc")
+# 入口函数按 getauxval 结果路由（或用 GCC IFUNC / clang target attribute 内联切换）
+```
+
+clang 还支持**函数级**目标特性，单文件混编多档位：`__attribute__((target("crc")))`。
+
+## 诊断路径：设备上 SIGILL / Illegal instruction
+
+1. `hdc shell "hilog -x | grep -i sigill"`（或 crash 日志）确认指令地址；
+2. 反汇编产物看崩在哪条指令（`llvm-objdump -d` 查该地址），是 `crc32x`/`aes*`/`ldadd` 等扩展指令
+   → 就是 march 选高了；
+3. 修法按上表退到基线档或改运行时分发，**不是**把设备换个遍去试。
+
+## 实证案例
+
+- **7zip 26.02**（HAD-W32 真机）：上游 `var_clang_arm64.mak` 提供多档 march 预设（且存在多行
+  覆盖陷阱，最终取值可能为空）；实际取 `-march=armv8-a+crypto+crc` + 上游自带
+  `getauxval(AT_HWCAP)` 运行时分发，323 编译单元（含 ARM64 LZMA 汇编 `LzmaDecOpt.S`），
+  加密归档/哈希标准向量/基准用例真机全过（39/39 名册）。
+- OpenBLAS 案例另有 `OPENBLAS_CORETYPE` 环境变量档位旁路（见 adaptation/numpy-OpenBLAS 案例），
+  同属「特性档位交给运行时」的同型解法。
+
+## 给适配 agent 的判定程序
+
+1. 库不含 SIMD/crypto 热路径 → 直接基线档，完事。
+2. 含 → 查上游是否已自带档位分发（搜 `getauxval` / `AT_HWCAP` / `__builtin_cpu_supports`）：
+   - 已带（如 7zip）：全局 march 取**基线档**让分发兜底，别把分发逻辑编译期焊死；
+   - 不带：先问 PRD 是否真需要加速（多数库基线档性能已够）；确需加速才自己加分发，
+     改动走 patches/。
+3. 选定后必须**真机验证加速路径真的被走到**（跑 crypto/哈希/基准类用例，而不是只测纯 C 路径）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-app/345/237/237/345/221/275/345/220/215POSIX/344/277/241/345/217/267/351/207/217/345/217/227/351/231/220.md

@@ -0,0 +1,54 @@
+---
+name: 鸿蒙PC-app域命名POSIX信号量受限
+description: 鸿蒙 PC app 域（HAP 沙箱）里命名 POSIX 信号量（sem_open）虽在 root/NDK 层探针「OK」，实际 app 域会失败——root 能用 ≠ app 能用。Poco 1.15.3 实证：NamedEvent/NamedMutex 的 file-scope static 在 static-init 期调 sem_open 抛 SystemException 未捕获、进程在 main() 前 terminate。核心教训：static-init 期调可能失败的系统调用 = 定时炸弹。触发词：sem_open、命名信号量、POSIX 信号量、NamedEvent、NamedMutex、static-init 崩溃、main 前崩溃、static 对象构造崩溃、SystemException、namefs、/dev/shm。
+metadata:
+  type: platform
+  source: new/PC + Poco 1.15.3 设备验证（2026-09）
+---
+
+# 鸿蒙 PC：app 域命名 POSIX 信号量受限
+
+> 本文是 [[鸿蒙PC-POSIX-NDK能力探针矩阵]] 的**口径修正**：那边在 **root 域**实测
+> `sem_open` ✅OK，但 **app 域实测并非如此**——Poco 1.15.3 真机验证里 `NamedEvent`/`NamedMutex`
+> 因 `sem_open` 失败而在进程 `main()` 之前崩溃。结论：**root 能用 ≠ app 能用**，判 app 域能不能用，
+> 以 app 域实测为准。
+
+## 为什么 root 探针会误判
+
+鸿蒙 PC 的 `/dev/shm` 带 **namefs MAC**（`mount` 可见 `tmpfs on /dev/shm ... hmmac=namefs:shmfs,seclabel`）：
+命名 POSIX 信号量（`sem_open`）落在 `/dev/shm` 的 namefs 命名空间里，app 域对该 MAC 标签不可访问；
+app 沙箱另有自己的 `shm` 挂载（`/mnt/sandbox/shm`，`hmmac=use_task`）。root 域直通 `/dev/shm`，
+所以探针全绿；app 域被 namefs MAC 拦，`sem_open` 返回失败。
+
+> 注意与 `shm_open`（共享内存对象）区分：Poco 实测里 `shm_open` 的用例（`SharedMemory::testCreate`）
+> 并未失败，只有 `testCreateFromFile` 因测试数据路径（`findDataFile` 找 `data/` 子目录）报错——即
+> 共享内存对象在 app 域可用，**命名信号量才是受限的那个**。二者别混。
+
+## 现象（Poco 实证）
+
+1. `static NamedEvent testEvent("TestEvent")` / `static NamedMutex testMutex("TestMutex")` 这类
+   file-scope 静态对象，构造器里 `sem_open("/tmp/<name>.event", O_CREAT, ...)`（Poco `getFileName()`
+   返回 `/tmp/` 前缀，那是 POSIX 信号量名约定、要求以 `/` 开头，不真是 /tmp 文件）。
+2. app 域 `sem_open` 返 `SEM_FAILED` → 构造器 `throw SystemException("cannot create named event ... (sem_open() failed)")`。
+3. 因为它们是在**静态初始化期**（`main()` 之前）构造，异常未捕获 → 进程直接
+   `libc++abi: terminating due to uncaught exception of type Poco::SystemException`。
+   连 `CppUnitMain` 里装的 `std::set_terminate` 都来不及生效（main 还没进）。
+
+## 处置
+
+1. **命名信号量/IPC 测试判豁免**（platform-exclusive-api），evidence 指向 `sem_open` 失败。
+2. **static 对象改 Meyers 单例**（函数局部 static）延迟到首次使用——异常从「进程崩溃」转成
+   「可被测试框架捕获的用例错误」，再配合 `-ignore` 或 `#ifdef` 跳过注册。
+
+## 通用教训（比「sem_open 受限」更值钱）
+
+**file-scope static 对象在静态初始化期调用可能失败的系统调用**（命名信号量/共享内存/网络/文件 IO）
+= 定时炸弹：失败即未捕获 terminate，且 `set_terminate` 装不上（main 没进）。任何 C/C++ 测试或库里
+有 `static Foo foo(...)` 且 `Foo` 构造器可能抛异常，都要先改成懒构造。
+
+## 相关条目
+
+- [鸿蒙PC-POSIX-NDK能力探针矩阵.md](鸿蒙PC-POSIX-NDK能力探针矩阵.md) — 本文修正其 sem_open 的 app 域口径
+- [鸿蒙PC-app域测试前置条件矩阵.md](鸿蒙PC-app域测试前置条件矩阵.md) — AF_UNIX/socketpair、/tmp 等其余前置
+- [鸿蒙PC-app域执行二进制与JIT限制.md](鸿蒙PC-app域执行二进制与JIT限制.md) — seccomp/XPM 关卡（fork+exec、JIT、semget）
+- [鸿蒙PC-Poco-C++类库交叉编译与设备验证.md](../adaptation/鸿蒙PC-Poco-C++类库交叉编译与设备验证.md) — Poco 实证案例

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-app/345/237/237/346/211/247/350/241/214/344/272/214/350/277/233/345/210/266/344/270/216JIT/351/231/220/345/210/266.md

@@ -0,0 +1,152 @@
+---
+name: 鸿蒙PC-app域执行二进制与JIT限制
+description: HAP 应用想在 app 域 spawn 自带 ELF（node/python/任意 CLI）要连过四关：只有「私有 HNP」能 exec、io_uring 被 seccomp SIGSYS 秒杀（LD_PRELOAD 回落 epoll）、V8 JIT 写不了可执行内存（--jitless 解）、close_range(syscall 436) 批量 fd 操作被 seccomp 拦（SIGSYS）。另有 SIGINT 优雅退出失效（继承 SIG_IGN + blocked 信号掩码 + 工具侧 foreground gate 三关：runner 侧 child_pre_exec 重置处置+清空掩码 + 产品侧 __OHOS__ patch 去 gate，pty 造终端实测无效）。触发词：child_pre_exec、信号掩码、sigprocmask、blocked set、信号重置、SIGINT、SIGTERM、信号不递送、fork+execv、子进程、SIG_IGN、优雅退出、escalated to SIGKILL、app 域、seccomp、SIGSYS、syscall 436、close_range、closefrom、批量关闭 fd、io_uring、LD_PRELOAD、JIT、jitless、XPM、W^X、可执行内存、exec、私有 HNP、hnpPackages、控制终端、tcgetpgrp、pty、posix_openpt、tcsetpgrp、SIGKILL、sigkey_handler、sig_handler、alarm 看门狗失效、alarm 到点不杀、信号 pending 不递送、E178。
+metadata:
+  type: platform
+  source: new/PC + libbsd 0.12.2 外部一致性测试（close_range 关卡，2026-08）；openocd 0.12.0+dev（SIGINT 关卡，2026-09）
+---
+
+# 鸿蒙 PC：app 域里 fork/exec 二进制 + 跑 V8/JIT 的四道关
+
+> 平台机制，与具体库无关：任何 HAP 应用想在自己的 app 域进程里 **spawn 一个自带的 ELF 子进程**（node / python / 任意 CLI），都要连过这些关。从把 stock Node.js 24 塞进 OH-Electron HAP 跑 opencode sidecar 时抽取（见 [[鸿蒙PC-opencode-HAP化-Electron壳]]）。app 域比 hdc shell(su 域) / HiShell 域严得多——同一个二进制在 HiShell 里跑得好好的，搬进 app 域全踩。
+
+## 关卡①：HAP 里的二进制放哪才允许 exec —— 只有「私有 HNP」
+
+app 域进程能 `execve` 的文件，标签必须是 app 域 policy 放行的。实测在 HarmonyOS PC 6.1：
+
+| 放置方式 | 落地后属性 | app 域能 exec？ |
+|---|---|---|
+| `entry/libs/arm64-v8a/` 里的普通文件 | `installs:installs 0644`，标签 `data_app_el1_file`，**应用无法 chmod +x** | ❌ EACCES |
+| 拷到 el2 应用数据目录 `files/bin/` 再 chmod 755 | `0755`，标签 `debug_hap_data_file` | ❌ EACCES（hmmac deny，DAC 没问题也不行） |
+| `/data/local/tmp/...` | —— | ❌ app 域连 `mkdir` 都 EACCES（那是 su 域的地盘） |
+| **私有 HNP 包**（`module.json5` 声明 `hnpPackages` type=private） | 装到 `/data/app/<pkg>.org/<pkg>_<ver>/bin/`，标签 `private_hnp_file`，app NS 里还有 `/data/app/bin/` 符号链接农场 | ✅ **可直接 exec** |
+
+所以「想在 HAP 内分发可执行二进制」**唯一**正路是打成私有 HNP。做法：
+1. `hnpcli pack -i <dir> -o <out>` 把 `bin/ lib/ hnp.json` 打成 `.hnp`（`hnpcli` 在 SDK `toolchains/` 下；`hnp.json` 形如 `{"type":"hnp-config","name":"ocnode","version":"1.0","install":{}}`）。
+2. `module.json5` 的 `module` 段加 `"hnpPackages":[{"package":"ocnode.hnp","type":"private"}]`。
+3. `.hnp` 要进 HAP 包的 `hnp/arm64-v8a/` 目录。**注意**：DevEco 6.x 的 hvigor 没有自动收 `.hnp` 的内建逻辑（schema 认 `hnpPackages` 但打包阶段不收文件），需要自定义 hvigor task 在 `PackingCheck` 之后、`SignHap` 之前把 `hnp/` 塞进 unsigned HAP（`zip` 拼接），见 adaptation 笔记的 `injectHnp` 写法。
+4. 装上后 app 进程里 `HNP_PRIVATE_HOME=/data/app`，`/data/app/bin/<tool>` 是符号链接，`fs.realpathSync` 解到 `/data/app/<pkg>.org/<pkg>_<ver>/bin/<tool>`。
+
+> **2026-06-26 nmap 再确认（纯 ArkUI HAP，非 Electron）**：私有 HNP 里放 **C/C++ ELF**（nmap，musl，NEEDED 仅 libc++_shared+libc），app 域原生模块直接 `fork()`+`execv()`（不经 /bin/sh、不经 Node）**可成功 exec**，子进程 stdout 用 pipe 收回、`waitpid` 拿 exit=0。app NS 里 `/data/app/bin/nmap` 是符号链接，`realpath()` 解到 `/data/app/nmapcli.org/nmapcli_1.0/bin/nmap`（版本钉死路径），数据目录取同级 `../share/nmap`。hdc su 域看到的是另一条路径 `/data/app/el1/bundle/<userId>/hnp/<bundle>/nmapcli.org/...`（mount ns 差异）。injectHnp 的 hvigor task（PackingCheck 后、SignHap 前 `zip -r hap hnp/`）对纯 ArkUI HAP 同样有效，签名覆盖注入的 hnp。
+
+> 这跟 [[鸿蒙PC-HNP二进制SELinux-exec限制]] 是一体两面：那条讲的是**公共 HNP** 二进制（`hnp_file:s0`）被 app 域子进程经 `/bin/sh` exec 时被拒、要 cp 到 `data_local_tmp`；本条讲的是**私有 HNP**（`private_hnp_file:s0`）随 HAP 安装、app 域可直接 exec。两个标签待遇不同。另外公共 HNP node（`/data/service/hnp/node.org/.../bin/node`）在 app 域里**直接 spawn（不经 /bin/sh）也能 exec**，可做兜底。
+
+## 关卡②：io_uring 被 seccomp KILL —— LD_PRELOAD 改 syscall
+
+app 域 seccomp 对 `io_uring_setup/enter/register`（aarch64 syscall **425/426/427**）的处置是 **SIGSYS 直接杀进程**（`Reason:Signal:SIGSYS(SYS_SECCOMP) syscall number is 425`，faultlog 里能看到）。OHOS 的 Node.js 24 构建**无条件**调 io_uring，且 `UV_USE_IO_URING=0` 环境变量在这个构建里**不被尊重**——所以 node 一启动就被杀。
+
+修复：LD_PRELOAD 一个 shim，拦截 musl 导出的 `syscall()`，对这三个号直接 `errno=ENOSYS; return -1`。libuv 见 ENOSYS 会优雅回落到 epoll。要点：
+- node 二进制把 `syscall` 当 **UND 动态符号**导入（`readelf --dyn-syms` 可见），所以 LD_PRELOAD 符号插桩能命中；其余 syscall 用 `dlsym(RTLD_NEXT,"syscall")` 透传。
+- 用 OHOS NDK clang `--target=aarch64-linux-ohos --sysroot=<ndk>/sysroot -shared -fPIC` 编 `.so`，**放进私有 HNP 的 `lib/`** 一起分发（普通 libs 目录的 .so app 域 dlopen 也受标签限制，私有 HNP 最稳）。
+- spawn 时 `env.LD_PRELOAD` 指到 `realpath(node)/../../lib/<shim>.so`（注意 `/data/app/bin/node` 是符号链接，先 `realpathSync` 再算相对路径，否则路径算错、shim 没加载、依旧被杀）。
+
+## 关卡③：JIT 写不了可执行内存 —— `node --jitless`
+
+io_uring 过了之后，V8 初始化堆时 `mprotect(addr, ~256MB, PROT_READ|WRITE|EXEC)` 被 app 域 XPM/W^X 拒，`errno=22(EINVAL)`，V8 断言 `Check failed: 12 == errno`（它只接受 ENOMEM）于是 SIGTRAP abort。app 沙箱**不允许 spawn 出来的普通进程建可执行内存**（系统自带的 ArkWeb/Electron 的 V8 走的是另一条 JITFORT 授权路径，三方 spawn 的 node 拿不到）。
+
+修复：`node --jitless`，V8 只跑 Ignition 解释器、不建可执行页。代价是纯解释执行、性能下降，但能在 app 沙箱里正常跑（对 opencode 这种 IO/网络为主的负载够用）。副作用：**WebAssembly 不可用**（jitless 没 wasm），opencode 里 web-tree-sitter 本来就 stub 了，正好不冲突；若库强依赖 wasm 则此路不通。
+
+> ⚠️ **子进程不继承 `--jitless`**（pc-web-tool 22 条名册用例真机实证）：`node --jitless --test …` 跑测试时，`node --test` 会 spawn 测试子进程，而**子进程不继承主进程的 argv**，`--jitless` 标志在子进程里丢失 → 子进程仍触发 JIT 崩溃（症状是「已加 `--jitless` 却仍 `Check failed` SIGTRAP abort」）。修法是**逐文件直接 exec** `node --jitless --test-reporter=tap <file>`——每个测试文件独立进程、argv 自带 `--jitless`；任何 `spawn`/`fork` 派生的 Node 子进程同理都要在子进程 argv 里显式带上该标志，别指望继承。
+
+## 关卡④：close_range（syscall 436）等批量 fd 操作被 seccomp 拦 —— SIGSYS
+
+app 域进程内调用 `close_range`（aarch64 syscall **436**）会被 seccomp 拦截 → `Signal:SIGSYS(SYS_SECCOMP) syscall number is 436` 直接杀进程。一切「批量关闭文件描述符」的 API 都可能踩中：BSD 系的 `closefrom`（内部 fast-path 用 close_range）、直接用 `close_range` 的并发/事件循环库。
+
+与 io_uring 关卡同构——**处置不是绕测试，是走三级回退决策树**（完整程序见 `pc-device-verify/references/failure-triage.md` 的「fast-path + fallback」节）：
+
+1. 上游代码呈 fast-path + fallback 结构（如 closefrom: close_range → /proc/self/fd 遍历 → sysconf 逐个 close）→ **优先 patch 宏选择强制走 fallback**，产物在 app 域获得全功能；
+2. 运行时开关能关掉 fast-path（如 `UV_USE_IO_URING`）→ 设变量；
+3. 都没有 → LD_PRELOAD 拦 `syscall()` 对受限号返 `ENOSYS`（io_uring 关卡的 shim 写法直接复用）。
+
+> **黑名单是开放集**：已实测确认的 app 域受限 syscall 至少有 io_uring（425/426/427）、close_range(436)、semget(190，见下) 。**遇 SIGSYS 一律从 faultlog 查 syscall 号再下结论**，不要对照既有清单判定「不在名单里所以不是 seccomp」——名单随系统版本演进。
+
+## 关卡⑤：SysV IPC（semget 190）被 seccomp 拦 —— 命名 IPC 类库用 Android 桩
+
+app 沙箱 seccomp 拦截 `semget`（aarch64 syscall **190**，SIGSYS 杀进程）。基于 SysV 信号量的 POSIX
+命名事件/命名互斥量（`NamedEvent`/`NamedMutex` 类 API），其 testsuite 里**文件级静态对象在 `main` 前就构造**，一旦触发直接杀死进程
+且**零输出**（连 terminate 行都没有，最隐蔽）。诊断套路：
+
+```c
+// 思路：区分「静态初始化前/后死」+ 定位到具体 syscall 号
+__attribute__((constructor)) static void sentinel() { write(2, "PRE_MAIN_OK\n", 12); }  // 前哨：先确认死在哪一段
+// pre-main 装异常处理器，崩时打印 ucontext PC 与 x8（aarch64 的 x8 = syscall 号）：
+//   install sigaction(SIGSYS/SEGV/ABRT) → handler 里 mcontext->pc（触发指令地址）+ mcontext->regs[8]（syscall 号）
+```
+
+**解法与上游 Android 一致**：平台分支 `__OHOS__` 复用对应的 Android 空操作桩后端
+（构造空操作，`set`/`wait` 抛「未实现」异常）；POSIX 后端的 `getFileName()` 加 TMPDIR 优先分支
+（app 域无 `/tmp`，TMPDIR 自动注入可写 cache 目录）；testsuite 相关测试沿用上游的 Android 平台豁免宏
+（形如 `<库前缀>_OS_ANDROID`）扩展到 `__OHOS__`。
+
+## 关卡⑥：SIGINT 优雅退出失效——两道关：继承 SIG_IGN + 工具侧「前台才接」gate
+
+`kill -INT` 优雅退出用例在 app 域 fork+execv 子进程上失效，根因是**两层**，别只归给「继承 SIG_IGN」：
+
+1. **继承 `SIG_IGN`**：NAPI 宿主进程（HAP 的 app 域）对 SIGINT 设了 `SIG_IGN`，`fork()+execv()` 后子进程
+   仍保持忽略（POSIX：被忽略的信号在 exec 后继续被忽略）。工具自己的 `signal(SIGINT, handler)` 能否覆盖
+   取决于它何时装——多数工具在 `server_preinit`/`main` 早期会重装 handler 把 `SIG_IGN` 顶掉，但若没装到位则一直吞。
+2. **工具侧「前台才接」gate（更隐蔽）**：不少 CLI 把 SIGINT 当「终端 Ctrl+C 语义」处理，handler 里先判
+   `tcgetpgrp(STDIN_FILENO) > 0`（是否有控制终端且在前台进程组），非前台就**主动忽略**——openocd 非 `_WIN32`
+   分支正是 `server.c:714` 把 SIGINT 绑到 `sigkey_handler`（内部 `if (tcgetpgrp(STDIN_FILENO) > 0) sig_handler(sig);`），
+   SIGTERM 才走无条件 `sig_handler`（`server.c:716`）。app 域子进程**没有控制终端**，`tcgetpgrp` 返 -1 → SIGINT 虽
+   递送到了 handler 也被吞，只能升 SIGKILL 硬杀（数据/连接状态丢）。
+
+**修复 = 两道，缺一不可（openocd 0.12 F-07-03 真机实证）**：
+
+1. **runner 侧信号重置 `child_pre_exec()`**：exec 前把「当前被忽略」的可捕获信号改回 `SIG_DFL` **并清空阻塞掩码**——
+   否则 SIGINT 在 exec 后仍保持 SIG_IGN/被阻塞，工具的 `signal(SIGINT, handler)` 根本不会被调用（验证方必做）：
+
+   ```c
+   /* 完整版（openocd 续修 2026-09-11 实证；比只重置 SIG_IGN 更关键的是清空掩码） */
+   void child_pre_exec() {
+     signal(SIGINT, SIG_DFL);
+     signal(SIGTERM, SIG_DFL);
+     signal(SIGQUIT, SIG_DFL);
+     signal(SIGHUP, SIG_DFL);
+     signal(SIGPIPE, SIG_DFL);
+     sigset_t empty;
+     sigemptyset(&empty);
+     sigprocmask(SIG_SETMASK, &empty, nullptr);   // ← 掩码清空比 SIG_IGN 重置更关键
+   }
+   ```
+
+   > ⚠️ **为什么掩码清空是必要的**（openocd 续修轮关键发现）：POSIX 中 `exec()` 只把「被捕获的 handler」重置为
+   > SIG_DFL，**SIG_IGN 处置与整个信号掩码（sigprocmask blocked set）原样保留**。工具的 `signal(SIGINT, handler)`
+   > 只能覆盖处置、**改不掉掩码**——若宿主把 SIGINT 放进 blocked set，信号永远 pending 不递送。`sigprocmask(SIG_SETMASK, &empty)`
+   > 是 posix_spawn `POSIX_SPAWN_SETSIGMASK` 的裸 fork 等价物，exec wrapper 的标准责任（与
+   > `reset_inherited_signal_ignore()` 只重置 SIG_IGN 处置相比是**完整修复**，后者只修了一半）。
+   >
+   > ⚠️ **同一机制使 alarm() 看门狗兜底失效**（某库单进程 ELF 重度自测用例存活 2.5h+ 而不被
+   > alarm(900s) 收割的实证，2026-10-11）：exec 前只重置 SIG_IGN 不清掩码时，宿主 blocked set 里的
+   > SIGTERM/SIGALRM 到点**永远 pending 不递送**——alarm 到点进程不死，串行 worker 队列被
+   > 堵死、整轮无 summary。exec 看门狗勿依赖子进程 alarm，用父进程计时 +
+   > `kill(-pid, SIGKILL)`（E178 失效模式 2）。
+
+2. **产品侧 patch**：工具自己的「前台才接」gate 在 app 域无解，只能 patch 产品。openocd 的 `sigkey_handler`
+   在无前台终端时主动忽略 SIGINT（on-device hilog 实证：降完 SIG_IGN 后 SIGINT 已递送到 handler，
+   但打 `sigkey_handler(): Ignored Signal 2`）；而 **app 域补不出控制终端**——`posix_openpt`→`grantpt/unlockpt`
+   →`setsid`→`open(ptsname)`→`ioctl(TIOCSCTTY)`→`tcsetpgrp` 整条链跑完**回调全成功、不报错**，但 exec 后子进程
+   `tcgetpgrp(STDIN_FILENO)` 仍返 <=0（TIOCSCTTY/前台进程组在 app 沙箱无会话语义，静默失效）。正解是**产品侧
+   patch**：`__OHOS__` 下 `sigkey_handler` 直接无条件 `sig_handler(sig)`——app 域没有终端 Ctrl+C 概念，SIGINT 由
+   kill() 投递即表退出意图（patches/0005）。这就是「上游/平台信号重设方案」的落地形态：落在产品补丁上，不是平台侧。
+
+**判定口径**：`kill(srv, SIGINT)` 后**别按退出码判**——openocd 的 `exit_on_signal(sig)` 在 *nix 上是
+`signal(sig, SIG_DFL); raise(sig)`（`server.c:759`），进程最终**被 SIGINT 终止**，`waitpid` 拿到的是
+`WIFSIGNALED && WTERMSIG==SIGINT`（不是 `exit(130)`）。断言写
+`(WIFSIGNALED(st) && WTERMSIG(st)==SIGINT) || (WIFEXITED(st) && WEXITSTATUS(st)==0)`。
+
+> ⚠️ **实测否定的路线**：曾误判「runner 侧造 pty 控制终端」能解决 foreground gate（node-pty 只证 NDK/root 域
+> PTY OK，不代表 app 域会话语义成立）。实测 TIOCSCTTY/tcsetpgrp 在 app 域静默失效，白费一轮改码。**别在 runner
+> 侧补终端，直接 patch 产品侧 gate**（SIGINT 的 foreground 语义产品级去除，或等价地让 SIGINT 走无条件 sig_handler）。
+
+## 怎么定位（排障套路）
+- app 域进程 stdout/hilog 往往抓不全，且主进程 spawn 的子进程崩溃通过 SIGCHLD 通知在 OH-Electron 主进程里**不可靠**（`spawnSync` 成功 exec 会永久阻塞、子进程变僵尸）。改用：异步 `spawn` + 子进程 stdio 直接重定向到文件 fd；探活用「`spawn` 后 600ms 内没 `error` 事件即视为 exec 成功」。
+- 子进程崩溃看 **`/data/log/faultlog/faultlogger/cppcrash-<bundle>-*`**：`Reason:` 行直接给信号与 syscall 号（SIGSYS+425/426/427=io_uring；SIGSYS+436=close_range；SIGTRAP+V8 栈=JIT 断言）。
+- 想确认 LD_PRELOAD shim 到底有没有加载，给 shim 加 `__attribute__((constructor))` 往文件写个 marker；验证完记得撤掉。
+
+## 相关
+- [[鸿蒙PC-HNP二进制SELinux-exec限制]] —— 公共 HNP 二进制的 exec 限制（另一面）。
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— 私有 HNP 打包 mode/symlink 农场/6.0 vs 6.1 版本差异。
+- [[鸿蒙PC-HNP包与PATH]] —— HNP 安装位置与 PATH。
+- [[鸿蒙PC-进程视角与mount-namespace]] —— app NS 视图（`/data/app/...`）vs hdc su 视图（`/data/app/el1/bundle/<userId>/hnp/...`）。
+- [[鸿蒙PC-opencode-HAP化-Electron壳]] —— 本条三关的来源与完整落地。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-app/345/237/237/346/265/213/350/257/225/345/211/215/347/275/256/346/235/241/344/273/266/347/237/251/351/230/265.md

@@ -0,0 +1,52 @@
+---
+name: 鸿蒙PC-app域测试前置条件矩阵
+description: 测试前置类别 × 验证域可用性 × 等价构造法——在 HAP/app 域跑设备验证前先查这张表：mknod/命名管道/AF_UNIX 路径/真实 ELF fixture/终端/故障注入/文件系统锁在 app 域能不能满足、不能满足时怎么改测法。总纲：把纯函数当 IO 函数测是测试设计错误——入参是整数/枚举的一律常量构造。触发词：mknod、mkfifo、命名管道、S_IFIFO、S_IFSOCK、文件类型位、AF_UNIX bind、socketpair、/dev/tty、无终端、故障注入、malloc 失败、setrlimit、真实 ELF、fixture、HMDFS、文件锁、flock、测试目录、app 域测试、沙箱前置、testenv、测试前置、strmode 测法、常量构造。
+metadata:
+  type: platform
+  source: new/PC + libbsd 0.12.2 外部一致性测试（21 项 testenv-limited FAIL 实证，2026-08）
+---
+
+# 鸿蒙 PC：app 域测试前置条件矩阵
+
+## 总纲（最重要的一条）
+
+**把纯函数当 IO 函数测是测试设计错误。** 入参是整数/枚举/位掩码的 API（mode 位、格式标志、编码 flags、错误码）——**直接用常量构造输入**，不要为了「真实感」去创建文件系统对象。实证：`strmode(mode_t, buf)` 的入参只是一个整数，一次外部一致性测试为它造了 12 条「需要真实 fifo/socket/字符设备文件」的用例，在 app 域全军覆没——而喂 `S_IFIFO|0644` 常量本来一行就能测完同一代码路径。
+
+先分类再设计：**纯函数族**（常量构造，全测）/ **前置依赖族**（查下表）/ **交互终端族**（失败路径 + 显式豁免）。
+
+## 前置条件矩阵（app 域 = HAP 内验证场景）
+
+> 「特权域」那列**只用来解释「为什么 app 域不行」**，不是可以退去的地方：鸿蒙 PC 上
+> `hdc shell` 恒为 uid 2000、没有 root 可提，见 [[鸿蒙PC-hdc能力边界与取证通道]]。
+> **看到某项在特权域 ✓，不等于「换个域去测」是选项——只有「等价构造法」那列是可执行的。**
+
+| 前置类别 | 特权域（仅作对照，**鸿蒙 PC 上不可达**） | app 域（HAP 内）＝你的实际战场 | 等价构造法 |
+|---|---|---|---|
+| 字符/块设备节点（mknod） | ✓ | ✗ 需系统权限 | **常量构造**：mode_t 位掩码直接喂（`S_IFCHR`/`S_IFBLK`）；真需要文件系统的测试断言 stat 族字段时改测纯函数路径 |
+| 命名管道（mkfifo） | ✓ | 分文件系统，不稳定 | 同上：`S_IFIFO` 常量；或 socketpair 替代进程间通道 |
+| AF_UNIX bind 路径名 | ✓（POSIX 矩阵已证） | ✗ SELinux EPERM | **socketpair**（匿名、不 bind）；必须路径名的（权限传递类）判豁免 |
+| 套接字类型位（`S_IFSOCK`） | ✓ | — | 常量构造即可，无需真 socket |
+| 真实 ELF 文件（当 fixture） | ✓ | ✓ 但路径要想对 | **HAP 自带的 .so 就是现成 fixture**：`entry/libs/arm64-v8a/` 里的库文件可读、可 open、可 mmap——符号表查询/ELF 解析类测试用它，别用 `./test` 占位路径（实测会 ENOENT） |
+| 终端（/dev/tty） | ✓ | ✗ 无终端环境 | 终端交互 API 只测**失败路径**（返回 NULL + errno ENOTTY/ENXIO）；成功路径判豁免，归 testenv-limited。⚠️ 造 pty（`posix_openpt`+`TIOCSCTTY`+`tcsetpgrp`）在 app 域**静默失效**（会话语义不成立，`tcgetpgrp` 仍返 -1）——SIGINT 优雅退出这类 foreground gate 用例靠**产品侧 patch**解，见 `app域执行二进制与JIT限制` 关卡⑥ |
+| 故障注入（malloc 失败/rlimit 限制） | ✓ | setrlimit 受限、注入不可行 | 语义降级：改测「正常路径 + 空指针守卫」可测的部分，注入场景判豁免（**没有可补测的特权域**） |
+| 文件锁（flock/fcntl F_SETLK） | ✓ | **HMDFS 上语义与 POSIX 有差异** | 见下节——测试工作目录换 app 沙箱本地 files/ 后重测，仍失败才判分歧 |
+| /proc/self/exe 等自身路径 | ✓ | 可读性按路径而异 | 部署后的 .so 路径（应用沙箱内绝对路径）更可靠 |
+| 环境变量（setenv/getenv） | ✓ | ✓ | — |
+
+## HMDFS vs 本地 FS：测试目录是显式决策
+
+工作目录在 HMDFS（`/storage/Users/...` 桌面桥路径）还是在 app 沙箱本地（`.../files/`），会改变文件语义——fd 关闭行为、重建一致性、锁语义都有实测差异。**测试 harness 的默认工作目录落在哪个文件系统上必须是有意识的选择**：
+
+- 测**文件系统行为本身**（锁/持久化/重建）→ 放 app 沙箱本地 `files/`（语义最接近 POSIX 预期）；
+- 测**桌面文件访问能力** → 才用 HMDFS 路径；
+- harness 无意识落在 HMDFS 上产生的 FAIL，先换目录重测，仍失败才按 [[鸿蒙PC-musl与BSD-glibc语义分歧表]] 三向对照判分歧——「HMDFS 语义差异」不能当第一归因。
+
+## 与归因分类学的对接
+
+本矩阵服务 `03-adapt.json` 的 `test_run.failures[].attribution = testenv-limited`：归因前先查矩阵——**能用等价构造法测出来的，不许豁免**（改测法，归 testenv-limited 的修复路由）；矩阵确认不可满足的才判豁免并在 evidence 里引用本矩阵的行。语义权威见 pc-schemas 的 `enum-semantics.md`。
+
+## 相关条目
+
+- [鸿蒙PC-POSIX-NDK能力探针矩阵.md](鸿蒙PC-POSIX-NDK能力探针矩阵.md) — 能力探针矩阵（本表的姊妹篇：那边答「接口存不存在」，这边答「测试前置能不能满足」）
+- [鸿蒙PC-musl与BSD-glibc语义分歧表.md](鸿蒙PC-musl与BSD-glibc语义分歧表.md) — 语义分歧族（testenv-limited 之外的另一类非产物 FAIL）
+- [鸿蒙PC-app域执行二进制与JIT限制.md](鸿蒙PC-app域执行二进制与JIT限制.md) — seccomp/XPM 关卡（SIGSYS 类失败的根因）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-app/350/256/277/351/227/256PC/347/224/250/346/210/267/347/233/256/345/275/225.md

@@ -0,0 +1,38 @@
+---
+name: 鸿蒙PC-app访问PC用户目录
+description: 普通 app 默认只能进不能读写 /storage/Users/currentUser（others 仅 --x，不在 file_manager 组）；申请 READ_WRITE_DOCUMENTS/DOWNLOAD_DIRECTORY（normal 级）+ 运行时授权后可凭 access-token 直接读写，Desktop 要 system_basic 够不着
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：app 访问 PC 用户目录（Documents/Download/Desktop）
+
+> 平台机制，与具体库无关：任何 HAP app 想读写 PC 上的用户公共目录（不只是自己沙箱）都适用。从给 opencode HAP（[[鸿蒙PC-opencode-HAP化-Electron壳]]）开"打开 PC 任意目录"能力时抽取。
+
+## 默认状态：app 只能进、不能读写用户目录
+`/storage/Users/currentUser/`（及其下 Documents/Download/Desktop）整棵树都是 `20001006:file_manager`、mode `drwxrws--x`——group(file_manager) 有 rwx，**others 仅 `--x`**（能进入、不能列目录、不能写）。普通 app 的 uid（如 20020175）不在 file_manager 组（`Groups: 1097 3099`），所以默认只能进不能读写。
+> 对比：HiShell 等系统应用的进程 `Groups` 含 **1006(file_manager)**，所以它们能自由读写用户目录——普通 app 拿不到这个组。
+
+## 正解：申请目录权限 + 运行时授权（不靠改组）
+1. `module.json5` 的 `requestPermissions` 声明（user_grant 权限**必须**带 `reason`(指向 $string 资源) + `usedScene`，否则 hvigor 报 `00303218 Configuration Error`）：
+   - `ohos.permission.READ_WRITE_DOCUMENTS_DIRECTORY` —— **normal** 级，可申请
+   - `ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY` —— **normal** 级，可申请
+   - `ohos.permission.READ_WRITE_DESKTOP_DIRECTORY` —— **system_basic** 级，**normal 签名的 app 申请不到**（桌面目录够不着）
+2. ArkTS 入口 Ability `onCreate` 里 `abilityAccessCtrl.createAtManager().requestPermissionsFromUser(context, [...])`——user_grant 权限只能运行时弹窗，首启弹"允许 xx 访问你的文档文件夹？"，用户点允许。
+3. **授权后无需进 file_manager 组**：app 的 `Groups` 不变（仍 1097/3099），但 hmdfs/hmmac 凭 access-token 放行——持权限的进程可**直接用物理路径** `fs.writeFileSync('/storage/Users/currentUser/Documents/x.txt')` 读写成功（写出的文件 owner 会变成 `20001006:file_manager`，说明 hmdfs 接管归属）。
+
+## 验证 / 排查
+- 授权状态：`hdc shell atm dump -t -b <bundle>`，找权限名看 `grantStatus`（**0=已授予**，-1=拒绝）。`atm`=access token manager，`atm dump -t -i <tokenid>` 也行。
+- `acm` 是**账号**管理，不是权限授予；hdc **没有** `pm grant` 式命令，user_grant 只能 app 弹窗授权。
+- 文件落地验证走 hdc su 视角的真实路径：逻辑 `/storage/Users/currentUser/Documents` ↔ 真实 `/storage/media/<userId>/local/files/Docs/Documents`（见 [[鸿蒙PC-uid与文件归属]]）。
+- app 沙箱里 `/storage/Users/currentUser` 本就 bind-mount 了 hmdfs（`/proc/<pid>/mountinfo` 可见 `master:12 - hmdfs .../hmdfs/account`），路径可见，问题只在权限不在挂载。
+
+## 边界
+- 能做到：Documents、Download 全读写（normal app + 授权）。
+- 做不到：Desktop 及"PC 上任意路径"——Desktop 要 system_basic，任意路径要 FILE_ACCESS_MANAGER(system_basic)/file_manager 组，都需系统级签名（normal debug 证书 `apl:normal` 给不了）。要全盘访问只能换更高 APL 的签名。
+
+## 相关
+- [[鸿蒙PC-uid与文件归属]] —— file_manager uid/组、桌面物理路径、为何别硬写物理路径（本条是"授权后就能写物理路径"的补充）。
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— 同一 HAP 的 app 域其它限制（exec/io_uring/JIT）。
+- [[鸿蒙PC-opencode-HAP化-Electron壳]] —— 落地：opencode 据此读写 PC Documents/Download。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-glib-gtest/351/235/231/346/200/201/351/223/276/346/216/245musl/345/220/257/345/212/250/345/264/251/346/272/203.md

@@ -0,0 +1,89 @@
+---
+name: 鸿蒙PC-glib-gtest静态链接musl启动崩溃
+description: >-
+  glib gtest 框架（g_test_init）在 musl OHOS 上静态链接入测试二进制后启动即崩溃的根因与对策。
+  中心仓 glib 仅提供 .a 静态库（无 .so 共享库选项），gtest 框架静态链接后无法避免崩溃：
+  musl 的 __assert_fail 调用 __stdio_exit 退出 stdio，与 glibc（使用 __fxprintf）不同，
+  g_test_init 初始化路径触发 assert 导致进程崩溃。对策：补写等价的非 glib 测试用例替代
+  上游 glib gtest 用例，或等中心仓提供 glib 共享库后再切 shared 链接。
+  触发词：glib、gtest、g_test_init、GLib testing framework、静态链接、.a 静态库、musl assert、
+  __assert_fail、__stdio_exit、__fxprintf、测试启动崩溃、测试二进制崩溃、crash on startup、
+  test binary crash、glib gtest 崩溃、无 glib 共享库、中心仓 glib。
+metadata:
+  type: platform
+  source: usbredir 0.15.0 适配实证（test-filter/test-serializer 豁免归因，2026-09）
+---
+
+# glib gtest 框架在 musl OHOS 上启动崩溃（g_test_init 触发 assert）
+
+## 现象
+
+交叉编译的测试二进制（依赖 glib gtest 框架，`g_test_init(&argc, &argv, NULL)` 起步）在
+OHOS 设备上**启动即崩溃**——不是某个用例断言失败，是测试框架初始化阶段进程直接死掉。
+
+usbredir 实证：`test-filter`、`test-serializer` 两个上游测试二进制均此现象。
+
+## 根因
+
+三层叠加：
+
+1. **链接形态**：中心仓（Conan）提供的 glib 仅有 `libglib-2.0.a`（无 `.so`），pcre2/libffi
+   同样只有静态库 → gtest 框架被**静态链接**进测试二进制，无共享库可切换。
+   实证：`llvm-readelf -d dist/bin/test-filter` 的 NEEDED 仅有 `libusbredirparser.so.1`
+   （无 glib-2.0 等共享库），确认 glib 全部静态链入。
+
+2. **musl 的 `__assert_fail` 实现差异**：musl `src/exit/assert.c` 的 `__assert_fail` 调用
+   `__stdio_exit` 退出 stdio；glibc 同函数使用 `__fxprintf`。两者在「断言触发时清理 stdio」
+   的路径不同。
+
+3. **g_test_init 初始化路径触发 assert**：g_test_init 在初始化过程中触发了某个 assert
+   （glib 对运行时环境的前提检查），在 glibc 上该路径不触发或可恢复，在 musl 上直接走进
+   `__stdio_exit` → 进程崩溃。
+
+结论：**不是产物缺陷**，是「glib gtest + musl 静态链接」的组合问题，切换 shared 链接（目前
+中心仓不可行）或绕开 gtest 框架才能解决。
+
+## 判定方法
+
+拿到崩溃的测试二进制，按序确认：
+
+```bash
+# 1. 确认 glib 静态链接（无 glib 共享库 NEEDED）
+llvm-readelf -d dist/bin/<test> | grep NEEDED
+
+# 2. 确认依赖库只有 .a
+ls deps/glib-*/dist/lib/            # 应只见 libglib-2.0.a，无 .so
+
+# 3. 确认 musl assert 路径（源码级）
+#    musl src/exit/assert.c:6-12 —— __assert_fail 调 __stdio_exit（glibc 用 __fxprintf）
+```
+
+三步全中 → 归因「glib gtest 静态链接 musl 启动崩溃」，走对策。
+
+## 对策
+
+### 首选：补写等价非 glib 测试用例替代
+
+上游 gtest 用例的**断言面**（黑盒输入输出契约）与测试框架解耦——把每条用例的断言逐条
+重写为纯 C 测试（不依赖 glib）：
+
+- 分析上游用例的断言内容（成功/失败路径、边界、错误码），逐条转写为 `assert()`/自写宏。
+- 交叉编译为独立测试二进制，走 CLI 载体（私有 HNP execv）在设备上跑。
+- **逐条比对断言覆盖面**：每转写一条就对照上游用例登记一条（covered / 缺口），
+  缺口如实标注——「覆盖等价性 partial」优于「豁免了但没补」。
+
+usbredir 实证：test-parser.c 57 断言 + test-filter-check.c 19 断言，覆盖 F-01/F-02 的
+check/print/verify/异常面；上游 serializer roundtrip 正向断言与 filter 的
+string_to_rules 29 路边界为已知缺口，如实登记。
+
+### 备选：等中心仓提供 glib 共享库
+
+中心仓 glib 若后续提供 `.so` 构建选项，测试二进制切 shared 链接即可绕开（gtest 框架以
+共享库形态加载，assert 路径进入 glib 自己的动态库上下文）。当前无此选项，等待或自行交叉
+编译 glib 共享库。
+
+## 关联
+
+- [[鸿蒙PC-musl与BSD-glibc语义分歧表]] —— 同为 musl 与 glibc 行为分歧；本条是「断言实现
+  路径」维度的分歧（__assert_fail 的 stdio 清理方式）。
+- pc-knowledge-base adaptation「usbredir 交叉编译全套方案」—— 补写用例 + 双载体验证的具体流程。