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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E526: Conan 2.x apply_conandata_patches 默认 strip=0，pre-CI/本地校验必须镜像该语义而非 -p1
+
+> **严重度**: 🔴 blocking | **分类**: conan, patch, patch-ng | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+patch: can't find file
+Apply failed
+```
+
+## 根因
+
+Conan 2.x 的 apply_conandata_patches 读取 conandata.yml 的 patches 条目，经 patch_ng 库应用补丁，默认 strip=0：patch_ng 会自动剥离 git format-patch 风格 diff 头里的 a/ 与 b/ 前缀，无需 -p1 强剥。若 pre-CI/本地/评审校验用系统 patch 命令按 -p1 语义 dry-run，与 Conan 实际应用语义不一致：要么对 "--- a/xxx" 头多剥一层误判目标文件缺失（假失败），要么在 strip 层级上未覆盖真实应用路径（假通过），使 patch 校验结论失真。MLton 0001/0002/0003 补丁均为 git format-patch 格式（diff --git a/... b/...、--- a/... +++ b/...），应用与校验必须同一语义。
+
+## 验证命令
+
+```bash
+干净 source_folder 上跑 apply_conandata_patches(self) 后 diff/hash 确认目标文件已改；对比 patch --dry-run -p1 与 strip=0 两种校验在同一补丁上的结论差异，确认必须按 strip=0 语义校验。
+```
+
+## 解决方案
+
+**mirror-strip-0-patch-semantics-in-pre-ci**：pre-CI/本地校验与 apply_conandata_patches 使用同一 patch 语义：以 strip=0 + patch_ng 对 a/b 前缀的自动剥离为准，不用 -p1 强剥；最稳妥是直接在干净源码树调用 apply_conandata_patches 验证（应用后 diff 确认目标行已改），再对应用结果做 hash 比对，保证校验即应用。
+
+```bash
+校验脚本在干净源码树执行 apply_conandata_patches 后核对 hash/差异；若需 dry-run，按 strip=0 语义（patch_ng 自动剥 a/b 前缀）模拟，禁止 patch -p1 直接 dry-run git 格式补丁。
+```
+
+## 回退方案
+
+**explicit-strip-level-in-conandata**：若校验工具强制要求显式 strip 层级，在 conandata.yml 每条 patch 显式声明与 strip=0 等价的层级并让校验命令读取同一配置，保证校验与应用同源同语义。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`patch -p1.*dry-run|patch.*-p1.*校验`
+- **原因**：用 -p1 语义校验 strip=0 的应用，二者不一致导致假失败或假通过，patch 校验与 CI 结论失真。
+- **后果**：pre-CI 误拦合法补丁，或放行实际无法应用的补丁，评审与 CI 结果失真。
+
+### 🚫 禁止 2
+
+- **模式**：`改补丁头.*去掉.*a/.*b/|手工改写 diff 头`
+- **原因**：为迎合错误校验而改写 diff 头会破坏 git format-patch 的可追溯性与上游一致性。
+- **后果**：补丁不可复现，向上游提交受阻。
+
+## 涉及软件
+
+所有用 Conan 2.x 配方 + conandata.yml 注册 git format-patch 风格补丁（a/b 前缀）的项目；其 pre-CI checklist、patch dry-run 校验、评审脚本与 Conan 应用路径。与 E216-draft-C113（多源码 base_path 路由）、E258-draft-ENCH01（patch 致 mtime 倒挂）同属 Conan 补丁管线语义坑。
+
+---
+*条目 E526 · 更新 2026-08-10 · 知识库同步生成物*

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

@@ -0,0 +1,103 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E527: OHOS PC 无 X11/Wayland/Quartz/Win32 任何原生显示后端
+
+> **严重度**: 🔴 blocking | **分类**: platform, meson, pkg-config, display, gnome | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+Dependency ".*" not found
+X11 backend.*not found
+wayland.*not found.*try.*broadway
+Neither x11_backend nor wayland_backend nor broadway_backend is true
+Cannot open display
+cannot connect to X server
+gtk_init.*failed
+```
+
+## 根因
+
+OHOS PC 无 X11/Wayland/Quartz/Win32 任何原生显示后端，
+GTK3 的 meson.build 要求至少启用一个后端
+（x11_backend/wayland_backend/broadway_backend 全 false 时
+直接 configuration 失败），且默认后端连带依赖 epoxy(GL)、
+xinerama、cloudproviders 等平台组件；
+同时运行期 gtk_init() 需要 DISPLAY/连接显示服务，
+纯编译通过不等于可运行（R40 深度适配边界）。
+另有两类伴生问题：① glib-mkenums/glib-genmarshal 是构建时
+Python 工具，交叉编译时必须在 build machine 执行而非 host；
+② 上游是 .pc 多文件体系，Conan PkgConfigDeps 只生成声明
+的主 .pc，消费方 dependency('gtk+-3.0') 会找不到（同 E321）。
+
+## 验证命令
+
+```bash
+# 后端配置生效（configure 日志应出现 broadway: YES）
+grep -E "broadway|x11_backend" builddir/meson-logs/meson-log.txt
+# 产物含 libgtk-3 且 NEEDED 无 libX11/libwayland
+readelf -d <prefix>/lib/libgtk-3.so | grep NEEDED
+# 消费方 .pc 检测
+pkg-config --modversion gtk+-3.0
+```
+
+## 解决方案
+
+**broadway-backend-native-tools-wrapper**：三件套组合：① meson 选项切 broadway HTML5 后端
+（-Dx11_backend=false -Dwayland_backend=false
+-Dbroadway_backend=true，纯 HTTP/WebSocket 输出无原生显示
+依赖），同时禁 xinerama/cloudproviders/profiler/introspection/
+gtk_doc/man/demos/examples/tests；② generate() 里把
+glib-mkenums/glib-genmarshal 包装为 native 可执行 wrapper
+（shebang 指向 build machine python3，注入 pkg-config 变量
+让 meson 找到构建时工具）；③ PkgConfigDeps.generate() 后补
+转发型别名 .pc（Version 动态继承主 .pc，Requires 主 .pc，
+同 E321 手法）。运行期标注 R40 partial：需 broadwayd 服务 +
+浏览器访问，GUI 行为不在 CI 断言范围。
+
+```bash
+# ① meson 选项（conanfile.py layout()/build() 中经 MesonToolchain 注入）
+#   -Dx11_backend=false -Dwayland_backend=false -Dbroadway_backend=true
+#   -Dxinerama=no -Dcloudproviders=disabled -Dintrospection=disabled
+#   -Dgtk_doc=false -Ddemos=false -Dexamples=false -Dtests=false
+# ② 构建 glib-mkenums native wrapper（generate() 内，参考
+#    〈外部知识库归档〉::_build_python_tool_wrapper）
+#    shebang: #!/usr/bin/env python3 → 指向 build machine 解释器
+# ③ 别名 .pc：_create_pkg_config_alias("gtk+-3.0", ...) 参考
+#    gdk-pixbuf 配方同名函数 / pango 配方 --alias-pc 生成
+```
+
+## 回退方案
+
+**offscreen-headless-partial**：无法启用任何后端时（如上游移除 broadway），改编译
+headless 能力子集并在 manifest/notes 显式标注 R40 partial
+（仅 API 层可用，无窗口能力），禁止 stub 假装后端存在。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`stub.*(libX11|libwayland)|LD_PRELOAD.*libX11`
+- **原因**：用空实现 X11/Wayland 库欺骗链接期检查，运行期 gtk_init()
+仍会失败且崩溃点远离真实根因
+- **后果**：二进制进入制品仓后下游全部踩坑，且 R40 审计判 fail
+
+### 🚫 禁止 2
+
+- **模式**：`把 host 的 glib-mkenums/glib-genmarshal 路径写死进配方`
+- **原因**：conan 缓存目录随 HOME/缓存策略漂移，写死路径在其他环境必炸
+- **后果**：换机器/CI 后 enumeration 步骤找不到工具，构建随机失败
+
+## 涉及软件
+
+所有 GTK/GDK 系 GUI 库与应用在 OHOS PC 的适配
+（gtk+/gtksourceview3/klavaro/goocanvas 等 GNOME 生态）。
+
+## 相关模式
+
+- **相似模式**：[E318](E318.md)、[E321](E321.md)
+
+---
+*条目 E527 · 更新 2026-08-21 · 知识库同步生成物*

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

