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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E250: OHOS 原生环境不含 Go 工具链，go build 失败
+
+> **严重度**: 🔴 blocking | **分类**: toolchain, go | **自动修复**: ✅ inline-build-method
+
+---
+
+## 错误特征
+
+```
+go.*inaccessible or not found
+go: command not found
+make.*go.*not found
+go: No such file or directory
+go not found
+```
+
+## 根因
+
+OpenHarmony PC 原生环境未预装 Go 工具链（/bin/sh: go: inaccessible or not found），导致所有 Go 语言项目的编译步骤失败。PATH 中不包含 go 二进制。
+
+## 验证命令
+
+```bash
+which go 2>/dev/null || echo "Go toolchain NOT available"
+```
+
+## 解决方案
+
+**download-go-sdk**：在 conanfile.py build() 中自动下载 Go SDK 二进制发布版，解压后设置 GOROOT 和 PATH，然后执行 go build。使用 conan.tools.files.get() 下载并验证 SHA256。
+
+```bash
+get(self, url=f"https://go.dev/dl/go{go_version}.linux-arm64.tar.gz", sha256=go_sha256, destination=go_dest, strip_root=False)  # 设置 os.environ["GOROOT"] 和 os.environ["PATH"]
+```
+
+## 回退方案
+
+**use-prebuilt-package**：从 cmd-pkgs 仓库安装预编译的 Go 工具链（如已有 signed 版本）
+
+```bash
+curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- go <version>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`shutil.which\("go"\) or "go"`
+- **原因**：仅仅 shutil.which("go") or "go" 不能解决 Go 缺失的问题，Worker 上无 Go 时命令仍会失败
+- **后果**：编译失败（Error 127）
+
+## 涉及软件
+
+所有 Go 语言项目（如 flow-cli, croc, gh-dash 等依赖 go build 的软件）
+
+## 相关模式
+
+- **相似模式**：[E109](E109.md)、[E128](E128.md)、[E184](E184.md)、[E105](E105.md)
+
+---
+*条目 E250 · 更新 2026-07-17 · 知识库同步生成物*

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

@@ -0,0 +1,68 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E251: OHOS 上 NLP 词典/分词数据包的固定版本 hash、UTF-8 编码校验、词典文件统计、mecab-dict-index 索引生成、固定韩语样本文本分词输出精确比对方法
+
+> **严重度**: 🟡 medium | **分类**: packaging | **自动修复**: ❌ | **原则**: [P001](../principles.md#P001)
+
+---
+
+## 错误特征
+
+```
+NLP dictionary
+mecab-dict-index
+CSV dictionary
+Korean tokenization
+UTF-8 encoding check
+fixed sample output comparison
+```
+
+## 根因
+
+OHOS 适配韩语 NLP 词典数据包时遇到需要固定源码 hash 校验、UTF-8 编码校验、大规模 CSV 文件统计验证、外部 mecab-ko 工具依赖、以及固定样本文本精确分词比对的组合型问题。传统数据包模式（E241）覆盖 JSON/规则清单型但不完全适用 CSV/DEF 词典格式。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -tf=test_package
+```
+
+## 解决方案
+
+**nlp-dictionary-package-pattern**：NLP 词典数据包核心模式：
+1. settings = None（不依赖编译器/架构）
+2. source() 使用 get() 下载 tarball
+3. build() 中验证数据完整性（CSV/DEF 文件数、条目数、UTF-8 编码）
+4. package() 中复制所有 CSV/DEF/dicrc 及生成的二进制索引文件
+5. test_package 中依次执行：文件存在性 → UTF-8 校验 → 条目统计 → 可选 mecab 分词测试
+6. 外部工具 mecab-ko 需单独安装（非本包源文件）
+
+```bash
+# conanfile.py: settings = None; build() 验证 CSV/DEF/UTF-8; package() 复制数据
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`把 mecab-ko 主库源码混入当前词典包的 PR`
+- **原因**：mecab-ko 主库是独立包，混入会破坏 PR 原子性
+- **后果**：PR 审核不通过
+
+### 🚫 禁止 2
+
+- **模式**：`在没有 mecab-ko 时声称已运行分词测试`
+- **原因**：无 mecab-ko 可执行文件时无法进行分词测试
+- **后果**：虚假测试结果，审核不通过
+
+## 涉及软件
+
+韩语 MeCab 词典数据包（mecab-ko-dic）、日语 MeCab 词典数据包（mecab-ipadic）、任何以 CSV/DEF 为词典格式且用 mecab-dict-index 生成索引的 NLP 数据包。
+
+## 相关模式
+
+- **相似模式**：[E241](E241.md)
+- **根因条目（应先修它们）**：[E241](E241.md)
+
+---
+*条目 E251 · 更新 2026-07-28 · 知识库同步生成物*

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

@@ -0,0 +1,58 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E252: Asset-gated libraries need substantive pre-asset consumer tests
+
+> **严重度**: 🟡 medium | **分类**: packaging, testing, api | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)
+
+---
+
+## 错误特征
+
+```
+version-only smoke passes while context API is unusable
+test requires redistributing unavailable runtime assets
+missing-asset path is unverified
+```
+
+## 根因
+
+Libraries that require user-supplied ROMs, firmware, models, or licensed data for their full workload still expose meaningful installed-package contracts before those assets are loaded. Testing only a version function proves linkage but misses allocation, inventory, configuration, cleanup, and explicit missing-asset behavior. Bundling invented or redistributable-looking substitutes would test a different contract and can violate provenance or licensing boundaries.
+
+## 验证命令
+
+```bash
+conan create <recipe> -pr:h=<target-profile> -pr:b=<target-profile> --build=<package>
+```
+
+## 解决方案
+
+**substantive-pre-asset-lifecycle-flow**：Keep the lawful asset boundary explicit. In one installed-package consumer, call real public inventory and capability queries, create and release the primary context, exercise reversible configuration, and require the documented missing-asset result without changing the context to an open or active state. Run the process under the generated package environment. Count the process as one logical flow; its internal semantic checks are assertions, not extra tests.
+
+```bash
+<consumer> && verify exactly one successful process exit
+```
+
+## 回退方案
+
+**compile-link-plus-explicit-gap**：If even context creation needs restricted assets, compile and link a real public consumer, record target execution as unresolved, and do not claim functional runtime coverage until lawful assets are supplied.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(version|get_version).*(only|smoke)|return\s+0.*(ROM|firmware|model|asset)`
+- **原因**：A version-only or constant-success process does not exercise the installed library's stateful public contract.
+- **后果**：Packaging and ABI failures remain hidden until a downstream application supplies real assets.
+
+### 🚫 禁止 2
+
+- **模式**：`(assertion_count|check_count).*test_(count|flow)|shared.*\+.*static.*logical`
+- **原因**：Internal checks and shared/static reruns do not create independent inputs or failure boundaries.
+- **后果**：Reported coverage is inflated without additional executable workflows.
+
+## 涉及软件
+
+C/C++ libraries whose complete runtime workflow depends on external user-provided assets that cannot lawfully or faithfully be included in a package test.
+
+---
+*条目 E252 · 更新 2026-07-21 · 知识库同步生成物*

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

