@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/adaptation//351/270/277/350/222/231PC-OHOS-NDK-clang15-C++/346/226/260/347/211/271/346/200/247/345/205/274/345/256/271/347/274/272/345/217/243/346/270/205/345/215/225.md

@@ -0,0 +1,56 @@
+---
+name: 鸿蒙PC-OHOS-NDK-clang15-C++新特性兼容缺口清单
+description: OHOS NDK clang 15.0.4 + libcxx-ohos 15 面对 C++20/23 重度项目时的全部已知缺口与机械修法：concepts 约束 auto 带模板模板实参 ICE（改 requires 子句）、ranges 门控（-D_LIBCPP_ENABLE_EXPERIMENTAL）、P0960 聚合括号初始化缺失（改花括号）、P0634 typename 可选语境缺失（补 typename）、CRTP 基类约束成员缓存 bug（改函数模板延迟求值）、libc++ 裁剪（无 <source_location>、无 string_view operator<=>、float from_chars 被标记 deleted 复用 __APPLE__ 分支 strtod_l 兜底）。触发词：clang 15、NDK 15、concepts ICE、frontend command failed、stack dump、std::ranges no member、missing typename、functional-style cast、source_location not found、string_view <=>、CRTP、cannot decrement、from_chars deleted、strtod_l、C++23、C++20、compiler version、MySQL 26
+metadata:
+  type: adaptation
+  source: new/PC（mysql-server 26.7.0 Innovation 交叉编译实证，2026-09-10，commit 23e360a7；from_chars 缺口由 IfcOpenShell 0.9.0 交叉编译实证补充，2026-09-20）
+---
+
+# 鸿蒙 PC：OHOS NDK clang 15 的 C++20/23 兼容缺口清单
+
+> 适用判定：目标项目官方要求 clang 17+/GCC 11+（重度 C++20/23：concepts、ranges、
+> 聚合括号初始化），而手头只有 OHOS NDK clang 15.0.4。**先按本清单评估工作量再
+> 决定「源码降级」还是「等 NDK 升级」**——MySQL 26.7 实测：全部缺口均可源码级
+> 机械绕过，两天内收完，不必等 NDK。
+
+## 缺口总表（按发现顺序排修复优先级）
+
+| # | 缺口 | 症状特征 | 修法 | 错误图谱 |
+|---|---|---|---|---|
+| 1 | ranges 算法被 libc++ 门控 | `no member named 'none_of' in namespace 'std::ranges'` | 全局 `-D_LIBCPP_ENABLE_EXPERIMENTAL` | E147 |
+| 2 | concepts ICE：约束 auto 带**模板模板实参** | `clang frontend command failed due to signal` + stack dump，parser token 停在 `)` | 改 `template <typename T> requires Concept<T, TT>` | E146 |
+| 3 | P0960 聚合括号初始化未实现 | 函数式转换报 `no matching conversion`，候选只剩 copy/move ctor | 改花括号；成员是 explicit ctor 类型（如 tuple）时先显式构造 | E148 |
+| 4 | P0634 typename 可选语境未实现 | 模板内 `using X = Dep::Type;` 报 missing 'typename' | 脚本批量补 typename（按 error 行号清单） | E148 |
+| 5 | CRTP 基类约束成员缓存 bug | 派生类明明有 `prev()` 却报 `no member named 'prev'`、`--i would be invalid` | 基类约束成员改 `template <typename S = Self_t> requires ...` 延迟求值 | E148 |
+| 6 | libc++ 裁剪：无 `<source_location>` | `fatal error: 'source_location' file not found` | `__has_include` 守卫 + 默认值兜底类 | E148 |
+| 7 | libc++ 裁剪：`string_view` 无 `operator<=>` | `invalid operands to binary expression (string_view, string_view)` | `a.compare(b) <=> 0` | E148 |
+| 8 | libc++ 裁剪：**float `from_chars` 被标记 deleted** | 浮点解析处报 from_chars 无法实例化/deleted 引用 | 复用上游 `#if defined(__APPLE__)` 分支（追加 `|| defined(__OHOS__)`，include+调用两处）走 `strtod_l` 兜底 | E175 |
+
+## 关键判据与反模式
+
+- **先分清「报错」与「崩溃」**：报错（缺口 1/3/4/6/7）都是普通诊断、逐条可修；
+  崩溃（缺口 2）是前端 ICE，日志里找 `current parser token` 指向的行——MySQL 案
+  该模式只有 5 处函数签名，全树改完即过。
+- **缺口 2 的三变体实测**（clang 15.0.4）：`Concept auto` ✅ / `Concept<int> auto`
+  ✅ / `Concept<TT> auto`（模板模板实参）💥 / `requires` 子句 ✅ /
+  `template <Concept<TT> T>` ✅。只有第三种写法要改。
+- **缺口 5 最阴险**：症状与根因脱节（报的是迭代器缺成员，实为基类 requires 子句
+  在派生类不完整时求值并被缓存）。判定方法：把该成员函数单独拎出来直接调用，
+  同样报 no member → 命中本缺口。
+- **反模式**：看到 ranges 报错就判「NDK 太老不可行」（实际一行标志可解）；看到
+  ICE 就判「必须升级 NDK」（实际 5 处改写可解）；逐个把 `std::ranges::x` 改
+  `std::x`（~40 种算法改不完且污染上游）。
+
+## 最小验证法
+
+每个修法先用 30 行内的独立 TU + `-fsyntax-only` 实证（MySQL 案全部如此），
+再动源码；头文件级修复后用「只包含该头的空 TU」验证（如
+`#include "mysql/gtids/gtids.h" int main(){}`），不必整树构建。
+
+## MySQL 26.7 实证规模
+
+sets/gtids/strconv 三库：5 处约束 auto 改写（E146）、22 处补 typename、
+4 处聚合初始化改花括号、2 个 CRTP 基类（`Iterator_interface`/`Collection_interface`）
+共 13 个约束成员改函数模板、1 处 source_location 兜底、1 处 string_view 比较改写。
+修复后 `mysql/gtids/gtids.h`、`mysql/strconv/strconv.h` 过 `-fsyntax-only`，
+构建从 [10/564] 死点继续推进。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-OpenCL-SDK-app/345/237/237/351/200/202/351/205/215/350/241/245/345/205/205.md

