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

@@ -0,0 +1,69 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E543: Autotools 老项目（configure 生成于 2008 前后）在 OHOS 交叉/原生构建的三类典型适配点：AC_TRY_RUN 探测无交叉分支、lex/yacc 生成器依赖、无 make check 需 test_package 实质验证
+
+> **严重度**: 🟡 medium | **分类**: autotools, cross-compilation, toolchain, build-system | **自动修复**: ❌ | **原则**: [P003](../principles.md#P003)、[P013](../principles.md#P013)
+
+---
+
+## 错误特征
+
+```
+cannot run test program while cross compiling
+AC_TRY_RUN
+checking for format to printf and scanf
+cannot run C compiled programs
+AM_PROG_LEX
+AC_PROG_YACC
+```
+
+## 根因
+
+①configure.in 中的 AC_TRY_RUN 探测（如 guint64 printf/scanf 格式探测）在交叉编译时无法运行测试程序，2008 版 autoconf 生成的 configure 脚本在 cross_compiling=yes 时直接 abort（"cannot run test program while cross compiling"），无缓存/默认值分支；②configure.in 硬性要求 flex（AM_PROG_LEX）与 yacc（AC_PROG_YACC）重新生成 lexer.c/parser.c，CI 构建机无系统 flex/bison 时需要 tool_requires 提供；③上游无 make check 目标（测试程序为 noinst_PROGRAMS），构建验证必须由 test_package 实质调用库 API 完成。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉
+```
+
+## 解决方案
+
+**patch-configure-cross-branch**：直接补丁 configure 脚本（而非 configure.in）的交叉编译分支：交叉编译时跳过 AC_TRY_RUN 循环并赋平台默认值。libIDL 的 guint64 探测取 libIDL_cv_long_long_format="ll"（musl/glibc 标准 %lld），在 for format in ll q I64 循环的 cross_compiling=yes 分支里直接赋值 + break。补丁 configure 而非 configure.in 可避免在构建时依赖 autoconf 重新生成。
+
+```bash
+# configure 中 AC_TRY_RUN 交叉分支（原文为 abort）改为：
+#   if test "$cross_compiling" = yes; then
+#     libIDL_cv_long_long_format="ll"
+#     break
+#   else
+#     ...原有 AC_TRY_RUN 探测...
+#   fi
+```
+
+## 回退方案
+
+**tool-requires-flex-bison**：configure.in 要求 flex/bison 重新生成 lexer.c/parser.c；CI（OHOS build 机）无系统 flex/bison 时，conan 配方用 tool_requires flex/2.6.4 + bison/3.8.2（判断 settings_build.os），macOS 开发机用系统工具（user.build:flex_bison_native conf 区分本机模拟）。若上游已提交生成的 lexer.c/parser.c，则可不依赖 flex/bison。
+
+```bash
+conanfile.py build_requirements(): if settings_build.os == "OHOS": tool_requires("flex/2.6.4"); tool_requires("bison/3.8.2")
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`manually create .ci-result.json|skip W3|dummy package`
+- **原因**：W3 门禁防伪（SKILL 铁律）：.ci-result.json 必须由 finish step5 写入，含日志 SHA256。
+- **后果**：审计发现 431 个编译失败流入 CI（55%），submit 会校验 integrity_hash 拒绝伪造。
+
+## 涉及软件
+
+所有 2008 年前后生成 configure 的 Autotools C 项目（GNOME 系 libIDL/libxml2 等），尤其是带 AC_TRY_RUN 平台探测（long long 格式、字节序、端序）的老库。
+
+## 相关模式
+
+- **根因条目（应先修它们）**：[E072](E072.md)、[E007](E007.md)
+
+---
+*条目 E543 · 更新 2026-09-18 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E544: 框架 G0a 门禁在 〈外部知识库路径〉 为空目录时，zsh null-glob 移除整条 glob 后 `ls` 回退列 cwd，把仓库根条目数误当草稿数，导致任意软件 finish W3 本地 CI 模拟 G0 硬失败（与软件本身无关）
+
+> **严重度**: 🔴 blocking | **分类**: ci-gate|shell|build-system | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+G0a: 〈外部知识库路径〉 目录存在
+G0_DRAFT_COUNT
+ls -1.*\.kv\(N\).*wc -l
+```
+
+## 根因
+
+〈外部知识库流水线〉 的 G0a 门禁用 `ls -1 "${GRAPH_DIR_G0}/draft"/*.kv(N) 2>/dev/null | wc -l` 统计草稿数。zsh 的 null-glob 后缀 `(N)` 在无匹配（目录为空、没有 *.kv）时会把整条 glob 单词移除，于是 `ls -1` 退化为无参数调用、回退列出当前工作目录；`wc -l` 就把 cwd 顶层条目数（如仓库根 31 个条目）误当成草稿数，>0 即判定 G0a 失败。而 `ohc graph add --draft` 会 `mkdir(exist_ok=True)` 创建空的 〈外部知识库路径〉，只要该目录存在（即便为空）就进入 `[ -d ]` 分支触发本 bug。该目录框架本就不应存在（G0a 语义要求草稿放 〈外部知识库路径〉），但空目录也会被 `[ -d ]` 判定为存在。
+
+## 验证命令
+
+```bash
+CI_PACKAGES="〈外部知识库归档〉" zsh 〈外部知识库流水线〉  # 观察 G0a 是否把仓库根条目数误报为草稿数（31）而非 0
+```
+
+## 解决方案
+
+**fix-g0a-count-with-dir-check**：(1) 立即解除阻塞：删除空的 〈外部知识库路径〉 目录（未跟踪，框架自身要求其不存在，rmdir 即可），使 `[ -d ]` 分支不再进入；(2) 框架修复（需单独 PR 提交到脚本）：把 G0a 计数命令从裸 `ls .../*.kv(N)` 改为先判断目录非空再计数，或改用 find 计数，避免 null-glob 移除后 `ls` 回退列 cwd——例如 `G0_DRAFT_COUNT=$(find "${GRAPH_DIR_G0}/draft" -maxdepth 1 -name '*.kv' 2>/dev/null | wc -l)`，或对 glob 结果做 `(( ${#G0_KV_ARRAY} ))` 数组长度判断。
+
+```bash
+rmdir 〈外部知识库路径〉   # 解除阻塞；框架层修复见 rec_description（单独 PR）
+```
+
+## 涉及软件
+
+所有走 finish W3 本地 CI 模拟（调用 build_and_test.sh G0a）的软件；只要本机残留一个空的 〈外部知识库路径〉 目录，无论编译多成功都会在 G0 硬失败。纯 Python / 与框架交互少的三方库（如 libervia-templates）最易踩中，因为其 finish 流程不生成任何真实草稿。
+
+---
+*条目 E544 · 更新 2026-09-27 · 知识库同步生成物*

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

@@ -0,0 +1,42 @@
+<!-- 来源：new/PC · GLFW 案例 | 原编号 E120 -->
+> 适用性：把 HAP 装到鸿蒙 PC 设备时适用
+
+# L001: HAP 安装签名信任链失败（fail to verify pkcs7）
+
+## 严重度: 🔴 3 (blocking — GUI/app 上屏验证被卡)
+
+## 触发场景
+
+`hdc install`（→ `bm install`）安装 demo/应用 HAP 时。常见于 GUI 库（GLFW/SDL/Qt…）为验证目标路径而装 demo HAP，或 `delivery_form=app`。
+
+## 现象
+
+```
+error: failed to install bundle. code:9568257 error: fail to verify pkcs7 file.
+```
+
+自签（`hap-sign-tool.jar` 造 CA）后装机仍报此错；`param set persist.bm.install_no_sign true` 不生效；root shell 也拦。
+
+## 根因
+
+**HAP 安装签名是与二进制/ELF 签名（E077/E083）完全不同的机制**：BundleManager 装机时校验 HAP 的 PKCS7 profile 证书链是否链到设备信任根，**与 `hdc shell id` 是否 root 无关**。自签 CA 不在 `/system/etc/security/trusted_root_ca.json`，而 `/system` 只读 erofs 无法注入；`install_no_sign` 只在 eng/userdebug 版认。
+
+## 修复方案
+
+**别造自签「野 CA」——用 SDK 的 OpenHarmony CA 材料。**
+
+1. **首选**：`ohpt-agent sign-demo -w <ws> --install`——用 SDK 自带 `OpenHarmony.p12` 的 CA 私钥本地签发，链到设备信任的 `OpenHarmony Application Root CA`，**零账号、零设置、任意 bundleName**（真机实测通过）。
+2. 设备**不认** OpenHarmony 根，或要上架 → DevEco 账号自动签名。
+3. 连 SDK 都没有 → 如实降级 `status=built-pending-verification`（勿写 built-and-verified）。
+
+完整判定/路线程序见 `pc-knowledge-base` platform/鸿蒙PC-HAP调试签名与设备安装信任链.md。
+
+## 影响范围
+
+所有需装 HAP 上屏验证的适配：`delivery_form=app`，及命中 GUI 面能力域（graphical-window/gl-context/ui）的 cpp-lib/native-extension。
+
+## 关联
+
+- E077: ELF `.codesign` 自签（**另一套机制**，可自签）
+- E083: JNI `System.load` 签名校验（**另一套机制**）
+- pc-knowledge-base platform/鸿蒙PC-HAP调试签名与设备安装信任链.md（判定/路线权威）

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

@@ -0,0 +1,53 @@
+<!-- 来源：new/PC · GLFW 案例 | 原编号 E121 -->
+> 适用性：在本机命令行构建 HAP（hvigorw assembleApp/assembleHap）时适用
+
+# L002: HAP 构建 00308018（SDK management mode changed / not writable）= runtimeOS 与本机 SDK 形态不匹配
+
+## 严重度: 🔴 3 (blocking — HAP 打包/上屏验证被卡)
+
+## 触发场景
+
+`hvigorw assembleApp`/`assembleHap` 构建 demo/应用 HAP，SDK 初始化阶段（PreBuild）即失败。常见于手写的 `harmony-demo/build-profile.json5` 未按本机 SDK 形态选 `runtimeOS`。
+
+## 现象
+
+两种形态，错误码均为 `00308018`：
+
+```
+Error Code: 00308018  Cause: The SDK management mode has changed.
+Component ArkTS:... has been placed in the wrong place,
+  expect <sdk>/23/ets, actual <sdk>/default/openharmony/ets    （五组件连报）
+```
+或
+```
+Error Code: 00308018  The path <sdk> is not writable. Please choose a new location.
+  at SdkInfoConfig.create ...
+```
+
+## 根因
+
+**`runtimeOS` 与本机 SDK 布局形态不匹配。** hvigor 按 `runtimeOS` 决定 SDK 布局期望与是否写 SdkInfoConfig：
+
+- `runtimeOS: "OpenHarmony"` → 要求**版本化布局** `<sdk>/<api>/ets`（如 `23/ets`）；本机若是 DevEco 的 `default/openharmony/ets` 扁平布局 → 「SDK management mode has changed」；且需往 SDK 目录写 SdkInfoConfig → SDK 只读（macOS 上是 TCC/quarantine 文件级写保护，**非 SIP**）时报 not writable。
+- `runtimeOS: "HarmonyOS"` → 要求 `default/` 布局，**不写** SdkInfoConfig。
+
+同机同 hvigor 对照实证：`runtimeOS:"HarmonyOS"` 越过 Sdk init（继续暴露后续手写骨架缺陷），改回 `"OpenHarmony"` 立即复现 00308018。
+
+## 修复方案
+
+**改配置，别换/下载 SDK（歧路）。**
+
+1. **判定第一步**：看本机 SDK 布局——`<sdk>/default/` 存在 = HarmonyOS SDK（DevEco 装法）→ `build-profile.json5` 的 `runtimeOS` 必须 `"HarmonyOS"`；`<sdk>/<数字>/`（如 `23/`）= OpenHarmony 版本化 SDK → `"OpenHarmony"`。`ohpt-agent env` 的 SDK note 已带 layout 标注。
+2. 顺带查 `compileSdkVersion`：本机未装对应版本则**删该行**，编译版本跟随已装 SDK（实证模板不含此行）。
+3. **禁止**「下载另一个 SDK / 重构 SDK 目录结构」——被症状误导的歧路（曾误下数 GB 扁平 SDK 仍不通）。
+4. 骨架别手写：`ohpt-agent scaffold --kind cpp-lib-demo`（GUI 库 `cpp-gui-owb-demo`、Python GUI `python-gui-owb`）生成已实证骨架，只改占位符。
+
+## 影响范围
+
+所有需构建 HAP 的交付：`delivery_form=app`，及命中 GUI 面（graphical-window/gl-context/ui）的 cpp-lib/native-extension 的 `harmony-demo`。
+
+## 关联
+
+- E120: HAP 安装签名信任链（**装机**阶段，另一套机制；本条是**构建**阶段）
+- ohpt-agent scaffold（HAP 骨架控制面，避免手写 build-profile.json5）
+- pc-knowledge-base platform/鸿蒙PC-应用沙箱与物理路径映射.md（SDK 布局/定位）

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

@@ -0,0 +1,35 @@
+<!-- 来源：插件团队实战沉淀 | 原编号 E122 -->
+
+# L003：QPlainTextEdit::appendPlainText 在 OHOS 上 SIGABRT
+
+## severity
+
+3(blocking)
+
+## 症状
+
+调用 QPlainTextEdit::appendPlainText() 后应用崩溃，SIGABRT in Q_ASSERT。
+
+## 根因
+
+OHOS 上 QPlainTextEdit 在 widget 完全初始化前调用 appendPlainText 触发 Q_ASSERT（原平台不会）。
+
+## 解决
+
+用 QueuedConnection 延迟调用：
+
+```cpp
+QMetaObject::invokeMethod(textEdit, [textEdit, text]() {
+    if (textEdit->isVisible()) {
+        textEdit->appendPlainText(text);
+    }
+}, Qt::QueuedConnection);
+```
+
+## 验证
+
+应用启动后 appendPlainText 不再崩溃。
+
+## 参考
+
+pc-recipe-qt-app/references/qt5-cross-compile-hap.md

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

@@ -0,0 +1,31 @@
+<!-- 来源：插件团队实战沉淀 | 原编号 E125 -->
+
+# L004：CMake 默认生成器回退 MSVC，产物是 x86 .dll
+
+## severity
+
+2(major)
+
+## 症状
+
+构建产物是 x86 Windows .dll/.exe 而非 ARM64 .so；CMake 输出显示 Visual Studio 生成器。
+
+## 根因
+
+Windows 上 CMake 默认选 Visual Studio 生成器，忽略 OHOS toolchain 文件，回退到 MSVC 编译器。
+
+## 解决
+
+必须显式指定 -G Ninja：
+
+```bash
+cmake -S source -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=ohos.toolchain.cmake ...
+```
+
+## 验证
+
+CMake 输出显示 "CMake Generator: Ninja"，产物 `file <so>` 显示 "ELF 64-bit LSB ... ARM aarch64"。
+
+## 参考
+
+pc-recipe-qt-app/references/qt5-cross-compile-hap.md

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

@@ -0,0 +1,33 @@
+<!-- 来源：插件团队实战沉淀 | 原编号 E127 -->
+
+# L005：Scintilla 等 C++17 依赖编译失败
+
+## severity
+
+1(minor)
+
+## 症状
+
+`std::optional`/`std::variant` 等 C++17 类型未定义或 "feature not supported"。
+
+## 根因
+
+全局未启用 C++17 或不应全局设 C++17（可能与 musl 头文件冲突）。
+
+## 解决
+
+per-target 设 C++17：
+
+```cmake
+target_compile_features(scintilla PUBLIC cxx_std_17)
+```
+
+不要用 `set(CMAKE_CXX_STANDARD 17)`。
+
+## 验证
+
+scintilla 及依赖 C++17 的代码编译通过。
+
+## 参考
+
+pc-recipe-qt-app/references/qt5-cross-compile-hap.md §Scintilla

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

@@ -0,0 +1,36 @@
+<!-- 来源：插件团队实战沉淀 | 原编号 E128 -->
+
+# L006：链接 QPA 平台插件导致运行时加载失败
+
+## severity
+
+3(blocking)
+
+## 症状
+
+应用安装后启动崩溃/白屏，或运行时报 "This application failed to start because no Qt platform plugin could be initialized"。readelf 显示 NEEDED 包含平台插件 .so。
+
+## 根因
+
+链接平台插件导致 NEEDED 写入 .so 动态段，运行时动态链接器在错误路径查找插件。平台插件应由 Qt 运行时动态加载，不应编译时链接。
+
+## 解决
+
+移除 target_link_libraries 中的平台插件 target。只链接 Qt5::Core/Qt5::Gui/Qt5::Widgets 等模块。
+
+Qt 5.15.17：
+```cmake
+# ❌ 错误
+target_link_libraries(${PROJECT_NAME} Qt5::QOpenHarmonyPlatformIntegrationPlugin)
+
+# ✅ 正确
+target_link_libraries(${PROJECT_NAME} Qt5::Core Qt5::Gui Qt5::Widgets)
+```
+
+## 验证
+
+`llvm-readelf -d libYourApp.so | grep NEEDED` 中无 `libplugins_platforms_qopenharmony.so`。
+
+## 参考
+
+pc-recipe-qt-app/references/qt5-cross-compile-hap.md

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

@@ -0,0 +1,78 @@
+<!-- 来源：new/PC · mkspiffs 私有 HNP 执行器实证 + activemq-cpp 误判复盘 | 原编号 E129 -->
+> 适用性：在鸿蒙 PC 设备上执行**自己交叉编译出来的**可执行文件时适用
+
+# L007: 设备侧执行用户二进制被拒（Permission denied / Operation not permitted / exit 126 / 127）
+
+## 严重度: 🔴 3 (blocking — 设备验证被卡在第一步)
+
+## 触发场景
+
+`hdc file send` 把交叉编译产物推到 `/data/local/tmp`（或桌面 hmdfs 目录、应用沙箱 `files/bin/`）后直接跑；
+或 app 域原生代码 `fork/execv` 一个随 HAP 带进去的普通 ELF。
+
+## 现象
+
+```
+$ hdc shell "/data/local/tmp/mytool --version"
+sh: /data/local/tmp/mytool: Permission denied          # 或 Operation not permitted（EPERM）/ exit 126 / 127
+$ hdc shell "chmod 755 /data/local/tmp/mytool && /data/local/tmp/mytool"
+sh: ... Permission denied                              # chmod 无用
+```
+
+> **EPERM 与 EACCES 同罪**：`Operation not permitted` 与 `Permission denied` 在本条是同一拦截的两种文案，
+> 都指向 SELinux 标签归属——**不要**因为「not permitted」字样更像「权限/签名被拒」而拐进 E077 的签名叙事
+> （E077 只治「原来能跑、被 patchelf/strip 破坏后跑不了」；本机从没 exec 成功过的，签多少次都没用）。
+
+## 根因
+
+**拦截来自文件的 SELinux 标签归属，与 ELF 签名对错无关。** 用户文件落在 `data_local_tmp` /
+hmdfs / `data_app_el1_file` / `debug_hap_data_file` 这些标签下，hdc shell 域（uid 2000）与 app 域
+都不放行 exec。**判据**：把系统自带的 `/system/bin/toybox` 物理拷贝一份到同一目录，照样被拒——
+它的签名当然是对的，可见签名不是变量。DAC 权限（`chmod +x`）同理不是变量。
+
+> **别串台**：
+> - **E077** 是「原来能跑，被 `patchelf`/`strip`/`objcopy` 处理后跑不了」——`.codesign` 段失效。
+>   本条是「在这台设备上**从来没有** exec 成功过」，两者的修法完全不同。
+> - **E120** 是 HAP 装机的 PKCS7 信任链，又是另一套。
+
+## 修复方案
+
+**唯一通道：打成私有 HNP，随执行器 HAP 装机，在 app 域 `fork()+execv()` 跑。**
+
+```bash
+ohpt-agent scaffold --kind cli-hnp-runner -w <ws> --tool <cli名> --bundle com.example.<cli>run
+# 填 build/build-hap.sh 的 TOOL_BIN + napi_stub.cpp 的用例段，然后：
+bash build/build-hap.sh                                              # 打 HNP + zip 注入未签 HAP
+ohpt-agent sign-demo -w <ws> --hap dist/app/<cli名>-runner-unsigned.hap --install
+hdc shell "aa start -a EntryAbility -b <bundle> -m entry"
+hdc shell "hilog -x | grep <tag>"                                    # 主证据：TAP/RAW 原始输出
+```
+
+模板用法与承重骨架见 `templates/hap/cli-hnp-runner/README.md`；平台机制（四道关：私有 HNP 才能 exec、
+io_uring/close_range 被 seccomp、JIT 写不了可执行内存）见 `pc-knowledge-base` 的
+`platform/鸿蒙PC-app域执行二进制与JIT限制.md`；取证顺序（**先 `hilog -b D` 提级别再冷启动**）见
+`platform/鸿蒙PC-hdc能力边界与取证通道.md`。
+
+ELF 本身仍要签，但走**宿主链接期自签** `LDFLAGS='-Wl,--code-sign'`（post-link `strip` 会破坏签名段）；
+HAP 签名覆盖包内注入的 `hnp/`，无需设备侧签名工具。
+
+## 以下处置都不成立
+
+| 想法 | 为什么不成立 |
+|---|---|
+| `chmod +x` / 换个目录再跑 | 标签跟着目录走，`/data/local/tmp`、hmdfs 桌面、应用 `files/bin/` 全拒 |
+| 「先把 ELF 签对就能直跑」 | 系统自带二进制的拷贝（签名合法）同样被拒 |
+| 「换一台 root / 可调试 / 装了 DevBox 的机器」 | 工具只面向鸿蒙 PC 商用机（无 root），**不存在这个选项**；私有 HNP 通道在商用机上已端到端实证 |
+| 「设备上没有 X，所以做不了」 | 设备上有没有都一样要**自带**——打进私有 HNP 即可 |
+
+## 影响范围
+
+`delivery_form=cli` 的全部适配；以及任何需要在设备上真跑测试可执行（官方测试套件、benchmark、
+test_runner + 测试模块 `.so`）的形态——跑法见 `pc-knowledge-base` 的
+`platform/鸿蒙PC-真机跑官方测试套件.md`。
+
+## 关联
+
+- E077: ELF `.codesign` 被后处理破坏（**另一套**，可自签）
+- E120: HAP 装机 PKCS7 信任链（**另一套**）
+- `pc-device-verify` 的 `references/domain-hdc-shell.md`（hdc shell 域够不到的三件事）

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

@@ -0,0 +1,75 @@
+<!-- 来源：new/PC · readline 8.3 适配 ncurses 运行时数据缺失复盘（2026-09-03） | 原编号 E130 -->
+> 适用性：依赖库运行时会读取系统数据目录（terminfo/locale/CA 信任库等）的所有适配形态
+
+# L008: 依赖运行时数据在目标机缺失（功能全绿但能力静默降级）
+
+## 严重度: 🟠 2 (major — 不阻塞构建与常规测试，但交付的是能力退化版)
+
+## 触发场景
+
+依赖库静态/动态链入产物后，运行时会去**系统路径**读数据才能完整工作
+（terminfo、locale .mo、CA 信任库、插件数据……）。构建与设备测试全部通过，
+但真实使用中能力不完整——**没有报错、没有 crash、测试照常全绿**。
+
+## 现象
+
+- 能力查询类调用返回失败/空/恒定值：如 `tgetent()` 返回 0（查不到终端描述），
+  readline 按哑终端降级（无光标控制序列输出、渲染怪异或退化为逐行模式）
+- 翻译永远显示原文、TLS 校验全挂——**功能点用例却一个都不会红**
+  （断言锚在库内状态：`rl_point`/`history_length`/返回值，不锚环境数据）
+- 设备上该系统路径不存在：`ls /etc/terminfo` → No such file or directory
+
+## 根因
+
+**链接期自包含 ≠ 运行期可用。** 依赖的代码进了产物，但代码运行时读取的
+**数据**是"本应由发行版提供"的，鸿蒙 PC 零售机不带 Linux 惯例的系统数据目录
+（`/etc/terminfo`、`/usr/share/terminfo` 等均不存在，实测）。多数读数据的实现
+走静默降级（返回失败码），不崩溃、不报错——所以常规功能测试结构性测不出来：
+测试用例从 PRD 功能点生成，而"依赖的数据健康度"不是任何一个 API 功能点，
+它是横切所有功能点的环境前提。
+
+> **别串台**：
+> - **E019/E088** 是共享库**代码**加载失败（NEEDED/RPATH）——本条代码加载正常，
+>   缺的是**数据**。
+> - **E023** 是 locale 行为差异导致的测试失败（会报错）——本条是静默降级不报错。
+
+## 修复方案
+
+**三步证据链判定 + 数据随包 + 环境自举。** 完整判定方法、数据族-符号族-环境变量
+映射、验证模板见 `pc-capability-domains` 的
+`references/capability-domains/runtime-data-assets.md`（能力域条目，权威）。
+
+```c
+/* 以 terminfo 族为例：数据随 HNP share/terminfo，首次调用前自举 */
+setenv("TERMINFO", "<hnp-root>/share/terminfo", 0);
+setenv("TERM", "xterm-256color", 0);
+```
+
+验证必须用**三段式行为差分用例**（数据可达 / 能力真实 / 行为级证据），
+模板见 `pc-test-design` 的 `case-design-methods.md` §6。只有常规功能用例全绿
+**不能**证明数据健康——这正是本条被记录的原因。
+
+## 以下处置都不成立
+
+| 想法 | 为什么不成立 |
+|---|---|
+| 「测试全绿说明没问题」 | 功能点断言锚在库内状态，环境数据缺失不触发任何断言失败——全绿与本缺陷共存（readline 实测：降级状态下 32/32 全过） |
+| 「设备上没有就装到系统路径」 | 零售机无 root，`/etc`、`/usr/share` 不可写；数据必须随包（HNP）+ 环境变量指路 |
+| 「静态链入依赖代码就够了」 | 代码自包含 ≠ 数据自包含；terminfo/locale 这类数据是运行时按需读的，链不进去 |
+| 「逐个依赖扫包看有没有 share/ 目录」 | 信噪比极差且判不准（有数据目录 ≠ 运行时会读）；正确触发是**产物符号面**（`nm -D` 见数据访问符号族） |
+
+## 影响范围
+
+所有运行时读取系统数据的依赖：ncurses/terminfo（readline、goaccess 类）、
+gettext/locale、openssl/CA、按路径加载插件数据的库。零售机一律视为
+"系统数据不存在"环境做判定。
+
+## 关联
+
+- `pc-capability-domains/references/capability-domains/runtime-data-assets.md`
+  （能力域条目：判定三步链 + 数据族-自举映射 + 实例——权威）
+- `pc-test-design/case-design-methods.md` §6（行为差分伪用例模板）
+- `pc-delivery-forms` 交付必做项表"产物动态符号命中数据访问族"行（发现时机）
+- `pc-capability-domains/references/capability-domains/terminal-render.md`
+  （终端可见渲染——**渲染效果**这层的判定与验证；本条管数据健康、它管渲染正确，
+  buffer 断言失败的第一嫌疑是本条）

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

@@ -0,0 +1,81 @@
+<!-- 来源：new/PC · libunistring 1.4.2 适配 GB18030 编码方向缺失复盘（2026-09-04） | 原编号 E131 -->
+> 适用性：交叉编译 + 设备运行适用
+
+# L009: OHOS musl 分支 iconv 缺失 CJK 编码方向（to=CJK EINVAL）
+
+> **严重度**: 🟠 major | **分类**: libc/compat/encoding | **自动修复**: ❌ none
+
+---
+
+## 错误特征
+
+```
+iconv_open("GB18030", "UTF-8") = (iconv_t)-1, errno=22
+iconv_open("GBK", "UTF-8")     = (iconv_t)-1, errno=22
+iconv_open("GB2312", "UTF-8")  = (iconv_t)-1, errno=22
+iconv_open("BIG5", "UTF-8")    = (iconv_t)-1, errno=22
+```
+
+解码方向正常（`iconv_open("UTF-8", "GB18030")` = OK），ISO-8859-1 等非 CJK 双向正常。失败与源编码无关（UTF-8/UTF-16LE 均 EINVAL）。
+
+## 根因
+
+OHOS musl 分支裁剪了 CJK 的 wctomb（编码方向）转换表，只保留 mbtowc（解码方向）。标准 musl 上游支持 GB18030/GBK/GB2312/BIG5 双向，这是分支特定裁剪，不是 musl 固有行为。
+
+| 方向 | 标准 musl | OHOS musl |
+|------|-----------|-----------|
+| from=CJK（解码） | ✅ | ✅ |
+| to=CJK（编码） | ✅ | ❌ |
+
+## 诊断方法
+
+在 demo 进程中直接调 `<iconv.h>`（不经过被测库），做 to=CJK 与 from=CJK 对比探针矩阵：
+
+```
+iconv_open(to=GB18030, from=UTF-8)   → EINVAL ❌
+iconv_open(to=UTF-8,   from=GB18030) → OK     ✅
+iconv_open(to=GBK,     from=UTF-8)   → EINVAL ❌
+iconv_open(to=UTF-8,   from=GBK)     → OK     ✅
+iconv_open(to=GB2312,  from=UTF-8)   → EINVAL ❌
+iconv_open(to=UTF-8,   from=GB2312)  → OK     ✅
+iconv_open(to=BIG5,    from=UTF-8)   → EINVAL ❌
+```
+
+to=CJK 方向全 fail 且 from=CJK 方向全 ok → 归因 OHOS musl 分支裁剪，非被测库缺陷。
+
+## 解决方案
+
+静态嵌入 GNU libiconv，替代系统 iconv 的 CJK 编码方向：
+
+1. **交叉编译 GNU libiconv**：`--host=aarch64-linux-ohos --enable-static CFLAGS=-fPIC`。源 tarball 的 config.sub 不识别 ohos，从 gnulib build-aux 复制新版，libcharset/ 子目录的 config.sub 也需同样覆盖。
+2. **重编 iconv 消费 TU**：只重编被测库中直接调 `iconv_open`/`iconv`/`iconv_close` 的翻译单元，编译时加 `-I<libiconv-prefix>/include`。GNU libiconv 头在 `LIBICONV_PLUG` 未定义时自动映射 `iconv_open`→`libiconv_open`、`iconv`→`libiconv`。
+3. **链接 libiconv.a**：静态嵌入，DT_NEEDED 仍只有 `libc.so`，无额外运行时依赖，产物可原地替换部署。
+
+## 禁止模式
+
+❌ 依赖 musl 分支修复 → 适配周期内不可控
+❌ 改测试断言装死 → 被测库自身功能不完整，不是断言预期问题
+❌ 用 gnulib iconv 替换层 → gnulib 无此类 CJK 编码方向 knob
+
+## 影响范围
+
+所有在鸿蒙上做 CJK 编码转换的库（UTF-8 → GB18030/GBK/GB2312/BIG5 方向）。解码方向不受影响。
+
+## 变体：iconv 别名映射缺失（iso-2022-jp → iso-2022-jp-2）
+
+同根不同表：musl 的 iconv **别名表**比 glibc 薄——glibc 把 `iso-2022-jp` 视作 `iso-2022-jp-2` 的别名（同一编码族，互通），musl 无此别名映射。
+
+**实证（libetpan charconv_test，2026-09）**：libetpan `charconv.c:725` 把 `iso-2022-jp` 映射为 iconv 名 `iso-2022-jp-2`，设备上报 `iso-2022-jp: conversion failed with error 1（MAIL_CHARCONV_ERROR_UNKNOWN_CHARSET）`；宿主 glibc CI 全绿——平台字符表覆盖差异，非移植缺陷。
+
+**判别**：`iconv_open("iso-2022-jp-2", "UTF-8")` 在宿主 glibc 成功、设备 musl EINVAL；库源码把日文编码映射到 `*-2` 别名上。
+
+**解法方向**（与 CJK 方向一致的两条路）：
+1. 内建字符映射表：为库的日文编码路径内建 iso-2022-jp-2 表，不依赖系统 iconv；
+2. 随包静态嵌入 GNU libiconv（同下方主方案），GNU 版别名表覆盖 iso-2022-jp-2。
+
+判别口径：先在设备上用最小探针确认 `iconv_open` 别名缺失，再归因到「库的字符表假设 vs 平台 iconv 能力面」，不要当成产物缺陷去改库逻辑。
+
+## 关联
+
+- E039: musl iconv 不支持 //IGNORE 后缀（同为 musl iconv 能力面）
+- `pc-knowledge-base/adaptation/鸿蒙PC-libunistring-GNU-iconv替代系统iconv.md`（实例）

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

@@ -0,0 +1,64 @@
+<!-- 来源：new/PC 从 codec2 1.2.0 burble 静噪用例双架构分歧沉淀（2026-09-05） | 原编号 E132 -->
+> 一句话定位：同一测试代码宿主 x86_64 过、设备 aarch64 挂（或反之）——数值断言在阈值刀刃上翻转。
+
+# L010: 跨架构浮点微差 + libc 依赖的测试脚手架：同代码双架构一过一挂
+
+> **严重度**: 2 major | **领域**: numerics/test-scaffolding | **自动修复**: none
+
+---
+
+## 报错现场
+
+```
+# codec2 test_freedv_api_700D_burble（断言 output speech samples: 0）
+宿主 x86_64 + musl rand 精确复刻: 0 同步帧, nout=0        → PASS
+设备 aarch64 + musl (同一实现):    4/750 帧越过 -2dB 静噪门限
+                                  output speech samples: 2560 → FAIL
+# 同族先兆：musl rand() 未播种首抽返回 0 → Box-Muller log(0)=inf
+#           → "measured double sided (real) noise power: nan"（LDPC 用例三连挂）
+```
+
+## 根因
+
+两层叠加，缺一不炸、合起来必炸：
+
+1. **测试脚手架的随机性依赖 libc**：信道仿真/噪声注入用 libc `rand()`——glibc 与 musl 未播种序列不同、musl 首抽还是 0（`seed 0→1→1>>33==0`），噪声实现悄悄平台相关；
+2. **跨架构浮点微差**：即便噪声序列一致，libm 多项式/指令选择/求值顺序的 ULP 级差异经 DSP 链路（FFT/滤波/SNR 估计的 cnormf-sqrtf-log10f 链 + 平滑）累积成**亚 dB 量级漂移**。
+
+断言若恰好压在阈值上（"静噪 -2dB、实测 SNR 恰在 -0.3~-1.9"），亚 dB 漂移就翻转门控判定。**库功能本身正常**——同链路参考工作点用例全过、逐位一致用例全过。
+
+## 判别方法（排除法四连，顺序执行）
+
+1. `-ffp-contract=off` 与 `-O1/-O2/-O3` 重建结果**逐位一致** → 排除 FMA 收缩与优化级；
+2. 宿主上**精确复刻对端 RNG**（把对端 libc 的 rand 实现搬过来）重跑 → 仍一过一挂 → 排除"随机数序列不同"这一层；
+3. 同链路的精确计数用例（无阈值、只有等值断言）通过 → 排除功能/移植缺陷；
+4. 设备 A/B 对照：同代码同参数，唯一变量换 RNG（libc rand → 确定性 xorshift32）→ fail 变 pass → **实锤因果**。
+
+## 解决方案（是协议，不是答案——每个库的噪声结构不同，seed 不能通用）
+
+1. **脚手架确定性化**：libc `rand()` 换库自带的确定性发生器（如 xorshift32），
+   映射取 `(x>>8)+0.5)/2^24` 开区间中点——**严格落在 (0,1)**，`log()` 永不见 0
+   （顺带消灭 musl 首抽 0 的 inf 问题）；采样结构（Box-Muller 的 2-uniform）原样保留；
+2. **seed 防挑选协议**：N 个 seed 变体（如 12 个）宿主+设备**双平台扫荡**，以
+   「**其他用例的精确计数断言不变**」为筛选条件——改了别处行为的 seed 直接淘汰，
+   通过者才够格；选择过程（脚本、日志、淘汰依据）落盘备查；
+3. **断言值锚定等价条件**：数字必须来自与用例**等价时长/模式/语料**的实测
+   （验收规则 `testcases-numeric-expectation-anchored` 执法出处+条件）；
+4. **双证据存档**：round1 的 fail 判定与 round2 的修正证据都保留
+   （`<case>.round1.json` / `device-raw.round1.log`），notes 写明授权链与"检查点原样保留"。
+
+## 误判模式
+
+- 以为编译器 bug，反复换工具链/优化级（判别法 1 已排除，白耗轮次）
+- 以为移植缺陷去改**库**代码（功能正常，改了反而引入真回归）
+- 放宽阈值/调噪声电平让用例变绿——**这是篡改测试**，等于把刀锋断言改成钝刀
+- 只换 RNG 不做 A/B 对照——无法证明"确实是 RNG/浮点层"，可能掩盖真缺陷
+
+## 影响范围
+
+DSP/数值/信号处理类库（codec2、speexdsp、lame、opus 定点路径…）× 阈值附近断言 × 任何用 libc RNG 的测试脚手架。刀锋断言（静噪、门限、BER 边界）风险最高。
+
+## 关联
+
+- 验收规则 `testcases-numeric-expectation-anchored`（数字断言的出处+等价条件红线）
+- codec2 修复实证：`patches/ohos-adapt-03-ch-deterministic-noise.patch`（xorshift32 + seed 3 + A/B 对照）