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

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

@@ -0,0 +1,39 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E209: autogen.sh 运行时 libtoolize 无法正确复制 ltmain.sh 到源码目录
+
+> **严重度**: 🟡 medium | **分类**: build-system | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+autogen\.sh.*required file.*ltmain\.sh.*not found
+libtoolize.*ltmain\.sh
+```
+
+## 根因
+
+autogen.sh 运行时 libtoolize 无法正确复制 ltmain.sh 到源码目录，可能是因为目录结构不匹配或 libtool 版本问题
+
+## 验证命令
+
+```bash
+ls -la ltmain.sh && test -x configure
+```
+
+## 解决方案
+
+**manual-workaround**：手动复制 libtool 的 ltmain.sh 文件到源码目录根目录，然后重新运行 autogen.sh
+
+```bash
+cp $HOME/usr/local/share/libtool/build-aux/ltmain.sh . && ./autogen.sh
+```
+
+## 涉及软件
+
+autotools 项目，尤其是使用 AC_PROG_LIBTOOL 的旧版本 configure.ac
+
+---
+*条目 E209 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E210: mimalloc 的 MI_OVERRIDE 选项尝试覆盖系统 malloc/free
+
+> **严重度**: 🔴 blocking | **分类**: build-system | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Segmentation fault
+进程退出，代码 killed
+SIGKILL
+```
+
+## 根因
+
+mimalloc 的 MI_OVERRIDE 选项尝试覆盖系统 malloc/free，与鸿蒙系统的内存管理机制冲突，导致测试程序段错误
+
+## 验证命令
+
+```bash
+cd build && ./mimalloc-test-api
+```
+
+## 解决方案
+
+**add-cmake-flag**：在鸿蒙系统上使用 mimalloc 时，必须禁用 MI_OVERRIDE 选项，将其作为独立内存分配库使用，而非系统 malloc 替代品。启用 MI_LIBC_MUSL 选项以支持 musl libc 环境。
+
+```bash
+cmake -DCMAKE_BUILD_TYPE=Release -DMI_LIBC_MUSL=ON -DMI_OVERRIDE=OFF ..
+```
+
+## 涉及软件
+
+使用 mimalloc 的所有软件，在鸿蒙系统上编译时
+
+---
+*条目 E210 · 知识库同步生成物*

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

