@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/E534.md

@@ -0,0 +1,54 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E534: OHOS musl 缺失 GNU/BSD 扩展函数的 BusyBox 兼容层与配置规避
+
+> **严重度**: 🟡 medium | **分类**: portability, libc, musl, gnu-extensions | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined symbol: gethostid
+undefined symbol: strverscmp
+undefined symbol: sigisemptyset
+call to undeclared function 'getusershell'
+call to undeclared function 'gethostid'
+implicit declaration.*getusershell
+implicit declaration.*gethostid
+```
+
+## 根因
+
+OHOS musl libc 基于 musl 标准实现，不提供 gethostid、strverscmp、sigisemptyset、getusershell 等 GNU/BSD 扩展函数。这些函数在 glibc 中属于标准扩展，但 musl 项目明确选择不实现非 POSIX 扩展。BusyBox 的某些 applet（hostid、sort -V、ls -v、hush shell、su）直接调用这些函数，编译时产生隐式声明警告/错误，链接时产生未定义符号错误。
+
+## 验证命令
+
+```bash
+echo '#include <string.h>' | clang -x c - -c -E -dM 2>/dev/null | grep HAVE_STRVERSCMP; echo '#include <signal.h>' | clang -x c - -c -E -dM 2>/dev/null | grep sigisemptyset; echo '#include <unistd.h>' | clang -x c - -c -E -dM 2>/dev/null | grep gethostid; nm -D /lib/ld-musl-aarch64.so.1 2>/dev/null | grep -E 'gethostid|strverscmp|sigisemptyset'
+```
+
+## 解决方案
+
+**compat-patch-in-missing-syscalls**：在 libbb/missing_syscalls.c 中添加 gethostid/strverscmp/sigisemptyset 的兼容实现，用 __attribute__((weak)) 弱符号（无需平台条件编译，链接时自动检测：glibc 强符号优先，musl 缺时弱定义生效）。getusershell 因逻辑较复杂（需扫描 /etc/shells），建议直接禁用 applet（CONFIG_SU=n）。实现原则：最小化、不改变调用语义、仅填补 libc 空缺。
+
+```bash
+diff --git a/libbb/missing_syscalls.c b/libbb/missing_syscalls.c
+--- a/libbb/missing_syscalls.c
++++ b/libbb/missing_syscalls.c
++__attribute__((weak)) long gethostid(void) { return 0; }
++__attribute__((weak)) int strverscmp(const char *l0, const char *r0) { /* 标准 GNU 算法，长度比较优先，无溢出；详见 patch */ }
++__attribute__((weak)) int sigisemptyset(const sigset_t *set) { for(i=1;i<_NSIG;i++) if(sigismember(set,i)) return 0; return 1; }
+(完整实现见 BusyBox 1.36.1 适配 patches/0001-ohos-compat-missing-libc-functions.patch)
+```
+
+## 回退方案
+
+**config-disable-applets**：若不愿提供源码补丁，可通过 .config 禁用调用这些函数的 applet（CONFIG_HOSTID=n, CONFIG_FEATURE_SORT_BIG=n, CONFIG_SU=n），但 hush 调用 sigisemptyset 无法通过 config 禁用，必须提供补丁。
+
+## 涉及软件
+
+BusyBox 1.36.1 及同类基于 musl 的 OHOS 环境中使用 gethostid/strverscmp/sigisemptyset/getusershell 调用的软件。已知: hostid (coreutils), sort -V (coreutils), ls -v (coreutils), hush shell (shell/hush.c), su (loginutils)。
+
+---
+*条目 E534 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,91 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E535: CGNS 4.5.2 上游 CTest 在 OHOS 启用与真实通过率核验（24 项: 23 通过 + 1 skip + 0 失败）
+
+> **严重度**: 🟡 medium | **分类**: platform, ohos, build-system, cmake, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+CGNS_ENABLE_TESTS=OFF
+100% tests passed, 0 tests failed out of 24
+Test #.*test_back_comp.*Skipped
+The Fortran compiler identification is unknown
+HDF5.*not found
+MPI.*not found
+```
+
+## 根因
+
+路径 A（基础适配）常以"上游测试需 HDF5/MPI，不可用"为由直接将上游测试写成 0/N，
+未实际启用上游 CTest 核验真实通过率。实测证明该假设对 CGNS 4.5.2 不成立：
+上游 C 测试（24 个 CTest 入口）不依赖 HDF5 链接即可完整构建执行；当
+CGNS_ENABLE_TESTS=ON 且 HDF5=OFF 时，C 测试仅链接 cgns + m。启用后真实结果：
+24 个注册项中 23 个执行并通过、1 个 test_back_comp 由上游 SKIP_TESTS 机制
+（SKIP_RETURN_CODE 125）跳过硬编码在每条 case 的预期输出，0 个失败，
+执行通过率 23/23（100%），不得写成 24/24 或 0/24。OHOS 平台能力缺口
+（无 Fortran 编译器 flang/gfortran、无 MPI）导致 10 个 Fortran CTest 与
+8 个并行示例 N/A，属独立边界，不应与 C 测试结果混算。
+
+## 验证命令
+
+```bash
+上游 CTest 真实注册数与结果核验（仓库外探针或配方内 cmake.test()）:
+ctest -N                                注册数 = 24
+ctest --output-on-failure               23 passed + 1 skip + 0 failed, exit 0
+conan create 主包阶段真实执行: CGNS_ENABLE_TESTS=ON + cmake.test() -> 24 项
+test_package 消费者验证: 6 个 CGNS API 断言 6/6 通过
+  cg_open(CG_MODE_WRITE) -> cg_base_write -> cg_close ->
+  cg_open(CG_MODE_READ) -> cg_nbases -> cg_close
+```
+
+## 解决方案
+
+**enable-upstream-ctest**：conanfile.py 的 generate() 设置 CGNS_ENABLE_TESTS=ON（HDF5=OFF），
+build() 中执行 cmake.test()，让 conan create 真实运行上游 24 项
+CTest；结果按"执行通过数 = 注册数 - skip 数"口径上报
+
+```bash
+def generate(self):
+    tc = CMakeToolchain(self)
+    tc.variables["CGNS_ENABLE_HDF5"] = False
+    tc.variables["CGNS_ENABLE_TESTS"] = True
+    tc.generate()
+def build(self):
+    cmake.configure(); cmake.build()
+    cmake.test()   # conan create 时真实执行上游 CTest
+```
+
+## 回退方案
+
+**ctest-probe-only**：无法并入正式配方时，在仓库外临时探针构建
+（cmake -DCGNS_ENABLE_TESTS=ON + ctest -N + ctest
+--output-on-failure）核验真实注册数与通过率，再按证据上报
+
+```bash
+cmake -S . -B build -DCMAKE_C_COMPILER=<clang> -DCGNS_ENABLE_HDF5=OFF -DCGNS_ENABLE_FORTRAN=OFF -DCGNS_ENABLE_TESTS=ON && cmake --build build -j2 && cd build && ctest -N && ctest --output-on-failure
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`0/24|0/N.*HDF5.*不可用|凭 README 印象写测试数量`
+- **原因**：CGNS C 测试不依赖 HDF5；未启用上游 CTest 就写 0/N 与真实通过率不符
+- **后果**：测试结果失实，无法通过审核（把"未执行"写成"失败"）
+
+### 🚫 禁止 2
+
+- **模式**：`24/24 通过|100% 全部通过`
+- **原因**：实际 1 项 test_back_comp 被上游 SKIP_RETURN_CODE 125 跳过
+- **后果**：通过率口径错误（执行通过率 23/23，非 24/24）
+
+## 涉及软件
+
+所有 CMake 构建、上游有 CTest 注册测试且测试不依赖平台缺失能力
+（HDF5/MPI/Fortran）的 C 库；典型: 科学计算数值库（CGNS 类）
+
+---
+*条目 E535 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,84 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E536: Broadcom (brcm) 固件资源包验证方法 — 适用于纯二进制固件资源包
+
+> **严重度**: 🟢 minor | **分类**: firmware-resource-package | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+brcm.*firmware
+firmware.*blob
+binary.*resource
+firmware.*resource.*package
+no.*compile
+resource.*only.*package
+```
+
+## 根因
+
+linux-firmware 项目包含各厂商的二进制固件 blob，brcm 子目录为 Broadcom 无线网卡固件。
+此类资源不含 C/C++ 编译产物、无构建系统、无传统测试框架。Conan 适配为纯资源包模式。
+
+## 验证命令
+
+```bash
+# 验证是否为纯固件资源包:
+# 检查文件类型是否全为二进制 blob:
+file brcm/*.bin brcm/*.fw brcm/*.hcd 2>/dev/null | grep -c "data\|MS Windows" 
+# 确认无 ELF / 可执行文件:
+find brcm/ -type f -exec file {} \; | grep -iE "ELF|executable" | wc -l
+```
+
+## 解决方案
+
+**firmware-resource-package-validation**：Broadcom 固件资源包的完整验证流程，包括：固定 URL/版本/sha256、许可证验证、
+文件清单/类型/非空/hash 校验、目录结构验证、无 ELF 检查、资源安装路径验证、
+package_info 约束、无 Conan 第三方依赖、无硬件功能验证。
+
+```bash
+# conanfile.py 关键模式:
+#   package_type = "unknown"（无编译产物）
+#   def build(): pass  # 无编译
+#   def package(): copy(self, "*", src=..., dst="res/brcm")
+#   def package_info(): self.cpp_info.resdirs = ["res"]  # 资源包声明
+# test_package 验证：
+#   conanfile.py 中 test() 调用 shell 脚本验证文件和路径
+```
+
+## 回退方案
+
+**upstream-verify-and-download**：直接从官方 CDN 下载并 sha256 验证，提取厂商子目录作为独立资源包
+
+```bash
+# 从官方 CDN 获取 tar.xz（recipe conandata 实际使用）:
+curl -sSL -o linux-firmware-${VER}.tar.xz \
+  "https://cdn.kernel.org/pub/linux/kernel/firmware/linux-firmware-${VER}.tar.xz"
+# 验证 sha256:
+echo "${SHA256}  linux-firmware-${VER}.tar.xz" | sha256sum -c
+# 提取 brcm 子目录（strip-root=1 与 recipe source() strip_root=True 一致）:
+tar xJf linux-firmware-${VER}.tar.xz --strip-components=1 linux-firmware-${VER}/brcm
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`requires.*=.*["']firmware-tools["']|tool_requires.*=.*firmware`
+- **原因**：固件资源包不需要任何编译工具或 firmware-tools 依赖
+- **后果**：引入不必要依赖导致 CI 失败
+
+### 🚫 禁止 2
+
+- **模式**：`cpp_info\.libs\s*=|cpp_info\.bindirs\s*=`
+- **原因**：固件资源包不提供库文件和二进制目录
+- **后果**：下游编译会错误链接到固件数据，导致链接失败
+
+## 涉及软件
+
+所有基于 linux-firmware 的厂商固件资源包子包（brcm, iwlwifi, ath10k, rtlwifi 等）
+
+---
+*条目 E536 · 更新 2026-07-30 · 知识库同步生成物*

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

@@ -0,0 +1,88 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E537: Conan cache absolute DT_NEEDED leakage and relocatable SONAME/link repair
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, linking, conan, packaging, relocatable | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+DT_NEEDED
+NEEDED
+\.cache/conan2
+\.conan2/p/
+unable to find library
+Error loading shared library
+Permission denied
+mmap PROT_EXEC
+IMPORTED_SONAME
+target_link_directories
+SONAME
+```
+
+## 根因
+
+A KDE Frameworks (KF6) dependency library (e.g. kcoreaddons/karchive/ki18n) is
+published without a DT_SONAME. When the dependent library (e.g. libKF6Package.so)
+is linked against that dependency, CMake passes the dependency's absolute Conan
+cache path (IMPORTED_LOCATION) to the linker. Because the dependency has no
+SONAME, ld records the machine-private absolute path (e.g.
+/storage/Users/currentUser/.conan2/p/... or an older .cache/conan2 layout) into
+the produced DT_NEEDED. On a consumer machine with a different Conan cache
+layout that absolute path does not exist, so the loader cannot resolve the
+dependency and the published artifact is not consumable. A post-build ELF
+rewrite with patchelf can remove the paths, but on the OHOS HMDFS cache
+filesystem the patchelf-rewritten file is refused at runtime with
+"Permission denied" (mmap PROT_EXEC), so the repair must happen at link time.
+
+## 验证命令
+
+```bash
+readelf -d bin/libKF6Package.so | grep NEEDED
+```
+
+## 解决方案
+
+**link-time-SONAME-basename**：Do not rewrite the ELF after build. Instead make the linker record the
+dependency by its SONAME-style basename at link time: (1) stamp an
+IMPORTED_SONAME on each KF6 dependency target and clear both generic and
+per-config IMPORTED_NO_SONAME (IMPORTED_NO_SONAME_RELEASE) so CMake passes
+"-L<dir> -l:libKF6CoreAddons.so"; or, more robustly, (2) add
+target_link_directories(KF6Package PUBLIC ${KPACKAGE_DEP_LIB_DIRS}) and link
+the deps by bare "-lKF6CoreAddons" / "-lKF6Archive" / "-lKF6I18n", explicitly
+re-adding Qt6::Core (which keeps its own SONAME) so the Qt runtime link is
+preserved, and copy the deps' INTERFACE_INCLUDE_DIRECTORIES back onto the
+target so headers (QStringList/KJob/QLoggingCategory) remain available. Give
+the produced library a stable SONAME with -Wl,-soname,libKF6Package.so.
+
+```bash
+target_link_directories(KF6Package PUBLIC ${KPACKAGE_DEP_LIB_DIRS})
+```
+
+## 回退方案
+
+**post-build-elf-rewrite**：patchelf --set-soname + --replace-needed on a writable copy then rm -f && cp back; removes the leak but the rewritten file is rejected by HMDFS at runtime (Permission denied / mmap PROT_EXEC), so it is NOT acceptable as the primary fix on OHOS.
+
+```bash
+patchelf --set-soname libKF6Package.so --replace-needed <abs> <basename>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`publish a .so whose DT_NEEDED contains an absolute .conan2/.cache path|use patchelf-rewritten .so on HMDFS as the shipped artifact|link deps by absolute path without SONAME`
+- **原因**：The absolute path is machine-private and non-relocatable; a patchelf-rewritten file is not loadable on HMDFS.
+- **后果**：Consumer on a different cache layout fails to resolve; or the artifact is refused by the HMDFS loader at runtime.
+
+## 涉及软件
+
+Any Conan package that links an imported shared library which itself lacks a
+DT_SONAME and whose IMPORTED_LOCATION is an absolute cache path; reproducible
+across KF6 (kpackage, and any library linking kcoreaddons/karchive/ki18n) and
+similar Conan ecosystems.
+
+---
+*条目 E537 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,86 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E538: 统一 C++17/libc++ profile 后 ohpcd 发布依赖图选项不一致的解决与 pangomm 本地闭环修复链
+
+> **严重度**: 🟡 medium | **分类**: ohos, toolchain, conan, dependency-graph, meson-pkgconfig | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)、[P020](../principles.md#P020)
+
+---
+
+## 错误特征
+
+```
+Missing binary: harfbuzz
+Options conflicts
+No compatible configuration found
+package 'pangocairo' has no Version
+has no Description
+gmmprocdir
+glibmm_generate_extra_defs-2.68 not found
+binary-sign-tool.*-a
+pangomm.h.*not found
+symbol not found
+```
+
+## 根因
+
+r11 时 ohpcd 发布的 harfbuzz/14.2.0.1 binary 仅基于 glib:shared=False（静态）
+构建，而 glibmm/cairomm/pango 发布 binary 基于 shared=True，pangomm 全图
+glib=shared=True 时 harfbuzz 计算包 ID 无发布 binary，源码构建超过 300s 前台时限。
+r12 中 ohpcd 发布修复版 harfbuzz/14.2.0.1#58fa487c（2026-08-23），binary
+1b5bfb 改为 requires glib/2.84.Z（动态，不锁 revision），全图解析成功。
+但 pangomm 自身闭环又暴露 meson/PkgConfigDeps/签名/运行时的多环节适配点。
+
+## 验证命令
+
+```bash
+conan list 'harfbuzz/14.2.0.1:*' -r ohpcd;
+conan create 〈外部知识库归档〉 --profile:host=pangomm-cxx17 --build=missing
+```
+
+## 解决方案
+
+**published-binary-wait-plus-meson-pkgconfig-fixes**：发布侧：等待 ohpcd 发布与 shared glib 匹配的 harfbuzz binary（r12 已修复）。
+消费侧 recipe 需要四类修复：
+(1) alias-pc：PkgConfigDeps 只生成 pango.pc，需为 pangocairo/pangoft2 手写
+    转发 .pc 且带 Name/Description/Version（pkg-config 0.29.2 校验）；
+(2) pc-var：PkgConfigDeps 不写 gmmprocdir，需补进 glibmm-2.68.pc；
+(3) link-args：meson find_library(glibmm_generate_extra_defs-2.68) 需
+    -L glibmm libdir（经 conf tools.build:sharedlinkflags/exelinkflags 注入）；
+(4) sign：binary-sign-tool 正确语法 sign -selfSign 1 -inFile X -outFile Y，
+    -a 非法；package_info 需声明 include/pangomm-2.48 与 lib/.../include。
+
+```bash
+conan create 〈外部知识库归档〉 --profile:host=pangomm-cxx17 --build=missing
+```
+
+## 回退方案
+
+**runtime-skip-musl-loader-block**：test_package 运行时若因 cairomm 发布 binary 与 OHOS musl 加载器不兼容
+（symbol not found）阻塞且无法在 recipe 内修复，记录为运行时环境阻塞，
+编译+链接证据保留，运行阶段按环境限制回报。
+
+```bash
+LD_LIBRARY_PATH=... ./test_probe
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`modify harfbuzz/glibmm/cairomm/pango recipe to force shared`
+- **原因**：违反"不得修改依赖库"原则，且会破坏已发布 binary 匹配。
+- **后果**：recipe 修改后发布 binary 不匹配，重新引入缺包。
+
+### 🚫 禁止 2
+
+- **模式**：`sign -a <file> for binary-sign-tool`
+- **原因**：-a 不是 binary-sign-tool 有效命令（trust list 报错）。
+- **后果**：package() 阶段签名失败，包无法产出。
+
+## 涉及软件
+
+OHOS armv8 clang15 C++17/libc++ profile 下消费 glibmm/cairomm/pango/harfbuzz
+依赖链的 Meson 项目；依赖 ohpcd 发布一致性的 Conan 图；OHOS musl 运行时。
+
+---
+*条目 E538 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E539: zlib test_package should build a shared-library PIC probe
+
+> **严重度**: 🟡 medium | **分类**: conan, test-package-pic-probe | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+zlib_pic_probe
+R_AARCH64_ADR_PREL_PG_HI21
+relocation
+SHARED
+libz.a
+```
+
+## 根因
+
+A normal compress/uncompress round trip proves the zlib API works, but it does not prove that static libz.a was built from PIC objects. The non-PIC failure only appears when the archive is linked into a shared object on AArch64.
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**api-roundtrip-plus-shared-library-link**：Keep a runtime API smoke test for compress/uncompress, and add a second CMake target that builds a SHARED library linked against zlib::zlib. The shared target catches non-PIC static archives during test_package build, before downstream consumers hit the same relocation.
+
+```bash
+add_library(zlib_pic_probe SHARED pic_probe.c); target_link_libraries(zlib_pic_probe zlib::zlib)
+```
+
+## 回退方案
+
+**downstream-dso-reproducer**：If CMake test_package cannot be used, build a minimal shared object manually with clang and link it against the packaged libz.a.
+
+```bash
+clang -shared pic_probe.c path/to/libz.a -o libzlib_pic_probe.so
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`only run zlibVersion|only compile an executable|empty test_package`
+- **原因**：Executable-only tests can pass even when the static archive cannot be linked into DSOs.
+- **后果**：Higher-level consumers fail later with relocation errors despite zlib test_package passing.
+
+## 涉及软件
+
+Static zlib packages used by downstream shared-library, plugin, or Python-extension consumers on OHOS.
+
+---
+*条目 E539 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E540: zlib Makefile shadow CI needs /data/service/hnp/bin in PATH
+
+> **严重度**: 🟡 medium | **分类**: ohos, runner-tool-path | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+make: inaccessible or not found
+/system/bin/sh: make
+/data/service/hnp/bin
+exit 127
+```
+
+## 根因
+
+The OHOS Conan profile can point CC/CXX to /data/service/hnp/bin/clang, so configure succeeds, while later recipe commands such as make -j1 still resolve through PATH. If runner PATH lacks /data/service/hnp/bin, Makefile packages fail at the first make invocation.
+
+## 验证命令
+
+```bash
+sh $HOME/bin/ohos-test-runner.sh --path /data/service/hnp/bin -- zsh 〈外部知识库流水线〉 〈外部知识库归档〉
+```
+
+## 解决方案
+
+**runner-path-prepend**：Before single-package shadow CI, prepend /data/service/hnp/bin to PATH through the runner --path option. For CMake-based test_package builds, also include the active HNP CMake directory when present.
+
+```bash
+EXTRA_PATH=/data/service/hnp/bin:/data/service/hnp/cmake.org/cmake_4.1.2/bin:$HOME/usr/local/bin:$HOME/.local/bin:$HOME/ohpc-ci-shadow/python-user/bin; sh $HOME/bin/ohos-test-runner.sh --path "$EXTRA_PATH" -- zsh 〈外部知识库流水线〉 〈外部知识库归档〉
+```
+
+## 回退方案
+
+**absolute-make-command-probe**：If the runner still fails, first verify /data/service/hnp/bin/make --version and inspect runner logs/env.txt before changing the recipe.
+
+```bash
+/data/service/hnp/bin/make --version; grep '^PATH=' "$RUN/logs/env.txt"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`treat make not found as zlib source failure|clear device lock owned by another run|rerun without CI_PACKAGES`
+- **原因**：The failure is a runner environment issue, not a zlib compatibility failure; lock ownership and single-package scope must be preserved.
+- **后果**：Misdiagnosis can cause unnecessary recipe churn or disrupt another active device CI task.
+
+## 涉及软件
+
+zlib and similar Makefile/autotools packages verified through ohos-test-runner on HarmonyOS devices.
+
+---
+*条目 E540 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E541: zlib on OHOS should stay static-only but use PIC objects for DSO consumers
+
+> **严重度**: 🟡 medium | **分类**: ohos, system-same-name-static-pic | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+R_AARCH64_ADR_PREL_PG_HI21
+z_errmsg
+libz.so
+libz.a
+non-PIC
+shared library
+```
+
+## 根因
+
+HarmonyOS provides a system libz.so, so publishing another shared libz.so from Conan can collide with system loader paths. However, a plain static libz.a built without -fPIC cannot be linked into shared libraries or Python extension modules on AArch64.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**static-only-pic-archive**：Build zlib with upstream configure in static mode, keep the package artifact as lib/libz.a, and force CFLAGS to include -fPIC. This avoids publishing a competing libz.so while still allowing downstream shared objects to absorb zlib objects safely.
+
+```bash
+CONFIG_SHELL=/data/service/hnp/bin/bash CC=/data/service/hnp/bin/clang CFLAGS="-O3 -fPIC" /data/service/hnp/bin/bash ./configure --static --prefix=/ && make -j1 && make check
+```
+
+## 回退方案
+
+**consumer-side-version-pin**：If older zlib packages already exist, add a suffix package version for the PIC archive and pin DSO-building consumers to that version.
+
+```bash
+self.requires("zlib/1.3.1.1.1")
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`publish Conan libz.so on OHOS|drop -fPIC from static zlib|replace system libz.so`
+- **原因**：Shared libz.so can collide with the platform library, while non-PIC libz.a breaks DSO and Python extension links.
+- **后果**：Downstream consumers can fail with AArch64 relocation errors or load the wrong libz implementation at runtime.
+
+## 涉及软件
+
+zlib packages and downstream OHOS consumers that link zlib transitively into shared libraries, modules, or plugin DSOs.
+
+---
+*条目 E541 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,53 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E542: Qt 子模块无独立源码：provider 配方复用已发布父模块制品（Qt6LinguistTools 案例）
+
+> **严重度**: 🟡 medium | **分类**: conan, dependency-graph, provider, qt-module | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Could NOT find Qt6LinguistTools
+Could not find a package configuration file
+provided by "Qt6LinguistTools"
+Qt6LinguistToolsConfig\.cmake.*does NOT exist
+requires Qt6LinguistTools \(not published
+```
+
+## 根因
+
+Qt6LinguistTools 在 Qt 6 中不是独立源码模块：其实体（lrelease/lupdate/
+lconvert/lcheck/ltext2id 等工具 + Qt6LinguistToolsConfig.cmake /
+Qt6::LinguistTools 宏模块）由 qttools 构建产生。消费者（如 KDE kdnssd 的
+ECM ECMPoQmTools.cmake:155）执行 find_package(Qt6 COMPONENTS LinguistTools)
+依赖 Qt6LinguistToolsConfig.cmake；此前 ohpcd 未发布任何提供该配置的包，
+KDE 库（karchive/kauth/kbookmarks/kcodecs/kcompletion 等）只能把
+ecm_install_po_files_as_qm(poqm) 注释掉（"requires Qt6LinguistTools (not
+published to ohpcd)"）。若按常规方式为 Qt6LinguistTools 重新下载编译
+qttools 全部源码，会重复已发布的 qttools/6.11.1.1 制品且违反 R36 先例。
+
+## 验证命令
+
+```bash
+待补：条目级验证命令未随草稿记录；条目来自已合并 PR，CI 验证以 PR 记录为准
+```
+
+## 解决方案
+
+**provider 配方复用已发布父模块制品：conanfile.py name=qt6linguisttools
+（slug 全小写 L0m-5），requires(qttools, qtbase)，build() 仅
+apply_conandata_patches，package() 从 qttools 依赖包复制
+lib/cmake/Qt6LinguistTools/* 与 bin/{lrelease,lupdate,lconvert,lcheck,
+ltext2id}，package_info 暴露 linguisttools 组件（Qt6::LinguistTools）+
+env_info.PATH。**：通用模式：独立归档库实为已发布父模块子组件时——(1) conan download
+--only-recipe 核验父模块制品含目标 CMake 组件；(2) provider 配方复用，
+禁止重新下载父模块源码编译（R36）；(3) 归档目录名=conan slug 全小写。
+
+## 涉及软件
+
+Qt6LinguistTools, LinguistTools, qttools, lrelease, lupdate, lconvert, ECMPoQmTools, ecm_install_po_。根因: Qt6LinguistTools 在 Qt 6 中不是独立源码模块：其实体（lrelease/lupdate/ lconvert/lcheck/ltext2id 等工具 + Qt6LinguistToolsConfig.cmake / Qt6::LinguistTools 宏模块）由 qttools
+
+---
+*条目 E542 · 更新 2026-08-31 · 知识库同步生成物*