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

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E494: lld --gc-sections 裁剪 __start_/__stop_ 封装符号导致链接失败
+
+> **严重度**: 🟡 medium | **分类**: linking, gc-sections, lld | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined symbol: __start___debug
+undefined symbol: __stop___debug
+__start___debug.*gc-sections
+```
+
+## 根因
+
+lld 15 的 --gc-sections 会裁剪 __start_/__stop_ 封装符号, 导致引用这些符号的代码链接失败
+
+## 验证命令
+
+```bash
+grep -rn "gc-sections" Makefile | head -1; ld.lld --version
+```
+
+## 解决方案
+
+**LDFLAGS 增加 -Wl,-z,nostart-stop-gc**：在链接参数中增加 -z nostart-stop-gc, 保留 __start_/__stop_ 封装符号
+
+```bash
+make LDFLAGS="-Wl,--gc-sections -Wl,-z,nostart-stop-gc"
+```
+
+## 涉及软件
+
+使用 lld 15 链接且开启 --gc-sections 的 autotools/cmake 项目 (bluez 5.79 等)
+
+---
+*条目 E494 · 更新 2026-08-12 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E495: Qt 6 模块 CMake 构建报 "You need to set QT_HOST_PATH to cross compile Qt"
+
+> **严重度**: 🟡 medium | **分类**: cmake, cross-compile, qt-module, qt6 | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+You need to set QT_HOST_PATH to cross compile Qt
+```
+
+## 根因
+
+Qt 6 模块用 CMake 构建时检测到交叉编译（CMAKE_SYSTEM_NAME 已设置），要求 QT_HOST_PATH 指向含 moc/rcc 等 host 工具的 Qt 安装前缀
+
+## 验证命令
+
+```bash
+cmake -S . -B build -DCMAKE_SYSTEM_NAME=OHOS 2>&1 | grep 'QT_HOST_PATH'
+```
+
+## 解决方案
+
+**本机同架构（如 OHOS aarch64 host=target）时设 QT_HOST_PATH=qtbase 前缀；conan 配方中改用 CMAKE_PREFIX_PATH 指向 qtbase 包 + QT_QMAKE_TARGET_MKSPEC=harmonyos-clang 即可，无需 QT_HOST_PATH**：本机同架构编译设 QT_HOST_PATH；conan 配方用 CMAKE_PREFIX_PATH+harmonyos-clang mkspec 规避
+
+```bash
+cmake -S . -B build -DCMAKE_PREFIX_PATH=${QTPFX} -DQT_HOST_PATH=${QTPFX} -DQT_QMAKE_TARGET_MKSPEC=harmonyos-clang
+```
+
+## 涉及软件
+
+cmake|qt6|qt-module
+
+---
+*条目 E495 · 更新 2026-08-15 · 知识库同步生成物*

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

