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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E314: R 默认使用 RPE_CPU 采样事件
+
+> **严重度**: 🟡 medium | **分类**: detection, ohos, syscall, runtime, itimer-prof | **自动修复**: ✅ source-patch
+
+---
+
+## 错误特征
+
+```
+no events were recorded
+Rprof_memory_summary
+Error in Rprof_memory_summary
+```
+
+## 根因
+
+R 默认使用 RPE_CPU 采样事件，通过 setitimer(ITIMER_PROF) 周期触发 SIGPROF 进行 CPU 性能采样。在 HarmonyOS 上，该定时器存在初始延迟异常：请求 0.02s 的 it_value 实际被内核置为约 1.4s，首个 SIGPROF 远晚于典型 profiling 工作负载的结束时刻，导致采样事件数为 0。属于平台运行时能力差异，不是测试本身或数值功能损坏。
+
+## 验证命令
+
+```bash
+R -e 'Rprof(tf=tempfile(), interval=0.02, memory.profiling=TRUE); replicate(20, {x<-rnorm(1e4); y<-lm(x~rnorm(1e4))}); Rprof(NULL); p<-summaryRprof(tf); cat("events:", length(p$by.self$sample.interval), "\n")'
+```
+
+## 解决方案
+
+**probe-detect-fallback**：在 R_InitProfiling 中、signal(SIGPROF, doprof) 之后增加能力探测：以请求 interval 设置 ITIMER_PROF 后立即 getitimer 回读；若回读 it_value 大于请求值 10 倍（p_got > p_set * 10），判定定时器异常，将 R_Profiling_Event 改为 RPE_ELAPSED 走既有 ProfileThread（pthread_kill(SIGPROF)）路径；探测完成后清零定时器，不残留状态。补丁 0008。
+
+```bash
+cd $R_HOME && patch -p1 < 〈外部知识库归档〉 && make -j4 && make install DESTDIR=$TEST_PREFIX
+```
+
+## 回退方案
+
+**skip-rprof-test-block**：仅当能力探测补丁无法应用时，将 Rprof memory profiling 测试块标记为 expected failure 或条件跳过，但必须记录跳过原因并保留其余 reg-tests-2.R 测试块完整执行。
+
+```bash
+conditional_skip="Rprof memory profiling block skipped: ITIMER_PROF initial delay anomaly on OHOS"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip entire reg-tests-2.R`
+- **原因**：reg-tests-2.R 包含数百个独立测试块，跳过整文件会丢失绝大多数上游回归覆盖。
+- **后果**：PR 审查会拒绝因单个 Rprof 块失败而跳过全文件的证据。
+
+### 🚫 禁止 2
+
+- **模式**：`prewrite Rprof output file`
+- **原因**：预写输出使测试虚假通过，不反映实际采样能力。
+- **后果**：掩盖平台能力差异，后续真实 profiling 场景仍会失败。
+
+### 🚫 禁止 3
+
+- **模式**：`accept empty events as pass`
+- **原因**：Rprof_memory_summary 抛出 "no events were recorded" 是显式失败信号，不能视为 OK。
+- **后果**：测试框架返回非零退出码，CI 判定 FAIL。
+
+## 涉及软件
+
+所有在 HarmonyOS 上运行 Rprof memory profiling 的场景；上游测试 tests/reg-tests-2.R 中的 Rprof 回归测试块。
+
+## 相关模式
+
+- **相似模式**：[E176](E176.md)
+
+---
+*条目 E314 · 更新 2026-08-09 · 知识库同步生成物*

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