@@ -0,0 +1,44 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E211: musl libc 缺少 glibc 的 pthread affinity 扩展函数
+
+> **严重度**: 🟡 medium | **分类**: platform, compat | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undeclared identifier.*pthread_getaffinity_np
+undeclared identifier.*pthread_setaffinity_np
+did you mean.*sched_setaffinity
+```
+
+## 根因
+
+musl libc 缺少 glibc 的 pthread affinity 扩展函数,
+pthread_getaffinity_np / pthread_setaffinity_np 在 musl 中未实现,
+OpenHarmony 使用 musl libc 因此受影响
+
+## 验证命令
+
+```bash
+echo -e '#include <pthread.h>\nint main(){pthread_getaffinity_np(0,0,0);return 0;}' | clang -x c -c - -o /dev/null 2>&1
+```
+
+## 解决方案
+
+**replace-with-sched-api**：用 sched_getaffinity/sched_setaffinity 替代 pthread affinity 函数,
+sched_* 是标准 POSIX API, musl 完整实现, pid=0 表示当前线程/进程,
+需确保 cpu_set_t 类型通过 sched.h 可用
+
+```bash
+sed -i 's/pthread_getaffinity_np(/sched_getaffinity(0, /g; s/pthread_setaffinity_np(/sched_setaffinity(0, /g'
+```
+
+## 涉及软件
+
+使用 pthread affinity API 的软件 (OpenImageDenoise, TBB, OpenMPI 等)
+
+---
+*条目 E211 · 更新 2026-07-01 · 知识库同步生成物*

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

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E212: hmmac 安全标签阻止从用户路径 dlopen .so 文件
+
+> **严重度**: 🟡 medium | **分类**: platform, limitation, ohos, toolchain, security | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+Error loading shared library.*\.so.*Permission denied
+Can't load.*\.so.*Permission denied
+dlopen.*Permission denied
+```
+
+## 根因
+
+OpenHarmony 的 hmmac (Harmony MAC) 安全模块根据文件所在路径分配安全标签。/data/service/hnp/ 下的文件获得 hnp_file 标签（通过 hmmac=inherit_parent），而用户可写路径（/storage/Users 为 hmdfs 标签，/data/storage/el2/base 为 hishell_hap_data_file 标签）获得不同标签。Perl/Python 进程运行在 hnp_file 安全上下文中，hmmac 策略仅允许加载 hnp_file 标签的 .so 文件。用户无权写入 /data/service/hnp/（属主 installs:installs），导致编译产物无法被 dlopen 加载。注：perl-dbd-pg 3.18.0 (2026-06-10) 已记录此问题，当时称为 "SELinux HMDFS 限制"，本次通过 ls -Z 安全标签分析确认根因更精确地为 hmmac 安全标签。
+
+## 验证命令
+
+```bash
+ls -Z <so_path> → 检查标签是否为 u:object_r:hnp_file:s0；若不是则 dlopen 会失败
+```
+
+## 解决方案
+
+**install-to-hnp-path**：通过 hnp 包管理器或 cmd-pkgs 将 .so 安装到 /data/service/hnp/ 路径，获得 hnp_file 安全标签
+
+```bash
+# 需通过系统包管理器安装，非用户可自行操作
+```
+
+## 回退方案
+
+**verify-elf-only**：无法安装到 hnp 路径时，仅做 ELF 技术验证（file/readelf/nm），记录平台限制，不阻塞编译流程
+
+```bash
+file <so_path> && llvm-readelf -d <so_path> && llvm-nm -D <so_path>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`chmod 777|chmod a\+rwx.*\.so`
+- **原因**：权限问题不是 Unix 文件权限导致的，而是 hmmac 安全标签限制。chmod 无法改变安全标签。
+- **后果**：chmod 无效，dlopen 仍然失败，且降低系统安全性
+
+### 🚫 禁止 2
+
+- **模式**：`chcon|setfattr.*security\.hmmac`
+- **原因**：普通用户无权修改 hmmac 安全标签（Operation not permitted）
+- **后果**：操作失败，浪费排障时间
+
+## 涉及软件
+
+所有需要 dlopen 加载 .so 的 Perl XS 模块、Python C 扩展、JNI 库等，当 .so 位于用户可写路径时
+
+## 相关模式
+
+- **相似模式**：[E131](E131.md)、[E083](E083.md)
+
+---
+*条目 E212 · 更新 2026-07-14 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E213: l64a() missing in OHOS libc (musl)
+
+> **严重度**: 🟡 medium | **分类**: api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined reference to .l64a.
+cannot find -l.*l64a
+```
+
+## 根因
+
+OHOS libc (musl) does not provide l64a() function, which converts a long value to a radix-64 string
+
+## 验证命令
+
+```bash
+echo "int main(){return (int)(long)l64a(0L);}" | clang -x c - -o /dev/null 2>&1 | grep l64a
+```
+
+## 解决方案
+
+**implement-locally**：Implement l64a() in a project source file and add extern declaration before usage to prevent implicit int return on aarch64
+
+```bash
+# Add to misc.c: char *l64a(long value) { static char buf[7]; ... } and add extern char *l64a(long); in calling file
+```
+
+## 回退方案
+
+**stub-function**：Provide a stub that returns a constant string if full implementation is not needed
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`implicit.*l64a`
+- **原因**：Without extern declaration, compiler assumes int return, causing pointer truncation on aarch64
+- **后果**：Segfault at runtime due to truncated pointer
+
+## 涉及软件
+
+Software that calls l64a() directly or via libraries (e.g. bitwise)
+
+## 相关模式
+
+- **相似模式**：[E085](E085.md)
+
+---
+*条目 E213 · 更新 2026-07-14 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E214: Shell 脚本交互式 read 阻塞非交互式执行
+
+> **严重度**: 🟡 medium | **分类**: shell | **自动修复**: ❌ | **原则**: [P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+read -r void
+Press ENTER to continue
+Security check failed
+hangs indefinitely
+timeout kills
+```
+
+## 根因
+
+Shell 脚本工具（如安全审计工具 lynis）在初始化阶段有交互式安全检查，使用 `read -r var` 等待用户按 ENTER 确认。在非交互环境（conan test_package、CI、L2 smoke test）中，stdin 没有输入，`read` 会永久阻塞，直到被超时机制杀死。常见于安全审计工具（lynis, rkhunter, chkrootkit 等）有交互式安全确认提示。
+
+## 验证命令
+
+```bash
+timeout 10 ./script.sh --version && echo "PASS" || echo "FAIL"
+```
+
+## 解决方案
+
+**non-blocking-read**：三种方案（任选其一，推荐组合方案1+2）：1. 非阻塞 read: `read -r var < /dev/null 2>/dev/null || true`；2. 早期参数处理: `for arg in "$@"; do case "$arg" in --version|-V) echo "$VERSION"; exit 0;; esac; done`；3. 终端检测: `[ -t 0 ] && read -r var || true`
+
+```bash
+sed -i 's/read -r void/read -r void < \/dev\/null 2>\/dev\/null || true/' script.sh
+```
+
+## 回退方案
+
+**early-exit**：在交互检查之前添加 --version 等参数的早期处理，直接退出避免触发交互逻辑
+
+```bash
+for arg in "$@"; do case "$arg" in --version|-V) echo "$VERSION"; exit 0;; esac; done
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`timeout.*--version.*\|\|.*echo.*FAIL`
+- **原因**：仅用 timeout 绕过不解决根因，脚本仍会阻塞等待 stdin
+- **后果**：CI 超时资源浪费，其他调用路径仍会阻塞
+
+## 涉及软件
+
+任何有交互式提示（read 命令等待用户输入）的 shell 脚本工具。已知影响: lynis 3.1.7, 可能影响 rkhunter, chkrootkit 等。
+
+## 相关模式
+
+- **相似模式**：[E165](E165.md)
+
+---
+*条目 E214 · 更新 2026-07-14 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E215: LuaRocks 3.13.0 targeting Lua 5.5 needs Path B test-dependency handling
+
+> **严重度**: 🟡 medium | **分类**: lua, packaging, testing, relocatable | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+luacov 0.15.0-1
+lua >= 5.1, < 5.5
+os.tmpname()
+unable to generate a unique filename
+luarocks command not found
+```
+
+## 根因
+
+LuaRocks 3.13.0 supports --lua-version=5.5, but its upstream Busted test harness depends on luacov 0.15.0-1, whose rockspec declares lua >= 5.1, < 5.5. This makes the upstream test dependency incompatible with a lua/5.5.0 target, so Path A cannot be claimed even when the packaged commands build and run.
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 --build=missing
+```
+
+## 解决方案
+
+**path-b-with-consumer-validation**：Use Path B, record upstream inventory and luacov dependency-range failure, keep test_package separate from upstream tests, execute packaged luarocks commands by absolute path, and cover positive smoke plus deterministic fault injection.
+
+```bash
+python test_package/test_luarocks55.py <package>/bin/luarocks <package>/bin/luarocks-admin
+```
+
+## 回退方案
+
+**launcher-and-tempdir-hardening**：Make luarocks launchers relocatable from arg[0] and patch packaged util.lua to prefer TMPDIR/TMP/TEMP before os.tmpname() on OHOS workers.
+
+```bash
+set TMPDIR to a writable path and rerun luarocks --version, config lua_version, help install, invalid command, and invalid rockspec lint checks
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`count test_package as upstream Busted tests`
+- **原因**：Consumer checks prove packaged artifact behavior but do not satisfy upstream Path A accounting.
+- **后果**：PR evidence becomes misleading and can be rejected for false upstream-test pass rate.
+
+## 涉及软件
+
+LuaRocks packages targeting Lua 5.5, especially Conan recipes that must distinguish upstream Busted test accounting from consumer test_package validation.
+
+---
+*条目 E215 · 更新 2026-08-05 · 知识库同步生成物*

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

@@ -0,0 +1,69 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E216: glib/libxml2 CMakeDeps 组件头文件传播失效
+
+> **严重度**: 🟢 minor | **分类**: cmake, cross-compile, conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+glib.h: No such file or directory
+libxml/xmlversion.h: No such file
+list sub-command LENGTH requires two arguments
+Unknown arguments specified
+```
+
+## 根因
+
+Conan 2.29 + glib 2.84.0/libxml2 2.15.3 的 CMakeDeps 生成文件不传播 components 的 INTERFACE_INCLUDE_DIRECTORIES。team ohpcd glib recipe 不使用 components 子目标而是 flat cpp_info.libs,生成的 CMake target 是 aggregate glib::glib。libxml2 recipe 设置 cmake_file_name="LibXml2" 大小写敏感。
+
+## 验证命令
+
+```bash
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake && cmake --build build
+```
+
+## 解决方案
+
+**glob-fallback-with-empty-guard**：test_package/CMakeLists.txt 中显式 file(GLOB) 找 conan cache 中的 glib.h / glibconfig.h / libxml2 xmlversion.h,匹配 p/b/<pkg>/b/... 和 p/<pkg>/p/... 双布局。foreach 循环体内通过 `set(_VAL "${${_var}}")` 将变量值捕获到临时普通变量,后续操作 `_VAL` 避免 semicolon 在 list() / get_filename_component() 参数中被误解析为分隔符。空 GLOB 守卫: if(_VAL STREQUAL "") continue(),多匹配检测:string(FIND) + FATAL_ERROR。
+
+```bash
+foreach(_var IN ITEMS _GLIB_H_FILES ...) set(_VAL "${${_var}}") if(_VAL STREQUAL "") continue() endif() string(FIND "${_VAL}" ";" _SEMI_POS) if(_SEMI_POS GREATER_EQUAL 0) message(FATAL_ERROR ...) endif() get_filename_component(_DIR "${_VAL}" DIRECTORY)
+```
+
+## 回退方案
+
+**explicit-link-aggregate-target**：显式 target_link_libraries(test_pidgin pidgin::pidgin glib::glib LibXml2::LibXml2) 一次性 link aggregate target,依赖 cmake_file_name / cmake_target_name 正确传递
+
+```bash
+target_link_libraries(test_pidgin pidgin::pidgin glib::glib LibXml2::LibXml2)
+```
+
+**hardcode-sysroot-paths**：直接硬编码 sysroot include 路径,在 cross_building() 块内 set CONAN_INCLUDE_GLIB 等环境变量
+
+```bash
+target_include_directories(test_pidgin PRIVATE /opt/sysroot/include/glib-2.0)
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`list\(\s*(LENGTH|GET|JOIN)\s+\$\{\{\$?\$?_\w+\}?\}\s`
+- **原因**：CMake list(LENGTH/GET/JOIN) 的 <list> 参数是变量名,CMake 内部自动解引用。正确写法:foreach 循环体内用 `set(_VAL "${${_var}}")` 将变量值捕获到临时普通变量后再操作。错误写法:直接在 list() 参数里写 `${${_var}}` —— 双解引用展开后变量值为含分号的路径字符串(如 "/path1;/path2"),分号被 CMake 解析为参数分隔符,导致 `Unknown arguments specified` 错误
+- **后果**：CMake configure 失败,报错 "list sub-command LENGTH requires exactly two arguments" 或 "Unknown arguments specified";GLOB 兜底完全无法运行,链接阶段报 glib.h 找不到
+
+### 🚫 禁止 2
+
+- **模式**：`file\(GLOB.*libxml2\*`
+- **原因**：conan on-disk 用前 5 字符 prefix,libxml2 的 prefix 是 libxm 不是 libxml2
+- **后果**：GLOB 永远返回 0 匹配,空 GLOB 崩溃 configure
+
+## 涉及软件
+
+任何使用 glib/libxml2 作为 conan 依赖且交叉编译到 aarch64 (OHOS) 的 test_package/consumer
+
+---
+*条目 E216 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,45 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E217: 上游 CMake 用 install(FILES ${c_headers} DESTINATION include/${…
+
+> **严重度**: 🟡 medium | **分类**: headers, cmake, conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+fatal error: '.+\.h' file not found
+test_package.*\.c:\d+:\d+: fatal error
+```
+
+## 根因
+
+上游 CMake 用 install(FILES ${c_headers} DESTINATION include/${PROJECT_NAME}) 把头文件
+装进 include/<subdir>，但 conan-init 生成的模板配方 package_info() 默认 includedirs=["include"]，
+test_package 的 #include <xxx.h> 找不到头文件，G2 在 test_package 阶段失败。
+知识图谱仅匹配到 E001（找不到编译器），根因完全不同，属误匹配。
+
+## 验证命令
+
+```bash
+grep -rn "DESTINATION include" <src>/CMakeLists.txt && 检查 package_info includedirs 是否匹配
+```
+
+## 解决方案
+
+**check-cmake-header-install-subdir**：先读上游 CMakeLists 确认 install(FILES ... DESTINATION) 目标目录，再把
+package_info() 的 cpp_info.includedirs 指向实际子目录（如 ["include/libairspyhf"]），
+与上游工具源码的 #include <airspyhf.h> 保持一致
+
+```bash
+grep -rn "DESTINATION include" <src>/CMakeLists.txt && 修改 conanfile.py package_info() includedirs
+```
+
+## 涉及软件
+
+所有 CMake 工程头文件安装到 include/<subdir>（如 include/libairspyhf、include/libusb-1.0）
+且 test_package 以顶层 <subdir>/../ 形式 include 的场景
+
+---
+*条目 E217 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,65 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E218: CastXML 二进制同时 NEED libLLVM-15.so 和 libclang-cpp.so
+
+> **严重度**: 🟡 medium | **分类**: llvm, linking, runtime | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)
+
+---
+
+## 错误特征
+
+```
+CommandLine Error: Option '.*' registered more than once!
+LLVM ERROR: inconsistency in registered CommandLine options
+libLLVM-15.*libclang-cpp.*NEEDED
+mc-relax-all
+```
+
+## 根因
+
+CastXML 二进制同时 NEED libLLVM-15.so 和 libclang-cpp.so。
+OHOS SDK LLVM 是 LLVM_ENABLE_SHARED_LIBS=ON 构建，libLLVM-15.so 和 libclang-cpp.so
+各为独立 monolith，各自拥有完整的 LLVM CommandLine option 注册循环。
+当 binary 同时 dlopen 两库时，mc-relax-all 等 option 被注册两次，
+触发 LLVM ERROR: inconsistency in registered CommandLine options，
+导致进程以 exit 134 崩溃，所有 3919 个 CTest 失败。
+
+## 验证命令
+
+```bash
+readelf -d castxml | grep NEEDED; readelf -d libclang-cpp.so | grep NEEDED; castxml --version; ctest --output-on-failure
+```
+
+## 解决方案
+
+**link-only-clang-cpp-monolith**：只链接 libclang-cpp.so（OHOS SDK 的 clang monolith 已包含全部 LLVM 符号），
+移除对 libLLVM-15.so 的直接链接。具体步骤：
+1. patch CastXML 的 src/CMakeLists.txt：移除/注释 llvm_config(castxml ...) 调用
+2. patch castxml.cxx：移除 #include "llvm/Support/InitLLVM.h" 和
+   llvm::InitLLVM initLLVM(...) 实例化。OHOS 不需要 LLVM crash handler，
+   直接初始化 llvm::SmallVector(argv_in, argv_in + argc_in) 替代。
+3. 保持 CLANG_LINK_CLANG_DYLIB=ON，确保 binary 通过 clang-cpp target 链接 libclang-cpp.so。
+前提条件：libclang-cpp.so 必须是包含所有 LLVM 符号的 monolith。
+
+```bash
+# patches/0007-ohos-llvm-remove-llvm-config.patch + patches/0008-ohos-llvm-remove-initllvm.patch
+# 验证: readelf -d castxml | grep NEEDED (应只输出 libclang-cpp.so)
+# castxml --version (exit 0); ctest --output-on-failure (应全通过)
+```
+
+## 回退方案
+
+**static-link-llvm**：如果无法移除 libLLVM 依赖，则改为静态链接 LLVM 库以避免双 dylib 冲突。
+
+```bash
+设置 LLVM_LINK_LLVM_DYLIB=OFF 后重新构建
+```
+
+## 涉及软件
+
+OHOS SDK LLVM/Clang shared library (monolith) 场景下，任何依赖 Clang/LLVM
+CMake config 且出现 CommandLine Error: Option registered more than once
+的工具类项目。核心条件是 libclang-cpp.so 为包含全部 LLVM 符号的自包含 monolith。
+
+---
+*条目 E218 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,50 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E219: CI buildenv 下勿将非 HNP python 作为 conan create 硬门禁
+
+> **严重度**: 🟡 medium | **分类**: platform, limitation, ohos, toolchain, python | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+OHOS: no non-sandbox python3 found
+inaccessible or not found
+/data/app/bin/python3
+```
+
+## 根因
+
+〈外部知识库流水线〉 的 [buildenv] 将 /data/service/hnp/bin 置于 PATH 首位。
+conan create 内使用 HNP python 做 pip 是预期行为。HNP 进程因 hmmac(E212) 无法
+dlopen 用户路径 .so；同时 /data/app/bin/python3 在 create 沙箱中常 inaccessible。
+将「必须找到非 HNP python」写成 required=True 会导致 CI 在签名/测试前失败，
+而早期无该门禁时 pip+package 本可成功（仅 test 阶段遇 E077/E212）。
+
+## 验证命令
+
+```bash
+对照 nanobind test_package E212 fallback；对照 bpytop 签名但不硬门禁 python
+```
+
+## 解决方案
+
+**e212-verify-elf-fallback**：pip 可用任意 python（含 HNP）；E077 签名 + 可选 ctypes preload；live import/CLI 失败且命中 E212 时 ELF 静态校验通过即可，对齐 nanobind
+
+```bash
+# build: python3 -m pip ...（buildenv HNP OK）
+# sign: llvm-objcopy --remove-section .codesign; binary-sign-tool sign -selfSign 1
+# test: try CLI; on Permission denied → llvm-readelf -d rpds*.so
+```
+
+## 涉及软件
+
+依赖原生扩展的纯 Python Conan 包（rpds/pyyaml 等）
+
+## 相关模式
+
+- **相似模式**：[E212](E212.md)、[E077](E077.md)、[E179](E179.md)
+
+---
+*条目 E219 · 更新 2026-08-03 · 知识库同步生成物*