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

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E346: OHOS hmmac 沙盒拒绝 make 默认 SHELL=/bin/sh（/bin/sh: Permission denied → Error 127；配置阶段 try-compile 与编译阶段均受影响，改用 Ninja generator 解决）
+
+> **严重度**: 🔴 blocking | **分类**: ohos, make, environment, shell, ninja | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+/bin/sh: Permission denied
+Error 127
+make.*Error 127
+make.*Permission denied
+SHELL.*/bin/sh
+Check for working C compiler.*broken
+checking for working C compiler.*broken
+```
+
+## 根因
+
+CMake 生成的 Makefile 硬编码 SHELL = /bin/sh（第 48 行附近），make 子进程执行每条编译规则时调用 /bin/sh 启动 shell；OHOS OpenDesk 沙盒的 hmmac 策略拒绝执行 /bin/sh（报 /bin/sh: Permission denied），导致所有编译目标静默失败并返回 Error 127/Error 1，日志中 clang 编译器命令零输出。该问题同时影响两个阶段：(1) 编译阶段 make 执行 .o 编译规则；(2) CMake 配置阶段（cmake -B）的 try_compile（如 Check for working C compiler）内部也调用 make + /bin/sh → try-compile 失败 → "Check for working C compiler ... broken" → 干净构建在配置阶段即中止。这是 make 默认 shell 被沙盒拒绝的问题，不是 clang 前端初始化失败，也不是 LD_LIBRARY_PATH 问题。补充：hmmac 还拒绝 symlink() 系统调用（ln -s / cmake -E create_symlink / cmake_symlink_library 均 Permission denied），共享库版本化 symlink 规则需改写为 cp 复制
+
+## 验证命令
+
+```bash
+cd <build-ohos> && grep -n '^SHELL' Makefile 看到 SHELL = /bin/sh；或复现：cmake -B（默认 Makefiles）配置报 "Check for working C compiler ... broken" + make[1]: /bin/sh: Permission denied + Error 127；改用 -G Ninja -DCMAKE_MAKE_PROGRAM=/data/service/hnp/bin/ninja 后配置与编译均通过
+```
+
+## 解决方案
+
+**cmake-generator-ninja**：推荐首选改用 Ninja generator（主编验证 + 实测通过）：cmake -B 配置命令追加 -G Ninja -DCMAKE_MAKE_PROGRAM=/data/service/hnp/bin/ninja。Ninja 直接 exec 编译器，不经 /bin/sh，配置阶段 try-compile 与编译阶段均通过。配套：(1) 共享库版本化 symlink 规则在 Ninja 下位于 build-ohos/CMakeFiles/rules.ninja（rule CMAKE_SYMLINK_LIBRARY），需改写 command 为 cp 循环（for f in $out; do cp -f $in $$f; done）规避 hmmac 拒绝 symlink()；(2) cmake --build 不可再追加 -- SHELL=...（Ninja 会把 SHELL=... 当作 target 报 unknown target）。R33 合规：ninja 路径为显式探测常量
+
+```bash
+# 配置阶段（关键）:\n  self.run('{cm} -B "{bd}" -S "{src}" -G Ninja -DCMAKE_MAKE_PROGRAM=/data/service/hnp/bin/ninja {defs}')\n  # 编译阶段: ninja 直接 exec 编译器，无需 SHELL 覆盖\n  self.run('{cm} --build "{bd}" -j{nj}')  # ⚠️ 勿加 -- SHELL=...（Ninja 报 unknown target）\n  # symlink 补丁（hmmac 拒绝 symlink()）: 改写 CMakeFiles/rules.ninja 中\n  #   rule CMAKE_SYMLINK_LIBRARY 的 command 为\n  #   for f in $out; do cp -f $in $$f; done
+```
+
+## 回退方案
+
+**cmake-build-with-SHELL-override**：若无法切换到 Ninja（如必须保留 Makefiles generator），则仅在编译阶段用 cmake --build ... -- SHELL=/data/service/hnp/bin/bash 覆盖 make 的硬编码 SHELL（make 命令行变量优先级最高）；但注意该方案不能修复 CMake 配置阶段 try-compile（其内部 make 不受命令行覆盖），干净构建仍可能在配置阶段失败，故仅作 make-only 场景的降级兜底
+
+```bash
+self.run('{cm} --build "{bd}" -j{nj} -- SHELL=/data/service/hnp/bin/bash')  # 仅 Makefiles generator 有效；Ninja 下会报 unknown target
+```
+
+## 涉及软件
+
+任何在 OHOS 本机 conan create / make 编译的 CMake 工程（Unix Makefiles generator 硬编码 SHELL=/bin/sh 的场景）；配置阶段与编译阶段均受影响
+
+---
+*条目 E346 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E347: GitLab 418 拦截 conan/urllib 源码下载（反爬）
+
+> **严重度**: 🟡 medium | **分类**: network, download, source | **自动修复**: ✅ impl-name                   # 内置实现名 (见 DESIGN §5)
+
+---
+
+## 错误特征
+
+```
+GitLab 418 I'm a teapot on conan/urllib source download
+```
+
+## 根因
+
+gitlab.alpinelinux.org blocks non-curl User-Agents (ohc/1.0, Conan/2.x, Mozilla/5.0) with HTTP 418
+
+## 验证命令
+
+```bash
+curl -fsSL <上游URL> 成功但 conan create 报 HTTP Error 418: I'm a teapot
+```
+
+## 解决方案
+
+**Pre-seed conan source download cache (core.sources:download_cache, keyed by sha256) with a curl-downloaded tarball before conan create; gitlab URLs are official R39 source, cache bypasses the anti-bot 418**：用 curl 预下载 tarball，按 sha256 命名放入 conan sources download cache，绕过 gitlab 反爬 418
+
+```bash
+mkdir -p $CONAN_CACHE/s/<sha256> && curl -fsSL <url> -o $CONAN_CACHE/s/<sha256>/file && 生成 .json 元数据
+```
+
+## 涉及软件
+
+从 gitlab.alpinelinux.org / gitlab.com 下载源码的 conan 配方（source() 阶段）
+
+---
+*条目 E347 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,126 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E348: Conan 2 的 PkgConfigDeps 按依赖包 cpp_info 组件的 pkg_config_name
+
+> **严重度**: 🟡 medium | **分类**: build-system, dependency, pkg-config, glib2 | **自动修复**: ❌ | **原则**: [P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+Run-time dependency gobject-2\.0 found: NO
+dependency.*gobject-2\.0.*not found
+pkg-config.*gobject-2\.0.*not found in pkg-config search path
+No package 'gobject-2\.0' found
+```
+
+## 根因
+
+Conan 2 的 PkgConfigDeps 按依赖包 cpp_info 组件的 pkg_config_name
+逐一生成 .pc；本仓 glib2 配方（〈外部知识库归档〉）只声明
+根组件一个 pkg_config_name="glib-2.0"，故只生成 glib-2.0.pc。
+而 GNOME/GLib 家族上游是 .pc **多文件体系**（glib-2.0 /
+gobject-2.0 / gio-2.0 … 各一个 .pc）。
+消费方 meson.build 用 dependency('gobject-2.0') 检测时，
+pkg-config 在 generators 目录搜不到 gobject-2.0.pc → 检测失败
+（graphene 1.10.8 的 graphene-gobject 类型需要 gobject）。
+这是 conan PkgConfigDeps 的"每包单 .pc 输出"与上游多 .pc
+体系的通用落差，不是单一库的问题。
+
+## 验证命令
+
+```bash
+# 1. 看 PkgConfigDeps 生成了哪些 .pc
+ls ${generators_folder}/           # 期望只有 glib-2.0.pc，无 gobject-2.0.pc
+# 2. 复现 meson 检测失败
+pkg-config --exists gobject-2.0; echo $?   # 非 0 = 找不到
+# 3. 主 .pc 版本（转发型 .pc 的 Version 应继承它）
+pkg-config --modversion glib-2.0           # 期望 2.88.0
+```
+
+## 解决方案
+
+**forwarding-pc-in-generate**：在**消费方配方**的 generate() 里，PkgConfigDeps.generate() 之后
+补写一个转发型 <副>.pc（如 gobject-2.0.pc）到
+self.generators_folder：Version 从主 .pc（glib-2.0.pc）的
+Version 行**动态继承**（不写死）；Requires: <主.pc>（路径/Cflags
+/Libs 全部由被转发的 glib-2.0.pc 提供，转发型 .pc 不写 prefix）。
+前提：依赖声明用 transitive_headers=True, transitive_libs=True
+让 glib 头/库透传给下游。这是 pango 1.56.4 配方
+【skill: --alias-pc 生成】（cairo-ft=cairo,freetype2 /
+cairo-fc=cairo,fontconfig）的同款手法。
+
+```bash
+# graphene 1.10.8 配方 generate() 实例（〈外部知识库归档〉）
+# def generate(self):
+#     PkgConfigDeps(self).generate()
+#     self._forward_gobject_pc()
+def _forward_gobject_pc(self):
+    _src = os.path.join(self.generators_folder, "glib-2.0.pc")
+    if not os.path.isfile(_src):
+        self.output.warning("gobject-2.0 forward: glib-2.0.pc not generated, skip")
+        return
+    _ver = "0"
+    with open(_src, encoding="utf-8") as _f:
+        for _line in _f:
+            if _line.startswith("Version:"):
+                _ver = _line.split(":", 1)[1].strip()
+                break
+    _dst = os.path.join(self.generators_folder, "gobject-2.0.pc")
+    if os.path.isfile(_dst):
+        return
+    with open(_dst, "w", encoding="utf-8") as _f:
+        _f.write(
+            "Name: gobject-2.0\n"
+            "Description: forwarding .pc generated by graphene recipe (Requires glib-2.0)\n"
+            "Version: %s\n"
+            "Requires: glib-2.0\n" % _ver
+        )
+# 依赖声明：self.requires("glib2/2.88.0", transitive_headers=True, transitive_libs=True)
+```
+
+## 回退方案
+
+**patch-glob-aliases**：消费方需要多个副 .pc 时，写通用循环：扫描 generators_folder 下
+主 .pc，对每个 pkg_config_name 派生别名 .pc（Requires: 主.pc），
+一次覆盖整个 GNOME/GLib 家族；仍走 generate()，Version 仍动态继承。
+
+```bash
+# 通用别名示意（generate() 内）
+# for _alias, _req in [('gobject-2.0', 'glib-2.0'), ('gio-2.0', 'glib-2.0')]:
+#     _ver = 读取 generators_folder/<_req>.pc 的 Version: 行
+#     写 generators_folder/<_alias>.pc = Name / Version / Requires: <_req>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`写死 Version（如 .pc 里硬编码 "Version: 2.88.0"）`
+- **原因**：conan 依赖版本升级或配方跨版本复用后，写死的版本与主 .pc 脱节；
+消费方 dependency('gobject-2.0', version: '>=X') 约束会拒绝
+- **后果**：版本约束不满足 → meson 报依赖版本错误；或依赖升级后遗留的
+旧版本号误导后续排查
+
+### 🚫 禁止 2
+
+- **模式**：`把包内自带的 .pc 直接加 PKG_CONFIG_PATH`
+- **原因**：conan 包内 .pc 按 prefix=/ 安装，写的是 /lib、/include 等根路径；
+直接加 PKG_CONFIG_PATH 会解析到设备上不存在的 /lib
+- **后果**：pkg-config 命中但 Cflags/Libs 指向空目录 /lib；若同时混设
+C_INCLUDE_PATH 还触发 E075 的 -I 过滤陷阱
+
+## 涉及软件
+
+所有通过 conan PkgConfigDeps 依赖 GNOME/GLib 家族包（glib2、
+gtk、pango、gdk-pixbuf 等）且消费方用 meson dependency() 检测
+家族内非主 .pc（gobject-2.0、gio-2.0、gmodule-2.0 等）的项目。
+另见 gdk-pixbuf `_create_pkg_config_alias`（复制改名式别名）。
+
+## 相关模式
+
+- **相似模式**：[E075](E075.md)、[E158](E158.md)
+
+---
+*条目 E348 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,85 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E349: 自举编译器类软件常把 bootstrap 源、阶段产物执行、源码根定位
+
+> **严重度**: 🔴 blocking | **分类**: ohos, autotools, toolchain, compiler, conan | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+vlang/vc
+make v
+binary-sign-tool
+read-only /tmp
+Boehm GC
+CMakeToolchain.extra_ldflags
+```
+
+## 根因
+
+自举编译器类软件常把 bootstrap 源、阶段产物执行、源码根定位
+和运行时临时目录耦合在一起。V 0.5.2 的默认 Makefile 会在
+构建阶段拉取 vlang/vc，并立即执行 stage1/stage2/final
+编译器；HarmonyOS PC 上构建阶段不能依赖联网拉取，生成的
+ELF 需要签名后才能继续执行，默认 /tmp 可能只读，且默认
+Boehm GC 在目标上可能报告无效数据根范围。Conan 2 的
+CMakeToolchain 还区分可执行链接标志和通用链接标志。
+
+## 验证命令
+
+```bash
+conan create 〈外部知识库归档〉 --build=vlang/*
+```
+
+## 解决方案
+
+**pinned-bootstrap-source-and-signed-stage-wrapper**：在 source() 中下载并校验主源码与 bootstrap 源，避免 build()
+阶段 clone/pull；只运行本地 bootstrap 目标；每个需要立即
+exec 的 OHOS 阶段产物用 binary-sign-tool 签名并恢复执行位；
+build/package/test 均设置 recipe-owned TMPDIR/TMP/TEMP；
+包装 bin/v 让真实编译器在 share/v 下找到 cmd/vlib/thirdparty，
+并在 OHOS 普通编译调用中追加 -gc none。
+
+```bash
+get(v source) && get(vc source) && make -f Makefile -j1 v VCFILE=v.c OHOS_SIGN_TOOL=binary-sign-tool TMPDIR=$build/tmp
+```
+
+## 回退方案
+
+**executable-link-flag-split**：test_package 使用 Conan 2 CMakeToolchain 时，给 CMake 编译器
+探测或消费者可执行程序追加 OHOS linker 选择，应使用
+toolchain.extra_exelinkflags，而不是不存在的 extra_ldflags。
+
+```bash
+toolchain.extra_exelinkflags.append("-fuse-ld=/path/to/ld.bfd")
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`build.*git clone|build.*curl.*vlang/vc|make.*fresh_vc`
+- **原因**：自举源必须在 source() 阶段固定并校验，build() 阶段联网拉取会使 CI 不可复现。
+- **后果**：构建阶段网络超时或拉取到非锁定 bootstrap 源，导致不可追溯。
+
+### 🚫 禁止 2
+
+- **模式**：`CMakeToolchain\.extra_ldflags`
+- **原因**：Conan 2 CMakeToolchain 没有该属性；可执行链接标志应走 extra_exelinkflags。
+- **后果**：generate() 阶段 AttributeError，CI 在 conan-build-test 前中止。
+
+## 涉及软件
+
+自举语言编译器、需要外部 bootstrap 源仓库的工具链、
+安装后必须通过 wrapper 保持源码根关系的 CLI 编译器包，
+以及 test_package 需要给 CMake 可执行探测追加 OHOS
+linker 选择的 Conan 2 配方。
+
+## 相关模式
+
+- **相似模式**：[E106](E106.md)、[E128](E128.md)
+
+---
+*条目 E349 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E350: Desktop wrapper hard-codes KDE/X11 services unavailable on OpenHarmony
+
+> **严重度**: 🟡 medium | **分类**: portability, desktop-integration, provider-abstraction | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Requirement plasma-activities-cli missing
+xdpyinfo: not found
+kdialog: not found
+```
+
+## 根因
+
+Linux desktop wrapper hard-codes KDE Activities, X11 geometry and GUI dialog commands; OpenHarmony and other non-KDE desktops expose neither the same activity service nor the same display utilities.
+
+## 验证命令
+
+```bash
+bash test_activity_context.sh /path/to/packaged/activityfirefox
+```
+
+## 解决方案
+
+**explicit-context-provider**：Preserve native desktop auto-discovery when available, but move identity resolution behind a provider boundary and accept explicit ID/name inputs from OpenHarmony launchers or system-parameter bridges; restrict path-bearing IDs to a documented safe alphabet and length; make display/dialog helpers optional; test both resolution and the wrapped application flow.
+
+```bash
+patch -p1 < patches/0001-activityfirefox.patch && bash test_activity_context.sh /path/to/packaged/activityfirefox
+```
+
+## 回退方案
+
+**single-default-context**：Use one documented stable default context only when the product explicitly does not need per-workspace separation.
+
+```bash
+ACTIVITY_AWARE_ID=default ACTIVITY_AWARE_NAME=Default activityfirefox
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`fake plasma-activities-cli|hard-code random UUID|skip context resolution test|allow path separators in context ID`
+- **原因**：A command stub, unstable identifier, unsafe path component, or probe-only test does not implement a safe end-to-end platform contract.
+- **后果**：User data can be routed to the wrong Firefox profile, escape the profile directory, or produce a false-positive CI result.
+
+## 涉及软件
+
+Shell and command-line wrappers that derive application state from KDE Activities, X11 geometry, desktop dialogs, notifications, portals, session managers, or similar desktop-specific commands.
+
+---
+*条目 E350 · 更新 2026-08-12 · 知识库同步生成物*

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

@@ -0,0 +1,42 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E351: AbiWord 导出方向插件（GsfOutput）需要扩展 compat shim：可增长内存缓冲 gsf-output.h + IE_Exp 导出框架；并补齐上游被禁用的 xxx_UT_DEBUGMSG 宏
+
+> **严重度**: 🟡 medium | **分类**: ohos, abiword, compat-shim, export-direction, gsf-output | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+xxx_UT_DEBUGMSG.*undeclared
+gsf_off_t.*unknown type
+UT_ASSERT.*undeclared identifier
+GsfOutput.*no member
+recognizeSuffix.*GsfOutput
+```
+
+## 根因
+
+AbiWord 插件若含导出方向（IE_Exp），上游代码依赖 libgsf GsfOutput API（gsf_output_write/seek/tell）与 AbiWord IE_Exp 框架。clarisworks 版 compat shim 只覆盖导入方向（GsfInput+IE_Imp）。此外上游 ie_exp_PalmDoc.cpp 使用永久禁用的调试宏 xxx_UT_DEBUGMSG、ie_impexp_PalmDoc.cpp 经 ie_imp.h 传递使用 UT_ASSERT，ut_debugmsg.h/ie_imp.h 若不补齐则编译报 undeclared identifier；gsf_off_t 在 gsf-input.h/gsf-output.h 各自 typedef 需要统一守卫。
+
+## 验证命令
+
+```bash
+cd  && grep -n gsf_output_write plugins/pdb/xp/ie_exp_PalmDoc.cpp && grep -n xxx_UT_DEBUGMSG compat/ut_debugmsg.h && grep -n GSF_OFF_T_DEFINED compat/glib.h && make check -j1
+```
+
+## 解决方案
+
+**extend-compat-shim-export-direction**：compat/ 新增 gsf/gsf-output.h（可增长内存缓冲 + gsf_output_write/seek/tell/get_data/get_size 测试钩子）、ie_exp.h（IE_ExpSniffer/IE_Exp 导出框架 + registerExporter）、ie_exp_Text.h（文本导出基类，遍历 PD_Document 文本 span 调 _writeBytes）；glib.h 增加 gsf_off_t 统一守卫 typedef、GObject ref/unref、g_ascii_strcasecmp；ut_debugmsg.h 补齐 xxx_UT_DEBUGMSG；ie_imp.h include ut_assert.h；新增源码走 conanfile.py export_sources（不生成 new-file 补丁，E258 草稿）。
+
+```bash
+cp -r 〈外部知识库归档〉 compat && (按上述描述扩展 compat 后) autoreconf -fi && ./configure --prefix=$DEFAULT_PREFIX --build=aarch64-unknown-linux-ohos --host=aarch64-unknown-linux-ohos && make -j1 && make check -j1
+```
+
+## 涉及软件
+
+AbiWord 3.x 带导出方向的插件（pdb/PalmDoc、wpdoc 等）在 OHOS 的 compat shim 适配；任何需要 GsfOutput 内存流 API 的鸿蒙适配
+
+---
+*条目 E351 · 更新 2026-08-13 · 知识库同步生成物*

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