@@ -0,0 +1,79 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E315: HarmonyOS 不通过传统 /etc/localtime 链暴露权威本地时区
+
+> **严重度**: 🟡 medium | **分类**: detection, ohos, runtime, nls | **自动修复**: ✅ source-patch
+
+---
+
+## 错误特征
+
+```
+(converted from
+UTC offset
+tzcode
+zoneinfo
+localtime).*Asia/Shanghai
+Olson
+IANA
+TZDIR
+persist\.time\.timezone
+param get
+```
+
+## 根因
+
+HarmonyOS 不通过传统 /etc/localtime 链暴露权威本地时区。设备只读调查确认 /usr/bin/param get persist.time.timezone 返回 Asia/Shanghai（权威 IANA 名称）；系统 /system/etc/zoneinfo/tzdata 为 OpenHarmony 打包格式，不是 R 可直接遍历的 Olson 目录。/etc/zoneinfo 目录虽存在但没有 Asia/Shanghai 展开文件，会遮蔽 R internal zoneinfo。R 官方源码自带 src/extra/tzone/zoneinfo.zip（含 zoneinfo/Asia/Shanghai），因此需启用 --with-internal-tzcode 以 R 自带版本固定的 IANA 数据库作为 TZDIR 能力来源。
+
+## 验证命令
+
+```bash
+R -e 'cat(Sys.timezone(), "\n"); cat(format(as.POSIXct("2026-01-01 00:00:00")), "\n")'
+```
+
+## 解决方案
+
+**authoritative-param-probe-with-tzdir-priority**：补丁 0003 在 datetime.R 的 Sys.timezone() 中，传统发现链前插入 HarmonyOS 专用探测块：(1) 仅当 param 命令存在时执行 param get persist.time.timezone；(2) 返回单一非空 IANA 名称后，按 R internal zoneinfo → 显式 TZDIR → 标准系统目录的候选优先级，仅选择真实包含该 IANA 文件的候选目录；(3) 将选中目录写入 TZDIR 环境变量，调用 cacheIt 缓存时区名称并返回。configure 阶段启用 --with-internal-tzcode 确保 R 自带 IANA 数据库可用。未硬编码 Asia/Shanghai 或 UTC。
+
+```bash
+./configure --prefix=/ --with-internal-tzcode && patch -p1 < patches/0003-authoritative-timezone-param.patch && make -j4 && make install DESTDIR=$TEST_PREFIX
+```
+
+## 回退方案
+
+**hardcode-utc-with-warning**：仅当 param 探测和 internal zoneinfo 均不可用时，临时设置 TZ=UTC 并在日志中记录 warning，表明时区能力降级。不应作为最终交付方案。
+
+```bash
+export TZ=UTC && R -e 'cat(Sys.timezone(), "\n")'
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`hardcode Asia/Shanghai`
+- **原因**：硬编码特定时区会丧失跨设备可移植性，不同 HarmonyOS 设备可能配置不同时区。
+- **后果**：在非 Asia/Shanghai 设备上返回错误时区，下游依赖时区的计算全部出错。
+
+### 🚫 禁止 2
+
+- **模式**：`hardcode TZ=UTC as final solution`
+- **原因**：UTC 降级虽能避免崩溃，但所有本地时间转换偏差，不符合设备实际时区配置。
+- **后果**：消费者测试中 as.POSIXct/as.POSIXlt 结果与设备系统时间不一致。
+
+### 🚫 禁止 3
+
+- **模式**：`let /etc/zoneinfo shadow internal zoneinfo`
+- **原因**：/etc/zoneinfo 目录存在但缺少 Asia/Shanghai 展开文件，若优先级高于 R internal zoneinfo 会遮蔽有效数据源。
+- **后果**：Sys.timezone() 返回空或 NA，时区相关函数降级为 UTC。
+
+## 涉及软件
+
+所有在 HarmonyOS 上运行 R 并调用 Sys.timezone()、as.POSIXct()、as.POSIXlt() 等时区相关函数的场景。影响 configure 阶段的 --with-internal-tzcode 选择，以及 datetime.R 中 Sys.timezone() 的时区发现逻辑。
+
+## 相关模式
+
+- **相似模式**：[E176](E176.md)
+
+---
+*条目 E315 · 更新 2026-08-09 · 知识库同步生成物*

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

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E316: R 的 exec/R ELF NEEDED 记录的是 OpenBLAS 的 SONAME libopenblas.so.…
+
+> **严重度**: 🔴 blocking | **分类**: ohos, linking, conan, dependency, packaging | **自动修复**: ✅ recipe-patch
+
+---
+
+## 错误特征
+
+```
+Error loading shared library libopenblas\.so\.0
+Error relocating.*zgemm_.*symbol not found
+needed by.*exec/R
+```
+
+## 根因
+
+R 的 exec/R ELF NEEDED 记录的是 OpenBLAS 的 SONAME libopenblas.so.0，但 Conan 包的 _prepare_relocatable_runtime 只复制了 libopenblas.so（开发者符号链接）。OpenBLAS Conan 包内 libopenblas.so 与 libopenblas.so.0 均是指向 libopenblas_armv8p-r0.3.33.so 的符号链接；动态链接器按 SONAME 查找，缺 .so.0 实体即失败。
+
+## 验证命令
+
+```bash
+llvm-readelf -d <package>/lib/R/bin/exec/R | grep NEEDED; ls -lh <package>/lib/R/lib/libopenblas.so*
+```
+
+## 解决方案
+
+**copy-soname-entity**：在 conanfile.py 的 _prepare_relocatable_runtime 中，复制库文件时必须同时提供 SONAME 实体。使用 shutil.copy2 跟随符号链接复制实体文件，确保 libopenblas.so 和 libopenblas.so.0 两份均为实体（或采用等价方式保证 SONAME 文件存在）。打包日志应出现 Packaged ... libopenblas.so.0。
+
+```bash
+shutil.copy2(os.path.join(openblas_folder, "lib", "libopenblas.so"), os.path.join(rlib, "libopenblas.so")) && shutil.copy2(os.path.join(openblas_folder, "lib", "libopenblas.so.0"), os.path.join(rlib, "libopenblas.so.0"))
+```
+
+## 回退方案
+
+**post-install-symlink-recreate**：若 Conan 打包流程无法修改，在 consumer test_package 的 run 前手动创建 libopenblas.so.0 → libopenblas_armv8p-r0.3.33.so 的符号链接。但这不是生产级方案，仅用于验证。
+
+```bash
+cd <package>/lib/R/lib && ln -sf libopenblas_armv8p-r0.3.33.so libopenblas.so.0
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`copy only libopenblas.so without .so.0 SONAME entity`
+- **原因**：动态链接器按 NEEDED 中的 SONAME（libopenblas.so.0）查找文件，只复制 libopenblas.so 会导致运行时加载失败。
+- **后果**：consumer 移动包后 exec/R 启动报 Error loading shared library libopenblas.so.0。
+
+### 🚫 禁止 2
+
+- **模式**：`rely on Conan symlink preservation across package move`
+- **原因**：Conan 打包在跨环境移动时可能丢失符号链接关系，导致 SONAME 文件指向不存在的目标。
+- **后果**：移动包后符号链接断裂，动态链接器仍无法加载 libopenblas.so.0。
+
+## 涉及软件
+
+所有在 HarmonyOS 上使用 Conan 打包 R 并依赖 OpenBLAS 的场景。影响 consumer test_package 将包移动到非原路径后的运行时启动。
+
+## 相关模式
+
+- **相似模式**：[E068](E068.md)、[E207](E207.md)
+
+---
+*条目 E316 · 更新 2026-08-09 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E317: R 的 src/scripts/Makefile.in install 规则用 sed 全局替换 s/\(VAR=\).…
+
+> **严重度**: 🔴 blocking | **分类**: ohos, autotools, make, install, shell | **自动修复**: ✅ source-patch
+
+---
+
+## 错误特征
+
+```
+normalizePath\(R\.home\(.share.\).*No such file or directory
+//lib/R/share
+R_SHARE_DIR.*固化
+R_INCLUDE_DIR.*固化
+R_DOC_DIR.*固化
+```
+
+## 根因
+
+R 的 src/scripts/Makefile.in install 规则用 sed 全局替换 s/\(VAR=\).*/ 处理 R_SHARE_DIR=/R_INCLUDE_DIR=/R_DOC_DIR=，把配方中本应运行时展开的 R_SHARE_DIR="${R_HOME_DIR}/share" shell 变量引用也一并固化为 configure 编译期值（--prefix=/ 时即 //lib/R/share）。移动后该路径不存在。需改为范围限定替换 1,/VAR=/s/\(VAR=\).*/，只替换第一个出现（即 configure 固化的默认行），保留 re-derive 块中的变量引用。
+
+## 验证命令
+
+```bash
+R -e 'cat(R.home("share"), "\n", normalizePath(R.home("share"), mustWork=TRUE), "\n")' # 修复前: //lib/R/share No such file or directory; 修复后: 实际路径
+```
+
+## 解决方案
+
+**sed-range-limited-replace**：补丁 0009 将 src/scripts/Makefile.in install 规则中 R_SHARE_DIR/R_INCLUDE_DIR/R_DOC_DIR 的 sed 替换从全局 s/\(VAR=\).*/ 改为范围限定 1,/VAR=/s/\(VAR=\).*/，与 R_HOME_DIR 的处理方式对齐。只替换第一个出现（即 configure 固化的默认行），保留后续 re-derive 块中的 R_SHARE_DIR="${R_HOME_DIR}/share" 变量引用，使资源目录在包移动后仍能从运行时验证的 R_HOME_DIR 重新推导。
+
+```bash
+cd $R_HOME && patch -p1 < 〈外部知识库归档〉 && make -j4 && make install DESTDIR=$TEST_PREFIX
+```
+
+## 回退方案
+
+**post-install-sed-rewrite**：若补丁无法在 install 阶段应用，可在 make install 后手动对生成的 R 脚本执行范围限定 sed 替换，修正固化值。但这不是生产级方案，仅用于验证。
+
+```bash
+sed -i '1,/R_SHARE_DIR=/s/\(R_SHARE_DIR=\).*/\1${R_HOME_DIR}\/share/' <package>/lib/R/bin/R
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`use global sed replace s/\(VAR=\).*/ without 1,/PATTERN=/ range`
+- **原因**：全局替换会把 re-derive 块中的 R_SHARE_DIR="${R_HOME_DIR}/share" 变量引用也固化为 configure 编译期值。
+- **后果**：包移动后 R.home("share") 返回固化值 //lib/R/share，normalizePath 报 No such file or directory。
+
+### 🚫 禁止 2
+
+- **模式**：`hardcode R_SHARE_DIR to absolute path`
+- **原因**：硬编码绝对路径会丧失包的可移动性，移动后路径仍不匹配。
+- **后果**：moved-r-base 场景下 R.home("share") 返回错误路径，share 目录资源无法访问。
+
+## 涉及软件
+
+所有使用 --prefix=/ + DESTDIR 安装模式并需移动安装目录的 autotools 项目。影响 R 的 R.home("share")、R.home("include")、R.home("doc") 在包移动后的路径解析。
+
+## 相关模式
+
+- **相似模式**：[E005](E005.md)、[E078](E078.md)、[E176](E176.md)、[E215](E215.md)
+
+---
+*条目 E317 · 更新 2026-08-09 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E318: HarmonyOS 上 go test 临时 ELF 未签名导致测试无法执行
+
+> **严重度**: 🔴 blocking | **分类**: ohos, go, testing, security | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)
+
+---
+
+## 错误特征
+
+```
+fork/exec.*\.test.*permission denied
+go test.*permission denied
+operation not permitted.*\.test
+exec format error.*\.test
+```
+
+## 根因
+
+go test 默认在临时目录编译包级测试 ELF 并立即执行；HarmonyOS 会拒绝加载未签名 ELF。即使测试 ELF 已在非 HMDFS 目录成功链接，未经签名仍会在进入测试代码前失败。
+
+## 验证命令
+
+```bash
+GOTOOLCHAIN=local go test -v ./...
+```
+
+## 解决方案
+
+**compile-sign-run-go-tests**：按 package 使用 go test -c 将测试 ELF 输出到非 HMDFS 目录，移除旧 .codesign 后自签并恢复执行权限，最后从该 package 的原源码目录执行，保留相对资源路径、包级初始化和原测试判定。
+
+```bash
+go test -c -o "$TEST_ROOT/pkg.test" ./pkg && (llvm-objcopy --remove-section .codesign "$TEST_ROOT/pkg.test" 2>/dev/null || true) && binary-sign-tool sign -inFile "$TEST_ROOT/pkg.test" -outFile "$TEST_ROOT/pkg.test.signed" -selfSign 1 && mv "$TEST_ROOT/pkg.test.signed" "$TEST_ROOT/pkg.test" && chmod +x "$TEST_ROOT/pkg.test" && (cd pkg && "$TEST_ROOT/pkg.test" -test.v -test.count=1)
+```
+
+## 回退方案
+
+**compile-off-device-sign-on-target**：若 HarmonyOS worker 没有可执行 Go 工具链，可在受支持的 Linux/arm64 构建机执行 go test -c，再把测试 ELF 传到目标机自签并从原 package 目录执行；源码、测试资源和提交必须一致。
+
+```bash
+CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go test -c -o pkg.test ./pkg
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`go test.*\|\|.*true|skip.*go test|删除.*_test\.go|修改.*断言.*通过`
+- **原因**：跳过、删除或放宽上游测试不能证明 HarmonyOS 适配保持原有行为。
+- **后果**：测试覆盖率虚高，签名或真实运行问题被隐藏。
+
+### 🚫 禁止 2
+
+- **模式**：`cd.*cache.*&&.*\.test|/data/storage/el2/base/cache/.*\.test.*without.*cd`
+- **原因**：在缓存输出目录直接运行会改变依赖相对资源的 package 工作目录。
+- **后果**：测试因错误 CWD 产生假失败，或绕过原包资源语义。
+
+## 涉及软件
+
+所有需要在 HarmonyOS 真机运行上游 Go 测试套件的项目，尤其是包含相对路径资源、多个 package 或子测试的项目。
+
+## 相关模式
+
+- **相似模式**：[E077](E077.md)
+- **根因条目（应先修它们）**：[E077](E077.md)、[E124](E124.md)、[E128](E128.md)、[E134](E134.md)、[E166](E166.md)
+
+---
+*条目 E318 · 更新 2026-08-08 · 知识库同步生成物*

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

