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

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

@@ -0,0 +1,69 @@
+# Node/Electron 原生扩展
+
+仅在 pc-node-library 的 Node.js 三方库范围内使用。NDK/sysroot、交叉编译、签名与部署知识复用 pc-knowledge-base；以下把这些知识收敛为 Node/Electron 双宿主的实际动作。
+
+含原生依赖的 03 开发/返修先读本文；FFI、异步回调或 SIGSYS 问题时，再读 [原生运行诊断](native-runtime.md)。06 消费已验证库产物和工程配方，仍以 05 名册编写自己的用例；产品缺陷反馈 03。
+
+| binding 实际接口 | 需要确认 |
+|---|---|
+| Node-API C | 所用 NAPI_VERSION、运行时实现、异步回调和线程安全函数 |
+| node-addon-api | 上述条件 + 包装层版本、C++ 标准、异常/RTTI、C++ 运行库 |
+| NAN | 精确目标 Node/Electron/V8 headers、宏展开后的 API、模块版本 |
+| 直接 V8/Node | 内部 SDK/config.gypi、Isolate/Context、Worker 与释放语义 |
+
+不能用某个库名永久推断接口类别，也不能因为 napi_* 同名把 Node addon 链到 ArkTS 的 libace_napi。Node-API ABI 稳定性不代表跨 OS/CPU、libc 或外部动态库兼容。[Node-API](https://nodejs.org/api/n-api.html)
+
+执行顺序：
+
+1. 固定源码、锁文件、目标 runtime/headers/config/shim 的版本和哈希；宿主 Node 只负责跑构建工具，不能自动成为目标 headers 来源。
+2. 检查 binding.gyp、cmake-js、prebuild/node-gyp-build 的下载与平台分发。保留原有平台路径，只为有实际证据的 openharmony 分支添加适配。
+3. 优先复用已适配构建入口；上游 node-gyp 没有现成 OHOS 配置时，可生成 CMake adapter，但须迁移 sources/defines/conditions/generated headers/actions/依赖，不能机械抄 sources 就声称等价。
+4. SQLite/libvips 等外部原生依赖单独构建；核对 ELF 架构、NEEDED、未定义符号、RUNPATH、libc++、签名，保留许可证。
+5. 独立 Node 的 `.node` 由对应 Node 宿主加载。Electron-OH 的 shim/原生库打包位置取目标发行版指南，不把 Node 的延迟符号解析规则照搬过去。
+6. 先加载，再跑原 API 断言、错误、并发、资源释放与窗口/Worker 销毁。缺 headers 或缺设备记环境缺口，不能据此判接口不支持。
+
+Electron-OH 特定发行版的 shim 和 HAP 接线见 `pc-knowledge-base` 的 `electron/addon-build.md`。[Electron 原生模块](https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules) 说明通用 rebuild 原理；该工具本身不证明 OHOS 工具链已经具备。
+
+## 独立 Node 的 CMake 薄层示例
+
+目标接口确认是 Node-API 且目标 Node 提供动态符号时，可用 OHOS toolchain 构建 `.node`（PREFIX 空、SUFFIX `.node`）。`OHOS_ALLOW_UNDEFINED_SYMBOLS=1` 只适用于已经核对由该宿主提供的符号；不能用它掩盖外部库漏链。显式传入目标运行时 headers 路径，不自动发现并使用 DevEco 的宿主 Node 头文件。
+
+vendored 依赖可静态并入扩展，或把目标共享库一起部署；选哪种依据许可证、符号和体积约束。DT_NEEDED 必须匹配实际依赖，不应一概要求只有 libc/libc++。运行时 NAPI_VERSION 上限只是必要条件，异步/线程等实际实现还要验。
+
+既有案例记录：classic-level 3.0.0 的 LevelDB Node-API binding 曾以 CMake/OHOS NDK、vendored leveldb+snappy 在目标 Node 22.7.0 验证上游测试；这是该版本案例，不代表任意新版同样可用。设备部署统一用当前自带运行时/私有 HNP 流程，不复用历史可调试设备的 nsenter 指令。
+
+## 通用适配流程
+
+Node.js 三方库统一从当前源码和目标环境出发。没有现成配方时直接构建与诊断，不能因此停止或记 blocked。
+
+1. 从 package/锁文件、入口、安装脚本和源码识别纯 JS、Node-API、NAN/V8、FFI 及外部原生依赖；确定宿主适用性与本阶段名册。
+2. 准备目标运行时、headers、工具链和两个必需 demo，先各自验证无目标库的宿主探针。宿主失败先修工程与运行环境。
+3. 按依赖拓扑从底层 C/C++ 库到 addon 构建，执行下方构建与装载检查。查询 registry 未命中即进入源码适配，不把缺少预编译包视为不支持。
+4. 每个宿主依次通过 require、最小真实调用、异步/线程/资源生命周期检查，再运行全部适用用例；纯 JS 库跳过原生步骤。FFI 与数据库是诊断类型示例，不是仅支持这两个库。
+5. 失败时区分编译、链接、安装、启动、加载、原生调用、回调与业务断言层；建立最小复现，根据错误修改源码/构建/接线，重建并重新验证受影响宿主。不以修改断言或同步替代异步达成通过。
+6. 两个必需宿主完成后交付配方、补丁、产物和证据。不能仅凭提示词保证所有库必然可适配；真实平台能力缺口需要最小复现与证据，未定位或预算耗尽不等于不可适配。
+
+## 构建与装载检查清单
+
+1. **依赖闭包**：列出 JS 运行依赖、所有 .node、静态/共享 C 库及加载关系；先按 pc-registry 检查可复用配方。预编译 linux-arm64/musl 不能仅凭 CPU 与 libc 相近就当作 OHOS 产物。
+2. **交叉编译**：从 env 解析 NDK/sysroot 与目标 headers/shim。原构建不能用于 OHOS 时迁移 binding.gyp 的 sources、平台条件、defines、actions、生成头文件和链接依赖到 CMake adapter。macOS 的 -bundle 等宿主参数不能进入目标链接行。用编译器实际宏检查 __OHOS__/__linux__ 分支，不全局伪装 Android；C++ 标准、异常与 RTTI 取源码要求，不机械固定版本或宏。
+3. **依赖生成配置**：libffi 的 ffi.h/fficonfig.h、aarch64 汇编、ABI/closures 配置必须来自同一目标构建；SQLite 的 amalgamation 版本、THREADSAFE、FTS/JSON 等编译选项与上游功能一致。不能拿宿主 configure 的运行探测结果冒充目标结果。
+4. **双宿主隔离**：使用独立构建目录及 dist/lib/node、dist/lib/electron。独立 Node 由对应宿主提供 napi_*；Electron 按目标发行版 shim 接线，核对 HIDE_NAPI_AND_UV 的实际宏展开。它们是分别验收的产物，不能仅凭 N-API ABI 稳定就盲目互换。
+5. **ELF 静态核验**：用目标 llvm-readelf/llvm-nm 检查架构、NEEDED、未定义符号、导出入口和 RUNPATH；每个未定义符号应有明确提供者。检查 libc++ 导出与 C++ ABI 命名空间；Node-API 路线不应意外依赖宿主 V8/Node 的 C++ 内部符号。扩展不链接 ArkTS libace_napi 来补同名 API。
+6. **Electron 桥接**：检查实际 shim 的符号覆盖，不能假定它包含全部 uv_*。缺项转发必须使用目标版本真实签名/类型，检查 dlopen/dlsym 失败并报告 dlerror，禁止无检查调用空函数指针、手写错误的 opaque 结构尺寸。需要宿主 libuv 时不能另带一份 libuv 操作宿主 loop。按加载器确认 napi_register_module_v1 是否可见且真正转发模块初始化；DT_NEEDED、RPATH 或本地符号绑定调整必须有解析证据，不能以 -Bsymbolic 万能兜底。
+7. **包内核验**：逐项比对 dist→HNP/HAP 的文件哈希及实际应用域加载路径，包括 libc++、依赖 .so、shim 与运行时。JS 加载器为 openharmony 增加精确分支，保留上游平台行为；发行工程自带的桥接 addon 与待适配库 addon 分开核对，避免同名覆盖。
+8. **部署**：Node 走本库私有 HNP；Electron 用固定 debug 构建入口、完整 ohpm 依赖和同版运行资源。区分 ELF 代码签名与 HAP 签名，不能添加全零签名段冒充签名。安装后先宿主探针、再 addon 加载/一个真实调用、最后完整名册。
+
+## 验收与交付
+
+- require 成功只证明加载。FFI 还须同步/变参/结构体/回调/异步/GC；数据库还须打开关闭、错误、语句、并发、事务/序列化与资源释放，具体名册仍来自 02 或 05，不用固定探针替代业务用例。
+- 不修改库承诺的同步/异步语义来凑通过率；不改测试避免 TDZ 来掩盖提前 complete，不吞异常、不删失败用例。
+- 输出可重建脚本、源码补丁、依赖版本/来源与许可证、两宿主产物及哈希、真实命令/日志和逐工程结果。历史尝试放实验日志，当前报告只描述本次包的事实；未运行用例不得记 crash/pass。
+- 预算内按证据续修；预算结束如实记录最后成功节点、失败节点和下一项区分实验。没有最小复现及同环境对照，不写“只能升级 V8/系统”。
+
+## 可复用知识来源
+
+- [C++ 交叉编译](../../pc-knowledge-base/adaptation/鸿蒙PC-C++库交叉编译要点.md)：目标宏、交叉工具链、依赖与平台分支；案例中的系统自带库仍需在本应用域核实。
+- [应用域执行与 JIT](../../pc-knowledge-base/platform/鸿蒙PC-app域执行二进制与JIT限制.md)：私有 HNP、faultlog、syscall fallback；历史 syscall/运行时结论按目标版本复核。
+- [Electron addon 构建](../../pc-knowledge-base/electron/addon-build.md)：shim 链接、C++ ABI 与导出检查；不照搬其单宿主判定和版本无关假设。
+- [Autotools 三元组](../../pc-error-atlas/knowledge/errors/E072.md)：旧 config.sub 不认识 OHOS 时修配置识别，不以 Linux 宿主配置替代交叉目标。

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

@@ -0,0 +1,80 @@
+# 原生扩展运行诊断：FFI 与异步数据库
+
+仅由 Node.js 三方库专项调用。先完成 [原生扩展](native-addon.md) 的通用适配流程与构建检查；下列是诊断顺序，不表示两个示例库已经适配成功。
+
+按症状读取：Node 最小脚本 SIGSYS → node-startup；ffi 符号/调用/Callback 异常 → ffi；sqlite3 或其他 addon 异步挂起 → async-work。每项实验保存命令、包/产物哈希、宿主版本、原始日志、实际结果与下一步，不修改其他库工作区。
+
+## node-startup
+
+在实际 HAP 的私有 HNP、同一启动器和 argv/env 下，按顺序运行：
+
+1. node --version；再运行无 addon 的 console.log 与宿主探针。版本输出成功并不代表 V8/事件循环初始化成功。
+2. 在后者失败时取 runner 的 WIFEXITED/WIFSIGNALED、信号号、stderr，以及本 bundle/PID/启动时刻对应的 faultlog；不要直接解读自定义负返回码。SIGSYS 要取 syscall 号，SIGTRAP/ABRT 要取调用栈与原始断言。
+3. 核对当前包内 Node 文件哈希、真实 exec 路径、shim、libc++、--jitless、环境变量与子进程参数是否符合本次构建及启动配置。无 addon 已失败时先修载体，不反复改 ffi 源码。
+4. 对 faultlog 已证实的 io_uring/close_range 等 fast-path，核对目标版本支持的开关或上游 fallback。环境变量存在于二进制不等于该路径被禁用；必要时在本库使用返回 ENOSYS 的已验证 fallback shim。核对 Node 是否动态导入被拦截符号、shim 是否真正加载；syscall shim 必须正确转发其他调用，不使用可能破坏参数的草率可变参数实现。
+5. 可执行内存错误才试对应运行时的 jitless 配方，并确认参数实际进入目标进程。jitless 不自动解决 libffi closure 的可执行 trampoline。Node 派生子进程也核对实际 argv/env，不能只验证父进程。
+
+`prepare-node-launch.cjs --syscall-fallback --ndk <目标NDK>` 提供 aarch64 ABI 正确转发的可选回退。只对 io_uring/close_range 返回 ENOSYS，其余 syscall 原样转发；原始 stderr 必须记录加载及实际命中的调用号。不能仅凭 SIGSYS 启用或归因，须结合无 addon 对照和实际命中日志。当前 Node 24.13.0 设备实验记录到 syscall 425（io_uring_setup）；不能将此结论推广到任意版本或架构。
+
+## ffi
+
+适用于 node-ffi-napi/ref-napi/libffi 依赖链，版本按实际 package/锁文件核对。
+
+### 构建与模块身份
+
+- 先构建目标 libffi（含同版配置头和 aarch64 汇编），再 ref-napi，再 ffi addon。确保编译时 ref-napi 头文件与实际加载的 ref 模块属于同一实现/版本；不要把发行模板的桥接模块当成目标包实现。
+- 核对 ffi_prep_cif、ffi_call、ffi_prep_closure_loc 的实际构建支持，sizeof(void*)、size_t、ffi_arg、结构体大小/对齐及 FFI_DEFAULT_ABI；不能靠复制 Linux 生成头或随意调整 ABI 数值试到“不崩溃”。
+- 加载器按精确包根/入口解析目标 .node，记录 require.resolve 和实际加载路径；避免 contains('ffi-napi') 等宽匹配误路由 ref-napi 或模板模块。
+
+### 最小区分实验
+
+1. **原生对照**：在同一宿主进程中，用小型 Node-API 诊断 addon 直接调用 dlopen/dlsym；打印加载的绝对路径、dlerror、句柄与符号指针（%p）。使用本工程构建的小型共享库，先用 llvm-nm 检查导出一个 int→int 函数。不要先借 ffi 调用 dlopen 来“证明 ffi 没问题”。
+2. **FFI 同步**：同一目标库和函数通过 ffi 调用，逐步增加 double、字符串、结构体与变参。若原生对照成功而 ffi 失败，查参数封送、指针宽度、libffi 目标配置/汇编；尤其核对指针是否经 JavaScript Number 往返（高于 2^53 的句柄会丢精度），内部使用 BigInt/原生指针保持全宽；若对照也失败，查导出、NEEDED、加载路径/命名空间、签名与 dlerror。
+3. **空指针**：RTLD_DEFAULT 可能就是空值，不能用 isNull() 判它不可用。ref.alloc(ref.types.void) 只有零长度，不能 writeBigInt64BE；使用 ref.NULL 或目标接口规定的空指针表示，区分“空指针”和“存着零的缓冲区地址”。不要通过 JS Number 打印完整 64 位指针来判断是否损坏。RTLD_LOCAL 本身不意味着 dlsym(handle, symbol) 不能查该库；加 RTLD_GLOBAL 不是通用修复。
+4. **Callback 单独验证**：同步 ffi_call 通过后，单独创建、调用、释放 closure；记录 ffi_closure_alloc 返回值、closure 与 code 地址、ffi_prep_closure_loc 状态。崩溃取栈，内存映射失败记录 errno；只有证据明确指向可执行内存策略才研究该 libffi 版本的受支持 trampoline/分配后端。不能因 V8 使用 jitless 就断言 closure 必然不可用。
+5. **异步和 GC**：按下一节验证线程池，再测异步 ffi 调用、回调线程约束、回调引用存活、GC 后释放及重复创建。qsort 回调等应实际被 C 调用；未到达的后续用例记 not-run，而非批量 crash。
+
+本次 ffi-napi/ref-napi 修复确认高位 dlopen 句柄经 Number 丢精度；修复内部 BigInt 传递后，恢复公开 ffi.Library 路径验证，不能以 directDlopen 测试旁路代替库 API。PointerBuffer 与 Buffer 接口不同，读回调用 ref.readInt32，不能无条件调用 Buffer 方法。GC 测试应释放强引用、用 WeakRef 确认实际回收，再创建调用新回调。静态 trampoline 池是有容量限制的实现：交付时声明容量，另外验证耗尽、回收、线程安全；少量回调通过不证明任意并发容量。
+
+## async-work
+
+适用于 vscode-node-sqlite3、node-sqlite3 以及使用 napi_async_work 的其他 addon；不要推广到纯同步数据库实现。
+
+### 三层探针与判断
+
+| 层 | 实际动作 | 失败后检查 |
+|---|---|---|
+| JS 宿主 | 无 addon 的 nextTick、timer 各连续运行多次 | 入口、宿主事件循环与启动配置 |
+| 最小 Node-API addon | 创建并排队一个计算任务，连续两次，再少量并发；输出 create/queue 返回码、execute/complete、线程、任务 id | shim 解析、env、线程池、loop 与待处理异常 |
+| 真实数据库 | 内存库 open/close → 连续两次 → prepare/run/get/finalize → 文件库与适用完整名册 | baton、SQLite 错误、语句/数据库生命周期、队列和锁 |
+
+JS 探针不能替代 N-API 探针。所有层使用同一宿主、同版 headers/shim、同样打包/启动方式；不要用 Node 24 的成功证明 Electron 内 Node 22 的桥接正确。
+
+每项 async work 记录 create/queue 的 napi_status；失败时及时读取 napi_get_last_error_info，必要时核对待处理异常。NDEBUG 会移除 assert，不能只用 assert(status == 0) 处理 API 失败。queue 失败应报告并按所有权释放任务，不能留下永不结算的 Promise。
+
+- 没有 execute：先核对 create/queue 真实返回值与转发目标，不能宣称线程池已运行。
+- execute 有、complete 无：核对宿主 napi_get_uv_event_loop、loop 存活、实际线程、env/Context 来源、跨运行时 shim 混用、取消/销毁路径；保存宿主仍存活的证据。
+- complete 有、JS 无：检查调用线程、handle/callback scope、callback 引用寿命、napi_call_function 状态与待处理异常；不得清异常后报成功。
+- JS 收到回调但结果错误：回到库逻辑与原始断言，不再归为环境挂起。
+
+宿主事件循环本身可能卡住，超时由外层设备执行器收尾并保留日志；不能仅用同一 JS loop 内的 timer 保证诊断终止。
+
+### 保持异步语义与对象所有权
+
+napi_create_async_work 创建任务、napi_queue_async_work 排队；execute 执行计算，complete 在相应事件循环回调。execute 不访问需要 JS 环境的值；env/回调引用不能来自 ArkTS 或另一个 Node 实例。
+
+禁止在 create 内同步 execute+complete、让 queue 直接返回成功。这不仅使构造器内回调早于 const 初始化，还可能形成 use-after-free：sqlite3 的 Work_AfterOpen 用 unique_ptr 释放 baton，若 create 尚未返回就调用它，后续写 &baton->request 和调用方读取 request 都访问已释放对象。即使 39/39 通过也不构成正确修复。
+
+已有同步补丁先在诊断分支移除，回到原始异步路径做最小探针。确需兼容层时必须保持一次完成、异步时序、线程/loop 归属、取消与 env 清理语义，再跑完整原库测试；不通过 nextTick/setTimeout 盲换时机或把测试改用 this 来掩盖缺陷。
+
+### sqlite3 编译与业务恢复
+
+核对 SQLite amalgamation 版本/编译选项、node-addon-api 版本、目标 headers、NAPI_VERSION、异常宏和 shim 的函数签名，特别是老包装层与新 headers 的 const/env 类型差异；不凭编译通过认定运行兼容。
+
+Node 当前若依赖同步 async-work 补丁，其历史计数应标注“语义待复核”；Electron 已移除补丁的挂起要独立定位，不能用旧补丁错误解释新包。修复后验证回调不会在 API 返回前执行、连续/并发任务能结束、错误只完成一次、close/finalize 后无悬挂任务，再完整跑本阶段名册。
+
+## 结论与沉淀
+
+只有在同版本同应用域的最小探针也失败、拿到真实错误/栈、核对桥接和配置后，才能提出具体的平台缺陷结论。记录已验证修复的版本、前提、构建命令、实际运行结果及不适用范围；未验证假设不进入“已验证配方”。
+
+参考语义：[Node-API 异步工作](https://nodejs.org/api/n-api.html#asynchronous-operations)、[POSIX dlsym](https://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html)。

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

@@ -0,0 +1,11 @@
+# 包识别与补丁原则
+
+定位实际 package.json（monorepo 要定位子包）；核对 exports/main/module/type、条件导出、类型声明、engines、测试与 CI。区分 dependencies、optionalDependencies、peerDependencies、devDependencies，检查安装脚本是否下载原生 prebuild，以及运行期传递依赖里的 `.node`、外部工具和 WASM。
+
+纯 JS 优先不改源码试跑。平台分支依据目标真实 `process.platform`、路径和权限补充，不全局伪装 linux，也不将 linux-arm64 预编译包当 OHOS。保留 CJS/ESM、同步/异步、错误、回调和释放语义；JS 算法无需改写成 ArkTS。
+
+Electron 的 main/preload/renderer、IPC、contextIsolation/sandbox/nodeIntegration 按真实入口分析。devDependency 里的 Electron 不构成运行依赖；把同步 API 换成异步 IPC 或 sidecar 要报告语义变化。库所需系统能力继续交给 pc-capability-domains 判断，存在 Electron 引擎并不意味着所有 API 可用。
+
+补丁只改有证据的平台路径、加载、权限或 API 差异。`bindings`、`node-pre-gyp`、`prebuild-install`、`node-gyp-build` 的分发逻辑需按实际目标核对；保留其他平台行为。真实日志记录最终加载的原生文件路径，不能只改后缀就认定兼容。
+
+独立 Node 运行时随私有 HNP 自带，遵循 pc-knowledge-base 的设备运行时供给指南。Electron 模板和引擎必须匹配；只在实际启动独立 Node/外部工具时使用应用配方的子进程治理，不把 sidecar 流程强加给普通库。

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

@@ -0,0 +1,69 @@
+# Node.js 库自动恢复与已验证配方
+
+只处理当前 workspace 的 Node.js 三方库。03 与 06 分别拥有 harmony-demo* 与 test-demo*。
+这些配方源于 Electron-OH 37.2.0 / HAD-W32 / OpenHarmony 7.0.0.105 的实际执行记录；其他版本先跑探针，不能当作兼容性保证。已知成功库仅提供对照，不授权修改或重新签名其工作区。
+
+## 固定执行顺序
+
+1. `ohpt-agent node-demo-diagnose -w <ws> --stage 3|6`，按 targets 只处理未完成工程。
+2. 安装、启动失败也属于返修输入；无需等业务套件产生 OHPTCASE。保留本轮命令、退出码、原始安装输出/设备日志。
+3. 在当前工程运行无目标库探针：Node 使用 `scripts/prepare-node-launch.cjs` 生成统一启动配置和 `node-entry.cjs`，打包进本工程 HNP 后执行；新 Electron 模板在业务套件前自动执行文件、nextTick、定时器探针及真实 renderer→preload→main 请求检查。宿主卡死时由外层设备运行超时收尾，不能等待 JS 定时器自救。
+4. 探针失败先修载体；探针通过后运行一个最小真实库调用，再运行适用名册。
+5. 每次变更生成新的签名内容，成功后替换本工程 dist/app/current-signed.hap；记录返回的 hap_sha256，部署该包、冷启动并生成新的 node-demo-results。签名成功不等于运行成功。
+6. 两宿主都通过才收敛。仅修改报告、重复同一命令不能作为新的修复方案。同一故障重复出现，下一轮必须增加对照或更换假设；保留整体有界预算。
+
+探针成功只说明本次宿主基础能力可用，不替代 N-API/FFI/业务验证。目前探针每次新进程都运行，不跨设备缓存“可用”状态。
+
+## 固定构建入口
+
+带 demo-project.json 的工程统一使用 [固定工程工具](managed-projects.md)，骨架/配置漂移阻止构建；修复模板并明确迁移，不绕开检查调用旧脚本。以下脚本保留供历史未托管工程使用，也是统一工具的底层构建实现。
+
+Node 使用 `scripts/build-node-demo.cjs --workspace <ws> --stage 3|6 --hnp <本工程相对路径> --install`：固定 debug、准确 unsigned HAP、只注入文件条目（不增加 libs/ 目录条目），并记录本轮构建/签名/安装输出。HNP 需先包含运行时、真实依赖和启动工具生成的入口；此工具不把缺失依赖变成可运行状态。
+
+使用本 Skill 的 `scripts/build-electron-demo.cjs --workspace <ws> --stage 3|6 --install`：自动 stage-app、ohpm install --all、debug assembleHap、签名并安装本阶段工程。只在 Node.js 三方库启用。每步原始输出和退出码保留在该工程 verify/build-attempts/<批次>/，失败即停止并定位到 dependencies/build/sign-install 层。返回 signed_hap/hap_sha256 是本次待验证的固定包与哈希，不代表通过。构建批次只保留日志/元数据，unsigned 与 hvigor 中间 HAP 在收尾移除。环境路径取 DEVECO_SDK_HOME 或 PATH，不写死用户名。
+
+## 已验证：Electron 37.2.0 调试工程
+
+适用症状：安装权限拒绝 9568289、启动 TypeError/napi_unwrap、缺原生桥接模块。electron-log/electron-store 的成功记录表明该环境存在可工作组合，不应直接要求升级系统。
+
+- 使用同版完整发行工程和引擎，先 `ohpm install --all`，再 `hvigorw assembleHap -p product=default -p buildMode=debug --no-daemon`。显式 debug，不能依赖默认模式。
+- 9568289 且输出明确指向 ALLOW_WRITABLE_CODE_MEMORY：在当前库 Demo 中核对该权限及 V8 启动方式。采用已验证的 `--js-flags=--jitless` 调试配方时，移除相应不可授予的权限声明后重建签名、独立安装。不能借用已安装的 03 bundle 给 06 跑用例。
+- napi_unwrap/TypeError 本身不能证明版本不兼容。先核对 debug 模式、发行模板和 libelectron 的同源性。
+- 若日志明确缺 ffi_bindings.node/ref_binding.node，检查同版发行资源中的桥接模块及 electron/libs/arm64-v8a 打包结果。仅使用可追溯且 ABI 匹配的版本，不从随机成功库复制二进制。
+- `Cannot find module web_engine`：检查 electron/oh-package.json5 的本地依赖、ohpm 安装结果、web_engine 的导出及模块注册。先在本工作区构建无业务模板。compatibleSdkVersion 声明不等同于实际编译 SDK 版本，不能据此断言必须换宿主。
+
+## 已验证：独立 Node 的 HNP 调试路径
+
+- 使用有版本与来源记录、已确认可安装执行的 OHOS Node 发行物。核对架构、依赖、实际打入 HNP 的文件和安装位置。
+- 明确把完整 HNP runner HAP 传给签名工具；不要误签 hvigor 生成的、不含 Node 的小 entry HAP。
+- app 域 JIT 或 io_uring 限制：先取 faultlog 的信号、syscall 号或 V8 错误，再按目标版本选择 --jitless、实际支持的 libuv 开关或返回 ENOSYS 的受限 syscall fallback。不能把 UV_NO_IO_URING=1 或 UV_USE_IO_URING=0 当成所有发行物有效的固定配方；环境变量设置成功不证明禁用了调用。核对 shim 的导入符号、加载 marker、实际路径和哈希，详见 [原生运行诊断](native-runtime.md#node-startup)。
+- 9568393 要区分 HAP 包签名与 HNP 可执行文件代码签名。禁止 llvm-objcopy 添加全零签名段冒充合法签名。先对比已验证发行物与本工程打包流程，而非立即认定 macOS 无解。
+- rc=-2/零输出不唯一指向 SIGSEGV；检查 runner 对 waitpid/signal 的实际映射。记录子进程 signal/errno/stderr，再建立最小探针。其他同机 HNP 成功是必须解释的反例，不得泛化“所有 N-API .so 都会使 HNP 无法执行”。
+
+## 需要实验：原生异步回调挂起
+
+先读 [原生异步工作诊断](native-runtime.md#async-work)。它规定纯 JS、最小 N-API、库调用三层对照，以及 create/queue/execute/complete 的返回值、线程和生命周期取证。sqlite3 的既有 V8/jitless 归因尚未证实；构造器内同步 complete 会改变时序并可能释放仍被调用方使用的任务，不能沉淀为成功配方。
+
+## 阶段与证据隔离
+
+- 参考其他库只读。需要对照则复制完整参考材料到本工作区的独立诊断目录，另用 bundle；禁止对源库执行 sign-demo、构建或安装替换。
+- Node 库 sign-demo 必须传 --demo-dir、--hap（本轮 unsigned 输入），使用返回的 signedHap 与 hap_sha256。签名自验成功后原子替换本工程 dist/app/current-signed.hap；失败保留旧完整包但不得当成本轮成功。不要重复签名当前 signed 包，安装直接使用构建返回路径。
+- node-demo-results 只把日志封存到本工程 verify/artifacts；HAP 始终引用 dist/app/current-signed.hap，必须传 --hap-sha256 <实际安装时记录的哈希>。取证时不得重新计算哈希来掩盖包已替换。重建后旧结果哈希失配，必须重新安装运行；独立验收核对结果 hap_sha256 后安装同一当前包，不再次签名。历史 JSON/日志保留，历史二进制不再保证可重放。
+- 构建、签名、取证和 Web 导出/上传共用工程占用锁；遇到“工程正被占用”应等待当前操作结束后重试，不改名绕开。锁主进程及成员均已退出时自动回收；锁记录不完整则拒绝写入，先确认相关进程已结束再处理残留锁。Web 与插件应配套更新，锁文件不进入导出或上传产物。
+- 06 只消费 03 库产物；发现产品缺陷反馈 03，通过返修入口升级库版本后重新验证依赖宿主。不得在 06 私下修 source、patches、dist/lib 或 harmony-demo*。
+- Web 单阶段结束后会重新查询 gate，在本次 03 最多 5 次、06 最多 2 次的预算内续修；ask/block/验收移交/取消/执行错误停止并保留原因。检测到跨阶段改写会停止且保留现场，不自动回滚用户工作。
+
+用户在 Web 明确重新执行 03/06 时，会先归档该阶段的历史计数、派发账本、报告和日志，再开启新修复批次。仅重置本阶段预算；保留原报告、有效 Demo 和验收证据。自动返修以及“继续会话”沿用当前预算，不能通过循环重置次数绕过上限。存在未结算派发时拒绝重置，先核实任务状态。
+
+## 阻塞结论证据
+
+平台/SDK/V8 不支持必须有无目标库的最小复现、版本指纹、真实错误以及同环境成功案例的差异解释。没有这些证据，只能写“根因未确认，当前实验失败”。
+权限拒绝、设备断开、包安装失败、预算耗尽分别记录；不能统一写成环境死锁。预算耗尽表示自动尝试结束，不表示平台不可适配，也不能降低原用例断言。
+
+## 构建模式与启动归因
+
+当前 Node.js 库的两个宿主均检查实际 debug HAP。Node 显式 assembleHap -p buildMode=debug，选择当前模块准确的 unsigned HAP 路径，禁止 find | head 命中旧 assembleApp 子目录产物。Electron demo 调试验证必须使用固定构建入口；签名及新结果登记会读取实际 HAP 的 module.json，要求 app.buildMode=debug 且 app.debug=true。assembleApp 不显式指定模式可能产出 release；构建成功与装机成功均不能证明包符合验证配方。
+
+进程未存活时，保存本 bundle 的启动时间、PID、退出原因及完整日志。其他 Electron 应用进程存在不能证明资源冲突，不能据此要求重启设备或终止其他库进程。优先核对实际安装包与同版本成功包的模式、模块及启动参数。06 汇总必须用 node-demo-results --summary，单宿主通过不能写全阶段 passed。
+
+配置传递和自动汇总的完整执行顺序见 [06 固定顺序](stages.md#06-固定顺序工程配方与用例分离)。03 的通过仅证明工程配方可参考，不能替代 06 按 05 名册运行。构建配置检查失败属于可修复配置差异，不能记为平台不支持。

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

@@ -0,0 +1,66 @@
+# 各阶段的专项执行要求
+
+适用范围与共同约束见 [Skill 入口](../SKILL.md)。按当前阶段及角色读取对应章节，不把本文件整段复制进阶段提示词。
+
+## scan
+
+01 识别独立 Node 使用模式，写 `node_library.runtime_mode/reason/evidence`：
+
+- 有独立 Node 使用模式为 `node-and-electron`；有效使用必须依赖 Electron 才为 `electron-only`，同时声明 `harmony_adaptation.host_runtime=electron-oh` 供装载契约使用。
+- evidence 为 `source/file:line` 数组。开发依赖、选用的主宿主、环境缺失或构建失败不能证明 Electron-only；不能按包名判定。
+- 逐功能识别 Electron main/preload/renderer/IPC 需求，保留在 PRD。不能因 Node 无法执行就放入 scope_out。
+- 历史补扫保留有效源码、工程和证据；若旧 PRD 曾排除 Electron 功能，修正需求范围，让下游按更新后的需求审查名册。
+
+## cases
+
+02 和 05 各自维护一份跨宿主共享名册，并非每宿主复制一份，也不是把两个阶段的名册合并。普通用例省略 `node_library` 表示全部必需宿主；确有宿主限制时标：
+
+`node_library: {hosts, reason, evidence, process?}`
+
+hosts 为 `device-node` / `electron-oh` 的非空子集；缩小范围必须有 reason 与 `source/file:line` 依据。按需标 process 为 main/preload/renderer/multi-process。Electron 专属功能仅在 Electron 验证，不从 PRD 或名册删除，也不使用 platform_exclusive 表示宿主差异。
+
+- 02 保持原始 `name`。补写用例的开发机预跑使用真正适用的运行时；Electron-only 不要求独立 Node 预跑，所需运行时缺失按原有 host_run.unavailable 规则记录。
+- 05 从 PRD 逐功能设计，保持原始 `id`，保留已有的步骤、断言、自评审和职责边界。
+
+## develop
+
+新工程先按 [固定工程工具](managed-projects.md) 完成全部必需宿主的标准 probe；通过后才接入目标库业务。工程失败记录为载体层，不能在库源码中试修。
+
+03 按 [工程与取证](examples.md) 执行，只处理 `state.library_examples` 中 stage=3 的工程。先准备全部必需工程并分别取得首轮构建/运行结果，再集中续修；Node/Electron 原生产物分别构建。命中原生扩展时，编码前读取 [原生扩展流程](native-addon.md)，按通用流程分析当前源码、构建依赖并核对两个宿主的装载契约；不能把主要宿主的链接方式直接用于另一个宿主。
+
+每工程由 `node-demo-results` 派生适用名册并生成结果，填写 `examples[].result_file`；共同名册通过 `--summary` 按用例去重取所有适用宿主的最差结果。这替换默认单载体 roster-results 流程，不要求某宿主执行另一宿主的专属用例。
+
+返修先运行 `node-demo-diagnose` 并读取 [自动恢复](recovery.md)，启动失败与零用例输出同样进入修复。恢复先核对全部必需工程和证据有效性，只补缺项；保留有效结果，不退回只修主要宿主。所有必需工程真实通过才可完整成功，具体续修预算与结果失效规则见工程参考。
+
+## verify
+
+本角色独立验收，不能只读取开发方结果后背书。 原生库同时按 [原生扩展验收](native-addon.md#验收与交付) 检查回调时序、资源生命周期和真实调用，不能把同步替代异步后的计数通过视为语义正确。读取 stage=3 工程清单，核验每工程的 HAP、适用名册、宿主运行标记、断言和工具结果，并复核 electron-only 或缩小用例宿主范围的源码依据。
+
+逐工程先核对当前 HAP 与开发方结果 hap_sha256 一致，再部署已交付 HAP，真实复跑适用名册，不重建、不改 Demo、不改库。按 [工程与取证](examples.md) 的 `node-demo-results --stage 3` 命令，以本次新设备日志和原 HAP 生成该工程 `verify/dev_verify_loop<N>.results.json`；日志也放在该工程 verify 下，使用未占用的新编号。此独立结果替换默认单载体的 dev_verify_loop 结果路径和 roster-results 命令，不覆盖开发方文件、不修改 03-adapt.json 的 result_file。
+
+逐用例对比独立结果、03 examples 指向的开发方结果与原始日志，在 verify-verdict.json 的 diagnosis 中列明本轮核对的工程、双方结果路径及差异。不要用 `--summary` 代替独立结果对比：该命令读取 03 报告指向的开发方结果。任何必需工程缺失、未运行或未通过，不得背书完整成功；可确认如实报告的部分结果。Electron 专属功能须在真实 Electron 上下文验证，不能用 Node mock 替代。
+
+## summary
+
+04 读取 `state.node_library_demos`，分别汇总 stage=3 必需工程的构建、真机验证与阻塞。任何必需工程未完成，不得写完整适配成功；03 缺失时仍基于已有事实如实汇总。electron-only 不把不存在的 Node 工程列为未完成。
+
+06 测试结论单列，不反向修改 03 结论。
+
+## test
+
+06 失败时按 [自动恢复](recovery.md) 处理；按 [工程与取证](examples.md) 执行，只处理 stage=6 的工程。每宿主消费 03 对应产物，缺产物写 blocked 并反馈 03，不在本阶段修改库。
+
+按宿主派生适用名册、逐条接线并生成各工程独立结果。共同 case_results/coverage 使用 `--summary` 按用例去重取所有适用宿主最差结果。工程各自保留证据，不能全部写进默认 test-demo 路径。
+
+全绿需所有必需工程完成；恢复时即使已有 passed/partial 报告，也核对缺工程和证据失效。此流程替换通用模板的固定 native 接线与结果格式，保留每步真实断言、用例 ID、功能覆盖和不修改库的职责边界。
+
+### 06 固定顺序（工程配方与用例分离）
+
+托管工程按 [固定工程工具](managed-projects.md#06-继承) 对每个宿主执行 inherit/probe/build；下列第 2、3 步只用于历史未托管 Electron 工程。用例接线、运行、汇总仍按下列要求，不复制 03 suite。
+
+1. 读取 05 名册，使用 `node-demo-results --stage 6 --host-runtime <host> --prepare --out <本工程>/cases.json` 派生当前宿主用例。03 使用 02 名册；两阶段用例不能互换。已存在名册先比对，不覆盖有效结果。
+2. Electron 工程创建后执行 `ohpt-agent node-demo-config -w <ws> --json`，核对差异；需要同步白名单配置时加 `--apply`。该工具重新验证 03 证据，保留目标 bundle 和 05 用例，备份被改配置。白名单仅包含构建配置、模块依赖/声明、WebWindow 运行时支撑；不复制 app-src、suite、cases、测试夹具、验证结果、HAP、签名材料。原生运行库仅核对哈希，差异时从同版发行资源准备，不拷贝他库二进制。业务入口 main.cjs 内额外启动参数单独核对、按需重写，禁止复制整个入口。
+3. 运行 `node skills/pc-node-library/scripts/build-electron-demo.cjs --workspace <ws> --stage 6 --install`（脚本路径相对于插件根）。构建前自动检查配置差异；存在差异则停止并修正。其他宿主沿用各自固定构建方式和 03 已验证产物，不借用 03 HAP。
+4. 在真实设备执行。新模板输出 OHPTSTART 分层事件：app-ready → host-probe → suite-load → case-execution；失败事件包含错误栈。先宿主探针，再加载套件。事件不能代替业务断言；没有日志只能标根因未确认。
+5. `node-demo-diagnose -w <ws> --stage 6 --log <本工程原始日志>` 定位失败层。安装失败保留 build-attempts 的 sign-install 原始输出；无 app-ready 则核对包内 debug/bundle、精确 PID 和退出原因。不得根据其他应用进程存在推断必须重启设备。
+6. 两工程各自产出 node-demo-results，将 result_file 写入 06 examples 后，执行 `node-demo-results -w <ws> --stage 6 --summary --write-report --out test-demo-electron/verify/summary-<新编号>.json`。工具仅重算 06 的 status、coverage、case_results，备份原报告；缺宿主如实写 partial，不能手填单侧 passed。最后 gate --stage 6 复核，人工篡改汇总仍被门禁拒绝。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/scripts/build-electron-demo.cjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),{spawnSync}=require('node:child_process'),{parseArgs}=require('node:util');
+const {isNodeLibrary}=require('./node-library-policy.cjs');
+const {stageApp}=require('./stage-app.cjs');
+const slots=require('./current-hap.cjs');
+function build({workspace,stage,install=false,assembled=false},run=spawnSync){
+ const ws=fs.realpathSync(workspace);
+ if(![3,6].includes(Number(stage)))throw Error('stage 必须为 3/6');
+ const scan=JSON.parse(fs.readFileSync(path.join(ws,'.ohos-adaptation-pc/01-scan.json'),'utf8'));
+ if(!isNodeLibrary(scan))throw Error('仅支持 Node.js 三方库');
+ const project=Number(stage)===3?'harmony-demo-electron':'test-demo-electron',root=slots.projectRoot(ws,project);
+ if(root!==path.join(ws,project))throw Error('demo 不得链接到其他工作区');
+ return slots.withProject(root,()=>{
+ const attempt=path.join(root,'verify','build-attempts',Date.now()+'-'+process.pid);fs.mkdirSync(attempt,{recursive:true});
+ const facts={stage:Number(stage),project,build_mode:'debug',started_at:new Date().toISOString(),steps:[],status:'running'};
+ const save=()=>fs.writeFileSync(path.join(attempt,'attempt.json'),JSON.stringify(facts,null,2)+'\n');
+  // Windows 宿主：DevEco 的 ohpm/hvigorw 是 Unix sh 脚本（无扩展名），spawnSync 直调必 ENOENT；
+  // tool() 已优先给出 node + JS 入口（数组命令）；无 JS 入口时回退同名 .bat/.cmd，并以
+  // shell:true 单串执行（路径含空格，cmd.exe /c 引号数组方式实测失败）。
+  function step(name,cmd,args){
+   const parts=Array.isArray(cmd)?cmd:[cmd],c=parts[0],pre=parts.slice(1);
+   let exec=c,execArgs=[...pre,...args],opts={cwd:root,encoding:'utf8',timeout:600000,maxBuffer:32*1024*1024};
+   if(process.platform==='win32'&&parts.length===1){const bat=c+'.bat',cmdX=c+'.cmd';const p=fs.existsSync(bat)?bat:(fs.existsSync(cmdX)?cmdX:null);if(p){exec='"'+p+'" '+execArgs.map(a=>'"'+a+'"').join(' ');execArgs=[];opts.shell=true;}}
+   const r=run(exec,execArgs,opts);
+   fs.writeFileSync(path.join(attempt,name+'.log'),(r.stdout||'')+'\n'+(r.stderr||''));
+   facts.steps.push({name,command:parts.concat(args),exit:r.status,error:r.error?.message,log:path.relative(ws,path.join(attempt,name+'.log'))});save();
+   if(r.error||r.status!==0)throw Error(name+' 失败；先查看本轮日志，不得归因为库不支持');return r;
+  }
+   slots.clearOutputs(root,'electron');
+  let injected=null;   // 注入临时包路径（review #3）：提升到 try 外，finally 才够得着清理
+  try{
+   if(Number(stage)===6&&!assembled)step('config-preflight',process.execPath,[path.resolve(__dirname,'../../../dist/agent-cli.js'),'node-demo-config','-w',ws,'--json']);
+   if(!assembled)stageApp({project:root});
+    const studio=process.env.DEVECO_SDK_HOME?path.dirname(process.env.DEVECO_SDK_HOME):null;
+    const tool=(name,relative,jsEntry)=>{
+     const abs=studio&&fs.existsSync(path.join(studio,relative))?path.join(studio,relative):name;
+     if(process.platform==='win32'&&jsEntry&&abs!==name&&fs.existsSync(path.join(path.dirname(abs),jsEntry)))return [process.execPath,path.join(path.dirname(abs),jsEntry)];
+     return [abs];
+    };
+    step('dependencies',tool('ohpm','tools/ohpm/bin/ohpm','pm-cli.js'),['install','--all']);
+    step('build',tool('hvigorw','tools/hvigor/bin/hvigorw','hvigorw.js'),['assembleHap','-p','product=default','-p','buildMode=debug','--no-daemon']);
+   let hap=path.join(project,'electron/build/default/outputs/default/electron-default-unsigned.hap');
+    // 私有 HNP 注入（recipe runtime["electron-oh"].hnp 声明时启用）：hvigor assembleHap 不收
+    // hnp/arm64-v8a 条目，而 module.json5 hnpPackages 声明 + zip 条目缺失会 install failed
+    // （2026-10-15 HAD-W32 实证）。注入只替换目标条目 hnp/arm64-v8a/<name>.hnp——其余 .hnp
+    // 属其他工具/运行时，静默删除会让 module.json 声明失配（review #2）；注入前断言
+    // module.json 的 app.debug/buildMode=debug，防把 release 包当 unsigned 送签。签名的是注入后的包。
+    // recipe 读取容错：未声明 HNP 的普通工程（含 assembled 直签场景）可能没有 demo-recipe.json，
+    // 读不到 = 不注入，走原路径。
+    let hnpRel=null;
+    try{const recipe=JSON.parse(fs.readFileSync(path.join(root,'demo-recipe.json'),'utf8'));hnpRel=recipe.runtime&&recipe.runtime['electron-oh']&&recipe.runtime['electron-oh'].hnp;}catch{}
+    if(hnpRel){
+    const hnp=path.resolve(ws,hnpRel);
+    if(!hnp.startsWith(ws+path.sep)||!hnp.endsWith('.hnp'))throw Error('hnp 必须指向工作区内 .hnp 文件');
+    if(!fs.existsSync(hnp))throw Error('hnp 不存在: '+hnpRel);
+    injected=path.join(attempt,'hnp-injected-unsigned.hap');
+    step('hnp-inject',process.env.PYTHON||'python3',['-c','import zipfile,json,sys,os\nsrc,hnp,out=sys.argv[1:]\ntarget="hnp/arm64-v8a/"+os.path.basename(hnp)\nwith zipfile.ZipFile(src) as zi,zipfile.ZipFile(out,"w",zipfile.ZIP_DEFLATED) as zo:\n app=json.loads(zi.read("module.json"))["app"]\n assert app.get("debug") is True and app.get("buildMode")=="debug","Expected debug HAP"\n for info in zi.infolist():\n  if info.filename!=target: zo.writestr(info,zi.read(info))\n zo.write(hnp,target)',path.resolve(ws,hap),hnp,injected]);
+    hap=path.relative(ws,injected);
+   }
+   const args=[path.resolve(__dirname,'../../../dist/agent-cli.js'),'sign-demo','-w',ws,'--demo-dir',project,'--hap',hap,'--json'];if(install)args.push('--install');
+   const signed=JSON.parse(step('sign-install',process.execPath,args).stdout);
+   if(!signed.ok)throw Error(signed.error||'签名未成功');
+   facts.signed_hap=signed.signedHap;facts.hap_sha256=signed.hap_sha256;facts.status=install?'installed-pending-test':'signed-pending-test';save();return facts;
+  }catch(e){facts.status='failed';facts.error=e.message;save();throw e;}
+  // 注入临时包必须清理（review #3）：clearOutputs 只清模块 build 输出，verify/build-attempts
+  // 下的注入中间产物在成功/失败路径都会残留。只删本次生成的注入包，日志与 attempt.json 保留；
+  // 签名产物在 dist/app/（sign-demo 落盘），不受影响。嵌套 finally：清理失败也不跳过 clearOutputs。
+  finally{try{if(injected)fs.rmSync(injected,{force:true});}finally{slots.clearOutputs(root,'electron');}}
+ });
+}
+module.exports={build};
+if(require.main===module){const {values}=parseArgs({options:{workspace:{type:'string'},stage:{type:'string'},install:{type:'boolean'}}});try{console.log(JSON.stringify(build(values),null,2));}catch(e){console.error(e.message);process.exitCode=1;}}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/scripts/build-node-demo.cjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),cp=require('node:child_process');
+const {isNodeLibrary,examples}=require('./node-library-policy.cjs');
+const slots=require('./current-hap.cjs');
+function build({workspace,stage,hnp:hnpPath,install=false,module:moduleName='entry'},spawn=cp.spawnSync) {
+ const ws=fs.realpathSync(workspace);stage=Number(stage);
+ const scan=JSON.parse(fs.readFileSync(path.join(ws,'.ohos-adaptation-pc/01-scan.json')));
+ if(!isNodeLibrary(scan)||![3,6].includes(stage))throw Error('仅支持 Node.js 三方库 stage 3/6');
+ const item=examples(scan).find(e=>e.stage===stage&&e.host_runtime==='device-node');
+ if(!item)throw Error('device-node 不是必需工程');
+ const demo=slots.projectRoot(ws,item.project_dir);
+ if(!demo.startsWith(ws+path.sep))throw Error('工程越界');
+ const hnp=fs.realpathSync(path.resolve(ws,hnpPath));
+ if(!hnp.startsWith(demo+path.sep)||!hnp.endsWith('.hnp'))throw Error('HNP 必须属于当前工程');
+ if(!/^[\w-]+$/.test(moduleName))throw Error('无效 module');
+ const sdk=process.env.DEVECO_SDK_HOME;if(!sdk)throw Error('缺少 DEVECO_SDK_HOME');
+ // Windows spawnSync 无法执行无扩展名 POSIX 启动脚本（ohpm/hvigorw ENOENT，python3 为 Store 桩），
+ // 统一改走 node + JS 入口；PYTHON 环境变量优先（与 demo-project.cjs 打包通道一致）。
+ // run() 另保留 .bat/.cmd 兜底（DevEco 的 ohpm/hvigorw 亦有同名 .bat/.cmd，shell:true 单串执行）。
+ const isWin=process.platform==='win32';
+ const hvigorBin=path.resolve(sdk,'../tools/hvigor/bin'),ohpmBin=path.resolve(sdk,'../tools/ohpm/bin');
+ const hvigor=isWin&&fs.existsSync(path.join(hvigorBin,'hvigorw.js'))?[process.execPath,path.join(hvigorBin,'hvigorw.js')]:[path.join(hvigorBin,'hvigorw')];
+ const ohpm=isWin&&fs.existsSync(path.join(ohpmBin,'pm-cli.js'))?[process.execPath,path.join(ohpmBin,'pm-cli.js')]:[path.join(ohpmBin,'ohpm')];
+ const python=process.env.PYTHON||'python3';
+ return slots.withProject(demo,()=>{
+ const attempt=path.join(demo,'verify/build-attempts',`${Date.now()}-${process.pid}`);fs.mkdirSync(attempt,{recursive:true});
+ function run(command,args,cwd,name){const parts=Array.isArray(command)?command:[command],c=parts[0],pre=parts.slice(1);let exec=c,execArgs=[...pre,...args],opts={cwd,encoding:'utf8',maxBuffer:32*1024*1024};if(process.platform==='win32'&&parts.length===1){const bat=c+'.bat',cmdX=c+'.cmd';const p=fs.existsSync(bat)?bat:(fs.existsSync(cmdX)?cmdX:null);if(p){exec='"'+p+'" '+execArgs.map(a=>'"'+a+'"').join(' ');execArgs=[];opts.shell=true;}}const r=spawn(exec,execArgs,opts);fs.writeFileSync(path.join(attempt,name+'.log'),(r.stdout||'')+(r.stderr||'')+(r.error?String(r.error):''));if(r.status!==0)throw Error(name+' failed; see '+attempt);return r.stdout;}
+ // Delete only this expected generated output: an up-to-date result cannot select an old app/ HAP.
+ const unsigned=slots.safePath(demo,moduleName+'/build/default/outputs/default/'+moduleName+'-default-unsigned.hap');
+ const output=slots.safePath(demo,'dist/app/.node-runner-unsigned.hap',true);
+ slots.clearOutputs(demo,moduleName);fs.rmSync(output,{force:true});
+ try {
+ run(ohpm[0],[...ohpm.slice(1),'install','--all'],demo,'dependencies');
+ run(hvigor[0],[...hvigor.slice(1),'assembleHap','-p','product=default','-p','buildMode=debug','--no-daemon'],demo,'build');
+ if(!fs.existsSync(unsigned))throw Error('缺少本轮明确 unsigned HAP: '+unsigned);
+ run(python,['-c',`import zipfile,json,sys
+src,hnp,out=sys.argv[1:]
+with zipfile.ZipFile(src) as zi,zipfile.ZipFile(out,'w',zipfile.ZIP_DEFLATED) as zo:
+ app=json.loads(zi.read('module.json'))['app']
+ assert app.get('debug') is True and app.get('buildMode')=='debug','Expected debug HAP'
+ for info in zi.infolist():
+  if not info.is_dir() and not info.filename.endswith('.hnp'): zo.writestr(info,zi.read(info))
+ zo.write(hnp,'hnp/arm64-v8a/'+__import__('os').path.basename(hnp))
+`,unsigned,hnp,output],demo,'package');
+ const cli=path.resolve(__dirname,'../../../dist/agent-cli.js');
+ const args=[cli,'sign-demo','-w',ws,'--demo-dir',item.project_dir,'--hap',path.relative(ws,output),'--json'];
+ if(install)args.push('--install');
+ const signed=JSON.parse(run(process.execPath,args,ws,'sign-install'));
+ if(!signed.ok||(install&&signed.installed!=='success'))throw Error('签名或装机未成功: '+attempt);
+ const result={status:install?'installed-pending-test':'signed-pending-test',hap:path.relative(ws,signed.signedHap),signed_hap:signed.signedHap,hap_sha256:signed.hap_sha256,attempt:path.relative(ws,attempt)};
+ fs.writeFileSync(path.join(attempt,'attempt.json'),JSON.stringify(result,null,2));return result;
+ } finally {fs.rmSync(output,{force:true});slots.clearOutputs(demo,moduleName);}
+ });
+}
+module.exports={build};
+if(require.main===module){
+ const {parseArgs}=require('node:util');
+ try {const {values}=parseArgs({options:{workspace:{type:'string'},stage:{type:'string'},hnp:{type:'string'},module:{type:'string'},install:{type:'boolean'}}});console.log(JSON.stringify(build(values),null,2));}
+ catch(e){console.error(e.message);process.exitCode=1;}
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/scripts/create-electron-example.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+// 只物化示例工程，运行时资源由既有 Electron 应用配方供给。
+const fs = require('node:fs');
+const path = require('node:path');
+const {parseArgs} = require('node:util');
+const JSON5 = require('json5');
+const {caseDocument} = require('./node-library-policy.cjs');
+
+function create({workspace, stage, bundle, template}) {
+  if (![3, 6].includes(Number(stage))) throw Error('stage 必须为 3 或 6');
+  if (!/^[a-zA-Z][\w]*(\.[a-zA-Z][\w]*)+$/.test(bundle || '')) throw Error('需要独立 bundleName');
+  workspace = fs.realpathSync(workspace);
+  const dir = Number(stage) === 3 ? 'harmony-demo-electron' : 'test-demo-electron';
+  const dest = path.join(workspace, dir);
+  if (fs.existsSync(dest)) throw Error('工程已存在；保留并编辑，不自动覆盖：' + dest);
+  const source = path.join(workspace, '.ohos-adaptation-pc', Number(stage) === 3 ? '02-baseline.json' : '05-testcases.json');
+  const doc = JSON.parse(fs.readFileSync(source, 'utf8').replace(/^\uFEFF/, ''));
+  if (!Array.isArray(doc.cases) || !doc.cases.length) throw Error('上游名册为空');
+  const scan = JSON.parse(fs.readFileSync(path.join(workspace, '.ohos-adaptation-pc/01-scan.json'), 'utf8').replace(/^\uFEFF/, ''));
+  const cases = caseDocument(scan, doc, Number(stage), 'electron-oh', {source: path.relative(workspace, source)});
+  if (!template) {
+    let env;
+    try { env = JSON.parse(fs.readFileSync(path.join(workspace, '.ohos-adaptation-pc/00-env.json'), 'utf8').replace(/^\uFEFF/, '')); } catch { /* below gives actionable error */ }
+    const runtime = env?.capabilities?.electron_runtime;
+    if (!runtime?.found || !runtime.ohos_hap) throw Error('未探到 Electron-OH 运行时工程；先配置运行时并执行 ohpt-agent env，或显式传入完整同版 --template');
+    template = runtime.ohos_hap;
+  }
+  template = fs.realpathSync(template);
+  if (!fs.existsSync(path.join(template, 'build-profile.json5'))) throw Error('需要 HAP 模板');
+  if (dest === template || dest.startsWith(template + path.sep)) throw Error('输出不能位于模板内');
+  if (fs.existsSync(path.join(template,'app-src'))) throw Error('模板含 app-src，请使用无业务示例的模板');
+  const profile = JSON5.parse(fs.readFileSync(path.join(template, 'build-profile.json5'), 'utf8'));
+  const app = JSON5.parse(fs.readFileSync(path.join(template, 'AppScope/app.json5'), 'utf8'));
+  // 模板的开发者签名材料不进入新工程。
+  delete profile.app?.signingConfigs;
+  for (const product of profile.app?.products || []) delete product.signingConfig;
+  app.app.bundleName = bundle;
+  fs.cpSync(template, dest, {recursive: true, filter: p => !['node_modules', 'oh_modules', 'build', '.hvigor', '.git', 'oh-signing'].includes(path.basename(p)) && !/\.(p12|pfx|pem|key|cer|csr)$/.test(p)});
+  fs.writeFileSync(path.join(dest, 'build-profile.json5'), JSON.stringify(profile, null, 2));
+  fs.writeFileSync(path.join(dest, 'AppScope/app.json5'), JSON.stringify(app, null, 2));
+  const appDir = path.join(dest, 'app-src');
+  fs.mkdirSync(appDir);
+  fs.writeFileSync(path.join(appDir, 'cases.json'), JSON.stringify(cases, null, 2));
+  fs.writeFileSync(path.join(appDir, 'package.json'), JSON.stringify({name:'library-example',version:'1.0.0',main:'main.cjs'}, null, 2));
+  fs.writeFileSync(path.join(appDir, 'suite.cjs'), "// 按 cases.json 的 ID 接入真实库测试，保留原断言与夹具。\nmodule.exports = {};\n");
+  for (const file of ['main.cjs','preload.cjs','index.html','renderer.js','run-suite.cjs','host-probe.cjs']) {
+    fs.copyFileSync(path.join(__dirname, '../templates', file), path.join(appDir, file));
+  }
+  return {project_dir: dir, app_dir: dir + '/app-src', host_runtime:'electron-oh', status:'not-run',
+    next:'按 Electron 应用配方补齐同版引擎/模块/图标、接入真实测试，再 stage-app、构建和设备验证。'};
+}
+module.exports = {create};
+if (require.main === module) {
+  const {values} = parseArgs({options: Object.fromEntries(['workspace','stage','bundle','template'].map(k=>[k,{type:'string'}]))});
+  process.stdout.write(JSON.stringify(create(values), null, 2) + '\n');
+}