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

@@ -0,0 +1,96 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E220: OHOS true-device storage and runtime can diverge from
+
+> **严重度**: 🔴 blocking | **分类**: detection, toolchain, runtime, filesystem, permissions | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)、[P016](../principles.md#P016)、[P020](../principles.md#P020)
+
+---
+
+## 错误特征
+
+```
+ln.*Operation not permitted
+touch:.*Permission denied
+not writable by you
+Can't create.*lib/auto
+SIGSYS caught
+Can't set \$0 with prctl
+```
+
+## 根因
+
+OHOS true-device storage and runtime can diverge from
+POSIX/Linux assumptions in several independent ways:
+hardlink/symlink creation may be denied, metadata-only
+touch on generated executables may fail, -w or
+POSIX::access(W_OK) may not match actual create/unlink
+ability, and Configure may detect headers/symbols for
+runtime features that later fail with SIGSYS/EINVAL.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉;
+make test_harness_notty;
+perl -MConfig -MFile::Spec -e "print qq(ok\n)"
+```
+
+## 解决方案
+
+**composite-ohos-toolchain-adaptation**：Treat repeated build failures as a connected platform
+pattern instead of isolated patches: replace upstream
+link shortcuts with a copy-link wrapper that preserves
+relative-source semantics; remove timestamp-only touch
+steps on generated executables; replace unreliable
+permission predicates with actual create/unlink probes;
+and disable runtime features when true-device execution
+proves configure probes are false positives.
+
+```bash
+Set TMPDIR/TMPPREFIX to a build-local writable path;
+pass Configure through an explicit shell; set lns/LNS
+to an OHOS copy-link wrapper; patch writeability checks
+to probe create/unlink; disable misdetected runtime
+features such as IPC/SysV or HAS_PRCTL_SET_NAME when
+true-device tests prove SIGSYS/EINVAL failures.
+```
+
+## 回退方案
+
+**split-runtime-compatibility-followup**：If upstream runtime tests still fail after the build
+tool package is usable, classify remaining failures by
+filesystem, permissions, signal/timer, locale/timezone,
+direct script execution, or dynamic loader behavior and
+avoid mixing broad runtime compatibility work into a
+dependency-tool PR.
+
+```bash
+Record upstream file-level pass rate and per-file root
+cause closure in the package notes or failure analysis.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`Treat a successful Configure header/symbol probe as
+proof that the same feature is safe at runtime on OHOS.`
+- **原因**：True-device execution can still raise SIGSYS, EINVAL, or
+hang child processes after a successful compile probe.
+- **后果**：Packages may build but later fail or hang during their
+own upstream tests or downstream configure scripts.
+
+## 涉及软件
+
+Native interpreter or toolchain packages whose upstream
+build systems use link-as-copy shortcuts, timestamp
+refresh rules, Perl/ExtUtils-style install checks, or
+configure-time feature probes that are not enough to
+prove true-device runtime availability.
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)、[E018](E018.md)、[E050](E050.md)
+
+---
+*条目 E220 · 更新 2026-07-27 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E221: 同时提供 CLI 与公开库时应建模完整 Conan library 契约
+
+> **严重度**: 🔴 blocking | **分类**: cmake, linking, conan, packaging, api | **自动修复**: ❌ | **原则**: [P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+undefined symbol:.*
+set\([^)]*_LIBS_RELEASE\s*\)
+CMakeDeps.*target.*libs.*empty
+non-existent.*include
+```
+
+## 根因
+
+配方同时安装 CLI 和公开库却按 application 模型声明；生成依赖元数据可能不传播公开库，或默认 include/system library 元数据与安装物不一致，导致 target 缺库、缺系统依赖或引用不存在目录。
+
+## 验证命令
+
+```bash
+检查包内安装物和生成 target 数据；使用仅链接生成 target、不硬编码包路径或 -l 的消费者完成 configure、compile、link、run。
+```
+
+## 解决方案
+
+**model-cli-library-public-contract**：若开发库是公开契约，将包建模为 library，声明 shared 选项，按实际顺序填写 libs/system_libs；无公共头时 includedirs 为空，同时保留 bindirs 暴露 CLI。
+
+```bash
+检查安装的库、头和 bin；配置 package_type/options/cpp_info；用 CMakeDeps imported target 执行真实消费者。
+```
+
+## 回退方案
+
+**explicit-cli-only-contract**：若库只是内部副产物，则保持 CLI-only 并明确不承诺开发库，避免暴露半完整契约。
+
+```bash
+从公开 package_info 中移除不承诺的库接口并声明边界。
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`target_link_libraries.*(/|-[lL])|link_directories|find_library.*package_folder`
+- **原因**：test_package 硬编码路径或库参数会绕过生成元数据。
+- **后果**：测试假通过而真实下游仍失败。
+
+### 🚫 禁止 2
+
+- **模式**：`includedirs.*include.*不存在|盲填.*system_libs|盲填.*libs`
+- **原因**：库顺序、系统依赖和公共头目录必须由安装物与运行级消费者验证。
+- **后果**：产生二次链接或 CMake 配置失败。
+
+## 涉及软件
+
+Conan 2 中同时提供命令行工具与公开静态或共享库，并依赖 CMakeDeps 等生成器供下游消费的包。
+
+---
+*条目 E221 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E222: 非调试 HarmonyOS 设备在 ptrace 不可用时建立原生崩溃证据链
+
+> **严重度**: 🔴 blocking | **分类**: ohos, warnings, runtime, security | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P015](../principles.md#P015)
+
+---
+
+## 错误特征
+
+```
+ptrace: Permission denied
+DeviceDebuggable:No
+A packet returned an error: 8
+SIGSEGV\(SEGV_MAPERR\)
+```
+
+## 根因
+
+ptrace 调试入口不可用不等于无诊断能力；应把 FaultLogger、模块偏移、线程栈、进程映射、符号化、反汇编和证伪探针组合为证据链，避免由顶层 signal 或系统库 frame 直接猜根因。
+
+## 验证命令
+
+```bash
+重复复现并比较 signal、PC 模块偏移和业务 frame；用符号表与反汇编定位语句；对主要替代假设执行独立最小探针。
+```
+
+## 解决方案
+
+**faultlogger-evidence-chain**：ptrace 被拒时优先收集 FaultLogger 与 maps，完成模块偏移符号化和反汇编，并为主要假设保留证伪证据；修复后以完整设备负载确认。
+
+```bash
+采集 FaultLogger；记录 PC/模块/偏移/线程栈/maps；使用 llvm-addr2line 或 llvm-objdump；重复原负载并执行最小反假因探针。
+```
+
+## 回退方案
+
+**user-space-instrumentation**：FaultLogger 信息不足时，用受控日志、LD_PRELOAD 或定向探针补足用户态证据，但探针不能替代原负载 PASS。
+
+```bash
+在最小复现中增加地址、生命周期和返回值日志，再与 FaultLogger 时间点对应。
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ptrace.*denied.*无法诊断|只看.*SIGSEGV|只看.*allocator`
+- **原因**：调试器受限只关闭一种入口；顶层 signal 或系统库 frame 不能证明业务根因。
+- **后果**：容易误诊并扩大补丁。
+
+## 涉及软件
+
+HarmonyOS 非调试设备上稳定复现的 C/C++ 原生崩溃，尤其是 VM、runtime、编译器工具和多线程程序。
+
+---
+*条目 E222 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,67 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E223: secure tmp 需联合验证 owner、mode、MAC 与真实写入闭环
+
+> **严重度**: 🔴 blocking | **分类**: platform, hmdfs, environment, security | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+config\.status.*subs1\.awk.*Permission denied
+mktemp -d.*conf
+mode 2771
+Read-only file system.*EROFS
+```
+
+## 根因
+
+HMDFS 上目录存在、可创建或显示某个 mode 均不足以证明敏感临时数据满足 owner 隔离、权限位、MAC 域和后续写入语义；放宽 umask 或 chmod 777 会破坏 secure tmp 边界。
+
+## 验证命令
+
+```bash
+对候选临时根执行 owner UID/GID、目录 mode、文件 mode、MAC label 与 create/write/read/remove 探针，再运行真实 config.status。
+```
+
+## 解决方案
+
+**private-cache-capability-validation**：优先使用调用方注入或能力探测得到的 app-private cache；验证 owner、目录0700、文件0600、MAC域和真实写入闭环，失败则 fail-closed。
+
+```bash
+在候选目录创建私有子目录和文件，检查 stat 与安全标签，完成读写删除，再定向 secure temp 并执行 config.status。
+```
+
+## 回退方案
+
+**isolated-non-hmdfs-build-root**：无可验证私有缓存时，使用明确隔离且实测满足条件的非 HMDFS 构建根；不得回退到只读 /tmp 或宽权限目录。
+
+```bash
+由 launcher 注入隔离临时根并执行同一 owner/mode/MAC/IO 探针。
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`chmod 777|chmod a\+rwx|umask 0(00|22)`
+- **原因**：放宽 DAC 不能证明 MAC 和 owner 语义，且破坏敏感临时数据隔离。
+- **后果**：可能形成泄露、竞态或错误通用建议。
+
+### 🚫 禁止 2
+
+- **模式**：`/data/storage/el2/base/cache.*通用|固定.*app-private.*所有应用`
+- **原因**：固定路径只对特定身份、用户和 MAC 域有证据，不能跨环境泛化。
+- **后果**：其他身份下可能不可写或标签不匹配。
+
+## 涉及软件
+
+在 HarmonyOS/HMDFS 上运行 Autoconf config.status 或处理其他敏感临时数据的构建流程。
+
+## 相关模式
+
+- **相似模式**：[E206](E206.md)、[E110](E110.md)、[E112](E112.md)、[E118](E118.md)、[E175](E175.md)
+
+---
+*条目 E223 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E224: alternate signal stack 的拥有者线程注销与 backing memory 回收顺序
+
+> **严重度**: 🔴 blocking | **分类**: syscall, threading, runtime, memory | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P015](../principles.md#P015)
+
+---
+
+## 错误特征
+
+```
+SIGSEGV\(SEGV_MAPERR\).*free
+je_arena_dalloc_small
+TaskData::~TaskData
+free\(signalStack\)
+sigaltstack.*SS_DISABLE
+```
+
+## 根因
+
+线程注册 alternate signal stack 后，在拥有者线程生命周期结束前未完成注销，却由析构或 join 后路径释放 backing memory，形成注册资源与内存回收顺序冲突；具体平台表现可能是崩溃或悬空状态。
+
+## 验证命令
+
+```bash
+记录每线程 allocate/register/disable/exit/join/free 顺序和 sigaltstack 返回值；重复线程退出负载并结合崩溃日志验证。
+```
+
+## 解决方案
+
+**owner-thread-altstack-lifecycle**：当前 source event 在 OHOS 发现；实现应由 SA_ONSTACK 与 HAVE_SIGALTSTACK 能力探针门控，由拥有者线程在退出前注销 alternate stack，确认结果后再回收 backing memory；失败时不得无条件危险释放。
+
+```bash
+在拥有者线程退出或 TLS 清理前调用 sigaltstack(SS_DISABLE)，记录结果，再执行后续回收；用原始多线程负载重复验证。
+```
+
+## 回退方案
+
+**capability-scoped-disable**：仅在证明该能力不可用且功能可选时按能力边界禁用，并披露 profiling/信号保护回归。
+
+```bash
+增加能力探针和功能边界说明，不按平台名盲目关闭。
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`free\(.*signal.*stack|delete.*signal.*stack`
+- **原因**：未证明已注销就释放 backing memory，会破坏线程级信号资源生命周期。
+- **后果**：可能在退出、析构或 allocator 路径稳定崩溃。
+
+### 🚫 禁止 2
+
+- **模式**：`__OHOS__.*disable.*sigaltstack|所有POSIX平台.*必须`
+- **原因**：生命周期原则需结合具体实现和平台行为，不能由单一事件宣称所有 POSIX 平台绝对一致。
+- **后果**：形成过度泛化或不必要的功能禁用。
+
+## 涉及软件
+
+自行分配 alternate signal stack 的 VM、runtime、profiler、崩溃处理器及多线程信号程序。
+
+## 相关模式
+
+- **相似模式**：[E045](E045.md)
+
+---
+*条目 E224 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E225: CMakeToolchain source-side preset 与 Conan test-package 临时布局
+
+> **严重度**: 🔴 blocking | **分类**: conan, packaging, testing, security | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)
+
+---
+
+## 错误特征
+
+```
+CMakeUserPresets\.json
+Invalid configuration:.*BUILD_DIR
+test_package requires external BUILD_DIR
+```
+
+## 根因
+
+CMakeToolchain 默认可能向 test_package source 写入 CMakeUserPresets.json；recipe 若依赖非标准 shell BUILD_DIR，标准 conan create 不提供该变量，会在官方 CI 的 test_package layout 阶段失败。
+
+## 验证命令
+
+```bash
+在 unset BUILD_DIR 的标准 conan test/create 环境运行；确认 cmake_layout(build_folder="$TMP") 为每次调用创建不同临时根，build/generators 位于 source 外且 source 无 CMakeUserPresets.json。
+```
+
+## 解决方案
+
+**conan-managed-temporary-test-layout**：在已实测支持该特殊值的 Conan 版本中，保留 CMakeToolchain user_presets_path=False，并使用 cmake_layout(self, build_folder="$TMP")；当前证据限定 Conan 2.29.1，其以 tempfile.mkdtemp 创建遵循 TMPDIR 的每次调用唯一临时根。
+
+```bash
+先在目标 Conan 版本以 unset BUILD_DIR 的 graph/test 探针验证 "$TMP" 语义；确认支持后使用 cmake_layout(self, build_folder="$TMP")，并在 generate() 设置 tc.user_presets_path=False。
+```
+
+## 回退方案
+
+**conan-conf-test-folder**：若目标 Conan 版本不支持 test-package 的 "$TMP" 特殊值，使用该版本正式支持的 cmake_layout test_folder 配置指向调用方管理的唯一临时目录。
+
+```bash
+核验目标 Conan 版本文档与 layout 结果，再通过正式 conf 配置 test_folder；不得恢复 recipe 对非标准 BUILD_DIR 的硬依赖。
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`gitignore.*CMakeUserPresets|生成后.*删除.*CMakeUserPresets|os\.getenv\("BUILD_DIR"\)|requires external BUILD_DIR`
+- **原因**：ignore 或事后删除不能证明 source 零污染；BUILD_DIR 不是 Conan test_package 标准契约，官方 conan create 不保证提供。
+- **后果**：本地 launcher 注入变量时假通过，官方标准 conan create 在 test_package layout 阶段失败，或 source 出现生成文件。
+
+## 涉及软件
+
+使用 Conan 2 CMakeToolchain 的 test_package，要求 source 零生成物且必须在标准 conan create 环境独立运行的配方。
+
+---
+*条目 E225 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E226: Capture child output as bytes when HarmonyOS os.popen text decoding fails
+
+> **严重度**: 🟡 medium | **分类**: python | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+TypeError: can't concat str to bytes
+process_output = pipe\.read\(\)
+```
+
+## 根因
+
+The validated HarmonyOS Python 3.12 os.popen text wrapper feeds a str fragment into a codec path expecting bytes, so pipe.read raises TypeError before the caller can inspect child output or exit status.
+
+## 验证命令
+
+```bash
+Run the patched upstream CTest suite verbosely and require every logical case plus the final CTest summary to pass.
+```
+
+## 解决方案
+
+**capture-subprocess-bytes-explicitly**：Replace only the os.popen text wrapper with subprocess.PIPE byte capture, then decode once explicitly while preserving the command and return-code failure semantics.
+
+```bash
+subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT).communicate()[0].decode('utf-8', errors='replace')
+```
+
+## 回退方案
+
+**targeted-binary-pipe-wrapper**：If the upstream command requires a shell pipeline for HarmonyOS execution policy, retain that command but keep stdout in binary mode and decode after communicate().
+
+```bash
+Run the same command through the shell with stdout=PIPE and text mode disabled.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`except TypeError|skip.*runjsontests|JSONCPP_WITH_TESTS.*OFF`
+- **原因**：Suppressing the exception or disabling the suite hides unexecuted upstream tests.
+- **后果**：The package can be reported as tested even though parser and writer inputs never ran.
+
+## 涉及软件
+
+Python test drivers and build scripts on HarmonyOS PC that use os.popen().read() to capture output from native executables.
+
+## 相关模式
+
+- **相似模式**：[E055](E055.md)
+
+---
+*条目 E226 · 更新 2026-07-19 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E227: Distinguish unified patch context prefixes from source trailing whitespace
+
+> **严重度**: 🟡 medium | **分类**: patch | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+trailing whitespace\.
+new blank line at EOF\.
+raw patch line == ' '
+```
+
+## 根因
+
+A canonical unified diff prefixes every unchanged context line with one space; when the unchanged source line is empty, the patch file therefore contains a raw single-space line that an outer repository git diff --check can classify as blank-at-eol even though the patched source has no trailing whitespace.
+
+## 验证命令
+
+```bash
+Confirm the source edit has no trailing whitespace, classify each flagged raw single-space line as unified-diff context, then require git apply --check and GNU patch --dry-run --fuzz=0 -p1.
+```
+
+## 解决方案
+
+**split-source-and-patch-whitespace-validation**：Run git diff --check on non-patch changes and validate patch files with both Git and GNU patch parsers at zero fuzz.
+
+```bash
+git diff <base>...HEAD --check -- . ':(exclude,glob)**/*.patch'; git apply --check <patches>; patch --dry-run --fuzz=0 -p1 -d <source> -i <patch>
+```
+
+## 回退方案
+
+**framework-patch-whitespace-attributes**：In a separate framework PR, narrowly configure patch-file whitespace attributes while retaining all non-patch whitespace checks.
+
+```bash
+*.patch whitespace=-blank-at-eol,-blank-at-eof
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`remove.*source.*blank|strip.*context|unified.*n=0|disable.*whitespace`
+- **原因**：These workarounds either change unrelated source formatting, weaken patch placement evidence, corrupt canonical context, or hide genuine non-patch whitespace defects.
+- **后果**：The patch may become less reviewable or unsafe while real whitespace regressions go undetected.
+
+## 涉及软件
+
+New or renamed canonical unified patch files audited as ordinary text by an outer Git repository.
+
+---
+*条目 E227 · 更新 2026-07-19 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E228: HMDFS 上无扩展名 Libtool 测试 wrapper 无法直接启动
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, testing, permissions, libtool | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+Permission denied.*test/
+LOG_COMPILER.*Permission denied
+libtool.*wrapper.*cannot execute
+```
+
+## 根因
+
+Automake/Libtool 为动态链接测试生成与测试 ELF 同名的无扩展名 shell wrapper，真实 ELF 位于相邻 .libs 目录。HMDFS 权限语义可能阻止 wrapper 直接执行，而它没有 .sh 后缀，普通脚本规则无法识别；同时静态或非 Libtool 测试本身是真实 ELF，不能统一交给 shell 解释。
+
+## 验证命令
+
+```bash
+for t in test/*; do test -f "${t%/*}/.libs/${t##*/}" && file "$t" "${t%/*}/.libs/${t##*/}"; done
+```
+
+## 解决方案
+
+**conditional-log-compiler-launcher**：给 Automake LOG_COMPILER 提供 launcher；对首个测试参数计算同目录 .libs/<basename>，存在该真实 ELF 时用 HarmonyOS shell 启动外层 wrapper，否则直接 exec 原测试。launcher 自身也通过已知 shell 启动，不依赖执行位。
+
+```bash
+candidate="${1%/*}/.libs/${1##*/}"; if test -f "$candidate"; then exec /system/bin/sh "$@"; else exec "$@"; fi
+```
+
+## 回退方案
+
+**relocate-build-tree**：若 LOG_COMPILER 不能覆盖上游测试驱动，将构建和测试迁移到允许脚本正常执行的目标机文件系统，再保持原 make check 判定。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LOG_COMPILER=.*sh(?!.*\.libs)|exec /system/bin/sh \"\$@\".*unconditional`
+- **原因**：将所有测试统一交给 shell 会把真实 ELF 当脚本解析，制造新的失败或掩盖测试类型差异。
+- **后果**：非 Libtool 测试无法运行，make check 结果失真。
+
+### 🚫 禁止 2
+
+- **模式**：`chmod \+x.*wrapper|skip.*Permission denied`
+- **原因**：HMDFS 上 chmod 可能不改变有效执行权限；跳过 wrapper 会减少上游测试覆盖。
+- **后果**：问题仍复现，或以删减测试伪造通过。
+
+## 涉及软件
+
+在 HarmonyOS HMDFS 工作目录运行 Automake make check，且测试集合同时包含 Libtool wrapper 和直接 ELF 的项目。
+
+## 相关模式
+
+- **相似模式**：[E087](E087.md)、[E129](E129.md)
+
+---
+*条目 E228 · 更新 2026-07-19 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E229: 缺失 libc API 时独立测试未链接库内 fallback 对象
+
+> **严重度**: 🟡 medium | **分类**: libc, linking, runtime, testing | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+undefined reference to [`']?(explicit_bzero
+[a-zA-Z0-9_]+)[`']?.*test
+symbol not found.*fallback
+```
+
+## 根因
+
+目标 libc 缺少某 API 时，上游会把 fallback 实现编入主库并可能设为 hidden；独立测试目标若只链接公共测试对象而不链接主库或准确的 fallback 对象，链接器仍找不到该符号。共享库中的 hidden fallback 也不能作为外部符号满足测试目标。
+
+## 验证命令
+
+```bash
+grep -R -n 'fallback\|explicit_bzero' Makefile.am lib test; readelf -Ws .libs/*.so | grep -E 'HIDDEN|LOCAL'
+```
+
+## 解决方案
+
+**link-exact-fallback-object**：确认失败测试真实调用链和 fallback 对象来源，把准确的 libtool object 加入该测试目标 LDADD；若 CI 使用发布 tarball 且不运行 autoreconf，同步对应 Makefile.in。随后执行完整 make check，保持原断言和 SKIP 规则。
+
+```bash
+test_target_LDADD = lib/libname_la-fallback.lo $(COMMON_TEST_OBJECTS)
+```
+
+## 回退方案
+
+**link-test-against-library**：仅当上游测试语义允许且不会形成递归依赖时，让测试链接已包含 fallback 的主库；需确认 symbol visibility 足以满足该测试。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*undefined reference|disable.*test|return 0.*OHOS`
+- **原因**：链接失败暴露真实适配缺口，删除测试或平台空壳会伪造通过。
+- **后果**：fallback 路径和嵌套调用行为完全未验证。
+
+### 🚫 禁止 2
+
+- **模式**：`export.*hidden.*fallback|visibility.*default.*test`
+- **原因**：为测试扩大内部 fallback 的导出范围会改变库 ABI；测试应链接准确对象而非污染公共符号表。
+- **后果**：无意新增公共 ABI，可能造成符号冲突。
+
+## 涉及软件
+
+自带 libc 兼容 fallback、并用独立 Automake/Libtool 测试可执行文件验证内部并发或嵌套行为的 C/C++ 项目。
+
+## 相关模式
+
+- **相似模式**：[E213](E213.md)
+
+---
+*条目 E229 · 更新 2026-07-19 · 知识库同步生成物*