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

@@ -0,0 +1,72 @@
+<!-- 来源：某图像库适配实证（2026-09-08，CImg 家族 X11/Xlib.h 缺失） | 原编号 E142 -->
+> 适用性：**CImg 家族库**（CImg.h、某图像库、lib某图像库 等依赖 CImg 的库）在非 Windows 平台交叉编译
+
+# L019: CImg 家族 X11/Xlib.h not found（NDK sysroot 无 X11）
+
+## 基本信息
+- **严重度**: 2 (major)
+- **类别**: compilation (编译头文件缺失)
+- **触发工具**: C++ 编译器（clang++）
+- **阶段**: compile
+- **首次发现**: 某图像库 (2026-09-08)
+
+## 错误签名
+
+```
+fatal error: 'X11/Xlib.h' file not found
+#include <X11/Xlib.h>
+         ^~~~~~~~~~~~
+```
+
+## 根因分析
+
+CImg.h 在**非 Windows 平台**（`cimg_OS!=2`）默认 `#include <X11/Xlib.h>` 以支持
+X11 显示后端。OHOS NDK sysroot 没有 X11 头文件，且鸿蒙 PC 没有 X11 窗口系统。
+
+**CImg 的显示后端是完全可选的**：仅用于交互式图像预览功能（`display` 命令），
+图像处理核心与 CLI 批处理完全不依赖它。因此不需要移植 X11 或走 OWB 桥接，
+直接禁用显示后端即可。
+
+## 解决方案
+
+### 方案 1（推荐）：编译标志加 `-Dcimg_display=0`
+
+显式禁用 CImg 显示后端，这是最直接的修法——比靠探测不命中更稳：
+
+```cmake
+# CMakeLists.txt 中添加
+target_compile_definitions(某图像库 PRIVATE cimg_display=0)
+# 或命令行
+-DCMAKE_CXX_FLAGS="-Dcimg_display=0"
+```
+
+`cimg_display=0` 后：
+- CImg.h 不再 `#include <X11/Xlib.h>`
+- `display` 命令在运行时自动报 unsupported（某图像库.cpp:6557 有可用性检查）
+- 图像处理核心与 CLI 批处理完全不受影响
+
+### 方案 2：不推荐（给宿主补 X11 头文件）
+
+从 Linux 系统拷贝 X11 头文件到 NDK sysroot 可以编译通过，但产物链接 X11 后
+在鸿蒙上运行时无法工作（无 X11 显示服务），意义不大。
+
+## 排查流程
+
+```
+编译报 "fatal error: 'X11/Xlib.h' file not found"
+    │
+    ├─ 报错源文件是 CImg.h 或依赖 CImg 的库？
+    │       是 → 确认 E142：CImg 家族默认 include X11
+    │
+    ├─ 库的显示后端是核心功能还是可选的交互式预览？
+    │       可选预览 → 加 -Dcimg_display=0（方案 1，推荐）
+    │
+    └─ 显示后端是核心功能？
+         → 无法简单禁用，需走 OWB 桥接方案（见 graphical-window 能力域）
+```
+
+## 关联
+
+- `pc-capability-domains` [[graphical-window]] 降级实证（CImg 家族显示后端禁用）
+- `pc-knowledge-base` [[鸿蒙PC-图像处理库-CImg图像库交叉编译]] §2.3（某图像库 实证）
+- **E005**: 编译时头文件缺依赖的同类问题（但 E005 是 X11 以外的缺失）

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

