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

@@ -0,0 +1,44 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E027: libintl_gettext 链接失败
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: linking, nls | **自动修复**: ✅ reconfigure
+
+---
+
+## 错误特征
+
+```
+undefined symbol.*libintl_gettext
+undefined symbol.*libintl_bindtextdomain
+libintl.*not found
+-lintl.*undefined
+```
+
+## 根因
+
+GNU 软件默认启用 NLS(Native Language Support)国际化,
+依赖 libintl(gettext 库), 鸿蒙系统未预装该库
+
+## 验证命令
+
+```bash
+grep -r "LIBINTL\|libintl\|nls" Makefile.am configure.ac
+```
+
+## 解决方案
+
+**configure-disable-feature**：通过 ./configure --disable-nls 禁用国际化支持(推荐)
+
+```bash
+./configure --disable-nls
+```
+
+## 涉及软件
+
+gdbm, tar, coreutils 等 GNU 工具链项目
+
+---
+*条目 E027 · 更新 2026-04-09 · 知识库同步生成物*

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

@@ -0,0 +1,62 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E028: 用户编译的共享库与系统库冲突
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🔴 blocking | **分类**: linking, packaging | **自动修复**: ✅ reconfigure
+
+---
+
+## 错误特征
+
+```
+shared library.*conflict
+system library crash
+symbol link incomplete
+ncurses.*crash
+lib.*\.so.*override.*system
+```
+
+## 根因
+
+用户编译的共享库(.so)版本覆盖了系统版本但符号链接不完整,
+导致依赖系统库的程序崩溃
+
+## 验证命令
+
+```bash
+ls -la $HOME/usr/local/lib/lib*.so*; ldd /usr/bin/zsh
+```
+
+## 解决方案
+
+**configure-static-only**：只编译静态库(--without-shared), 避免覆盖系统共享库
+
+```bash
+./configure --without-shared --prefix=$HOME/usr/local
+```
+
+## 回退方案
+
+**config-cache**：如果 ./configure 参数被忽略，检查 config.cache 并删除后重试
+
+```bash
+rm -f config.cache && ./configure --prefix=$TEST_PREFIX <params>
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`install.*shared.*library.*to.*/usr/(lib|lib64)`
+- **原因**：禁止将用户编译的共享库安装到系统目录(/usr/lib),
+这会破坏系统程序
+- **后果**：系统工具崩溃(zsh/vim/grep 等全部不可用)
+
+## 涉及软件
+
+安装到系统路径或 LD_LIBRARY_PATH 前端的共享库项目(ncurses 等)
+
+---
+*条目 E028 · 更新 2026-04-09 · 知识库同步生成物*

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

@@ -0,0 +1,45 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E029: bash 内置 malloc 与 musl 不兼容
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: compat, libc, memory | **自动修复**: ✅ reconfigure
+
+---
+
+## 错误特征
+
+```
+memory.*abnormal
+malloc.*incompatible
+bash-malloc.*musl
+runtime.*memory error
+```
+
+## 根因
+
+bash 默认使用内置 malloc 实现,
+与 musl libc 的内存管理机制不兼容,
+导致运行时出现内存异常(编译不报错)
+
+## 验证命令
+
+```bash
+./configure --help | grep bash-malloc; ldd $(which bash) | grep musl
+```
+
+## 解决方案
+
+**configure-disable-feature**：禁用内置 malloc, 使用系统(musl)的 malloc
+
+```bash
+./configure --without-bash-malloc --prefix=$HOME/usr/local
+```
+
+## 涉及软件
+
+bash 及其他有内置 malloc 替代的项目
+
+---
+*条目 E029 · 更新 2026-04-09 · 知识库同步生成物*

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

@@ -0,0 +1,44 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E030: 鸿蒙无 32 位兼容层导致编译失败
+
+> 适用性：交叉编译语境，本机原生编译需甄别
+
+> **严重度**: 🟢 minor | **分类**: configure, architecture | **自动修复**: ✅ reconfigure
+
+---
+
+## 错误特征
+
+```
+m32.*personality.*fail
+32-bit.*not supported
+--disable-mpers
+aarch64.*only
+```
+
+## 根因
+
+某些工具(strace 等)默认启用 32 位程序追踪支持(m32 personality),
+鸿蒙系统仅有 aarch64 架构, 无 32 位兼容层
+
+## 验证命令
+
+```bash
+uname -m; file /bin/ls | grep -o 'aarch64\|arm'
+```
+
+## 解决方案
+
+**configure-disable-feature**：禁用 32 位支持(--disable-mpers), 仅保留 aarch64 支持
+
+```bash
+./configure --disable-mpers --prefix=$HOME/usr/local
+```
+
+## 涉及软件
+
+strace 等需要多架构支持的调试/追踪工具
+
+---
+*条目 E030 · 更新 2026-04-09 · 知识库同步生成物*

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

@@ -0,0 +1,46 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E031: /proc 文件系统 SELinux 访问限制
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: selinux, runtime, filesystem | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Cannot open /proc/stat.*Permission denied
+/proc/.*Permission denied.*selinux
+```
+
+## 根因
+
+鸿蒙 SELinux 策略限制普通用户访问 /proc 文件系统,
+导致读取 /proc/stat、/proc/meminfo 等失败
+
+## 验证命令
+
+```bash
+cat /proc/stat  # Permission denied
+```
+
+## 解决方案
+
+**sudo-run**：使用 sudo 运行程序, 继承终端环境变量
+
+```bash
+sudo -E TERM=xterm-256color htop
+```
+
+## 回退方案
+
+**skip-proc-reading**：对于自定义工具, 改用 sysinfo() 等 syscall 替代 /proc 解析
+
+## 涉及软件
+
+htop 及其他直接读取 /proc 的运行时工具
+
+---
+*条目 E031 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E032: _GNU_SOURCE 未定义导致 dirent API 不完整
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: compat, libc, headers | **自动修复**: ✅ set-env-var | **原则**: [P006](../principles.md#P006)
+
+---
+
+## 错误特征
+
+```
+unknown type name 'DIR'
+call to undeclared function 'opendir'
+undeclared.*opendir
+undeclared.*readdir
+```
+
+## 根因
+
+musl 需要 _GNU_SOURCE 而非 _BSD_SOURCE 来暴露完整 dirent API,
+部分软件使用 _BSD_SOURCE 不足以在 musl 下获得完整接口
+
+## 验证命令
+
+```bash
+grep -r "_BSD_SOURCE\|_GNU_SOURCE" 源码目录
+```
+
+## 解决方案
+
+**add-cflags**：通过 CFLAGS 添加 _GNU_SOURCE 宏定义
+
+```bash
+export CFLAGS="-D_GNU_SOURCE $CFLAGS"
+```
+
+## 回退方案
+
+**source-patch**：修改源码中的 _BSD_SOURCE 为 _GNU_SOURCE
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`使用 _BSD_SOURCE 替代 _GNU_SOURCE`
+- **原因**：musl 下 _BSD_SOURCE 不暴露完整 dirent API (DIR/opendir/readdir)
+- **后果**：编译报错: unknown type name 'DIR', undeclared function 'opendir'
+
+## 涉及软件
+
+使用 dirent API 的软件 (gawk 等)
+
+---
+*条目 E032 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,49 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E033: ncurses 宽字符函数需要 _XOPEN_SOURCE_EXTENDED
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: compat, libc, headers | **自动修复**: ✅ set-env-var | **原则**: [P006](../principles.md#P006)
+
+---
+
+## 错误特征
+
+```
+unknown type name 'cchar_t'
+call to undeclared function 'setcchar'
+undeclared.*cchar_t
+undeclared.*setcchar
+ncurses.*wide
+```
+
+## 根因
+
+musl 下 ncurses 宽字符接口需要显式定义 _XOPEN_SOURCE_EXTENDED
+才能暴露 cchar_t 等类型和 setcchar 等函数
+
+## 验证命令
+
+```bash
+grep -r "_XOPEN_SOURCE" 源码目录
+```
+
+## 解决方案
+
+**add-cflags**：通过 CFLAGS 添加 _XOPEN_SOURCE_EXTENDED 和 _XOPEN_SOURCE=600
+
+```bash
+export CFLAGS="-D_XOPEN_SOURCE_EXTENDED -D_XOPEN_SOURCE=600 $CFLAGS"
+```
+
+## 回退方案
+
+**disable-feature**：回退方案: 禁用宽字符功能编译 (--disable-widec)
+
+## 涉及软件
+
+Python curses 模块及其他使用 ncurses 宽字符 API 的软件
+
+---
+*条目 E033 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,53 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E034: 系统缺少 CA 证书包
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: packaging, filesystem, security | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+unable to load client CA certificates
+SSL certificate verification failed
+ca-certificates.*not found
+/etc/ssl/certs.*No such file
+```
+
+## 根因
+
+鸿蒙系统未预装 ca-certificates 包,
+缺少 /etc/ssl/certs/ca-certificates.crt
+
+## 验证命令
+
+```bash
+ls /etc/ssl/certs/ca-certificates.crt  # 文件不存在
+```
+
+## 解决方案
+
+**install-ca-certs**：通过鸿蒙系统 设置→安装证书→CA证书 导入证书包;
+或从可信源下载 ca-certificates 并安装到 /etc/ssl/certs/
+
+## 回退方案
+
+**skip-verify**：临时方案(仅可信源): wget --no-check-certificate 或 curl -k
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`在生产环境或不可信网络中使用 --no-check-certificate/-k`
+- **原因**：跳过证书验证使连接易受中间人攻击(MITM)
+- **后果**：敏感数据(密码、token)可能被窃取
+
+## 涉及软件
+
+wget、curl、Python requests 等所有需要 TLS 证书验证的工具
+
+---
+*条目 E034 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E035: Boost.Build 的 SHELL 执行机制与鸿蒙 shell 不兼容
+
+> **严重度**: 🔴 blocking | **分类**: compat, build-system | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+match-command-output.*exited with error code
+SHELL.*version.*failed
+clang++ --version.*error
+```
+
+## 根因
+
+Boost.Build 的 SHELL 执行机制与鸿蒙 shell 不兼容，无法正确执行版本检测等命令
+
+## 验证命令
+
+```bash
+./b2 --version 2>&1 | grep -E "(exited with error|match-command-output)"
+```
+
+## 解决方案
+
+**header-only-install**：仅安装 Boost 的 header-only 部分，无需编译，直接复制 boost/ 头文件目录
+
+```bash
+cp -r boost $DEFAULT_PREFIX/include/
+```
+
+## 回退方案
+
+**use-standard-library**：对于需要编译的库（filesystem, thread, chrono），使用 C++ 标准库替代（std::filesystem, std::thread, std::chrono）
+
+```bash
+使用 C++11/17 标准库替代 Boost 库
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`b2 install|bjam install`
+- **原因**：Boost.Build 在鸿蒙上无法正常执行 SHELL 命令，会导致编译失败
+- **后果**：编译过程中报错，无法继续
+
+## 涉及软件
+
+所有需要使用 b2/bjam 构建的软件（boost, boost-dependent libraries）
+
+---
+*条目 E035 · 更新 2026-05-19 · 知识库同步生成物*

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

@@ -0,0 +1,53 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E036: 平台字符串含空格导致构建路径错误
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: platform, python, filesystem | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+No module named '_sysconfigdata'.*ohos_aarch64
+build path.*space
+platform string.*space
+uname.*space
+```
+
+## 根因
+
+uname -r 返回 "HongMeng Kernel 1.11.0"(含空格),
+Python 的 get_platform() 将其拼入路径, 导致模块路径解析失败
+
+## 验证命令
+
+```bash
+python3 -c "import sysconfig; print(sysconfig.get_platform())"
+```
+
+## 解决方案
+
+**source-patch**：修改 sysconfig.py / distutils/util.py,
+跳过 release 字段, 使用 "ohos-aarch64" 作为平台标识
+
+## 回退方案
+
+**env-override**：设置 PYTHON_PLATFORM 环境变量覆盖 (如果 Python 版本支持)
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`在路径处理代码中直接拼接 uname -r 输出而不做空格过滤`
+- **原因**：鸿蒙内核版本字符串含空格, 直接拼接导致路径解析失败
+- **后果**：ImportError: No module named '_sysconfigdata_xxx'
+
+## 涉及软件
+
+Python 构建及依赖 sysconfig.get_platform() 的工具链
+
+---
+*条目 E036 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,67 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E037: shebang 兼容性（/usr/bin/env 缺失 + 可移植性）
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: compat, portability, filesystem, shell | **自动修复**: ✅ batch-sed
+
+---
+
+## 错误特征
+
+```
+/usr/bin/env.*bad interpreter.*No such file
+/usr/bin/env.*No such file or directory
+shebang.*env.*fail
+```
+
+## 根因
+
+鸿蒙系统没有 /usr/bin/env, 使用 #!/usr/bin/env xxx shebang 的脚本无法执行。
+同时, 硬编码解释器绝对路径(如 #!/data/service/hnp/bin/perl) 导致不可移植。
+
+## 验证命令
+
+```bash
+ls /usr/bin/env  # 文件不存在
+```
+
+## 解决方案
+
+**shebang-fix**：分两步处理:
+1) 先检查目标系统是否存在 /usr/bin/env, 若存在则用 #!/bin/env xxx (可移植优先)
+2) 若不存在(如鸿蒙), 则降级为直接 shebang: #!/bin/sh, #!/bin/bash, #!/usr/bin/perl 等
+对于已安装的包, 批量 sed 替换修复
+
+```bash
+# 检测并批量修复
+if [ ! -e /usr/bin/env ]; then
+  find $PREFIX -type f -exec sed -i 's|#!/usr/bin/env \([^ ]*\)|#!/\1|g' {} +
+fi
+```
+
+## 回退方案
+
+**install-env-symlink**：创建 /usr/bin/env 软链接指向 /bin/sh (需 root 权限)
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`构建生成的脚本中使用硬编码平台特定路径作为 shebang`
+- **原因**：如 #!/data/service/hnp/bin/perl, 换机后路径不同导致全部失效
+- **后果**：所有生成脚本无法执行: bad interpreter: No such file or directory
+
+### 🚫 禁止 2
+
+- **模式**：`在已知无 /usr/bin/env 的目标平台上新写脚本用 #!/usr/bin/env xxx`
+- **原因**：该 shebang 格式在目标平台不可执行
+- **后果**：脚本执行失败: bad interpreter
+
+## 涉及软件
+
+所有使用不兼容 shebang 的脚本 (libtool、automake 生成的脚本等)
+
+---
+*条目 E037 · 更新 2026-08-20 · 知识库同步生成物*

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

@@ -0,0 +1,61 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E038: groff 宏文件缺失
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟢 minor | **分类**: compat, packaging | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+macro 'g' not defined
+macro 'safe' not defined
+macro 'padj' not defined
+groff.*warning.*diversion
+```
+
+## 根因
+
+groff 1.23.0 移除了 g.tmac(getopt宏)、safe.tmac(安全子集宏)、
+padj.tmac(段落调整宏); man-db 的 man_db.conf 中 nroff 定义仍引用这些已移除的宏
+
+## 验证命令
+
+```bash
+man man  # 查看 groff 警告输出
+```
+
+## 解决方案
+
+**config-patch**：修改 man_db.conf 中的 nroff 定义, 移除不兼容的宏参数:
+DEFINE nroff groff -Tutf8 -mandoc (去掉 -mg -msafe -mpadj)
+
+## 回退方案
+
+**consult-knowledge**：推荐方案不适用时，查阅 ../error-index.md 中相似条目的替代方案
+
+```bash
+grep -r "关键词" ../error-index.md
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`groff 1.23.0+ 的 nroff 配置中引用 -mg/-msafe/-mpadj 宏参数`
+- **原因**：这些宏已在 groff 1.23.0 中被移除
+- **后果**：groff 警告 + 手册页渲染异常
+
+## 涉及软件
+
+man-db 及其他依赖旧版 groff 宏的手册页工具
+
+## 相关模式
+
+- **前置条件（本条是它们的前置）**：[E039](E039.md)、[E040](E040.md)
+
+---
+*条目 E038 · 更新 2026-04-10 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E039: musl iconv 不支持 //IGNORE 后缀
+
+> 适用性：本机原生编译适用
+
+> **严重度**: 🟡 medium | **分类**: compat, libc, python | **自动修复**: ❌ | **原则**: [P005](../principles.md#P005)、[P011](../principles.md#P011)
+
+---
+
+## 错误特征
+
+```
+iconv_open.*//IGNORE.*Invalid argument
+iconv.*//IGNORE.*Invalid
+musl.*iconv.*not support
+```
+
+## 根因
+
+glibc 的 iconv 支持 //IGNORE(忽略不可转换字符) 和
+//TRANSLIT(音译) 后缀扩展, 但 musl libc 的 iconv 不支持这些后缀。
+man-db 的 manconv 工具使用 iconv_open("UTF-//IGNORE", ...)
+
+## 验证命令
+
+```bash
+mandb 2>&1 | grep -i "iconv"
+```
+
+## 解决方案
+
+**source-patch**：musl 兼容方案: 去掉 //IGNORE 后缀, 使用标准编码名
+
+## 回退方案
+
+**manual-workaround**：如果自动补丁不适用，手动在源码中做最小兼容修改并记录到 notes.md
+
+```bash
+# 手动编辑源码后记录:
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`在代码中使用 iconv_open("...//IGNORE", ...) 或 "...//TRANSLIT" 格式`
+- **原因**：musl iconv 不支持 glibc 扩展后缀, 导致 Invalid argument 错误
+- **后果**：字符编码转换完全失败; man-db whatis 解析全部失败
+
+## 涉及软件
+
+man-db 的 whatis/apropos 搜索功能失效; man 命令本身显示不受影响
+
+---
+*条目 E039 · 更新 2026-04-10 · 知识库同步生成物*