@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/local-errors/L011.md

@@ -0,0 +1,64 @@
+<!-- 来源：new/PC 从 codec2 1.2.0 阶段 6 demo 宿主脚本三连坑沉淀（2026-09-05） | 原编号 E133 -->
+> 一句话定位：Windows 宿主上 agent 生成/改写的脚本与源码，因 BOM / 有损编码 / CRLF 在执行期怪异失败。
+
+# L011: Windows 宿主编码纪律：BOM 吞注释、ASCII 损坏源码、CRLF 毒化 sh/CTest
+
+> **严重度**: 2 major | **领域**: host-tooling/encoding | **自动修复**: none
+
+---
+
+## 报错现场（三种脸）
+
+```
+① UTF-8 BOM 的 .ps1：首行注释前有 EF BB BF，PowerShell 5.1 把注释行当命令解析 → 脚本直接报错
+② Set-Content -Encoding ascii 写含中文注释的 C 源码 → 中文全部变 '?'，注释损坏、个别情形破坏语法
+③ 多行命令/生成文件带 CRLF：sh 把 '\r' 当命令名一部分 → ": command not found"；
+   CTestTestfile.cmake 多行命令因 \r 污染解析失败
+```
+
+## 根因
+
+- **PowerShell 5.1 默认编码不是 UTF-8**（Get-Content/Set-Content 走 ANSI/系统码页），UTF-8 无 BOM 的中文读写即乱；
+- **`Set-Content -Encoding ascii` 是有损转换**——非 ASCII 字符静默变 `?`，不报错、不留痕；
+- **Windows 换行符（CRLF）**经编辑器/git autocrlf/重定向混入 `.sh`、`CTestTestfile.cmake`、生成源码，POSIX 侧解析期爆炸。
+
+## 判别方法
+
+- 症状侧：`: command not found`（`\r` 挂在命令名后）、注释行报"不是 cmdlet"、源码里成串 `?`；
+- 确诊侧（十六进制看首字节/行尾）：`Format-Hex` 或 `xxd`——BOM = `EF BB BF`，CRLF = `0D 0A`；
+- **阳性对照**：先用一个已知干净的文件跑同一条检查，确认工具本身没被环境骗（宿主工具链缺斤短两时，"扫到 0"不是"干净"）。
+
+## 解决方案
+
+1. **统一写法**：所有生成/改写文本文件走 .NET API 而非 PowerShell cmdlet——
+   `[System.IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`
+   （`$false` = 无 BOM；需要 LF 时把 `$text` 里显式用 `` `n ``）；
+2. **读文件显式编码**：`Get-Content -Encoding UTF8` 或 `[IO.File]::ReadAllText`，别依赖默认码页；
+3. **写给 POSIX 消费者的文件（.sh / CTestTestfile / Makefile）一律 LF**，生成后抽查行尾；
+4. **中文字符串禁止过 `-Encoding ascii`**——要么 UTF-8 无 BOM，要么先把中文挪出该文件。
+
+## 误判模式
+
+- 以为是脚本逻辑错误，反复改逻辑（编码问题改逻辑永远修不好）
+- 以为是权限/路径问题（报错形态有时像 PathNotFound）
+- 用 `2>$null` 吞掉探测命令的报错再断言"环境干净"——把工具失效当成检查通过
+
+## 影响范围
+
+所有在 Windows 宿主上生成脚本/源码的阶段：阶段 2 补写用例源码、阶段 3 构建与对账脚本、阶段 6 demo 工程源码与 PS1 包装。Linux 宿主不受影响（本条只管 Windows 侧生成物）。
+
+## 变体：git autocrlf 毒化 fixture 数据（字节级对比用例）
+
+同名不同载体：**CRLF 不只是脚本/源码的问题，还会进入 fixture 数据文件**，毒化字节级对比类用例（JSON 序列化 diff、EML/RFC822 原文比对）。
+
+**实证（libetpan mime-parser，2026-09）**：`git autocrlf=true` 的工作树把 fixture 转成 CRLF，设备端 JSON 序列化对比多出 6 个 `\r` 字节差（generated 2565 vs expected 2559）；且 blob 本身可能就是 CRLF（上游提交习惯）——**判别必须 `git cat-file blob <path>` 核对源字节，不能只看 `file` 命令**。
+
+**处置**：staging 一律在 `core.autocrlf=false` 的重提工作树上做，或逐文件用 `git cat-file blob` 还原源字节；宿主预跑时用源字节对照。
+
+**判别**：设备端字节级 fixture 对比失败，且首差字节在 `0x0d`（`\r`）附近；或 generated 与 expected 长度差恰为行数。
+
+## 关联
+
+- `pc-knowledge-base`（Windows 宿主骨干条目）
+- codec2 阶段 6 实证：PS1 BOM 注释、cases_f02/f07 中文注释 ASCII 损坏、CTestTestfile CRLF 三坑同场爆发
+- libetpan 实证：fixture CRLF 毒化字节级对比（2026-09）

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

@@ -0,0 +1,82 @@
+<!-- 来源：new/PC 自杀毒引擎 CLI 全家桶私有 HNP 装机实测（2026-09-07），源码定位 startup_appspawn service/hnp/base/hnp_zip.c | 原编号 E134 -->
+> 一句话定位：自制 .hnp 装机报 9568407（native package install failed）——**HNP 安装器会剥离每个 zip 条目的首段路径，且解包不建父目录**；zip 布局不满足「pkg/ 前缀 + 目录条目先行」的隐含契约。
+
+# L012: HNP zip 布局违约装机失败（9568407 / 0x801101 / native package install failed）
+
+> **严重度**: 3 (blocking —— 设备装机环节) | **领域**: install/packaging | **宿主修复**: 重打包即可，无需重编
+
+---
+
+## 典型现场（三种面具）
+
+```
+$ bm install -p /data/local/tmp/runner-signed.hap
+error: failed to install bundle.
+code:9568407
+error: Failed to install the HAP because installing the native package failed.
+
+# hilog（tag: hnp/APPSPAWN_HNP）里能看到真正死因：
+E [hnp_zip.c:319] unzip open file:/data/app/.../clamav_1.0.0/clamav/clamav.hdb unsuccess!
+I [hnp_installer.c:665] hnp install end, ret=8392961        # 0x801101 = 打开文件失败
+# 若走宿主 hdc 直装路径参数不对，还会先撞 9568269 install file path invalid（传输层假面具）
+```
+
+## 根因（源码级）
+
+OpenHarmony appspawn 的 `HnpUnZip()`（`service/hnp/base/hnp_zip.c`）对每个 zip 条目：
+
+```c
+char *slash = strchr(fileName, '/');
+if (slash != NULL) slash++;            // ← 剥掉条目的【第一段路径】
+sprintf_s(filePath, "%s/%s", outputDir, slash);
+FILE *outFile = fopen(filePath, "wb"); // ← fopen 不创建父目录！
+```
+
+两条隐含契约，违反任一即失败：
+
+| 契约 | 违反后果 |
+|---|---|
+| **条目应带 `pkg/` 前缀**（官方 hnpcli pack 就是这么打的） | 无前缀时首段剥离把 `bin/x` 压成 `x`、`lib/libfoo.so` 平铺进版本目录根——`.so` 全错位（rpath `$ORIGIN/../lib` 失配）；含子目录的数据文件（如 `share/xx/yy.dat`）落成 `xx/yy.dat` |
+| **目录条目必须先于其内容出现**（hnpcli 的 ZipHandleDir 即目录先行） | 解到深层文件时父目录还不存在，`fopen("wb")` 直接失败 → 0x801101 → bm install 层报 9568407 |
+
+另：条目压缩格式用 DEFLATE（type 8）——官方包全是 DEFLATE，STORED（type 0）未验证且体积大三倍；Python zipfile 需显式 `zi.compress_type = zipfile.ZIP_DEFLATED`。
+
+## 判别方法
+
+```python
+import zipfile
+z = zipfile.ZipFile("my.hnp")
+names = z.namelist()
+print([n for n in names[:5]])                        # 首 5 条应见 pkg/ 前缀且目录在前
+bad_prefix = [n for n in names if not n.startswith("pkg/")]
+# 每个文件的父目录条目必须在其之前出现：
+seen = {n for n in names if n.endswith("/")}
+missing = [n for n in names if not n.endswith("/") and len(n.split("/")) > 2
+           and "/".join(n.split("/")[:-1]) + "/" not in seen]
+```
+
+装机失败后抓真因：`hdc shell "hilog -x" | grep APPSPAWN_HNP`，看 `hnp_zip.c` 行号与 `ret=` 错误码（`8392961` = 0x801101 打开失败）。
+
+## 修复（重打包三件套）
+
+```python
+with zipfile.ZipFile(HNP, "w", zipfile.ZIP_DEFLATED) as z:
+    def wr(arc, data, is_dir=False):
+        zi = zipfile.ZipInfo("pkg/" + arc)            # ① 全条目 pkg/ 前缀
+        zi.external_attr = (0o40775 << 16) | 0x10 if is_dir else (0o100667 << 16)
+        zi.compress_type = zipfile.ZIP_DEFLATED       # ② DEFLATE
+        z.writestr(zi, data)
+    for root, dnames, fnames in os.walk(PKG):
+        for d in sorted(dnames):                      # ③ 目录条目先于内容写
+            wr(rel(d) + "/", b"", is_dir=True)
+        for f in sorted(fnames):
+            wr(rel(f), read(f))
+```
+
+陷阱补丁：**内存构造的条目**（夹具等不落盘文件）父目录不在磁盘上，必须显式补目录条目后再写文件；`hnp.json` 放 `pkg/` 根下（剥离后正好落 HNP 根）。
+
+## 关联
+
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— HNP 打包完整姿势（mode/exec 位/zip 注入 HAP 在同一篇）
+- E120 是 HAP 装机签名问题（9568257 PKCS7），与本条的 9568407 native package 阶段不同层
+- 9568269 "install file path invalid" 多为宿主侧安装命令/路径问题，换 `hdc file send` 到设备再 `bm install -p <设备路径>` 排除传输层

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

@@ -0,0 +1,53 @@
+<!-- 来源：activemq-cpp 适配实证 (2026-09-08, OHOS 6.1.1.135 HAD-W32) | 原编号 E135 -->
+> 适用性：OHOS aarch64 上交叉编译 OpenSSL 3.x 相关代码
+
+# L013: OpenSSL 3.x TLS 握手在 OHOS aarch64 平台级失败
+
+> **结构化数据**: graph/E135.kv | **原则**: 无
+> **严重度**: 🔴 high（该特性无法成功） | **分类**: openssl/network/platform | **自动修复**: ❌ 平台缺陷
+
+---
+
+## 错误特征
+
+```
+# 客户端
+TLS_DIAG: client[raw] SSL_connect failed: ssl_err=2 ossl_err=error:00000000:lib(0)::reason(0)
+# 服务端
+TLS_DIAG: SSL_accept failed: error:0A000126:SSL routines::unexpected eof while reading
+```
+
+- `SSL_connect` 返回 `SSL_ERROR_SSL`（ssl_err=2），**错误队列为空**（`ossl_err=error:00000000`）——这是关键判别特征
+- 服务端 `SSL_accept` 收到 `unexpected eof while reading`（客户端在握手早期关闭连接）
+
+## 根因
+
+**OHOS 6.1.1.135（HAD-W32, aarch64）平台的 OpenSSL 3.x TLS 握手实现缺陷**。客户端发完 ClientHello 后，在 ServerHello 处理阶段失败并关闭连接。已穷尽以下方案全部同一位错：
+
+| 尝试 | 结果 |
+|------|------|
+| decaf SSLSocket（activemq-cpp 库路径） | ❌ 同错 |
+| raw OpenSSL `TLS_client/server_method`（绕过库） | ❌ 同错 |
+| 强制 TLS 1.2（`SSL_CTX_set_min/max_proto_version`） | ❌ 同错 |
+| 显式密码套件（`SSL_CTX_set_cipher_list`） | ❌ 同错 |
+| `SSL_VERIFY_NONE`（禁用证书验证） | ❌ 同错 |
+| **OpenSSL 3.0.16（LTS）/ 3.5.6 / 3.5.8.1 三个版本** | ❌ 全部同错 |
+
+## 判别：不是版本问题
+
+中心制品仓（cnb.cool/OpenHarmonyPCDeveloper）提供 `openssl/3.0.16`、`3.5.6`、`3.5.8.1` 等版本，全部交叉编译产物在设备上 TLS 握手同一位错 → **平台实现问题，与 OpenSSL 小版本无关**。换版本无效。
+
+## 解决方案
+
+**无法由库适配解决**。处置：
+
+1. **归类 testenv-limited**：03-adapt.json / 04-summary.json 如实记录，不升级 built-and-verified
+2. **验证 SSL 工厂级基础设施**（可 PASS）：`SslTransportFactoryTest`（只创建 SSLContext/Factory，不做网络握手）在设备上 PASS——证明 OpenSSL 库可加载、API 可用，仅 TLS 网络握手失败
+3. **等待平台修复**：OHOS 平台修复 OpenSSL 3.x TLS 握手实现后重测
+4. 若应用场景可接受，走非 TLS 传输（如 plain TCP）降级
+
+## 相关
+
+- `pc-knowledge-base` platform/鸿蒙PC-app域执行二进制与JIT限制.md —— app 域网络沙箱上下文
+- [[E003]] —— 链接/符号类错误（本条目是运行时握手，不是链接问题）
+- activemq-cpp 适配案例（04-summary sediment: OpenSSL 3.x TLS 平台发现）

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

@@ -0,0 +1,92 @@
+<!-- 来源：usbredir 0.15.0 适配实证（2026-09，Windows 宿主 meson 交叉编译） | 原编号 E136 -->
+> 适用性：**交叉编译语境**（Windows 宿主 → OHOS aarch64），本机原生编译不适用
+
+# L014: meson `run_command('test', '-d', ...)` 在 Windows 宿主失败（无 `test` 命令）
+
+## 基本信息
+- **严重度**: 2 (major)
+- **类别**: host_side_meson (宿主侧构建环境，非产物缺陷)
+- **触发工具**: meson setup / meson reconfigure
+- **阶段**: configure
+- **首次发现**: usbredir 0.15.0 (2026-09-08)
+
+## 错误签名
+
+```
+meson.build:XX:0: ERROR: run_command test failed with exit status 1
+```
+
+或：
+
+```
+Program test found: NO
+```
+
+`meson.build` 里常见写法（判别 git 工作树 / 目录存在）：
+
+```meson
+if run_command('test', '-d', '.git').returncode() == 0
+```
+
+Windows 宿主（PowerShell/CMD）上**根本没有 `test` 命令**（POSIX 工具），
+`run_command('test', ...)` 找不到可执行程序 → meson setup 直接报错中止。
+
+## 根因分析
+
+meson 的 `run_command` 在 configure 期调用宿主 shell 执行外部程序。上游在 Linux/macOS
+写 `.git` 存在性判别时随手用了 POSIX 的 `test -d`；交叉编译到 OHOS 时 meson **在宿主上**
+执行这段逻辑（Windows 无 `test`）→ 直接失败。**与目标平台无关**，换任何 POSIX-only
+外部命令到 Windows 宿主跑 meson 都会撞同类问题。
+
+## 解决方案
+
+### 方案 1（推荐）：改用 meson 内置 `fs.is_dir()`
+
+`meson.build` 顶部：
+
+```meson
+fs = import('fs')
+```
+
+把 `run_command('test', '-d', X)` 全部替换为：
+
+```meson
+if fs.is_dir(X)
+```
+
+`fs.is_dir()` 是 meson 内建模块、纯 Python 实现，**不依赖宿主外部命令**，Windows/Linux/macOS
+宿主行为一致。这是 upstream 从 meson 0.57 起推荐的替代物。
+
+落地为 patch 示例（usbredir 0001 实测）：
+
+```diff
+-run_command('test', '-d', '.git')
++fs.is_dir('.git')
+```
+
+### 方案 2：给宿主补 POSIX 工具
+
+MSYS2/Cygwin 环境下 `test` 存在，但会引入 MSYS2 PATH 的连带坑（见 E133/hvigor
+spawn java ENOENT——混合 PATH 下 Node/Java 解析失败），不推荐。
+
+## 排查流程
+
+```
+meson setup 报 "run_command xxx failed"
+    │
+    ├─ 被调命令是 POSIX-only（test/dirname/grep -q…）？
+    │       是 → 确认 E136：Windows 宿主无该命令
+    │
+    ├─ 该命令是否只做「文件/目录存在性判别」？
+    │       是 → 用 fs.is_dir() / fs.exists() 替代（方案 1）
+    │
+    └─ 判别依赖 command-line 返回值且有更复杂语义？
+         → 改写为 meson 内建逻辑或 Python 脚本（自定义 find_program + run 包一层）
+```
+
+## 关联
+
+- **E090**: meson host_system 平台检测（同属 meson 语境，但那是目标侧平台名判定）
+- **E133**: Windows 宿主 PowerShell/文件编码坑（同属「宿主侧环境问题、非产物缺陷」大类）
+- pc-knowledge-base「Windows 宿主构建环境四坑」条目 —— ld.lld 并行崩溃 / hvigor MSYS2
+  PATH / hvigor 路径非法字符 / 本条 / pkg-config 缺失（同文件归档，便于一次查全）

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

@@ -0,0 +1,60 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E137.md | 原编号 E137 -->
+> 一句话定位：库的公开 API 契约假设入参非空（如设备/会话/后端句柄必已初始化），但降级/可选能力裁剪后调用方按「能力不可用」分支传入 NULL，函数入口未守卫、内部（或转手 libc/下层库）直接解引用 → SIGSEGV。
+
+# L015: 可选能力降级模式下 API 入参为 NULL 未守卫 → 解引用 SIGSEGV
+
+> **严重度**: 2 major | **领域**: runtime/null-safety | **自动修复**: none（入口加 NULL 守卫）
+
+---
+
+## 报错现场
+
+交叉编译产物在设备侧调用某库 API 时进程直接段错误。faultlog/崩溃栈指向**库内部对入参的首次解引用**，而非调用方代码：
+
+```
+Reason: Signal:SIGSEGV(SEGV_MAPERR) ...
+#00 pc ... libfoo.so (foo_query_info+xx)   ← 库内部函数
+```
+
+## 根因
+
+库 API 的隐含契约是「入参非空」——典型如「设备/会话/后端句柄必已初始化」。上游只在「能力恒可用」的前提下成立，因而**入口不加守卫**，直接 `get_descriptor(handle, ...)` 式解引用。
+
+一旦做了**降级重构 / 可选能力裁剪**（把某能力的初始化从致命改为非致命，用 `have_xxx` 标志守卫），原先「该能力一定可用」的深层 API 就会在能力不可达时收到 NULL 句柄。交叉编译（`-O2`）下对 NULL 解引用是未定义行为，直接 SIGSEGV；原平台/上游 CI 因「该分支本来就走不到」从未暴露。
+
+## 判别方法
+
+1. 崩溃在库内部对入参指针的**直接解引用**（faultlog 栈顶是库函数，不是调用方）；
+2. 该入参来源是「某可选能力是否可用」的降级分支（而非调用方自身的 bug）；
+3. 原平台/上游从未报过此崩溃（该路径在原平台恒可达）。
+
+三条全中 → 归因「降级模式 NULL 入参未守卫」，加守卫。
+
+## 解决方案
+
+**入口加 NULL 守卫**，返回错误码而非崩溃——守卫要加在「对入参第一次解引用之前」：
+
+```c
+if (handle == NULL)
+    return -EIO;   /* 或 -EINVAL；返回错误码，让调用方按能力缺失路径处理 */
+```
+
+要点：
+
+- 与调用方的降级分支配套：调用方只在 `have_xxx` 时走该路径，守卫兜住「能力不可达却仍被调用」的边界。
+- 守卫返回值选库已有的错误码约定（如 `-EIO`/`-EINVAL`），别引入新语义。
+- 顺手排查**同函数内**其他对同一入参的解引用点，一并守卫。
+
+## 影响范围
+
+所有做过「能力非致命化 / 可选后端裁剪」的 C/C++ 库交叉编译场景。降级重构一旦把某能力的初始化失败从 `exit` 改为「跳过」，就必须审计**全部**消费该能力的 API 的 NULL 入口。不止设备句柄——会话、上下文、回调表、可选后端指针同属此类。
+
+## 关联
+
+- `pc-knowledge-base/platform/鸿蒙PC-CLI工具main函数平台能力检查降级模式.md` —— 降级重构通用范式（含「回调 NULL 安全」）；本条是其「深层 API 入参守卫」维度
+- E040：man-db SIGSEGV null pointer（同为 SIGSEGV，但根因是 `get_man_owner` 因 config 返回 NULL，非降级模式）
+- E090：meson host_system 平台检测（同属交叉编译语境，但那是构建期）
+
+## 实证
+
+交叉编译的 C 库做「外设能力降级」后，某「查询类 API」在设备不可达时收到 NULL 设备句柄，入口直接 `get_descriptor(handle, ...)` 解引用 → SIGSEGV。入口加 `if (handle == NULL) return -EIO;` 守卫后崩溃消除，降级路径正常返回错误码。

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

@@ -0,0 +1,83 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E139.md | 原编号 E139 -->
+> 一句话定位：补写/迁移到鸿蒙（musl）的上游或 generated C 测试，断言或参数类型硬编码了 glibc/宿主平台行为，与真实 API 契约不符 → 测试报错 / 越界写 SIGSEGV，看起来像库 bug，实为 **testcase-defect**。
+
+# L016: 测试用例缺陷——断言/参数类型与真实平台契约不符（testcase-defect）
+
+> **严重度**: 2 major | **领域**: test/contract | **自动修复**: none（改测试，不动库；须 file:line 依据回指上游源码）
+
+---
+
+## 报错现场
+
+两种典型表现，共同点是**报在测试侧、根因在测试侧**，库本身没错：
+
+1. **断言预期值写错**（musl vs glibc 字符串行为）：
+
+```
+test_mpg123_string_api: chomp_string("trail  \r\n") == "trail"   ← FAIL（实际 "trail  "）
+```
+
+2. **参数类型写错 → 越界写 → SIGSEGV**（aarch64 指针宽度）：
+
+```
+Reason: Signal:SIGSEGV ...
+#00 pc ... test_out123_params (out123_param FLAGS, ...)   ← 测试程序内崩溃
+```
+
+## 根因
+
+补写 / 迁移测试时，测试代码照搬了**宿主平台（glibc/x86）的隐含假设**，而在鸿蒙 musl / aarch64 上不成立：
+
+- **musl 字符串行为与 glibc 不同**：如 mpg123 `chomp_string` 只剥尾部 `\r\n`、**不动空格**，原断言
+  按 glibc 习惯写成 `strcmp(cs.p, "trail")`，实际结果是 `"trail  "`。函数行为本身正确（回指上游
+  `source/src/libmpg123/stringbuf.c:218-235`），是**断言预期错**。
+- **aarch64 `long` 是 8 字节**：C API 声明 `long*`（如 out123 `out123_getparam`/`out123_getparam2`
+  写 `*ret_value=value`），测试却用 `int ival; out123_getparam(oh, ..., &ival)`——写 4 字节栈内存，
+  越界污染相邻栈帧（下一个 `out123_param(OUT123_FLAGS)` 的 `ao->flags` 字段）→ SIGSEGV。设备上表现
+  为"open 成功、VERBOSE 成功、getparam=1 成功、FLAGS 越界段错误"，全套自洽，极像库 bug。
+
+**不变量**：这两类都属于"改评判标准"的 testcase-defect——只归因、**改测试不改库**，且依据必须给得出
+`file:line` 且真在盘（回指上游源码证实真实契约），修正前的判定证据要存档（`evidence_before`）。
+对应验收规则 `testcase-amendment-evidenced`。
+
+## 判别方法
+
+1. 报错点在**测试程序 / generated C 测试**内部（不是库函数入口的 NULL 解引用——那是 E137）；
+2. 该断言/入参的"正确值"能在**上游源码**里找到权威定义（header 签名、实现函数体）；
+3. 改成与上游契约一致后，用例转 PASS 且不触碰任何返回码/错误码等契约级断言。
+
+三条全中 → 归因 testcase-defect，改测试（`amendment` 字段留痕），不是库 bug。
+
+**与 E137（NULL 入参 SIGSEGV）区分**：E137 是库**入口未守卫**导致的库 bug（加守卫）；本条是
+**测试自身写错**（改测试）。两者都会 SIGSEGV，分界看崩溃栈顶——E137 在库函数，本条在测试程序。
+
+## 解决方案
+
+1. **断言**：查上游实现（`stringbuf.c` 等）确认真实行为，把预期值改成 musl 下的真实值
+   （`"trail  "`）。别为了"让测试过"改库的字符串处理。
+2. **参数类型**：照抄头文件的参数签名——`long*` 就用 `long ival`（aarch64 8B），别图省事用 `int`。
+   用 `-Wsizeof-pointer-memaccess` / `-Wint-conversion` 之类告警在编译期就能抓到。
+3. 修完把改动写成 testcase-defect：`suspected_cause=testcase-defect`、`amendment` 填 `file:line` +
+   `evidence_before`（修正前的判定证据），不进 `failures[]`（那是库的失败，这里库没错）。
+
+## 影响范围
+
+所有"补写 / 从上游迁移测试到鸿蒙 musl"的场景。高频于：C 库字符串/stdio 相关断言、回调参数用
+`long*`/`size_t*` 传出值的 API、依赖 glibc 私有行为（`_IO_FILE`、`secure_getenv` 等）的测试。
+
+## 关联
+
+- E132：跨架构浮点/rand 确定性一过一挂（同为"测试侧平台分歧"，但那是数值阈值，不是断言契约）
+- E137：NULL 入参 SIGSEGV（库 bug，加守卫；与本条的 SIGSEGV 分界见上）
+- `pc-knowledge-base/platform/鸿蒙PC-musl与BSD-glibc库差异.md` —— musl/glibc 差异总览
+- 机制：`lib/testcase-amendment.ts` 的 `pendingTestcaseAmendments()`（改评判标准须机器管起来）
+
+## 实证
+
+mpg123 适配（2026-09）两处 testcase-defect：
+
+1. `tests-generated/test_mpg123_string_api.c:121` `chomp_string` 断言由 `"trail"` 改 `"trail  "`，
+   比对上游 `source/src/libmpg123/stringbuf.c:218-235` 证实 `chomp_string` 只剥尾部 `\r\n` 不动空格。
+2. `test_out123_params` 用 `int ival` 传 `out123_getparam`（声明 `long*`），aarch64 上 4B 越界写 →
+   设备 SIGSEGV；改 `long ival` 后 33/33 全通。独立验收据此判 `testcase-defect`（`verified=true`、
+   `confidence` medium→high），未触碰返回码/错误码等契约级断言。

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

@@ -0,0 +1,89 @@
+<!-- 来源：某图像库适配实证（2026-09-08，Windows 宿主 CMake 交叉编译） | 原编号 E140 -->
+> 适用性：**CMake 交叉编译语境**（Windows 宿主 → OHOS aarch64），Linux 宿主无此问题
+
+# L017: Windows 宿主 `find_package(PkgConfig REQUIRED)` 配置失败（无 pkg-config）
+
+## 基本信息
+- **严重度**: 3 (blocking)
+- **类别**: host_side_cmake (宿主侧构建环境，非产物缺陷)
+- **触发工具**: cmake / cmake configure
+- **阶段**: configure
+- **首次发现**: 某图像库 (2026-09-08)
+
+## 错误签名
+
+```
+CMake Error at CMakeLists.txt:80 (find_package):
+  By not providing "FindPkgConfig.cmake" in CMAKE_MODULE_PATH this project
+  has asked CMake to find a package configuration file provided by
+  "PkgConfig", but CMake did not find one.
+```
+
+或：
+
+```
+Could not find a package configuration file provided by "PkgConfig"
+```
+
+## 根因分析
+
+`find_package(PkgConfig REQUIRED)` 在 **Windows 原生环境**（PowerShell/CMD，非 MSYS2）
+找不到 `pkg-config` 命令——CMake 的 FindPkgConfig 模块需要 `pkg-config` 可执行程序，
+Windows 默认没有。**仅在 Windows 宿主上出这个问题**：Linux/macOS 系统自带 pkg-config。
+
+## 解决方案
+
+### 方案 1（推荐，某图像库 实证）：REQUIRED → QUIET（全可选依赖时）
+
+**前提**：先核对 CMakeLists.txt 中所有 `pkg_check_modules` 调用是否都服务**可选依赖**
+（如 FFTW/CURL/X11/GTK 等）。**必须是全部可选**，才能安全降级。
+
+如果全部可选：
+
+```cmake
+# 改前
+find_package(PkgConfig REQUIRED)
+
+# 改后
+find_package(PkgConfig QUIET)
+```
+
+配置通过后，对应功能按 `pkg_check_modules` 未命中自然裁剪，不影响核心能力。
+
+落地 patch 示例（某图像库 0001 实测）：
+```diff
+-find_package(PkgConfig REQUIRED)
++find_package(PkgConfig QUIET)
+```
+
+**功能被裁剪时同步裁剪验证用例**（某图像库：用例全用 BMP 原生 I/O，不测试 FFT/网络/显示）。
+
+### 方案 2：用 pkg-config 模拟器（meson 语境）
+
+参见 Windows 宿主构建环境四坑 坑 5——Python 编写的 pkg-config 模拟器，
+从 `PKG_CONFIG_PATH` 读取 `.pc` 文件回填编译标志。这套方案是为 meson 生态准备的，
+CMake 项目也可用，但方案 1 更轻量（一行 patch）。
+
+## 排查流程
+
+```
+cmake 报 "Could not find a package configuration file provided by 'PkgConfig'"
+    │
+    ├─ 宿主是 Windows？
+    │       是 → 确认 E140：Windows 缺 pkg-config
+    │
+    ├─ 所有 pkg_check_modules 调用的依赖是否都是可选的？
+    │       是 → 改 REQUIRED 为 QUIET（方案 1）
+    │
+    ├─ 有 pkg_check_modules 调用必选依赖？
+    │       是 → 需装 pkg-config 模拟器（方案 2）或给宿主补 pkg-config
+    │
+    └─ 宿主是 Linux/macOS？
+         → 不是 E140，排查其他原因（如 CMake 版本、PKG_CONFIG_PATH 等）
+```
+
+## 关联
+
+- **E075**: pkg-config 相关的另一类问题（C_INCLUDE_PATH 导致 --cflags 返回空），不同根因
+- `pc-knowledge-base` [[鸿蒙PC-Windows宿主构建环境四坑]] 坑 5（pkg-config 缺失：meson 模拟器 + 本条 CMake QUIET 变体）
+- `pc-knowledge-base` [[鸿蒙PC-图像处理库-CImg图像库交叉编译]] §2.1（某图像库 实证）

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

@@ -0,0 +1,77 @@
+<!-- 来源：某图像库适配实证（2026-09-08，CImg 头文件版本不兼容） | 原编号 E141 -->
+> 适用性：**头文件数据族依赖**——库本身是纯头文件（header-only），但版本与宿主库绑定
+
+# L018: conan 头文件数据族版本不兼容（cimg/3.6.6 t_magenta 常量 vs 函数）
+
+## 基本信息
+- **严重度**: 2 (major)
+- **类别**: dependency_version (依赖版本不匹配)
+- **触发工具**: C++ 编译器（clang++）
+- **阶段**: compile
+- **首次发现**: 某图像库 (2026-09-08)
+
+## 错误签名
+
+```
+src/某图像库.cpp:XXX:XX: error: called object type 'const char[8]' is not a function or function pointer
+    cimg::t_magenta()
+    ^~~~~~~~~~~~~~~~
+```
+
+波及函数：`t_magenta()`、`t_bold()`、`t_normal()`、`t_green()` 等，同一模式 20+ 编译错。
+
+## 根因分析
+
+CImg 3.6.6（conan 仓版本）将 `t_magenta()` 等定义为**常量字符数组**（`const char[]`），
+而 某图像库 405 将其作为**函数调用**（`cimg::t_magenta()`）。两者的 CImg 版本不匹配。
+
+**头文件数据族依赖（header-only library）的版本必须与宿主库严格锁定**：conan 仓的
+`cimg/3.6.6` 是最新稳定版，但 某图像库 405 发行时对应的 CImg 版本是 405（master 分支）。
+依赖中间仓的「最新稳定版」来匹配特定 某图像库 版本必然失败。
+
+## 解决方案
+
+### 方案 1（推荐）：从上游直接取对应版本头文件
+
+不依赖 conan 仓，从上游 GitHub 取与 某图像库_version 匹配的 CImg.h：
+
+```bash
+# 确认 某图像库_version（某图像库.h 中 #define 某图像库_version）
+# 取对应版本的 CImg.h（GitHub master，对应 某图像库 405）
+curl -fsSL -o source/src/CImg.h https://github.com/GreycLab/CImg/raw/master/CImg.h
+```
+
+Windows 上 curl 可能超时，改用 BITS：
+```powershell
+Start-BitsTransfer -Source https://github.com/GreycLab/CImg/raw/master/CImg.h -Destination CImg.h
+```
+
+### 方案 2：从 conan 指定与 某图像库 版本匹配的 CImg 版本
+
+如果 conan 仓恰好有匹配版本，可指定：
+```bash
+conan install --requires=cimg/<匹配版本> -r ohpcd
+```
+但需先确认该版本 API 兼容性（通过搜索 某图像库 源码中的 `t_magenta` 调用模式
+判断 CImg 版本）。
+
+## 排查流程
+
+```
+编译报 "called object type 'const char[N]' is not a function"
+    │
+    ├─ 涉及 cimg::t_magenta()/t_bold()/t_green() 等？
+    │       是 → 确认 E141：CImg 版本与宿主库不匹配
+    │
+    ├─ 涉及其他头文件库的常量/函数二分？
+    │       是 → 类似机制：确认头文件数据族版本与宿主库绑定
+    │
+    └─ 检查 某图像库_version 与 CImg 版本的对应关系
+         → 去 GitHub 上游取对应版本
+```
+
+## 关联
+
+- **E005**: 编译时头文件缺依赖（同属 CImg 家族，但那是 X11 缺失，不是版本不匹配）
+- `pc-knowledge-base` [[鸿蒙PC-图像处理库-CImg图像库交叉编译]] §2.2（某图像库 实证）
+- `pc-capability-domains` graphical-window（CImg 家族显示后端降级）