@@ -0,0 +1,82 @@
+<!-- 来源：new/PC libetpan 适配实证（2026-09-08） | 原编号 E143 -->
+> 一句话定位：Windows 宿主 DevEco 默认装 Program Files，NDK 的 `aarch64-unknown-linux-ohos-clang` 封装脚本 `exec $SOURCE/clang` 未加引号→路径在空格处断裂→configure 报 C compiler cannot create executables。
+
+# L020: NDK 目标封装脚本在带空格安装路径下失效（Windows 宿主）
+
+> **严重度**: 3 blocking | **领域**: host-tooling/cross-compile | **自动修复**: none
+
+---
+
+## 报错现场
+
+```
+$ ./configure --host=aarch64-unknown-linux-ohos
+...
+checking for aarch64-unknown-linux-ohos-clang... /c/Program Files/.../llvm/bin/aarch64-unknown-linux-ohos-clang
+checking whether the C compiler works... no
+configure: error: C compiler cannot create executables
+```
+
+**config.log 关键行**：
+```
+configure:3771: /c/Program Files/.../aarch64-unknown-linux-ohos-clang ...
+/c/Program: No such file or directory          ← 空格处断裂！
+```
+
+## 根因
+
+DevEco Studio 默认安装路径含空格：`C:\Program Files\Huawei\DevEco Studio\...`。
+
+NDK 提供的 `llvm/bin/aarch64-unknown-linux-ohos-clang` 封装脚本（Windows 上是 `.bat`/`.cmd` 或 shell 脚本）在执行 `exec $SOURCE/clang` 时**未给 `$SOURCE` 加引号**，导致 `$SOURCE` 展开为带空格的路径时，被 shell 拆成两个参数——`/c/Program` 被当作命令名，`Files/...` 成为它的第一个参数，自然找不到。
+
+这不是传统 autotools 的 `cannot create executables`（E001/E082 的「cc not found」或「gnulib 检测 stdbool 失败」），而是封装脚本自身的 shell 引用缺陷——**换一个 NDK 版本或换一个宿主 shell 不会自愈**。
+
+## 判别方法
+
+1. 现象：`configure: error: C compiler cannot create executables`（同 E001/E082）
+2. 打开 `config.log`，找到 `configure:xxxx: ... -o conftest` 行，看编译器路径是否在空格处断裂
+3. 确认 NDK 路径含空格：`echo $NDK` 或 `ls "C:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\native"`
+4. 确认 NDK 封装脚本存在且未加引号：`cat "$(which aarch64-unknown-linux-ohos-clang)"` 看 `exec $SOURCE/clang` 行
+
+**与 E001/E082 的区分**：
+- E001：`cc` 二进制根本不在 PATH 上或未安装——`which clang` 返回空
+- E082：gnulib 的 stdbool 检测第二次运行 conftest 时因缓存自相矛盾——与路径空格无关
+- E143：`which clang` 能命中，但 shell 把路径拆碎导致 `exec` 失败
+
+## 解决方案
+
+**自建引号封装脚本**，放在无空格的路径下（如 `build/toolchain/aarch64-ohos-clang`），内容：
+
+```bash
+#! /bin/sh
+# 替代 NDK 官方封装：引号形式复刻语义
+exec "$NDK/llvm/bin/clang" -target aarch64-linux-ohos --sysroot="$NDK/sysroot" -D__MUSL__ "$@"
+```
+
+其中 `$NDK` 是 OHOS NDK 根目录（`$DEVECO_SDK_HOME/default/openharmony/native`）。
+
+配置时：
+```bash
+export CC="$WORKSPACE/build/toolchain/aarch64-ohos-clang"
+export CXX="$WORKSPACE/build/toolchain/aarch64-ohos-clang++"
+# 对 CXX 同理
+```
+
+**注意**：8.3 短路径（`C:\PROGRA~1\...`）只对部分 MSYS2 场景有效，跨工具链（autotools / CMake / meson 混合场景）不可靠——一律用封装脚本。
+
+## 影响范围
+
+所有在 Windows 宿主上交叉编译 OHOS 的 autotools 项目，且 DevEco 安装在默认路径（含空格）。macOS/Linux 宿主不受影响。
+
+**meson 场景同样受影响**（2026-09-17 更正，此前本节误写「不受影响」）：cross-file 的 `[binaries] c/cpp` 若指向 NDK 官方封装脚本，一样在空格处断裂（meson setup 报 `C compiler cannot create executables`）。落地形态是自建 **.cmd 引号封装**（内容形如 `"C:\Program Files\Huawei\DevEco Studio\sdk\...\clang.exe" -target aarch64-linux-ohos --sysroot=... -D__MUSL__ %*`），cross-file 指向该 .cmd；`llvm-ar`/`ranlib`/`strip` 直接指 `.exe` 全路径不受影响。usbredir 0.15.0 全量 meson 编译 23 目标零错误实证。只有 CMake 项目经 `CMAKE_C_COMPILER` 直指 clang 二进制（带引号）才不经过封装脚本。
+
+## 关联
+
+- E001：`C compiler cannot create executables`（cc not found，根因不同）
+- E082：gnulib stdbool 检测导致的 `cannot create executables`（根因不同）
+- E133：Windows 宿主编码纪律（同为 Windows 宿主侧工具链问题）
+- `pc-knowledge-base/adaptation/鸿蒙PC-Windows宿主构建环境四坑.md`（宿主编译环境总览，含本坑）
+
+## 实证
+
+libetpan 适配（2026-09）：NDK 官方封装脚本失效。自建 `build/toolchain/aarch64-linux-ohos-clang` 引号封装后，`configure` 通过，`make -j8` 编译出 `libetpan.so.26`（aarch64 + .codesign）。

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