@@ -0,0 +1,83 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E319: Python noarch 包在 OHOS 受限网络下 import 时自动下载资源导致阻塞/失败；纯 Python 包需 pip wheel --no-deps + site-packages 布局打包
+
+> **严重度**: 🟡 medium | **分类**: network, python, packaging | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+LookupError:.*corpus
+Initial downloading of word corpus
+nltk.download
+ModuleNotFoundError: No module named '.*'
+connection timed out
+Failed to establish a new connection
+unable to generate a unique filename
+ssl.SSLCertVerificationError
+```
+
+## 根因
+
+(1) 上游 Python 包（如 bacook17/acronym 2.0.0）在模块顶层调用 nltk.corpus.words/brown/gutenberg.ensure_loaded()，语料缺失时自动 nltk.download() 联网下载——OHOS 构建/worker 容器网络受限时 import 挂起或失败，阻塞所有仅 import 包的使用方；(2) 纯 Python noarch 包（py3-none-any.whl）无编译产物，Conan 打包必须用 pip wheel --no-deps 构建 wheel，再以 site-packages 布局（lib/pythonX.Y/site-packages）放入 package，并通过 runenv/buildenv PYTHONPATH 暴露，console_scripts 放 bin/。
+
+## 验证命令
+
+```bash
+timeout 30 python3 -c "import acronym" 2>&1 | head -3; python3 -m pip wheel --no-deps -w .dist . && ls .dist/*.whl; python3 -m installer .dist/*.whl --destdir $STAGING --prefix $PREFIX
+```
+
+## 解决方案
+
+**lazy-resource-loading-and-pip-wheel-noarch-package**：1) 移除模块顶层的 ensure_loaded()/download() 调用，改为显式惰性 helper（如 ensure_corpus(corpus)），仅在真正执行功能（find_acronyms/main）时调用，语料缺失抛清晰 RuntimeError 提示 nltk.download()；import 模块绝不触网；2) 纯 Python 包 Conan 配方：settings 仅 ("os","arch")，build() 用 python3 -m pip install --break-system-packages --no-deps --prefix=staging 安装，package() 定位 staging 下 lib/pythonX.Y/site-packages 复制到 package 同构目录，bin/ 复制 console_scripts；3) package_info() 中 runenv_info/buildenv_info append PYTHONPATH 指向 package 的 site-packages，bindirs=["bin"]；4) test_package 用 unittest 补全路径 B 测试，find_acronyms 用 FakeCorpus（实现 words()/ensure_loaded()）避免真实语料下载。
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing --user=ohpcd --channel=stable
+```
+
+## 回退方案
+
+**preinstall-nltk-data**：若功能必须真实语料，可在 test_package/构建环境预置 NLTK_DATA 目录并 nltk.download() 完整语料（words/brown/gutenberg），再运行功能测试。体积大（words+brown 约数十 MB），受限网络下需离线源。
+
+```bash
+python3 -m nltk.downloader -d $NLTK_DATA words brown gutenberg
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`保留模块顶层 nltk.download()|import 时 ensure_loaded() 不捕获`
+- **原因**：OHOS 受限网络下 import 挂起/失败，所有使用方被阻塞；知识库 E215 已记录 os.tmpname() 受限环境问题，同属网络/环境依赖
+- **后果**：conan create 的 test_package import 阶段超时或失败
+
+### 🚫 禁止 2
+
+- **模式**：`把补写测试写成"上游测试通过率"|勾选"上游无测试"却把新增用例计入上游通过率`
+- **原因**：上游 sdist 无任何测试文件，补全是路径 B 测试框架/工具链材料；计入上游通过率属误报
+- **后果**：AI Review/CI 审核拒绝
+
+### 🚫 禁止 3
+
+- **模式**：`纯 Python 包 recipe 声明 settings=("os","compiler","build_type","arch") 并要求编译`
+- **原因**：noarch 包无编译，声明 compiler 会强制工具链检测，交叉环境可能失败
+- **后果**：不必要的工具链依赖与失败
+
+### 🚫 禁止 4
+
+- **模式**：`package() 直接 copy site-packages 到 include/ 或忽略 PYTHONPATH`
+- **原因**：Python 运行时按 site-packages 布局与 PYTHONPATH 搜索模块，放错位置 import 失败
+- **后果**：test_package import acronym 报 ModuleNotFoundError
+
+## 涉及软件
+
+所有在模块顶层下载语料/模型/字典等资源的 Python 包（NLTK 系、torchvision 模型缓存系等）在 OHOS/受限网络上的 import；所有纯 Python noarch 包的 Conan 适配
+
+## 相关模式
+
+- **根因条目（应先修它们）**：[E215](E215.md)
+
+---
+*条目 E319 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,71 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E320: HarmonyOS fmemopen 符号存在但运行时不可用，AC_CHECK_FUNCS 误判，需 AC_RUN_IFELSE 探测并回退临时文件
+
+> **严重度**: 🟡 medium | **分类**: platform, detection, ohos, libc, autotools | **自动修复**: ❌ | **原则**: [P001](../principles.md#P001)、[P007](../principles.md#P007)
+
+---
+
+## 错误特征
+
+```
+fmemopen.*EBADF
+fclose.*EBADF.*fmemopen
+bad file descriptor.*fmemopen
+fmemopen.*write.*fail
+cob_get_field_str.*truncat
+ac_cv_fmemopen_works=no
+HAVE_FMEMOPEN.*runtime.*unusable
+field not allocated
+```
+
+## 根因
+
+HarmonyOS libc 导出 fmemopen 符号且链接成功，但运行时对缓冲区写入无效、fclose 返回 EBADF，即符号存在不等于语义可用。AC_CHECK_FUNCS 仅做链接级检测，误判 HAVE_FMEMOPEN=1，导致源码走 fmemopen 路径产生坏输出或运行时失败。交叉编译/真机构建中 configure 无法直接运行宿主程序时此类误判尤其隐蔽。
+
+## 验证命令
+
+```bash
+grep -n "ac_cv_fmemopen_works" configure && grep -n "AC_RUN_IFELSE" configure.ac && grep -n "HAVE_FMEMOPEN" libcob/call.c && make MAKEINFO=true check -j1 | grep -E "tests behaved as expected|tests were skipped"
+```
+
+## 解决方案
+
+**configure-runtime-probe**：用 AC_RUN_IFELSE 在 configure 阶段真实写读 fmemopen 缓冲验证可用性，仅在运行时探测通过时才 AC_DEFINE(HAVE_FMEMOPEN)；失败则源码回退临时文件实现，不依赖平台宏。
+
+```bash
+cd $BUILD_SRC_DIR && patch -p1 < 〈外部知识库归档〉 && patch -p1 < 〈外部知识库归档〉 && patch -p1 < 〈外部知识库归档〉 && ./configure --prefix=$DEFAULT_PREFIX && make -j1 && make install DESTDIR=$TEST_PREFIX
+```
+
+## 回退方案
+
+**temp-file-fallback**：当 fmemopen 运行时探测失败时，源码回退到不可预测命名的临时文件（如 libcob 的 cob_create_tmpfile），并将读取量限制为缓冲区 size-1、检查 fseek、按实际 fread 字节数写 NUL，避免短缓冲区越界。
+
+```bash
+patch -p1 < 〈外部知识库归档〉
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`AC_CHECK_FUNCS\(\[.*fmemopen|HAVE_FMEMOPEN.*AC_CHECK_FUNCS`
+- **原因**：仅链接级 AC_CHECK_FUNCS 无法发现运行时不可用的 fmemopen，会把坏路径编进制品。
+- **后果**：产物运行时输出损坏或 EBADF，上游测试失败被误判为平台兼容问题。
+
+### 🚫 禁止 2
+
+- **模式**：`#ifdef __OHOS__|defined\(__OHOS__\)`
+- **原因**：R8 禁止在源码/补丁中引入平台条件编译宏；平台差异应通过 configure 运行时探测表达。
+- **后果**：PR 审查被拒（R8 违规），且无法覆盖其他同样存在坏 fmemopen 的目标平台。
+
+## 涉及软件
+
+所有使用 autotools AC_CHECK_FUNCS 检测 fmemopen 并在运行时依赖其内存流语义的 C/C++ 软件；交叉编译到 HarmonyOS/OHOS 平台的 autotools 项目。
+
+## 相关模式
+
+- **相似模式**：[E302](E302.md)、[E230](E230.md)
+
+---
+*条目 E320 · 更新 2026-08-11 · 知识库同步生成物*

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

@@ -0,0 +1,80 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E321: martinmoene lite 系 header-only 库：Conan 1.x 配方迁移 2.x 与 INTERFACE 消费/上游测试入口恢复
+
+> **严重度**: 🟡 medium | **分类**: ohos, headers, cmake, conan, packaging | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+from conans import ConanFile, CMake
+conans import.*error
+No module named conans
+header-only
+INTERFACE library
+CMakePackageConfigHelpers
+find_package.*byte-lite
+package_type.*header-library
+cmake_layout
+strip_root
+```
+
+## 根因
+
+martinmoene/nonstd-lite 系（byte-lite/any-lite/optional-lite/span-lite/expected-lite
+等）是单文件 header-only C++ 库：include/nonstd/*.hpp + CMake INTERFACE library
+（如 nonstd::byte-lite），上游自带 Conan 1.x 配方（from conans import ConanFile, CMake，
+依赖 CMake(self)/cmake.configure() 的 Conan 1 风格），在 Conan 2.x（本项目基线 2.29.1）
+下无法直接复用：Conan 1 API 已移除（No module named conans）、CMake helper 调用方式
+不同、需要显式 package_type=header-library、cmake_layout、CMakeToolchain 与
+cpp_info.set_property("cmake_file_name"/"cmake_target_name") 才能让下游 find_package
+解析到 INTERFACE target。版本号仅由 git tag 表达（byte.hpp 无版本宏），CMake 选项
+{NAME}_OPT_BUILD_TESTS/_OPT_BUILD_EXAMPLES 决定是否带上游测试入口。
+
+## 验证命令
+
+```bash
+python3 scripts/ohc-run.py conan-verify byte-lite 0.3.0 --profile ohos-aarch64
+--project-dir <worktree>  （G0-G4/L2/L4/L5 全过）；或本地
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉
+-pr:b=〈外部知识库流水线〉（test_package PASS: byte-lite header-only
+库链接和核心 API 验证通过）；上游测试：cmake -S . -B build
+-DBYTE_LITE_OPT_BUILD_TESTS=ON -DBYTE_LITE_OPT_BUILD_EXAMPLES=OFF && ctest
+--test-dir build（4/4：test-cpp98/11/14/17）。
+```
+
+## 解决方案
+
+**header-only-lite-conan2-migration**：(1) conanfile.py 用 Conan 2 风格重写：from conan import ConanFile，
+package_type="header-library"，settings=os/compiler/build_type/arch，
+layout()=cmake_layout(self)，export_sources()=export_conandata_patches(self)，
+source()=get(self, **self.conan_data["sources"], strip_root=True)
++ apply_conandata_patches(self)，generate()=CMakeToolchain + OHOS 映射
+（settings.os in ("Linux","OHOS") 时设 CMAKE_SYSTEM_NAME=Linux、
+CMAKE_SYSTEM_PROCESSOR=aarch64）+ 打开 {NAME}_OPT_BUILD_TESTS=ON 保持上游测试入口，
+build()=CMake.configure/build/test，package()=CMake.install，
+package_info() 用 cpp_info.set_property("cmake_file_name", "byte-lite") 与
+cpp_info.set_property("cmake_target_name", "nonstd::byte-lite")，libs=[]。
+(2) test_package/conanfile.py 用 CMakeDeps 生成器、find_package(byte-lite) 链接
+nonstd::byte-lite，test() 实际调用被测库 API（to_integer/位运算/比较）。
+(3) 版本号仅来自 git tag：conandata.yml sources.url 指向官方 release tarball、
+sha256 实测填写；conan-verify G1 要求 test_package/MANIFEST.yml（CI L0e）。
+(4) 上游测试入口恢复：CMake 选项 BYTE_LITE_OPT_BUILD_TESTS=ON 时 CTest 4 个可执行
+（test-cpp98/11/14/17），本地 ctest 全过即证明头文件在 C++98~17 下均可编译。
+
+```bash
+conanfile.py 骨架见 〈外部知识库归档〉（Conan 2.x 重写版）；
+test_package 见 〈外部知识库归档〉；重建验证：
+python3 scripts/ohc-run.py conan-verify byte-lite 0.3.0 --profile ohos-aarch64。
+```
+
+## 涉及软件
+
+所有 martinmoene/nonstd-lite 系单文件 header-only 库的首次 OHOS/arm64 Conan 2.x 配方
+编写；上游仍带 Conan 1.x conanfile.py 的 header-only 库迁移；依赖 CMake INTERFACE
+target 消费的 test_package 编写；需要恢复上游 CTest 测试入口（cpp98/11/14/17）的场景。
+
+---
+*条目 E321 · 更新 2026-08-31 · 知识库同步生成物*

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

@@ -0,0 +1,74 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E322: header-only CMake INTERFACE 库的 Conan 配方模式（关闭上游默认 tests/examples + 消费上游 CONFIG target）
+
+> **严重度**: 🟡 medium | **分类**: headers, cmake, conan, packaging | **自动修复**: ❌ | **原则**: [P012](../principles.md#P012)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+TF_BUILD_TESTS
+TF_BUILD_EXAMPLES
+conan create.*builds tests
+find_package\(Taskflow
+package_type.*header-library
+```
+
+## 根因
+
+header-only 库（add_library(X INTERFACE)）在上游 CMake 自带完整 install/export（XConfig.cmake + X::X target）时，若 conanfile.py 直接 conan create，上游默认 ON 的 TF_BUILD_TESTS/TF_BUILD_EXAMPLES 会把 26+ unittests/examples 连带构建，引入 3rd-party 测试依赖并大幅拖慢配包装插；同时配方若不声明 package_type=header-library + self.info.clear()，会错误生成与编译器相关的 package_id 并产出空 .so 链接目标。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing
+```
+
+## 解决方案
+
+**header-only-cmake-interface-recipe**：配方声明 package_type="header-library"，package_id() 里 self.info.clear()（header-only 与编译器/arch 无关）；generate() 用 CMakeToolchain 显式关闭上游默认构建选项（TF_BUILD_TESTS=OFF / TF_BUILD_EXAMPLES=OFF / TF_BUILD_BENCHMARKS=OFF / TF_BUILD_PROFILER=OFF / TF_BUILD_CUDA=OFF / TF_BUILD_SYCL=OFF）；build()/package() 走上游 CMake install（自动装 include + XConfig.cmake）；package_info() 设置 cmake_file_name/cmake_target_name 以便 find_package(CONFIG)；test_package 用 find_package(Taskflow CONFIG REQUIRED) + 链接 Taskflow::Taskflow + 真实调用 API（非空壳）。
+
+```bash
+python3 scripts/ohc-run.py conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing
+```
+
+## 回退方案
+
+**header-only-copy-headers**：若上游无完整 install/export，则 package() 直接 copy taskflow/ 头目录到 include/，package_info 只设 includedirs，不提供 CMake CONFIG（消费者用 include path）。
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉 --build=missing
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`package_type.*library.*with.*shared.*True|default_options.*shared.*True`
+- **原因**：header-only INTERFACE 库无二进制，声明 shared/静态会产生空链接目标与歧义 package_id。
+- **后果**：conan 生成空 lib 目标，消费者链接失败或产生非确定 package_id。
+
+### 🚫 禁止 2
+
+- **模式**：`print.*success|skip.*test_package|no.*API.*call`
+- **原因**：test_package 必须真实消费被测头 API（R34），禁止空壳。
+- **后果**：CI L1e 破坏性反向验证失败。
+
+### 🚫 禁止 3
+
+- **模式**：`TF_BUILD_TESTS.*ON|TF_BUILD_EXAMPLES.*ON`
+- **原因**：上游默认开启测试/示例，配包装插必须显式关闭，否则连带构建大量 unittests 并拉入 3rd-party 测试依赖。
+- **后果**：conan create 极慢或失败，配包装插不稳定。
+
+## 涉及软件
+
+header-only C++17/20 CMake INTERFACE target 库（上游自带完整 install/export，如 cpp-taskflow、其他 header-only 任务图/模板库），在 OHOS aarch64 + Conan 2 配包装插场景。
+
+## 相关模式
+
+- **相似模式**：[E307](E307.md)、[E035](E035.md)、[E191](E191.md)、[E216](E216.md)
+
+---
+*条目 E322 · 更新 2026-08-30 · 知识库同步生成物*