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

@@ -0,0 +1,48 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E119: OpenHarmony SDK 的系统头文件组织问题
+
+> **严重度**: 🔴 blocking | **分类**: toolchain | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+error: redefinition of 'struct sockaddr_storage'
+note: previous definition of 'struct sockaddr_storage' was here
+conflicting types for 'sockaddr_storage'
+```
+
+## 根因
+
+OpenHarmony SDK 的系统头文件组织问题，linux/socket.h 和 sys/socket.h 都定义了 sockaddr_storage 结构体
+
+## 验证命令
+
+```bash
+grep -r "sockaddr_storage" /usr/include/linux/socket.h /usr/include/sys/socket.h 2>/dev/null | head -5
+```
+
+## 解决方案
+
+**macro-guard-skip-header**：使用 #ifdef __OHOS__ 宏守卫，定义 _UAPI_LINUX_SOCKET_H 跳过 linux/socket.h，手动定义 __kernel_sa_family_t
+
+```bash
+在 #include <sys/socket.h> 后、#include <linux/if_arp.h> 前插入修复代码块
+```
+
+## 回退方案
+
+**exclude-linux-socket-h**：在源文件中避免包含 linux/socket.h 相关的头文件
+
+```bash
+手动修改源文件，使用 #ifdef __OHOS__ 排除 linux/if_arp.h 等头文件
+```
+
+## 涉及软件
+
+所有在 OpenHarmony 上编译的软件，当源文件同时包含 linux/socket.h 和 sys/socket.h 时触发
+
+---
+*条目 E119 · 更新 2026-05-27 · 知识库同步生成物*

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

@@ -0,0 +1,52 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E120: OHOS SDK 的 lld 动态链接到 libxml2.so.16
+
+> **严重度**: 🔴 blocking | **分类**: ohos, toolchain, linking, environment | **自动修复**: ✅ set-env
+
+---
+
+## 错误特征
+
+```
+error while loading shared libraries: libxml2\.so\.16
+cannot open shared object file: libxml2\.so\.16
+lld: error:.*libxml2
+```
+
+## 根因
+
+OHOS SDK 的 lld 动态链接到 libxml2.so.16，但系统库路径未包含该路径
+
+## 验证命令
+
+```bash
+ldd /data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/bin/lld | grep libxml2
+```
+
+## 解决方案
+
+**env-library-path**：设置 LD_LIBRARY_PATH 包含 OHOS SDK 的 lib 目录
+
+```bash
+export LD_LIBRARY_PATH=/data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/ohos/native/llvm/lib:$LD_LIBRARY_PATH
+```
+
+## 回退方案
+
+**static-link**：使用静态链接的 lld 版本（如果可用）
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LD_LIBRARY_PATH=.*libxml2`
+- **原因**：不应直接指向 libxml2 库目录，应指向 OHOS SDK 的 lib 目录
+- **后果**：可能导致其他库加载问题
+
+## 涉及软件
+
+使用 OHOS SDK 26.0.0+ 的所有编译，尤其是链接阶段
+
+---
+*条目 E120 · 更新 2026-05-29 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E121: OHOS 系统只提供 utmp API（setutent/pututline/endutent）
+
+> **严重度**: 🔴 blocking | **分类**: platform, limitation, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined symbol: setutxent
+undefined symbol: pututxline
+undefined symbol: endutxent
+did you mean: setutent
+did you mean: pututline
+did you mean: endutent
+```
+
+## 根因
+
+OHOS 系统只提供 utmp API（setutent/pututline/endutent），不提供 utmpx API（setutxent/pututxline/endutxent），导致链接失败
+
+## 验证命令
+
+```bash
+grep -r "setutxent|pututxline|endutxent" *.c
+```
+
+## 解决方案
+
+**add_compile_definition**：添加 OMIT_UTMP 编译定义，禁用 utmp 记录功能（对非桌面终端程序核心功能非必需）
+
+```bash
+target_compile_definitions(target PRIVATE OMIT_UTMP)
+```
+
+## 回退方案
+
+**replace-api**：将 utmpx API 替换为 utmp API（setutxent → setutent，pututxline → pututline，endutxent → endutent）
+
+```bash
+sed -i 's/setutxent/setutent/;s/pututxline/pututline/;s/endutxent/endutent/' pty.c
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`utmpx\.h`
+- **原因**：OHOS 不提供 utmpx.h，必须禁用或替换
+- **后果**：链接失败：undefined symbol
+
+## 涉及软件
+
+使用 utmpx.h 和 utmp 记录功能的程序（如 SSH 服务器、终端工具）
+
+---
+*条目 E121 · 更新 2026-05-28 · 知识库同步生成物*

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