@@ -0,0 +1,104 @@
+<!-- 来源：new/PC mpg123 适配实证（2026-09-09） | 原编号 E144 -->
+> 一句话定位：Windows cmd 批处理中 `set "VAR=--flag="%OTHER_VAR%""` 的嵌套引号在 `%VAR%` 展开时，外层 `set "..."` 将内层引号视为字面值，导致 clang 报 `no input files`——所有参数被当作一个参数传给 clang，源文件路径被忽略。
+
+# L021: cmd `set "VAR=..."` 嵌套引号导致编译参数断裂（Windows 宿主）
+
+> **严重度**: 3 blocking | **领域**: host-tooling/build-script | **自动修复**: none（改用内联 flags）
+
+---
+
+## 报错现场
+
+```
+=== Compiling generated test programs ===
+-- test_mpg123_feeder --
+clang: error: no input files
+test_mpg123_feeder FAILED
+-- test_mpg123_format --
+clang: error: no input files
+test_mpg123_format FAILED
+...
+=== Checking results ===
+<dist/testbins/> 目录下旧文件还在，新编译的未生成。
+```
+
+所有编译命令全部失败，无一例外，且都是 `no input files`——不是特定某个源文件的问题。
+
+## 根因
+
+`build_tests.cmd` 中用 `set "BASE_CFLAGS=..."` 变量暂存公共编译参数，内层引号被外层 `set "..."` 语法吞掉为字面值：
+
+```cmd
+set "BASE_CFLAGS=--target=aarch64-linux-ohos --sysroot="%SYSROOT%" -D__MUSL__ ..."
+```
+
+当 `%SYSROOT%` 展开为 `C:\Program Files\Huawei\...\sysroot` 时，`set "..."` 把整个 `--target=... --sysroot="C:\Program Files\..."` 当作一个字符串存入变量。但外层 `set "..."` 的引号界定符已经被 SYSROOT 路径中的空格打断——实际存入的是 `BASE_CFLAGS=--target=... --sysroot="C:\Program`，`Files\...` 被当作下一个命令。
+
+当后来用 `"%CLANG%" %BASE_CFLAGS% -o "%DIST%\test.exe" "%WS%\source\src\tests\test.c" %BASE_LDFLAGS%` 展开时，`%BASE_CFLAGS%` 的内容被 cmd 再次拆词，嵌套引号碎裂，导致 clang 收到的参数序列中**源文件路径丢失**，clang 报 `no input files`。
+
+**cmd 的 `set "VAR=value"` 语法规则**：
+- 外层双引号只是语法界定符，用来保护值中的特殊字符（空格、`&`、`|` 等）
+- 值内部的双引号被当作**字面字符**存入变量，不是语法引号
+- 展开时字面引号不参与参数解析，不会被 cmd 当作参数分界
+
+## 判别方法
+
+1. 现象：cmd 批处理中所有 clang 命令都报 `no input files`
+2. 确认使用了 `set "BASE_CFLAGS=...%SYSROOT%..."` 且 `%SYSROOT%` 含空格
+3. 对比：用内联 flags（不经过变量）的编译命令能正常执行
+4. 在 `set "BASE_CFLAGS=..."` 行后加 `echo %BASE_CFLAGS%` 观察展开结果——含空格路径的字面引号是否碎裂
+
+**与 E001/E082/E143 的区分**：
+- E001：`cc` 二进制不在 PATH 上——`which clang` 返回空
+- E082：gnulib stdbool 检测自相矛盾——与路径空格无关
+- E143：NDK 封装脚本 `exec $SOURCE/clang` 缺引号——shell 执行 `clang` 时报错，不是 clang 自己报 no input files
+- **E144**：clang 找到了但参数断裂导致源文件丢失——**`config.log` 中 clang 命令完整但缺少源文件路径**
+
+## 解决方案
+
+### 方案 A（推荐）：内联 flags，不使用中间变量
+
+借鉴 `build_missing_tests.cmd` 已验证的写法，每条编译命令直接写完整 flags：
+
+```cmd
+"%CLANG%" --target=aarch64-linux-ohos --sysroot="%SYSROOT%" -D__MUSL__ -DHAVE_CONFIG_H -I"%WS%\build\cmake-build\src" ... -o "%DIST%\test.exe" "%WS%\source\src\tests\test.c" -L"%WS%\dist\lib" -lmpg123 -lm -Wl,--code-sign
+```
+
+优点：每条命令独立，没有变量展开的嵌套引号问题。缺点：重复编写，但可以通过复制粘贴减少工作量。
+
+### 方案 B：用 `set VAR=value`（不加外层引号）
+
+```cmd
+set BASE_CFLAGS=--target=aarch64-linux-ohos --sysroot="%SYSROOT%" -D__MUSL__ -DHAVE_CONFIG_H -I"%WS%\build\cmake-build\src" ...
+```
+
+注意：`set VAR=value`（不加外层引号）对值中的空格敏感，但嵌套引号是字面有效的。风险是值中的 `&`、`|`、`>`、`<` 等特殊字符会被 cmd 解释。如果确定 flags 中没有这些字符可以用。
+
+### 方案 C：PowerShell 替代
+
+PowerShell 的引用规则更一致，不存在这个嵌套引号问题：
+
+```powershell
+$BASE_CFLAGS = '--target=aarch64-linux-ohos --sysroot="' + $env:SYSROOT + '" -D__MUSL__ ...'
+& $CLANG $BASE_CFLAGS -o "$DIST\test.exe" "$WS\source\src\tests\test.c" $BASE_LDFLAGS
+```
+
+## 影响范围
+
+所有在 Windows 宿主上编写 cmd 批处理编译脚本的适配项目，且：
+1. 使用 `set "VAR=...%PATH_WITH_SPACES%..."` 模式
+2. 路径变量含空格（如 `C:\Program Files\...`）
+3. 编译参数中需要嵌套引号传递含空格的路径
+
+macOS/Linux 宿主的 bash 脚本通过 `$VAR` 展开 + 双引号保护（`"$VAR"`）没有此问题。
+
+## 实证
+
+mpg123 适配（2026-09）：`build/build_tests.cmd` 使用 `set "BASE_CFLAGS=--sysroot="%SYSROOT%""` 导致所有 30 条编译命令全部报 `no input files`。`build/build_missing_tests.cmd` 使用内联 flags（无中间变量）正常编译。修复后 33 个测试二进制全部成功编译，带上 `.codesign` 段。
+
+## 关联
+
+- E143：NDK 封装脚本在带空格安装路径下失效（同为 Windows 宿主路径空格问题）
+- E132：Windows 宿主编码纪律（同为 Windows 宿主侧工具链问题）
+- E133：Windows 宿主构建环境四坑
+- `pc-knowledge-base/adaptation/鸿蒙PC-Windows宿主构建环境四坑.md`

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

