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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/references/operations/ptrace-alternatives.md

@@ -0,0 +1,306 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# 鸿蒙系统 ptrace 限制及替代方案
+
+> **更新日期**: 2026-03-23  
+> **测试环境**: HarmonyOS HongMeng Kernel 1.11.0 aarch64  
+> **SELinux 上下文**: `u:r:adhoc_bin:s0`
+
+---
+
+## 1. 问题概述
+
+strace 依赖 ptrace 系统调用，但鸿蒙系统的 SELinux 策略在内核级别完全封锁了 ptrace，
+导致 strace 编译后无法执行实际追踪。sudo 和 setenforce 均无法绕过。
+
+---
+
+## 2. 封锁层级分析
+
+### 2.1 权限封锁范围
+
+| 操作 | 普通用户 | sudo | 说明 |
+|------|:--------:|:----:|------|
+| `ptrace(PTRACE_TRACEME)` | ❌ EACCES | ❌ kill EACCES | 内核主动终止进程 |
+| `/sys/fs/selinux/*` | ❌ | ❌ | 完全不可读 |
+| `setenforce 0` | ❌ | ❌ | Permission denied |
+| `/sys/kernel/security/*` | ❌ | ❌ | 完全不可读 |
+| `/sys/kernel/debug/tracing/` | ❌ | ❌ | debugfs 已挂载但不可访问 |
+| `/proc/self/syscall` | ❌ 不存在 | ❌ 不存在 | 内核未导出此文件 |
+| `LD_PRELOAD` | ✅ | ✅ | 可用 |
+
+### 2.2 封锁原理
+
+```
+用户进程 (adhoc_bin:s0)
+    │
+    ├─► strace 调用 ptrace(PTRACE_TRACEME)
+    │       └─► 内核 LSM 检查 → 无 allow 规则 → EACCES
+    │
+    ├─► sudo strace
+    │       └─► 仍在受限域 → kill EACCES（进程被杀）
+    │
+    └─► sudo setenforce 0
+            └─► SELinux 接口不可写（系统级锁定）
+```
+
+**结论**：这不是简单的 SELinux boolean 或 DAC 权限问题，而是系统级的硬性安全策略。
+
+---
+
+## 3. 替代方案调查
+
+### 3.1 方案总览
+
+| 方案 | 原理 | 需要 ptrace? | 鸿蒙可用 | 适用场景 |
+|------|------|:------------:|:--------:|----------|
+| ftrace | 内核 tracepoint | 否 | ❌ | 内核调试 |
+| perf | perf_event 子系统 | 否 | ❌ | 性能分析 |
+| eBPF/bpftrace | 内核虚拟机 | 否 | ❌ | 高级追踪 |
+| auditd | 内核审计框架 | 否 | ❌ | 安全审计 |
+| **ltrace** | **动态库 hook (ptrace)** | **是** | **❌** | **库函数追踪** |
+| **latrace** | **LD_AUDIT 接口** | **否** | **待验证** | **库函数追踪** |
+| **LD_PRELOAD** | **libc 函数拦截** | **否** | **✅** | **用户态函数追踪** |
+
+### 3.2 各方案详情
+
+#### ❌ ftrace（不可用）
+- debugfs 已挂载，但 `/sys/kernel/debug/tracing/` 目录权限被 SELinux 封锁
+- 即使 sudo 也无法读取 tracing 目录
+- 需要系统级权限才能解锁
+
+#### ❌ perf（不可用）
+- 系统未安装 perf
+- `perf_event_paranoid` 不可读，可能也被锁定
+
+#### ❌ eBPF / bpftrace（不可用）
+- 未安装相关工具（bpftool、bpftrace、bcc）
+- `/sys/fs/bpf` 不可访问
+
+#### ❌ ltrace（理论上也不可用）
+- ltrace 虽然追踪的是库函数调用，但底层仍依赖 ptrace
+- 在标准 Linux 上 ltrace 使用 ptrace 来插入断点和读取参数
+- **鸿蒙上 ltrace 同样会被 SELinux 阻止**（但尚未实际测试编译/运行）
+
+#### ❓ latrace（待验证）
+- 原理：利用 glibc 的 `LD_AUDIT` 接口（`la_symbind*` 系列回调）
+- **不依赖 ptrace**，理论上可以在鸿蒙上工作
+- 但 musl libc 可能不支持 LD_AUDIT 接口
+- 来源：https://latrace.sourceforge.net/
+
+#### ✅ LD_PRELOAD（已验证可用）
+
+**原理**：通过环境变量 `LD_PRELOAD` 加载自定义共享库，用 `dlsym(RTLD_NEXT, ...)` 
+获取原始函数指针，在调用前后插入日志代码。
+
+**鸿蒙实测**：
+```
+# 追踪 wc -l /dev/null
+LD_PRELOAD=$TMPDIR/libhook.so wc -l /dev/null
+
+# 输出日志：
+open("/dev/null", 0x0)
+read(4, 262144) = 0
+```
+
+---
+
+## 4. LD_PRELOAD 使用指南
+
+### 4.1 基础 hook 库
+
+以下是一个可用的基础 hook 库实现：
+
+```c
+// hook.c - 基础 libc 函数拦截库
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <dlfcn.h>
+#include <string.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+static FILE *logfile = NULL;
+
+static void init_log(void) {
+    if (!logfile) {
+        const char *tmpdir = getenv("TMPDIR");
+        if (!tmpdir) tmpdir = "/tmp";
+        char path[512];
+        snprintf(path, sizeof(path), "%s/hook_trace.log", tmpdir);
+        logfile = fopen(path, "a");
+        setvbuf(logfile, NULL, _IONBF, 0);  // 无缓冲，实时输出
+    }
+}
+
+// 拦截 open()
+typedef int (*orig_open_t)(const char *pathname, int flags, ...);
+int open(const char *pathname, int flags, ...) {
+    orig_open_t orig = dlsym(RTLD_NEXT, "open");
+    init_log();
+    if (logfile) fprintf(logfile, "open(\"%s\", 0x%x)\n", pathname, flags);
+    return orig(pathname, flags, 0);
+}
+
+// 拦截 openat()
+typedef int (*orig_openat_t)(int dirfd, const char *pathname, int flags, ...);
+int openat(int dirfd, const char *pathname, int flags, ...) {
+    orig_openat_t orig = dlsym(RTLD_NEXT, "openat");
+    init_log();
+    if (logfile) fprintf(logfile, "openat(%d, \"%s\", 0x%x)\n", dirfd, pathname, flags);
+    return orig(dirfd, pathname, flags, 0);
+}
+
+// 拦截 read()（过滤 stdin/stdout/stderr）
+typedef ssize_t (*orig_read_t)(int fd, void *buf, size_t count);
+ssize_t read(int fd, void *buf, size_t count) {
+    orig_read_t orig = dlsym(RTLD_NEXT, "read");
+    ssize_t ret = orig(fd, buf, count);
+    init_log();
+    if (logfile && fd > 2) fprintf(logfile, "read(%d, %zu) = %zd\n", fd, count, ret);
+    return ret;
+}
+
+// 拦截 write()（过滤 stdin/stdout/stderr）
+typedef ssize_t (*orig_write_t)(int fd, const void *buf, size_t count);
+ssize_t write(int fd, const void *buf, size_t count) {
+    orig_write_t orig = dlsym(RTLD_NEXT, "write");
+    init_log();
+    if (logfile && fd > 2) fprintf(logfile, "write(%d, %zu)\n", fd, count);
+    return orig(fd, buf, count);
+}
+
+// 拦截 execve()
+typedef int (*orig_execve_t)(const char *pathname, char *const argv[], char *const envp[]);
+int execve(const char *pathname, char *const argv[], char *const envp[]) {
+    orig_execve_t orig = dlsym(RTLD_NEXT, "execve");
+    init_log();
+    if (logfile) {
+        fprintf(logfile, "execve(\"%s\"", pathname);
+        for (int i = 0; argv && argv[i]; i++) fprintf(logfile, ", \"%s\"", argv[i]);
+        fprintf(logfile, ")\n");
+    }
+    return orig(pathname, argv, envp);
+}
+```
+
+### 4.2 编译和使用
+
+```bash
+# 编译 hook 库
+clang -shared -fPIC -o $TMPDIR/libhook.so hook.c -ldl
+
+# 使用：追踪任意命令
+rm -f $TMPDIR/hook_trace.log
+LD_PRELOAD=$TMPDIR/libhook.so <command> [args...]
+
+# 查看追踪日志
+cat $TMPDIR/hook_trace.log
+```
+
+### 4.3 LD_PRELOAD 的局限性
+
+| 能力 | strace (ptrace) | LD_PRELOAD |
+|------|:---------------:|:----------:|
+| 拦截 libc 函数（open/read/write...） | ✅ | ✅ |
+| 拦截直接系统调用（`syscall()` / 内联汇编） | ✅ | ❌ |
+| 追踪已运行的进程（`strace -p PID`） | ✅ | ❌ |
+| 追踪静态链接程序 | ✅ | ❌ |
+| 查看完整内核返回值和寄存器 | ✅ | ❌ |
+| 追踪信号 | ✅ | ❌ |
+| 无需修改目标程序 | ✅ | ✅ |
+| 需要特殊权限 | ❌ | ❌ |
+
+### 4.4 扩展建议
+
+可以继续 hook 的常用函数：
+
+```c
+// 文件操作
+close(), unlink(), rename(), stat(), fstat(), lstat()
+readlink(), symlink(), chmod(), chown(), mkdir(), rmdir()
+
+// 内存操作
+mmap(), munmap(), mprotect(), brk()
+
+// 网络操作（需 #include <sys/socket.h>）
+socket(), bind(), connect(), listen(), accept(), send(), recv()
+
+// 进程操作
+fork(), clone(), waitpid(), getpid(), getppid()
+
+// 信号
+signal(), sigaction()
+```
+
+---
+
+## 5. 已知工具对比
+
+### 5.1 ltrace（需要 ptrace，鸿蒙不可用）
+
+| 项目 | 说明 |
+|------|------|
+| 官网 | http://www.ltrace.org/ |
+| 仓库 | https://sourceware.org/git/?p=ltrace.git |
+| 许可 | GPL-2.0 |
+| 原理 | 通过 ptrace 插入断点，追踪动态库函数调用 |
+| ptrace 依赖 | **是**（在 PLT/GOT 层面插入断点需要 ptrace） |
+| 鸿蒙可用 | ❌（ptrace 被封锁） |
+| 备注 | 虽然追踪的是库函数，但底层机制仍依赖 ptrace |
+
+### 5.2 latrace（可能可用，待验证）
+
+| 项目 | 说明 |
+|------|------|
+| 官网 | https://latrace.sourceforge.net/ |
+| 许可 | GPL-2.0 |
+| 原理 | 利用 glibc 的 LD_AUDIT 接口（la_symbind* 回调） |
+| ptrace 依赖 | **否** |
+| 鸿蒙可用 | ❓（需测试 musl 是否支持 LD_AUDIT） |
+| 备注 | musl libc 可能不支持 LD_AUDIT，如不支持则无法使用 |
+
+### 5.3 手动 LD_PRELOAD hook（已验证可用）
+
+| 项目 | 说明 |
+|------|------|
+| 实现 | 自定义共享库 + dlsym(RTLD_NEXT) |
+| ptrace 依赖 | **否** |
+| 鸿蒙可用 | ✅ 已验证 |
+| 优势 | 简单、可控、可定制 |
+| 劣势 | 需要为每个函数手动编写 hook；无法追踪直接系统调用 |
+
+---
+
+## 6. 总结与建议
+
+### 当前鸿蒙环境下的最佳实践
+
+```
+需要调试时：
+    │
+    ├─► 追踪库函数调用 → LD_PRELOAD hook 库 ✅
+    │       - 适用于：排查文件操作、IO、进程创建等
+    │       - 限制：无法追踪静态链接程序和直接系统调用
+    │
+    ├─► 追踪库函数调用 → 尝试编译 ltrace/latrace ❓
+    │       - ltrace：需 ptrace，预计不可用
+    │       - latrace：需 LD_AUDIT，musl 支持待确认
+    │
+    └─► 内核级追踪 → 无可用方案 ❌
+            - ftrace/perf/eBPF 全被 SELinux 封锁
+            - 需要系统级权限或 OpenHarmony 官方支持
+```
+
+### 对 MISSING_TOOLS.md 的影响
+
+strace 状态已标记为 `partial`（编译成功但 ptrace 受限），建议：
+1. 保留 strace 编译档案，记录 ptrace 限制
+2. LD_PRELOAD hook 库作为实际可用的调试工具
+3. 如需更完善的工具，可考虑编写一个 strace 风格的 LD_PRELOAD 包装器
+
+---
+
+*文档版本: 1.0*  
+*最后更新: 2026-03-23*  
+*关联档案: archives/s/strace/6.19/*

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pc-node-library
+description: 仅针对 ecosystem=nodejs（兼容历史 node）且 kind=library 的 Node.js 三方库，判定独立 Node/Electron 使用模式，交付 03/06 必需 demo 并按宿主验收；不接管应用、CLI、tool、其他生态。
+---
+
+# Node.js 三方库适配
+
+仅当 `01-scan.library.ecosystem ∈ {nodejs,node}` 且 `kind=library` 使用以下规则；01 尚未落盘时以本轮源码识别结果为准。重新扫描若改判为其他类型，停止应用本专项。其他库和应用沿用原流程。
+
+本 Skill 是专项规则入口：只细化扫描字段、工程选择、用例适用性、取证与汇总，不放宽阶段职责、真实断言和独立验收要求。命中本专项后，用对应参考替换阶段 agent 的默认单工程路径、接线及结果收集方式；没有涉及的步骤仍遵循阶段 agent。应用专属人工检查点不适用于库 demo。
+
+## 共同约束
+
+- `node_library.runtime_mode` 决定必需宿主：`node-and-electron` 为 Node + Electron，`electron-only` 为 Electron。`host_runtime` 仍表示主要宿主，不能单独免除另一宿主。模式缺失时补扫 01，保留历史源码、工程和证据。
+- `state.library_examples` 是必需 demo 清单，`node_library_demos` 是完成情况。`verify_carriers` 表示加载路径，不是全部工程。目录与结果命令由 [工程参考](references/examples.md) 定义。
+- 普通用例默认在所有必需宿主运行；Electron 专属功能保留在共同名册，只分配适用宿主。环境不可用记 blocked，不能改适用性、删除功能或借用 `platform_exclusive` 豁免。
+- 03→06 只传已验证工程配方；03 用例来自 02，06 用例来自 05，不复制套件、结果或 HAP。06 使用配置预检和工具汇总，详见阶段参考。
+- 结果按工程/宿主独立保存，完整成功须每个必需工程的适用名册真跑且通过。纯 JS、主宿主通过或预算不足均不免除 Electron；资源不足如实报告部分完成。缺完成标记、仅启动、空函数均不是通过。
+
+## 固定工程入口
+
+新建 Node/Electron Demo 使用 [固定工程工具](references/managed-projects.md)，先标准工程 probe，再接库和测试。03/06 共用版本化骨架，配方承载运行参数及依赖映射；06 通过 inherit 取得本库已验证 03 配方。已有未托管工程保留，不自动覆盖或使历史证据失效。
+
+## 当前阶段入口
+
+先读共同约束，再按调用方给的阶段和实际角色读取下表对应章节；仅有阶段号 3 不足以区分开发与独立验收。没有 Skill 工具时，通过 Read 读取本文件，参考路径相对于本文件所在目录解析。
+
+| 阶段 / 角色 | 必读参考 |
+|---|---|
+| 01 扫描（含首次识别和历史补扫） | [扫描](references/stages.md#scan) |
+| 02 基线设计、05 功能用例设计 | [用例设计](references/stages.md#cases) |
+| 03 开发与返修 | [开发](references/stages.md#develop) + [工程与取证](references/examples.md) |
+| 03 独立验收 | [独立验收](references/stages.md#verify) + [工程与取证](references/examples.md) |
+| 04 汇总 | [汇总](references/stages.md#summary) |
+| 06 功能验证与恢复 | [功能验证](references/stages.md#test) + [工程与取证](references/examples.md) |
+
+## 按需技术参考
+
+| 工作 | 参考 |
+|---|---|
+| 包识别与运行依赖 | [包识别](references/package-and-patches.md) |
+| 含 .node、FFI、SQLite 等原生依赖；原生加载/调用/回调失败 | 必读 [原生扩展](references/native-addon.md)，再按其中入口读取专项诊断 |
+| Electron addon | `pc-knowledge-base` 的 `electron/addon-build.md` |
+| 03/06 启动、装机或用例失败；证据漂移 | [自动恢复与已验证配方](references/recovery.md) |
+| Electron 加载、权限与启动 | [故障定位](references/electron-oh-troubleshooting.md) |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/references/electron-oh-troubleshooting.md

@@ -0,0 +1,57 @@
+# Electron-OH API 与故障定位
+
+仅用于 通用流程中的 Electron 库验证。资料核对日期：2026-09-14。下面是检索入口和诊断方法，不是某个库已经通过的证明。
+
+## 资料来源与版本
+
+- 用户提供的 [鸿蒙化 Electron 开发问题集](https://developer.huawei.com/consumer/cn/forum/topic/0204203363319759021)：本次网页读取仅得到导航，浏览器加载超时，未核实正文；遇到具体错误可再查，不能引用未读到的条目作结论。
+- [CPF-Electron 鸿蒙化指导](https://gitcode.com/CPF-Electron/Electron)：已核对 HAP 资源、平台分支、窗口和权限说明。
+- [API 模块目录](https://gitcode.com/CPF-Electron/Electron/blob/main/docs/api/README.md)：按模块查支持范围，再核对目标发行版实现。main 分支不是当前工程 的版本承诺；不要把整个模块的“支持数”当作每个调用签名、选项和生命周期都可用。
+- [HNP 与 fork 指南](https://gitcode.com/CPF-Electron/Electron/blob/main/docs/hnp-packaging-guide/README.md)：应用内可执行文件与签名、HNP、子进程集成。历史示例中的 SDK 修改、硬编码路径与当前工具链可能不同。
+- 上游 [进程模型](https://www.electronjs.org/docs/latest/tutorial/process-model)、[sandbox](https://www.electronjs.org/docs/latest/tutorial/sandbox) 解释语义；鸿蒙支持范围仍查目标版本。
+
+排查前记录 实际运行时来源、实际 process.versions、platform/arch、设备系统版本、debug/release、模板与引擎版本。先查项目内锁定版本文档/声明/实现，缺少时使用上述在线资料并标明分支。不要为解决库用例失败自动升级运行时或混用模板。
+
+## API 定位
+
+从 API 目录进入对应模块，记录具体成员、选项、调用进程、时机、文档版本和最小真机复现。以下是库验证的优先检查点，不能仅由存在同名函数判通过：
+
+| 场景 | 重点 API / 行为 | 需验证的语义 |
+|---|---|---|
+| 启动与路径 | app.whenReady、app.getPath、app.getName；process.resourcesPath | 初始化是否赶在 ready 前；名称来自哪个应用元数据；包资源与可写数据目录是否区分 |
+| 窗口与日志 | BrowserWindow、webContents、loadFile/loadURL | 正确页面实际加载、renderer 确实运行；收集加载失败和进程异常 |
+| preload 与隔离 | webPreferences.preload/contextIsolation/sandbox/nodeIntegration、contextBridge | 保持冻结配置；sandbox preload 的 require 受限，不能因加载失败就关闭隔离 |
+| 消息 | ipcMain、ipcRenderer | 真实往返、sender/窗口归属、错误传播、超时与监听清理 |
+| 自定义会话 | session.fromPartition、窗口 session/partition | 在创建窗口前确定会话；测试操作的是同一会话且没有跨用例残留 |
+| 退出与异常 | app 生命周期、窗口关闭、main/renderer 异常 | 需要独立应用生命周期的用例使用冷启动隔离；不吞掉异常或 mock app.quit |
+
+鸿蒙扩展需先核对目标版本：指导文档描述 `BrowserWindow` 构造选项 `windowInfo.type`，以及 `systemPreferences.requestSystemPermission(permission)`、`requestDirectoryPermission(path)`、`openApplicationInfoEntry()`、`fileAccessPersist(paths)`。目录请求传 null 的 true 可能只表示部分目录获准，不能当成全部目录可访问。相关参数、权限声明与实际授权要逐项检查，按用例需要配置。窗口显示/隐藏在部分模板中涉及托盘及 AppWindowAdapter 的启动选项，窗口不出现时检查匹配模板，不直接判定多窗口不支持。
+
+## 先确定失败发生在哪一层
+
+| 现象 | 先检查 | 可以采取的修复及证据 |
+|---|---|---|
+| npm: inaccessible / not found | 套件是否在设备执行 npm start；应用是否实际启动 | 宿主构建 webpack/esbuild/Vite 资源并随包交付，目标使用匹配 HAP 入口启动；保留原场景与断言。安装 npm 不能直接替代 Electron-OH 的应用启动机制 |
+| 子进程 ENOENT / EACCES、XPM 拒绝 | 实际可执行路径、HNP 安装/签名、依赖库、应用沙箱视角 | 按目标版本 HNP 配方提供 OHOS 二进制，核实真实安装路径。不要用 chmod 或关闭 XPM 充当交付修复；不要直接复制 Linux ELF |
+| V8 fatal / jitless 相关启动失败 | 父子进程 execPath、execArgv、运行时 launch_args、动态库环境和 stderr | 新启动的普通 node 命令不会自动复制父进程命令行参数；按运行时契约传参并真机重试。崩溃栈未定位前只能作为假设，不能归因为库 API 不支持 |
+| preload / renderer 无结果 | preload 路径、打包导出、页面加载、sandbox require、IPC sender | 保留原安全选项，修资源路径/正确导出并验证真实 IPC；超时记失败，不能由 main 直接生成 renderer 通过结果 |
+| 日志路径/应用名与宿主不同 | package.json/productName、main 入口、cwd、userData 与应用私有目录 | 明确测试 fixture 的宿主条件，构造真实等价元数据/目录；不要将库返回值硬编码成预期值 |
+| 写文件 EACCES / 网络失败 | 请求路径、声明权限与实际授权；服务器监听地址/端口及生命周期 | 在原场景允许的目录写入后读回；受控网络端点实际收包。需要公共目录的测试不能改成私有目录后声称语义等价 |
+| addon 装载/符号错误 | ABI、OHOS 工具链、shim 覆盖、依赖库与签名 | 按 `pc-knowledge-base` 的 `electron/addon-build.md` 处理；最小 addon 可加载不证明真实库可用 |
+
+HNP 指南的公私目录环境变量描述与示例路径存在容易混淆的地方。不要硬编码网上示例或假定 HNP_PRIVATE_HOME/HNP_PUBLIC_HOME 的映射；以当前模板、应用进程环境和实际安装目录核实。保持现有工程级打包方式，不修改全局 DevEco 安装目录来套用旧教程。
+
+## 上游 E2E 到 HAP 的等价接线
+
+这是本线的测试设计方法，非文档承诺所有上游测试可原样执行：
+
+1. 拆开宿主构建和设备运行：保持各 fixture 的 bundler 配置、CJS/ESM 导出和资源内容，构建结果打包到正确 app 路径。
+2. 将 npm start 背后的 main/preload/renderer 和安全配置映射到真实 HAP 启动。涉及 ready、quit、全局异常捕获的场景采用独立冷启动；仅在不改变生命周期语义时复用 harness 窗口。`require(main.js)` 不能重放已经发生的 app.ready。
+3. 多窗口/自定义 session 用真实窗口与会话；保持期待的日志、文件、IPC、网络收包和退出结果。复现报告区分“启动没成功”和“功能断言失败”。
+4. 套件属于 02 冻结输入；修改驱动要回 02 保持 ID、范围、断言及检查目的，记录等价性、宿主自证并重新冻结；03 重新取证。不能改 platform_exclusive 排除启动失败。
+
+例如 electron-log 的多条 E2E 同时报 npm 缺失，应先修共用启动器；修好后才知道隔离、会话、打包与异常处理各自是否有真正的兼容问题。Node 子进程的启动参数可参考 [process.execArgv](https://nodejs.org/api/process.html#processexecargv)，但 Electron 内嵌 Node 与独立 Node 的可执行入口不能互换。
+
+## 升级处理与停止条件
+
+先解决 fixture/构建接线，再看库的平台分支，最后判断运行时实现缺陷。运行时层保留最小复现、锁定版本、完整栈/设备日志、预期与实际、已尝试动作；无 SDK/源码或缺上游支持时如实记录阻塞。自动修复与结束条件沿用 通用 gate 和阶段 agent 的原有规则，不保证所有问题可由库 agent 独立修复，也不以裁剪冻结名册作为退出手段。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/references/examples.md

@@ -0,0 +1,74 @@
+# Node.js 库的必需 demo 与结果
+
+只适用于 `ecosystem=nodejs/node` 且 `kind=library`。运行模式由 01 的 `node_library` 判定；不得用 `host_runtime` 替代。
+
+| 模式 | 03（02 基线） | 06（05 功能用例） |
+|---|---|---|
+| node-and-electron | harmony-demo、harmony-demo-electron | test-demo、test-demo-electron |
+| electron-only | harmony-demo-electron | test-demo-electron |
+
+## 环境准备
+
+必需宿主由 env/gate 共用规则计算。所有本专项项目检查 `electron_runtime`（完整运行时工程）、sdk/hvigorw；原生扩展再检查 electron_toolchain（N-API 垫片）和 ndk。使用裸 V8/C++ 跨界接口时还须按 addon 配方核对专用 LLVM，不能仅凭垫片存在宣称 ABI 可用。
+
+运行时工程位置：`OHPT_ELECTRON_OHOS_HAP` 优先，其次 `OHPT_ELECTRON_SRC/src/ohos/app/ohos_hap`，再读取 `~/.ohos-agent-pc-adapter/electron-runtime.json` 的 `ohos_hap` 绝对路径。共享配置供 Web 子进程和 CLI 同时读取，无需硬编码开发机路径。Web 的 `data/toolchain-env.json` 会注入高优先级环境变量：若配置了旧路径，会覆盖用户配置；修改后须重启 Web 及执行服务。`invalid` 时先核对 `source/path/missing_files/remediation`，若 `alternative` 给出完整运行时，应修正配置覆盖，再探测，不得直接断言全机无运行时。探测结果 `electron_runtime.ohos_hap` 供模板转换的 `--sdk-electron <路径>/electron` 使用。
+
+排障时先读取工作区 `00-env.json` 的 `electron_runtime`；需要刷新时运行 `ohpt-agent env -w <workspace> --json`。不要为了确认运行时路径直接 `cat ~/.ohos-agent-pc-adapter/electron-runtime.json` 或遍历用户目录，headless 执行可能自动拒绝 external_directory。若工具调用被拒绝，记录具体操作和路径；不得把权限拒绝归因为运行时不兼容，也不得通过替换命令绕过拒绝。
+
+缺字段表示未探测，先刷新环境；found=false 才按具体缺项处理。路径或资源状态变化时 gate 返回 `refresh_env=true`，必须先刷新再判定。proceed-degraded 只允许降级执行，不免除交付、不构成永久终态；环境恢复后补跑未完成工程。`degraded-skipped` 不得计入 `roster.ran`、不得写 `test_run.completed=true` 或 `target_path_covered=covered`。探针通过仅说明资源具备，版本兼容性仍需实际构建运行验证。
+
+构建、签名与常见故障使用 [自动恢复配方](recovery.md)，优先调用固定构建入口，避免自行拼装签名命令。
+
+## 创建与接线
+
+**新工程优先按 [固定工程工具](managed-projects.md) 执行**：node-demo-project create/inherit → probe → 接 suite → build。下面的 scaffold、create-electron-example 和手工启动接线仅用于已有未托管工程的兼容维护，不能混用于带 demo-project.json 的托管工程。
+
+1. 读取 `ohpt-agent state -w "$WORKSPACE" --json` 的 `library_examples` 和 `node_library_demos`。运行模式待补时回到 01；保留已有工程，不删除历史 Node 目录。
+2. 先创建本阶段全部缺失工程。Node 用 `scaffold --kind cli-hnp-runner --tool node`；03 保持简洁验证页面，06 展示模块、用例、步骤与实际结果。Electron 用 `scripts/create-electron-example.cjs --workspace <绝对路径> --stage 3|6 --bundle <独立bundleName>`，默认使用 env 探出的完整运行时工程，避免混用不同版本的模块与引擎；也可用 `--template` 显式指定匹配的完整模板。已有工程增量编辑，不覆盖 suite。
+3. `ohpt-agent node-demo-results -w "$WORKSPACE" --stage 3 --host-runtime device-node --prepare --out harmony-demo/cases.json` 生成该宿主用例视图；Electron 创建脚本使用相同选择器。06 换 stage=6 和目录。输出存在时用新路径生成并审查更新，不覆盖历史结果。
+4. 03 的用例 ID 是 02 原始 `name`，06 是 05 原始 `id`；不可重新编号。`excluded` 展示不适用于当前宿主的条目及依据，不能当成 pass 或 blocked。没有适用用例时修正分类/用例，不交空测试工程。
+5. 两宿主共用断言和夹具，接线按实际入口适配。`suite.cjs` 按用例 ID 调真实库，使用 `ctx.check(index, ok, actual, expected)` 记录断言。03 至少一个检查点；06 覆盖每一步。上游测试可通过真实测试框架结果接线，不能只检查进程启动。
+6. Electron main/preload/renderer/IPC 用真实上下文和安全配置。Electron 专属功能仅其 demo 执行；普通 Node 功能在两边分别执行。原生产物分放 `dist/lib/node/` 和 `dist/lib/electron/`，不得混用 ABI。
+
+## 运行与取证
+
+Electron 完整引擎、模块、图标按应用配方的 HAP 部分补齐；不执行完整应用迁移流程或应用专属人工检查点。`stage-app.cjs` 同步 app-src。默认页面加载后自动执行全部适用用例一次，保留手动重跑；无需假定 Want 参数已转发到 JS。冷启动前打开日志采集，冷启动一次取得一份完整结果；手动重跑使用新日志文件。
+
+Node 工程先执行 `scripts/prepare-node-launch.cjs --workspace <ws> --stage 3|6`，生成 `scripts/node-launch/` 下的统一 argv/env 头文件、宿主探针和入口。启动器用 `ohpt_node_args`、`ohpt_node_env` 同时启动探针和业务，入口为 `node-entry.cjs <suite> [args]`；探针失败不加载 suite。需要针对已定位的 aarch64 io_uring/close_range fast-path 回退时显式加 `--syscall-fallback --ndk <目标NDK>`，不能对所有原生错误盲目启用。工具拒绝非 Node 库和非必需宿主。
+
+Node 把运行时、库、生产依赖、夹具与 runner 装进私有 HNP。可以复用 `templates/run-suite.cjs`，传入 prepare 生成的 cases.json。两宿主的 runner 打印真实运行时标记 `OHPTCASE runtime host=device-node|electron-oh`；实际 Electron 由 `process.versions.electron` 判断，禁止手工伪造标记。
+
+每工程用不同 bundleName。在各自工程构建 HAP，固定构建工具已完成签名；直接安装返回的 signed_hap 并记录 hap_sha256。只有手工构建的 unsigned 输入才使用 `sign-demo --demo-dir <工程> --hap <本轮unsigned HAP> --install`，不要对当前签名包再次签名。设备原始日志、HAP 和结果必须在对应工程子树中；模板引擎若未将 console 导出到 hilog，从应用真实日志文件取证。启动成功不等于用例执行。
+
+```sh
+ohpt-agent node-demo-results -w "$WORKSPACE" --stage 3 --host-runtime electron-oh \
+  --log harmony-demo-electron/verify/device.log \
+  --hap harmony-demo-electron/dist/app/current-signed.hap \
+  --hap-sha256 <实际安装时记录的哈希> \
+  --executed-at <原始设备执行时间，含时区> \
+  --out harmony-demo-electron/verify/run-1.results.json
+```
+
+Node 换 host-runtime 和路径；06 换 stage。该命令解析宿主适用名册、原始结果与完成标记，记录日志/HAP/名册/运行模式及共用输入指纹。device-node 结果必须在首条业务记录之前有真实 OHPTHOST 成功记录（运行时版本、平台、文件与事件循环检查）；缺失、失败或晚于业务时门禁拒绝完成。结果文件只由工具生成，禁止模型修改。失败用例也生成真实结果；命令成功仅表示日志完整，不表示所有用例通过。
+
+03/06 的 `examples[]` 每必需工程一条：`project_dir/host_runtime/status/result_file/evidence/notes`。`passed` 必须通过 CLI 同源校验；未构建或未执行保留 blocked/failed/not-run 和具体原因。按宿主分别记录实际执行，主 `test_run`/06 `case_results` 按用例去重取所有适用宿主的最差结果：一个宿主 fail/blocked/not-run，不能被另一个 pass 覆盖。不得把执行次数相加当功能数。可从 `node-demo-results --summary --stage 3|6 --out <本阶段Electron工程/verify/summary.json>` 获取工具汇总，再誊写报告字段。
+
+## 续修与结束
+
+先完成两边可执行的首轮，再按现有有界预算续修。保留有效结果；只改一边的 demo 则只重跑该边，共用源码/补丁/产物变化要重验两边。补交复用现有派发计数机制与阶段上限（03 最多 5 次、06 最多 2 次）；使用 node-demo-3-attempts/node-demo-6-attempts 隔离历史空报告预算，已有 resume/verify 回环沿用原计数。预算耗尽只表示停止，不表示成功。03 完整成功和 06 passed 都要求全部必需工程完成；其他情况如实 partial/待验证。Electron-only 不生成 Node 工程，也不把 Node 标成 blocked。
+
+旧工作区先补运行模式和宿主适用性，再补缺失工程和工具结果；旧 Node 成功事实保留，但不能用它推断 Electron 已通过。已有原始日志无法证明宿主或对应产物时重新采集。
+
+### 证据版本兼容
+
+任何版本中，若 OHPTHOST 已明确报告 platform 不是 openharmony（例如 darwin），则不能作为鸿蒙设备通过证据；旧协议兼容不允许接受已知外平台运行结果。
+
+新生成结果使用 v3，Node 业务执行前必须有真实 OHPTHOST 探针。读取既有 v1/v2 结果时按原协议核验，不能因新增探针字段缺失而推翻旧的通过结论；HAP/日志/名册/源码哈希、真实断言和宿主归属校验继续生效。既有 HAP 哈希失配不能只刷新哈希：恢复哈希匹配的原始包，或重新构建运行、按当前协议生成并封存新证据。禁止手工把 v3 结果降为旧版本规避探针。
+
+## 当前 HAP 保留规则
+
+03/06 × 必需宿主各自只保留一个 dist/app/current-signed.hap；构建/签名过程可以使用临时 HAP，正常结束后移除。签名自验成功才替换旧文件，失败不可使用旧包冒充新产物。结果命令不复制 HAP，只封存日志并记录执行包哈希。覆盖包后历史结果自然失效，重新运行后生成新编号结果，不手改旧哈希。已有历史封存结果仍按旧协议只读校验，不批量迁移或删除旧工作区。
+
+标准工程探针与业务构建共用当前包；探针通过后保留配置、设备、运行日志和执行哈希，业务包替换不要求保存探针二进制。遇到工程占用错误，等待原构建/取证退出，不绕过锁直接覆盖文件。
+
+使用 verify-demo 取证时，Node 库路径只安装当前签名包，不重新签名；--no-install 必须同时传 --hap-sha256 <实际安装包哈希>，否则拒绝假设设备上就是当前包。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/references/managed-projects.md

@@ -0,0 +1,88 @@
+# 固定 Demo 工程（node-library-v1）
+
+仅 Node.js 三方库的**新工程**默认使用本流程。已有未托管工程不自动覆盖或删目录：保留有效证据，继续旧构建流程；迁移须先保全用户 suite/夹具，明确迁移范围。工具生成的 `demo-project.json` 标识托管骨架，`demo-recipe.json` 记录配置；它们不等于验证通过。
+
+## 配方与职责
+
+03 根据当前库的实际依赖准备工作区相对 `build/node-demo-recipe.json`。运行时来源从 env 取得，禁止写死开发者路径。示例中的绝对路径只是占位，版本须对应实际发行物：
+
+```json
+{
+  "version": 1,
+  "template_version": "node-library-v1",
+  "runtime": {
+    "device-node": {
+      "version": "24.13.0",
+      "binary": "/absolute/OHOS/node",
+      "argv": ["--jitless", "--expose-gc"],
+      "env": {"LD_LIBRARY_PATH": "${bin}"},
+      "files": [{"from": "deps/node/libc++_shared.so", "to": "bin/libc++_shared.so"}]
+    },
+    "electron-oh": {
+      "version": "37.2.0",
+      "template": "/absolute/complete-electron-ohos-hap",
+      "switches": {"js-flags": "--jitless"},
+      "omitPermissions": ["ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY"]
+    }
+  },
+  "payload": {
+    "device-node": [{"from": "build/production-package", "to": "node_modules/example"}],
+    "electron-oh": [{"from": "build/electron-package", "to": "node_modules/example"}]
+  },
+  "nativeFiles": {
+    "device-node": [{"from": "dist/lib/node/binding.node", "to": "binding.node"}],
+    "electron-oh": [{"from": "dist/lib/electron/binding.node", "to": "binding.node"}]
+  }
+}
+```
+
+- `runtime` 只放运行时基础资源，不放目标库。`files` 的来源必须先准备在当前工作区；`binary/template` 是只读外部运行时资源。纯 JS 无 `nativeFiles`；electron-only 无需 Node 配置。
+- `payload` 是已准备好的生产依赖闭包，不在装配时联网下载 npm 包。Node 的 `to` 相对 HNP 的 pkg/；Electron 相对 app/。Node scripts/、hnp.json 为工具保留区。不要上传开发机 node_modules 的符号链接，先物化精确依赖。
+- `nativeFiles` 目标只能是文件名：Node 放 pkg/bin，Electron 放 electron/libs/arm64-v8a；库加载器仍须使用本宿主正确路径。运行时文件与目标文件不得重名。
+- `argv/env/switches/omitPermissions` 是针对当前版本验证的配置，不是所有版本的默认补丁。`${bin}` 只在 Node env 中展开为实际 HNP bin 目录。需 syscall fallback 时先按真实故障证据准备目标 so，将其列入 runtime.files，再声明 LD_PRELOAD=${bin}/具体文件。
+- 原生库在对应 runtime 内加 `headers`（目标 Node-API 头目录的绝对路径）；Electron 再加 `shim`（匹配 libshim.a 的绝对路径）。标准探针用它编译一个独立 N-API addon，验证连续及并发异步完成。
+- 模板/引擎/运行时文件、工具链关键文件及启动配置内容进入标准验证指纹；声明版本与实际运行版本必须一致。模板来源不得包含已适配库业务或私有签名材料。
+
+## 03 工具流程
+
+对 state.library_examples 中 stage=3 的每个宿主运行：
+
+```sh
+ohpt-agent node-demo-project -w <ws> --stage 3 --host <device-node|electron-oh> --action create --recipe build/node-demo-recipe.json
+ohpt-agent node-demo-project -w <ws> --stage 3 --host <host> --action probe
+```
+
+create 固定工程和身份；probe 实际构建 debug 包、签名、取得设备租约、安装冷启动并读取本 bundle 日志，120 秒外部超时。Node 使用私有 HNP 中独立命名的运行时、固定启动器和脚本；Electron 验证真实 renderer→preload→main IPC。标准包不装配目标 payload/nativeFiles，不加载业务 suite。原生库另验证 N-API 加载、连续和并发任务。日志读取当前支持调试包 debug_hap 的 user 100 路径；不可读时如实阻塞，不以进程存活代替成功。
+
+`env` 的 resources-only 只代表资源在位；只有 probe 生成的 `verify/standard-ready.json` 表示该工程组合已运行通过。新记录使用 version=2，保留设备/系统、配置和资源指纹、实际探针 HAP 的哈希、运行 token 和原始日志。探针与业务共用当前 HAP，业务构建替换包后不要求探针二进制仍在盘；check/build 重新验证日志哈希、token、宿主和必需能力。配置、资源或设备变化时重跑标准探针。旧 version=1 仍按原协议检查原始 HAP，不自动改写。check/build 都会复核；不手写 readiness 文件。
+
+标准工程通过后，agent 只编辑 `app-src/suite.cjs`、测试夹具和库源码/构建配方。Node/Electron 基础入口、IPC 和启动器由工具维护。业务套件按 02 名册使用 ctx.check；保持实际调用和原断言。
+
+生成的 `cases.json` 使用版本 1 契约，业务工程、标准探针和 `node-demo-results --prepare` 共用生成逻辑。`modules` 和 `excluded` 始终为数组；06 业务工程保留 05 的模块名称，标准探针使用空模块列表。页面兼容旧文件未声明版本或模块列表的情况，但拒绝未知版本。每次 Electron 执行都会重新记录宿主检查；原生探针与主入口共用本次文件日志，不能用其他运行的控制台输出补齐 readiness。
+
+```sh
+ohpt-agent node-demo-project -w <ws> --stage 3 --host <host> --action build
+```
+
+build 重新装配业务载荷，成功后替换本工程 dist/app/current-signed.hap 并返回 hap/hap_sha256，**不会把标准探针通过当作业务通过**。按已有设备取证流程安装这个返回包，运行 node-demo-results 时传 --hap-sha256 <实际安装包哈希>。不要绕回旧 build-node-demo/build-electron-demo 直接构建托管工程。骨架或配方需改变时修复工具/模板并明确迁移，不让每个库临时改 C++ 启动器。
+
+Electron 标准探针先枚举设备日志路径，再分别读取最近 16 份日志，按本次运行 token 选择原始日志；不使用经 hdc 转发后可能丢参数的 `find -exec`。旧 token 的通过记录不能授予 readiness；没有本次完成记录时保留最近日志供诊断，并继续判定未通过。
+
+## 06 继承
+
+03 对应配方及全部必需宿主结果有效通过后：
+
+```sh
+ohpt-agent node-demo-project -w <ws> --stage 6 --host <host> --action inherit
+ohpt-agent node-demo-project -w <ws> --stage 6 --host <host> --action probe
+```
+
+inherit 读取本库 03 配方，从模板生成独立 06 工程及 bundle；Node 和 Electron 都覆盖。只继承运行配置、库产物与依赖映射，不复制 03 suite/夹具/日志/HAP/结果。用例由 05 重新选择；在 06 app-src 接线后 action build，继续独立运行、结果封存和汇总。标准探针不计入 02/05 名册。
+
+## 失败处理
+
+资源缺失、模板构建、签名安装或标准探针失败 → 修复运行配方/基础工具，保留原日志，不归因库不支持。标准工程通过后，库加载、ABI、原生行为或测试失败 → 03 库适配/测试接线修复；06 的产品缺陷交回 03。现有门禁、独立验收和总预算保持，不能为工程失败伪造业务 PASS。
+
+## 用例结果路径
+
+`verify-demo --cases` 支持以源码相对路径为 ID 的用例（例如 `adaptor/services/__tests__/challenge.ts`），会在取证目录创建对应子目录并保留原始 ID，不需要改名或缩减用例。绝对路径和含 `..` 的 ID 不允许作为结果落盘路径。