@@ -0,0 +1,59 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E122: GNU config.sub 脚本的 kernel-os 组合验证（case $kernel-$os-$obj in）
+
+> **严重度**: 🟡 medium | **分类**: autotools, configure | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Invalid configuration.*Kernel.*linux.*not known to work with OS.*ohos
+Kernel.*linux.*not known to work with OS.*ohos
+linux-ohos.*not recognized
+```
+
+## 根因
+
+GNU config.sub 脚本的 kernel-os 组合验证（case $kernel-$os-$obj in）
+只包含 linux-gnu、linux-android、linux-musl 等已知组合，
+不包含 linux-ohos。当 config.guess 输出 aarch64-unknown-linux-ohos
+时，config.sub 在最终验证阶段拒绝此三元组。
+patch-autotools-ohos.pl 脚本只修改了 OS 列表和基本三元组，
+但未修改 kernel-os 验证列表。
+
+## 验证命令
+
+```bash
+grep "linux-gnu\*-" build-aux/config.sub;
+grep "linux-ohos" build-aux/config.sub;
+./build-aux/config.sub aarch64-unknown-linux-ohos
+```
+
+## 解决方案
+
+**add-linux-ohos-to-validation**：在 config.sub 的 kernel-os 验证列表中添加 linux-ohos*-。
+定位到 "case $kernel-$os-$obj in" 分支，
+在 linux-uclibc*- 后添加 linux-ohos*-。
+
+```bash
+sed -i '/linux-uclibc\*- )/a\            | linux-ohos*- )/' build-aux/config.sub
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`--build=*|--host=*`
+- **原因**：导致 configure 误判为交叉编译，
+AC_RUN_IFELSE 等运行时检测全部跳过，
+生成的 config.h 与实际平台不匹配
+- **后果**：级联错误链
+
+## 涉及软件
+
+**所有 autotools 项目**（在应用 patch-autotools-ohos.pl 后仍可能遇到）
+
+---
+*条目 E122 · 更新 2026-04-30 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E123: meson 构建系统中
+
+> **严重度**: 🟡 medium | **分类**: meson, linking, static-library | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+undefined symbol: g_libintl_gettext
+undefined symbol: g_libintl_bindtextdomain
+ld\.lld: error: undefined symbol: g_libintl_
+```
+
+## 根因
+
+meson 构建系统中，当使用静态库（如 glib 的 .a 文件）作为依赖时，如果这些静态库依赖其他库（如 libintl），meson 可能会错误地链接动态库版本（.so）而不是静态库版本（.a）。这导致静态库中引用的符号在运行时找不到，因为静态库期望链接到静态版本的依赖库。
+
+## 验证命令
+
+```bash
+grep 'libintl\.a' build/build.ninja && ninja -j1 && echo "链接成功"
+```
+
+## 解决方案
+
+**patch-build-file**：修改 meson 生成的 build.ninja 文件，将所有动态库依赖（.so）替换为静态库版本（.a）。具体操作：sed -i 's|libintl\.so|libintl.a|g' build.ninja，然后重新编译。
+
+```bash
+cd build && sed -i 's|libffi\.so|libffi.a|g' build.ninja && sed -i 's|libintl\.so|libintl.a|g' build.ninja && ninja
+```
+
+## 涉及软件
+
+使用 glib 静态库作为依赖的 meson 项目，以及其他使用静态链接但依赖库同时提供静态和动态版本的场景。
+
+---
+*条目 E123 · 知识库同步生成物*

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

@@ -0,0 +1,39 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E124: Go link 工具尝试 mmap 输出文件时被 SELinux 或安全策略拒绝
+
+> **严重度**: 🔴 blocking | **分类**: linking, go, permissions | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+mapping output file failed: permission denied
+link: mapping output file failed
+```
+
+## 根因
+
+Go link 工具尝试 mmap 输出文件时被 SELinux 或安全策略拒绝
+
+## 验证命令
+
+```bash
+export CGO_ENABLED=1 && go build -v 2>&1 | grep "mapping output file"
+```
+
+## 解决方案
+
+**use-cgo-linker**：启用 CGO 使用系统链接器替代 Go link 工具
+
+```bash
+export CGO_ENABLED=1 && export CC=clang && go build -v -o bin/${NAME} ${PKG}
+```
+
+## 涉及软件
+
+Go 语言项目编译（需要 Go 1.25+ 的项目）
+
+---
+*条目 E124 · 更新 2026-05-21 · 知识库同步生成物*

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

