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

@@ -0,0 +1,45 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E283: Conan library 包的 shared 选项契约
+
+> **严重度**: 🔴 blocking | **分类**: conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Package type is 'library', but no 'shared' option declared
+```
+
+## 根因
+
+Conan 的 library 包类型要求标准 shared 选项决定包 ID 和链接类型，缺失时配方契约无效。
+
+## 验证命令
+
+```bash
+分别以 shared=False 和 shared=True 执行 conan create 并检查包 ID。
+```
+
+## 解决方案
+
+**declare-shared-contract**：声明标准 shared 选项和默认值，并将该选项传递给构建系统。
+
+```bash
+options = {'shared': [True, False]}; default_options = {'shared': False}
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **原因**：library 包必须同时检查标准 shared 选项是否存在并传入构建系统。
+- **后果**：Conan 拒绝创建包或同一包 ID 对应不确定链接类型。
+
+## 涉及软件
+
+所有声明 package_type=library 的 Conan 2 配方。
+
+---
+*条目 E283 · 更新 2026-07-16 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E284: 交叉构建时生成目标平台配置头而非复用 host 探测结果
+
+> **严重度**: 🟡 medium | **分类**: portability, configure, cross-compile | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+unknown type name.*u_int16_t
+sparseconfig.h
+generated.*config.*host
+target.*configuration header
+```
+
+## 根因
+
+Autoconf/CMake 生成的 config.h 类头文件记录运行探测环境的类型、命名空间和功能宏；交叉构建若复用 Windows 或其他 host 生成结果，会把主机能力误当成 OHOS 目标能力。
+
+## 验证命令
+
+```bash
+使用 OHOS target compiler 编译上游测试和真实消费者，再在 HarmonyOS PC 上签名并执行目标 ELF
+```
+
+## 解决方案
+
+**generate-target-config-header**：根据已验证的目标平台能力显式生成最小配置头，并用目标编译器编译上游测试与真实消费者
+
+```bash
+conan.tools.files.save() 生成目标 config 头；clang++ --target=aarch64-linux-ohos 编译验证
+```
+
+## 回退方案
+
+**target-toolchain-configure**：若构建系统支持可靠交叉探测，使用目标 toolchain 运行 configure 并审计缓存结果
+
+```bash
+configure --host=aarch64-linux-ohos --build=<host-triplet>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`直接复制 Windows 或本机 configure 生成的 config.h 到 OHOS 包`
+- **原因**：配置头描述的是 host 能力而非 target 能力
+- **后果**：目标编译失败、ABI/类型判断错误或运行期未定义行为
+
+## 涉及软件
+
+依赖 configure 生成 config.h、sparseconfig.h 或类似能力头文件的 C/C++ 库，尤其是 header-only 库的 Conan 交叉配方
+
+---
+*条目 E284 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,63 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E285: OpenAL 类音频库在无音频设备环境下关闭外部后端并以 Null/loopback 完成构建与替代验证
+
+> **严重度**: 🟡 medium | **分类**: portability | **自动修复**: ✅ cmake-option-disable-backends
+
+---
+
+## 错误特征
+
+```
+No Output
+ALC_SOFT_loopback
+alcRenderSamplesSOFT
+ALSOFT_TESTS
+audio backend
+ALSA
+PulseAudio
+PipeWire
+sign-elf
+no audio device
+```
+
+## 根因
+
+OHOS PC / 无真实音频设备环境缺少 ALSA/PulseAudio/PipeWire 等外部音频后端依赖与硬件；默认配置会因缺依赖失败，上游测试与运行验证依赖真实设备而无法直接执行，需要显式关闭外部后端并保留源码内置 Null/loopback 后端，同时把上游 ctest 与替代验证分开统计
+
+## 验证命令
+
+```bash
+ctest --test-dir build-tests --output-on-failure -V
+```
+
+## 解决方案
+
+**disable-external-backends-keep-null-loopback**：CMake 配置时显式关闭全部外部音频后端（ALSA/PulseAudio/PipeWire/JACK/OSS/Solaris/SndIO/PortAudio/SDL2/SDL3/WaveFile/Oboe/OpenSL/CoreAudio）并关闭 DLOPEN/Modules/Utils/Examples，仅保留源码内置 Null/loopback 后端；单独以 ALSOFT_TESTS=ON 构建 OpenAL_Tests 并运行 ctest；无真实设备时用 No Output null 后端与 ALC_SOFT_loopback+alcRenderSamplesSOFT 作替代验证，两者分开统计
+
+```bash
+cmake -S . -B build-tests -DALSOFT_TESTS=ON -DALSOFT_UTILS=OFF -DALSOFT_EXAMPLES=OFF -DALSOFT_DLOPEN=OFF -DALSOFT_ENABLE_MODULES=OFF -DALSOFT_BACKEND_WAVE=OFF -DALSOFT_BACKEND_ALSA=OFF -DALSOFT_BACKEND_PULSEAUDIO=OFF -DALSOFT_BACKEND_PIPEWIRE=OFF -DALSOFT_BACKEND_JACK=OFF -DALSOFT_BACKEND_OSS=OFF -DALSOFT_BACKEND_SOLARIS=OFF -DALSOFT_BACKEND_SNDIO=OFF -DALSOFT_BACKEND_PORTAUDIO=OFF -DALSOFT_BACKEND_SDL2=OFF -DALSOFT_BACKEND_SDL3=OFF && cmake --build build-tests -j4 && ctest --test-dir build-tests --output-on-failure -V
+```
+
+## 回退方案
+
+**loopback-alternative-verification**：无真实音频设备时，用 $HOME/tmp 下的临时验证程序走 ALC_SOFT_loopback（alcLoopbackOpenDeviceSOFT + alcCreateContext 属性列表 ALC_FORMAT_CHANNELS_SOFT/ALC_FORMAT_TYPE_SOFT/ALC_FREQUENCY + alcRenderSamplesSOFT）与 No Output null 后端，作为替代验证单独统计，不覆盖上游 ctest 结果
+
+```bash
+clang++ -std=c++20 openal-probe-verify.cpp -I include -L build-tests -lopenal -o openal-probe-verify && LD_LIBRARY_PATH=build-tests ./openal-probe-verify
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`把二进制 zip 的 SHA256 当源码 SHA256|伪造.*hash|未执行.*测试.*写成.*100%`
+- **原因**：上游 GitHub Release 未提供源码包官方 SHA256，只有二进制 zip digest；测试未执行或不可执行时必须记录真实原因与真实通过率
+- **后果**：数据失真导致门禁与路径判定错误
+
+## 涉及软件
+
+OpenAL 生态及同类音频后端 C/C++ 库（CMake 构建、后端可选项）在无音频设备 / 缺后端依赖环境下的适配与验证
+
+---
+*条目 E285 · 更新 2026-08-02 · 知识库同步生成物*

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

@@ -0,0 +1,89 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E286: OHOS SDK LLVM 15 缺失完整 LLVM 插件/lit/TableGen 组件，导致 enzyme 等 LLVM pass/plugin 类库无法完整构建与运行上游测试
+
+> **严重度**: 🔴 blocking | **分类**: ohos, cmake, toolchain, llvm, testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Library.*LLVMExports.*not found
+LLVMDemangle.*not found
+symbol not found.*_ZN4llvm
+Error relocating.*libLLVMEnzyme
+handleBLAS.*undeclared
+attributeTablegen.*undeclared
+tablegen stub failed
+llvm-tblgen.*not found
+FileCheck.*not found
+lit.*not found
+LLVMConfig.cmake.*FATAL_ERROR
+add_llvm_library
+configure_lit_site_cfg
+llvmGetPassPluginInfo
+```
+
+## 根因
+
+OHOS SDK LLVM 15 (/data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/) 仅提供单体共享库 libLLVM-15.so 与基本 clang/lld，但缺失 LLVM AutoDiff 插件类库所需的完整组件：(1) LLVMExports.cmake 引用不存在的 .a stub 文件（LLVMDemangle.a/LLVMSupport.a/LLVMCore.a 等），CMake 在 find_package(LLVM) 时触发 FATAL_ERROR；(2) 无 llvm-tblgen 二进制，导致 Enzyme 的 TableGen 描述（BlasDerivatives.td/CallDerivatives.td 等）无法生成 .inc 文件，编译时 handleBLAS/attributeTablegen 等 undeclared；(3) 无 lit/FileCheck/llvm-lit，上游 1523 个 lit 测试用例无法执行；(4) 单体 libLLVM-15.so 未导出部分 LLVM C++ API 符号（如 llvm::cl::Option::setArgStr），导致 dlopen 加载 Enzyme 插件库时 symbol not found。现有知识库 E120/E132 仅覆盖 lld/libxml2/LD_LIBRARY_PATH 类运行时路径问题，未覆盖 LLVMExports .a stub/LLVMDemangle/TableGen/tblgen/lit/FileCheck/符号导出 的组合问题。
+
+## 验证命令
+
+```bash
+ls /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/lib/cmake/llvm/LLVMExports.cmake && ls /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/bin/llvm-tblgen 2>&1; which lit FileCheck llvm-lit 2>&1; nm -D /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/lib/libLLVM-15.so | grep -c "llvm::cl::Option::setArgStr"
+```
+
+## 解决方案
+
+**cmake-overlay-with-stub-tblgen-and-skip-lit**：1) 提供 cmake-overlay/LLVMConfig.cmake 覆盖 OHOS SDK 的 LLVMConfig.cmake，跳过引用不存在 .a stub 的 LLVMExports.cmake，改为创建指向单体 libLLVM-15.so 的 IMPORTED target（LLVM/LLVMDemangle/LLVMSupport/LLVMCore/LLVMTransformUtils/LLVMAnalysis）；2) 提供 cmake-overlay/AddLLVM.cmake stub 实现 tablegen()/add_llvm_library()/add_public_tablegen_target()/configure_lit_site_cfg()/get_llvm_lit_path() 等 Enzyme 构建所需的 LLVM CMake 函数；3) 提供 cmake-overlay/stub-tblgen.sh（需 chmod +x）生成最小 .inc 桩文件，为 BlasDerivatives.inc 提供 return false 的 handleBLAS、为 BlasAttributor.inc 提供 return false 的 attributeTablegen 等，使源码编译通过；4) build() 中跳过 enzyme/test 子目录（lit 测试体系无法在 OHOS 上运行）；5) conanfile.py export_sources/source() 复制 overlay 到源码树，generate() 设 LLVM_DIR 指向 overlay；6) test_package 用 dlopen(libLLVM-15.so, RTLD_GLOBAL) 预加载 LLVM 符号 + dlopen(libLLVMEnzyme-15.so) + dlsym(llvmGetPassPluginInfo) + 实际调用验证插件入口可执行；7) runtime 加载仍可能因单体 .so 未导出部分 C++ 符号而 symbol not found——此为 OHOS SDK LLVM 工具链缺口，记录为路径 C 候选需官方确认。
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing --user=ohpcd --channel=stable
+```
+
+## 回退方案
+
+**provide-pre-generated-inc-files**：在完整 LLVM 15 环境上用 enzyme-tblgen 预生成 8 个 .inc 文件（BlasDerivatives/CallDerivatives/BinopDerivatives/IntrinsicDerivatives/InstructionDerivatives/BlasAttributor/BlasTA/BlasDiffUse），作为 patches/ 打入源码树，绕过 stub-tblgen.sh 的空桩问题。需外部完整 LLVM 15 工具链，非本仓库可独立完成。
+
+```bash
+enzyme-tblgen -o BlasDerivatives.inc BlasDerivatives.td -gen-enzyme-blas-derivatives
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`直接修改 OHOS SDK 目录下只读的 LLVMExports.cmake|强制 ln -sf 覆盖 SDK 文件`
+- **原因**：OHOS SDK 安装目录为只读，且直接修改 SDK 文件会污染其他软件的构建环境
+- **后果**：写入失败或破坏其他软件构建
+
+### 🚫 禁止 2
+
+- **模式**：`stub-tblgen.sh 无执行权限|chmod -x stub-tblgen.sh`
+- **原因**：stub-tblgen.sh 由 execute_process 调用，无执行权限会触发 "permission denied" 并生成空文件，导致 handleBLAS/attributeTablegen undeclared 编译错误
+- **后果**：BlasDerivatives.inc/BlasAttributor.inc 为空，编译失败于 CallDerivatives.cpp:2254 与 Utils.cpp:410
+
+### 🚫 禁止 3
+
+- **模式**：`把上游 lit 测试写成 100% 通过|勾选"上游无测试"|把 stub .inc 桩写成完整功能`
+- **原因**：上游 enzyme/test 下有 1523 个 lit 测试文件，OHOS SDK 缺 lit/FileCheck/llvm-lit 无法执行；stub .inc 仅返回 false 非真实 BLAS 规则
+- **后果**：误判测试通过率，AI Review/CI 审核拒绝
+
+### 🚫 禁止 4
+
+- **模式**：`test_package dlopen 失败返回 0|只打印 OK 不实际调用 llvmGetPassPluginInfo`
+- **原因**：R34 要求 test 必实质依赖被测包；dlopen 失败返回 0 为 false pass
+- **后果**：R34 违规，CI L1e 破性反向验证兜底失败
+
+## 涉及软件
+
+所有依赖完整 LLVM 15 CMake 导出（LLVMExports/LLVMConfig）、TableGen/tblgen 代码生成、lit/FileCheck 测试体系、或 LLVM C++ 插件 API 的 LLVM pass/plugin 类库（enzyme、Polly、MLIR plugins 等），在 OHOS SDK LLVM 上构建与测试
+
+## 相关模式
+
+- **根因条目（应先修它们）**：[E120](E120.md)、[E132](E132.md)
+
+---
+*条目 E286 · 更新 2026-07-23 · 知识库同步生成物*

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