@@ -0,0 +1,57 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E145.md | 原编号 E145 -->
+> 一句话定位：conan 中心仓 glib 鸿蒙包未打包 gio 的 Unix 专有头 `gunixinputstream.h` / `gunixoutputstream.h`，上游 #include 了但实际没调用相关符号 → 编译报 `No such file or directory`。先确认符号是否真被用，未用则直接移除 include。
+
+# L022: glib conan 包缺失 Unix 专有头（gio/gunixinputstream.h、gunixoutputstream.h）
+
+> **严重度**: 2 major | **领域**: dependency/package | **自动修复**: none（移除未用 include）
+
+---
+
+## 报错现场
+
+```
+../source/tools/usbredirect.c:NN:10: fatal error: 'gio/gunixinputstream.h' file not found
+#include <gio/gunixinputstream.h>
+         ^~~~~~~~~~~~~~~~~~~~~~~~~
+```
+
+或 `gio/gunixoutputstream.h` 同理。交叉编译（Windows 宿主 → OHOS aarch64）用 `PKG_CONFIG_PATH`/Conan 缓存里的 glib 头目录时触发。
+
+## 根因
+
+conan 中心仓的 glib/2.88.3 鸿蒙包**没有打包 gio 下的 Unix 专有头** `gunixinputstream.h` / `gunixoutputstream.h`（`g_unix_input_stream_new` / `g_unix_output_stream_new` 是 Unix/管道 fd 专用 API，glib 包裁剪时把对应的 Unix 头剔了）。上游源码 `#include` 了这两个头，但**实际代码里并没有调用**相关符号——属于历史遗留的冗余 include。
+
+这与「库真需要该符号」是两种性质：前者删 include 零功能影响，后者才需要补头或换鸿蒙等效 API。
+
+## 判别方法
+
+1. 现象：交叉编译报 `gio/gunixinputstream.h: No such file or directory`（unixoutputstream 同理）
+2. 确认头确实不在 deps/glib 的 include 目录：`ls deps/glib-*/dist/include/glib-2.0/gio/ | grep -i unix`，应只有 `gunix*.h` 之外的文件（unix 专有头被裁掉）
+3. **关键**：源码里 `grep -n 'g_unix_input_stream\|g_unix_output_stream'` 确认是否真的调用了符号——没调用 = 删 include 即可；有调用 = 需补头文件或改鸿蒙等效 API（不适用本条目）
+
+**与同类头缺失的区分**：E114/E110 等是 sysroot/libc 头缺失（musl）、E140/E141 是 pkg-config/conan 配置问题；本条是**三方 conan 包自身裁剪头文件**导致的「include 了但没符号」。
+
+## 解决方案
+
+### 方案 A（首选）：移除未实际使用的 include
+
+确认符号没被调用后，直接删除 `#include <gio/gunixinputstream.h>` 与 `#include <gio/gunixoutputstream.h>` 两行。零功能影响。
+
+### 方案 B：库确实需要该符号时
+
+- 从同版本 glib 源码补那两份头（`gio/gunixinputstream.h`/`gunixoutputstream.h`）进 conan 缓存 include 目录；或
+- 改用鸿蒙等效 API（若只是读写 fd，用 `read/write/poll` 原语替代 `GInputStream` 封装）。
+
+## 影响范围
+
+所有以中心仓（conan）glib/2.88.x 作为依赖、且上游源码又 `#include` 了 gio 下 Unix 专有头（`gunix*.h`）的 C/C++ 库交叉编译场景。glib 包裁剪头文件是包本身的形态，**任何拉同一份 glib conan 包的库都会撞**，不是 usbredir 独有。
+
+## 关联
+
+- E136：meson `run_command('test')` Windows 宿主无 test 命令（同为 usbredir 交叉编译语境）
+- E143：NDK 封装脚本空格路径失败（同为 Windows 宿主交叉编译）
+- `pc-knowledge-base/adaptation/鸿蒙PC-usbredir-USB重定向工具降级适配.md`
+
+## 实证
+
+usbredir 0.15.0（2026-09）：`source/tools/usbredirect.c` include `gio/gunixinputstream.h` + `gio/gunixoutputstream.h`，实际未调用对应符号。移除两行后交叉编译通过，`usbredirect` 正常运行（含 .codesign 签名段）。

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

