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

@@ -0,0 +1,74 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E293: 2003 年代旧 C++ 代码在 C++17 标准下动态异常规范 throw(...) 与 register 关键字编译失败
+
+> **严重度**: 🟡 medium | **分类**: c++ | **自动修复**: ✅ toolchain-flag
+
+---
+
+## 错误特征
+
+```
+ISO C\+\+17 does not allow dynamic exception specifications
+ISO C\+\+17 does not allow 'register' storage class specifier
+-Wdynamic-exception-spec
+-Wregister
+throw\(AiksaurusException\)
+```
+
+## 根因
+
+2003 年前后编写的 C++ 代码广泛使用动态异常规范
+throw(Type)（C++17 移除）和 register 存储说明符
+（C++17 移除）。OHOS 编译 profile 设置
+compiler.cppstd=17，clang -std=c++17 下这些特性
+从 warning 升级为 hard error，导致旧 autotools
+项目编译中断。知识图谱引擎常误匹配为工具链缺失
+（E001 cc not found）或 shebang 问题（E165）。
+
+## 验证命令
+
+```bash
+grep -cE "throw\([A-Za-z]|\\bregister\\b" <src>/*.cpp
+```
+
+## 解决方案
+
+**toolchain-flag**：在 conanfile.py generate() 的 AutotoolsToolchain/
+CMakeToolchain 中追加 -Wno-error=dynamic-exception-spec
+与 -Wno-error=register，把这两个诊断降级为 warning
+
+```bash
+tc.extra_cxxflags.append("-Wno-error=dynamic-exception-spec"); tc.extra_cxxflags.append("-Wno-error=register")
+```
+
+## 回退方案
+
+**source-patch**：若降级为 warning 仍无法编译（如 -Werror 传递），
+需 patch 源码：删除 register 关键字、将
+throw(Type) 替换为 noexcept(false)
+
+```bash
+sed -i 's/\\bregister\\b//g' src/*.cpp
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`--build=|--host=.*ohos|set\(CMAKE_CXX_STANDARD 11\)`
+- **原因**：禁止用 --host/--build 绕过（误判交叉编译），
+也禁止把 cppstd 降到 11 掩盖问题（OHOS profile 固定 17）
+- **后果**：级联错误链：交叉编译误判 → AC_RUN_IFELSE 跳过 → config.h 错误 → 运行时崩溃
+
+## 涉及软件
+
+所有 2003 年前后发布的 C++ autotools/cmake 项目，
+在 compiler.cppstd=17 的 OHOS 环境下编译时报错
+
+## 相关模式
+
+- **相似模式**：[E001](E001.md)、[E053](E053.md)
+
+---
+*条目 E293 · 更新 2026-08-05 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E294: 共享包使用第二个静态构建树恢复完整上游测试
+
+> **严重度**: 🟡 medium | **分类**: cmake, cross-compile, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+BUILD_SHARED_LIBS.*tests.*missing
+shared.*only.*public.*tests
+internal.*symbols.*static
+upstream.*test.*targets.*not built
+```
+
+## 根因
+
+部分 CMake 项目在 BUILD_SHARED_LIBS=ON 时只启用公共 API 测试，依赖内部符号的完整测试仅在静态构建中生成。直接把正式包改为静态会改变交付契约；直接关闭测试则丢失上游回归覆盖。交叉构建时还必须区分测试目标编译链接与目标端实际执行。
+
+## 验证命令
+
+```bash
+always build with cmake --build build-tests --parallel; only when Conan can_run is true execute ctest --test-dir build-tests --output-on-failure --no-tests=error
+```
+
+## 解决方案
+
+**dual-cmake-build-tree**：正式构建树保持 shared 和 install；第二个不安装的构建树复用同一 Conan toolchain，设置 BUILD_SHARED_LIBS=OFF、测试 ON、安装 OFF，构建完整上游测试。can_run 为 true 时执行 CTest，为 false 时只记录编译链接证据。
+
+```bash
+cmake -S . -B build-tests -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTING=ON -DCMAKE_SKIP_INSTALL_RULES=ON && cmake --build build-tests --parallel
+```
+
+## 回退方案
+
+**non-installed-static-test-target**：上游已能同时生成 shared/static target 时，可用最小 CMake 补丁让测试链接不安装的 static target；最终 package 仍必须审计为 shared-only。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`BUILD_SHARED_LIBS.*OFF.*package|default_options.*shared.*False`
+- **原因**：仅为跑完整测试而把正式共享包改成静态包，会改变下游 ABI 和交付契约。
+- **后果**：下游链接形态变化，测试结论不能代表所声明的共享包。
+
+### 🚫 禁止 2
+
+- **模式**：`BUILD.*TESTS.*OFF|skip.*upstream.*tests|return.*not.*can_run`
+- **原因**：交叉构建不能成为不编译上游测试的理由；只能跳过无法在构建机执行的目标二进制。
+- **后果**：内部实现和平台兼容错误在 CI 前被隐藏。
+
+## 涉及软件
+
+CMake/Conan 库项目；最终交付必须保持共享库，但上游完整测试依赖静态内部符号或仅在 NOT BUILD_SHARED_LIBS 分支创建。已验证 LevelDB 1.23，适用于结构相同的数据库、压缩、几何和基础设施库。
+
+---
+*条目 E294 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E295: sign-elf 缺失导致 ELF 证据降级为 probe-only（无法证明鸿蒙签名门禁满足）
+
+> **严重度**: 🟡 medium | **分类**: toolchain | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+command -v sign-elf
+sign-elf:.*not found
+sign-elf:.*inaccessible
+探针 ELF.*未完成可交付签名门禁
+codesign.*签名段
+```
+
+## 根因
+
+执行环境没有 sign-elf（command -v sign-elf 无输出），未安装也未伪造签名工具；鸿蒙 ELF 需含有效 .codesign 签名段才能被内核加载（E077），缺少签名工具时编译、上游测试、Conan test_package、Null/loopback 运行结果只能作为探针证据，不能证明可交付 ELF 已满足鸿蒙签名门禁
+
+## 验证命令
+
+```bash
+command -v sign-elf; echo rc=$?
+```
+
+## 解决方案
+
+**record-sign-elf-missing-probe-only**：记录 sign-elf 缺失状态：编译/测试/运行结果仅作探针证据；允许做静态检查（readelf/检查 .codesign 段存在性）但不得宣称交付门禁完成；恢复条件为官方执行环境提供 sign-elf 或框架认可的等价工具后重新签名并重跑相关测试、打包和门禁
+
+```bash
+command -v sign-elf && echo PRESENT || echo MISSING; readelf -S libopenal.so | grep -i codesign || echo "无 .codesign 段（未签名）"
+```
+
+## 回退方案
+
+**request-official-sign-env**：恢复条件：官方执行环境提供 sign-elf 或框架认可的等价签名工具，然后重新签名并重跑相关测试、打包（PackageBuilder）和门禁（conan create/conan-verify/finish/W3）
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip sign|chmod 777|用本地主机可运行.*替代签名|自动申报.*HarmonyOS 系统差异专项|申报.*路径 C`
+- **原因**：跳过签名/chmod 777/本地替代均不能产生有效 .codesign 段；工具缺失不得自动申报为系统差异专项或路径 C
+- **后果**：交付 ELF 无法被鸿蒙内核加载，或专项申报失真
+
+## 涉及软件
+
+所有需要交付可执行 ELF / 动态库的鸿蒙适配库；sign-elf 缺失时相关运行/测试证据一律降级为 probe-only
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)、[E088](E088.md)
+
+---
+*条目 E295 · 更新 2026-08-02 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E296: Complete an OHOS Meson cross file on a Windows build host
+
+> **严重度**: 🟡 medium | **分类**: platform, build-system, meson, cross-compile | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+prefix value 'C:/' must be an absolute path
+Unable to detect linker.*program not executable
+Target: x86_64-w64-windows-gnu
+```
+
+## 根因
+
+Conan's Meson helper derives the install prefix from the Windows build machine, while Meson validates it for the POSIX OHOS target. A CMake-only OHOS user toolchain is not consumed by Meson, so compiler paths alone retain the SDK clang default x86_64-w64-windows-gnu target and omit the OHOS sysroot and Windows-suffixed LLVM archiver tools.
+
+## 验证命令
+
+```bash
+inspect conan_meson_cross.ini for prefix '/', --target=aarch64-linux-ohos, native/sysroot, llvm-ar.exe and llvm-ranlib.exe; then force conan create --build=<package>/*
+```
+
+## 解决方案
+
+**complete-meson-cross-machine**：Use a POSIX target prefix with Meson install staging, derive the SDK sysroot from the structured compiler path, add the OHOS target and sysroot to compile/link args, and inject absolute ar/ranlib paths into the generated Meson cross file.
+
+```bash
+set Meson prefix to /; extend MesonToolchain c_args/cpp_args/c_link_args/cpp_link_args with --target=aarch64-linux-ohos and --sysroot=<sdk>/native/sysroot; set ar and ranlib from the SDK llvm/bin directory
+```
+
+## 回退方案
+
+**dedicated-meson-profile**：Put the same target, sysroot, prefix, and LLVM binary declarations in a project-owned Meson machine file and reference it through tools.meson.mesontoolchain:extra_machine_files.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`tools.cmake.cmaketoolchain:user_toolchain.*MesonToolchain`
+- **原因**：Meson does not load a CMake user toolchain; compiler paths without target/sysroot silently describe the Windows host compiler target.
+- **后果**：Meson rejects the linker or produces host-targeted probes instead of OHOS objects.
+
+### 🚫 禁止 2
+
+- **模式**：`prefix=C:/.*host_machine.*harmonyos`
+- **原因**：A Windows drive prefix is a build-host path, not the POSIX target prefix used with Meson destdir staging.
+- **后果**：Meson setup fails before compilation or installs target paths with host semantics.
+
+## 涉及软件
+
+Conan 2 Meson recipes cross-built from Windows to OHOS armv8 with SDK clang; especially profiles that configure tools.cmake.cmaketoolchain:user_toolchain but only provide c/cpp paths to tools.build:compiler_executables.
+
+---
+*条目 E296 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,49 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E297: 应用包运行时资源完整性检查
+
+> **严重度**: 🟡 medium | **分类**: packaging, runtime | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+No such file or directory.*share
+No such file or directory.*www
+No such file or directory.*config
+Disabling local tree
+```
+
+## 根因
+
+配方只复制可执行文件而遗漏程序按编译时路径查找的网页、配置模板或数据资源，导致程序可启动但功能降级。
+
+## 验证命令
+
+```bash
+在隔离包目录运行功能测试并确认所有编译时资源路径存在。
+```
+
+## 解决方案
+
+**package-runtime-resource-closure**：从上游安装规则和源码路径常量建立运行时资源清单，按相同相对布局打包并测试。
+
+```bash
+copy runtime files to package_folder/share and run packaged binary in an isolated directory
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`copy\(.*["'](bin|app|program)["']`
+- **原因**：仅复制可执行文件不能证明应用运行时资源闭包完整。
+- **后果**：程序可启动但在读取网页、配置或数据时功能降级。
+
+## 涉及软件
+
+安装布局包含 bin 与 share 或 etc 资源的命令行工具、服务和桌面应用。
+
+---
+*条目 E297 · 更新 2026-07-16 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E298: Conan test_package 的显式运行与环境
+
+> **严重度**: 🔴 blocking | **分类**: conan, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library
+cannot open shared object file
+shared library not found
+command not found
+```
+
+## 根因
+
+cmake.test() 把执行委托给 CTest，配方无法显式控制和审计 conanrun 环境；
+消费者需要包内动态库或 CLI 时可能因运行时搜索路径缺失而失败。
+
+## 验证命令
+
+```bash
+conan create . -o '*:shared=True'
+```
+
+## 解决方案
+
+**virtual-run-env-explicit-run**：生成 VirtualRunEnv，并在 test() 中使用 self.run(..., env='conanrun') 显式执行消费者。
+
+```bash
+generators = 'CMakeDeps', 'CMakeToolchain', 'VirtualRunEnv'; self.run(f'"{test_bin}"', env='conanrun', cwd=self.build_folder)
+```
+
+## 回退方案
+
+**ctest-via-conanrun**：必须保留 CTest 时，通过 self.run 在 conanrun 环境中执行 CTest 并打开失败输出。
+
+```bash
+self.run(f'ctest --test-dir "{self.build_folder}" --output-on-failure', env='conanrun', cwd=self.build_folder)
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LD_LIBRARY_PATH=.*\.conan2|PATH=.*\.conan2/p/`
+- **原因**：禁止硬编码开发机 Conan 缓存路径来修补测试运行环境，应由 VirtualRunEnv 生成环境。
+- **后果**：缓存哈希和目录会随机器、配方 revision 与包 ID 变化，测试无法复现。
+
+## 涉及软件
+
+使用 Conan 2 test_package 测试共享库、包内 CLI 或其他运行时资源的 C/C++ 配方。
+
+## 相关模式
+
+- **相似模式**：[E019](E019.md)、[E088](E088.md)、[E212](E212.md)
+
+---
+*条目 E298 · 更新 2026-07-16 · 知识库同步生成物*

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

@@ -0,0 +1,69 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E299: Conan 源码获取失败的分层诊断
+
+> **严重度**: 🔴 blocking | **分类**: conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Could not download from the URL
+sha256 hash failed for
+curl: (28)
+403 Forbidden
+404 Not Found
+Could not resolve host
+SSL certificate problem
+TLS handshake failed
+Connection refused
+Connection reset
+```
+
+## 根因
+
+网络超时、URL 错误和 SHA256 不匹配都发生在 source() 阶段，
+但根因和修复动作不同；仅按“下载失败”摘要会产生误诊。
+
+## 验证命令
+
+```bash
+conan source <recipe> -v
+```
+
+## 解决方案
+
+**classify-source-failure**：先按传输、HTTP 状态和完整性校验分层，再分别修复网络、URL 或可信 SHA256，始终保留官方源或权威镜像。
+
+```bash
+conan source <recipe> -v; sha256sum <official-release-archive>
+```
+
+## 回退方案
+
+**verified-network-fallback**：仅在日志明确出现超时、DNS、TLS 或连接错误时，按 E017 重试或使用 CI 自动镜像回退。
+
+```bash
+curl -fL --retry 3 <official-url> -o <archive>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`raw\.gitcode\.com/.*/blob/|raw\.githubusercontent\.com/.*/(main|master)/`
+- **原因**：禁止用个人仓库 blob 或滚动分支绕过网络、URL 或哈希问题；应使用官方 release 或权威镜像。
+- **后果**：来源不可审计且内容可能漂移，CI 重现性、SHA256 可信度和 R39 合规性同时失效。
+
+## 涉及软件
+
+所有通过 Conan tools.files.get() 和 conandata.yml 下载上游源码的配方。
+
+## 相关模式
+
+- **相似模式**：[E017](E017.md)
+- **前置条件（本条是它们的前置）**：[E017](E017.md)
+
+---
+*条目 E299 · 更新 2026-07-16 · 知识库同步生成物*

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

@@ -0,0 +1,48 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E300: Bridge Conan dependency paths into upstream custom CMake find modules
+
+> **严重度**: 🔴 blocking | **分类**: cmake, conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Could NOT find .* \(missing: .*_INCLUDE_DIR.*_LIBRARY.*\)
+.*_INCLUDE_DIR-NOTFOUND
+.*_LIBRARY-NOTFOUND
+```
+
+## 根因
+
+An upstream Find module may ignore Conan-generated CMake targets and search only legacy include and library cache variables, so a published dependency remains undiscoverable during cross configuration.
+
+## 验证命令
+
+```bash
+Inspect the upstream Find module inputs, verify the exact header and library under self.dependencies, and confirm CMakeCache.txt binds both variables to that Conan package revision.
+```
+
+## 解决方案
+
+**cmake-cache-path-bridge**：Resolve and validate the dependency header and library from self.dependencies, then pass the exact cache variables expected by the upstream Find module through CMakeToolchain.
+
+```bash
+Set <DEP>_INCLUDE_DIR and <DEP>_LIBRARY from the verified Conan package paths before tc.generate().
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`hard-coded system include or library path`
+- **原因**：System paths bypass the locked Conan package and can select host or stale target artifacts.
+- **后果**：Non-reproducible configure results or host contamination in the target build.
+
+## 涉及软件
+
+CMake projects that ship custom Find modules instead of consuming dependency config targets, especially cross builds without system search paths.
+
+---
+*条目 E300 · 更新 2026-07-30 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E301: Conan CMake.test cli_args are build arguments, not CTest arguments
+
+> **严重度**: 🟡 medium | **分类**: cmake, conan, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+cmake --build.*--target test.*--output-on-failure
+Unknown argument --output-on-failure
+```
+
+## 根因
+
+In Conan 2, CMake.test() runs cmake --build with the test target, so its cli_args are routed to cmake --build; only CMake.ctest() routes cli_args to ctest.
+
+## 验证命令
+
+```bash
+Inspect conan.tools.cmake.CMake.test and CMake.ctest, then run conan create on a host where can_run() is true.
+```
+
+## 解决方案
+
+**use-cmake-ctest-helper**：Use cmake.ctest(cli_args=[...]) for CTest options after cmake.build(); reserve cmake.test() for invoking the build system test target with build arguments.
+
+```bash
+Replace cmake.test(cli_args=["--output-on-failure"]) with cmake.ctest(cli_args=["--output-on-failure"]).
+```
+
+## 回退方案
+
+**explicit-ctest-run**：Run ctest explicitly from the CMake build folder with the Conan build and run environments activated.
+
+```bash
+ctest --output-on-failure
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`cmake\.test\(cli_args=.*--output-on-failure`
+- **原因**：--output-on-failure is a CTest option, but CMake.test() forwards cli_args to cmake --build.
+- **后果**：Native or target-device builds fail before running any tests, while cross builds may hide the defect behind can_run() == false.
+
+## 涉及软件
+
+Conan 2 CMake recipes that run upstream CTest suites and pass CTest flags through CMake.test(cli_args=...).
+
+---
+*条目 E301 · 更新 2026-07-19 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E302: Gate open_memstream on its close and flush contract, not symbol presence
+
+> **严重度**: 🔴 blocking | **分类**: detection, libc | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+PosixMemstreamTest\.CanCheckBufferWithContents
+HAVE_OPEN_MEMSTREAM=1
+Actual: ''
+```
+
+## 根因
+
+A target libc can export open_memstream while fclose rejects its cookie stream before flushing buffered data, so symbol-only CMake detection enables a capability whose observable contract is broken.
+
+## 验证命令
+
+```bash
+On the target, write a sub-BUFSIZ string to open_memstream, require fclose to return zero, and compare the resulting buffer; then rerun every test target that consumes the wrapper.
+```
+
+## 解决方案
+
+**behavior-probe-or-evidence-bound-disable**：Prefer a target behavior probe that verifies write, fclose, and buffer publication. When cross configuration cannot run it, use an evidence-bound target override to disable the capability and retain the upstream fallback path.
+
+```bash
+Set HAVE_OPEN_MEMSTREAM=OFF only for a target whose runtime probe or libc implementation proves the close and flush contract is unusable.
+```
+
+## 回退方案
+
+**writable-real-file-capture**：If output comparison remains required, use a writable real file stream under TMPDIR and preserve the same readback assertions.
+
+```bash
+Route capture through a normal file opened below TMPDIR and validate cleanup plus exact content.
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`fflush\(.*\).*fclose\(|change expected output to empty|skip the complete test target`
+- **原因**：A pre-flush workaround can leave the broken cookie stream unclosed, while changing references or skipping targets hides the failed runtime contract.
+- **后果**：Resource leaks or false-positive test results remain even though the immediate empty-output assertion disappears.
+
+## 涉及软件
+
+CMake projects and test frameworks that use open_memstream to capture FILE output, especially cross builds that cannot run configure-time probes.
+
+---
+*条目 E302 · 更新 2026-07-30 · 知识库同步生成物*

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

@@ -0,0 +1,65 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E303: 受限进程不可枚举根目录导致 hostfs 身份探测误判
+
+> **严重度**: 🔴 blocking | **分类**: restricted-process-filesystem-probe | **自动修复**: ❌ | **原则**: [P013](../principles.md#P013)、[P015](../principles.md#P015)
+
+---
+
+## 错误特征
+
+```
+error: can't open `/': Permission denied[.]?
+opendir.*[/].*EACCES
+```
+
+## 根因
+
+受限运行域可能允许路径搜索和已知文件访问，却拒绝读取根目录项；hostfs 将仅用于确认宿主伪磁盘的 opendir("/") EACCES 当成坏文件名，使真实目标文件尚未检查就提前失败
+
+## 验证命令
+
+```bash
+x86_64-elf-grub-file --is-x86-multiboot multiboot.o
+```
+
+## 解决方案
+
+**scope-root-probe-eacces**：仅当 errno 为 EACCES 且探测路径严格等于 / 时，把 hostfs 身份探测视为成功；按运行时能力失败判断而不依赖平台宏，后续实际文件打开仍由原有函数校验并保留所有其他错误
+
+```bash
+patch --dry-run --fuzz=0 -p1 -d "$GRUB_SOURCE_ROOT" -i "$RECIPE_ROOT/patches/0010-grub-core-kern-emu-hostfs.c.patch"
+```
+
+## 回退方案
+
+**use-explicit-accessible-root**：若上游调用接口允许，显式传入应用域可枚举的包目录，避免把 / 作为身份探测路径
+
+```bash
+invoke the tool with an explicit accessible module directory
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ignore.*opendir.*error|return.*GRUB_ERR_NONE.*all`
+- **原因**：无条件吞掉目录打开错误会把 ENOENT、ENOTDIR 和真实权限故障伪装成成功
+- **后果**：后续访问在更远位置失败且诊断信息丢失
+
+### 🚫 禁止 2
+
+- **模式**：`chmod.* /|chown.* /|disable.*sandbox|run.*root`
+- **原因**：修改系统根目录权限或绕过应用安全域不属于三方库适配边界
+- **后果**：破坏系统安全模型且在 CI/用户环境不可复现
+
+## 涉及软件
+
+在容器、沙箱或应用安全域等受限进程中以根目录枚举作为文件系统身份或能力探测、而实际数据访问另有独立校验的宿主侧工具
+
+## 相关模式
+
+- **相似模式**：[E031](E031.md)、[E212](E212.md)
+
+---
+*条目 E303 · 更新 2026-07-19 · 知识库同步生成物*