@@ -0,0 +1,87 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E287: AFL/fuzz corpus 替代测试框架 — 基于上游 fuzzin 语料
+的确定性 runner，适用于 OHOS CI 无法原样运行
+AFL/tmux/sudo/sysfs/TFTP 网络交互测试的场景
+
+> **严重度**: 🔴 blocking | **分类**: testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+pcap_activate:.*CAP_NET_RAW
+Timeout while waiting for ACK
+afl-fuzz: command not found
+tmux: command not found
+sudo:.*not found
+sysfs.*not available
+TFTP.*timeout
+no CAP_NET_RAW
+Cannot open raw socket
+```
+
+## 根因
+
+部分 C/C++ 命令行工具（如 nmrpflash）上游提供 AFL 模糊测试
+入口（fuzz.c + fuzz.bash + fuzzin/ 语料），但原样运行依赖
+AFL/tmux/sudo/Linux sysfs/CAP_NET_RAW/TFTP 网络交互环境，
+这些在 OHOS 交叉编译 CI 中无法满足。具体障碍：
+1) AFL 编译器（afl-clang-fast）不可用
+2) tmux 终端复用器不可用
+3) sudo 无 raw socket 权限（鸿蒙 sudo 为自研简化版）
+4) /proc/sys/kernel/core_pattern 等 sysfs 不可写
+5) CAP_NET_RAW 未授予，pcap_open_live 失败
+6) TFTP 网络服务无法在 CI 中部署
+7) /tmp 只读（erofs），AFL 需要可写临时目录
+
+## 验证命令
+
+```bash
+# 编译 fuzz.c（无 AFL 依赖，替换 AFL_CC → CC）
+CC=clang
+CFLAGS="-I\$SRC -I\$LIBNL_INC -I\$LIBPCAP_INC -D_DEFAULT_SOURCE -D_GNU_SOURCE"
+LDFLAGS="-L\$LIBNL_DIR -L\$LIBPCAP_DIR -lnl-route-3 -lnl-3 -lpcap"
+\$CC -c \$CFLAGS \$SRC/fuzz.c
+\$CC fuzz.o tftp.o util.o nmrp.o ethsock.o -o fuzz \$LDFLAGS
+# 运行 corpus
+./fuzz nmrp
+./fuzz tftp <corpus_file>
+```
+
+## 解决方案
+
+**fuzz-corpus-deterministic-runner**：使用上游 fuzz.c + fuzzin/ 语料，替换 AFL 编译器为
+标准 CC 编译，构建确定性 corpus runner。fuzz.c 本身无
+AFL 依赖（仅需标准 C 库和项目头文件），AFL 依赖仅在
+Makefile 的 fuzz target 中（afl-clang-fast）。编译后
+运行 fuzzin/ 语料文件，验证无崩溃（segfault/abort）即
+通过。注意：这不是上游原样测试通过率，不能替代真实
+网络服务测试。
+
+```bash
+# 见 verification_cmd 编译命令。运行：
+# NMRP 模式：./fuzz nmrp
+# TFTP 模式：./fuzz tftp <path/to/fuzzin/tftp.bin>
+```
+
+## 回退方案
+
+**回退 1**
+
+```bash
+# 如果 fuzz.c 不可用，可退而求其次：
+# 1. 仅运行二进制 smoke test（-V 版本检查）
+# 2. 在 PR 正文中详细说明上游测试入口核验结果
+# 3. 创建 test_package 验证二进制基本运行
+```
+
+## 涉及软件
+
+所有带 AFL fuzz 入口、fuzz corpus、网络交互测试、
+原始 socket 操作但 OHOS CI 无法原样运行的 C/C++ 命令行库。
+已知适用：nmrpflash 0.9.27（已验证）
+
+---
+*条目 E287 · 更新 2026-07-23 · 知识库同步生成物*

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

@@ -0,0 +1,47 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E288: CMake 双库目标收敛为单一可选产物
+
+> **严重度**: 🟡 medium | **分类**: cmake, packaging | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+package contains both .*\.a and .*\.so
+BUILD_SHARED_LIBS.*ignored
+```
+
+## 根因
+
+上游显式定义 STATIC 和 SHARED 两个目标时 BUILD_SHARED_LIBS 不参与目标类型选择，包会同时安装两类库。
+
+## 验证命令
+
+```bash
+( set -eu; REF="pkg/version"; PKG="${REF%%/*}"; VER="${REF#*/}"; WORK_ROOT="$(mktemp -d)"; trap 'rm -rf "$WORK_ROOT"' EXIT; STATIC_DEPLOY="$WORK_ROOT/static"; SHARED_DEPLOY="$WORK_ROOT/shared"; conan create recipe -o "$PKG/*:shared=False"; conan create recipe -o "$PKG/*:shared=True"; conan install --requires="$REF" -o "$PKG/*:shared=False" --deployer=full_deploy --deployer-folder="$STATIC_DEPLOY"; conan install --requires="$REF" -o "$PKG/*:shared=True" --deployer=full_deploy --deployer-folder="$SHARED_DEPLOY"; STATIC_ROOT="$STATIC_DEPLOY/full_deploy/host/$PKG/$VER"; SHARED_ROOT="$SHARED_DEPLOY/full_deploy/host/$PKG/$VER"; STATIC_LIB="$(find "$STATIC_ROOT" -type d -name lib -print -quit)"; SHARED_LIB="$(find "$SHARED_ROOT" -type d -name lib -print -quit)"; test -n "$STATIC_LIB"; test -n "$SHARED_LIB"; test -n "$(find "$STATIC_LIB" -type f -name '*.a' -print -quit)"; test -z "$(find "$STATIC_LIB" \( -type f -o -type l \) -name '*.so*' -print -quit)"; test -n "$(find "$SHARED_LIB" \( -type f -o -type l \) -name '*.so*' -print -quit)"; test -z "$(find "$SHARED_LIB" -type f -name '*.a' -print -quit)"; )
+```
+
+## 解决方案
+
+**single-cmake-library-target**：将双目标改为一个未显式指定类型的 add_library 目标，让 BUILD_SHARED_LIBS 决定产物。
+
+```bash
+cmake -S . -B build -DBUILD_SHARED_LIBS=OFF
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`add_library\([^)]*STATIC|add_library\([^)]*SHARED`
+- **原因**：显式双目标会绕过 BUILD_SHARED_LIBS 的统一选择。
+- **后果**：包内同时出现静态和共享库，Conan shared 选项失效。
+
+## 涉及软件
+
+同时定义静态和共享目标且由 Conan shared 选项控制的 CMake 项目。
+
+---
+*条目 E288 · 更新 2026-07-16 · 知识库同步生成物*

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

@@ -0,0 +1,67 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E289: HELP2MAN=true 未生成手册页但 Automake 仍安装 man_MANS 导致失败
+
+> **严重度**: 🔴 blocking | **分类**: autotools, install | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+install: cannot stat .*\.[1-9].*: No such file or directory
+No rule to make target .*\.[1-9].*install-man
+```
+
+## 根因
+
+把 HELP2MAN 设置为 true 只会让生成命令成功返回而不产生手册页；Automake 生成的 man_MANS 安装清单仍非空，install-man 目标因此读取不存在的文件并失败
+
+## 验证命令
+
+```bash
+make install DESTDIR="$DESTDIR" man_MANS=
+```
+
+## 解决方案
+
+**clear-automake-man-list**：禁用 help2man 时，在 make install 命令行显式传入 man_MANS=，使 Automake 不执行缺失手册页的安装规则
+
+```bash
+make install DESTDIR="$DESTDIR" man_MANS=
+```
+
+## 回退方案
+
+**provide-working-help2man**：构建环境可执行目标工具且能安装 help2man 时，保留原 man_MANS 并真实生成手册页
+
+```bash
+make && make install DESTDIR="$DESTDIR"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`HELP2MAN=true.*make install`
+- **原因**：仅替换生成器不会清空 Automake 的 man_MANS 安装清单
+- **后果**：安装阶段仍因手册页不存在而失败
+
+### 🚫 禁止 2
+
+- **模式**：`touch .*\.[1-9]|: > .*\.[1-9]`
+- **原因**：伪造空手册页会掩盖文档生成与安装清单不一致
+- **后果**：包中出现无效文档且真实构建缺陷未解决
+
+### 🚫 禁止 3
+
+- **模式**：`make install.*\|\| true|make -k install`
+- **原因**：忽略安装失败无法证明制品完整
+- **后果**：缺失文件的包可能被错误标记为构建成功
+
+## 涉及软件
+
+使用 Automake man_MANS 安装由 help2man 生成的手册页，并在交叉构建中用 true 替代文档生成器的项目
+
+---
+*条目 E289 · 更新 2026-07-18 · 知识库同步生成物*

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

@@ -0,0 +1,67 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E290: CMake 类型探测不能使用 check_symbol_exists
+
+> **严重度**: 🟡 medium | **分类**: detection, portability, cmake | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+check_symbol_exists.*typedef
+HAVE_.*TYPE.*FALSE
+unknown type name.*__kernel_
+__kernel_rwf_t
+```
+
+## 根因
+
+check_symbol_exists 只适合宏、函数和变量；对 typedef 或类型别名会尝试取地址并必然编译失败，使实际存在的目标类型被误判为不存在。
+
+## 验证命令
+
+```bash
+cmake -S . -B build && cmake --build build --verbose
+```
+
+## 解决方案
+
+**compile-probe-for-type**：用目标编译器编译一个包含目标头文件、声明该类型变量的最小源码，使 HAVE_* 结果与目标头文件中的真实类型定义一致
+
+```bash
+include(CheckCSourceCompiles); check_c_source_compiles("#include <header.h>\nint main(void) { target_type *value = 0; return value != 0; }" HAVE_TARGET_TYPE)
+```
+
+## 回退方案
+
+**check-type-size**：需要同时获取类型大小时使用 CheckTypeSize，但仍必须让目标 toolchain 完成编译探测
+
+```bash
+include(CheckTypeSize); check_type_size("target_type" TARGET_TYPE_SIZE)
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`check_symbol_exists.*typedef|check_symbol_exists.*_t\b`
+- **原因**：typedef 不是可取地址的符号，检测会稳定地产生假阴性
+- **后果**：HAVE_* 宏错误、目标功能被静默禁用或后续编译失败
+
+### 🚫 禁止 2
+
+- **模式**：`手工强制 HAVE_.*TYPE.*1|直接写入生成的 config.h`
+- **原因**：绕过目标编译器会把 host 假设写入 target 配置
+- **后果**：交叉构建选择错误代码路径，产生 ABI 或运行时风险
+
+## 涉及软件
+
+将 Autoconf AC_CHECK_TYPES 或其他类型能力探测迁移到 CMake 的 C/C++ 项目，包括原生构建和交叉构建
+
+## 相关模式
+
+- **相似模式**：[E151](E151.md)
+
+---
+*条目 E290 · 更新 2026-07-24 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E291: 既有正式条目的 graph validate 问题导致 finish/W4 阻塞（repository_baseline_blocked）
+
+> **严重度**: 🔴 blocking | **分类**: repository-baseline-blocked | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+STEP_FAILED: Step6
+W4.*知识图谱完整性检查发现
+graph validate 报告问题
+finish.*退出码.*1
+non-standard fields
+unknown principle
+```
+
+## 根因
+
+仓库 〈外部知识库路径〉 的既有正式条目（E213/E214 等）存在 non-standard fields / unknown principle 等 graph validate 问题，W4 知识图谱完整性检查因此报告 1 类问题；即使当前库自身 conan create=0、conan-verify=0、W3 本地 CI 通过且 .ci-result.json 由框架生成，finish 顶层退出码仍为 1（STEP_FAILED: Step6），内部知识整理 EXIT_CODE=0 不能替代 finish 顶层通过
+
+## 验证命令
+
+```bash
+python3 scripts/ohc-run.py graph validate 2>&1 | grep -E 'E213|E214|errors|warnings'
+```
+
+## 解决方案
+
+**record-repository-baseline-blocked**：记录 repository_baseline_blocked 状态：保存 graph validate 命令、退出码、首个错误、finish 日志和恢复条件；不把 W3 或 .ci-result.json 单独写成 finish 通过；不把 E213/E214 修复混入当前库 PR
+
+```bash
+python3 scripts/ohc-run.py graph validate > validate.log 2>&1; echo rc=$?; python3 scripts/ohc-run.py finish <软件> <版本> built > finish.log 2>&1; echo rc=$?
+```
+
+## 回退方案
+
+**wait-repo-maintainer-fix**：恢复条件：仓库维护者修复既有 E213/E214 等基线条目后，重新执行当前库的 conan create、conan-verify、finish、W3
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`把.*\.ci-result\.json.*写成.*finish.*通过|手动修改.*\.ci-result\.json|修复.*E213.*E214.*混入当前库 PR|跳过.*W4`
+- **原因**：W3/.ci-result.json 只证明 W3 本地 CI 通过，不能替代 finish 顶层通过；E213/E214 是仓库基线条目修复，应单独 PR 处理
+- **后果**：门禁数据失真或混包，审核不通过
+
+## 涉及软件
+
+所有需要执行 finish 的库（W4/Step6 依赖全库 graph validate 通过，基线条目问题会阻塞任何库的 finish 顶层通过）
+
+---
+*条目 E291 · 更新 2026-08-02 · 知识库同步生成物*

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