@@ -0,0 +1,90 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E146.md | 原编号 E146 --> 一句话定位：OHOS NDK clang 15 前端对「带**模板模板参数**的 concept 约束 `auto` 形参」（如 `Is_specialization<std::basic_string> auto &out`）直接 ICE（0xC0000005 段错误、含 stack dump、-O0 亦复现）；同一 concept 写成 `template <typename T> requires Concept<T, TT>` 即可通过。plain `Concept auto` 与带类型实参的 `Concept<int> auto` 均不触发。
+
+# L023: clang 15 前端 ICE —— concept 带模板模板实参的约束 auto 形参
+
+## 问题现象
+
+交叉编译使用 C++20 concepts 的代码时，编译器**崩溃**而非报错：
+
+```
+PLEASE submit a bug report to https://github.com/llvm/llvm-project/issues/ ...
+1.  some_header.h:152:64: current parser token ')'
+2.  some_header.h:42:1: parsing namespace 'mysql'
+Exception Code: 0xC0000005
+Stack dump: ...
+clang++: error: clang frontend command failed due to signal (use -v to see invocation)
+```
+
+**解析期崩溃**（parser token 停在 `)`），与优化级别无关（-O0 复现），无诊断信息指向真实原因。
+
+## 根因分析
+
+clang ≤15 前端对「约束 `auto` 形参的 concept 实参列表中含**模板模板实参**」这一语法形态存在解析崩溃：
+
+```cpp
+template <class Test, template <typename...> class Primary>
+concept Is_specialization = ...;
+
+// 💥 ICE：constraint 带模板模板实参 std::basic_string
+void f(Is_specialization<std::basic_string> auto &out);
+```
+
+实测三变体（OHOS NDK clang 15.0.4，-std=gnu++2b）：
+
+| 写法 | 结果 |
+|---|---|
+| `void f(Concept auto &x)`（无实参） | ✅ 通过 |
+| `void f(Concept<int> auto &x)`（类型实参） | ✅ 通过 |
+| `void f(Concept<TT> auto &x)`（**模板模板实参**） | 💥 ICE |
+| `template <typename T> requires Concept<T, TT> void f(T &x)` | ✅ 通过 |
+| `template <Concept<TT> T> void f(const T &x)`（约束模板类型形参） | ✅ 通过 |
+
+MySQL 26.7 实证触发点：`libs/mysql/strconv/decode/decode.h:152`、`encode/encode.h:227`、`conv/hex_basic.h:52/75`、`conv/escaped_basic.h:42`（`Is_specialization` / `Is_nontype_specialization` 共 5 处函数签名），任何包含这些头的 TU 全灭。
+
+## 解决方案
+
+把约束 `auto` 形参改写为**模板头 + requires 子句**，语义完全等价、重载决议行为不变（约束模板仍优先于无约束缩写模板）：
+
+```cpp
+// 改前（ICE）
+[[nodiscard]] Parser decode(const Is_parse_options_nocheck auto &opt,
+                            const std::string_view &in_sv,
+                            mysql::meta::Is_specialization<std::basic_string> auto &out);
+
+// 改后（通过）
+template <typename String_t>
+  requires mysql::meta::Is_specialization<String_t, std::basic_string>
+[[nodiscard]] Parser decode(const Is_parse_options_nocheck auto &opt,
+                            const std::string_view &in_sv, String_t &out);
+```
+
+已有模板头的函数直接在模板参数列表追加类型形参并加 requires 子句即可。
+
+## 适用范围
+
+- OHOS NDK clang 15（以及任何 clang ≤15）上编译使用 C++20 concepts 的项目
+- 判定特征：`clang frontend command failed due to signal` + stack dump 中 `current parser token ')'` 指向某个 `Concept<模板名> auto` 形参
+
+## 实例
+
+### MySQL 26.7
+
+5 处签名改写后，原 ICE 的 `mysql/gtids/gtids.h` 通过 `-fsyntax-only`；构建从 [10/564] sql_main 死点继续推进。
+
+## 关联知识
+
+- E147：libc++ 15 ranges 门控（同为 clang/libc++ 15 时代缺陷，症状是普通报错而非崩溃）
+- E148：clang 15 的 C++20 缺口组（P0960/P0634/CRTP 约束缓存/libc++ 裁剪）
+- `pc-knowledge-base/adaptation/鸿蒙PC-OHOS-NDK-clang15-C++新特性兼容缺口清单.md`
+
+## 注意事项
+
+1. 先确认崩溃点在「解析期」（stack dump 有 `current parser token`）， codegen 期崩溃是另一类问题
+2. 不要用「升级编译器」当唯一出路——requires 子句改写是源码级绕过，且对上游可接受（C++20 合法写法）
+3. 改完用 `-fsyntax-only` 对包含该头的最小 TU 验证，不必整树构建
+
+---
+
+**发现于**: mysql-server 26.7.0 Innovation（commit 23e360a7）  
+**日期**: 2026-09-10  
+**贡献者**: OHPT pc-adapter

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

@@ -0,0 +1,70 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E147.md | 原编号 E147 --> 一句话定位：OHOS NDK libc++ 15 把整个 C++20 ranges 算法族标为 incomplete 并默认门控（`_LIBCPP_HAS_NO_INCOMPLETE_RANGES`），报 `no member named 'none_of' in namespace 'std::ranges'`——实现完整存在，一行 `-D_LIBCPP_ENABLE_EXPERIMENTAL` 全局解锁，**不要逐个改源码、不要急着升级 NDK**。
+
+# L024: std::ranges 算法报 no member named —— libc++ 15 门控需 -D_LIBCPP_ENABLE_EXPERIMENTAL
+
+## 问题现象
+
+编译使用 C++20 ranges 算法的代码时报：
+
+```
+error: no member named 'none_of' in namespace 'std::ranges'
+error: no member named 'any_of' in namespace 'std::ranges'
+error: no member named 'sort' in namespace 'std::ranges'
+...
+```
+
+涉及算法可达 ~40 种（none_of/any_of/all_of/sort/find_if/contains/lower_bound/minmax…）。
+
+## 根因分析
+
+OHOS NDK libc++ 15 的 `__algorithm/ranges_*.h` 里这些算法**实现完整存在**，但被 `__config` 默认定义的 `_LIBCPP_HAS_NO_INCOMPLETE_RANGES` 整体门控（头文件内 `#ifndef _LIBCPP_HAS_NO_INCOMPLETE_RANGES` 包裹）。报错样式具有强误导性，看起来像是「编译器不支持 C++20 ranges」，实际只是门控。
+
+与 E146（前端 ICE）必须区分：**ranges 报错是普通诊断、标志可解；concepts ICE 是编译器崩溃、标志无解**（后者改写法，见 E146）。
+
+## 解决方案
+
+在工具链文件全局追加（不要逐目标、不要改源码）：
+
+```cmake
+# ohos.toolchain.cmake
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -D_LIBCPP_ENABLE_EXPERIMENTAL ...")
+```
+
+最小验证用例（MySQL 案实证，加标志前后对照）：
+
+```cpp
+#include <algorithm>
+#include <vector>
+bool f(const std::vector<int> &v) {
+  return std::ranges::none_of(v, [](int x) { return x < 0; });
+}
+```
+
+## 适用范围
+
+- OHOS NDK clang 15 / libc++ 15 上编译任何使用 C++20/23 ranges 的 C++ 项目
+- 判定特征：`no member named '<算法>' in namespace 'std::ranges'`，且 NDK 头里能 grep 到 `__algorithm/ranges_<算法>.h`
+
+## 实例
+
+### MySQL 26.7
+
+不加标志：`make_join_hypergraph.h:158` 等报 `no member named 'none_of'`；全源码另有 ~40 种算法被同一门控卡住。加 `-D_LIBCPP_ENABLE_EXPERIMENTAL` 后全部解锁（`build/test_ranges.o` 实证）。
+
+## 关联知识
+
+- E146：clang 15 concepts ICE（区分「报错」与「崩溃」）
+- E148：clang 15 的 C++20 缺口组
+- `pc-knowledge-base/adaptation/鸿蒙PC-OHOS-NDK-clang15-C++新特性兼容缺口清单.md`
+
+## 注意事项
+
+1. 一旦某个 ranges 算法报 no member，**全源码 grep `std::ranges::` 统计算法种数**，确认规模后直接上标志，逐个改写成 `std::` 版不可行且污染上游
+2. 该标志同时解锁 libc++ 其它 experimental 门控，属预期副作用
+3. 验收/根因记录里别把这类门控误诊为「NDK 不支持 C++20 ranges 需升级 NDK」
+
+---
+
+**发现于**: mysql-server 26.7.0 Innovation（commit 23e360a7）  
+**日期**: 2026-09-10  
+**贡献者**: OHPT pc-adapter

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