@@ -0,0 +1,79 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E253: OCaml 工具链迁移到 HarmonyOS PC 的编译配置、testsuite 驱动与平台限制处理方法
+
+> **严重度**: 🟡 medium | **分类**: ohos, toolchain | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+OHOS_ocaml_build
+ocaml_testsuite_migration
+ocamltest_hmmac
+config_guess_ohos
+configure_tmpdir
+create_process_EPERM
+```
+
+## 根因
+
+OCaml 4.14.1.1 在 OHOS PC (aarch64) 上迁移需处理 4 类问题:
+1) config.guess 无法识别 OHOS 平台 (识别为 unknown-unknown-linux-gnu),
+   configure 阶段主机三元组判定错误;
+2) configure 生成的 config.status 使用 mktemp -d 创建临时目录,
+   OHOS /tmp 为 erofs 只读文件系统导致 Permission denied;
+3) upstream testsuite 入口为 make all (无 make check), 依赖 ocamltest 驱动;
+   字节码版 ocamltest/ocamldebug 被 hmmac 拦截 (Operation not permitted),
+   ocamldebug 默认 UNIX socket bind 也被 hmmac 拒绝;
+4) Unix.create_process 调用 fork+exec 被 OHOS 安全策略禁止 (EPERM),
+   posix_spawn 可替代但相对路径解析行为与 glibc 不同 (ENOENT).
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**ohos-toolchain-migration**：按上述 6 点完成 OHOS 适配后, conan create RC=0, test_package 冒烟通过
+(3 个工具版本断言)。上游 testsuite 真机实测 2951/3144 (93.9%) 通过,
+剩余失败为平台硬限制 (hmmac 拦截字节码可执行文件、UNIX socket bind、
+子进程创建、动态链接器符号解析差异), 已在 MANIFEST.yml fail_analysis
+中逐类归因并按 TEST_QUALITY_SPEC 3.3 声明豁免。通过率必须如实填报,
+禁止虚报 100% (E011 规则)。
+
+```bash
+# 1. 本地 CI 模拟预审
+CI_PACKAGES="〈外部知识库归档〉" CI_BRANCH="feat/ocaml-4.14.1.1" zsh 〈外部知识库流水线〉
+# 2. 上游 testsuite 真机实测 (入口为 make all)
+cd $B/testsuite && make all
+# 3. 通过率如实填报 2951/3144 (93.9%)
+```
+
+## 回退方案
+
+**no-recipe-level-fallback**：无配方层回退方案; 平台硬限制仅能豁免声明, 或上游源码修改 (超出 PR 范围)
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`2951/3144|93\.9%|100%通过.*(上游|upstream)|上游.*无测试`
+- **原因**：通过率必须如实填报为 2951/3144 (93.9%), 33 个失败用例按 TEST_QUALITY_SPEC 3.3 声明豁免, 禁止虚报 100% 或"无测试"
+- **后果**：违反 E011 虚报通过率禁令, PR 被拒绝并影响参赛资格
+
+### 🚫 禁止 2
+
+- **模式**：`ocamltest_config.*flambda.*true|flambda=true`
+- **原因**：当前编译器未启用 flambda, 强制 ocamltest 报告 flambda=true 会使依赖 flambda 的用例大量回归 (实测通过率降至 81%), 不可用作修复手段
+- **后果**：测试结果失真, 审核不通过
+
+## 涉及软件
+
+OCaml 全系列工具链 (ocamlc/ocamlopt/ocamlrun/ocamldebug/ocamlobjinfo 等 39 个 bin), 及依赖 OCaml 生态的 dune/zarith 等下游
+
+---
+*条目 E253 · 更新 2026-08-06 · 知识库同步生成物*

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

@@ -0,0 +1,77 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E254: toybox patch --dry-run 真实应用 new-file 补丁，破坏补丁管线
+
+> **严重度**: 🔴 blocking | **分类**: compat, toolchain, patch | **自动修复**: ❌ | **原则**: [P012](../principles.md#P012)
+
+---
+
+## 错误特征
+
+```
+patch.*dry-run
+creating .*\.patch
+source/target file does not exist
+Failed to apply patch:.*\.patch
+```
+
+## 根因
+
+鸿蒙默认 /usr/bin/patch 是 toybox 0.8.12。其 `patch --dry-run`
+对 new-file 补丁（--- /dev/null → +++ b/...）会真实创建文件
+（输出 "creating new.txt"），忽略 --dry-run 语义。
+refresh-patch 的 dry-run 校验因此污染 orig 目录：
+下一轮扫描把该文件误判为 MOD（diff_files），生成的补丁带
+a/ b/ 前缀，patch_ng（conan apply_conandata_patches 内部）
+无法解析/应用，conan create 在 source() 阶段失败。
+
+## 验证命令
+
+```bash
+printf '--- /dev/null\n+++ b/t.txt\n@@ -0,0 +1,1 @@\n+x\n' | patch --dry-run -p1; ls t.txt 2>/dev/null && echo "被真实创建"
+```
+
+## 解决方案
+
+**avoid-new-file-patches**：补丁只保留修改文件（modified-file diff），新增源码文件通过
+conanfile.py export_sources 传递，彻底避免 toybox new-file
+dry-run 污染路径。toybox 对修改文件 diff 的 dry-run 不真实应用。
+
+```bash
+# conanfile.py: 新增源码不写补丁，走 export_sources
+def export_sources(self):
+    export_conandata_patches(self)
+    copy(self, "*", src=os.path.join(self.recipe_folder, "compat"),
+         dst=os.path.join(self.export_sources_folder, "compat"))
+# conandata.yml: 只列修改文件补丁
+#   - patch_file: "patches/0001-Makefile.am.patch"
+```
+
+## 回退方案
+
+**install-gnu-patch**：安装 GNU patch 替代 toybox，使 --dry-run 语义正确
+
+```bash
+curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- patch
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`(patch_file:.*compat/|patch_file:.*tests/)`
+- **原因**：新增文件补丁（new-file）会触发 toybox dry-run 真实应用，污染 orig
+- **后果**：下一轮 refresh-patch 误判 MOD，生成 patch_ng 无法应用的 a/ 格式补丁，W3 conan create 阻塞
+
+## 涉及软件
+
+所有通过 refresh-patch 生成 new-file 补丁、且系统 patch 为
+toybox 的 HarmonyOS 软件（含 conan 配方管线）
+
+## 相关模式
+
+- **相似模式**：[E010](E010.md)、[E106](E106.md)
+- **根因条目（应先修它们）**：[E010](E010.md)
+
+---
+*条目 E254 · 更新 2026-08-05 · 知识库同步生成物*

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