@@ -0,0 +1,81 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E292: 大型 C++ 数据处理库上游测试在 OHOS 上需要分层迁移和环境补齐
+
+> **严重度**: 🔴 blocking | **分类**: testing | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+gtest_captured_stream
+PARQUET_TEST_DATA
+ARROW_TEST_DATA
+discover_tz_dir
+Cannot locate timezone
+std::ranges::equal
+Error loading shared library .*release.*so
+duplicate libarrow_gtest
+SIGTRAP 133
+jobserver mkfifo
+posix_fadvise failed
+OpenAppendStream
+Boost.Context.*x86_64
+make_x86_64_sysv_elf_gas
+DST
+Broken_Hill
+std::bad_alloc
+OutOfMemory
+ResizeOOM
+Signal 11
+symlink.*Permission denied
+hardlink.*Operation not permitted
+OpenSSL::SSL
+OpenSSL::Crypto
+```
+
+## 根因
+
+大型 C++ 数据处理库的上游测试同时依赖 CTest/GTest、官方测试数据、timezone 数据、动态库加载路径、C++20 标准库能力、平台文件系统语义和重依赖 FetchContent 源码包; OHOS Conan 真机环境缺少这些 Linux 开发机默认条件, 且当前测试文件系统可能拒绝 symlink/hardlink, 导致无法直接声明完整上游测试通过
+
+## 验证命令
+
+```bash
+ctest --output-on-failure; ctest --output-on-failure -R parquet; ctest --output-on-failure -R 'arrow-(dataset|acero)'; sh scripts/ohos-probe-upstream-modules.sh --module flight --grpc-src <pre-extracted-grpc>
+```
+
+## 解决方案
+
+**layered-ctest-migration**：先按 CTest target inventory 区分可执行 C++ 子集、需额外环境子集和不可执行子集; 对可执行子集补齐 TEST_TMPDIR/TMPDIR、ARROW_TEST_DATA、PARQUET_TEST_DATA、TZDIR、单一动态库目录和 basename NEEDED 等环境; timezone 用例需记录 tzdb 来源和版本, 不应未验证就把系统 zoneinfo 作为默认回退; compute-on 或 Boost.Context 场景需显式设置 CMAKE_SYSTEM_PROCESSOR/BOOST_CONTEXT_ARCHITECTURE; Flight/gRPC 等重依赖探针需先检查 FetchContent 源码包是否含 symlink/hardlink, 必要时使用 no-links 预解包并通过 FETCHCONTENT_SOURCE_DIR_* 注入; 若继续缺少 OpenSSL/BoringSSL 等依赖, 应记录为依赖闭环缺口而不是目标测试失败; 必要时给 GTest/date 等测试或运行时基础设施增加通用环境变量入口; 对可归纳为通用防御语义的平台差异采用 POSIX 兼容修复, 其余差异独立报告说明
+
+```bash
+export TMPDIR=$PWD/tmp ARROW_TEST_DATA=$ROOT/testing/data PARQUET_TEST_DATA=$ROOT/cpp/submodules/parquet-testing/data TZDIR=$HOME/.local/lib/python3.12/site-packages/tzdata/zoneinfo; cmake -DCMAKE_SYSTEM_PROCESSOR=aarch64 -DBOOST_CONTEXT_ARCHITECTURE=arm64 -DBOOST_CONTEXT_ABI=aapcs; ctest -j1 --output-on-failure
+```
+
+## 回退方案
+
+**consumer-test-package-plus-difference-report**：若完整上游测试无法在当前 OHOS 环境闭环, 至少提供 Conan test_package 运行时 API 验证, 并将未执行或未通过子集的环境缺口、系统差异和后续计划写入 reports
+
+```bash
+conan create . -o apache-arrow/*:shared=True && conan create . -o apache-arrow/*:shared=False
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`将 test_package 冒充完整上游测试通过|将 CTest target 子集写成 Path C 全量通过|忽略未通过 target`
+- **原因**：大型 C++ 库的消费者风险主要来自未验证模块和运行时边界, 必须分开统计上游原样测试、迁移后可执行子集和消费者验证
+- **后果**：下游库依赖 apache-arrow 时可能暴露未覆盖模块问题, 路径 B 证据也会因过度声明而不稳
+
+## 涉及软件
+
+Apache Arrow 类多模块 C++ 数据处理库, 以及依赖 CTest/GTest、官方测试数据、运行时动态库加载环境、gRPC/OpenSSL 等重依赖的 C++ 上游测试体系
+
+## 相关模式
+
+- **相似模式**：[E092](E092.md)
+
+---
+*条目 E292 · 更新 2026-07-27 · 知识库同步生成物*