@@ -0,0 +1,39 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E496: OHOS 沙箱 setsockopt(SO_PRIORITY) 返回 EPERM 被误判为致命错误
+
+> **严重度**: 🟡 medium | **分类**: socket, linking, permissions | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+setsockopt\(.*SO_PRIORITY.*Operation not permitted
+Operation not permitted.*SO_PRIORITY
+```
+
+## 根因
+
+OHOS 沙箱无 CAP_NET_ADMIN 权限, SO_PRIORITY setsockopt 返回 EPERM; 若代码将其视为致命错误会导致连接/会话建立失败
+
+## 验证命令
+
+```bash
+grep -rn SO_PRIORITY android/avdtp.c | head -1
+```
+
+## 解决方案
+
+**setsockopt 调用对 EPERM/EACCES 视为尽力而为(不致命), 与 ENOTSOCK 同等处理**：setsockopt 调用对 EPERM/EACCES 视为尽力而为(不致命), 与 ENOTSOCK 同等处理
+
+```bash
+可选: 具体命令模板(${VAR}变量引用)
+```
+
+## 涉及软件
+
+OHOS 沙箱无 CAP_NET_ADMIN 的软件 (avdtp 类 socket 优先级设置)
+
+---
+*条目 E496 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,65 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E497: Keep Git metadata on a native filesystem for HMDFS worktrees
+
+> **严重度**: 🟡 medium | **分类**: git-filesystem-compat | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+fatal: cannot stat '<HMDFS worktree>/.git/branches'
+fatal: detected dubious ownership in repository
+```
+
+## 根因
+
+Process-local safe.directory configuration resolves only Git's ownership guard. A Git metadata directory created directly under an HMDFS /storage worktree can still fail native metadata probes such as stat of .git/branches. Git maintenance may also fail on the same filesystem. The worktree content and Git metadata therefore need separate filesystem placements.
+
+## 验证命令
+
+```bash
+Initialize the /storage worktree with a task-private --separate-git-dir path under native /data, commit the frozen snapshot, run git status and rev-parse, require empty stderr with maintenance.auto=false and gc.auto=0, then remove both task-private directories.
+```
+
+## 解决方案
+
+**native-separate-git-dir**：Set safe.directory for the exact worktree through process-local GIT_CONFIG_COUNT variables, initialize the worktree with git init --separate-git-dir=<task-private native /data path> <HMDFS worktree>, then disable automatic maintenance and garbage collection in that repository before staging and committing the frozen snapshot.
+
+```bash
+GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=safe.directory GIT_CONFIG_VALUE_0=<worktree> git init --separate-git-dir=<native-data-gitdir> <worktree>; git config maintenance.auto false; git config gc.auto 0
+```
+
+## 回退方案
+
+**native-complete-worktree**：If worktree indirection is not supported by the installed Git, place both the task-private worktree and metadata on a verified native filesystem and copy only the immutable inputs from HMDFS.
+
+```bash
+create a new native task root and revalidate the complete input manifest before the first launch
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`git config --global.*safe.directory|safe.directory[ =]*\*`
+- **原因**：A global or wildcard ownership exception mutates shared user state and grants broader trust than the task requires.
+- **后果**：Unrelated repositories become trusted and later tasks inherit an unbound security relaxation.
+
+### 🚫 禁止 2
+
+- **模式**：`git init .*\/storage.*&&.*ignore.*cannot stat|mkdir .*\.git\/branches`
+- **原因**：Manually creating a missing metadata subdirectory does not repair unsupported Git metadata semantics on HMDFS.
+- **后果**：Later index, ref, lock, maintenance, or object operations can fail after the workflow has already started.
+
+## 涉及软件
+
+OpenHarmony device workflows that need a real Git worktree under /storage while the HMDFS mount cannot reliably host Git's metadata directory.
+
+## 相关模式
+
+- **相似模式**：[E101](E101.md)
+
+---
+*条目 E497 · 更新 2026-08-20 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E498: Clear Conan's default include directory for a headerless library
+
+> **严重度**: 🔴 blocking | **分类**: cmake, conan, packaging, api, headerless-library | **自动修复**: ❌ | **原则**: [P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+imported target.*non-existent.*include
+INTERFACE_INCLUDE_DIRECTORIES.*does not exist
+CMakeDeps.*include.*does not exist
+```
+
+## 根因
+
+Conan defaults cpp_info.includedirs to include even when a package intentionally installs no public headers, so CMakeDeps exports a usage requirement for a directory that does not exist.
+
+## 验证命令
+
+```bash
+Configure, compile, link, and run a consumer that uses only the generated imported target; require no hard-coded include or library paths and no nonexistent include-directory diagnostic.
+```
+
+## 解决方案
+
+**explicit-empty-public-include-contract**：Set self.cpp_info.includedirs to an empty list while preserving the real public libraries, transitive requirements, target names, and system libraries.
+
+```bash
+Add self.cpp_info.includedirs = [] in package_info() and rerun a CMakeDeps imported-target consumer.
+```
+
+## 回退方案
+
+**install-missing-public-headers**：If the library actually has a public header API, install the missing headers and keep a real include directory instead of clearing metadata.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`target_include_directories.*package_folder|include_directories.*\.conan|CMAKE_PREFIX_PATH.*include`
+- **原因**：Consumer-side hard-coded paths bypass the generated package contract.
+- **后果**：The test can pass while downstream CMakeDeps consumers still fail.
+
+### 🚫 禁止 2
+
+- **模式**：`includedirs.*\[\].*public headers installed`
+- **原因**：Clearing include metadata is valid only for a genuinely headerless public contract.
+- **后果**：Real header consumers lose their required usage path.
+
+## 涉及软件
+
+Conan library recipes that install linkable libraries and metadata but intentionally expose no public headers.
+
+## 相关模式
+
+- **相似模式**：[E221](E221.md)
+
+---
+*条目 E498 · 更新 2026-08-19 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E499: Conan shared-package consumers need explicit transitive runtime libdirs
+
+> **严重度**: 🟡 medium | **分类**: conan, runtime, environment, shared-library | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+Error loading shared library libminizip\.so\.1
+Error 127 while executing
+```
+
+## 根因
+
+A shared Conan package can link successfully while its direct test consumer fails at execution because VirtualRunEnv does not infer every transitive dependency libdir from cpp_info.requires. The package export must propagate dependency libdirs through runenv_info, otherwise a runtime dependency such as minizip is absent from LD_LIBRARY_PATH even though the producer linked against it.
+
+## 验证命令
+
+```bash
+For isolated verification, remove consumer-side libdir reconstruction, run the unchanged consumer under env="conanrun", require the exact loader error before the producer fix, then require the complete upstream suite plus consumer assertions with generated LD_LIBRARY_PATH entries. If the consumer also reconstructs dependency libdirs, report only a combined runtime-closure PASS.
+```
+
+## 解决方案
+
+**export-transitive-runtime-libdirs**：In package_info(), iterate direct dependency cpp_info.libdirs and prepend each directory to self.runenv_info LD_LIBRARY_PATH. Keep cpp_info.requires for link metadata. Distinguish isolated producer-environment verification from a combined closure where test_package also reconstructs dependency libdirs.
+
+```bash
+for _ref, dependency in self.dependencies.items(): for libdir in dependency.cpp_info.libdirs: self.runenv_info.prepend_path("LD_LIBRARY_PATH", libdir)
+```
+
+## 回退方案
+
+**explicit-consumer-runtime-requirements**：Add every runtime dependency explicitly to test_package requirements only when package-level runenv propagation cannot be changed; this is narrower and should not replace the producer runenv contract.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`remove.*minizip|skip.*runtime|ignore.*Error 127|test.*NOT_RUN`
+- **原因**：Suppressing a missing runtime library or skipping the consumer hides a real shared-link closure defect.
+- **后果**：The package can pass link-time checks while direct consumers fail on a clean target.
+
+### 🚫 禁止 2
+
+- **模式**：`__OHOS__|OHOS.*ifdef|HarmonyOS.*ifdef`
+- **原因**：Runtime environment propagation is a Conan package contract and must not fork upstream source with platform macros.
+- **后果**：Conditional source changes obscure the dependency closure and violate the source portability boundary.
+
+## 涉及软件
+
+Conan 2 shared-library recipes whose package_info() declares cpp_info.requires and whose test_package executes a consumer through VirtualRunEnv.
+
+---
+*条目 E499 · 更新 2026-08-22 · 知识库同步生成物*

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

@@ -0,0 +1,39 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E500: OHOS musl libc 无 glibc MAX_INPUT 宏导致编译失败
+
+> **严重度**: 🟡 medium | **分类**: compat, libc, headers | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+use of undeclared identifier 'MAX_INPUT'
+MAX_INPUT.*undeclared
+```
+
+## 根因
+
+OHOS musl libc 无 glibc 的 MAX_INPUT 宏; 需用 _POSIX_MAX_INPUT 兼容定义
+
+## 验证命令
+
+```bash
+grep -rn MAX_INPUT gdbus/object.c | head -1
+```
+
+## 解决方案
+
+**源文件加 #ifndef MAX_INPUT #define MAX_INPUT _POSIX_MAX_INPUT #endif**：源文件加 #ifndef MAX_INPUT #define MAX_INPUT _POSIX_MAX_INPUT #endif
+
+```bash
+可选: 具体命令模板(${VAR}变量引用)
+```
+
+## 涉及软件
+
+OHOS/musl libc 上使用 glibc MAX_INPUT 宏的软件 (bluez/gdbus 等)
+
+---
+*条目 E500 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E501: Makefile-only C libraries need direct Conan build and linker runtime env on OHOS runners
+
+> **严重度**: 🟡 medium | **分类**: toolchain, conan, runner | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+make: inaccessible or not found
+cmake: inaccessible or not found
+Error loading shared library libxml2.so.16
+Error relocating .*lld: xml.* symbol not found
+```
+
+## 根因
+
+Some OHOS PR runners do not expose make/cmake to Conan subprocesses, and OHOS SDK lld may require the SDK llvm/lib directory in LD_LIBRARY_PATH for libxml2 runtime symbols.
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=lua/*
+```
+
+## 解决方案
+
+**direct-compile-source-list-and-wrap-link-env**：Mirror the upstream Makefile source list in the Conan recipe, compile with the profile compiler, archive with llvm-ar/llvm-ranlib, run the upstream smoke test from the build tree, and prepend OHOS SDK ohos/native/llvm/lib to LD_LIBRARY_PATH around link commands.
+
+```bash
+use conan.tools.env.Environment().prepend_path("LD_LIBRARY_PATH", sdk_llvm_lib) with vars(self).apply() around clang link commands
+```
+
+## 回退方案
+
+**package-library-surface-only**：If CI generic CLI smoke probes do not match upstream command semantics and downstream only needs the library, package include/lib/man/license and leave CLI binaries uninstalled.
+
+```bash
+set cpp_info.bindirs=[] and validate include/lua.h plus lib/liblua.a in package()
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`self\\.run\\(.*env=\\{.*\\}`
+- **原因**：Conan 2 self.run(env=...) expects generated env script names, not a raw Python dict.
+- **后果**：Recipe may fail before reaching the intended compiler/linker command.
+
+## 涉及软件
+
+Small C libraries with hand-written Makefiles where downstream consumers need headers/static libraries more than packaged CLI tools.
+
+## 相关模式
+
+- **相似模式**：[E011](E011.md)、[E132](E132.md)
+- **根因条目（应先修它们）**：[E132](E132.md)
+
+---
+*条目 E501 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E502: OHOS CI workers refuse dlopen and LD_PRELOAD of every user-directory shared object regardless of ELF signature while exec-time NEEDED loading still works
+
+> **严重度**: 🔴 blocking | **分类**: platform, limitation, ohos, musl, security | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library /[^:]+: Permission denied
+\(needed by
+do_dlsym failed: Symbol not found.*so=/data/service/hnp
+```
+
+## 根因
+
+The worker loader policy applies to any shared object mapped after process start (dlopen, LD_PRELOAD) for files under user storage directories and rejects it with Permission denied whether the ELF carries a fresh build-time self-signature or the release signature downloaded from the artifact registry. The same freshly self-signed libraries load fine as DT_NEEDED of a process at exec time (verified: the isl C tests passed against the build-time-signed libgmp.so.10 copy resolved from LD_LIBRARY_PATH in build #33895). The interactive device environment is more permissive, so a local dlopen success does not transfer to workers and signature work alone cannot unblock the worker dlopen path.
+
+## 验证命令
+
+```bash
+Probe each candidate .so in its own ctypes.CDLL process and print one short line per verdict (file tail plus OSError message tail): self-signed private copy, release-signed published file, dlopen target; on a worker all three show Permission denied while binaries whose NEEDED chain includes the same freshly self-signed files execute normally.
+```
+
+## 解决方案
+
+**probe-then-route-to-exec-time**：Echo one structured short line per load attempt (never head-slice a multi-line traceback buffer) to localize which file and reason the loader reported, then route the required library into the process through the accepted exec-time path; for python ctypes tests use the embedded launcher pattern of E2167.
+
+```bash
+keep per-file probes line-structured and short (status, errno, last chars of the OSError message, one line per attempt); reference implementation _OHOS_DLOPEN_PROBE_SRC in 〈外部知识库归档〉
+```
+
+## 回退方案
+
+**escalate-platform-boundary**：When no accepted load path can host the test, report the boundary with the per-file probe matrix, worker ids and build numbers (R41/R43 evidence style) instead of skipping, stubbing or unconditional-pass shims.
+
+```bash
+collect the E135PROBE-style short lines from the CI console output and attach them to the PR comment or issue body
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`probe_output\[:[0-9]+\]|\[:[0-9]+\].*(stdout|stderr|traceback)`
+- **原因**：Head-slicing a multi-line diagnostic buffer drops the loader reason that rides at the end of the OSError line; thirteen CI rounds lost their forensics to the recipe's own [:400] cap (build #33806) before the probes were restructured.
+- **后果**：Repeated expensive CI rounds without ever learning which file or reason the loader reported.
+
+### 🚫 禁止 2
+
+- **模式**：`llvm-objcopy.*\.conan2|binary-sign-tool.*\.conan2`
+- **原因**：Conan cache package files are shared immutable inputs; stripping or rewriting .codesign there silently corrupts a release-signed binary and mimics an imaginary platform policy (a diagnostic objcopy aimed at the cache made libgmp.so.10.5.0 unloadable for hours and produced a false "signature expiry" conclusion).
+- **后果**：Cache-wide corruption misattributed to the platform; recover only via conan remove <pkg> -c and conan download <pkg> -r=<remote>.
+
+### 🚫 禁止 3
+
+- **模式**：`(skip|XFAIL|xfail).*dlopen|stub.*LoadLibrary`
+- **原因**：Skipping or stubbing the dlopen-based upstream test contradicts the path-A full-upstream-test requirement and hides the platform boundary instead of documenting it.
+- **后果**：Unverifiable test counts and a false-green archive that review and CI audits will reject.
+
+## 涉及软件
+
+Every upstream test that dlopen()s or LD_PRELOADs user-built shared libraries (ctypes/python bindings, plugin hosts, FFI suites) executed on CI workers.
+
+## 相关模式
+
+- **相似模式**：[E135](E135.md)、[E077](E077.md)
+
+---
+*条目 E502 · 更新 2026-08-28 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E503: CLI 工具无 --version/--help 长选项导致 L2 smoke test 失败
+
+> **严重度**: 🟡 medium | **分类**: smoke-test | **自动修复**: ❌ | **原则**: [P004](../principles.md#P004)
+
+---
+
+## 错误特征
+
+```
+unrecognized option
+invalid option --
+jshn
+```
+
+## 根因
+
+上游 CLI 工具仅实现 getopt 短选项，--version/--help 落入默认分支调用 usage() 并返回非 0（exit 2）
+
+## 验证命令
+
+```bash
+jshn --version && jshn --help; echo $?
+```
+
+## 解决方案
+
+**补丁在 main() 开头增加 --version/--help GNU 长选项处理并返回 0（libubox jshn 先例）**：main() 开头（getopt 循环前）拦截 --version/--help，打印版本/用法后 return 0
+
+```bash
+编辑 jshn.c 后: ohc-run.py track-edit add libubox 2026-06-19 jshn.c && ohc-run.py refresh-patch --auto libubox 2026-06-19
+```
+
+## 回退方案
+
+**在 getopt 循环的 default 分支对 argv[optind] 判断 --version/--help**：通过 getopt 处理后的剩余参数匹配长选项，改动更小但需注意 optind 语义
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`return usage\(argv\[0\]\)\s*;|exit\(2\)`
+- **原因**：--help 分支若直接返回 usage() 结果会以非 0 退出，L2 门禁仍失败
+- **后果**：L2 smoke test FAIL，conan-verify 无法通过
+
+## 涉及软件
+
+conan-verify L2 门禁对所有 bin/ 可执行文件运行 --version/--help，rc!=0 则判定失败
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)
+
+---
+*条目 E503 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E504: CMake install 期 RPATH_CHANGE 重写 .so 后 OHOS musl loader 无法加载
+
+> **严重度**: 🔴 blocking | **分类**: cmake, install | **自动修复**: ❌ | **原则**: [P004](../principles.md#P004)
+
+---
+
+## 错误特征
+
+```
+Error loading shared library
+RPATH_CHANGE
+Error in test() method
+Error 127 while executing
+```
+
+## 根因
+
+CMake install 期 RPATH_CHANGE 重写链接了依赖库的 .so，改写产物 OHOS musl loader 无法加载（即使 LD_LIBRARY_PATH 指向也失败）
+
+## 验证命令
+
+```bash
+cmp p/lib/libblobmsg_json.so b/build/Release/libblobmsg_json.so && LD_LIBRARY_PATH=p/lib ./test_bin
+```
+
+## 解决方案
+
+**conanfile.py generate() 设 CMAKE_SKIP_INSTALL_RPATH=TRUE，并在 package() 中用构建产物覆盖 install 产物（libubox 先例）**：跳过 install 期 RPATH 改写，package() 内用 build 目录原始 .so/jshn 覆盖安装产物，保证 loader 可加载
+
+```bash
+conanfile.py 中 generate() 加 tc.cache_variables["CMAKE_SKIP_INSTALL_RPATH"]="TRUE"；package() 中 shutil.copy2 覆盖
+```
+
+## 回退方案
+
+**不用 cmake.install()，手动将 build 产物拷贝到 package 目录**：完全绕过 CMake install 的 RPATH 处理，适用于 install 目标复杂无法覆盖的场景
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`NEW_RPATH\s+""`
+- **原因**：install 期把 RUNPATH 改为空会触发 .so 重写，产物 musl loader 无法加载
+- **后果**：conan create 构建成功但 test_package 运行时 Error 127，G2 门禁失败
+
+## 涉及软件
+
+所有链接了 conan 依赖（如 json-c）的 CMake 项目；仅依赖 libc 的 .so（如 libubox.so）不受影响
+
+## 相关模式
+
+- **相似模式**：[E092](E092.md)、[E074](E074.md)
+
+---
+*条目 E504 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E505: OHOS loader: LD_LIBRARY_PATH overrides DT_RPATH and symlinked soname aliases cannot resolve
+
+> **严重度**: 🟢 minor | **分类**: autotools, configure, dynamic-loading | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library [^:]+: \(needed by\)
+cannot run C compiled programs
+configure: error: cannot run C compiled programs
+Error loading shared library .*: Permission denied
+```
+
+## 根因
+
+OHOS 上 musl 加载器认 LD_LIBRARY_PATH，并且一旦该变量被设置，其查找会压过二进制内嵌的 DT_RPATH。依赖包安装的版本化别名（libfoo.so.1 -> libfoo.so.1.2.3）在 HMDFS 上无法由加载器经别名名解析，因此把 LD_LIBRARY_PATH 指向依赖包 lib 目录会让查找失败，即使 DT_RPATH 指向的实体化目录是可加载的。表现是 configure 报 cannot run C compiled programs（rc=77）或运行期 Error loading shared library X (needed by Y)，而 ls/lld 层面文件都存在。
+
+## 验证命令
+
+```bash
+clang -o probe probe.c -lfontconfig -L$VIEW -Wl,--disable-new-dtags -Wl,-rpath,$VIEW && env -u LD_LIBRARY_PATH ./probe; echo $?; LD_LIBRARY_PATH=$VIEW ./probe; echo $?
+```
+
+## 解决方案
+
+**materialised-signed-runtime-view**：在任务私有构建目录里为依赖共享库闭包建立实体化视图：按依赖 cpp_info.libdirs 遍历，resolve 符号链接后以真实文件名复制为普通文件（保留 owner 可执行位），然后只把该视图嵌入所构建二进制的 DT_RPATH（-Wl,--disable-new-dtags,-rpath,<view>）。不要为此导出全局 LD_LIBRARY_PATH：无论指向包目录还是视图目录都有害（包目录因符号链接别名解析失败，视图目录会毒化被继承的工具链子进程，见 forbid_2）。
+
+```bash
+mkdir -p $BUILD/runtime-libs && for e in $(ls $DEP/lib | grep -E '\.so(\.[0-9]+)*'); do cp -p $DEP/lib/$(readlink -f $DEP/lib/$e 2>/dev/null || echo $DEP/lib/$e) $BUILD/runtime-libs/$e; done; export LDFLAGS="$LDFLAGS -L$BUILD/runtime-libs -Wl,--disable-new-dtags -Wl,-rpath,$BUILD/runtime-libs"; unset LD_LIBRARY_PATH
+```
+
+## 回退方案
+
+**probe-without-ld-library-path**：先在不设 LD_LIBRARY_PATH、仅嵌 rpath 的条件下重跑同一个失败二进制，确认变量确实在压制 DT_RPATH，再调整视图；避免误改为静态链接。
+
+```bash
+env -u LD_LIBRARY_PATH ./conftest; echo $?
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`用 --host= 让 cross_compiling=yes 跳过运行探测来掩盖加载失败`
+- **原因**：绕过 AC_RUN 检测会把 autoconf 的能力探测结果写成错误值（config.h 失真），且 R1 明令禁止三元组参数
+- **后果**：后续库在自己的 test_package 阶段才暴露同一加载问题，定位成本更高
+
+### 🚫 禁止 2
+
+- **模式**：`为了修运行探测而 export LD_LIBRARY_PATH=<视图目录>（或包目录）作为全局环境`
+- **原因**：该变量会被所有子进程继承。指向包目录时因符号链接别名解析失败；指向视图目录时，视图里的依赖副本会被交给工具链子进程——OHOS SDK 的 lld 依赖 libxml2，于是被 Conan 的 libxml2 抢占
+- **后果**：CI worker 上 clang 调 lld 直接崩：Error relocating .../native/llvm/bin/lld: xmlFreeDoc: symbol not found，被 autoconf 报成 C compiler cannot create executables；本机可能侥幸不复现，换 worker 必炸
+
+## 涉及软件
+
+所有在 OHOS 上用 Autotools/CMake 构建、且 autoconf 运行探测或测试程序会链接共享依赖闭包的包（X.Org 客户端库、cairo、pango、fontconfig/freetype 下游等）。与内核版本和 HMMAC 策略相关，换设备须按 verification_cmd 重新实测。
+
+---
+*条目 E505 · 更新 2026-08-28 · 知识库同步生成物*