@@ -0,0 +1,94 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E255: OHOS Conan 流水线主要为编译型 C/C++ 库设计
+
+> **严重度**: 🟡 medium | **分类**: packaging, testing | **自动修复**: ❌ | **原则**: [P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+symbolic link loop
+BadZipFile
+Symlink loop
+no_test_sources
+stub_test_method
+no_manifest
+commands.json missing
+no_bin_content
+no_lib_content
+L0 quality gate failed
+```
+
+## 根因
+
+OHOS Conan 流水线主要为编译型 C/C++ 库设计，其 L0/L1/L2/L4/L5
+质量门禁（commands.json, test_sources by find, self.run() 检查等）
+对纯资源型数据包不适用。资源型数据包的特殊性：
+1. 无编译步骤：build() 应直接 pass，没有 make/cc 调用
+2. 源码包可能包含大量符号链接（包括上游符号链接循环），
+   tarfile 默认提取会因 OSError [Errno 40] 失败
+3. 验证焦点是资源内容的正确性（文件存在性、格式合法性、
+   目录结构完整性），而非编译/链接/运行测试
+4. 安装通过 cp -R 复制目录树到 share/ 下，不生成 bin/lib/include/
+5. 部分平台 FS（如 HMDFS）上 find 命令使用绝对路径时不枚举目录内容，
+   导致 CI 脚本的 L0c 检测永远找不到测试源文件
+6. 无 ELF 产物，L4 安全扫描、L2 --version/--help 测试均不适用
+
+## 验证命令
+
+```bash
+conan create . -tf test_package 2>&1 | tail -10
+```
+
+## 解决方案
+
+**resource-data-package-conan-recipe**：纯资源/数据型 Conan 配方应遵循以下通用模式：
+1. package_type = "unknown" — 标记非库/非应用，避免触发 commands.json 门禁
+2. no_copy_source = True — 源码和包目录分离
+3. settings = "os", "arch" — 仅需要 os/arch，不需要 compiler/build_type
+4. build() — 直接 pass（无编译步骤）
+5. package() — 用 copy() 将资源目录树复制到 share/ 对应子目录
+6. package_info() — cpp_info 的 bindirs/libdirs/includedirs/libs 全部置空
+7. export_sources() + apply_conandata_patches() — 仍需声明以通过 G1 检查
+source() 处理符号链接循环：使用 tarfile 手动提取 filter="data"。
+test_package 验证焦点：资源描述文件存在性、格式合法性、断链检测。
+
+```bash
+# 创建/验证
+conan create . -tf test_package
+```
+
+## 回退方案
+
+**skip-l0-for-resource-packages**：对于纯资源/数据型包（无编译、无 ELF、无可执行文件），W3 本地 CI 的
+L0 门禁中以下检查不适用：L0c (find test sources), L0k (commands.json),
+L2 (--version/--help), L4 (checksec)。核心验证以 conan create + test_package 通过为准。
+
+```bash
+# 只执行核心验证
+conan create . -tf test_package
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`为资源包创建 commands.json 或虚假二进制测试源文件`
+- **原因**：资源包无 CLI 工具和编译步骤，创建空壳 commands.json 或伪造 .c 文件
+会把路径 A 冒充高难度，违反 PR 原子性规则
+- **后果**：L0 门禁虽通过但证据不真实，PR 审核不通过且影响路径判断
+
+## 涉及软件
+
+OHOS 上所有纯资源/数据型包（无编译步骤）的 Conan 适配：
+图标主题、字体包、文档/帮助包、配置模板等
+
+## 相关模式
+
+- **相似模式**：[E241](E241.md)
+- **根因条目（应先修它们）**：[E241](E241.md)
+
+---
+*条目 E255 · 更新 2026-07-28 · 知识库同步生成物*

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

@@ -0,0 +1,61 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E256: 二进制文件提交导致 CI PR diff patch 应用失败
+
+> **严重度**: 🔴 blocking | **分类**: patch | **自动修复**: ✅ remove-binary-files | **原则**: [P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+missing binary patch data.*\.tar\.gz
+error: binary patch does not apply to.*packaging
+patch does not apply.*packaging.*\.tar\.gz
+PR.*diff.*无法应用.*冲突
+```
+
+## 根因
+
+PR 分支中提交了二进制构建产物（如 packaging/*.tar.gz）或构建过程标记文件（如 .staging-verified），CI checkout 流程通过 `git apply pr.diff` 应用 PR diff 时，git 无法处理缺少 binary patch data 的二进制文件，导致 patch 应用失败
+
+## 验证命令
+
+```bash
+git ls-tree -r HEAD -- 〈外部知识库归档〉 | grep -E '(packaging/|\.staging-verified|\.tar\.gz|\.so|\.o$)'
+```
+
+## 解决方案
+
+**remove-binary-from-commit**：从分支中删除二进制构建产物和空标记文件，amend 提交并 force push
+
+```bash
+git rm 〈外部知识库归档〉 〈外部知识库归档〉 && git commit --amend --no-edit && git push origin feat/xxx --force-with-lease
+```
+
+## 回退方案
+
+**add-to-gitignore**：在 .gitignore 中添加 packaging/ 和 .staging-verified 规则，防止后续误提交
+
+```bash
+echo -e "packaging/\n.staging-verified" >> 〈外部知识库归档〉
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`packaging/.*\.tar\.gz|\.staging-verified`
+- **原因**：二进制构建产物和空标记文件不应提交到仓库，CI 只读 conanfile.py/conandata.yml/test_package/patches/
+- **后果**：CI checkout 流程无法通过 git apply 应用包含二进制文件的 PR diff，导致 PR 构建失败
+
+## 涉及软件
+
+所有包含二进制文件（packaging/*.tar.gz、*.so、*.a、*.o 等）或空标记文件（.staging-verified）的 PR
+
+## 相关模式
+
+- **相似模式**：[E227](E227.md)
+
+---
+*条目 E256 · 更新 2026-08-11 · 知识库同步生成物*

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

@@ -0,0 +1,57 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E257: header-only 无 CMake 库配方的 conan-verify G1 要求显式 build()（no-op 即可）
+
+> **严重度**: 🟡 medium | **分类**: headers, conan, completeness, recipe | **自动修复**: ✅ conan-verify-g1-noop-build | **原则**: [P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+G1: FAIL
+conanfile.py 缺少: build() 方法
+G1 失败，请先生成完整配方
+```
+
+## 根因
+
+conan-verify 的 G1 配方完整性门禁把 build() 方法列为 conanfile.py 必填项，
+是结构检查而非编译检查。header-only 无 CMake/meson/autotools 构建系统的
+C++ 库按直觉省略 build()，导致 G1 FAIL 并阻止后续 G0-G5/L2/L4/L5 继续。
+只需提供 no-op build() 即满足结构完整性，与 E241/E255/E281 的数据/资源型包
+（settings=None、无 C++ 编译）不同：header-only C++ 库保留 settings 与
+package_type='header-library'，仅在配方中补显式 build()。
+
+## 验证命令
+
+```bash
+python3 scripts/ohc-run.py conan-verify <软件> <版本>；G1 通过后继续
+conan create 验证 test_package 消费者链接与运行（./test_<name>）。
+```
+
+## 解决方案
+
+**no-op-build-for-header-only**：header-only 无构建系统库在 conanfile.py 提供 no-op build()（pass），
+package() 用 conan.tools.files.copy 复制头文件；保留 settings 与
+package_type='header-library'。有 CMake 项目的库照常写真实 build()。
+
+```bash
+def build(self): pass  # no-op for header-only / no build system
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`省略 build() 方法直接 conan-verify`
+- **原因**：G1 结构门禁将缺失 build() 判为配方不完整，直接 FAIL 并中断验证
+- **后果**：无法进入 G0-G5/L2/L4/L5，配方无法标记通过
+
+## 涉及软件
+
+所有 header-only / 无构建系统 C++ 库的 Conan 配方（单头文件库、纯头文件模板库），
+在 conan-verify（G1 配方完整性）与 W3/finish 前置门禁中被判 FAIL 的场景。
+
+---
+*条目 E257 · 更新 2026-08-30 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E258: meson.options 与 meson_options.txt 双文件（符号链接物化）导致 meson 拒绝配置
+
+> **严重度**: 🟡 medium | **分类**: meson, filesystem, symlink | **自动修复**: ✅ source-patch
+
+---
+
+## 错误特征
+
+```
+meson\.options and meson_options\.txt both exist, but are not the same file
+```
+
+## 根因
+
+上游源码同时携带 meson.options 与 meson_options.txt（后者是前者的符号链接）。在 HMDFS 等文件系统上复制源码时符号链接被物化为独立普通文件，meson >= 1.5 检测到两份内容相同但非同一 inode 的文件时报错
+
+## 验证命令
+
+```bash
+ls -la meson.options meson_options.txt && meson setup build
+```
+
+## 解决方案
+
+**delete-duplicate-meson-options**：删除 meson_options.txt（或恢复其为 meson.options 的符号链接），使两者为同一文件。meson 0.63+ 支持 meson.options 命名。conan get() 的 tarfile 提取保留符号链接不受影响。
+
+```bash
+rm -f meson_options.txt
+```
+
+## 涉及软件
+
+pcsc-lite 2.4.0 及其他同时打包 meson.options 与 meson_options.txt 的上游项目
+
+---
+*条目 E258 · 更新 2026-08-07 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E259: Conan Release 的 -DNDEBUG 让 assert(含副作用的表达式) 整体不求值，触发上游 latent bug
+
+> **严重度**: 🟡 medium | **分类**: build-system, conan, testing | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+assertion.*self != NULL.*failed
+assertion.*[a-z_]+ != NULL.*failed
+Critical.*assertion.*failed
+FAIL:.*[0-9]+ out of [0-9]+ tests failed
+```
+
+## 根因
+
+上游代码用 assert(EXPR) 包裹了一个有副作用的表达式（如 assert(g_module_symbol(h, "sym", (gpointer*)&p)))），本意是"断言成功的同时完成取符号赋值"。但 Conan 的 AutotoolsToolchain 在 build_type=Release 时注入 -DNDEBUG，C/C++ 标准下 assert(EXPR) 展开为 ((void)0)，EXPR 根本不求值——于是赋值/调用从未发生，p 保持未初始化，后续逻辑静默走错分支或读到垃圾值。这类 bug 在上游裸 make check（无 NDEBUG）下永远不会触发，故属 latent bug；只有 Conan Release 或其它显式 -DNDEBUG 构建才会暴露。调试特征：测试大面积失败（数百个）、但编译/链接全过、失败模式集中在某个初始化路径返回 NULL 或空，且 set_configure / hook 注册类调用"看似没执行"。
+
+## 验证命令
+
+```bash
+在 recipe build() 或测试编译命令里确认含 -DNDEBUG（grep -n DNDEBUG build-release/tests/Makefile）；对可疑 assert 行写最小 C 程序验证：assert((side_effect())) 编译加 -DNDEBUG 后 side_effect 是否执行。
+```
+
+## 解决方案
+
+**hoist-side-effect-out-of-assert**：把 assert(含副作用的表达式) 拆成两步：先把表达式求值存入局部变量，再 assert 该变量的结果。这样 NDEBUG 下断言虽被去除，但副作用（赋值/调用）仍执行。修改落在测试夹具或上游源码的对应行，用最小 source patch 实现，不改变测试 oracle、不跳过测试、不预置答案。
+
+```bash
+gboolean ok = g_module_symbol(h, "set_configure", (gpointer*)&sc); assert(ok);
+```
+
+## 回退方案
+
+**disable-ndebug-for-tests**：仅当上游 assert 副作用遍布、无法逐处拆分时，在 recipe 的测试编译阶段去掉 -DNDEBUG（如 AutotoolsToolchain 的 CXXFLAGS 移除 NDEBUG，或给 make check 单独传 -UNDEBUG）。但这改变了 Release 构建的测试语义，偏离上游真实 Release 行为，仅作退路。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*test|disable.*test|return 0.*OHOS`
+- **原因**：测试失败暴露的是上游 latent bug 的真实触发，删除或空壳化测试会伪造通过，掩盖 Release 构建下的真实风险。
+- **后果**：Release 制品在断言路径上的初始化缺陷完全未验证。
+
+### 🚫 禁止 2
+
+- **模式**：`#define NDEBUG 0|#undef NDEBUG.*production`
+- **原因**：在生产源码里全局取消 NDEBUG 会改变 Release 构建语义、带来性能与行为差异，且掩盖上游设计缺陷而非修复它。
+- **后果**：Release/Debug 行为分叉，性能回退，缺陷被长期掩盖。
+
+## 涉及软件
+
+任何用 Conan Release（-DNDEBUG）构建、且上游存在 assert(含赋值/函数调用等副作用的表达式) 的 C/C++ 项目。常见于用 assert 同时做"检查+初始化"的测试夹具、注册回调、dlsym/g_module_symbol 取符号等场景。上游在普通 Linux 发行版（不带 NDEBUG 跑测试）下永远不会暴露。
+
+---
+*条目 E259 · 更新 2026-08-06 · 知识库同步生成物*