@@ -0,0 +1,88 @@
+---
+name: 鸿蒙PC-OpenCL-SDK-app域适配补充
+description: OpenCL-SDK v2026.05.29 在鸿蒙 PC (HAD-W32, OpenHarmony 6.1.1.135) app 域的适配补充经验——Error.hpp 悬空指针 UB 修复、binaries cwd 不可写修复、app 域 vendor ICD 事件回调限制。与「鸿蒙PC-OpenCL-SDK-适配要点」（root/可调试机版）互补，本文件聚焦 app 域验证（零售机生态）。
+metadata:
+  type: adaptation
+  source: new/PC (OpenCL-SDK 2026.05.29, app域验证, HAD-W32, Maleoon 916)
+  relates_to: E131, E157
+  supersedes: []
+---
+
+# 鸿蒙 PC：OpenCL-SDK app 域适配补充
+
+> 本文件是 `鸿蒙PC-OpenCL-SDK-适配要点.md` 的 app 域补充。该文件记录 root/可调试机上的编译与 ctypes 验证经验；本文件记录 HAD-W32（OpenHarmony-6.1.1.135）上通过 HAP 私有 HNP 双载体验证的全套经验。
+
+## 一、与 root 机适配的关键差异
+
+| 维度 | root 机（旧记录） | app 域（本记录） |
+|------|-------------------|------------------|
+| 设备 | HongMeng Kernel 1.12.0 | OpenHarmony 6.1.1.135 |
+| 验证方式 | Python ctypes + hdc shell | HAP 双载体（hap-dlopen + HNP fork+execv） |
+| 编译 | 设备本机或 Mac 交叉编译 | NDK 交叉编译（Windows 宿主） |
+| exec 限制 | XPM dmverity 限制 /data/local/tmp | app 域 SELinux 只 exec 私有 HNP |
+| 验证工具链 | 无需 | cli-hnp-runner + OHPTCASE 协议 + hilog 取证 |
+
+## 二、Error.hpp 悬空指针 UB 修复
+
+### 问题
+
+upstream OpenCL-SDK 的 `cl::util::Error` 类中 `errStr_` 为 `const char*`，指向外部持有的 `std::string::c_str()`。File.cpp:35,61 和 Image.cpp:43-44 中 `std::string` 局部变量在传入 `errHandler` 后析构，`c_str()` 返回的指针悬空。在 musl + allocator reuse 下表现为间歇性空串（what() 返回空）。
+
+### 修复
+
+`patches/0001-error-own-string.patch`：将 `errStr_` 类型从 `const char*` 改为 `std::string`，构造时深拷贝消息字符串，`what()` 返回 `errStr_.c_str()`。
+
+```cpp
+// Before (UB):
+class Error : public std::runtime_error {
+    const char* errStr_;  // 指向外部临时 string::c_str()
+};
+// After (fix):
+class Error : public std::runtime_error {
+    std::string errStr_;  // 自拥消息字符串
+    const char* what() const noexcept override { return errStr_.c_str(); }
+};
+```
+
+### 适用范围
+
+适用于任何 C++ 错误类持有外部字符串指针导致悬垂的场景。在 musl（OHOS）上 allocator reuse 策略使此 UB 从不稳定空串转为难度增大的间歇性故障——修复后 `gen_utils_cpp_file_io` 从 flaky FAIL 转确定性 PASS。
+
+## 三、binaries(C) cwd 不可写修复
+
+### 问题
+
+OpenCL-SDK 的 binaries（C 版）用例调用 `cl_util_write_binaries`，内部 `fopen_s("wb")` 因 cwd（HNP pkg/bin/）在 app 域不可写返回 CL_INVALID_VALUE（rc=226）。C++ 版 binariescpp 通过（因走 fstream，内部实现不同）。
+
+### 修复
+
+cli-hnp-runner 的 `napi_stub.cpp:260` 为每个用例的 `cwd` 字段添加路由：将需要写文件的用例（binaries）cwd 设为 `"writable"`，映射到 app 域沙箱可写目录 `/data/storage/el2/base/temp/`（`g_tmp_dir`）。
+
+```cpp
+// napi_stub.cpp: 用例表 cwd 字段
+{"binaries",   run_binaries,   "writable"},  // 原为 "bin"（HNP pkg/bin/ 只读）
+{"binariescpp", run_binariescpp, "writable"},
+```
+
+round3+round4 两轮稳定 PASS，hilog 确认 `Binary file written.` + `Saved program found` + Collatz 完整计算。
+
+### 适用范围
+
+任何通过 HNP 执行的 cpp-lib/cli 在 app 域需要写文件的用例：HNP pkg/bin/ 只读（app 域 mount namespace 限制），必须 chdir 到沙箱可写目录（`g_tmp_dir`）。
+
+## 四、app 域 vendor ICD 事件回调限制
+
+### 问题
+
+callback/callbackcpp 用例在 app 域失败：
+- `clEnqueueNDRangeKernel` 返回 `CL_OUT_OF_HOST_MEMORY`（-6）
+- hilog RAW 段显示 vendor ICD 内部错误：`token timeout!`、`Failed to create cqEvent: postEvent.`、`FreqHintStartEvent`
+- HUAWEI Maleoon 916 GPU 驱动 ICD（`/vendor/lib64/passthrough/libOpenCL.so`）在 app 域 cqEvent 创建被拦截
+
+### 结论
+
+**product-defect/open**，grep 确认上述错误字符串不在 OpenCL-SDK 任何源码中。C 版和 C++ 版双变体均失败。24 条其余 GPU 样本（含 `clEnqueueNDRangeKernel+clWaitForEvents`）全部 PASS，基础 kernel 执行链可用。无第二 ICD 可选、无驱动修改权限。
+
+### 工作区
+
+交付说明注明「HUAWEI Maleoon 916 GPU 驱动在 app 域不支持事件回调（cqEvent 创建失败），影响 OpenCL 事件回调类功能；其余 GPU 计算功能正常」。待华为驱动更新或 app 域权限调整后重新验证。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-OpenCL-SDK-/351/200/202/351/205/215/350/246/201/347/202/271.md