@@ -0,0 +1,64 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E528: Close the OHOS native Autotools environment before configure
+
+> **严重度**: 🔴 blocking | **分类**: ohos, autotools, conan, permissions, native-toolchain | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+could not determine .* interface
+configure: error: could not setup config files machinery
+conf.*/subs1.awk: Permission denied
+checking for .*ar.*link -lib
+cannot create .*subs1.awk
+```
+
+## 根因
+
+On OHOS shadow CI, the runner profile can provide clang through tools.build:compiler_executables while PATH still omits the full native toolchain directory. Autotools then fails archiver discovery and may fall through to unrelated host tools such as link -lib. After that is fixed, Autoconf config.status can create ./conf* subdirectories under the build folder with ownership/permission semantics that reject creating generated files such as subs1.awk.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**recipe-local-ohos-autotools-env-closure**：In generate(), derive the tool directory from tools.build:compiler_executables['c']; prepend it to PATH; define AR, NM, RANLIB, and STRIP to llvm-* tools when present. For OHOS, create a device-private TMPDIR such as /data/storage/el2/base/<pkg>-configure-tmp and use replace_in_file(strict=True) after apply_conandata_patches() to make the generated configure/config.status template create conf* below TMPDIR instead of the build folder.
+
+```bash
+conan create 〈外部知识库归档〉 --build=missing
+```
+
+## 回退方案
+
+**explicit-configure-shell-and-make-j1**：If the host shell or make jobserver adds noise, invoke configure through sh from build_folder and keep make at -j1. This does not replace the toolchain and mktemp closure; it only reduces unrelated OHOS runner variability.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`patch.*〈外部知识库流水线〉|edit.*ohos-test-runner|export PATH=.*profile-wide`
+- **原因**：A package PR must not fix a package-local Autotools environment by modifying shared CI or runner infrastructure.
+- **后果**：The recipe remains non-reproducible outside that one runner and violates one-library-one-PR isolation.
+
+### 🚫 禁止 2
+
+- **模式**：`chmod.*conf.*|retry.*configure|ignore.*Permission denied`
+- **原因**：The config.status failure is deterministic HMDFS temporary-directory behavior, not a flaky chmod issue.
+- **后果**：Retries keep failing or advance only when unrelated environment state changes.
+
+## 涉及软件
+
+Dependency-light Autotools release-tarball recipes that run configure natively on OHOS and rely on Conan profile compiler paths instead of a globally complete PATH.
+
+## 相关模式
+
+- **相似模式**：[E114](E114.md)、[E337](E337.md)
+
+---
+*条目 E528 · 更新 2026-08-26 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E529: Give OHOS CMake test_package recipes their own tool PATH
+
+> **严重度**: 🔴 blocking | **分类**: ohos, cmake, conan, packaging, testing | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+/system/bin/sh: cmake: inaccessible or not found
+CMake.configure.*Error 127
+test package.*cmake
+```
+
+## 根因
+
+Conan executes test_package as a separate recipe context. Build environment scripts generated by the package recipe do not automatically repair PATH for CMake.configure() inside the test package. On OHOS shadow CI, cmake and make can live in the same native toolchain directory as clang, so a package can build successfully while its consumer test fails with cmake inaccessible or not found.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**test-package-local-tool-path**：Add a generate() method to the test_package recipe. For OHOS, derive the tool directory from tools.build:compiler_executables['c'], fall back to /data/service/hnp/bin when present, prepend that directory to PATH with Environment(), and save the script before calling CMake.configure().
+
+```bash
+conan create 〈外部知识库归档〉 --build=missing
+```
+
+## 回退方案
+
+**explicit-cmake-tool-conf**：If a future runner separates cmake from clang, extend the same test_package-local generate() method to read an explicit CMake tool path from Conan conf. Keep the fix in the test package, not in the main package build step.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*test_package|def test.*pass|return.*before.*CMake`
+- **原因**：The CMake failure is an environment closure problem, not evidence that consumer validation should be removed.
+- **后果**：The package can publish without proving that installed headers and libraries are consumable.
+
+### 🚫 禁止 2
+
+- **模式**：`assume.*package.*generate.*test_package|source.*conanbuild.*from package cache`
+- **原因**：The package recipe and test_package recipe have separate generated environments.
+- **后果**：The main package build passes, but the consumer test remains non-reproducible.
+
+## 涉及软件
+
+Conan 2 test_package recipes using CMake, CMakeToolchain, CMakeDeps, and cmake_layout on OHOS where the runner PATH is minimal and tool locations are primarily exposed through tools.build:compiler_executables.
+
+## 相关模式
+
+- **相似模式**：[E338](E338.md)
+
+---
+*条目 E529 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E530: X11 客户端库无 X server 时用强类型活重定位 + ABI 布局固定做消费者测试
+
+> **严重度**: 🔴 blocking | **分类**: ohos, packaging, testing, abi, x11 | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+undefined reference to .Xinerama
+No such file or directory.*X11
+make check.*no tests
+Xvfb
+:0.*Cannot open display
+```
+
+## 根因
+
+X11 扩展客户端库上游通常无自动化测试（make check 为空），
+而真实函数调用需要 X server。空 test_package 只验证链接、
+不验证导出符号集合与类型/常量契约，ABI 退化时无声。
+OHOS CI worker 无 Xvfb，无法运行上游 X 测试。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+（test_package 两个可执行文件须全部通过）
+```
+
+## 解决方案
+
+**strong-typed-relocation-plus-abi-pinning**：api_surface.c 用 __typeof__(&name) + volatile 取地址对每个导出符号生成
+活重定位（链接期即校验签名与存在性）；version_contract.c 用 CHECK 宏
+钉死协议版本常量与公开结构体 offsetof/sizeof；CMake 加 -Wall -Wextra
+-Werror；test_package 用 explicit test_type，OHOS 上签名后逐个运行。
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 回退方案
+
+**static-nm-symbol-check**：若无法编译消费者测试（如缺头），退而用 readelf/nm 对产物导出符号
+做静态清单对比上游头文件声明；但该法不校验签名与布局，优先级低于前者。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`int main\(void\)\{\s*return 0;\s*\}.*test_package`
+- **原因**：只链接不验证的空 test_package 无法捕获符号/类型/布局退化。
+- **后果**：ABI 破坏合并上线后消费者运行时才崩溃。
+
+### 🚫 禁止 2
+
+- **模式**：`Xvfb|DISPLAY=:0|dlopen.*dlsym`
+- **原因**：OHOS CI 无 X server；弱引用/dlopen 兜底掩盖缺失符号。
+- **后果**：测试在 CI 必挂或漏报缺失符号。
+
+## 涉及软件
+
+X11 家族扩展客户端库（Xcomposite/Xinerama/Xdamage/Xrandr/Xcursor）
+及一切无上游测试、产物为 .so 且无运行时依赖的库在 OHOS 的适配。
+
+## 相关模式
+
+- **相似模式**：[E340](E340.md)
+
+---
+*条目 E530 · 更新 2026-08-26 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E531: OHOS musl libc 缺少 glibc 风格 qsort_r — 以本地 shim 委托 qsort 修复
+
+> **严重度**: 🟡 medium | **分类**: compat, portability, libc, musl, autotools | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined reference.*qsort_r
+qsort_r.*not found
+ld.lld.*undefined.*qsort_r
+```
+
+## 根因
+
+authselect 的 src/lib/util/dir.c 使用 glibc 风格 qsort_r (GNU 签名 qsort_r(void*,size_t,size_t,int(*)(const void*,const void*,void*),void*), compar 回调接收用户上下文 arg)；OHOS 使用 musl libc，不导出 GNU 签名 qsort_r (musl 导出的 BSD 签名参数顺序不同, thunk 在 compar 前且未作为公共符号导出)；链接时 --no-allow-shlib-undefined 检测到未定义符号 qsort_r 而失败。
+
+## 验证命令
+
+```bash
+make check 或 conan create 应包含 cmocka 测试；验证链接器不报 qsort_r 未定义，且排序行为与原始 glibc qsort_r 一致。
+```
+
+## 解决方案
+
+**local-glibc-compat-shim**：在受影响源文件中以 #ifndef __GLIBC__ 条件编译添加本地 GNU 签名 qsort_r shim，通过静态全局变量保存比较器与上下文，委托标准 qsort 实现；调用方无需修改代码；仅安全用于单线程 CLI 场景。
+
+```bash
+见 patches/0001-qsort-r-compat.patch
+```
+
+## 回退方案
+
+**thread-local-storage**：若目标应用为多线程环境，需改用 _Thread_local 或完全重入实现，避免静态上下文竞态条件。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`qsort_r.*__GLIBC__|#ifdef __GLIBC__`
+- **原因**：glibc 已有 qsort_r，条件编译保护应用于非 glibc 平台。
+- **后果**：在 glibc 上重复定义 qsort_r 会导致符号冲突。
+
+### 🚫 禁止 2
+
+- **模式**：`using.*qsort_r.*musl|qsort_r.*musl.*BSD`
+- **原因**：musl 的 BSD 签名 qsort_r 参数顺序与 glibc 不兼容，直接调用会编译错误，不能替代 glibc 风格 qsort_r。
+- **后果**：编译时参数顺序错误或链接符号冲突。
+
+### 🚫 禁止 3
+
+- **模式**：`--build=missing|--build=.*pcre2|conan upload`
+- **原因**：qsort_r 问题是 libc 兼容性，不是依赖缺失或补丁缺失。
+- **后果**：绕过依赖检查不会解决 libc 符号缺失。
+
+## 涉及软件
+
+在 OHOS (musl) 上使用 glibc 风格 qsort_r 的 C/C++ 项目；常见于 autotools 构建的 CLI 工具，其 configure.ac 或源代码直接调用 glibc 扩展 qsort_r 进行带上下文的比较排序。
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)、[E114](E114.md)、[E011](E011.md)
+
+---
+*条目 E531 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,76 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E532: 上游 CMake if(WIN32) elseif(UNIX) else() 平台三分支不识别 HarmonyOS，编译落入 else() 报 Unsupported platform
+
+> **严重度**: 🔴 blocking | **分类**: platform, detection, ohos, posix, cmake | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+CMake Error.*Unsupported platform
+message\(FATAL_ERROR "Unsupported platform
+elseif \(UNIX\)
+if \(WIN32 OR MINGW
+No transport adapter was selected.*libcurl
+```
+
+## 根因
+
+CMake 在 OHOS 工具链下将 CMAKE_SYSTEM_NAME 设为 "HarmonyOS"，它不是 WIN32 也不是 UNIX。
+许多上游项目的 cmake-modules 用
+  if(WIN32 OR MINGW ...)  ...  elseif(UNIX)  ...  else() message(FATAL_ERROR "Unsupported platform.")
+三分支做平台判定（例如 azure-sdk-for-cpp 的 cmake-modules/AzureTransportAdapters.cmake）。
+HarmonyOS 平台（POSIX 语义、ELF、libc++）既不满足 WIN32 也不满足 UNIX，落入 else() 直接 FATAL。
+配置阶段即失败，尚未进入编译。
+
+## 验证命令
+
+```bash
+conan create . -pr:h=ohos-aarch64 -pr:b=ohos-aarch64 2>&1 | grep -E "Unsupported platform|checking|CMake Error"
+```
+
+## 解决方案
+
+**harmonyos-into-unix-branch**：将平台判定条件由 elseif(UNIX) 扩展为 elseif(UNIX OR CMAKE_SYSTEM_NAME STREQUAL "HarmonyOS")，
+使 HarmonyOS 落入 POSIX 分支，复用该分支的 curl/libcurl 传输适配与 POSIX 编译选项。
+若判定语句写成 if(WIN32 ...) / elseif(UNIX ...) 的完整分支结构，仅需最小一处改动；
+注意以 patch 形式提供，避免改动上游源码管理。
+
+```bash
+sed -i 's/elseif (UNIX)/elseif (UNIX OR CMAKE_SYSTEM_NAME STREQUAL "HarmonyOS")/' cmake-modules/AzureTransportAdapters.cmake
+```
+
+## 回退方案
+
+**toolchain-inject-platform-cmake**：若上游判定逻辑复杂不便打补丁，可考虑注入 Platform/HarmonyOS.cmake（include Platform/Linux）使
+CMake 平台模块链认为系统属已知平台；但三分支判定基于独立变量（WIN32/UNIX），注入平台模块不改变
+UNIX 变量的判定结果，故对本模式无效。此路仅对"SONAME/平台模块缺失"类问题有效。
+
+```bash
+true
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`set\(CMAKE_SYSTEM_NAME\s+\"Linux\"\)`
+- **原因**：强行把系统名改成 Linux 会改变大量平台行为（pthread、soname、abi），行为面过宽，不如精确归入 UNIX 分支。
+- **后果**：可能掩盖真实平台差异，且与 OHOS 工具链生成的环境变量冲突。
+
+### 🚫 禁止 2
+
+- **模式**：`message\(FATAL_ERROR "Unsupported platform.\)`
+- **原因**：不做修复直接编译必然在此处失败。
+- **后果**：configure 阶段终止，无法进入编译/测试。
+
+## 涉及软件
+
+所有以 CMake 构建、且 cmake-modules 使用 if(WIN32)/elseif(UNIX)/else() 三分支
+进行平台判定的上游 C/C++ 库的 OHOS 适配。HarmonyOS androidx 平台为默认影响面。
+azure-core-cpp 1.16.4 实证：AzureTransportAdapters.cmake:73 message(FATAL_ERROR "Unsupported platform.")
+
+---
+*条目 E532 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,116 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E533: libarchive/bsdtar 3.7.7 HarmonyOS PC 适配: autotools 跨平台 + hmdfs 权限 + 依赖边界 + 测试套件分类
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, ohos, portability, autotools, dependency | **自动修复**: ❌ | **原则**: [P001](../principles.md#P001)、[P005](../principles.md#P005)、[P013](../principles.md#P013)、[P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+config.guess.*HarmonyOS
+Permission denied.*tmp
+assertion_file_mode
+umask 077
+hmfs.*mode
+setgid
+owner-bits-only
+R_AARCH64_ADR_PREL_PG_HI21.*z_errmsg
+fPIC
+liblzma.*runtime.*load
+make check.*failed
+```
+
+## 根因
+
+1. config.guess 缺乏 HarmonyOS 识别分支，configure 无法推断 aarch64-unknown-linux-ohos
+   triplet，导致构建系统类型检测失败。libarchive 3.7.7 内置的 config.guess 是 2021-10-26
+   版本，无 HarmonyOS 条目。
+2. hmdfs（HarmonyOS Distributed File System）强制 setgid 位、裁剪 group/other 权限位，
+   且 mkdir 默认 umask 077 在大赛中因平台原因生效（非容器环境），导致 configure 临时目录
+   创建失败（Permission denied）以及测试套件中 assertion_file_mode 精确 0755 断言失败。
+3. 实际链接依赖仅 zlib + liblzma(xz)（bzip2/zstd/lz4/openssl/libxml2 在 OHOS 上
+   configure 未检测到），但 zlib 官方制品仓的 libz.a 未以 -fPIC 编译，链接共享库时触发
+   R_AARCH64_ADR_PREL_PG_HI21 重定位错误；xz 的 pkg-config 优先指向 harmonybrew 系统
+   共享库导致运行时 .so 加载失败。
+4. 上游 `make check` 5 套件合计 801 条用例，因平台已知限制（hmdfs 硬链接不支持、
+   权限位差异、未编译加密 backend）产生 39 failed + 226 skipped，非库本身缺陷。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**autotools-hmdfs-dependency-boundary-test-classification**：1. config.guess 增强：在 `case $UNAME_MACHINE:$UNAME_SYSTEM:$UNAME_RELEASE:$UNAME_VERSION`
+   分支前插入 HarmonyOS 条目，将 aarch64 映射为 ${MACHINE}-unknown-linux-ohos。
+2. hmdfs 权限兼容：configure 临时目录创建 umask 从 077 改为 002；test_main.c 中
+   assertion_file_mode 比较改为 owner-bits-only（0700 掩码比较），容忍 setgid 和
+   其他位差异。
+3. 依赖冻结：声明 zlib/1.3.1.1（-fPIC 重建版）和 xz/5.6.2 为唯一强制依赖；
+   configure 传 `--without-xml2` 禁用可选 libxml2；generate() 中通过
+   extra_cflags/extra_ldflags 将 conan 依赖的 include/lib 路径置前以覆盖 pkg-config
+   的 harmonybrew 系统路径。
+4. 测试分类：`make check` 保留全部 5 套件 801 条注册项，不接受平台宏整体跳过；
+   已知 hmdfs 硬链接失败（E079）、权限位失败（E011/E129）和加密 backend 未编译失败
+   作为独立类别记录，不阻塞适配结论。
+5. test_package 验证：执行 bsdtar --version 确认工具和依赖版本字符串，内存 tar 读取
+   验证 libarchive 库 API，tar 创建-提取往返验证 CLI 完整性。
+
+```bash
+apply patches 0001-0003, configure --build=aarch64-unknown-linux-gnu --without-xml2, make, make check, make install
+```
+
+## 回退方案
+
+**manual-package-version**：若 config.guess 补丁无法干净应用（偏移较大或上游基线已变），可传递
+`--build=aarch64-unknown-linux-gnu` 并设置 `OHOS=1` 环境变量绕过检测；
+hmdfs 补丁应在 test_main.c 中定位当前版本的 assertion_file_mode 函数位置。
+
+```bash
+configure --build=aarch64-unknown-linux-gnu && make
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(__OHOS__|HarmonyOS).*OS.*skip|remove.*test.*registration|delete.*test.*case`
+- **原因**：平台宏不能替代逐条测试能力评估；删除注册项会掩盖回归
+- **后果**：测试套件注册数减少，能力恢复后不会自动补充覆盖
+
+### 🚫 禁止 2
+
+- **模式**：`(skip|ignore).*make.*check|make.*check.*skip`
+- **原因**：make check 是唯一的全量 L1 测试输出，跳过即失去适配证据
+- **后果**：无法证明上游测试在 OHOS 上实际运行状态
+
+### 🚫 禁止 3
+
+- **模式**：`conan.requires.*zlib/1.3.1[^.]|conan.requires.*zlib/1\.[^3]`
+- **原因**：非 -fPIC 的 zlib 版本无法链接共享库，会触发 aarch64 重定位错误
+- **后果**：构建失败，CI 报告 R_AARCH64_ADR_PREL_PG_HI21 错误
+
+### 🚫 禁止 4
+
+- **模式**：`--without-xml2.*--with-xml2|--with-xml2`
+- **原因**：libxml2 不在 conan 依赖图中，链接会引入不可控的系统库
+- **后果**：运行时依赖不可追踪，CI 构建不一致
+
+## 涉及软件
+
+基于 autotools 构建系统的 libarchive 系 CLI 工具（bsdtar, bsdcpio, bsdcat,
+bsdunzip）在 HarmonyOS PC（arm64）上适配时，涉及 config.guess 增强、hmdfs 文件系统
+兼容性、精确依赖冻结与测试套件平台差异分类的联动方案。相近的 libarchive 次版本
+（3.7.x 系列）可复用相同补丁思路，但 patch 上下文（test_main.c 中函数位置、config.guess
+基线）需要逐版本适配。
+
+## 相关模式
+
+- **相似模式**：[E007](E007.md)、[E011](E011.md)、[E079](E079.md)、[E129](E129.md)、[E041](E041.md)、[E005](E005.md)
+
+---
+*条目 E533 · 更新 2026-08-27 · 知识库同步生成物*