@@ -0,0 +1,79 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E352: Pure Lua 5.1 modules need interpreter-aware layout and target-side require validation
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, lua, conan, packaging, target-validation | **自动修复**: ❌ | **原则**: [P016](../principles.md#P016)
+
+---
+
+## 错误特征
+
+```
+module '.*' not found
+no file '.*/share/lua/5\.1/.*\.lua'
+cannot open .*\.lua
+attempt to call .* nil value
+```
+
+## 根因
+
+Pure Lua modules are executable interpreter resources rather than opaque data files.
+A generic data-only recipe can preserve files while still breaking the Lua contract:
+versioned module roots may be absent from LUA_PATH, legacy top-level require names may
+depend on upstream symlinks that HMDFS cannot follow, and host-only file checks do not
+prove that the target Lua 5.1 interpreter can parse and execute the packaged modules.
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**lua-module-dual-layout-target-require**：Declare all four OHOS profile settings and clear them only in package_id; validate an
+exact non-empty module inventory; install real file copies under both the namespaced
+and compatibility module paths; publish a versioned LUA_PATH through Conan buildenv/runenv;
+then compile or obtain the target Lua interpreter and execute require plus behavior
+assertions against the packaged files. Keep optional-dependency stubs in test_package
+only and prove that they drive the real packaged module.
+
+```bash
+conan create 〈外部知识库归档〉 -pr:h=〈外部知识库流水线〉 -pr:b=〈外部知识库流水线〉
+```
+
+## 回退方案
+
+**namespaced-layout-only**：If upstream does not promise top-level compatibility imports, install only the canonical
+namespace and test every documented require name; do not invent compatibility aliases.
+
+```bash
+lua -e "assert(require('package.namespace'))"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`ln -s .*share/lua|os\.symlink\(.*share/lua`
+- **原因**：HMDFS may preserve a link entry but fail to resolve it, so compatibility require names become runtime-only failures.
+- **后果**：File inventory checks can pass while Lua reports module not found on the HarmonyOS target.
+
+### 🚫 禁止 2
+
+- **模式**：`test.*exists.*\.lua|host.*lua.*require`
+- **原因**：Existence checks and host-interpreter tests do not prove target Lua version compatibility or packaged-module execution.
+- **后果**：Syntax, module search path, dependency loading, and behavior regressions can reach consumers undetected.
+
+## 涉及软件
+
+Pure Lua 5.1 packages whose upstream install rules place modules below a namespace,
+expose compatibility names through symlinks, have no formal test suite, or contain
+optional runtime integrations that are unavailable as OHOS Conan dependencies.
+
+## 相关模式
+
+- **相似模式**：[E050](E050.md)、[E132](E132.md)、[E216](E216.md)、[E241](E241.md)
+
+---
+*条目 E352 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E353: CMake static upstream tests must link the real target
+
+> **严重度**: 🟢 minor | **分类**: cmake, static-library, target-identity, upstream-tests | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+cannot find -lgd
+No rule to make target.*libgd
+GD_LIB.*gd_static
+static.*test.*target
+```
+
+## 根因
+
+Static-only CMake variants can create a different target name than the upstream test helper expects, so the helper falls back to a bare linker name and loses the target dependency.
+
+## 验证命令
+
+```bash
+conan create ${RECIPE} -pr:h=${OHOS_PROFILE} -pr:b=${OHOS_PROFILE} -o ${REF}:with_upstream_tests=True --build=missing --build=${REF}
+```
+
+## 解决方案
+
+**test-helper-target-alias**：When upstream tests are enabled, patch the test helper variable to the actual CMake target produced by the selected static/shared variant.
+
+```bash
+ctest --test-dir ${BUILD_DIR} --output-on-failure
+```
+
+## 回退方案
+
+**disable-upstream-tests-only-with-blocker**：If the target mapping cannot be made safely, document the exact blocker rather than publishing a guessed passed/total rate.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*ctest|0/.*from CI|CI.*pass rate`
+- **原因**：CI package summaries and unstarted CTest runs are not HarmonyOS PC upstream-test evidence.
+- **后果**：The PR body would publish an unsupported test rate.
+
+### 🚫 禁止 2
+
+- **模式**：`global.*GD_LIB|package.*runtime.*test-only`
+- **原因**：The fix belongs to upstream-test source preparation unless the delivered package also requires it.
+- **后果**：Test-only build wiring may leak into the normal package surface.
+
+## 涉及软件
+
+CMake recipes that enable upstream tests in static-only builds and whose test helper variables name a logical library instead of the actual CMake target.
+
+---
+*条目 E353 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,69 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E354: Run Redis upstream Tcl suites against signed OHOS binaries
+
+> **严重度**: 🟡 medium | **分类**: hmdfs, ohos, linking, filesystem, security | **自动修复**: ❌ | **原则**: [P017](../principles.md#P017)、[P019](../principles.md#P019)
+
+---
+
+## 错误特征
+
+```
+Permission denied.*runtest
+Redis test.*failed
+REDIS_TEST_TMPDIR
+tclsh8\.6.*not found
+SIGSTOP.*not.*suspend
+pause_process.*accounting
+```
+
+## 根因
+
+Redis upstream integration tests execute source-tree target binaries and Tcl launchers. On OHOS the binaries must be signed before testing, HarmonyFS can block direct script execution, test state needs user-cache storage, and SIGSTOP can be acknowledged without suspending the process.
+
+## 验证命令
+
+```bash
+PATH=<tcl-package>/bin:$PATH REDIS_TEST_TMPDIR=/data/storage/el2/base/cache/redis-test-$$ make -j1 test test-modules test-sentinel test-cluster
+```
+
+## 解决方案
+
+**sign-targets-run-all-suites-account-capabilities**：Declare Tcl as a separate build-only tool, sign all source-tree target commands before testing, invoke launchers through sh, redirect state to user-cache storage, run all four official entry points, and count only named SIGSTOP-dependent tests as skips with a fail-closed helper guard.
+
+```bash
+llvm-objcopy --remove-section .codesign src/redis-*; binary-sign-tool sign ...; REDIS_TEST_TMPDIR=/data/storage/el2/base/cache/redis-test-$$ make -j1 test test-modules test-sentinel test-cluster
+```
+
+## 回退方案
+
+**extended-package-integration-suite**：Use a checksum-verified isolated Tcl cache while the independent Tcl package awaits publication, and run broad package tests for persistence, replication, failover, Sentinel, Cluster, ACLs, scripting, corruption rejection, and process-stop alternatives.
+
+```bash
+conan cache restore <validated-tcl-cache>; CI_PACKAGES=〈外部知识库归档〉 zsh 〈外部知识库流水线〉
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`skip.*upstream.*suite|upstream_test_in_build:\s*false`
+- **原因**：A smoke-only check does not cover persistence, replication, Cluster, Sentinel, scripting, modules, or failure handling.
+- **后果**：Major runtime regressions can pass packaging gates while the official integration runners never execute.
+
+### 🚫 禁止 2
+
+- **模式**：`binary-sign-tool.*after.*runtest|chmod.*runtest.*retry`
+- **原因**：Target executables must be signed before launch, and HarmonyFS script execution failures require an explicit interpreter rather than repeated chmod.
+- **后果**：Tests fail before meaningful assertions or exercise binaries different from the packaged files.
+
+## 涉及软件
+
+Redis 8.x Conan builds that run the official default, Module API, Sentinel, and Cluster Tcl suites on OHOS.
+
+## 相关模式
+
+- **根因条目（应先修它们）**：[E077](E077.md)、[E060](E060.md)、[E046](E046.md)
+
+---
+*条目 E354 · 更新 2026-08-16 · 知识库同步生成物*

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

@@ -0,0 +1,45 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E355: OHOS meson 适配三步法——harmonyos 平台映射 + conan 制品 .pc prefix=/ 修正 + boost 裁剪模块补全（libboost_locale.a 手工编译）
+
+> **严重度**: 🔴 blocking | **分类**: ohos, meson, conan, pkg-config, boost | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Unsupported platform
+Dependency .* not found
+file not found
+prefix=/
+failed to map segment
+```
+
+## 根因
+
+OHOS 上 meson 的 host_machine.system() 返回 harmonyos（非 linux/darwin/windows），meson 子项目（如 luajit）的平台检测报 Unsupported platform，需映射到 linux 分支；conan 制品 .pc 的 prefix=/ 错误导致 -I//include 空前缀需修正；boost 制品裁剪 interprocess/locale/asio/charconv 模块头与 libboost_locale 编译库需从 GitHub 补全+手工编译
+
+## 验证命令
+
+```bash
+grep -n "host_machine.system" meson.build && grep -n "prefix=" <conan 制品>/lib/pkgconfig/*.pc && test -f <boost 制品>/include/boost/interprocess/streams/bufferstream.hpp && meson setup build --buildtype=release --wrap-mode=nodownload -Dwx_version=3.2.6 && meson compile -C build gtest-main
+```
+
+## 解决方案
+
+**patch-meson-platform**：OHOS meson 适配三步：①host_machine.system() 返回 harmonyos 时映射 linux 分支（LUAJIT_OS_LINUX + elfasm）解决子项目 Unsupported platform；②修正 conan 制品 .pc 的 prefix=/（freetype/harfbuzz/fontconfig/icu/boost/wx-baseu/fftw3）；③补全 boost 制品裁剪模块头（interprocess/locale/asio/charconv 从 GitHub 下载）+ 手工编译 libboost_locale.a（15 共享源 + ICU/STD 后端，NO_POSIX/NO_WINAPI_BACKEND 避开 glibc 专有 strfmon_l）
+
+```bash
+grep -n "host_machine.system" <src>/meson.build && 在子项目平台检测处把
+harmonyos/ohos 并入 linux 分支（如 luajit: if host_machine.system() in
+['linux','harmonyos','ohos']）+ 修正 conan 制品 .pc 的 prefix=/ +
+补全 boost 裁剪模块头并手工编译 libboost_locale.a
+```
+
+## 涉及软件
+
+所有 meson 构建且含子项目（luajit 等）的库在 OHOS 适配；所有依赖 conan boost 制品裁剪模块的库；所有依赖 .pc prefix=/ 错误制品的库
+
+---
+*条目 E355 · 更新 2026-08-14 · 知识库同步生成物*