@@ -0,0 +1,144 @@
+---
+name: 鸿蒙PC-OpenCL-SDK-适配要点
+description: KhronosGroup/OpenCL-SDK v2026.05.29 在鸿蒙PC (aarch64-unknown-linux-ohos) 的适配要点，包括编译、ICD 配置、设备 GPU 信息、XPM 执行限制、Python ctypes 踩坑（cl_device_type 必须 c_uint64）
+metadata:
+  type: adaptation
+  source: new/PC
+  library: OpenCL-SDK
+  version: v2026.05.29 (2026-06-15)
+  device: root/可调试机, HongMeng Kernel 1.12.0
+---
+
+# 鸿蒙PC OpenCL-SDK 适配要点
+
+## 结论
+
+OpenCL-SDK 在鸿蒙PC 上**零补丁编译通过**。三个核心示例场景（enumopencl/saxpy/copybuffer）均通过 Python ctypes 验证，Maleoon 916 GPU 可实际执行 OpenCL kernel。macOS Apple M4 对比：OpenCL 已废弃，0 platforms。
+
+## 编译
+
+**完全不需要任何补丁**，标准 ohos.toolchain.cmake 即可：
+
+```bash
+cmake -S src/opencl-sdk -B build/opencl-sdk \
+  -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/ohos.toolchain.cmake \
+  -DOHOS_ARCH=arm64-v8a \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DBUILD_TESTING=OFF \
+  -DOPENCL_SDK_BUILD_SAMPLES=ON \
+  -DOPENCL_SDK_BUILD_OPENGL_SAMPLES=OFF \
+  -DOPENCL_SDK_BUILD_VULKAN_SAMPLES=OFF \
+  -DOPENCL_SDK_TEST_SAMPLES=OFF
+cmake --build build/opencl-sdk --parallel 8
+```
+
+pthread 通过 CMake `find_package(Threads REQUIRED)` 正常找到 `-lpthread`，不需要额外处理。
+
+## 设备 OpenCL ICD 状况（重要）
+
+### 华为的非标准实现路径
+
+华为鸿蒙PC **没有** 标准的 `/etc/OpenCL/vendors/*.icd` 配置文件，而是将 GPU 驱动直接放在:
+
+```
+/vendor/lib64/libOpenCL.so -> passthrough/libOpenCL.so
+/vendor/lib64/passthrough/libOpenCL.so  (44KB, 华为私有 ICD passthrough)
+/vendor/lib64/passthrough/libOpenCL_impl.so -> libhvgr_v210.so
+/vendor/lib64/chipsetsdk/libOpenCL_impl.so  (GPU 实现)
+```
+
+### 使用 ICD Loader 的正确方式
+
+必须用 `OCL_ICD_FILENAMES` 环境变量直接指定 vendor SO（`OPENCL_VENDOR_PATH` 不工作）：
+
+```bash
+export OCL_ICD_FILENAMES=/vendor/lib64/passthrough/libOpenCL.so
+```
+
+这样我们编译的 ICD Loader (`libOpenCL.so`) 就能找到华为的实现。
+
+### 设备 GPU 信息
+
+- **Platform**: HUAWEI OpenCL 3.0 B301 v13.0.0  
+- **Device**: Maleoon 916 (华为自研 GPU)
+- **类型**: GPU (但 `CL_DEVICE_TYPE` 返回非标准值，不是 `CL_DEVICE_TYPE_GPU=4`)
+- **计算单元**: 6 CUs
+- **内存**: 4096MB
+- **OpenCL-C 版本**: OpenCL C 1.2 B301 v13.0.0
+
+## 验证方式（绕过 XPM 限制）
+
+HongMeng Kernel 1.12.0 对 `/data/local/tmp/` 下的 PIE 动态链接二进制有 XPM dmverity 检查，`binary-sign-tool -selfSign 1` 无法满足（只添加 code_sign ELF section，不产生 dmverity hash）。
+
+### Python ctypes 两个关键坑
+
+**坑1：必须用设备原生构建的 ICD loader，不能用 Mac 交叉编译的**
+
+我们用 Mac NDK 交叉编译的 `libOpenCL.so.1.0.0` 加载后，`clGetDeviceIDs` 必然 SIGSEGV。原因见坑2。设备上的 `~/Documents/OpenCL-SDK-main/build_ohos/external/OpenCL-ICD-Loader/libOpenCL.so` 是原生编译的，必须用它：
+
+```python
+ICD_LIB = '/data/service/el2/100/hmdfs/account/files/Docs/OpenCL-SDK-main/build_ohos/external/OpenCL-ICD-Loader/libOpenCL.so'
+os.environ['OCL_ICD_FILENAMES'] = '/vendor/lib64/passthrough/libOpenCL.so'
+cl = ctypes.CDLL(ICD_LIB)
+```
+
+**坑2：OpenCL 含 `unsigned long` 参数的函数必须设 argtypes，否则 SIGSEGV**
+
+`cl_device_type` / `cl_mem_flags` / `cl_command_queue_properties` 在 64-bit OHOS 上是 `unsigned long` = 8 字节。ctypes 默认按 `int`（4字节）传参，参数错位导致栈损坏，即 `clGetDeviceIDs` SIGSEGV：
+
+```python
+# 正确写法 —— 必须 c_uint64 而非 c_uint32！
+cl.clGetDeviceIDs.argtypes = [
+    ctypes.c_void_p,    # platform
+    ctypes.c_uint64,    # device_type  ← cl_device_type = unsigned long = 64-bit
+    ctypes.c_uint32,    # num_entries
+    ctypes.c_void_p,    # *devices
+    ctypes.POINTER(ctypes.c_uint32)  # *num_devices
+]
+r = cl.clGetDeviceIDs(plat, ctypes.c_uint64(0xFFFFFFFF), ...)
+```
+
+类似地：`clCreateBuffer` 的 `flags`（`cl_mem_flags`）、`clCreateCommandQueue` 的 `properties`（`cl_command_queue_properties`）都要用 `c_uint64`。
+
+
+### 实测验证输出
+
+```
+场景 2/3  saxpy — GPU 向量乘加  y = α·x + y
+  N=65,536  α=2.0
+  ⏱  Wall: 1.97ms  |  GPU kernel: 33.1µs
+  Bandwidth: 23.74 GB/s
+  ✅ SAXPY 验证通过
+
+场景 3/3  copybuffer — 设备内缓冲区拷贝
+  拷贝 1024 KB
+  Bandwidth: 22.71 GB/s
+  ✅ copybuffer 验证通过
+```
+
+## XPM 执行限制详情
+
+- **现象**: `hdc shell /data/local/tmp/mybinary` 报 `Operation not permitted`
+- **dmesg**: `[xpm:1010] mybinary is not protected by dmverity`
+- **根因**: HongMeng Kernel 1.12.0 要求 `/data/local/tmp/` 下执行的 PIE 动态链接 ELF 有 dmverity 签名
+- **binary-sign-tool 的作用**: 添加 `.code_sign` ELF section，但不满足 XPM 的 dmverity 要求
+- **与旧版区别**: 早期适配记录（如 goaccess）说 `data_local_tmp 标签，exec 无需签名`——这可能是旧内核版本行为，1.12.0 加强了检查
+- **正确绕过**: 将可执行文件打包为 HAP 私有 HNP (`type=private`)，标签变为 `private_hnp_file:s0`，app 域可 exec
+- **不影响**: `.so` 共享库通过 dlopen 加载不受 XPM 限制
+
+## 与 goaccess 记录的差异
+
+[[鸿蒙PC-autotools-C二进制-goaccess]] 记录 `data_local_tmp` 无需签名即可 exec。
+本次在 HongMeng Kernel 1.12.0 上发现不再成立，XPM 已加强。该旧记录针对早期内核，需注意。
+
+## 补充：app 域适配（HAD-W32 / OpenHarmony 6.1.1.135）
+
+本文件记录的是 root/可调试机上的编译与 ctypes 验证经验。后续在 HAD-W32（OpenHarmony 6.1.1.135，零售机级设备）上通过 HAP 双载体（cpp-lib-demo + cli-hnp-runner）做了完整的 app 域验证，经验记录在：
+
+> **[[鸿蒙PC-OpenCL-SDK-app域适配补充]]** — 新增经验包括：
+> - Error.hpp 悬空指针 UB 修复（errStr_ const char* → std::string），压测间歇性空串
+> - binaries(C) cwd 不可写修复（napi_stub.cpp 路由至沙箱可写目录 g_tmp_dir）
+> - app 域 vendor ICD 事件回调限制（cqEvent 创建失败，product-defect/open）
+> - 补写用例断言的环境敏感性（-2000 越界 vs CL_DEVICE_NOT_FOUND）
+> - .cl kernel 数据文件 HNP 打包（EXTRA_DATA 遗漏）
+> - OCL_ICD_FILENAMES 在 fork+execv child_pre_exec 阶段注入

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-OpenSSL/347/263/273/345/257/206/347/240/201/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,127 @@
+---
+name: 鸿蒙PC-OpenSSL系密码库交叉编译
+description: OpenSSL/BoringSSL/LibreSSL 等 Perl Configure 构建的密码库交叉编译到 aarch64-linux-ohos：复用 linux-aarch64 目标 + 覆盖 CC/CXX/AR/RANLIB，禁用 Linux 特有引擎，链接期 -Wl,--code-sign；零源码补丁即可。另收 TLS 内存握手测试需服务端自签证书、国密分支 NTLS 默认禁用需 enable-ntls。触发词：OpenSSL、Configure、linux-aarch64、no-afalgeng、crypto、ssl、自签证书、SSL_CTX、enable-ntls、NTLS、TLCP、国密。
+metadata:
+  type: adaptation
+  source: new/PC（OpenSSL 系密码库实证）
+---
+
+# OpenSSL 系密码库交叉编译到鸿蒙 PC
+
+来自 OpenSSL 系密码库交叉编译适配（OpenSSL / BoringSSL / LibreSSL 通用）。
+这类库不走 CMake/autotools，而是 **Perl Configure** 自定义构建系统。
+
+## 1. Configure 方案：复用 linux-aarch64 + 覆盖工具链变量
+
+**无需新增 Platform 目标**——直接复用现成的 `linux-aarch64` 配置，把编译工具链覆盖成 OHOS NDK clang：
+
+```bash
+./Configure linux-aarch64 \
+  --prefix=$PREFIX \
+  --cross-compile-prefix= \
+  CC="$OHOS_NDK/llvm/bin/aarch64-unknown-linux-ohos-clang --target=aarch64-linux-ohos" \
+  CXX="$OHOS_NDK/llvm/bin/aarch64-unknown-linux-ohos-clang++ --target=aarch64-linux-ohos" \
+  AR=aarch64-unknown-linux-ohos-llvm-ar RANLIB=aarch64-unknown-linux-ohos-llvm-ranlib \
+  no-afalgeng no-devcryptoeng no-capieng no-ktls \
+  LDFLAGS='-Wl,--code-sign'
+```
+
+要点：
+- **禁用 Linux 特有引擎**：`no-afalgeng`（AF_ALG 内核加密接口，OHOS 无）、`no-devcryptoeng`、
+  `no-capieng`、`no-ktls`。
+- **链接期签名**：`LDFLAGS='-Wl,--code-sign'`，`.so`/可执行文件自动带 `.codesign` 段，
+  免除 post-build 单独签名（dlopen/exec 需要，见错误图谱 E077/E129）。
+- **`no-asm` 可选降级纯 C**：aarch64 perlasm 兼容性好、musl 目标无需硬件加速汇编时才要；默认可留着。
+- 结论：**零源码补丁**即可完成可移植 C 代码的交叉编译。
+
+## 2. TLS 内存握手测试：服务端必须配自签证书
+
+用内存 BIO 模拟 TLS 1.3 握手时，服务端 `SSL_CTX` **必须配置自签证书**（X509 + EVP_PKEY），
+否则 `SSL_accept` 成功后数据通道建不起来（`SSL_read` 返回 -1）。写 `make_self_signed_cert()`
+辅助函数生成 RSA-2048 自签证书挂到 `SSL_CTX_use_certificate`/`SSL_CTX_use_PrivateKey`，
+修复后 TLS 1.3 握手通过、5 字节数据成功收发（`version=TLSv1.3`）。
+
+## 3. OpenSSL 国密分支：NTLS 默认禁用，需显式 `enable-ntls`
+
+OpenSSL 国密分支库的 NTLS（国密 TLCP）在 Configure 默认配置下**不编入**——不加 `enable-ntls`
+时 `libssl.so` 动态符号表零 ntls 符号（`SSL_CTX_enable_ntls`/`NTLS_method` 等全部缺失），
+构建不报错、普通 TLS 功能正常，属**静默能力缺失**，直到国密用例调用才暴露。
+
+修法：Configure 原命令追加 `enable-ntls` 全量重建（实证 `libssl.so` 体积明显增大，增量即
+NTLS 代码），并以 `llvm-nm -D` 逐符号复核 + 重建前后基线对比留证。适配默认关闭可选协议
+套件的 OpenSSL 分支库、并需验收国密 NTLS/TLCP 能力时，先核对构建开关，别把「默认没开」
+误判成「平台不支持」。
+
+## 4. demo 验证接线：TLS 1.3 / NTLS 握手与证书构造（运行时侧）
+
+> 构建开关 `enable-ntls` 只是把符号编进去，**运行时接线还要再显式启用**。以下全部是
+> demo 验证阶段（`napi_stub.cpp` 给 OpenSSL 系/某国密 OpenSSL 分支库接线）实测踩坑，错误条目见
+> `pc-error-atlas` E156（五类 harness-defect，改 stub 不改库）。
+
+### 4.1 TLS 1.3 内存 BIO 握手：用 ssltestlib 交叉接线，别用手工 pump
+
+「泵模式」（`SSL_do_handshake` 交替 + `BIO_read`/`BIO_write` 手动搬数据 + `BIO_set_mem_eof_return`）
+对 TLS 1.2 兼容、对 **TLS 1.3 信号乱序**（1.3 握手消息加密、时序依赖严格），client 报
+`SSL_R_UNEXPECTED_MESSAGE`（0A0000F4）。修法照抄 OpenSSL 官方 `sslapitest.c` /
+该分支 `ssl_ntls_api_test.c` 的 `create_bare_ssl_connection` 交叉接线：
+
+- client/server 各挂**分离的读/写 mem BIO**（`BIO_new(BIO_s_mem())` × 4），对端的读 BIO
+  接到本端的写 BIO；
+- **共享 BIO 用 `BIO_up_ref` 增持后再交给第二个 SSL**——漏 up_ref 会双重释放，`SSL_free`
+  时直接启动崩溃（曾把崩溃误判成 HAP 生命周期问题，排查多轮才定位）；
+- `SSL_connect`/`SSL_accept` 交替驱动，**无 pump**。
+
+### 4.2 NTLS 握手：`NTLS_method()` 与 `SSL_CTX_enable_ntls()` 必须成对
+
+该分支 `ssl/statem/statem.c` 的 `ossl_statem_connect/accept` 只在 `sc->enable_ntls==1`
+时路由到 `state_machine_ntls()`（NTLS 状态机）；否则即使 `NTLS_method()` 也走标准 TLS
+状态机，用 NTLS_VERSION=0x0101 协商 → 对端报 `SSL_R_UNSUPPORTED_SSL_VERSION`
+（legacy_version=0x0101）。修法：**sctx 和 cctx 都**在 `SSL_new` 之前显式
+`SSL_CTX_enable_ntls()`（官方测试每个用例都是 `NTLS_method()` + `enable_ntls()` 成对）。
+`SSL_CTX_set_verify` 同理必须在 `SSL_new` 之前（SSL 创建时继承 ctx verify 模式）。
+
+### 4.3 SM2 自签证书：别调 `X509_sign`，用 PEM 预生成加载
+
+某国密 OpenSSL 分支 8.5.0-pre2 的 `X509_sign`（`ASN1_item_sign` 路径）对 provider-native SM2 密钥走
+legacy ameth 兼容层时报 `ERR_R_PASSED_NULL_PARAMETER`（078C0102）——SM2 签名能力本身完好
+（`EVP_DigestSign` SM2+SM3 路径通过）。修法：宿主 OpenSSL 3.5.6 预生成 SM2 PEM 证书
+（`openssl ecparam -name SM2 -genkey` + `req -new -x509 -sm2`，sign/enc 各一），字符串常量
+嵌入，`PEM_read_bio_X509`/`PEM_read_bio_PrivateKey` 加载（加载后
+`EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)`），绕开 `X509_sign` 路径（该分支官方
+`ssl_ntls_api_test.c` 用 `test/certs/sm2/` 预生成证书同款做法）。
+
+### 4.4 DRBG 显式实例化：必须设 CIPHER 参数；确定性只有 TEST-RAND 可达
+
+`EVP_RAND_fetch("CTR-DRBG")` + `EVP_RAND_CTX_new` 拿到的 CTR-DRBG ctx **不会自动加载密码**
+（`drbg_ctr_new` 只置 `use_df=1`）——不 `EVP_RAND_CTX_set_params(OSSL_DRBG_PARAM_CIPHER="AES-256-CTR")`
+直接 `EVP_RAND_instantiate` 会静默 return 0：`error:1C8000BC:Provider routines::error instantiating drbg`
+（仅包装层错误、错误队列无内层、child_strength=0，见 E177）。生产 `RAND_bytes` 一直正常，
+正因全局链创建 DRBG 时都设了 CIPHER（`crypto/rand/rand_lib.c` 的 `rand_new_drbg` 同款）。
+父源用生产契约 `RAND_get0_private`（系统熵源链 SEED-SRC→primary→private 的次级 DRBG）。
+
+**确定性（同种子→同输出）不是生产 API 契约**：`OSSL_RAND_PARAM_TEST_ENTROPY`/`TEST_NONCE`
+只被 test-only 的 TEST-RAND provider（`test_rng.c`）消费，生产 CTR-DRBG 的 `set_ctx_params`
+只认 `use_df`/`cipher`/`properties`（`drbg_ctr.c:724-802`），给 DRBG 传 TEST_ENTROPY 报
+`error:030000EA provider signature failure`。确定性断言只有 TEST-RAND 作 parent 时可达且属
+测试期能力——用例设计改验「可 fetch + 可实例化 + 强度 256 生成非全零 + 两次输出互不相同」。
+（某国密 OpenSSL 分支 8.5.0-pre2 实证：换父源/换熵源/TEST_ENTROPY 三种接法的 instantiate 失败同根因。）
+
+**国密算法注册名差异**：该分支 keymgmt 的内部注册名是 `SM2`（`providers/implementations/include/prov/names.h:323`：
+`#define PROV_NAMES_SM2 "SM2:1.2.156.10197.1.301"`），不是 OpenSSL 标准写法 `EC-SM2`——
+`openssl genpkey -algorithm EC-SM2` 报 `unsupported algorithm EC-SM2`，`-algorithm SM2`
+（或直接写 OID `1.2.156.10197.1.301`）才被 fetch（8.5.0-pre2 test_gensm2 实测）。国密用例选
+算法名前先查 `names.h` 的注册名，别照搬上游 OpenSSL 文档写法。
+
+### 4.5 v3 CA 自签证书：必须带 `basicConstraints critical,CA:TRUE`
+
+`X509_set_version(cert, 2)` 升 v3 后不加 basicConstraints，`X509_verify_cert` 对正确 CA 也报
+`X509_V_ERR_INVALID_CA`（`X509_check_ca` 返回 0）。修法：`X509_sign` **之前**加扩展
+`X509V3_EXT_conf_nid(NULL, &v3ctx, NID_basic_constraints, "critical,CA:TRUE")` + `X509_add_ext`
+（签名覆盖全部扩展，sign 前加才有效）。证书构造辅助函数（自签 CA）应在库验证 demo 里统一
+带此扩展，链验证/握手两类用例共用。
+
+## 相关
+- [[鸿蒙PC-C++库交叉编译要点]] §5 —— CA bundle 路径 `/etc/ssl/certs/cacert.pem`（非标准）。
+- `pc-registry` —— OpenSSL 已有中心仓 Conan 预编译制品（1.1.1w/3.5.6），依赖 OpenSSL 时**优先复用**（免自编），本文件是「必须自编」时的配方。
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— 密码库 `.so` 经 HAP 载体 dlopen 验证的签名字段说明。
+- `pc-error-atlas` E156 —— 本节五类接线陷阱的完整错误条目（症状/根因/判别/实证）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-POSIX/347/263/273C++/347/261/273/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221/344/270/216/350/256/276/345/244/207/351/252/214/350/257/201.md

