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

@@ -0,0 +1,83 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E444: HarmonyOS 原生 GLib/GObject 消费方不要假设 ELF .init_array 构造器已完成类型系统初始化
+
+> **严重度**: 🔴 blocking | **分类**: ohos, constructors, glib, gobject, runtime-init | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+GObject.*type system.*not initialized
+G_IS_OBJECT.*failed
+g_object_new.*failed
+first GObject use.*HarmonyOS
+constructor.*init_array.*not run
+g_type_ensure_initialized
+```
+
+## 根因
+
+GLib/GObject 通常依赖库构造器在进程启动或动态库装载时自动运行 gobject_init()。
+HarmonyOS 原生 Conan 测试环境中，首次使用 GObject 类型系统前不能总是假设 ELF
+.init_array 构造器已经按上游预期执行。若消费方直接进入 g_object_new()、
+G_IS_OBJECT()、GType 查询或 GIO 对象构造，可能暴露类型系统未初始化风险。
+glib 2.88.0 适配通过新增显式、幂等、线程安全的
+g_type_ensure_initialized() 入口，在首次 GObject/GIO 使用前兜底调用。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+# 期望:
+# - upstream Meson tests: 302 ok, 0 failed, 6 skipped
+# - test_package: test glib 2.88.0: OK (string/hashtable/variant/gobject/gio)
+# - L1e destructive negative test confirms the smoke test depends on glib artifacts
+```
+
+## 解决方案
+
+**explicit-idempotent-gobject-init-entry**：在 GLib/GObject 适配补丁中提供公开入口 g_type_ensure_initialized()，
+通过 g_once_init_enter()/g_once_init_leave() 保证幂等和线程安全；
+若构造器已运行则不重复初始化，若 HarmonyOS 上构造器未先运行则显式执行
+gobject_init()。消费方 test_package 在首次 GObject/GIO 使用前调用该入口两次，
+同时覆盖重复调用不会破坏状态的场景。
+
+```bash
+g_type_ensure_initialized();
+g_type_ensure_initialized();
+GObject *o = g_object_new(G_TYPE_OBJECT, NULL);
+g_assert(G_IS_OBJECT(o));
+```
+
+## 回退方案
+
+**avoid-gobject-in-smoke-test**：只测 g_strdup()/GHashTable 等 glib-core API 可以绕过 GObject 初始化问题，
+但会让 test_package 对 gobject/gio 组件覆盖不足，L1e 负向验证价值下降。
+
+```bash
+test only glib core APIs
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`rely only on library constructor|assume .init_array`
+- **原因**：HarmonyOS 原生执行环境中该假设已经被 glib 2.88.0 适配验证为风险点。
+- **后果**：首次 GObject 使用可能在类型系统未完成初始化时运行，导致测试或消费方启动不稳定。
+
+### 🚫 禁止 2
+
+- **模式**：`fake test by only printing version|skip all GObject/GIO API use`
+
+## 涉及软件
+
+在 HarmonyOS/OHOS native 环境中直接消费 GLib/GObject/GIO 的 Conan 包和
+test_package，尤其是第一步就调用 g_object_new(), G_IS_OBJECT(),
+g_file_new_for_path() 或上游测试依赖 GObject 基础类型注册的场景。
+该问题不是 pkg-config 找不到 gobject-2.0，也不是 GLib 命令行工具缺运行权限。
+
+---
+*条目 E444 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E445: Neovim runtime plugins need a packaged Vusted/Busted chain for Path B upstream tests
+
+> **严重度**: 🟡 medium | **分类**: lua, testing, busted, neovim, path-b | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+vusted ./test
+make test -> vusted ./test
+nvim --headless
+0/9 actual upstream Vusted tests executed
+```
+
+## 根因
+
+Neovim runtime-plugin upstream tests can require a real headless Neovim plus Vusted/Busted Lua test harness; package-layout or Python consumer checks do not execute the upstream Vusted cases and must not be counted as upstream passes.
+
+## 验证命令
+
+```bash
+From the packaged plugin root, run vusted ./test with packaged neovim and vusted in the Conan run environment, then record the upstream case count and full package refs.
+```
+
+## 解决方案
+
+**path-b-packaged-neovim-vusted-chain**：Use Path B when the upstream test harness needs packaged Neovim/Vusted prerequisites; package the upstream test tree, run the real vusted command from the installed plugin root, and keep adapted consumer layout checks separate from upstream-test accounting.
+
+```bash
+conan create 〈外部知识库归档〉 --build=missing; cd <package>/share/nvim-lspconfig && vusted ./test
+```
+
+## 回退方案
+
+**consumer-layout-guard-only**：If packaged Neovim/Vusted is unavailable, keep a Python or shell consumer check only as package layout validation and report upstream Vusted execution as 0/N.
+
+```bash
+python test_package/test_nvim_lspconfig.py
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`count.*Python.*layout.*upstream|count.*test_package.*as.*Vusted|claim.*Path A.*without.*vusted`
+- **原因**：Adapted consumer checks prove packaged files and selected behavior inputs but do not execute upstream Vusted/Busted cases.
+- **后果**：PR evidence can overstate upstream-test coverage and hide missing Neovim/Vusted runtime prerequisites.
+
+### 🚫 禁止 2
+
+- **模式**：`omit.*test/|omit.*lsp/|run.*vusted.*outside.*packaged.*root`
+- **原因**：nvim-lspconfig tests import both upstream test fixtures and runtime lsp files from the plugin root.
+- **后果**：The test command may validate a source checkout or incomplete package layout instead of the published artifact.
+
+## 涉及软件
+
+Neovim Lua plugins whose upstream test entry is make test or vusted and whose OHOS validation depends on separately packaged neovim, vusted, busted, and Lua runtime modules.
+
+---
+*条目 E445 · 更新 2026-08-24 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E446: Keep filesystem tests active while exempting unsupported OHOS link-creation paths
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, portability, testing, filesystem | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+Assertion failed: !zix_create_symlink
+ZIX_STATUS_BAD_PERMS
+hard.?link.*BAD_PERMS
+symlink.*NOT_SUPPORTED
+```
+
+## 根因
+
+Some OHOS/HMDFS-backed test directories reject hardlink or symlink creation even though ordinary file, directory, and path canonicalization operations work. Upstream filesystem tests may assert POSIX link creation success and abort before the remaining coverage runs.
+
+## 验证命令
+
+```bash
+meson test -C <build_folder> --print-errorlogs; require the filesystem test to continue past link-creation capability checks and preserve the non-link canonical-path assertions.
+```
+
+## 解决方案
+
+**capability-scoped-filesystem-test-exemption**：Patch only the link-creation assertion. Accept documented platform statuses such as BAD_PERMS or NOT_SUPPORTED, and skip only the symlink-specific branch when creating the symlink is denied. Keep the rest of the filesystem test program enabled.
+
+```bash
+assert(!st || st == ZIX_STATUS_NOT_SUPPORTED || st == ZIX_STATUS_BAD_PERMS)
+```
+
+## 回退方案
+
+**move-test-root-to-link-capable-filesystem**：If the test is meant to validate actual link support rather than generic filesystem behavior, run it on a target directory that supports the required link operation and document that requirement.
+
+```bash
+TMPDIR=<link-capable-dir> meson test -C <build_folder> --print-errorlogs
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`disable.*filesystem|skip.*test_filesystem|tests.*disabled`
+- **原因**：The unsupported operation is only one subtest; broad skipping hides unrelated directory, path, missing-file, and cleanup behavior.
+- **后果**：The package can pass while core filesystem helpers are untested on the target.
+
+### 🚫 禁止 2
+
+- **模式**：`assert\\(true\\)|return 0|ignore.*all.*filesystem`
+- **原因**：A fake pass removes evidence that the library still handles supported filesystem operations correctly.
+- **后果**：CI no longer distinguishes platform capability limits from library regressions.
+
+### 🚫 禁止 3
+
+- **模式**：`chmod -R|mount.*rw|force.*symlink`
+- **原因**：Changing broad filesystem permissions or mounts is not a package-local adaptation and can destabilize shared runners.
+- **后果**：The fix becomes non-reproducible and may affect unrelated packages.
+
+## 涉及软件
+
+Small portability libraries whose upstream tests include hardlink or symlink subtests and run directly on HarmonyOS PC target filesystems.
+
+## 相关模式
+
+- **相似模式**：[E050](E050.md)、[E080](E080.md)
+
+---
+*条目 E446 · 更新 2026-08-25 · 知识库同步生成物*

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

@@ -0,0 +1,94 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E447: Bridge Conan SDL2 family include/link requirements into vendored FindSDL2* module consumers under OHOS cross-compile
+
+> **严重度**: 🔴 blocking | **分类**: cmake, cross-compile, conan, sdl2 | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+SDL_audio.h file not found
+SDL_gamecontroller.h file not found
+undefined symbol: WebPGetFeaturesInternal
+undefined symbol: TIFFClientOpen
+undefined symbol: pb_decode
+No rule to make target .*msg\.pb\.c
+```
+
+## 根因
+
+cdogs-sdl 1.0.0 ships vendored FindSDL2.cmake / FindSDL2_image.cmake / FindSDL2_mixer.cmake (build/cmake/). 在 OHOS aarch64 交叉编译 + Conan 2 CMakeDeps 下： (1) 若启用 CMAKE_FIND_PACKAGE_PREFER_CONFIG=TRUE，find_package(SDL2) 走 CMakeDeps CONFIG，只定义 sdl2::sdl2 target，不设置 SDL2_INCLUDE_DIRS 变量 → 上游 include_directories(${SDL2_INCLUDE_DIRS}) 为空 → SDL_audio.h/SDL_gamecontroller.h not found； (2) 若关闭 PREFER_CONFIG 保持 MODULE（含 generators=CMakeDeps 时），MODULE 的 find_path/find_library 在交叉编译环境找不到 Conan 包内头文件，或返回裸库路径而不含传递依赖（libwebp/libtiff/zlib）→ 链接期 undefined symbol； (3) 上游自身依赖 nanopb 的 nanopb_generate_cpp 宏（需要 protoc + Python google.protobuf + pkg_resources），交叉环境工具缺失。 全套问题不能靠参数开关/粒度替换解决——需要显式缓存变量桥接。
+
+## 验证命令
+
+```bash
+grep -R 'SDL2_INCLUDE_DIRS\|SDL2_LIBRARY\|SDL2_IMAGE_LIBRARIES\|nanopb_generate_cpp' CMakeLists.txt src/
+```
+
+## 解决方案
+
+**conan-recipe cache-variable bridge (E300 扩展)**：在 conanfile.py generate() 中遍历 self.dependencies[sdl2/sdl2_image/sdl2_mixer]，将 cpp_info.includedirs（含 include/SDL2 子目录）与 cpp_info.libs 映射为上游 vendored Find 模块期望的缓存变量（SDL2_INCLUDE_DIRS/SDL2_LIBRARY/SDL2_IMAGE_* 等），经 CMakeToolchain cache_variables 注入；库变量直接指向 Conan CMakeDeps imported target（sdl2::sdl2 等）以携带 INTERFACE_LINK_LIBRARIES 传递依赖。不设置 CMAKE_FIND_PACKAGE_PREFER_CONFIG（避免 MODULE→CONFIG 变量丢失回归）。
+
+```bash
+def generate(self):
+    tc = CMakeToolchain(self)
+    tc.cache_variables["CMAKE_POLICY_VERSION_MINIMUM"] = "3.5"
+    for dep, prefix in ((self.dependencies["sdl2"], "SDL2"),
+                        (self.dependencies["sdl2_image"], "SDL2_IMAGE"),
+                        (self.dependencies["sdl2_mixer"], "SDL2_MIXER")):
+        inc = "".join(...)  # cpp_info.includedirs + include/SDL2 子目录
+        tc.cache_variables[f"{prefix}_INCLUDE_DIR"] = inc
+        tc.cache_variables[f"{prefix}_INCLUDE_DIRS"] = inc
+        tgt = dep.ref.name + "::" + dep.ref.name
+        tc.cache_variables[f"{prefix}_LIBRARY"] = tgt
+        tc.cache_variables[f"{prefix}_LIBRARY_TEMP"] = tgt
+        tc.cache_variables[f"{prefix}_LIBRARIES"] = tgt
+    tc.generate()
+# build() 中再对源做三处补丁：
+#  (a) 顶层 CMakeLists.txt 注入 find_package(sdl2/sdl2_image/sdl2_mixer/nanopb CONFIG QUIET)
+#      + add_definitions(-Wno-implicit-const-int-float-conversion)（clang 15 RAND_MAX 转换）
+#  (b) src/proto/CMakeLists.txt：msg.pb.c/.h 已预生成时跳过 nanopb_generate_cpp
+#      （避免 protoc/Google protobuf 依赖），并给 cdogs_proto 追加
+#      target_link_libraries(cdogs_proto nanopb::nanopb)
+#  (c) src/cdogs 与 src/tests 的 target_link_libraries 保留上游 MODULE 变量并追加
+#      CMakeDeps targets（sdl2::sdl2 sdl2_image::sdl2_image ...）
+```
+
+## 回退方案
+
+**conan-toolchain pkg-config bridging**：若目标和依赖可用 pkg-config，可用 CMakeToolchain 的 pkg_config conditioned…由 pkg_check_modules 替代 find_path，配合 pkg-config 文件的 Libs.private 传递静态依赖。
+
+```bash
+# 依赖方产出 .pc（含 Libs.private）时：
+# CMakeLists：find_package(PkgConfig); pkg_check_modules(SDL2_IMAGE IMPORTED_TARGET SDL2_image)
+# 链接：target_link_libraries(cdogs PkgConfig::SDL2_IMAGE)
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`CMAKE_FIND_PACKAGE_PREFER_CONFIG.*TRUE`
+- **原因**：把 vendored MODULE 解析导向 CONFIG，SDL2_INCLUDE_DIRS 等变量丢失，include 目录为空。
+- **后果**：SDL_audio.h/SDL_gamecontroller.h not found（r08 实测回归）。
+
+### 🚫 禁止 2
+
+- **模式**：`把 ${SDL2_IMAGE_LIBRARIES} 直接清空或仅替换为裸库路径`
+- **原因**：丢失 libwebp/libtiff 等传递依赖。
+- **后果**：链接期 undefined symbol: WebP*/TIFF*（r08 实测）。
+
+### 🚫 禁止 3
+
+- **模式**：`手动生成/伪造 msg.pb.c 而不用上游预生成文件`
+- **原因**：上游已带预生成产物，直接用即可；protoc 在交叉环境不可用。
+- **后果**：nanopb 生成失败或引入不一致产物。
+
+## 涉及软件
+
+携带 vendored FindFoo*.cmake 模块、用 find_path/find_library 解析 CMake 变量风格的 SDL2 系（或类似 FFmpeg/GStreamer/SDL 系）项目，在 OHOS/arm64 交叉编译 + Conan 2 CMakeDeps 下消费静态依赖的场景。
+
+---
+*条目 E447 · 更新 2026-08-26 · 知识库同步生成物*

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

@@ -0,0 +1,90 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E448: Close the GNUstep Make environment for GNUstep libraries on OHOS
+
+> **严重度**: 🔴 blocking | **分类**: ohos, autotools, environment, gnustep, tool-requires | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+GNUSTEP_MAKEFILES.*not found
+GNUSTEP_SYSTEM_ROOT
+GNUSTEP_CONFIG_FILE
+/bin/sh.*not found
+Permission denied
+GNUstep Makefiles
+```
+
+## 根因
+
+GNUstep libraries are not plain Autotools packages. The
+configure script and GNUmakefile both need a coherent
+GNUstep Make domain before they can detect, build, and
+install libraries. On OHOS, scripts may also need an
+executable shell path that exists on the worker, and the
+produced libraries must be staged in the GNUstep SYSTEM
+layout rather than a conventional prefix-only libdir.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**conan-gnustep-make-domain-closure**：Resolve the gnustep-make package folder from the Conan
+build dependency, prepend its bin directory to PATH, set
+GNUSTEP_MAKEFILES to share/GNUstep/Makefiles, bind
+GNUSTEP_SYSTEM_ROOT and GNUSTEP_CONFIG_FILE to the
+current package folder, pass
+GNUSTEP_INSTALLATION_DOMAIN=SYSTEM during configure and
+make, and expose dependency library directories through
+the build and run environments. Prepare configure and
+GNUstep Make scripts with an OHOS-available shell before
+invoking them.
+
+```bash
+with gnustep_environment.vars(self).apply(): configure; make -j1 GNUSTEP_INSTALLATION_DOMAIN=SYSTEM GNUSTEP_SYSTEM_ROOT=<package_folder>
+```
+
+## 回退方案
+
+**explicit-gnustep-tool-paths**：When the upstream build does not honor the full GNUstep
+environment, pass GNUSTEP_MAKEFILES, GNUSTEP_SYSTEM_ROOT,
+and GNUSTEP_INSTALLATION_DOMAIN directly on the make
+command line while keeping the Conan package layout
+task-local.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`configure.*without.*GNUSTEP_MAKEFILES|make.*without.*GNUSTEP_SYSTEM_ROOT`
+- **原因**：GNUstep Make rules read domain variables throughout the
+build, so a configure-only setting is not sufficient.
+- **后果**：Configure may pass, but build, install, or downstream
+consumers resolve the wrong GNUstep domain.
+
+### 🚫 禁止 2
+
+- **模式**：`hardcode.*/storage/Users/.*/\.conan2|patch.*gnustep-make.*package_folder`
+- **原因**：gnustep-make is a shared Conan tool package and must stay
+relocatable for other recipes and users.
+- **后果**：Builds become cache-location dependent and can corrupt
+unrelated tasks.
+
+## 涉及软件
+
+Conan recipes for GNUstep core or application libraries
+that consume gnustep-make as a tool requirement and build
+on an OHOS target worker.
+
+## 相关模式
+
+- **相似模式**：[E337](E337.md)
+
+---
+*条目 E448 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,87 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E449: Publish GNU Objective-C runtime flags and run paths for GNUstep consumers
+
+> **严重度**: 🔴 blocking | **分类**: ohos, conan, runtime, gnustep, objective-c | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P014](../principles.md#P014)、[P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+Foundation/Foundation.h.*not found
+undefined reference.*objc
+objc_msg_lookup
+NSConstantString
+cannot find -lobjc
+symbol lookup error.*libgnustep-base
+```
+
+## 根因
+
+A GNUstep Foundation consumer needs the same GNU
+Objective-C runtime ABI and constant-string class as the
+library package. Conan's C and CMake consumers do not
+infer these flags automatically from the presence of
+libobjc2. If the recipe only publishes the library name,
+downstream Objective-C code can compile or link with the
+wrong runtime, miss Foundation headers, or fail at target
+execution because libobjc, libffi, curl, or
+libgnustep-base are not on the runtime library path.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**objc-runtime-flags-in-package-info**：Publish GNUstep Base headers and libraries with
+transitive libobjc2, libffi, and curl requirements. Add
+-fobjc-runtime=gcc, -fblocks, and
+-fconstant-string-class=NSConstantString to consumer
+compile flags, add the runtime flags to executable and
+shared link flags, and prepend the GNUstep Base and
+dependency libdirs to buildenv_info and runenv_info.
+Verify with an Objective-C test_package that imports
+Foundation/Foundation.h, constructs Foundation objects,
+links, signs/runs under shadow CI, and exits cleanly.
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=ohos-aarch64 -pr:b=ohos-aarch64 --build=missing
+```
+
+## 回退方案
+
+**explicit-consumer-cflags**：If a downstream build system ignores Conan cpp_info
+flags, inject the same Objective-C runtime and constant
+string flags into that consumer's toolchain while
+keeping gnustep-base package_info as the source of truth.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`test_package.*\\.c$|main\\(.*printf.*only`
+- **原因**：A C-only consumer cannot prove Objective-C runtime ABI,
+Foundation headers, constant strings, or message dispatch.
+- **后果**：The package can look green while real GNUstep consumers
+fail to compile, link, or run.
+
+### 🚫 禁止 2
+
+- **模式**：`rely.*system.*libobjc|omit.*fobjc-runtime|omit.*NSConstantString`
+- **原因**：GNUstep Base and downstream Objective-C objects must use
+the same runtime ABI and constant-string representation.
+- **后果**：Linkage succeeds inconsistently or target execution fails
+with missing Objective-C runtime symbols.
+
+## 涉及软件
+
+Conan recipes that package GNUstep Base or libraries
+depending on GNUstep Base for OHOS and expose Objective-C
+Foundation APIs to downstream consumers.
+
+---
+*条目 E449 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,77 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E450: Keep OHOS host metadata separate from an AVR target sysroot and validate it with the target toolchain
+
+> **严重度**: 🔴 blocking | **分类**: cross-compile, sysroot-packaging, test-boundary, tool-dispatch | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+avr-gcc: error trying to exec 'as'
+cannot find ld
+cannot open linker script file
+architecture: aarch64
+multilib directory escapes package root
+undefined reference to (memcpy
+strlen
+sin)
+```
+
+## 根因
+
+avr-libc produces headers, CRT objects, linker scripts, device archives, libc and libm for the AVR target even when Conan runs on an OHOS aarch64 host. Treating those files as native Conan C library metadata lets the OHOS compiler consume incompatible paths. In addition, avr-gcc -B searches its prefix for unprefixed as, ld and nm plus avr/lib/ldscripts, so merely placing avr-prefixed binutils on PATH is insufficient.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**cross-target-resource-boundary-and-explicit-driver-dispatch**：Model the result as a target resource package rather than an OHOS native library; keep cpp_info include, lib and libs empty; expose the sysroot through resdirs and an explicit root environment variable; construct an ephemeral avr-gcc -B dispatch root containing unprefixed binutils and linker scripts; and make test_package compile and link a real AVR ELF before checking target architecture, package-root containment and strong or weak symbol bindings.
+
+```bash
+conan create 〈外部知识库归档〉 --build=missing
+```
+
+## 回退方案
+
+**inventory-bounded-target-compile-link**：When a stage-1 compiler omits C++ or a simulator is not packaged, execute every eligible C and assembly source with a supported multilib, report executed pass rate separately from total source coverage, and list the blocked C++ and runtime inventory without claiming it passed.
+
+```bash
+MCU_LIST=at90s8515 MCU_LIST_FULL=at90s8515 sh runtest.sh -c
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`cpp_info\.(includedirs|libdirs|libs).*avr|package_type\s*=\s*"library"`
+- **原因**：AVR headers and archives must not be injected into an OHOS native consumer graph.
+- **后果**：The host compiler sees incompatible target headers or objects and the package boundary becomes misleading.
+
+### 🚫 禁止 2
+
+- **模式**：`PATH=.*avr-binutils.*avr-gcc|copy.*avr-(as|ld|nm).*PATH`
+- **原因**：PATH-only discovery does not satisfy avr-gcc -B lookup for unprefixed delegated tools and linker scripts.
+- **后果**：Compilation or linking fails after the compiler driver starts, despite avr-prefixed tools being present.
+
+### 🚫 禁止 3
+
+- **模式**：`462/462|100%.*upstream.*(?:runtime|source)`
+- **原因**：A C-only bootstrap compiler and no AVR simulator cannot execute the 53 C++ sources or AVR machine code.
+- **后果**：Coverage is overstated and CI evidence becomes unauditable.
+
+## 涉及软件
+
+Cross-target runtime or sysroot packages built by Conan on OHOS, especially staged compiler toolchains whose compiler driver delegates to a separately packaged binutils and whose test inventory spans multilib variants.
+
+## 相关模式
+
+- **相似模式**：[E011](E011.md)、[E129](E129.md)、[E206](E206.md)、[E223](E223.md)
+
+---
+*条目 E450 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,82 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E451: 消费 clang/LLVM 包时用 CMakeDeps 导致自带 ClangConfig 被遮蔽，clang 组件目标找不到
+
+> **严重度**: 🟡 medium | **分类**: build-system, cmake, conan | **自动修复**: ✅ cmake-prefix-path-to-package-config
+
+---
+
+## 错误特征
+
+```
+Target "ccls" links to target "clangIndex" but the target was not found
+No rule to make target.*clangIndex
+clangIndex.*not found
+find_package\(Clang\).*target.*not found
+CLANG_LINK_CLANG_DYLIB.*not defined
+```
+
+## 根因
+
+CMake 工程（如 ccls）需要 find_package(Clang REQUIRED) 解析到 clang 包自带的
+LLVM ClangConfig.cmake（定义 clangIndex/clangFormat/clangTooling 等组件目标，
+并设置 CLANG_LINK_CLANG_DYLIB=ON -> 链接 clang-cpp、LLVM_LINK_LLVM_DYLIB=ON ->
+链接 LLVM 聚合库）。但 conanfile 若同时生成 CMakeDeps，CMakeToolchain 生成的
+toolchain 会把 CMakeDeps 输出目录 PREPEND 到 CMAKE_PREFIX_PATH，CMakeDeps 生成的
+ClangConfig.cmake（只定义 clang::clang 聚合目标、无组件目标、无 *_DYLIB 变量）
+会遮蔽包内自带的 LLVM ClangConfig.cmake，导致链接 clangIndex/... 报 target 不存在。
+clang 包自身是 cmake_find_mode=config（包内含 lib/cmake/clang + lib/cmake/llvm）。
+另注意 rapidjson 包自带 config 只设 RapidJSON_INCLUDE_DIR（无 S），下游 CMakeLists
+若读 RapidJSON_INCLUDE_DIRS 变量会拿到空值导致 rapidjson 头找不到。
+
+## 验证命令
+
+```bash
+grep -E "Clang_DIR|LLVM_DIR" build/CMakeCache.txt 检查是否指向 clang 包内
+lib/cmake/clang；grep CLANG_LINK_CLANG_DYLIB build/CMakeCache.txt
+```
+
+## 解决方案
+
+**cmake-only-cmake-toolchain     # 只用 CMakeToolchain，不用 CMakeDeps**：conanfile generate() 只生成 CMakeToolchain，显式把依赖包目录写入
+CMAKE_PREFIX_PATH，find_package(Clang)/find_package(RapidJSON) 即命中
+包内自带的 LLVM/RapidJSON config；CMakeLists 需要的 *_INCLUDE_DIRS 变量显式补齐
+
+```bash
+tc = CMakeToolchain(self); tc.variables["CMAKE_PREFIX_PATH"] = ";".join(
+[self.dependencies["clang"].package_folder,
+ self.dependencies["rapidjson"].package_folder]);
+tc.variables["RapidJSON_INCLUDE_DIRS"] =
+os.path.join(rapidjson_pkg, "include"); tc.generate()
+```
+
+## 回退方案
+
+**cmakedeps-patch-generated-config**：仍用 CMakeDeps 时，在 generate() 里删除/覆盖生成的 ClangConfig.cmake，
+或把 clang 包目录 prepend 到 CMakeDeps 输出之前
+
+```bash
+（不推荐）generate() 中手动 rm CMakeDeps 生成的 ClangConfig* 并
+调整 CMAKE_PREFIX_PATH 顺序
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`CMAKE_PREFIX_PATH.*conanbuild|conandeps_legacy|CMakeDeps.*ClangConfig`
+- **原因**：toolchain 已把 CMakeDeps 输出目录 prepend 到 CMAKE_PREFIX_PATH，
+再手动加路径无法抵消遮蔽
+- **后果**：遮蔽依旧存在，clangIndex 等目标仍然找不到
+
+## 涉及软件
+
+HarmonyOS PC 上所有链接 LLVM/clang 库的 CMake 工程（language server、静态分析器、
+编译器前端等）
+
+## 相关模式
+
+- **相似模式**：[E216](E216.md)、[E221](E221.md)、[E300](E300.md)
+
+---
+*条目 E451 · 更新 2026-08-25 · 知识库同步生成物*