@@ -0,0 +1,66 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E125: HMDFS（鸿蒙分布式文件系统）在创建临时子目录时存在权限限制
+
+> **严重度**: 🔴 blocking | **分类**: environment | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+can't create .* subs1\.awk.*Permission denied
+config\.status.*could not setup config files machinery
+\.\/conf[a-zA-Z0-9]+\/.*Permission denied
+```
+
+## 根因
+
+HMDFS（鸿蒙分布式文件系统）在创建临时子目录时存在权限限制。
+autotools 的 config.status 使用 mktemp 创建随机命名的临时子目录
+（如 conf[a-zA-Z0-9]+/），并在其中写入 subs1.awk 等文件。
+但 HMDFS 的安全策略限制了某些目录下的子目录创建操作，
+导致即使父目录权限正确，子目录创建仍然失败。
+这与 E002（/tmp 只读）不同，E002 是挂载点只读问题，
+而 E081 是 HMDFS 特定的文件系统安全限制。
+
+## 验证命令
+
+```bash
+mount | grep hmdfs;
+cd $HOME && mkdir -p test-tmp && cd test-tmp && 
+mktemp -d ./confXXXXXX && ls -la || echo "HMDFS restriction detected"
+```
+
+## 解决方案
+
+**relocate-build-dir**：将源码目录移动到 HMDFS 外的可写目录（如 /data/local/tmp，如果可写）
+或使用 tmpfs 挂载点（如 /dev/shm，如果空间足够）。
+如果以上都不可行，则此问题为平台硬限制，需等待系统更新或使用
+非HMDFS环境的构建服务器。
+注意：即使设置 TMPDIR，config.status 仍会在源码目录下创建临时子目录，
+因此仅设置 TMPDIR 无法解决此问题。
+
+```bash
+# 方案 A：尝试使用 /dev/shm（tmpfs）
+if mountpoint -q /dev/shm && df -h /dev/shm | grep -q "G"; then
+  cd /dev/shm && cp -r $BUILD_SRC_DIR . && cd libsigrok-* && ./configure ...
+fi
+# 方案 B：标记为平台限制，无法编译
+echo "E081: HMDFS restriction blocks autotools config.status" >> $BUILD_ARCHIVE_DIR/notes.md
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`--build=|--host=`
+- **原因**：不能用 --build/--host 绕过，这会导致其他问题（见 E007）
+- **后果**：级联错误：config.h 不匹配 → 运行时崩溃
+
+## 涉及软件
+
+所有使用 autotools 构建系统的软件，在 HMDFS 挂载目录下编译时
+
+---
+*条目 E125 · 更新 2026-05-26 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E126: HarmonyOS HMDFS 文件系统不支持 GNU autotools 的 config.status 创建临时目录…
+
+> **严重度**: 🔴 blocking | **分类**: platform, limitation | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+can't create ./conf[a-zA-Z0-9]+/subs[0-9]+\.awk: Permission denied
+config\.status.*Permission denied
+HMDFS.*temporary file
+```
+
+## 根因
+
+HarmonyOS HMDFS 文件系统不支持 GNU autotools 的 config.status 创建临时目录和文件（confXXXX/subs1.awk 等），导致 configure 生成的 config.status 无法执行
+
+## 验证命令
+
+```bash
+df -h ~/tmp | grep hmdfs
+```
+
+## 解决方案
+
+**use_precompiled_package          # 见 DESIGN §5 impl 列表**：使用预编译包替代手动编译（R18 预编译包优先原则）
+
+```bash
+curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- {software} {version}
+```
+
+## 回退方案
+
+**use_cmake_alternative**：使用 CMake 构建系统替代 autotools（如果软件支持）
+
+```bash
+cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$DEFAULT_PREFIX ..
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`HMDFS|/storage/Users/currentUser/tmp|~/tmp`
+- **原因**：HMDFS 文件系统不支持 autotools 临时文件操作，在这些目录编译 autotools 项目必定失败
+- **后果**：编译失败，浪费时间调试无法解决的平台限制
+
+## 涉及软件
+
+所有使用 GNU autoconf 的软件编译，包括 MPFR、GMP、openssl 等 autotools 项目
+
+---
+*条目 E126 · 更新 2026-05-30 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E127: HarmonyOS 内核不支持 POSIX 线程取消机制(pthread_cancel
+
+> **严重度**: 🔴 blocking | **分类**: platform, api | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+pthread_cancel.*undeclared
+pthread_setcanceltype.*undeclared
+pthread_setcancelstate.*undeclared
+```
+
+## 根因
+
+HarmonyOS 内核不支持 POSIX 线程取消机制(pthread_cancel, pthread_setcanceltype, pthread_setcancelstate)，与 Android 类似
+
+## 验证命令
+
+```bash
+grep -r "pthread_cancel\|pthread_setcancel" /data/service/hnp/ohos-sdk.org/*/ohos/native/llvm/sysroot/usr/include/pthread.h || echo "Not found in HarmonyOS pthread.h"
+```
+
+## 解决方案
+
+**undef-macro**：添加条件编译，类似 Android 处理：在定义 KMP_CANCEL_THREADS 的位置添加 #ifdef __OHOS__ 守卫并 undef 该宏
+
+```bash
+在源码中添加: #if defined(__ANDROID__) || defined(__OHOS__) \n#undef KMP_CANCEL_THREADS\n#endif
+```
+
+## 回退方案
+
+**cmake-disable**：通过 CMake 选项禁用线程取消功能（如果软件支持）
+
+```bash
+cmake -DENABLE_THREAD_CANCEL=OFF ...
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`pthread_cancel\(.*\)`
+- **原因**：HarmonyOS 不支持 pthread_cancel，直接调用会导致编译失败
+- **后果**：编译失败，undeclared identifier 错误
+
+## 涉及软件
+
+使用 pthread_cancel 的多线程软件，特别是 OpenMP 运行时库(libomp)和其他线程管理库
+
+---
+*条目 E127 · 更新 2026-05-19 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E128: Go 编译器二进制文件需要 ELF 签名才能在鸿蒙上执行
+
+> **严重度**: 🔴 blocking | **分类**: platform, limitation | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+permission denied.*go.*
+sign.*elf.*failed.*go
+zsh.*permission denied.*go/bin/go
+```
+
+## 根因
+
+Go 编译器二进制文件需要 ELF 签名才能在鸿蒙上执行，但 binary-sign-tool 签名 Go 失败
+
+## 验证命令
+
+```bash
+go version
+```
+
+## 解决方案
+
+**use-prebuilt-package**：使用预编译的 Go 编译器（已签名），或使用交叉编译在其他平台为鸿蒙编译 Go 项目
+
+```bash
+curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- go <version>
+```
+
+## 涉及软件
+
+所有 Go 语言项目
+
+---
+*条目 E128 · 知识库同步生成物*

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

@@ -0,0 +1,56 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E129: HMDFS filesystem always sets setgid bit on new directories
+
+> **严重度**: 🔴 blocking | **分类**: platform, hmdfs | **自动修复**: ✅ sed-replace
+
+---
+
+## 错误特征
+
+```
+config\.status.*Permission denied.*subs1\.awk
+can't create.*conf[A-Za-z0-9]+.*Permission denied
+could not setup config files machinery
+```
+
+## 根因
+
+HMDFS filesystem always sets setgid bit on new directories; umask 077 creates drwx--S--- which blocks even the owner from writing files inside it
+
+## 验证命令
+
+```bash
+cd ~/tmp && (umask 077 && tmp=$(mktemp -d "./confXXXXXX") && echo test > "$tmp/testfile" && echo FAIL || echo PASS) && rm -rf ./conf*
+```
+
+## 解决方案
+
+**sed-replace**：Replace umask 077 with umask 022 in configure and config.status scripts (lines creating temp directories)
+
+```bash
+sed -i 's/umask 077/umask 022/g' configure config.status
+```
+
+## 回退方案
+
+**env-hint**：Set TMPDIR to writable location and ensure mktemp creates directories with group read permissions
+
+```bash
+export TMPDIR=$HOME/tmp && CONFIG_SHELL=bash bash ./configure --prefix=$DEFAULT_PREFIX
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`--build=|--host=|--target=`
+- **原因**：Native compilation on HarmonyOS; platform detection should use updated config.guess instead
+- **后果**：Binary paths hardcoded incorrectly; runtime failures
+
+## 涉及软件
+
+All autotools software using configure/config.status on HarmonyOS
+
+---
+*条目 E129 · 更新 2026-06-02 · 知识库同步生成物*

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

@@ -0,0 +1,40 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E130: OHOS SDK (ohos-sdk_26.0.0.18) ships custom libc++ headers at…
+
+> **严重度**: 🔴 blocking | **分类**: platform, libcxx-stdlib | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+no member named 'nullptr_t' in the global namespace
+unknown type name 'nullptr_t'
+'__abi_tag__' attribute only applies to
+```
+
+## 根因
+
+OHOS SDK (ohos-sdk_26.0.0.18) ships custom libc++ headers at libcxx-ohos/include/c++/v1/ designed for C++17+, projects using -std=c++11 fail with nullptr_t, __abi_tag__, and constexpr errors
+
+## 验证命令
+
+```bash
+echo '#include <string>' | clang++ -x c++ -std=c++11 -fno-rtti -isystem ~/usr/local/include - -o /dev/null
+```
+
+## 解决方案
+
+**change-cxx-standard**：Change -std=c++11 to -std=c++17 in CMakeLists.txt or build config, also disable -Werror
+
+```bash
+sed -i 's/-std=c++11/-std=c++17/' CMakeLists.txt && cmake .. -DFAIL_ON_WARNINGS=OFF
+```
+
+## 涉及软件
+
+any C++ project compiled with -std=c++11 or lower on OpenHarmony
+
+---
+*条目 E130 · 更新 2026-06-23 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E131: Setting LD=<value> as environment variable causes musl's dyn…
+
+> **严重度**: 🟡 medium | **分类**: environment | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library.*\.so.*Permission denied
+Can't load.*\.so.*Permission denied
+```
+
+## 根因
+
+Setting LD=<value> as environment variable causes musl's dynamic linker to fail loading .so files via dlopen() with "Permission denied". The LD variable is interpreted by the linker subsystem and interferes with normal .so resolution. This particularly affects Perl XS modules where CC=cc LD=cc are set during compilation (to override Perl's default clang 18 without sysroot) but must be unset at runtime.
+
+## 验证命令
+
+```bash
+env | grep "^LD=" → if set, try: env -u LD <command>
+```
+
+## 解决方案
+
+**unset-env-var**：Unset LD (and CC) environment variables before runtime/test operations
+
+```bash
+env -u CC -u LD perl -Mmodule -e '...'
+```
+
+## 回退方案
+
+**wrapper-script**：Create a wrapper script that unsets LD before exec
+
+```bash
+sh -c 'unset LD; exec "$@"' -- perl ...
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`export LD=`
+- **原因**：Do not set LD as persistent env var - it will break all .so loading
+- **后果**：All Perl XS modules and dlopen-based software fail with Permission denied
+
+## 涉及软件
+
+Perl XS modules and any software using dlopen when LD env var is set
+
+---
+*条目 E131 · 更新 2026-06-17 · 知识库同步生成物*