@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

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

@@ -0,0 +1,226 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# 鸿蒙 PC 适配原则库（20 条）
+
+> 原则被错误图谱条目引用（条目页元数据的「原则」列锚点跳转至此）。
+> level 语义：`critical`=自动拒绝含该模式的方案 / `high`=警告并记录 / `medium`=仅记录。
+
+<a id="P001"></a>
+
+### P001 · 禁止 --build/--host 绕过系统检测
+
+- **级别**：`critical`
+- **适用范围**：[E007](errors/E007.md), [E064](errors/E064.md)
+- **陈述**：鸿蒙是原生编译环境(aarch64)，不是交叉编译。
+使用 --build/--host 绕过 config.guess 会导致:
+cross_compiling=yes → AC_RUN_IFELSE 跳过 → config.h 错误
+- 🚫 禁止 1：模式 `--build=.*linux-|--host=.*linux-`；auto_reject: true；建议：使用 download-gnuconfig 或 patch-autotools-ohos.pl
+- 🚫 禁止 2：模式 `--build=.*gnu|--host=.*gnu`；auto_reject: true；建议：同上
+
+<a id="P002"></a>
+
+### P002 · conftest 必须能正常执行
+
+- **级别**：`critical`
+- **适用范围**：[E064](errors/E064.md), [E061](errors/E061.md), [E062](errors/E062.md), [E063](errors/E063.md), [E065](errors/E065.md)
+- **陈述**：configure 通过编译+执行 conftest 检测平台能力。
+鸿蒙上首次执行二进制需安全弹窗确认。
+弹窗超时 → configure 误判交叉编译 → 级联错误。
+- 🚫 禁止 1：模式 `cross.compiling=yes`；auto_reject: false；建议：先手动触发安全弹窗，再用 ac_cv_* 缓存变量
+
+<a id="P003"></a>
+
+### P003 · 修改生成文件必须保存为 .patch
+
+- **级别**：`high`
+- **适用范围**：[E007](errors/E007.md), [E008](errors/E008.md), [E063](errors/E063.md)
+- **陈述**：configure/Makefile/config.h 是 autotools 生成文件。
+sed 修改后必须存为 .patch，否则 distclean 后丢失。
+- 🚫 禁止 1：模式 `sed -i.*(configure|Makefile|config\.h)`；auto_reject: false；建议：确认 patches/ 目录有对应 .patch 文件
+
+<a id="P004"></a>
+
+### P004 · __OHOS__ 守卫是平台隔离标准写法
+
+- **级别**：`high`
+- **适用范围**：[E008](errors/E008.md), [E011](errors/E011.md), [E051](errors/E051.md), [E004](errors/E004.md), [E020](errors/E020.md)
+- **陈述**：#ifdef __OHOS__ 是 clang 自动定义的宏，精确唯一。
+禁止 #ifndef __linux__(排除BSD/macOS)和硬编码路径。
+- 🚫 禁止 1：模式 `#ifndef\s*__linux__`；auto_reject: true；建议：改为 #ifdef __OHOS__
+
+<a id="P005"></a>
+
+### P005 · 补丁必须可向上游提交
+
+- **级别**：`medium`
+- **适用范围**：[E008](errors/E008.md), [E039](errors/E039.md)
+- **陈述**：遵循上游编码风格。英文注释(HarmonyOS: reason格式)。
+不引入鸿蒙特有SDK/API依赖(除非绝对必要)。
+
+<a id="P006"></a>
+
+### P006 · CFLAGS hack 必须记录为技术债务
+
+- **级别**：`medium`
+- **适用范围**：[E005](errors/E005.md), [E011](errors/E011.md), [E032](errors/E032.md), [E033](errors/E033.md), [E063](errors/E063.md)
+- **陈述**：CFLAGS/CPPFLAGS/LDFLAGS 强制绕过编译错误时，
+必须在 notes.md 记录技术债务及期望的上游修复方式。
+
+<a id="P007"></a>
+
+### P007 · -Werror 禁用应精准到具体 warning 类别
+
+- **级别**：`medium`
+- **适用范围**：[E063](errors/E063.md)
+- **陈述**：禁止全局禁用 -Werror（如 CFLAGS="-Wno-error"）。
+应精准到具体的 warning 类别（如 -Wno-error=int-conversion）。
+全局禁用会掩盖真正的编译错误。
+
+<a id="P008"></a>
+
+### P008 · 未实现 syscall 必须调用前拦截
+
+- **级别**：`critical`
+- **适用范围**：[E051](errors/E051.md)
+- **陈述**：setreuid/setregid 的 SIGSYS 不可被 handler 捕获,
+进程直接终止(exit 159)。信号处理方案完全不可行。
+必须用 #ifdef __OHOS__ 在调用前 return ENOSYS。
+- 🚫 禁止 1：模式 `signal\(SIGSYS`；auto_reject: true；建议：用 #ifdef __OHOS__ 在调用前 return ENOSYS
+
+<a id="P009"></a>
+
+### P009 · RPATH 必须覆盖所有 NEEDED 库
+
+- **级别**：`high`
+- **适用范围**：[E042](errors/E042.md), [E019](errors/E019.md)
+- **陈述**：可移植包 RPATH 必须: 主程序→共享库→扩展模块,
+任何一层遗漏都会在目标机出现 ImportError。
+
+<a id="P010"></a>
+
+### P010 · 必须使用 LLVM 工具链
+
+- **级别**：`high`
+- **适用范围**：[E012](errors/E012.md), [E053](errors/E053.md)
+- **陈述**：鸿蒙 SDK 只有 LLVM/Clang。ar/ranlib/nm/strip 用 llvm-* 版本。
+C++ 编译器是 clang++ (无 cc1plus)。
+- 🚫 禁止 1：模式 `\bar\b(?!llvm-ar)`；auto_reject: false；建议：export AR=llvm-ar RANLIB=llvm-ranlib NM=llvm-nm
+
+<a id="P011"></a>
+
+### P011 · 补丁文件必须包含完整元数据 header
+
+- **级别**：`high`
+- **适用范围**：[E007](errors/E007.md), [E008](errors/E008.md), [E039](errors/E039.md), [E063](errors/E063.md)
+- **陈述**：每个补丁必须含 Source-Commit(被改文件的原始commit)、
+Modification-Layer(修改层级①②③)、Knowledge-Ref(关联知识)。
+缺失则无法追溯来源和复现补丁。
+- 🚫 禁止 1：模式 `(diff|patch).*无Source-Commit|From:.*\n(?!(Description|Origin|Upstream|Source-Commit))`；auto_reject: false；建议：补丁 header 必须包含: Description/Origin/Upstream/Source-Commit/Modification-Layer/Knowledge-Ref
+
+<a id="P012"></a>
+
+### P012 · 静态库优先原则（系统库冲突防护）
+
+- **级别**：`high`
+- **适用范围**：[E042](errors/E042.md), [E019](errors/E019.md), [E067](errors/E067.md)
+- **陈述**：鸿蒙系统关键组件(/bin/zsh 等)依赖系统共享库。
+用户编译的同名共享库会覆盖系统库→系统不稳定。
+判断标准: ldd /bin/xxx | grep <库名> → 有输出则必须用 --without-shared。
+- 🚫 禁止 1：模式 `--with-shared(?!.*无系统依赖确认)`；auto_reject: false；建议：先检查系统是否已有同名库: ldd /bin/* | grep <库名>；有则用 --without-shared 编译静态库
+
+<a id="P013"></a>
+
+### P013 · 平台限制必须降级而非绕过
+
+- **级别**：`high`
+- **适用范围**：[E074](errors/E074.md), [E046](errors/E046.md), [E048](errors/E048.md), [E055](errors/E055.md), [E057](errors/E057.md)
+- **陈述**：鸿蒙平台限制(FIFO/SELinux/HMDFS)是系统级行为差异，
+不因重试而改变。遇到此类限制必须降级到可用方案(如单线程/skip-test/wrapper)，
+禁止反复重试或忽略错误继续执行。
+- 🚫 禁止 1：模式 `反复重试.*make -j|忽略.*Permission denied.*继续|skipIf.*False`；auto_reject: true；建议：识别限制类型后选择对应降级方案
+
+<a id="P014"></a>
+
+### P014 · 环境变量与构建系统语义冲突陷阱
+
+- **级别**：`medium`
+- **适用范围**：[E075](errors/E075.md), [E002](errors/E002.md), [E074](errors/E074.md)
+- **陈述**：某些环境变量(C_INCLUDE_PATH/LD_LIBRARY_PATH等)与pkg-config/make等
+构建工具存在语义冲突。设置这些变量可能反而导致问题。
+应优先使用构建系统原生机制(PKG_CONFIG_PATH/RPATH/Makefile变量)。
+- 🚫 禁止 1：模式 `同时设置 C_INCLUDE_PATH 和 PKG_CONFIG_PATH`；auto_reject: false；建议：unset C_*_INCLUDE_PATH / LIBRARY_PATH，仅用 PKG_CONFIG_PATH
+
+<a id="P015"></a>
+
+### P015 · 内核 syscall 行为差异必须源码适配
+
+- **级别**：`high`
+- **适用范围**：[E076](errors/E076.md), [E008](errors/E008.md), [E051](errors/E051.md), [E022](errors/E022.md), [E025](errors/E025.md)
+- **陈述**：鸿蒙内核对部分 syscall(fstat/lseek/setreuid/sigaction等)的返回值
+与 Linux glibc 不同。这类差异无法通过环境变量或编译参数绕过，
+必须在源码中用 #ifdef __OHOS__ 守卫做兼容处理。
+- 🚫 禁止 1：模式 `忽略.*EACCES.*继续执行|suppress.*syscall.*error`；auto_reject: true；建议：用 #ifdef __OHOS__ 在调用处做兼容处理
+
+<a id="P016"></a>
+
+### P016 · HMDFS 文件系统限制必须用替代方案
+
+- **级别**：`critical`
+- **适用范围**：[E050](errors/E050.md), [E073](errors/E073.md), [E079](errors/E079.md), [E080](errors/E080.md), [E018](errors/E018.md)
+- **陈述**：HMDFS(HarmonyOS 分布式文件系统)不支持符号链接和硬链接创建。
+所有 ln -s / ln / symlink() 调用都会失败。
+必须用 cp 复制、wrapper 脚本、makedirs 或 monkey-patch 替代。
+- 🚫 禁止 1：模式 `ln -s.*HMDFS|symlink.*force|os\.symlink.*ignore.*OSError`；auto_reject: true；建议：cp 复制替代软链接；wrapper 脚本替代 bin 软链接；try/except OSError
+
+<a id="P017"></a>
+
+### P017 · ELF 签名必须与运行环境匹配
+
+- **级别**：`critical`
+- **适用范围**：[E083](errors/E083.md), [E077](errors/E077.md)
+- **陈述**：HarmonyOS 的 musl 动态链接器和 BiSheng JDK 在加载 .so 时
+校验 ELF 签名(.codesign 段)。系统预装的二进制拥有系统级签名，
+用户编译的二进制使用 binary-sign-tool -selfSign 自签名。
+两种签名体系不兼容：自签名的 .so 在系统 JDK 下加载失败(Permission denied)，
+反之亦然。必须确保同一运行环境中所有 ELF 文件使用同一签名体系。
+- 🚫 禁止 1：模式 `chmod.*777.*绕过签名|skip.*sign.*elf`；auto_reject: true；建议：拷贝 JDK 到用户路径后批量签名，或使用 sign-elf --batch 统一签名
+
+<a id="P018"></a>
+
+### P018 · JNI 库必须与 JDK 签名体系一致且平台标识正确
+
+- **级别**：`high`
+- **适用范围**：[E084](errors/E084.md), [E083](errors/E083.md)
+- **陈述**：Java JNI 库在鸿蒙上需要特殊处理：
+1. 平台标识为 harmonyos-aarch64（非 linux-aarch64），
+   JAR 中的 native library 路径必须匹配
+2. .so 文件必须与运行 JDK 使用同一 ELF 签名体系（见 P-SIGN-001）
+3. 静态链接依赖（如 libffi.a）避免运行时依赖
+4. 无 ant/maven 时可用 javac+clang+jar 手动构建
+- 🚫 禁止 1：模式 `linux-aarch64.*only|harmonyos.*fallback.*linux`；auto_reject: false；建议：JAR 同时包含 harmonyos-aarch64 和 linux-aarch64 路径以兼容
+
+<a id="P019"></a>
+
+### P019 · 可移植打包必须包含 post-install 签名步骤
+
+- **级别**：`high`
+- **适用范围**：[E077](errors/E077.md), [E042](errors/E042.md)
+- **陈述**：预编译包在目标机上解压后，ELF 文件可能被修改（patchelf RPATH、strip 等），
+导致签名失效。公共安装脚本必须包含重新签名步骤。
+任何修改 ELF 的操作后都必须重新签名。
+- 🚫 禁止 1：模式 `patchelf.*without.*re-sign|strip.*without.*re-sign`；auto_reject: true；建议：公共安装脚本末尾调用 sign-elf --batch 重新签名所有 ELF
+
+<a id="P020"></a>
+
+### P020 · HMDFS 不支持硬链接和 FIFO，必须用替代方案
+
+- **级别**：`high`
+- **适用范围**：[E079](errors/E079.md), [E018](errors/E018.md), [E074](errors/E074.md)
+- **陈述**：HMDFS(HarmonyOS 分布式文件系统)不支持硬链接(ln)和 FIFO(mkfifo)。
+ccache、cargo、pnpm、git 等工具内部使用硬链接或 FIFO，
+在 HMDFS 上会报 Operation not permitted。
+必须用符号链接、文件拷贝或环境变量切换到兼容模式替代。
+- 🚫 禁止 1：模式 `ln.*HMDFS|mkfifo.*HMDFS|hard.*link.*force`；auto_reject: true；建议：用 cp 替代硬链接；设置 CCACHE_NOLINK=1 等
+
+---
+*原则库 · 知识库同步生成物*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/prescan/README.md

@@ -0,0 +1,33 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# 预编译源码风险扫描（prescan）
+
+本目录为**生成物**（知识库同步管道打包而来），包含：
+
+| 文件 | 说明 |
+|---|---|
+| `pre_scan.py` | 预编译源码风险扫描器（纯标准库，Python 3 直跑） |
+| `prescan-rules.yaml` | 规则集：上游 24 条人工规则 + 知识图谱 `prescan_pattern` 预派生规则（见下表） + 本地手维护规则 3 条（PSCAN-LOCAL-*） |
+| `local-rules.yaml` | **本地手维护规则通道（非生成物）**：PSCAN-LOCAL-*，sync 时并入 prescan-rules.yaml；不进 manifest、不受 --check 判定。新增本地规则改它，改完重跑 `npm run sync:kb` 生效 |
+
+## 用法
+
+```bash
+python3 prescan/pre_scan.py <源码目录> --rules prescan/prescan-rules.yaml --no-writeback
+```
+
+- `--rules` 只接受**单个**规则文件，本目录的 `prescan-rules.yaml` 已是合并后的完整规则集。
+- 建议带 `--no-writeback`：默认模式会把命中数回填进规则文件，改动生成物会导致
+  `npm run sync:kb -- --check` 报漂移。
+- 扫描器另有一组内置 musl 缺失函数规则（`PSCAN-MUSL-FUNC-*`），不依赖规则文件，恒开。
+
+## 派生规则一览
+
+| 规则 | severity | 对应条目 | 说明 |
+|---|---|---|---|
+| PSCAN-KB-E013 | medium | [E013](../knowledge/errors/E013.md) | 动态链接错误（-ldl 缺失） |
+| PSCAN-KB-E019 | critical | [E019](../knowledge/errors/E019.md) | 库加载失败（运行时） |
+| PSCAN-KB-E037 | medium | [E037](../knowledge/errors/E037.md) | shebang 兼容性（/usr/bin/env 缺失 + 可移植性） |
+| PSCAN-KB-E465 | critical | [E465](../knowledge/errors/E465.md) | Route upstream dlopen/ctypes tests past the OHOS worker loader boundary with an embedded-Python launcher that links the library under test as its own NEEDED |
+
+知识源 commit：`70926181cd`。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/prescan/local-rules.yaml

@@ -0,0 +1,63 @@
+# local-rules.yaml — 本地预扫描规则（手维护，**非生成物**）
+#
+# 定位：本地新增扫描规则的**正式通道**。知识源规则集只读，其条目的 prescan_pattern
+# 覆盖率极低——门禁覆盖率的增量全靠本文件。同步时由 sync-kb.mjs 三路合并进生成物
+# prescan-rules.yaml（上游规则集原文 + 知识图谱 prescan_pattern 派生 + 本文件原文），
+# 运行时只需 `prescan/prescan-rules.yaml` 一个文件。
+#
+# 纪律：
+#  - 本文件**不进 manifest、不受 --check 多出/漂移判定**（与 knowledge/local-errors/ 同型豁免）；
+#    但改动后必须重跑 `npm run sync:kb`（需 PC_KB_ROOT）才会并入生成物，否则本地规则不生效。
+#  - schema 与上游规则集相同；id 一律 `PSCAN-LOCAL-*` 前缀；kb_ref 指向本地 L 条目
+#    （如 `L009`），description 里同样注明出处 L 编号。
+#  - 扫描器逐行匹配（每行独立 search，无跨行模式、行尾 CR 已被剥离）——只收
+#    「单行可静态 grep 的源码模式」，没有合适模式的条目不硬凑。
+#  - hit_count 保持 0：扫描器回填命中数会改动本文件，使用侧请带 --no-writeback。
+version: 1
+last_updated: 2026-10-13
+
+rules:
+  # ── 本地沉淀派生（L 系列） ──
+  - id: PSCAN-LOCAL-001
+    category: musl_compat
+    severity: medium
+    pattern: 'iconv_open\s*\(\s*"(GB18030|GBK|GB2312|BIG5)"'
+    scope_globs: ['*.c', '*.h', '*.cc', '*.cpp']
+    description: "[L009] iconv_open 以 CJK 编码为输出方向（to=CJK）：OHOS musl 分支裁剪了 CJK 编码方向转换表，运行期 EINVAL"
+    solution_hint: "解码方向（from=CJK）正常；编码方向需改用其他转换实现或在外部完成转换，详见 local-errors/L009.md"
+    kb_ref: "L009"
+    auto_generated: false
+    hit_count: 0
+
+  - id: PSCAN-LOCAL-002
+    category: build_hygiene
+    severity: high
+    pattern: '(git\s+apply|\bpatch\s+-p\d).*\|\|\s*(echo|true)'
+    scope_globs: ['*.sh', 'Makefile*', '*.mk', '*.py', '*.ps1']
+    description: "[L031] 补丁应用失败被 || echo/|| true 静默掩盖——补丁没打进产物但构建绿、patches_applied 声称已应用"
+    solution_hint: "补丁应用必须 fail-fast（set -e / exit 1），补丁写入前先 git apply --check 全链往返验证，详见 local-errors/L031.md"
+    kb_ref: "L031"
+    auto_generated: false
+    hit_count: 0
+
+  - id: PSCAN-LOCAL-003
+    category: platform_ipc
+    severity: medium
+    pattern: '\bsem_open\s*\('
+    scope_globs: ['*.c', '*.h', '*.cc', '*.cpp']
+    description: "[L029] sem_open 命名 POSIX 信号量在 app 域受限（/dev/shm namefs MAC）；file-scope static 对象在 static-init 期调用会在 main() 前 terminate"
+    solution_hint: "static 对象改 Meyers 单例（函数局部 static）延迟构造；app 域内避免命名信号量，详见 local-errors/L029.md"
+    kb_ref: "L029"
+    auto_generated: false
+    hit_count: 0
+
+  - id: PSCAN-LOCAL-004
+    category: platform_window
+    severity: medium
+    pattern: '\bnew\s+BrowserWindow\s*\('
+    scope_globs: ['*.js', '*.mjs', '*.cjs']
+    description: "[L063] Electron 主进程创建 BrowserWindow（多窗口形态匹配必查项）：若存在应用内第二次及以上 new BrowserWindow()（文件多开/新建窗口类功能）且主进程无 new Tray(——无托盘形态下模板默认 processMode=ATTACH_TO_STATUS_BAR_ITEM + startupVisibility 启动新 UIAbility 前置不满足（调用方须先添加状态栏 item），真机 16000067 新建窗口整体失效（Ctrl+N 与菜单点击均无反应，非系统占用快捷键）。适配必做项：AppWindowAdapter.createWindow 的 StartOptions 成对删除 processMode 与 startupVisibility 走默认 ProcessMode"
+    solution_hint: "先识别形态：主进程有 new Tray( → 带托盘，多窗口保持模板默认；无 new Tray( → 无托盘，AppWindowAdapter.createWindow 成对删除 processMode 与 startupVisibility（只删一个仍 16000067），详见 local-errors/L063.md"
+    kb_ref: "L063"
+    auto_generated: false
+    hit_count: 0