@@ -0,0 +1,79 @@
+---
+name: 鸿蒙PC-POSIX系C++类库交叉编译与设备验证
+description: POSIX 系 C++ 类库交叉编译与设备验证：CMAKE_SYSTEM_NAME=Linux 触发 UNIX 分支、musl 缺 pthread_setaffinity_np 按 __OHOS__ 守卫、app 域 seccomp 禁 SysV IPC 用 Android 桩、OpenSSL 走中心仓 Conan 复用；cpp-lib 用 HAP 载体 dlopen 验证核心功能、原库单元测试套件走 CLI 载体 + 环境注入清单；TLS 握手失败先查库的服务端 TLS 空桩（createServerSocket 返回 NULL），别误判平台缺陷。
+metadata:
+  type: adaptation
+  source: new/PC（POSIX 系 C++ 类库实证）
+---
+
+# POSIX 系 C++ 类库交叉编译与设备验证
+
+来自某 C++ 类库（交付形态 `cpp-lib`，原库自带单元测试套件）适配。
+
+## 1. CMAKE_SYSTEM_NAME=Linux 触发 POSIX 系库的 UNIX 分支
+
+OHOS NDK 自带 toolchain 设 `CMAKE_SYSTEM_NAME=OHOS` 时，CMake 的 `if(UNIX)` 为 **FALSE**，导致 POSIX 系库
+的 UNIX 源文件不编译、平台宏（形如 `<库前缀>_OS_FAMILY_UNIX`）与链接库（pthread/dl/rt）不生效。
+**解法**：自定义 toolchain 设 `CMAKE_SYSTEM_NAME=Linux` + `CMAKE_SYSTEM_PROCESSOR=aarch64` +
+手动指定 OHOS clang，让库走完整 UNIX 分支，**无需改上游 CMakeLists**。这是 OHOS 交叉编译 POSIX 系库的
+通用平台识别解法（对照 E092「改 toolchain」路线，这里反其道：不是改库，是让 toolchain 报 Linux）。
+
+## 2. musl 缺 pthread_setaffinity_np —— 按 __OHOS__ 守卫
+
+musl libc 未导出 `pthread_setaffinity_np`/`pthread_getaffinity_np`（E094），线程实现源文件（如
+`Thread_POSIX.cpp`）编译即失败。修法：`setAffinityImpl`/`getAffinityImpl` 加 `!defined(__OHOS__)` 守卫，
+OHOS 上返回 false/-1（线程亲和性可选，降级不影响主路径）。**任何用 pthread 亲和性的库在 OHOS 交叉编译
+都会撞**，属 musl 平台差异非库缺陷。
+
+## 3. app 域 seccomp 禁 SysV IPC —— 命名 IPC 用 Android 桩
+
+`NamedEvent`/`NamedMutex` 的 POSIX 实现基于 SysV 信号量，app 域 `semget`（syscall 190）被 seccomp 杀、
+进程启动即死（零输出）。诊断套路 + Android 桩方案见 [[鸿蒙PC-app域执行二进制与JIT限制]] 关卡⑤。
+
+## 4. OpenSSL 依赖：中心仓 Conan 复用
+
+中心仓 Conan 已有 ohos 预编译 `openssl 1.1.1w/3.5.6`，`OPENSSL_USE_STATIC_LIBS=TRUE` 拉静态库供给
+加解密/网络安全/令牌类组件，**避免 OpenSSL 自编整条链路**（configure/no-asm/构建/部署）。判定顺序见
+`pc-registry`（本地登记 → 中心仓 → 现场适配）。
+
+## 5. 设备验证：HAP 载体 dlopen 覆盖核心功能 + CLI 载体补全量回归
+
+CLI 载体（私有 HNP exec）被平台版本限制挡住时（见 [[鸿蒙PC-私有HNP打包与exec平台差异]] §三 6.0 vs 6.1），
+**cpp-lib 的功能验证改用 HAP 载体**：NAPI 壳 dlopen `.so`、逐功能点 `OH_LOG` 独立行、`v3 OK` 完成标记 +
+截图——全部 PRD 功能点真跑通过、独立验收 confidence=high。验证顺序建议：**HAP 载体先保核心
+功能绿，CLI 载体再补原库全量回归**。
+
+## 6. 原库单元测试套件设备跑的「执行器环境注入清单」
+
+私有 HNP 里跑原库自带单元测试套件（核心模块 900+ 测试实证），`run_cmd` 子进程除 `LD_LIBRARY_PATH` 外还需：
+1. **PATH 前置 HNP bin**——进程类测试用 `execvp("TestApp")` 按名找 helper，`TestApp` 须随 HNP 分发且带 0667 执行位；
+2. **HOME=cwd**——进程运行类测试写 `$HOME/.local` pid 文件，真实 HOME 只读；
+3. **测试数据查找分两族，别一套 `pkg/<module>/testsuite/data` 布局通吃**——① env 锚定族：测试用环境变量前缀找数据（`POCO_BASE`/`TEST_DATA` 等，Poco 的 JSON/Crypto/Zip 走 `POCO_BASE + "/<module>/testsuite/data/"`），随包落到 `pkg/<module>/testsuite/data/` 即够；② cwd 相对上溯族：测试从 cwd 向上搜目录名、或裸 `open("testdata.txt")`（Poco `SharedMemoryTest::findDataFile` 用 `Path::find(cwd, "data")`，quiche 的 `examples/cert.crt` 同理），而执行器 cwd 是应用沙箱 filesDir、**不是** HNP 根——光放 `pkg/` 下够不到，必须主动把 `data/`（或该相对路径）拷进 cwd 上溯路径（即「bin/data/testdata.txt 拷到 cwd/data」）。判别法：grep 测试源码 `findDataFile`/`Path::find(`/裸 `open(`，带环境变量前缀→①、不带→②。poco 实证：testdata.txt 只打进 `pkg/Foundation/testsuite/data/`，② 族 `SharedMemoryTest::testCreateFromFile` 仍报 FileNotFoundException；
+4. **别把 `libNonExistentLibrary.so` 这类故意的坏依赖桩打进包**——会让依赖探测类测试误判依赖齐全；
+5. **单元测试 runner 显式传 `-all`** 才跑全量。
+
+首轮 20+ 失败全部由此类环境问题构成，逐项注入后收敛到 0——**批量失败先怀疑环境注入而非库真坏**。
+
+## 7. TLS 回环测试失败：先查库的服务端 TLS 是不是空桩，别归因平台
+
+症状：`SSL_connect`/`SSL_accept` 握手失败、`SSL_ERROR_SSL` 且**错误队列空**（hilog 只见
+`unexpected eof while reading`）。此时**别判「平台 TLS 缺陷」**——鸿蒙上 OpenSSL 系 TLS 本身
+可用（内存握手双向收发实证，见 [[鸿蒙PC-OpenSSL系密码库交叉编译]] §2）。某 C++ 消息库的实锤
+根因是**上游根本没实现服务端 TLS**：其 OpenSSL 服务端 SocketFactory 的 `createServerSocket()`
+全部重载 `return NULL`（上游源码实物可查），客户端 `SSL_connect` 等对空桩发起握手才出现上述症状。
+
+**处置**：TLS 回环测试不能依赖库的服务端 TLS 接口——服务端改用 raw POSIX socket + raw OpenSSL
+`SSL_accept`（自签证书，同上 §2 手法），客户端仍走库的 TLS 路径。通用判定序：TLS 握手失败 →
+先查库的服务端实现是否空桩 → 再做内存握手对照实验，两步都排除后才谈平台。
+
+## 8. hvigor 清空 demo 工程 build 目录
+
+`hvigor assembleApp` 把 `<demo>/build/` 当输出目录**每次先清空**——放 `test-demo/build/*.sh` 的自定义脚本
+会被静默删（多轮适配先后撞上）。自定义构建脚本一律放工作区 `build/`，脚本内用绝对路径指 DEMO_DIR；
+msys bash 里跑 hvigor 还需手动 `export NODE_HOME`、PATH 加 `$SDK/../jbr/bin`（PackageHap 调 java，
+缺了报 spawn java ENOENT）与 toolchains。
+
+## 相关
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— seccomp 黑名单 + 诊断套路（关卡⑤/⑥）。
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— 私有 HNP 打包执行位 / 版本差异。
+- [[鸿蒙PC-OpenSSL系密码库交叉编译]]、`pc-registry` —— OpenSSL 依赖的自编配方 vs 中心仓复用。