@@ -0,0 +1,62 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E148.md | 原编号 E148 --> 一句话定位：OHOS NDK clang/libc++ 15 缺 C++20 的 P0960（聚合括号初始化）与 P0634（typename 可选语境）实现，libc++ 被裁剪（无 `<source_location>`、无 `string_view::operator<=>`），且 CRTP 基类的约束成员函数在派生类不完整时被提前求值并缓存错误结果——五类缺口症状各异，均有机械修法，不要因此误判「项目不可适配」。
+
+# L025: clang 15 的 C++20 缺口组（P0960 / P0634 / CRTP 约束缓存 / libc++ 裁剪）
+
+## 问题现象
+
+大型 C++20/23 项目在 OHOS NDK clang 15.0.4 上出现成组的、上游在 clang 17+/GCC 11+ 下完全正常的编译错误：
+
+```
+error: no matching conversion for functional-style cast from 'const Repeat' to 'Compound_parse_options<...>'
+error: missing 'typename' prior to dependent type name 'Set_traits_t::Element_t'
+error: fatal error: 'source_location' file not found
+error: invalid operands to binary expression ('std::string_view' and 'std::string_view')
+error: because '--__i' would be invalid: cannot decrement value of type 'It'   // It 明明有 prev()
+```
+
+## 根因分析
+
+五个独立缺口的对照表（全部实测于 OHOS NDK clang 15.0.4 + libcxx-ohos 15）：
+
+| # | 缺口 | 症状 | 修法 |
+|---|---|---|---|
+| 1 | **P0960 聚合括号初始化未实现**（clang 16 才落地） | `Agg(expr)` 函数式转换报 "no matching conversion"，候选只剩隐式 copy/move ctor | 改花括号聚合初始化；成员是 `std::tuple` 等 explicit ctor 类型时先显式构造：`Agg{std::tuple<T>(expr)}` |
+| 2 | **P0634「Down with typename」未实现** | 模板内 `using X = Dep::Type;` 报 missing 'typename' | 逐个补 `typename`（机械 sed 级修改） |
+| 3 | **CRTP 基类约束成员被提前求值并缓存** | 派生类明明有 `prev()`，概念检查却报 "no member named 'prev'"、约束成员（如 `operator--`）不可用 | 把基类成员函数改成**带默认模板形参的函数模板**：`template <typename S = Self_t> requires Has_member_prev<S> Self_t &operator--()`，约束延迟到调用点（派生类已完整）求值 |
+| 4 | **libc++ 裁剪：无 `<source_location>`** | fatal error: 'source_location' file not found | 用 `__has_include(<source_location>)` 守卫 + 返回默认值的兜底类（调试/定位用途，功能无损） |
+| 5 | **libc++ 裁剪：`string_view` 无 `operator<=>`** | invalid operands to binary expression (string_view, string_view) | `a.compare(b) <=> 0` 等价改写 |
+
+缺口 1/2/5 报错信息指向明确；**缺口 3 最阴险**：症状（`--i would be invalid`）与真实原因（约束缓存）完全脱节，且同基类的无约束成员（`operator++`）正常，极易误诊为迭代器实现缺陷。
+
+## 解决方案
+
+按上表逐类机械修复。排查顺序建议：先 `grep` 全源码统计缺口 2 的规模（通常几十处，脚本批量补），再处理 1（数量少），3 只有在概念/static_assert 诡异失败时才怀疑（判定特征：成员明明存在却报 no member），4/5 各一处兜底即可。
+
+## 适用范围
+
+- OHOS NDK clang 15 / libc++ 15 上编译 C++20/23 重度项目（MySQL 26.7 实证：sets/gtids/strconv 库 ~20 处 typename + 3 处聚合初始化 + 2 个 CRTP 接口基类 + 2 处 libc++ 裁剪）
+- 上游官方编译器要求 clang 17+/GCC 11+ 的项目，在更低版本工具链上收口时的典型落差面
+
+## 实例
+
+### MySQL 26.7
+
+`mysql/sets`、`mysql/gtids`、`mysql/strconv` 三库共修复：22 处补 typename、4 处聚合初始化改花括号（parse_options.h 的 3 个 make_compound_parse_options + operator| 的 CTAD）、`Iterator_interface`/`Collection_interface` 两个 CRTP 基类 13 个约束成员改函数模板、text_source_location.h 加 `__has_include` 兜底、buffer_interface.h 的 `<=>` 改 compare。全部修完后 `mysql/gtids/gtids.h`、`mysql/strconv/strconv.h` 通过 `-fsyntax-only`。
+
+## 关联知识
+
+- E146：clang 15 concepts 约束 auto 带模板模板实参 ICE（同属 clang 15 缺口，但症状是崩溃）
+- E147：libc++ 15 ranges 门控
+- `pc-knowledge-base/adaptation/鸿蒙PC-OHOS-NDK-clang15-C++新特性兼容缺口清单.md`
+
+## 注意事项
+
+1. 缺口 3 修法改变了基类成员的「模板性」，重载决议语义不变，但补丁要能向上游解释清楚动机
+2. 缺口 4 的兜底类只返回空串/0——若项目把 source_location 用于**功能性**逻辑（而非调试信息），需另行评估
+3. 遇到上游要求 clang 17+ 的项目，先用本表对照评估工作量，再决定「源码降级」还是「等 NDK 升级」
+
+---
+
+**发现于**: mysql-server 26.7.0 Innovation（commit 23e360a7）  
+**日期**: 2026-09-10  
+**贡献者**: OHPT pc-adapter

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

