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

@@ -0,0 +1,91 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E516: OHOS libc omits _res/__res_state and <linux/ip.h> — provide custom resolver state and skip IP options
+
+> **严重度**: 🟡 medium | **分类**: ohos, libc, build-system, ndk, resolver | **自动修复**: ❌ | **原则**: [P001](../principles.md#P001)、[P007](../principles.md#P007)
+
+---
+
+## 错误特征
+
+```
+undefined symbol: _res
+undefined reference to ._res.
+cannot find -lresolv
+incomplete type .struct ip_options.
+linux/ip.h: No such file
+```
+
+## 根因
+
+OHOS libc (bionic-derived) provides res_init()/res_search()/res_query()
+but does NOT export the legacy global `_res` symbol nor the `__res_state()`
+thread-local accessor that glibc exposes; software using `return &_res;` to
+obtain a resolver-state pointer fails to link (undefined symbol: _res).
+Separately the OHOS NDK headers ship no `<linux/ip.h>`, so `struct
+ip_options` is an incomplete type and code referencing it fails to compile.
+
+## 验证命令
+
+```bash
+echo 'int main(void){extern int _res; return _res;}' > /tmp/t.c
+&& clang /tmp/t.c -o /tmp/t 2>&1 | grep -q 'undefined.*_res' && echo CONFIRMED
+```
+
+## 解决方案
+
+**provide-custom-resolver-state**：Define OS_GET_DNS_RESOLVER_RES to skip the generic _res path,
+then provide a process-wide static struct __res_state accessor; for
+ip_options define NO_IP_OPTIONS and undef GLIBC_IP_OPTIONS to skip the
+deprecated IPv4 source-route path.
+
+```bash
+add to OS/os.h-<plat>: #define OS_GET_DNS_RESOLVER_RES \n #undef
+GLIBC_IP_OPTIONS \n #define NO_IP_OPTIONS ; add to OS/os.c-<plat>:
+static struct __res_state s; res_state os_get_dns_resolver_res(void){
+return &s; }
+```
+
+## 回退方案
+
+**link-against-libresolv-shim**：If the software cannot be patched, build a small shim
+library exposing a writable `_res` symbol and -lresolv to satisfy the
+linker, accepting that resolver options set on the shim may not propagate
+to OHOS internal resolver state.
+
+```bash
+echo 'int _res;' > shim.c && clang -shared -o libresshim.so
+shim.c && LDFLAGS+=-lresshim
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`return\s*&_res\s*;`
+- **原因**：Direct `_res` access does not link on OHOS (symbol absent);
+the shim fallback only silences the link error, runtime resolver config
+will not work.
+- **后果**：Binary links but DNS resolver options (retrans/retry/
+options) set by the software are silently ignored by OHOS res_search().
+
+### 🚫 禁止 2
+
+- **模式**：`#include\s*<linux/ip\.h>`
+- **原因**：OHOS NDK does not ship <linux/ip.h>; direct include fails.
+- **后果**：Compilation error: linux/ip.h: No such file or directory.
+
+## 涉及软件
+
+C/C++ software ported from Linux/glibc that (a) directly reads
+the global `_res` resolver state or calls `__res_state()` to configure DNS
+resolver options/retrans/retry (e.g. MTAs, DNS tools, anything wrapping
+res_search with custom state), and (b) references IPv4 IP socket options
+via `<linux/ip.h>` / `struct ip_options`. Observed on exim 4.99.5.
+
+## 相关模式
+
+- **根因条目（应先修它们）**：[E320](E320.md)
+
+---
+*条目 E516 · 更新 2026-08-26 · 知识库同步生成物*

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

@@ -0,0 +1,55 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E517: Published Conan package .so can carry a signature the consuming device rejects (dlopen: Permission denied)
+
+> **严重度**: 🟢 minor | **分类**: security, dynamic-loading | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library .*: Permission denied
+Permission denied .needed by
+```
+
+## 根因
+
+OHOS 拒绝映射签名不被本机接受的共享库，且错误文案是 Permission denied 而不是 No such file。与 E135（完全未签名）不同：本例中文件确实带 .codesign 段（llvm-readelf -SW 计数为 1），但该签名在消费端设备上无效——已发布包在构建机上签名后随二进制分发，落到另一台设备就可能不被接受。同一目录里其他依赖库可正常 dlopen，因此极易被误判为路径问题或符号链接问题。
+
+## 验证命令
+
+```bash
+dlopen 绝对路径逐个探测：对同一目录内相邻库能成功、目标库报 Permission denied，即判定为签名无效而非路径缺失
+```
+
+## 解决方案
+
+**remove-then-resign-in-task-local-view**：把目标库复制进任务私有视图后，先用 llvm-objcopy --remove-section .codesign 去掉旧段（binary-sign-tool 无法覆盖已有段），再用 binary-sign-tool sign -selfSign 1 重新签名，最后校验 .codesign 计数恰为 1 且保留 owner 可执行位。绝不修改依赖包本体。
+
+```bash
+llvm-objcopy --remove-section .codesign $VIEW/libfoo.so.1 && binary-sign-tool sign -inFile $VIEW/libfoo.so.1 -outFile $VIEW/libfoo.so.1.signed -selfSign 1 && mv $VIEW/libfoo.so.1.signed $VIEW/libfoo.so.1 && llvm-readelf -SW $VIEW/libfoo.so.1 | grep -c codesign
+```
+
+## 回退方案
+
+**per-file-absolute-dlopen-triage**：先用绝对路径 dlopen 逐个隔离，确认是签名、符号链接还是路径问题，再决定是否需要重签名；不要直接改成静态链接来掩盖（AGENTS 禁止）。
+
+```bash
+clang -o dl_probe dl_probe.c && ./dl_probe /abs/path/libfoo.so.1.2.3
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`看到 Permission denied 就改成静态链接或放宽 chmod`
+- **原因**：静态链接只掩盖了本机加载问题；HMDFS 的 chmod 会被归一化，且权限位不是最终权限（MAC 优先）
+- **后果**：产物语义被改变、问题被推迟到下游消费端爆发
+
+## 涉及软件
+
+任何把已发布 Conan 包的 .so 直接映射进本进程的构建或测试阶段（autoconf 运行探测、test_package 消费者、ctypes/dlopen 插件加载）。
+
+---
+*条目 E517 · 更新 2026-08-28 · 知识库同步生成物*

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

@@ -0,0 +1,73 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E518: CI git-clone 步骤失败——Worker 上 /data/service/hnp/bin/git 缺 libz.so (RUNPATH 硬编码构建机路径 /code/deps_install/lib, musl ldso 不解析)
+
+> **严重度**: 🔴 blocking | **分类**: ohos, toolchain, environment | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+Error loading shared library libz\.so.*needed by /data/service/hnp/bin/git
+Error loading shared library libz\.so.*git.*exit code 127
+git-clone.*exit code 127
+libz\.so.*Permission denied
+```
+
+## 根因
+
+buildbot worker 使用 /data/service/hnp/bin/git (git 2.45.2) 执行 git-clone,
+该二进制 NEEDED libz.so, 但其 RUNPATH 硬编码为 /code/deps_install/lib
+(构建 git 的机器路径, worker 上不存在)。musl ldso 不解析 $ORIGIN,
+只能靠系统默认加载路径。健康 worker 的 /usr/lib/libz.so.1 存在,
+故障 worker 缺失 → git 启动失败 exit 127, 构建在 git-clone 步骤即失败。
+该步骤发生在 checkout-pr / conan 配方可见之前, 配方代码无法干预。
+
+## 验证命令
+
+```bash
+/data/service/hnp/bin/git --version; ldd /data/service/hnp/bin/git 2>/dev/null; ls -la /usr/lib/libz.so.1; readelf -d /data/service/hnp/git.org/git_2.45.2/bin/git | grep -E 'NEEDED|RUNPATH'
+```
+
+## 解决方案
+
+**worker-env-fix-zlib**：CI 维护者修复 worker 环境: 安装 zlib (libz.so.1) 到系统默认库路径 /usr/lib, 使 git 可加载; 该 worker 上所有 PR 恢复正常
+
+```bash
+将 libz.so.1 安装到 /usr/lib (或从 cmd-pkgs 拉 zlib 包), 然后 /data/service/hnp/bin/git --version 验证
+```
+
+## 回退方案
+
+**patchelf-fix-git-runpath**：按 E186 先例用 patchelf 修改 git 的 RUNPATH 添加 /usr/lib: 复制 git 到可写目录, patchelf --set-rpath, 再用 binary-sign-tool 签名 (ELF 修改后必须重签)
+
+```bash
+cp /data/service/hnp/git.org/git_2.45.2/bin/git ~/tmp/git-local && patchelf --set-rpath '/usr/lib:/code/deps_install/lib' ~/tmp/git-local && binary-sign-tool sign ~/tmp/git-local
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`认为是 PR 配方问题反复 /rebuild`
+- **原因**：git-clone 发生在配方可见之前, 配方无法干预; 反复 rebuild 只会命中故障 worker
+- **后果**：无限重试无效, 延误修复
+
+### 🚫 禁止 2
+
+- **模式**：`在配方/仓库内尝试修改 /data/service/hnp/bin/git 或 /usr/lib`
+- **原因**：配方在 git-clone 之后才可见, 无法触达; 修改系统库属 worker 环境操作
+- **后果**：无效且越权
+
+## 涉及软件
+
+所有在该类 worker 上触发 CI 构建的 PR; 表现为 git-clone 步骤
+"Error loading shared library libz.so" exit 127
+
+## 相关模式
+
+- **相似模式**：[E186](E186.md)
+
+---
+*条目 E518 · 更新 2026-08-27 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E519: out-of-source 构建 install-data-am 的 $(EXTRA_DIST) 相对路径找不到源文件
+
+> **严重度**: 🟡 medium | **分类**: autotools, conan, packaging | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+ginstall: cannot stat '[a-z-]+\.txt': No such file or directory
+```
+
+## 根因
+
+conan 默认 out-of-source 构建（build-release 子目录），install-data-am 直接用 $(EXTRA_DIST) 安装文件，相对路径从 build 目录解析找不到源文件（如 vars-pl.txt）。需改为 $(addprefix $(srcdir)/,$(EXTRA_DIST))，contrib/docs 的 $(DOCS)/themes/* 同理。
+
+## 验证命令
+
+```bash
+conan create 全流程通过，make install 无 cannot stat 错误
+```
+
+## 解决方案
+
+**approach-identifier          # 见 DESIGN §5 impl 列表**：approach-identifier # 见 DESIGN §5 impl 列表
+
+```bash
+可选: 具体命令模板(${VAR}变量引用)
+```
+
+## 涉及软件
+
+Autotools 项目自定义 install-data-am 规则安装源码目录文件，且用 conan out-of-source 构建
+
+---
+*条目 E519 · 更新 2026-08-28 · 知识库同步生成物*

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

@@ -0,0 +1,38 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E520: qsb 宿主工具需 LD_LIBRARY_PATH
+
+> **严重度**: 🟡 medium | **分类**: qt6-module-adapt | **自动修复**: ✅ manual
+
+---
+
+## 错误特征
+
+```
+qsb: Error relocating symbol not found
+```
+
+## 根因
+
+Qt Shader Baker（qsb）构建期运行加载 libQt6ShaderTools/libQt6Core 需依赖包 lib 路径
+
+## 验证命令
+
+```bash
+qsb --version 2>&1 | grep -q "Error relocating" && echo "缺 LD_LIBRARY_PATH"
+```
+
+## 解决方案
+
+**build() 中用 cmake -E env LD_LIBRARY_PATH=<qtbase lib>:<qtshadertools lib> cmake --build**：cmake -E env 注入 qtbase/qtshadertools 的 lib 到 LD_LIBRARY_PATH 后执行 cmake --build
+
+```bash
+cmake -E env LD_LIBRARY_PATH=$LD_LIBRARY_PATH cmake --build <build_dir>
+```
+
+## 涉及软件
+
+Qt 6.11 子模块适配
+
+---
+*条目 E520 · 更新 2026-08-12 · 知识库同步生成物*

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

@@ -0,0 +1,60 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E521: libtoolize hardcoded SED path breaks aux-dir resolution (ltmain.sh placed in parent dir)
+
+> **严重度**: 🟡 medium | **分类**: build-system, autotools | **自动修复**: ✅ manual | **原则**: [P002](../principles.md#P002)、[P008](../principles.md#P008)
+
+---
+
+## 错误特征
+
+```
+required file \x27\./ltmain\.sh\x27 not found
+libtoolize: putting auxiliary files in \x27\.\./\.\.\x27
+usr/local/bin/sed: No such file
+```
+
+## 根因
+
+Installed libtoolize/automake hardcode /storage/Users/currentUser/usr/local/bin/sed which does not exist on the minimal OHOS image.  When SED is unset, libtoolize's extract-trace / aux-dir heuristic fails and it walks UP the tree, placing auxiliary files (ltmain.sh) into a parent directory; automake then aborts with "required file ./ltmain.sh not found".
+
+## 验证命令
+
+```bash
+ls -la ltmain.sh
+```
+
+## 解决方案
+
+**export-env-tools**：Set SED/AUTOCONF/AUTOHEADER/AUTOM4TE to the real tool paths (command -v) before autoreconf -fi so libtoolize resolves the aux dir to "." and copies ltmain.sh into the source root.  conanfile.py implements this in _prepare_autotools_env().
+
+```bash
+export SED=$(command -v sed) AUTOCONF=$(command -v autoconf) AUTOHEADER=$(command -v autoheader) AUTOM4TE=$(command -v autom4te); autoreconf -fi
+```
+
+## 回退方案
+
+**manual-copy-ltmain**：Manually copy the libtool build-aux ltmain.sh into the source root before autoreconf.
+
+```bash
+cp /storage/Users/currentUser/usr/local/share/libtool/build-aux/ltmain.sh . && autoreconf -fi
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`SED=`
+- **原因**：Leaving SED unset lets libtoolize fall back to its hardcoded broken path and walk up the tree.
+- **后果**：ltmain.sh placed in a parent dir; automake fails "required file ./ltmain.sh not found".
+
+## 涉及软件
+
+Any autotools project bootstrapped via autoreconf -fi on a minimal OHOS image
+
+## 相关模式
+
+- **相似模式**：[E209](E209.md)
+
+---
+*条目 E521 · 更新 2026-08-14 · 知识库同步生成物*

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

@@ -0,0 +1,88 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E522: Build a task-local recursive Libtool metadata closure
+
+> **严重度**: 🟡 medium | **分类**: autotools, cross-compile, conan, libtool, relocatable | **自动修复**: ❌ | **原则**: [P010](../principles.md#P010)、[P012](../principles.md#P012)、[P014](../principles.md#P014)
+
+---
+
+## 错误特征
+
+```
+is not a valid libtool archive
+library .*\.la was moved
+sanitized .*\.la.*missing archive
+bad escape \\H
+```
+
+## 根因
+
+A relocated Conan package can contain a direct Libtool
+archive whose dependency_libs points to current or stale
+transitive .la files. Repairing only the direct archive
+is insufficient because Libtool recursively opens each
+transitive archive. Cross-host graph checks add two traps:
+regex replacement strings interpret Windows backslashes,
+and Windows Path treats //lib/foo.la as a UNC anchor.
+
+## 验证命令
+
+```bash
+Run a fresh isolated graph/install check and an exact
+target static/shared conan create; require every shadow
+.la reference to remain inside the task-local shadow,
+zero stale cache tokens, complete upstream tests, real
+package consumers, and unchanged dependency packages.
+```
+
+## 解决方案
+
+**task-local-recursive-libtool-shadow**：Enumerate dependency .la files by unique basename,
+copy every declared library artifact into a build-local
+directory, rewrite the complete dependency_libs closure
+to shadow paths, bind each shadow libdir locally, and put
+the shadow directory before dependency libdirs. Use a
+callable regex replacement for host paths and
+PurePosixPath for leading-slash target tokens.
+
+```bash
+conan create <recipe> -pr:h=ohos-aarch64 -pr:b=ohos-aarch64 --build=missing
+```
+
+## 回退方案
+
+**scoped-la-free-static-archive-directory**：For static-only dependencies, use E236 and copy only
+required .a files into a private directory with no .la
+metadata. Do not use this fallback when shared library
+metadata is required.
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`sed .*dependency_libs.*\.conan|rm .*\.la.*conan`
+- **原因**：Rewriting or deleting files in a dependency package cache
+mutates shared package state outside the current recipe.
+- **后果**：Reproducibility and unrelated builds depend on task order.
+
+### 🚫 禁止 2
+
+- **模式**：`copy .*libX11\.la.*only|sanitize.*direct.*\.la`
+- **原因**：Libtool recursively follows transitive dependency_libs;
+a one-level repair leaves stale paths in libxcb or later
+archives.
+- **后果**：Configure and compilation pass until the final Libtool
+link, then fail on a moved or invalid archive.
+
+## 涉及软件
+
+Autotools/Libtool consumers of shared Conan dependencies
+where the dependency graph publishes .la metadata that
+still embeds package-cache paths.
+
+## 相关模式
+
+- **相似模式**：[E236](E236.md)
+
+---
+*条目 E522 · 更新 2026-08-19 · 知识库同步生成物*

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

@@ -0,0 +1,60 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E523: Go 链接器 fallocate() 在 HMDFS/tmpfs 上返回 EACCES 导致链接失败
+
+> **严重度**: 🔴 blocking | **分类**: toolchain | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+mapping output file failed: permission denied
+fallocate.*EACCES
+go tool link.*permission denied
+```
+
+## 根因
+
+Go 链接器 (cmd/link) 在写入输出文件时调用 fallocate() 预分配空间。OHOS 的 HMDFS 和 tmpfs 文件系统不支持 fallocate，返回 EACCES (errno=13)。Go 链接器只忽略 ENOTSUP/EPERM，不忽略 EACCES，导致链接失败。
+
+## 验证命令
+
+```bash
+echo '#include <fcntl.h>' > /tmp/t.c && echo 'int main(){int fd=open("/tmp/t",O_CREAT|O_RDWR,0644);return fallocate(fd,0,0,4096);}' >> /tmp/t.c && clang /tmp/t.c -o /tmp/t && /tmp/t 2>&1; echo $?
+```
+
+## 解决方案
+
+**toolexec-wrapper**：创建 toolexec 包装器脚本，拦截 go build 的链接步骤，将链接器输出重定向到 /dev/shm（支持 fallocate），链接完成后再复制回原路径
+
+```bash
+go build -toolexec $HOME/tmp/toolexec_wrapper.sh -o <binary> <package>
+```
+
+## 回退方案
+
+**patch-go-source**：修改 GOROOT/src/cmd/link/internal/ld/outbuf_mmap.go，在 fallocate 错误忽略列表中添加 syscall.EACCES，然后重建链接器
+
+```bash
+sed -i 's/errNoFallocate/errNoFallocate \&\& err != syscall.EACCES/' $GOROOT/src/cmd/link/internal/ld/outbuf_mmap.go
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`LD_PRELOAD.*fallocate`
+- **原因**：Go 使用 syscall 直接调用 fallocate，不经过 libc，LD_PRELOAD 无法拦截
+- **后果**：浪费时间调试 LD_PRELOAD 方案，最终无效
+
+## 涉及软件
+
+所有在 OHOS 上使用 Go 工具链编译的 Go 项目（go build/go install/go test 等）
+
+## 相关模式
+
+- **相似模式**：[E002](E002.md)
+
+---
+*条目 E523 · 更新 2026-08-19 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E524: Autotools configure 反复报 C compiler cannot create executables / 依赖缺失：检查共享 SYS_PREFIX 注入污染与逐项 REQUIRED 依赖
+
+> **严重度**: 🟢 minor | **分类**: build-system, autotools, conan, dependency | **自动修复**: ❌
+
+---
+
+## 错误特征
+
+```
+C compiler cannot create executables
+checking whether the C compiler works\.\.\. no
+configure: error: \*\*\* .* support not found
+requires libjansson
+requires SQLite3
+uuid support not found
+Asterisk requires
+```
+
+## 根因
+
+两个叠加根因。(1) 依赖注入目标用了共享目录 SYS_PREFIX（如 /storage/Users/currentUser/usr/local，CI worker 与本地共享同一台机器文件系统）：CI 从制品仓下载的依赖包 revision 与本地不同（共享库版 vs 静态库版、.pc 布局不同），注入后污染共享目录 → clang 链接 conftest 时 -L/usr/local/lib 找到坏库 → C compiler cannot create executables；本地恰好有历史遗留正确库所以永远复现不了。(2) Asterisk 等 autotools 项目的 configure 逐项硬性 REQUIRED 依赖缺失即报错：libedit、uuid(e2fsprogs)、jansson(>=2.11)、sqlite3、libxml2(menuselect)、ncurses(tinfo)——本地共享目录有历史遗留所以之前能过，改私有 prefix 后真实暴露。
+
+## 验证命令
+
+```bash
+conan create <recipe> -pr:h=ohos-aarch64 -pr:b=ohos-aarch64 --build=missing && grep -E "C compiler works|uuid_generate_random|jansson >=|sqlite3_open|creating makeopts" build.log
+```
+
+## 解决方案
+
+**private-prefix-injection**：generate() 依赖注入目标改为 build_folder 私有 prefix（os.path.join(self.build_folder, "prefix")），不碰共享 /usr/local；同时按 configure 报错逐项补齐 REQUIRED 依赖（libedit/libxml2/ncurses/uuid(e2fsprogs)/jansson/sqlite3），sqlite3 包无 .pc 时生成 shim，jansson 只发布共享库按 .so 校验。work 目录直接用 build_folder 子目录，禁用 os.access(X_OK) 探测（HMDFS chmod 被忽略、权限固定 660，X_OK 恒 False）。
+
+```bash
+generate() 内 _ensure_dep_present(self._prefix(), ...) + configure 传 CPPFLAGS/LDFLAGS/PKG_CONFIG_PATH 指向私有 prefix
+```
+
+## 回退方案
+
+**shared-prefix-with-immutable-deps**：若必须用共享前缀，需保证注入库与制品仓包完全一致（同 revision/同布局）且共享目录状态可复现；否则 CI 与本地必然不一致。
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`os\.access\(.*X_OK|os\.path\.islink.*conftest`
+- **原因**：HMDFS 上 os.access(X_OK) 恒为 False（chmod 被忽略、权限固定 660），用于探测目录可执行性会永远失败 → 回退到 noexec 路径。
+- **后果**：work 目录回退到 CI 上不可执行的 $TMPDIR 派生路径 → conftest 无法生成 → C compiler cannot create executables。
+
+### 🚫 禁止 2
+
+- **模式**：`inject.*usr/local|SYS_PREFIX.*copy|_ensure_.*\(SYS_PREFIX`
+- **原因**：向共享 /usr/local 注入依赖库会污染其他协作者/CI worker 的构建环境，且 CI 与本地依赖包 revision 不一致。
+- **后果**：19 轮 CI 全部失败（C compiler cannot create executables），本地却永远无法复现。
+
+### 🚫 禁止 3
+
+- **模式**：`ac_cv_prog_cc_works=yes.*enough|只加.*ac_cv.*不补依赖`
+- **原因**：ac_cv_prog_cc_works=yes 只能跳过编译器检查，无法解决后续 configure 逐项 REQUIRED 依赖缺失（uuid/jansson/sqlite3 等）。
+- **后果**：configure 在 C compiler 检查后继续报 *** support not found，构建仍失败。
+
+## 涉及软件
+
+All autotools-based third-party libs adapted on HarmonyOS PC where generate() injects deps into a shared SYS_PREFIX, and all Asterisk-family modules (configure REQUIRES libedit/uuid/jansson/sqlite3/libxml2/ncurses).
+
+## 相关模式
+
+- **相似模式**：[E052](E052.md)、[E060](E060.md)
+
+---
+*条目 E524 · 更新 2026-08-22 · 知识库同步生成物*

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

@@ -0,0 +1,72 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# E525: OHOS 下 make 应统一 -j1：仓库 Makefile 模板（如 7zip）仍用 -j$(nproc) 需修正
+
+> **严重度**: 🟡 medium | **分类**: selinux, build-system, filesystem | **自动修复**: ✅ env-var-override | **原则**: [P013](../principles.md#P013)、[P014](../principles.md#P014)、[P020](../principles.md#P020)
+
+---
+
+## 错误特征
+
+```
+make.*-j.*hang
+make.*stuck
+FIFO.*Permission denied
+make.*-j.*nproc
+```
+
+## 根因
+
+鸿蒙 SELinux 策略禁止用户进程创建 FIFO，GNU make jobserver 依赖
+FIFO 传递并行令牌，make -j>1 会卡住或报错（E074）。仓库部分
+Makefile 型 recipe 模板（〈外部知识库归档〉 与 25.01
+conanfile.py）仍用 make -j$(nproc)，新 recipe 照抄会踩 FIFO 坑。
+
+## 验证命令
+
+```bash
+mkfifo /tmp/test_fifo 2>&1   # 应报 Permission denied
+```
+
+## 解决方案
+
+**force-j1**：Makefile 型 recipe 的 self.run 统一 make -j1；E074 增补模板不一致提示。
+
+```bash
+make lib -j1
+```
+
+## 回退方案
+
+**add-makeflags**：必须保留部分并行时用 MAKEFLAGS 禁用 jobserver（E074 fallback 同款），
+仍不可行则整体 -j1。
+
+```bash
+export MAKEFLAGS="--no-builtin-rules --no-builtin-variables -j1"
+```
+
+## 🚫 禁止策略
+
+### 🚫 禁止 1
+
+- **模式**：`make.*-j.*nproc`
+- **原因**：OHOS FIFO 权限限制使 jobserver 初始化失败，并行构建卡住/报错。
+- **后果**：编译进程永久挂起，占用资源不产出。
+
+### 🚫 禁止 2
+
+- **模式**：`把 jobserver 报错误判为编译命令错误去改 Makefile 目标`
+- **原因**：FIFO 是系统级限制，改 Makefile 目标不解决；且会污染上游构建。
+- **后果**：无谓修改 Makefile 且并行仍失败，浪费调试轮次。
+
+## 涉及软件
+
+OHOS 上所有使用 make -j>1 的 Autotools/CMake/Makefile 型 recipe
+
+## 相关模式
+
+- **相似模式**：[E074](E074.md)
+- **根因条目（应先修它们）**：[E074](E074.md)
+
+---
+*条目 E525 · 更新 2026-08-20 · 知识库同步生成物*