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

@@ -0,0 +1,47 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E377: Bind test-only ExternalProject sources locally without reducing the upstream test inventory
+
+> **严重度**: 🔴 blocking | **分类**: cmake, externalproject, offline-source, upstream-tests | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Performing download step \(git clone\) for 'KWStyle'
+KWStyle-download.*Command failed
+```
+
+## 根因
+
+Enabling a project's real upstream tests may activate a test-tool ExternalProject whose build-time Git clone is unavailable on the target even though the main source is frozen.
+
+## 验证命令
+
+```bash
+Freeze the exact auxiliary source archive, configure ExternalProject with DOWNLOAD_COMMAND empty and an exact SOURCE_DIR, reject missing or hash-mismatched source, then run the complete upstream inventory.
+```
+
+## 解决方案
+
+**checksum-bound-local-externalproject-source**：Keep the upstream test entry enabled, fetch the fixed auxiliary revision during recipe source acquisition, and bind the extracted local directory into ExternalProject with downloads forbidden.
+
+```bash
+Set a project-specific local source directory, enable the no-download gate, and require generated ExternalProject dirinfo to report method=source_dir with an empty command.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ITK_USE_KWSTYLE.*OFF|BUILD_TESTING.*OFF|skip.*upstream.*test`
+- **原因**：Disabling the test tool or BUILD_TESTING reduces the existing upstream inventory instead of fixing the offline source boundary.
+- **后果**：A partial test run can be misreported as complete.
+
+## 涉及软件
+
+CMake projects that build test tools through ExternalProject during an offline or network-restricted target build.
+
+---
+*条目 E377 · 更新 2026-08-15 · 知识库同步生成物*

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

@@ -0,0 +1,47 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E378: Run Conan source probes only from an isolated recipe copy
+
+> **严重度**: 🟡 medium | **分类**: platform, conan2, source-folder, worktree-contamination | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Calling source\(\) in .*archives.*
+conan source.*unrecognized arguments.*output-folder
+```
+
+## 根因
+
+Conan 2.29.1 does not accept conan source --output-folder and an absolute recipe path still sets source_folder to the recipe directory, so get(strip_root=True) extracts into the worktree.
+
+## 验证命令
+
+```bash
+Copy only conanfile.py and conandata.yml to a create-new isolated recipe directory, run conan source . there, and verify the original worktree status is unchanged.
+```
+
+## 解决方案
+
+**isolated-recipe-copy-source-probe**：Treat the current recipe directory as the source output of conan source, so every source probe must execute from a disposable isolated recipe copy.
+
+```bash
+Create a new evidence/case/recipe directory, copy the recipe metadata, run conan source . with a case-local Conan home, and compare the original worktree before and after.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`conan source .*--output-folder|conan source [A-Z]:.*archives`
+- **原因**：The unsupported option fails before source(), while an absolute worktree recipe path still writes extracted source into that recipe directory.
+- **后果**：Large upstream trees contaminate the candidate worktree and can overlap intended recipe files.
+
+## 涉及软件
+
+Conan 2.29.1 source-method tests for recipes whose source() extracts archives at the source folder root.
+
+---
+*条目 E378 · 更新 2026-08-15 · 知识库同步生成物*

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

@@ -0,0 +1,53 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E379: Freeze the complete auxiliary input closure for offline upstream tests
+
+> **严重度**: 🔴 blocking | **分类**: cmake, externaldata, input-closure, offline-tests, pr-transport | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+clang-format-Windows.*file\(DOWNLOAD\)
+Object CID=.*not found.*No ExternalData_URL_TEMPLATES given
+missing binary patch data
+100% tests passed out of
+```
+
+## 根因
+
+A complete upstream test graph can consume formatting tools, compiler-specific support libraries, auxiliary source projects, and content-addressed baselines outside the main source archive; a Conan recipe that validates a task-local store but does not export it still fails on a clean CI worker, while a PR checkout service that applies a text-only diff cannot transport newly added raw binary baselines even when Git stores them correctly.
+
+## 验证命令
+
+```bash
+Export the recipe into a fresh Conan home, compare every exported auxiliary input by relative path, bytes, and SHA-256, then run a clean build with rejecting proxies, empty URL templates, and the complete CTest inventory.
+```
+
+## 解决方案
+
+**manifest-bound-complete-test-input-closure**：Preserve the upstream test inventory while exporting every required auxiliary source and content object, validating the complete manifest, using canonical text transport when the PR service cannot carry binary patch payloads, and binding the exact ExternalData hash-store root for runnable builds.
+
+```bash
+Store each binary object as canonical line-wrapped Base64 text when required by the PR transport, decode only inside export_sources, verify decoded path/bytes/SHA-256 against the unchanged manifest, export only the manifest plus original bytes, default runnable builds to source_folder/test-data/Objects while preserving a validated non-empty explicit override, normalize an empty override to the default, ignore host overrides for non-runnable builds, reject links and missing/extra objects, set ExternalData_NO_SYMLINKS, disable URL fallback, then execute the full CTest inventory.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`BUILD_TESTING.*OFF|ExternalData_URL_TEMPLATES.*https|skip.*missing.*baseline`
+- **原因**：Disabling tests or restoring URL fallback hides an incomplete frozen input closure.
+- **后果**：The resulting test evidence is partial or non-reproducible offline.
+
+## 涉及软件
+
+Conan-packaged CMake projects whose full test graph uses ExternalProject, direct file downloads, or ExternalData on a network-restricted build host or target, especially repositories whose CI reconstructs a PR from a text patch.
+
+## 相关模式
+
+- **相似模式**：[E256](E256.md)、[E268](E268.md)
+
+---
+*条目 E379 · 更新 2026-08-16 · 知识库同步生成物*

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

@@ -0,0 +1,49 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E380: Bind a validated memory budget when target CMake cannot parse procfs
+
+> **严重度**: 🔴 blocking | **分类**: cmake, memory, capability-binding, test-inventory | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Problem parsing /proc/meminfo
+ITK_COMPUTER_MEMORY_SIZE.*empty
+ITK_COMPUTER_MEMORY_SIZE is required for runnable OHOS tests
+tests passed.*out of 617
+```
+
+## 根因
+
+A target can expose valid MemTotal data while CMake's platform-specific host-memory parser fails, causing memory-gated tests to disappear from the generated inventory.
+
+## 验证命令
+
+```bash
+Give a validated explicit override highest priority; otherwise, only for runnable targets, parse exactly one local MemTotal kB field, derive the bounded test budget, require the generated cache value, and compare the exact CTest inventory against the host baseline.
+```
+
+## 解决方案
+
+**validated-explicit-memory-budget**：Keep the full expected inventory, prefer a sealed range-checked override when supplied, and otherwise derive the value from local read-only MemTotal only when the target is runnable.
+
+```bash
+Reject missing, duplicate, nonnumeric, zero, too-small, wrong-unit and implausibly large values; divide KiB to MiB before multiplying by 80; never inspect host procfs for non-runnable cross builds; then bind ITK_COMPUTER_MEMORY_SIZE and require the gated test.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`expected-count.*617|BUILD_TESTING.*OFF|__OHOS__|HarmonyOS`
+- **原因**：Lowering the expected test count, disabling tests, or branching on a platform name hides the failed capability discovery.
+- **后果**：The package can report success while silently omitting a memory-gated upstream test.
+
+## 涉及软件
+
+CMake projects that derive conditional test inventory from cmake_host_system_information on targets whose procfs format is not recognized, including same-machine target CI where Conan can_run is true but no task controller exports a memory override.
+
+---
+*条目 E380 · 更新 2026-08-16 · 知识库同步生成物*

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

@@ -0,0 +1,48 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E381: Bind wrapper and controller tree constants to the same final authority
+
+> **严重度**: 🔴 blocking | **分类**: device-control, snapshot-binding, successor-generation | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+HEAD/tree drift
+allocation.*tree.*stale
+controller.*tree.*drift
+```
+
+## 根因
+
+A successor freeze can bind the new staged tree while a mechanically copied outer wrapper or inner controller still emits the predecessor tree into the allocation object.
+
+## 验证命令
+
+```bash
+Generate a synthetic exact allocation from the real wrapper, run the production controller in offline mode, and require wrapper allocation tree, controller tree, authority tree and live git write-tree to be byte-identical.
+```
+
+## 解决方案
+
+**four-way-snapshot-binding**：Derive or assert every wrapper/controller snapshot constant against one final authority before claim, evidence creation, SSH or transfer.
+
+```bash
+Fail the local matrix when any of wrapper allocation, controller constant, authority or git write-tree differs; bind the verified controller and wrapper hashes into final W4.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`retry.*same.*run|ignore.*HEAD/tree drift|edit.*allocation.*after claim`
+- **原因**：A consumed one-shot claim cannot be repaired by retrying or mutating its evidence after the fact.
+- **后果**：Snapshot evidence may no longer describe the code sent to the device.
+
+## 涉及软件
+
+One-shot device controllers whose wrapper constructs allocation authority separately from the controller's local HEAD/tree prewrite gate.
+
+---
+*条目 E381 · 更新 2026-08-16 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E382: Materialize immutable cross-package resources when HMDFS cannot preserve dangling links
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, conan, packaging, filesystem, resource-overlay | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+dangling symbolic link
+PermissionError.*symlink
+Operation not permitted.*symlink
+missing.*shared.*view
+```
+
+## 根因
+
+The upstream deployment model overlays independently built packages, so a resource link is intentionally dangling until another package supplies its target; isolated Conan roots plus HMDFS link restrictions can silently omit the resource.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**dependency-graph-resource-materialization**：Resolve an explicit resource mapping from the declared dependency package, enforce source/destination containment, copy into a regular file, and verify byte identity against the resolved dependency version.
+
+```bash
+use os.path.realpath/commonpath, os.path.lexists/unlink, shutil.copy2, filecmp.cmp(shallow=False), and consumer cmp plus test ! -L
+```
+
+## 回退方案
+
+**deployment-overlay-or-wrapper**：Use a deployment overlay for mutable/shared state or a wrapper for executable aliases when regular-file materialization would change semantics.
+
+```bash
+define the ownership/overlay contract outside the isolated target package
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`symlink\(.*except.*pass|ln -s.*\|\| true|ignore.*PermissionError`
+- **原因**：Ignoring link failure lets packaging succeed with required resources absent.
+- **后果**：Runtime views or data are missing even though build and package creation report success.
+
+### 🚫 禁止 2
+
+- **模式**：`copy2?\(.*(/usr|/system)|golden.*copy|placeholder`
+- **原因**：Undeclared system sources, embedded golden copies and placeholders are not bound to the Conan dependency graph.
+- **后果**：Content can drift from the selected dependency version or package non-reproducibly.
+
+## 涉及软件
+
+Resource/application packages whose immutable linked target is owned by a declared Conan dependency and whose runtime semantics permit a byte-identical regular-file representation.
+
+## 相关模式
+
+- **相似模式**：[E050](E050.md)、[E073](E073.md)
+- **根因条目（应先修它们）**：[E018](E018.md)
+
+---
+*条目 E382 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,61 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E383: OHOS shared library missing SONAME due to absent Platform/HarmonyOS.cmake module
+
+> **严重度**: 🟡 medium | **分类**: platform, detection, cmake, linking, shared-library | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+readelf -d.*lib.*\.so.*no SONAME
+SONAME.*not found
+soname_gate_failed
+CMAKE_SHARED_LIBRARY_SONAME.*empty
+```
+
+## 根因
+
+CMake 4.x ships no Platform/HarmonyOS.cmake module. The Linux platform module (Platform/Linux.cmake) sets CMAKE_SHARED_LIBRARY_SONAME_C_FLAG=-Wl,-soname,, but without a HarmonyOS equivalent this variable is empty. The link template CMAKE_C_CREATE_SHARED_LIBRARY contains <SONAME_FLAG><TARGET_SONAME>; when SONAME_FLAG is empty the soname is not passed to the linker and the resulting .so has no SONAME field in its ELF dynamic section (readelf -d shows no SONAME). The project's SET_TARGET_PROPERTIES(... SOVERSION ...) has no effect on the binary.
+
+## 验证命令
+
+```bash
+readelf -d <lib>.so | grep SONAME; cmake --system-information 2>&1 | grep -i SONAME_FLAG; cmake --system-information 2>&1 | grep _INCLUDED_SYSTEM_INFO_FILE
+```
+
+## 解决方案
+
+**conan-recipe-soname-flag**：In conanfile.py generate(), set tc.cache_variables['CMAKE_SHARED_LIBRARY_SONAME_C_FLAG']='-Wl,-soname,' and tc.cache_variables['CMAKE_SHARED_LIBRARY_SONAME_CXX_FLAG']='-Wl,-soname,' so CMake passes -Wl,-soname,<TARGET_SONAME> to the linker. The project's SOVERSION property then resolves TARGET_SONAME to libfoo.so.<major>.
+
+```bash
+tc.cache_variables['CMAKE_SHARED_LIBRARY_SONAME_C_FLAG'] = '-Wl,-soname,'; tc.cache_variables['CMAKE_SHARED_LIBRARY_SONAME_CXX_FLAG'] = '-Wl,-soname,'
+```
+
+## 回退方案
+
+**patchelf-post-build**：If the toolchain-layer fix is not possible, run patchelf --set-soname libfoo.so.<major> on the .so in package() after cmake.install().
+
+```bash
+patchelf --set-soname libyajl.so.2 lib/libyajl.so
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`CMAKE_SKIP_RPATH|CMAKE_NO_SONAME|NO_SONAME`
+- **原因**：Disabling SONAME entirely makes downstream DT_NEEDED entries non-relocatable.
+- **后果**：Consumers only work while the exact Conan cache path exists.
+
+## 涉及软件
+
+All CMake packages building shared libraries (.so) for OHOS/HarmonyOS PC where CMAKE_SYSTEM_NAME resolves to HarmonyOS and no Platform/HarmonyOS.cmake exists. Confirmed with yajl 2.1.0 (libyajl.so).
+
+## 相关模式
+
+- **相似模式**：[E092](E092.md)
+
+---
+*条目 E383 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E384: 自写（非 autoconf 生成）的 configure 脚本用
+
+> **严重度**: 🟡 medium | **分类**: build-system, configure, dependency, pkg-config, security | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Library option -lcrypto cannot be used
+OpenSSL Crypto development libraries are not installed properly in required location
+Library option -lssl cannot be used
+OpenSSL development libraries are not installed properly in required location
+```
+
+## 根因
+
+自写（非 autoconf 生成）的 configure 脚本用
+`${CC} ${OSCFLAGS} ${OSLIBS} -lcrypto` 这类裸命令探测第三方库，
+只拼接脚本内部的 OSCFLAGS/OSLIBS，**不读** conan 的
+LDFLAGS/CPPFLAGS 环境变量；同时它用 pkg-config 按上游模块名
+（libcrypto/libssl）查询，而 conan 的 PkgConfigDeps 只按配方
+pkg_config_name（或包名，如 openssl.pc）生成 .pc，两路探测
+在 conan 缓存环境下都失败 → configure 中止。
+
+## 验证命令
+
+```bash
+cd <build_dir> && ./configure ... 2>&1 | grep -E "cannot be used|not installed properly"
+```
+
+## 解决方案
+
+**configure-documented-env-override**：使用 configure 脚本自身文档化的覆盖变量（coturn 为
+SSL_CFLAGS/SSL_LIBS；libp11 用 OPENSSL_CFLAGS/OPENSSL_LIBS），
+在 conanfile build() 的 Environment 中指向依赖包路径，configure
+命中 "Private SSL Library option" 分支直接采用并写入生成的 Makefile，
+无需改依赖配方，也不用补转发型 .pc。
+
+```bash
+openssl = self.dependencies["openssl"].package_folder
+build_env.define("SSL_CFLAGS", f"-I{os.path.join(openssl, 'include')}")
+build_env.define("SSL_LIBS", f"-L{os.path.join(openssl, 'lib')} -lcrypto -lssl")
+```
+
+## 回退方案
+
+**forward-pc-files**：在 generate() 里为上游模块名补转发型 .pc（libcrypto.pc/libssl.pc
+指向 openssl.pc），使 configure 的 testpkg_common 命中（参考 E321 思路）；
+但自写 configure 的裸 -l 探测分支仍可能失败，故优先用覆盖变量。
+
+```bash
+# generate() 内手工写 libcrypto.pc/libssl.pc 到 generators 目录
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`sed -i.*configure.*LCrypto|修改 conan 缓存里的依赖配方`
+- **原因**：不要改缓存内依赖包配方（会影响其他消费者）；不要 sed 篡改
+源码 configure 去绕过探测（应优先用文档化覆盖变量）
+
+## 涉及软件
+
+所有用自写 configure 探测第三方库的软件（coturn、libp11 同类），
+且依赖配方未声明与上游一致的多 pkg_config_name 的场景。
+
+---
+*条目 E384 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E385: 为 Cargo 原生 CMake 子构建补全 OHOS SDK 缺失的 llvm-ranlib
+
+> **严重度**: 🟡 medium | **分类**: ohos, cmake, toolchain, rust, archive | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)
+
+---
+
+## 错误特征
+
+```
+native/llvm/bin/llvm-ranlib.*not found
+Error running link command.*crypto
+CMAKE_RANLIB.*native/llvm/bin/llvm-ranlib
+```
+
+## 根因
+
+含原生 C/CMake 子构建的 Rust crate 会通过 build.rs 独立调用 OHOS SDK 的 CMake toolchain。该 toolchain 将 CMAKE_RANLIB 固定为 native/llvm/bin/llvm-ranlib，但当前 SDK 仅提供同目录 llvm-ar，缺少 llvm-ranlib。仅设置 Cargo 的 AR_<target> 或通用 RANLIB 不会覆盖子 CMake cache，导致静态归档索引阶段失败。前置架构配置错误也可能表现为 AES/BN 未定义符号，但该签名必须结合 OHOS_ARCH、CMAKE_SYSTEM_PROCESSOR 和 archive 对象清单单独诊断，不能归因于 ranlib 缺失。
+
+## 验证命令
+
+```bash
+test ! -x "$OHOS_NDK_HOME/native/llvm/bin/llvm-ranlib"; test -x "$OHOS_NDK_HOME/native/llvm/bin/llvm-ar"; rm -rf <fresh-cargo-target>; CARGO_TARGET_DIR=<fresh-cargo-target> cargo build --release --locked; grep -E '^CMAKE_(RANLIB|C_COMPILER_RANLIB|ASM_COMPILER_RANLIB):.*<build-local-wrapper>' <fresh-cargo-target>/release/build/aws-lc-sys-*/out/build/CMakeCache.txt; file <fresh-cargo-target>/release/stalwart-cli; readelf -h <fresh-cargo-target>/release/stalwart-cli
+```
+
+## 解决方案
+
+**target-scoped-cmake-toolchain-overlay**：保留官方 OHOS CMake toolchain 以获得正确目标架构、sysroot 和汇编源选择；在 Conan/Cargo 构建目录生成只执行 llvm-ar s 的 ranlib 包装器，再生成薄 CMake toolchain overlay，先 include 官方 ohos.toolchain.cmake，随后强制覆盖 CMAKE_RANLIB、CMAKE_C_COMPILER_RANLIB 和 CMAKE_ASM_COMPILER_RANLIB。通过 crate 提供的 target-specific CMAKE_TOOLCHAIN_FILE 环境变量注入，且只作用于目标 crate 子构建。
+
+```bash
+printf '#!/bin/sh\nexec "%s" s "$@"\n' "$LLVM_AR" > "$BUILD_DIR/llvm-ranlib"; chmod +x "$BUILD_DIR/llvm-ranlib"; write overlay including "$OHOS_NDK_HOME/native/build/cmake/ohos.toolchain.cmake" and force CMAKE_*_RANLIB to wrapper; export AWS_LC_SYS_CMAKE_TOOLCHAIN_FILE_aarch64_unknown_linux_ohos="$BUILD_DIR/aws-lc-ohos-toolchain.cmake"; cargo build --release --locked
+```
+
+## 回退方案
+
+**sdk-provided-ranlib**：若后续官方 SDK 补齐 native/llvm/bin/llvm-ranlib，则直接使用 SDK 工具并移除包装器；必须重新执行干净 Cargo/Conan 构建确认 CMake cache 未保留旧路径。
+
+```bash
+test -x "$OHOS_NDK_HOME/native/llvm/bin/llvm-ranlib" && rm -rf <cargo-target-dir> && cargo build --release --locked
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`AWS_LC_SYS_NO_ASM=1|AWS_LC_SYS_NO_ASM_aarch64_unknown_linux_ohos=1`
+- **原因**：aws-lc-sys 将 NO_ASM 限制为 debug 构建，且禁用汇编会改变 release 交付的性能和实现路径
+- **后果**：release 构建被上游拒绝，或测试结果无法代表正式产物
+
+### 🚫 禁止 2
+
+- **模式**：`(cp|ln).*(llvm-ar|ar).*native/llvm/bin/llvm-ranlib`
+- **原因**：直接修改 SDK 或伪造其工具文件污染共享工具链，无法由配方复现，也可能影响其他任务
+- **后果**：本机通过但 CI 失败，且破坏 SDK 完整性
+
+### 🚫 禁止 3
+
+- **模式**：`CMAKE_SYSTEM_NAME=Linux|AWS_LC_SYS_EFFECTIVE_TARGET.*linux-musl`
+- **原因**：用 Linux 平台冒充 OHOS 会绕开官方 toolchain 的 sysroot和平台语义；effective target 会影响绑定及部分目标/架构路由，但不能提供完整 OHOS toolchain 配置
+- **后果**：生成错误平台配置、遗漏 OHOS 约束或残留 AES/BN 未定义符号
+
+## 涉及软件
+
+使用 Cargo build.rs/cmake crate 启动目标平台 CMake 子构建，并依赖 OHOS SDK ohos.toolchain.cmake 生成静态库的 Rust 软件；已在 aws-lc-sys 0.39.1 验证，也适用于其他需要 ranlib 的原生 crate
+
+## 相关模式
+
+- **相似模式**：[E012](E012.md)、[E267](E267.md)、[E296](E296.md)
+
+---
+*条目 E385 · 更新 2026-08-17 · 知识库同步生成物*

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

@@ -0,0 +1,93 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E386: Capability-tested shell and selective Automake dispatcher on noexec source trees
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, autotools, conan, testing, noexec | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P010](../principles.md#P010)、[P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+getcwd.*diagnostic
+working directory.*invalid
+Permission denied.*RunTest
+LOG_COMPILER.*RunGrepTest
+configure.*noexec
+```
+
+## 根因
+
+A HarmonyOS/HMDFS source or build tree can reject direct
+execution of generated configure helpers and suffixless
+shell test drivers. A shell binary may still return zero
+while emitting a getcwd diagnostic, so executable-bit or
+return-code checks alone do not prove that it can preserve
+the requested working directory. Automake test lists can
+mix shell drivers with real ELF tests; routing every test
+through a shell would change the test semantics. Conan
+self.run may also source conanbuild after the recipe has
+selected a shell, silently replacing the tested path.
+
+## 验证命令
+
+```bash
+Run a fresh target conan create with a child-process
+`pwd` probe whose stdout and stderr are both empty; bind
+CONFIG_SHELL and SHELL to that path; run `make -j1 check`
+through a selective LOG_COMPILER dispatcher; require the
+complete upstream inventory and a real consumer to pass.
+```
+
+## 解决方案
+
+**capability-tested-shell-and-selective-dispatch**：Probe each candidate shell from the real build directory
+and accept it only when `pwd` returns zero with empty
+output and diagnostics. Reassert the resulting shell in
+an explicit environment script after Conan's conanbuild
+environment is sourced. Set CONFIG_SHELL and SHELL for
+Autoconf, and use LOG_COMPILER only for known suffixless
+shell drivers; direct ELF tests must continue to exec
+directly.
+
+```bash
+make -j1 check LOG_COMPILER='<tested-shell> -c <dispatcher>'
+```
+
+## 回退方案
+
+**executable-backed-test-root**：Move the source/build tree to a filesystem with proven
+script execution only when the project cannot express a
+selective launcher; keep the upstream test inventory and
+direct-ELF distinction unchanged.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`shell -c.*all.*TESTS|LOG_COMPILER=/system/bin/sh.*unconditional`
+- **原因**：Sending every Automake entry to a shell attempts to parse
+real ELF tests as scripts and can hide a missing test.
+- **后果**：The upstream test result is no longer authoritative.
+
+### 🚫 禁止 2
+
+- **模式**：`chmod \+x.*all|accept.*pwd.*stderr|os\.environ.*CONFIG_SHELL`
+- **原因**：chmod does not establish HMDFS execution capability, a
+noisy pwd probe can poison Autoconf, and Conan buildenv
+values are not guaranteed in the recipe Python process.
+- **后果**：The recipe can pass a local probe but fail at configure
+or silently use a different shell in later stages.
+
+## 涉及软件
+
+Conan Autotools recipes built from noexec or HMDFS-style
+paths with mixed suffixless shell and direct ELF Automake
+tests, especially native OpenHarmony builds.
+
+## 相关模式
+
+- **相似模式**：[E087](E087.md)、[E228](E228.md)、[E232](E232.md)
+
+---
+*条目 E386 · 更新 2026-08-18 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E387: LLVM 15.0.4 lit 测试框架在 OHOS 的适配入口与最小子集实测方法
+
+> **严重度**: 🟡 medium | **分类**: ohos, toolchain, llvm, cross-compile, lit | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+llvm_lit_ohos_adaptation
+lit_site_config_missing
+lit_psutil_missing
+```
+
+## 根因
+
+上游 llvm/test/lit.cfg.py 依赖 CMake 生成的 lit.site.cfg.py 提供大量 config 属性
+（llvm_tools_dir/llvm_obj_root/host_triple/targets_to_build/have_libxml2 等）；在 Conan 包/临时
+worktree 环境无 CMake 生成物时加载即 AttributeError；psutil 缺失使 lit --timeout 不可用（仅警告）
+
+## 验证命令
+
+```bash
+python3 <SRC>/llvm/utils/lit/lit.py --no-progress-bar <SUITE>/CodeGen/AArch64
+```
+
+## 解决方案
+
+**1) 自包含替换式 lit.cfg.py：复制上游 llvm/test/lit.cfg.py 并在顶部注入全部 site 属性
+（llvm_src_root/llvm_obj_root/llvm_tools_dir/llvm_lib_dir/llvm_shlib_dir/host_triple/target_triple/
+targets_to_build=字符串/llvm_use_sanitizer/build_mode/enable_llvm_dylib/llvm_dylib_version/host_arch/
+host_os/host_cc/host_ldflags/llvm_enable_assertions/inliner_model/raevict_model/lit_tools_dir/
+use_lit_shell/use_default_substitutions/python_executable/go/gold/ld/ld64/ptxas/ocamlfind/ocaml_flags/
+osx_sysroot/build_examples/build_shared_libs/enable_threads/expensive_checks/has_plugins/have_curl/
+have_libxar/have_libxml/have_libxml2/have_llvm_driver/have_ocamlopt/have_opt_viewer_modules/have_tf_aot/
+have_tf_api/libcxx_used/link_llvm_dylib/linked_bye_extension/llvm_locstats_used）+ import lit.llvm +
+lit.llvm.initialize(lit_config, config)；2) 入口脚本 run_lit_subsel.sh 生成 llvm-lit-wrapper.py
+（config_map 把源码 llvm/test 映射到 lit.site.cfg.py）；3) 最小 smoke 用例 test_lit/add.ll
+（RUN: llc -mtriple=aarch64-unknown-linux-ohos | FileCheck %s）；4) 子集选择：按文件名排序取
+CodeGen/AArch64 前 50 + InstSimplify 前 15，禁止跑全量（约 7.3 万文件不现实）**：LLVM 15.0.4 在 OHOS 上运行 lit 最小子集需自包含替换式配置（上游 lit.cfg.py + 注入全部 site 属性 +
+lit.llvm.initialize），否则加载即报 AttributeError（use_lit_shell/host_triple/ld64_executable/
+have_libxml2 等逐个缺失）。实测：AArch64 子集 49 用例 46 Passed + 3 Unsupported（缺 cortex-a53 fix /
+O0-O3 pipeline feature 非失败）+ InstSimplify 15 用例全 Passed（61/64，1.19s+0.61s，exit 0）。
+lit 框架自测 4/4 通过。psutil 缺失仅使 --timeout 不可用（警告非错误）。包内 bin 工具
+（llc/FileCheck/count/not/clang-15 等）需签名（.codesign 段）方可执行。
+与 DRAFT-intel-oneapi-dpcpp-ohos-sycl-lit（SYCL 层）范围不同，证据独立不重叠。
+
+## 涉及软件
+
+所有以 lit 为测试框架的三方库在 OHOS 上的 test_package 适配（LLVM/Clang/LLD/LLDB 及 lit 系库）
+
+---
+*条目 E387 · 更新 2026-08-31 · 知识库同步生成物*