@@ -0,0 +1,76 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E149.md | 原编号 E149 --> 一句话定位：demo 验证阶段（测试线阶段 6）生成的 NAPI stub 在给上游音频 API 接线时，枚举参数传了非法值（0）、或把「浮点-only」的 DSP API 用在整型上、或跨用例泄漏/重复调用 out123 模块遍历——症状是 API 返回错误码/默认值、甚至进程崩溃，全部长得像「库 bug」，实为 **harness 接线错（harness-defect）**，改 stub 不改库。
+
+# L026: demo 验证接线错——API 枚举/编码参数与模块生命周期（harness-defect）
+
+> **严重度**: 2 major | **领域**: test/contract + audio | **自动修复**: none（改 demo stub，不动库；依据回指上游头文件签名）
+
+---
+
+## 问题现象
+
+demo 验证阶段（`napi_stub.cpp` 接线）三种典型症状，共同点是**报在 stub 侧、根因在 stub 侧**，库本身没错：
+
+1. **枚举参数传了非法值**——`mpg123_eq2` 返回 -1，`mpg123_geteq2` 恒返回默认 1.0：
+
+```
+OHPTCASE: check id=F-05-01 cp=0 ok=0 expect=eq set ok actual=rc=-1
+OHPTCASE: check id=F-05-01 cp=1 ok=0 expect=eq get ~2.0 actual=val=1.000000
+```
+
+2. **把「浮点-only」DSP API 用在整型编码上**——`syn123_amp` 返回 3、`syn123_clip` 返回 0：
+
+```
+OHPTCASE: check id=F-07-04 cp=1 ok=0 expect=amp halved amplitude actual=rc=3
+OHPTCASE: check id=F-07-04 cp=3 ok=0 expect=clip processed all samples actual=clipped=0
+```
+
+3. **跨用例泄漏/重复调用模块遍历**——进程崩溃，后续用例全 not-run：
+
+```
+sceneboard/SCBMain: on sessionException errorReason: onAbilityDied
+CPP_CRASH（hiview RELIABILITY 事件）
+```
+
+## 根因
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| 1 | `mpg123_eq2` 返回 -1，`geteq2` 恒返回默认值 | `channel` 传了 `0`。mpg123 只接受 `MPG123_LEFT=0x1 / MPG123_RIGHT=0x2 / MPG123_LR=0x3`，`0` 走 switch `default` → `MPG123_ERR(-1)`；查询侧 channel 不命中同样返回默认 `1.0` | channel 用 `MPG123_LEFT`（0x1），band 仍 0–31 |
+| 2 | `syn123_amp` 返回 3、`syn123_clip` 返回 0 | `syn123_amp/clip` 只在 `MPG123_ENC_FLOAT_32(0x200)/FLOAT_64` 上直接生效；整型编码需 `syn123_handle` 内部转浮点，无 handle 时 amp 返回 `SYN123_BAD_ENC(3)`、clip 整型是 no-op 返 0 | 用 float32 缓冲直测，或传 syn123_handle |
+| 3 | 进程 CPP_CRASH，后续用例 not-run | `out123_open` 只装载模块、**不启动 renderer**（`out123_start` 才启）；demo 里开而不收（跳 close/del 泄漏句柄）累积模块状态，后续用例再调 `out123_drivers` 遍历模块列表时崩溃 | 别跨用例重复调 out123 模块遍历（库级驱动列表一次即可）；别泄漏开过的 out123 句柄 |
+
+**不变量**：三类都属于「改评判标准」之外、但又**改测试侧不改库**的 harness-defect——修 `napi_stub.cpp` 接线，依据必须给得出 `file:line` 且真在盘（回指上游 `mpg123.h`/`syn123.h`/`libout123` 头文件签名与实现），不触碰库的任何返回码契约。与 E139（断言/参数类型 testcase-defect）同门但不完全同：E139 是**改 test 用例的预期/入参类型**，本条是**改 demo stub 的接线方式**。
+
+## 判别方法
+
+1. 报错点在 **demo stub（napi_stub.cpp）** 内部，不在库函数入口（E137 才在库入口）；
+2. 该 API 的「正确用法」能在上游头文件/实现里找到权威定义（枚举值、编码语义、模块装载流程）；
+3. 改成与上游契约一致后，用例转 PASS 且不触碰库的返回码断言。
+
+三条全中 → 归因 harness-defect，改 stub，不是库 bug。
+
+## 解决方案
+
+1. **枚举参数**：接线前查头文件的 enum/宏定义，别用 `0` 占位。带 channel/flag/band 的 API 尤其高发（mpg123 eq、out123 flags、aLibX 各类 bitmask）。
+2. **浮点-only DSP**：sampleconv/amp/clip/gain 类 API 常只在浮点编码上直接工作，整型编码需 handle 做 on-the-fly 转换。测这类 API 优先用 float32 缓冲（`0x200`）最稳。
+3. **模块生命周期**：自带 module-loader 的库（out123 的 `mpg123_module_t` 等），模块「装载」与「启动」是两回事（`out123_open` vs `out123_start`）；demo 里开过的句柄要么正确 drain/close/del，要么干脆别在 library 壳里重复触发模块遍历（CLI 级验证归 cli-runner）。
+
+## 影响范围
+
+所有「demo 验证阶段给上游音频/多媒体 API 接线」的场景。高频于：mpg123/libout123/libsyn123 一族（eq/volume/amp/clip/resample）、任何带枚举 channel/format 参数的 C API、任何自带输出后端 loader 的库（libao/SDL/gstreamer/OpenAL-Soft）。
+
+## 关联
+
+- E139：assertion/参数类型 testcase-defect（同为「改测试侧不改库」，分界见上）
+- E137：NULL 入参 SIGSEGV（库 bug，加守卫；与本文档 SIGSEGV 区分：崩溃栈在库入口还是 stub）
+- `pc-capability-domains/references/solutions/ohaudio-backend/` —— out123/OHAudio 模块装载的权威方案（loader 形状 + 编译命令 + 四证判据）
+- 机制：验收规则 `testcase-amendment-evidenced`（改评判标准须机器管起来、留痕）
+
+## 实证
+
+mpg123 适配 demo 验证阶段（2026-09-10）三处 harness-defect：
+
+1. `napi_stub.cpp` 的 `case_F_05_01` 用 `_mpg123_eq2(mh, 0, 0, 2.0)`（channel=0）→ -1；改 `MPG123_LEFT(0x1)` 后 `eq2` 返 0、`geteq2` 返 2.0/0.0，判定点全过。依据 `source/src/include/mpg123.h:1334-1349` 枚举 + `libmpg123.c:476-495` 的 switch default。
+2. `case_F_07_04` 用 `_syn123_amp(整型, 0x0d0, ..., NULL)` → SYN123_BAD_ENC(3)；改 float32 缓冲（`0x200`）+ 修正 clip 断言（整型 no-op 返 0，改用越界 float 输入断言 `clipped==2`）后全过。依据 `syn123.h:555-572` + `libsyn123/volume.c:69-139` / `sampleconv.c:120-146`。
+3. `case_F_08_03` 在泄漏的 out123 句柄之上再次 `out123_drivers` 遍历模块列表 → 进程 onAbilityDied，F-09 三条 not-run；主壳删除冗余 out123 调用（库级驱动列表已由 F-06-02 覆盖，CLI 级归 cli-runner）后 F-09 恢复执行。依据 `libout123/libout123.c:409-494`（open 不启 renderer）与 `537-588`（start 才启）。
+4. 测试线阶段 6（2026-09-21）「输入源模式选错」假绿：demo 用 `mpg123_open_feed`（流式喂内嵌 sweep.mp3）验证基于**可寻址文件**的 API——`seek_frame(500)`/`mpg123_scan`/`mpg123_tellframe` 在 feed 模式下固定返回 -1（无可 seek 的 reader），demo 却以「调用无崩溃、行为明确（rc=-1）」判 pass，F-04-02 等 5 条全假绿。根因：checkpoint 要的是「成功后的精确状态」（帧号==500、索引可用），不是「调用不崩」；「返回 -1 但没崩」= 输入源模式与 API 语义不匹配导致行为根本没发生。修法：可寻址 API 走 `mpg123_open_fixed`（app 沙箱内真实文件），seek_frame 返 500/tellframe=500、scan rc=0 index fill=520 真实通过。配套两坑：① 拼接 MP3 帧做长流夹具时首帧是 Xing/VBR 头（声明固定帧数），跳过它才能真正拼出 >500 帧长流，否则 mpg123 仍只报 40 帧、seek_frame(500) 假过；② `syn123_query_waves` 注册波形前调用返回 SYN123_NO_DATA（仅 1 条），先 `setup_waves` 注册再 query。依据 `mpg123.h`（open_feed/open_fixed 语义）+ `libmpg123/readers.c`（feed 无可 seek 路径）。