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

@@ -0,0 +1,46 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E484: OHOS patch --dry-run 真实创建文件，污染 .orig 基线目录
+
+> **严重度**: 🟡 medium | **分类**: platform, limitation, ohos | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+creating
+patch --dry-run
+--dry-run -p1
+source/target file does not exist
+```
+
+## 根因
+
+HarmonyOS PC 的 GNU patch 在 --dry-run 模式下仍会真实创建新文件（0 字节占位），
+而非仅预览。refresh-patch 的 _dry_run() 在 .orig 目录执行 patch --dry-run，
+导致新增源文件（如 core.go）被写成 0 字节占位文件；下次 refresh-patch
+据此误判该文件"已存在"，生成 --- a/xxx 而非 --- /dev/null 的新文件补丁，
+conan apply_conandata_patches (patch_ng) 报 source/target file does not exist。
+
+## 验证命令
+
+```bash
+printf -- '--- /dev/null\n+++ b/t.go\n@@ -0,0 +1 @@\n+x\n' | patch --dry-run -p1; ls t.go 2>/dev/null && echo "OHOS 上 dry-run 创建了文件"
+```
+
+## 解决方案
+
+**baseline-restore**：每次 finish/refresh-patch 前，从原始 tarball 恢复干净的 .orig 基线目录，
+删除其中的 0 字节占位文件，使新增文件被正确识别为 /dev/null 新文件
+
+```bash
+rm -f ${ORIG_DIR}/${REL_NEW_FILE}; # 或重新解压 tarball 到 .orig
+```
+
+## 涉及软件
+
+HarmonyOS PC 上所有使用 refresh-patch --auto / patch 生成补丁的 Go/C 项目
+
+---
+*条目 E484 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E485: OHOS 沙箱/无硬件环境（无 JTAG ICE/USB 调试器等外设）——库（avarice——
+
+> **严重度**: 🟡 medium | **分类**: ohos, autotools, hardware, libusb, peripheral | **自动修复**: ✅ manual
+
+---
+
+## 错误特征
+
+```
+.*usb\.h.*No such file.*
+.*usb_get_string_simple.*undefined reference
+.*libusb-1.0 not found
+```
+
+## 根因
+
+OHOS 沙箱/无硬件环境（无 JTAG ICE/USB 调试器等外设）——库（avarice——
+AVR JTAG ICE 调试器——连接 GDB 与 Atmel AVR JTAG ICE）依赖硬件外设库
+（libusb-0.1——USB 接口——libusb_open/usb_get_string_simple 等）——
+configure 的 AC_CHECK_LIB([usb], [usb_get_string_simple]) 检查不硬失败（无
+AC_MSG_ERROR——configure 能过）——但编译（jtag2usb.cc——#include <usb.h>——
+15 个 usb_* API）需要外设库的头文件 + 链接符号——无硬件环境下外设库依赖
+无法满足（libusb-compat 无配方/不在制品仓——无法直接依赖）
+
+## 验证命令
+
+```bash
+构建对比：直接依赖外设库（configure 检查失败/编译缺头——
+usb.h No such file）vs stub 方案（stub 头 + stub 实现——编译链接通过——
+bin 生成——如实记录 stub 不伪造功能）
+```
+
+## 解决方案
+
+**stub 绕过（生成 stub 外设头（声明外设 API）+ stub 实现（返回
+-1/0——无硬件——功能不实际使用）——CPPFLAGS -I stub + 编译 stub 对象 +
+链接追加（make LIBS/LDFLAGS））**：stub 绕过（生成 stub 外设头（声明外设 API）+ stub 实现（返回 -1/0——无硬件——功能不实际使用）——CPPFLAGS -I stub + 编译 stub 对象 + 链接追加（make LIBS/LDFLAGS））
+
+```bash
+# 生成 stub 头（声明外设 API——libusb-0.1 的 15 个 usb_*）+ stub 实现
+# （返回 -1/0——无硬件——功能不实际使用——R9/R34 合规如实记录）
+stub_dir = os.path.join(build_folder, "stub"); os.makedirs(stub_dir, exist_ok=True)
+# stub usb.h：typedef struct usb_device usb_dev_handle; + usb_init/usb_find_busses/
+#   usb_find_devices/usb_get_busses/usb_open/usb_close/usb_get_string_simple/
+#   usb_bulk_read/usb_bulk_write/usb_claim_interface/usb_release_interface/
+#   usb_resetep/usb_set_configuration/usb_error/usb_daemon 声明
+# stub usb_stub.c：各函数返回 0/-1（无硬件）
+clang -c stub/usb_stub.c -I stub -o stub/usb_stub.o
+CPPFLAGS += -I stub_dir          # 编译源文件找到 stub 头
+make LIBS='... {stub_dir}/usb_stub.o'   # 链接满足 usb_* 符号
+```
+
+## 回退方案
+
+**如实记录环境限制（无硬件环境——外设库依赖无法满足——PR
+如实披露——申请硬件/特权环境）**
+
+```bash
+"如 stub 方案不可行（外设功能被实际调用且需真实现）——PR 评论
+如实记录（不得伪造通过——R9）"
+```
+
+## 涉及软件
+
+OHOS 上适配依赖硬件外设库（USB/串口/GPIO/调试器等）的工具/库
+（调试器、烧录器、传感器工具等）——无硬件环境——configure 依赖检查可过
+但编译/链接需要外设 API——stub 方案可复用
+
+---
+*条目 E485 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,79 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E486: 引导构建中在宿主 ELF 首次执行前签名并保持最终编译器为原生 ELF
+
+> **严重度**: 🟢 minor | **分类**: ohos, autotools, toolchain, linking, conan | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P013](../principles.md#P013)、[P016](../principles.md#P016)、[P019](../principles.md#P019)
+
+---
+
+## 错误特征
+
+```
+Permission denied.*(gen
+cc1
+xgcc
+avr-gcc)
+Operation not permitted.*(gen
+cc1
+xgcc)
+missing [.]codesign.*(cc1
+avr-gcc)
+Exec format error.*build helper
+```
+
+## 根因
+
+GCC 等引导构建会交错执行“由宿主编译器链接辅助程序”和“立即运行该程序”两个阶段。HarmonyOS 要求宿主 ELF 具有有效 .codesign，等到 make 完成或 package() 再批量签名已经太晚。编译器包装器还必须区分宿主 EXEC/DYN 与目标对象、汇编输出及 AVR ELF；若把最终 avr-gcc 替换为 shell 包装器，又会改变工具身份、相对路径和下游探测语义。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**link-interception-sign-before-first-exec**：仅在 OHOS 宿主构建环境中以 CC/CXX 包装真实编译器。真实编译器成功返回后解析 -o 和编译阶段参数，用 readelf 只识别宿主 EXEC/DYN；对命中的输出先移除旧 .codesign，再签名到同目录临时文件，确认新签名段后原子替换并恢复执行位。通过 SHELL 显式解释位于 HMDFS 的包装脚本。阶段目标完成和 package() 后再扫描补签遗漏的宿主 ELF，但最终 avr-gcc、cc1 仍以签名后的原生 ELF 交付。test_package 必须直接运行 avr-gcc，确认版本和包内 libgcc，再链接并检查目标 AVR ELF。
+
+```bash
+real compiler -> classify output with readelf -> remove stale .codesign -> sign temporary file -> verify .codesign -> replace before make executes the host tool
+```
+
+## 回退方案
+
+**explicit-build-target-signing-barriers**：若构建系统能稳定划分宿主工具生成与首次执行阶段，可在每个阶段边界扫描并签名新 ELF 后再继续下一目标；必须证明没有同一 make target 内的“链接后立即执行”，并保留最终原生工具验证。
+
+```bash
+build host-tool target; sign and verify every new host EXEC/DYN; continue dependent target
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`sign.*only.*(package|install)|package.*then.*codesign`
+- **原因**：GCC 的构建期宿主辅助程序会在 package() 之前首次执行，末端批量签名无法挽救已经失败的构建。
+- **后果**：构建在生成器或编译器内部工具首次启动时以 Permission denied/Operation not permitted 中止。
+
+### 🚫 禁止 2
+
+- **模式**：`sign.*(all outputs|[.]o|[.]a|avr target)|binary-sign-tool.*without.*readelf`
+- **原因**：编译器输出同时包含宿主 ELF、目标对象、静态库和 AVR ELF，不能按存在性或执行位盲签。
+- **后果**：目标产物被错误修改，增量构建不稳定，或签名工具对非宿主 ELF 失败。
+
+### 🚫 禁止 3
+
+- **模式**：`avr-gcc[.]real|replace.*avr-gcc.*shell|installed.*compiler.*wrapper`
+- **原因**：将最终编译器替换为 shell 启动器改变原生 ELF 身份及 GCC 的相对路径、程序名和下游工具探测语义。
+- **后果**：test_package 可能只验证包装层，真实驱动、cc1 或包内 libgcc 解析仍可损坏。
+
+## 涉及软件
+
+在 HarmonyOS 上原生构建且会在同一构建图中生成并立即执行宿主工具的编译器、代码生成器和自举工具链；不适用于只交叉生成目标二进制且构建期从不执行它们的普通项目。
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)、[E087](E087.md)、[E311](E311.md)
+
+---
+*条目 E486 · 更新 2026-08-17 · 知识库同步生成物*

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

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E487: KF6 上游（ECMPoQmTools.cmake:155）在 configure 阶段调用
+
+> **严重度**: 🟡 medium | **分类**: cmake, conan, kf6, linguisttools, qt6 | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Could NOT find Qt6LinguistTools (missing: Qt6LinguistTools_DIR)
+Failed to find required Qt component "LinguistTools"
+Expected Config file at .*lib/cmake/Qt6LinguistTools/Qt6LinguistToolsConfig.cmake.* does NOT exist
+ECMPoQmTools\.cmake:155 \(find_package\)
+```
+
+## 根因
+
+KF6 上游（ECMPoQmTools.cmake:155）在 configure 阶段调用
+find_package(Qt6 COMPONENTS LinguistTools) 做 poqm 翻译。
+qtbase 包不提供 Qt6::LinguistTools 组件（LinguistTools 实体
+由 qttools 构建产生：lrelease/lupdate/lconvert +
+Qt6LinguistToolsConfig.cmake）。Qt6Config.cmake 的组件解析
+锚定 Qt6_DIR（qtbase 的 lib/cmake/Qt6）相对路径，因此
+单独发布安装的 qt6linguisttools 包不会被自动发现，
+即使其 builddirs 已加入 CMAKE_PREFIX_PATH，configure 仍报
+"Failed to find required Qt component LinguistTools"。
+
+## 验证命令
+
+```bash
+conan create . -pr:h=〈外部知识库流水线〉 -pr:b=same; r03 实测：接入 tool_require + Qt6LinguistTools_DIR 后 conan create 全绿 （ECMPoQmTools find_package 成功，libKF6DNSSD 构建成功， test_package 2/2 通过含鸿蒙特有测试 test_kdnssd_ohos）
+```
+
+## 解决方案
+
+**qt6linguisttools-tool-require-plus-pin-DIR**：1) 将 qt6linguisttools/6.11.1（ohpcd 已发布，revision 021a6867…，与 Qt 6.11.1 匹配）
+作为构建期 tool_requires 声明；
+2) generate() 中显式设置 CMakeToolchain 变量
+Qt6LinguistTools_DIR = <qt6linguisttools 包>/lib/cmake/Qt6LinguistTools，让
+ECMPoQmTools 的 find_package(Qt6 COMPONENTS LinguistTools) 直接命中独立包；
+3) 在 conan_cmakedeps_paths.cmake 追加其 lib/cmake 与 lib/cmake/Qt6LinguistTools
+到 CMAKE_PREFIX_PATH/CMAKE_MODULE_PATH。禁止 --build=missing 从源码重编 qttools。
+
+```bash
+self.tool_requires("qt6linguisttools/6.11.1")  +  tc.variables["Qt6LinguistTools_DIR"]=os.path.join(ltt.package_folder,"lib","cmake","Qt6LinguistTools")
+```
+
+## 回退方案
+
+**禁用 poqm（不推荐：丢失上游翻译）**：在 generate() 关闭 ecm_install_po_files_as_qm / 跳过 poqm 步骤
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`--build=missing.*qttools|--build=missing.*qt6linguisttools`
+
+## 涉及软件
+
+使用 ECMPoQmTools/poqm 且 Qt 组件分包发布的 KF6/Qt6 库
+（kdnssd、其他含翻译的 KF6 库）在 HarmonyOS PC 上的适配
+
+---
+*条目 E487 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,71 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E488: OHOS HMDFS 文件系统强制文件 owner 为 20001006:file_manager（权限 770）——
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, ohos, python, permissions, dlopen | **自动修复**: ✅ manual
+
+---
+
+## 错误特征
+
+```
+Error loading shared library .*notmuch2.*
+import notmuch2 失败.*Permission denied
+dlopen.*permission denied
+```
+
+## 根因
+
+OHOS HMDFS 文件系统强制文件 owner 为 20001006:file_manager（权限 770）——
+CI 用户 100 不在 owner/组——os.chmod 对非 owner 静默失败（实测 chmod 777 后
+权限仍为 770）——conan 打包/解包保留 owner——Python C 扩展（.so）dlopen 被拒
+（Permission denied）——test_package 直接 import 包目录 .so 失败
+
+## 验证命令
+
+```bash
+python3 -c "import ctypes; ctypes.CDLL('<site-packages>/<pkg>/_capi.abi3.so')"；
+对比：直接加载（Permission denied）/ 复制包+open/write 重写 .so 后加载（成功）
+```
+
+## 解决方案
+
+**copy-rewrite（复制整个包到可写目录 + open/write 逐字节重写 .so + chmod 777 + rename）**：copy-rewrite（复制整个包到可写目录 + open/write 逐字节重写 .so + chmod 777 + rename）
+
+```bash
+# 适用前提：源 .so 必须可读（owner 在 euid 组内）——CI 用户 100 无法读
+# owner 20001006 的 770 .so 时第一步（copytree/read 源 .so）也失败——
+# 此方案仅适用于本地/可读环境（euid 在 file_manager 组内）；CI 场景走
+# fallback（如实记录环境限制——申请特权环境）
+tmpdir = tempfile.mkdtemp(prefix="pkg_"); os.chmod(tmpdir, 0o777)
+shutil.copytree(site_pkg + "/<pkg>", tmpdir + "/<pkg>")
+so = tmpdir + "/<pkg>/_capi.abi3.so"; so_tmp = so + ".tmp"
+open(so_tmp,"wb").write(open(so,"rb").read()); os.chmod(so_tmp,0o777)
+os.remove(so); os.rename(so_tmp, so); sys.path.insert(0, tmpdir); import <pkg>
+```
+
+## 回退方案
+
+**如实记录环境限制（CI 用户 100 无法 dlopen owner 20001006 的 .so——申请特权环境）**
+
+```bash
+如多方案仍失败——PR 评论如实记录（不得伪造通过——R9）
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(?s)except ImportError.*print\(f?"NOTE.*print\(f?"OK"\)|except ImportError:.*pass`
+- **原因**：import 失败被 except 吞掉后脚本恒以 0 退出——伪通过（R9 禁止）——
+aireview 对 notmuch2 test_package 明确要求 import 失败 sys.exit(1)
+- **后果**：门禁判定为伪通过（R9）——airview 意见不通过
+
+## 涉及软件
+
+所有打包含 C 扩展（.so）的 Python 包（cffi/cython/手写扩展）在
+OHOS 的 test_package 消费验证（import 真实加载场景）——本地 euid 在
+file_manager 组内可读（PASS），CI 用户 100 不在组（FAIL）的判例差异
+
+---
+*条目 E488 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E489: OHOS 上 CTest 必须在执行前签名构建树的完整 ELF 加载闭包
+
+> **严重度**: 🔴 blocking | **分类**: testing, security, dynamic-loading | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+CTest.*(Failed
+Permission denied
+Operation not permitted)
+dlopen.*(Permission denied
+Operation not permitted
+failed)
+Error loading shared library.*Permission denied
+```
+
+## 根因
+
+Conan 的 build() 在 package() 之前执行；若只在 package() 中签名安装产物，CTest 实际运行的构建树 ELF 仍未签名。动态测试的运行闭包不只包含测试可执行文件，还可能包含 LD_PRELOAD 库、普通共享库和运行时 dlopen 的 MODULE/plugin。只签测试入口或只签 package_folder 都会遗漏加载对象并在运行期失败。
+
+## 验证命令
+
+```bash
+ctest -N && llvm-readelf -S <test-and-loaded-elf> | grep codesign && ctest --output-on-failure --verbose -j1
+```
+
+## 解决方案
+
+**sign-build-tree-runtime-closure**：在调用 CTest 前枚举测试入口及其构建树加载闭包，仅选择普通 ELF 文件，先移除已有 .codesign 段再统一签名；签名工具缺失或任一文件签名失败时立即终止。签名完成后使用私有可写 TMPDIR 执行完整 CTest。
+
+```bash
+llvm-objcopy --remove-section .codesign <elf> && binary-sign-tool sign -inFile <elf> -outFile <elf> -selfSign 1 && TMPDIR=<writable-dir> ctest --output-on-failure --verbose -j1
+```
+
+## 回退方案
+
+**stage-and-sign-test-runtime**：若构建树不可原地修改，将测试入口和全部加载对象按原相对布局复制到独立运行目录，统一签名后从该目录执行；仍须证明没有从未签名构建树回退加载对象。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`sign.*package_folder.*after.*ctest|package-time signing only`
+- **原因**：package() 晚于 build()，无法修复已经在 build() 中执行的 CTest。
+- **后果**：配方可编译但上游测试在加载构建树 ELF 时失败，或被迫关闭测试。
+
+### 🚫 禁止 2
+
+- **模式**：`sign.*test executable only|ctest.*ignore_errors|ctest.*\|\| true`
+- **原因**：测试入口通过不代表其 LD_PRELOAD、共享库和插件闭包均可加载，忽略退出码还会制造假通过。
+- **后果**：动态加载路径缺少验证，测试结果不可用于高难度适配证明。
+
+## 涉及软件
+
+在 OHOS 上从 CMake/CTest 构建树直接运行测试，且测试会通过动态依赖、LD_PRELOAD、dlopen 或插件机制加载同一构建树 ELF 的 Conan 配方。
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)、[E212](E212.md)
+
+---
+*条目 E489 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E490: Restore Autotools helper execute bits before configure
+
+> **严重度**: 🟡 medium | **分类**: ohos, autotools, conan, filesystem, execute-permission | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+Permission denied
+configure.*cannot execute
+config\.guess.*Permission denied
+config\.sub.*Permission denied
+```
+
+## 根因
+
+Autotools helper scripts are executable programs, but some HarmonyOS PC adaptation paths preserve source content without preserving POSIX execute mode bits. The build can fail before compilation even though the generated scripts are otherwise valid.
+
+## 验证命令
+
+```bash
+Run clean conan create on HarmonyOS PC CI or target runner; require configure to complete, upstream make -j1 check to pass, and Conan test_package to pass with explicit pass rates.
+```
+
+## 解决方案
+
+**restore-known-autotools-script-modes**：Before configure, walk the recipe, source, and build folders and add owner/group/other execute bits only to known Autotools helper scripts. Then run configure and make check as part of the recipe build.
+
+```bash
+chmod +x configure config.guess config.sub install-sh missing; ./configure; make -j1; make -j1 check
+```
+
+## 回退方案
+
+**regenerate-autotools-files**：If helper scripts are missing or generated for the wrong project state, regenerate them with the upstream-supported bootstrap/autoreconf flow, then restore execute bits and rerun the full test target.
+
+```bash
+autoreconf -fi
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`chmod -R \+x`
+- **原因**：Making the whole source tree executable hides metadata problems and can package or execute unintended files.
+- **后果**：The package can gain noisy mode changes and future audits cannot tell which generated scripts actually needed execute bits.
+
+### 🚫 禁止 2
+
+- **模式**：`make(?!.*check)|pending CI log|pending current CI`
+- **原因**：A build-system permission fix changes how upstream scripts execute and must be validated by upstream tests, not only by compilation or placeholder PR text.
+- **后果**：Reviewers cannot confirm the real upstream test pass rate or whether helper-script execution changed runtime behavior.
+
+## 涉及软件
+
+Conan recipes for Autotools packages whose source trees include configure, config.guess, config.sub, install-sh, or missing and are built or transferred through OHOS/HMDFS-style paths.
+
+---
+*条目 E490 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,70 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E491: Harden legacy Autotools packages for HMDFS and staged OHOS installs
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, autotools, legacy-c, staged-install | **自动修复**: ❌ | **原则**: [P003](../principles.md#P003)、[P005](../principles.md#P005)、[P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+Permission denied.*configure
+cannot create.*subs1\.awk
+multiple definition
+install.*(/bin
+/share)
+```
+
+## 根因
+
+Legacy generated Autotools files can assume directly executable source scripts, private temporary directories that remain usable by child processes, common-symbol merging, and recursive install rules that honor the selected prefix without an explicit staging root. These assumptions fail independently on OHOS/HMDFS and with modern Clang defaults.
+
+## 验证命令
+
+```bash
+Confirm the official swftools-0.9.2 archive declares lib/python test1-test6 and lib/action test but omits their six test_*.py scripts and test.c, recording N_declared=7 and N_runnable=0; then run a clean single-package build on the HarmonyOS PC runner and require configure/build/install, package signing, and the swfc -> SWF -> swfdump test_package path (M=1) to pass 1/1.
+```
+
+## 解决方案
+
+**patch-each-autotools-failure-layer-and-run-end-to-end**：Invoke a readable configure script through sh when direct execution is unreliable; create a per-build writable TMPDIR with compatible permissions; replace tentative definitions with extern declarations plus one definition; propagate DESTDIR through every recursive Makefile.in install rule; distinguish declared upstream tests from files actually present in the release archive; then validate a real generated artifact with another packaged command.
+
+```bash
+sh configure <args> && make -j1 && make DESTDIR=<package-root> install
+```
+
+## 回退方案
+
+**isolate-and-classify-each-build-stage**：If the package still fails, separate script execution, configure temporary files, compilation/linking, recursive install, signing, and runtime validation so an environment resource failure is not misclassified as a library defect.
+
+```bash
+Re-run only after checking device process and memory pressure, preserving the same source and recipe revision.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(^|\s)-fcommon(\s|$)`
+- **原因**：A global compiler compatibility flag hides invalid declaration/definition relationships in old source code.
+- **后果**：Duplicate or ambiguous global state remains and can fail again under another compiler or link mode.
+
+### 🚫 禁止 2
+
+- **模式**：`make install(?!.*DESTDIR)`
+- **原因**：A prefix alone does not protect the target root when legacy recursive install rules use absolute bin, share, or man paths.
+- **后果**：Packaging can write outside the Conan package directory or fail on protected target directories.
+
+### 🚫 禁止 3
+
+- **模式**：`retry.*(can't fork|Errno 12)`
+- **原因**：Process or memory exhaustion must be classified with device resource evidence before changing package code.
+- **后果**：Repeated heavy runs consume the shared device window and can produce unrelated recipe changes.
+
+## 涉及软件
+
+Legacy Autotools command-line packages built in OHOS/HMDFS workspaces and installed into isolated Conan package directories.
+
+---
+*条目 E491 · 更新 2026-08-18 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E492: Materialize Meson shared-library aliases when OHOS does not expose SONAME names
+
+> **严重度**: 🟡 medium | **分类**: meson, linking, packaging, runtime, testing | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P012](../principles.md#P012)、[P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+Error loading shared library lib[^ ]+\\.so\\.0
+NEEDED.*lib[^ ]+\\.so\\.0
+lib[^ ]+\\.so\\.0.*symbol not found
+meson test.*exit status 127
+```
+
+## 根因
+
+Meson built the real versioned library, but the OHOS build/install tree did not expose the SONAME and developer-name aliases that the runtime loader and consumers search for. Adding only LD_LIBRARY_PATH is insufficient when the exact NEEDED filename is absent.
+
+## 验证命令
+
+```bash
+find <build>/ -name 'lib*.so*' -exec ls -l {} +; readelf -d <test-binary> | grep -E 'NEEDED|RUNPATH'; run meson test and Conan test_package with isolated runtime paths.
+```
+
+## 解决方案
+
+**build-and-package-soname-alias-materialization**：After meson build and after meson install, ensure the real versioned shared library has the SONAME alias and developer alias in the relevant build or package lib directory. Prefer relative symlinks on capable filesystems and fall back to copying the real ELF when symlinks are denied.
+
+```bash
+ensure libfoo.so.X and libfoo.so exist next to libfoo.so.X.Y.Z before meson test and after install
+```
+
+## 回退方案
+
+**configure-unversioned-shared-library-if-upstream-supports-it**：If the project supports disabling versioned SONAME layout without losing ABI information, configure an unversioned shared object and validate DT_NEEDED/SONAME explicitly.
+
+```bash
+meson configure -Ddefault_library=shared; readelf -d libfoo.so
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LD_LIBRARY_PATH=.*only|prepend_path\\(\"LD_LIBRARY_PATH\"`
+- **原因**：Runtime search paths cannot load a missing SONAME filename; the required alias must exist.
+- **后果**：Meson tests or consumers still fail with Error loading shared library even though the directory is in LD_LIBRARY_PATH.
+
+### 🚫 禁止 2
+
+- **模式**：`copy only .*lib.*\\.so($| )`
+- **原因**：The loader resolves the exact NEEDED name, usually the SONAME alias, not only the developer library name.
+- **后果**：Link can pass while runtime execution fails after cache relocation or isolated testing.
+
+### 🚫 禁止 3
+
+- **模式**：`skip.*meson test|tests.*disabled`
+- **原因**：The failure is in runtime artifact layout, not in upstream test logic.
+- **后果**：A broad skip hides loader and packaging defects that consumers will hit.
+
+## 涉及软件
+
+Meson packages on HarmonyOS PC that build shared libraries named like libfoo.so.X.Y.Z while tests or consumers need libfoo.so.X or libfoo.so.
+
+## 相关模式
+
+- **相似模式**：[E274](E274.md)、[E316](E316.md)
+
+---
+*条目 E492 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E493: OHOS musl libc 无 glibc 扩展符号 program_invocation_name（链接报 undefined symb
+
+> **严重度**: 🟡 medium | **分类**: ohos | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+use of undeclared identifier 'program_invocation_name'
+```
+
+## 根因
+
+OHOS musl libc 无 glibc 扩展符号 program_invocation_name（链接报 undefined symbol）
+
+## 验证命令
+
+```bash
+待补：条目级验证命令未随草稿记录；条目来自已合并 PR，CI 验证以 PR 记录为准
+```
+
+## 解决方案
+
+**__OHOS__ 下改用 __progname（extern "C" char *__progname）**：__OHOS__ 下改用 __progname（extern "C" char *__progname）
+
+```bash
+test/_test_main.cpp: 定义 getprogname() 时区分 __OHOS__
+```
+
+## 涉及软件
+
+undeclared, identifier, 'program_invocation_name'。根因: OHOS musl libc 无 glibc 扩展符号 program_invocation_name（链接报 undefined symbol）
+
+---
+*条目 E493 · 更新 2026-08-12 · 知识库同步生成物*