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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/templates/skeleton-backend/README.md

@@ -0,0 +1,19 @@
+# skeleton-backend — OWB Layer-3 起步模板
+
+一个最小、可编译的库侧后端范例（GPU/EGL 路径）。演示 [PORTING_KIT](../../docs/PORTING_KIT.md) 的五步：绑 surface → 建 EGL 上下文 → 排空事件 → VSync 帧回调 → 清屏+SwapBuffers。
+
+## 用法
+1. 复制 `skeleton_backend.c`，把 `skeleton_*` 改成 `yourlib_*`。
+2. `drainEvents()` 里把 `OWB_Event` 翻成你库的事件类型。
+3. `onFrame()` 里把 `glClear` 换成你库的渲染。
+4. 编进你 HAP 的 native `.so`，链 `libohos_window_bridge.so` + `libEGL.so libGLESv3.so`。
+5. surface 就绪后调一次 `skeleton_start()`（例如 NAPI `OnSurfaceCreated` 里，或用 `napi/owb_napi.cpp` 的 `OWB_NAPI_HookXComponent` 自动接管 XComponent 回调后）。
+
+## 编译验证（standalone）
+```bash
+NDK="$DEVECO_SDK_HOME/default/openharmony/native"
+$NDK/llvm/bin/clang --target=aarch64-linux-ohos --sysroot=$NDK/sysroot \
+  -std=c99 -I ../../include -c skeleton_backend.c -o /tmp/skeleton.o
+```
+
+CPU-blit 工具包（GTK/Qt-raster）不用 EGL：把 `onFrame` 换成 `OWB_AcquireFrame`→逐行写 `fb.pixels`（用 `fb.stride`）→`OWB_CommitFrame`。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/templates/skeleton-backend/skeleton_backend.c

@@ -0,0 +1,107 @@
+// skeleton_backend.c — minimal OWB Layer-3 backend (GPU/EGL path).
+//
+// The smallest thing that proves a library-side backend: bind an OWB surface,
+// stand up an EGL/GLES context on its OHNativeWindow, then clear + swap every
+// VSync while draining input. Copy this file, rename skeleton_* to yourlib_*,
+// and replace clear-screen with your library's render + event translation.
+//
+// Build it into your HAP's native .so alongside libohos_window_bridge and call
+// skeleton_start() once a surface exists (e.g. from your NAPI OnSurfaceCreated,
+// or right after OWB registration). See ../../docs/PORTING_KIT.md.
+#include <EGL/egl.h>
+#include <GLES3/gl3.h>
+#include <stddef.h>
+
+#include "ohos_window_bridge.h"
+
+static EGLDisplay s_dpy = EGL_NO_DISPLAY;
+static EGLSurface s_surf = EGL_NO_SURFACE;
+static EGLContext s_ctx = EGL_NO_CONTEXT;
+static uint64_t   s_sid = 0;
+
+// ---- step 1: bind an available OWB surface -----------------------------------
+static int bindSurface(OWB_SurfaceInfo* out)
+{
+    int n = OWB_GetSurfaceCount();
+    for (int i = 0; i < n; i++) {
+        if (OWB_GetSurfaceInfoByIndex(i, out) == OWB_OK && !out->inUse) {
+            OWB_AcquireSurface(out->surfaceId);
+            return 1;
+        }
+    }
+    return 0;
+}
+
+// ---- step 2: EGL context on the OHNativeWindow -------------------------------
+static int initEGL(void* nativeWindow)
+{
+    s_dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY);
+    if (s_dpy == EGL_NO_DISPLAY) return 0;
+    eglInitialize(s_dpy, NULL, NULL);
+    eglBindAPI(EGL_OPENGL_ES_API);
+
+    const EGLint cfgAttrs[] = {
+        EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
+        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
+        EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8,
+        EGL_NONE
+    };
+    EGLConfig cfg; EGLint num = 0;
+    if (!eglChooseConfig(s_dpy, cfgAttrs, &cfg, 1, &num) || num < 1) return 0;
+
+    // OWB_GetNativeWindow returns the OHNativeWindow* (as void*).
+    s_surf = eglCreateWindowSurface(s_dpy, cfg, (EGLNativeWindowType)nativeWindow, NULL);
+    if (s_surf == EGL_NO_SURFACE) return 0;
+
+    const EGLint ctxAttrs[] = { EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE };
+    s_ctx = eglCreateContext(s_dpy, cfg, EGL_NO_CONTEXT, ctxAttrs);
+    if (s_ctx == EGL_NO_CONTEXT) return 0;
+
+    return eglMakeCurrent(s_dpy, s_surf, s_surf, s_ctx);
+}
+
+// ---- step 3: translate input (replace with your library's event types) -------
+static void drainEvents(void)
+{
+    OWB_Event ev;
+    while (OWB_PollEvent(&ev)) {
+        switch (ev.type) {
+            case OWB_EVENT_SURFACE_CHANGED: /* resize your viewport */ break;
+            case OWB_EVENT_KEY:   /* map ev.data.key.keyCode -> your key */ break;
+            case OWB_EVENT_MOUSE: /* ev.data.mouse.{x,y,button,action} */ break;
+            case OWB_EVENT_TOUCH: /* ev.data.touch.{x,y,action} */ break;
+            default: break;
+        }
+    }
+}
+
+// ---- steps 4+5: VSync -> render + swap ---------------------------------------
+static void onFrame(uint64_t surfaceId, uint64_t ts, uint64_t target, void* user)
+{
+    (void)surfaceId; (void)ts; (void)target; (void)user;
+    drainEvents();
+
+    OWB_SurfaceInfo info;
+    if (OWB_GetSurfaceInfoById(s_sid, &info) == OWB_OK)
+        glViewport(0, 0, info.width, info.height);
+
+    glClearColor(0.15f, 0.35f, 0.55f, 1.0f);  // <- your library renders here instead
+    glClear(GL_COLOR_BUFFER_BIT);
+
+    eglSwapBuffers(s_dpy, s_surf);
+}
+
+// ---- entry: call once a surface is registered --------------------------------
+int skeleton_start(void)
+{
+    OWB_Initialize();
+    OWB_SurfaceInfo info;
+    if (!bindSurface(&info)) return OWB_ERR_NOT_FOUND;
+    s_sid = info.surfaceId;
+
+    if (!initEGL(OWB_GetNativeWindow(s_sid))) return OWB_ERR_STATE;
+
+    OWB_RegisterFrameCallback(s_sid, onFrame, NULL);
+    onFrame(s_sid, 0, 0, NULL);  // paint first frame immediately
+    return OWB_OK;
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: pc-delivery-forms
+description: 交付形态——按 scan 判定的 delivery_form 决定「本形态额外必须做什么、怎么算验完」，并给出与形态解耦、按产物特征生效的交付必做项。覆盖 pure-runtime（纯 Python/JS/Java/Go 库）、native-extension（Python C 扩展/N-API/JNI/Rust cdylib）、cpp-lib（纯 C/C++ 库出 .so）、cli（命令行工具，需 ELF 签名 + HNP/PATH）、app 与 app-unsupported（GUI 应用）。阶段 3 按交付形态路由到本 skill；Qt 应用（C++ GUI、Qt6→Qt5）路由到 pc-recipe-qt-app。触发词：交付形态、delivery_form、交付必做项、纯运行时、pure-runtime、原生扩展、native-extension、C++ 库、cpp-lib、命令行工具、CLI、HNP 打包、PATH、ELF 签名、binary-sign-tool、harmony-demo、harmony-app、hap 打包、GUI 应用、app-unsupported、Python C 扩展、N-API、JNI、PyO3、maturin、node-gyp、cdylib、宿主运行时、host_runtime、Electron addon。
+---
+
+# pc-delivery-forms：交付形态
+
+只答两件事：**本形态额外必须做什么**、**怎么算验完**。共性骨架（读 scan / 依赖复用 / patches / 状态判定 / 产物落位 / 设备验证通道）不在这里。
+
+## 形态表
+
+| delivery_form | 额外必做 | 验完判据 |
+|---|---|---|
+| `pure-runtime` | 部署到设备运行时（运行时**随交付物自带**） | **双载体**都跑通（见下方「验证载体」） |
+| `native-extension` | 原生扩展交叉编译（语言差异见下方索引；**先定宿主运行时**，见下方分叉） | **双载体**都跑通（宿主不可再分发进 CLI 载体时单载体，照 `verify_carriers` 做） |
+| `cpp-lib` | `harmony-demo/` 验证工程：`ohpt-agent scaffold --kind cpp-lib-demo`（GUI 库用 `cpp-gui-owb-demo`）；装机 `ohpt-agent sign-demo -w "$WORKSPACE" --install` | **双载体**都跑通（上屏库除外，只需 HAP） |
+| `cli` | ELF 签名 + 私有 HNP 执行器部署（见下方「cli 的设备侧部署」） | 设备上**真跑出正确输出**（runner TAP） |
+| `app` | `harmony-app/` 应用工程（交付物，提交新仓）+ hap 落 `dist/app/`；装机同上 | 冒烟启动：窗口能开、主功能能用 |
+| `app-unsupported` | 不硬做，只在 summary 产路线图 | — |
+
+cli 的设备侧部署只有一条路：**私有 HNP 执行器**（`ohpt-agent scaffold --kind cli-hnp-runner`，
+私有 HNP + app 域 `fork+execv`）——鸿蒙 PC 上 `hdc shell` 是 shell 用户、`/data/local/tmp` 不可执行、
+公共 HNP 不存在，别的路都不通（见 pc-knowledge-base `platform/鸿蒙PC-hdc能力边界与取证通道.md`）。
+验完判据：runner 的 TAP 原始输出（**取日志前必须 `hilog -b D` 提级别 + 冷启动**，否则 INFO 写入时即被丢）。
+
+ELF 签名默认 `LDFLAGS='-Wl,--code-sign'`（链接期自签；post-link `strip` 会破坏签名段）。`binary-sign-tool` 仅在有 OpenHarmony Linux 全量包且需标准证书链时用（macOS SDK 不含）。
+
+## 验证载体（库形态要跑两种真实使用形式）
+
+同一个 `.so`，**被 HAP 进程 dlopen 调符号**与**链进 ELF 在 app 域子进程里跑**是两条加载路径——
+加载器、命名空间、依赖闭包都不同，**一条过不代表另一条过**。所以库形态要两份证据。
+
+**本轮该产哪些载体、各用哪个 `scaffold --kind`，由 `ohpt-agent state -w <ws> --json` 的
+`workspaces[].verify_carriers` 直接给出**（形态与能力域算出来的，随契约演进自动跟随）——
+**照它做，别在这里背表**。gate env 块的 `verify_carriers` 是同一份派生
+（`verify-carriers.ts` 单一真源）；gate 与 state 同为只读，查信息走哪个都免费——
+有界环计数只落在派发事件上，不落在判定调用上。结果逐载体填
+`test_run.carriers[]`（`evidence` 须真在盘且非空）；缺哪一半会被 gate 的有界修复环点名、
+并由 PostWrite 验收（`dual-carrier-evidence`）复核。
+
+**manual 档（§5c）下库形态的 demo/runner 载体与 app 交付应用同规则**：所有装机 HAP
+（含 `harmony-demo/`、`harmony-cli-runner/` 执行器）一律不做本地自签，阶段 3 止于无签
+构建，等用户在 DevEco/AGC 人工签名后经检查点 `--hap` 部署续跑；`sign-demo` 本地自签在
+manual 档被守卫拒绝（degraded 降级后放行）。**打包步骤 / ACL 语义 / 三选项 / 降级流程见
+`references/forms/app.md` 的「人工签名打包（manual 档）」节**（app/demo/runner 共用同一份）。
+
+两个会走错路的分叉：
+
+- **原生 `.node` → 先定宿主运行时**：设备端 Node（缺省）走 `references/languages/node.md`；Electron-OH 内置 Node 走 `pc-knowledge-base` 的 `electron/addon-build.md`。**两者 ABI 不同、产物不可互换**，走错则编得出、装得上、加载即失败。
+- 图形/窗口/GL 类库 → 先查 `pc-capability-domains` 判可行性，再决定编不编。
+- UI 本就是 ArkUI、只想内嵌运行时跑后端 → **不是** GUI 工具链栈问题，走 `harmonyos-pc-resources` 运行时嵌入指南。
+- **Qt 应用（C++ GUI，含 Qt6→Qt5 降级 + 完整 HAP 打包）** → 拉 `pc-recipe-qt-app` skill，按它的 5 阶段工作流走（check-compat → fix → build → hap → patch）。它是独立的完整工具链资产（fix docs + 脚本 + HAP 模板 + toolchain），本表只做路由。
+
+## 交付必做项（按产物特征，形态判错也生效）
+
+做不了的写进 `remaining_blockers`；静默跳过 = 假完成。
+
+| 产物特征 | 必做项 | 合格证据 |
+|---|---|---|
+| `dist/` 下有 ELF 可执行（非 `.so`/`.jar`/`.whl`/`.hap`） | ELF 签名 + 私有 HNP 执行器部署并**在设备上真跑** | 签名后路径入 `artifacts[]`，并留 runner 的 TAP/原始输出 |
+| 交付物是应用 | hap 真落 `dist/app/` | `dist/app/*.hap` 真在盘（工程骨架 ≠ 已构建） |
+| 交付物是库 `.so` 且需被调用验证 | `harmony-demo/` 验证工程 | demo 在盘 + 调用/上屏证据 |
+| 产物动态符号命中数据访问族（`nm -D` 见 `tgetent`/`tgetstr`/`bindtextdomain`/`dlopen` 数据路径等） | **运行时数据检查**（通用三步链，见 `pc-capability-domains/references/capability-domains/runtime-data-assets.md`）：E2 源码闭包 grep `/etc/`、`/usr/share/` 字面量 + 设备确认路径缺失 → 命中则数据随包（HNP `share/`）+ 环境自举 | `03-adapt.json` 记录缺口清单、随包路径、自举方式；行为差分用例通过（三段式模板见 `pc-test-design/case-design-methods.md` §6）——缺任一项不得标完整交付态 |
+| 产物命中**终端发射族**（`tputs`/`tgoto`/`wadd*` 源码 CSI 字面量）——⚠️ 非 GUI 库也可能有终端上屏（TUI/行编辑类） | **终端上屏验证**（见 `pc-capability-domains/references/capability-domains/terminal-render.md`）：PTY 真交互 + 屏幕 buffer 语义断言 | PTY 捕获落盘 + buffer 断言 JSON + 上屏截图三件齐（操作节见 `pc-device-verify`）——「序列在场」≠「上屏效果正确」 |
+| 做了任何设备验证 | `test_run.device` 指纹 | `os_version`/`device_class`(型号)/`arch`/`page_size`——**绝不写序列号** |
+
+仅 `ecosystem=nodejs/node && kind=library` 加载 `pc-node-library`：按 01 的运行模式在 03/06 各交付 Node+Electron 或仅 Electron；必需清单由 state.library_examples 给出，不能由 verify_carriers 免除。原生 addon 继续引用 Electron 配方。其他生态、应用、CLI/tool 沿用本表。
+
+## 语言薄 adapter（任何形态都可用）
+
+| 语言 | reference |
+|---|---|
+| Python C 扩展（setuptools / meson / Cython） | `references/languages/python.md` |
+| Rust / PyO3（cargo / maturin） | `references/languages/rust.md` |
+| Node N-API（node-gyp / CMake） | `references/languages/node.md` |
+| Java JNI（maven / gradle） | `references/languages/java.md` |
+
+鸿蒙目标三元组与构建系统调用方式 → `pc-knowledge-base`「通用约束」（唯一权威）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/references/forms/app.md

@@ -0,0 +1,94 @@
+---
+name: app 形态交付
+description: app 形态（GUI 应用）的工程流程与交付档位——构建链四步（应用构建→载荷同步→HAP 打包→签名装机）、HAP 工程生成（Electron = scaffold kind electron-app）、交付档位、鸿蒙化工程复用判据。触发词：app 形态、交付档位、构建链、sync-payload、载荷同步、convert、鸿蒙化工程复用、built-pending-verification、代码工程交付、品牌资源替换。
+metadata:
+  type: form
+---
+
+# app 形态：工程流程与交付档位
+
+**app 形态 = 交付物是 GUI 应用**（Electron / Qt / 其他 GUI 栈）。把它看成一个大的三方库：骨架（阶段、门禁、名册、报告）与库形态完全共用，差异全在本篇。宿主平台机制（Electron-OH 的三关治理、引擎选型、已知坑）在 `pc-knowledge-base/electron/electron.md`；验证执行在 `pc-device-verify/references/hap-verify.md`；Qt 的工具链流程在 `pc-recipe-qt-app`。
+
+## 交付档位（默认止于 HAP 打包，部署归运行测试阶段）
+
+阶段 3 **默认执行到 HAP 打包（含签名）完成即停**——`03-adapt status=built-pending-verification` + artifacts 含 `.hap`；**装机与部署+冒烟用例归运行测试阶段（pc-03-dev-verify）**：装机 → 拉起 → 存活确认 + 阶段 2 的 4 条冒烟用例（单启动周期覆盖，回填 test_run）。
+
+**停在代码工程交付态（构建链 ①② 完成即停、③④ 不做）三种触发**：**明示**（任务 prompt 含「打 HAP 包前停下来 / 代码工程交付 / HAP 我自己打」类要求）；**manual 档**（签名档位=manual——`OHPT_APP_SIGNING=manual` / `config.json` 的 `appSigning=manual`，覆盖所有需装机 HAP，本形态天然命中）；**降级**（auto 下签名材料/SDK 缺失，`00-env.json` / `env-decision.json` 判定）。停止时返回文本标注「**代码工程就绪待用户打包**」——编排器按 §5c 检查点转报打包指南并等用户选择。
+
+## 人工签名打包（manual 档，§5c）
+
+**触发**：签名档位=manual——`OHPT_APP_SIGNING=manual` / `~/.ohos-agent-pc-adapter/config.json` 的 `appSigning=manual` / 用户对话明说。manual 档下**所有装机 HAP 一律不做本地自签**（`sign-demo` 守卫拒绝；degraded 后放行），统一由用户在 DevEco Studio 人工签名（AGC 账号）后经检查点续跑。
+
+**覆盖的 HAP 工程**（`checkpoint.project_path` 区分三种）：
+
+| 工程 | 是什么 | 对应形态 |
+|---|---|---|
+| `harmony-app/` | 交付应用（提交新仓的交付物） | `app` |
+| `harmony-demo/` | 库形态验证载体（HAP 进程 dlopen 被测产物） | `cpp-lib` / `pure-runtime` / `native-extension` |
+| `harmony-cli-runner/` | CLI 执行器（app 域 fork+execv 真跑被测 CLI） | `cli`（及库形态的 cli 载体） |
+
+**适配编码止点（pc-03-dev-adapt-code 执行）**——manual 档下子 agent 的完整行为契约：
+- 构建出**无签 HAP**（工程链等价命令记入 `build_commands[]`）→ 核验包内结构与 module.json 权限声明（**kernel ACL 声明原样保留**——system_basic/core 级权限只有 DevEco/AGC 正式签名链能装机授予，这正是走人工签名的原因）
+- 写 `03-adapt.json status=built-pending-verification`；`test_run.carriers[]` 如实记「manual 档：待用户 DevEco 签名打包后执行」；`remaining_blockers[]` 标明「manual 签名档：无签 HAP 已构建，待用户在 DevEco Studio 签名打包」
+- **不** `sign-demo` 本地自签，**不**装机（无签包装不上，装机必失败）；demo/runner 验证载体与交付应用同规则——它们同样是装机 HAP，一律等人工签名后经检查点续跑
+- **返回文本必须包含「代码工程就绪待用户打包」**——编排器 §5c 靠这个标记识别等待态并 arm 检查点
+- 该止点是合法等待态，不占 gate 空手续跑额度
+- 续跑注入后按内容继续：人工 HAP 路径 → 用该包部署并跑阶段 2 名册（不要重签）；DevEco 失败日志 → 按报错续修工程、重建无签 HAP，再次返回「代码工程就绪待用户打包」；降级 → 走 strip-acl 后的本地自签流程
+- 续修轮（fix-requested 后被重派）沿用本止点：修复完成、无签 HAP 重建成功后同样返回「代码工程就绪待用户打包」——检查点轮次（round+1）由 CLI arm 记账，子 agent 不写 `human-checkpoint.json`
+
+**用户打包步骤（DevEco Studio）**：
+1. File → Project Structure → Signing Configs：勾选 **Automatically generate signature** 并登录 AGC 账号完成自动签名
+2. Profile 需含 kernel ACL（工程声明了 system_basic/core 级权限时；`checkpoint.instructions` 已按实际权限动态列出）
+3. Build → Build Hap(s)/APP(s) → Build Hap(s)：产出 `*-signed.hap`（检查点自动发现工程内最新产物，无需手动拷贝）
+4. 完成后反馈三选一：**打包完成**（附已签 HAP 路径）/ **打包失败**（附 DevEco 报错）/ **降级**
+
+**三选项续跑**：
+- `package-done`：CLI 四道闸（发现/新鲜度/防旧包/bundleName+签名自验）过 → `pc-03-dev-verify` 用人工 HAP 部署并跑阶段 2 名册，**不重签**（人工包就是验证对象）
+- `package-failed`：报错落 `build/human-package-round<N>.log` → 续修工程、重建无签 HAP → 重新 arm（round+1）→ 再次请用户打包
+- `degraded`（降级终态）：`ohpt-agent checkpoint strip-acl` 剥 kernel ACL → 重建无签 HAP → `sign-demo` 本地自签 → 按 auto 档继续，本轮不再回人工检查点
+
+## 构建链四步
+
+① **应用侧构建**（Electron = 应用 bundle 构建，`npm install` 默认 `--ignore-scripts`——宿主上原生模块 postinstall 是宿主 ABI 白编，见 electron.md 硬性约束 #17；Qt = 交叉编译产物）→ ② **载荷同步**（**Electron 用确定性命令 `ohpt-agent sync-payload`**：新鲜度自检 + require 面提取 + package.json 补声明防 npm prune 误裁 + `--shim` 垫片幂等生成 + 终检；Qt = `qt5-ohos.py` 的 init-hap/copy-so）→ ③ **HAP 打包**（hvigorw）→ ④ **签名装机**（`ohpt-agent sign-demo`）。
+
+**默认档位流水线做 ①②③**；**①② 必须做满**：「可直接构建」= 载荷新鲜（改过源码必须重建 bundle 再同步——hvigor/DevEco 不重建应用，跳步会产出改而未进的假包）。
+
+**工具链版本与 Java 面**：`sync-payload` 是插件 **beta.21+** 命令——旧版全局 CLI 无此子命令（打 usage 退出；web 编排经「同代自证」垫片不受影响，手工执行前先确认 PATH 命令与本地插件同代）；hvigorw `PackageHap` 阶段报 `spawn java ENOENT` 时把 DevEco `jbr\bin` 加进 PATH（仅设 `JAVA_HOME` 不够）。
+
+**双轨同步纪律**（涉及主进程 bundle 的修复）：源码 patch（`patches/`，可追溯）+ HAP resfile bundle 幂等注入（marker 前缀，用户手工打包时免重编即可装机验证）。装机前先对账 HAP 内 marker/构建时间，别信文件名。
+
+**分发路线事实**：第三方 HAP 普通用户装不了（侧载禁止 `9568401`）——免 hdc 分发走 **ZIP 包 + 用户级解压**（HiShell toybox 不一定带 unzip，同时出 `.tar.gz`）。HNP 本质是 ZIP（≤4GB、无强制 manifest、签名可选）。配置文件位置 **XDG 优先于 `~/.config`**。
+
+## HAP 工程搭建
+
+> **鸿蒙化工程直接复用（优先判定）**：工作区已带入完整鸿蒙化工程（四样齐：build-profile + hvigorfile + AppScope + electron 模块，带 .convert-record.json）→ **跳过工程搭建，直接使用**。
+
+**Electron（nodejs 生态）**——一条命令生成 + 机器校验（运行时先取一次：`ohpt-agent fetch-electron-toolchain --engine <v34.8.5|v37.2.3>`，落全局缓存，scaffold 缺 `--sdk-electron` 时自动从缓存同步 libs/启动器/resfile）：
+
+```sh
+ohpt-agent fetch-electron-toolchain --engine v37.2.3   # 首次转换先取运行时（~350MB，按需下载）
+ohpt-agent scaffold --kind electron-app -w "$WORKSPACE" --out harmony-app \
+  --name "AppName" --bundle com.vendor.app --engine v37.2.3 \
+  --icon app_icon.png     # --sdk-electron 可选：显式 SDK extract 优先，缺省用缓存运行时
+```
+
+自动完成：模板拷贝（`templates/hap/electron-app/<ver>/`，双版本血统配对）+ 占位符全量替换（含三份 label）+ 品牌图标双端覆盖 + SDK 同步（启动器/libs/页面注册）+ **11 项机器校验**（exit 1 即有 FAIL）。塞完业务资产后重跑：`ohpt-agent scaffold --kind electron-app --validate <工程> --name "AppName"`。
+
+`module.json5` 定制（scaffold 之后）：
+- `hnpPackages`（仅打了私有 HNP 时声明）
+- `requestPermissions` **按 01-scan 的 `permission_dependencies[]` 分轨声明（不凭记忆）**：`system_grant` 声明即生效；`user_grant` 声明 + EntryAbility 编排 `requestPermissionsFromUser` 弹窗（系统弹窗仅一次、拒绝后只能设置页改；**picker 授权已由模板补丁持久化**——DialogAdapter 选中目录经 `persistDialogSelection` 落 preferences 并在启动时重新激活，见 electron.md 硬性约束 #16；复用非模板工程时需手工移植该补丁）；`acl` 声明可保留 + `remaining_blockers` 如实记「AGC 在线申请不可免」。知识：`pc-capability-domains` 的 app-permissions 域。
+
+**代码内身份替换 + 互斥词断言**：模板已身份中立化，但复用既有工程时会把别的应用身份带进来——注释、日志 tag、常量名一律替换为本应用语义。机器执法：验收规则 `hap-identity-foreign`（`ohpt-agent check` 可查）。
+
+## 机器命令速查（Electron）
+
+| 动作 | 命令 |
+|---|---|
+| 运行时获取（首次，按需下载） | `ohpt-agent fetch-electron-toolchain --engine v34.8.5\|v37.2.3`（目录级引用 + blob sha 四层校验，落全局缓存；仅 Electron 形态需要） |
+| 工程生成 + 校验 | `ohpt-agent scaffold --kind electron-app -w <ws> --out harmony-app --name X --bundle b --engine v37.2.3 --icon i.png [--sdk-electron <dir>]`（缺省取缓存运行时） |
+| 重跑工程校验 | `ohpt-agent scaffold --kind electron-app --validate harmony-app --name X` |
+| 载荷同步 | `ohpt-agent sync-payload --bundle <产物> --app harmony-app/electron/src/main/resources/resfile/resources/app --src source/src` |
+| 编译前首扫 | `ohpt-agent prescan source/ -w <ws>`（自动探测 Electron 子包：白屏面以 `PSCAN-EWS-*` critical findings 并入报告 + `electron_scan` 节带权限/API 候选——白屏命中即必改，经 prescan 门禁处置/豁免；见 pc-error-atlas prescan 节） |
+| 确定性扫描 | `ohpt-agent scan-electron source/<app> --json`（独立排查工具，编码/验证阶段按需单跑；12 类白屏根因 L1-L4 带修法锚点 electron.md #N——不转写进 01-scan，白屏面已由 prescan 承接） |
+| 冒烟名册 | `ohpt-agent baseline-smoke -w <ws> --json` |
+| 签名装机 | `ohpt-agent sign-demo -w <ws>` |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/references/languages/java.md

@@ -0,0 +1,53 @@
+# Java JNI 扩展适配
+
+适用：Java 库含原生扩展（JNI 库、JNA 等）。交叉编译骨干见 `pc-knowledge-base`。
+
+## 交叉编译路径（Linux/Mac → 鸿蒙）
+
+### 构建命令
+
+- JNI 扩展：编译 native 库为 `lib<name>-harmonyos-aarch64.so`，与 jar 一起部署
+- 纯 Java 依赖直接 `mvn package` / `gradle build`
+
+### 扩展后缀
+
+`.so`（命名约定 `lib<name>-harmonyos-aarch64.so`）
+
+### 特有坑
+
+- JNI 头文件生成：`javac -h <dir>` 为含 `native` 方法的类自动生成（手动编译全流程范式见 pc-error-atlas E084，以 JNA 为例）
+- jar 内 native 库路径约定按各库的 loader 逻辑；鸿蒙 JDK 的 `os.name` 报告 OpenHarmony/HarmonyOS，库不识别时**两条策略**（判定要点=上游多平台资源目录结构是否可直接复用）：A 补丁 OS 探测映射到 Linux 目录、复用上游 `Linux/arm64` 资源结构（jansi 型，完整案例见 pc-knowledge-base `adaptation/鸿蒙PC-Java-JNI库交叉编译与设备回归-jansi.md`）；B 保留检测值、新增 `harmonyos-aarch64` 资源目录（JNA 型，见 E084）
+
+## 设备运行时（自带供给）
+
+**别探设备上有没有 JDK——一律自带**：app 域只能用自己私有 HNP 里的运行时。宿主侧取 BiSheng JDK 产物（`BiShengJDKInstaller` 仓的 `.hnp` 解包，或预编译 tar）→ 打进私有 HNP → 随执行器 HAP 装机。程序与产物来源表的权威见 `pc-knowledge-base/platform/鸿蒙PC-设备语言运行时探测与供给.md`；确实拿不到产物才按 `built-pending-verification` 降级。
+
+- 验身：`$JAVA_HOME/bin/java -version`；要 `System.load()` 自编 JNI 库时先按 E083 处理签名（系统 JDK 校验 `.codesign` 段），手动编译+加载全范式见 E084
+- 设备跑用例（原库测试命令为 `mvn test` 类时的设备等价改写）：设备无 Maven/Gradle，用 junit-platform-console-standalone 单 jar 复跑——宿主机 `mvn test-compile dependency:copy-dependencies` 备齐 classes/test-classes/依赖 jar → **随 JDK 一起打进私有 HNP** → app 域内 `$JAVA_HOME/bin/java -jar junit-platform-console-standalone.jar -cp 'classes:test-classes:deps/*' --scan-classpath`。用例选集/超时参数继承原库测试命令；计数口径取命名用例级
+- 完成设备回归后在 03-adapt.json 填 `runtime_provisioning` 与 `target_path_covered`（语义见 pc-schemas enum-semantics.md）
+
+## 本机编译路径（鸿蒙PC上直接编）
+
+> ⏳ 扩展口：待补充。预留以下结构骨架。
+
+### 环境准备
+
+设备 JDK 的探测与供给见上节「设备运行时」；maven/gradle 设备侧不可用，构建仍在宿主机做（待补：本机 javac 直编流程）
+
+### 构建命令
+
+（待补）
+
+### 特有坑
+
+（待补）
+
+## 依赖源
+
+已适配 JNI 构件优先走中心制品仓 Maven 库：pom/settings 追加 `<repository>`（多仓声明天然 fallback）。端点权威见 `pc-registry` 的 `references/central-registry.md`（构件清单/groupId 以组织 Web 页为准）。
+
+## 资源引用
+
+- 交叉编译骨干 → `pc-knowledge-base`
+- 设备运行时探测与供给 → `pc-knowledge-base/platform/鸿蒙PC-设备语言运行时探测与供给.md`
+- 报错定位 → `pc-error-atlas` 错误图谱（JNI 签名 E083、手动编译范式 E084）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/references/languages/node.md

@@ -0,0 +1,98 @@
+# Node N-API 扩展适配
+
+适用：Node.js 库含原生扩展（node-pty/better-sqlite3/node-sass 等）。交叉编译骨干见 `pc-knowledge-base`。
+
+包入口、依赖与原生接口分类按 `pc-node-library` 指南；本文只给独立 Node 构建薄层。
+
+## 先定宿主运行时（决定后面一切）
+
+**同一个 `.node`，宿主不同则 ABI 不同、产物不可互换。** 走错这一步，后面每一步都白做。
+
+| 宿主 | 谁装载 | napi 符号 | 走哪篇 |
+|---|---|---|---|
+| `device-node`（缺省） | 设备端 Node（**随私有 HNP 自带**） | 留 UND，宿主 dlopen 时解析 | **本篇** |
+| `electron-oh` | Electron-OH 内置 Node（HAP 内 `libelectron.so`） | 静态链入垫片、**无 UND** | `pc-knowledge-base` 的 `electron/addon-build.md` |
+
+取值写 `01-scan.json` 的 `harmony_adaptation.host_runtime`；不写＝按缺省走本篇。
+它**首先是任务意图**（一个通用 addon 之所以成为「Electron addon」，是因为使用者要把它放进
+Electron），库信号只够当提示。产物与声明是否相符由验收规则 `load-contract-consistent` 机器核对。
+
+## 交叉编译路径（Linux/Mac → 鸿蒙）
+
+### 构建命令
+
+- N-API 扩展：CMake + OHOS toolchain 交叉编译为 `.node`，链接 Node headers
+- 纯 JS 依赖 `npm pack`/官方源；**原生依赖先按 `pc-registry` 获取序查中心仓 nodejs 源**（探测/安装命令的端点权威见 pc-registry 的 central-registry.md）——sharp/sqlite3/better-sqlite3 类已有预编译 ohos 版，命中即免交叉编译
+
+先检查上游构建入口是否支持目标工具链；缺少 OHOS 配置时可在 `build/` 新增 CMake adapter，完整迁移 sources、defines、conditions 与生成步骤。以下仅是 Node-API 的起点，不能直接套给 NAN/V8：
+
+```bash
+cmake -S <staging> -B <build-dir> \
+  -DCMAKE_TOOLCHAIN_FILE="$DEVECO_SDK_HOME/default/openharmony/native/build/cmake/ohos.toolchain.cmake" \
+  -DOHOS_ARCH=arm64-v8a \
+  -DOHOS_STL=c++_shared \
+  -DOHOS_ALLOW_UNDEFINED_SYMBOLS=1 \
+  -DCMAKE_BUILD_TYPE=Release
+cmake --build <build-dir> --parallel
+```
+
+关键点：
+
+- `OHOS_ALLOW_UNDEFINED_SYMBOLS=1`：`napi_*` 符号**不在链接期解析**，留给宿主 node 在 dlopen 时提供。正确产物的 DT_NEEDED 只有 `libc.so`、`libc++_shared.so`，**不含** `libace_napi.z.so`（那是 ArkTS/HAP 模块的依赖，Node 插件不要链）。
+- 产物命名 `<name>.node`：`set_target_properties(... PREFIX "" SUFFIX ".node")`。
+- vendored C++ 依赖（如 leveldb/snappy）编成**静态库并入 .node**，避免设备侧多 so 部署与 RUNPATH 问题。
+- Node headers 明确取目标运行时版本；不自动使用 DevEco 的宿主 Node 或本机 node-gyp 缓存。NAN/V8 还需匹配目标配置、模块 ABI 和工具链。
+- N-API 版本兼容以**设备实测**为准：设备端 `node -p process.versions.napi`（案例：可调试鸿蒙 PC（HongMeng 1.12.0）预装 Node 22.7.0 → napi 9），扩展要求的 `NAPI_VERSION` ≤ 该值即可。
+
+### 扩展后缀
+
+`.node`（Node 原生扩展标准后缀）
+
+### 特有坑
+
+- **vendored LevelDB 漏编 `util/env_posix.cc`**：LevelDB 的 POSIX 环境实现不在核心源列表里。漏编时编译链接都通过，设备 dlopen 才报 `Error relocating ...: leveldb::Env::Default` 缺符号——CMake 源列表须显式加入该文件。同类 vendored 库的「平台实现单独放文件」模式都要检查。
+- **老 node-gyp 项目默认 C++ 标准过旧**：binding.cc 若用 `std::optional` 等 C++17 特性，交叉编译报错，须显式 `set(CMAKE_CXX_STANDARD 17)`。
+- **测试包依赖不完整**：推送设备的测试包必须带全 node_modules **运行时传递依赖**。缺包的症状不直观（`class X extends undefined`、`... is not a constructor`），且重打包重推非常耗时——推送前逐个校验被 `require` 的包存在。
+
+### 设备端验证（自带 Node 运行时）
+
+> **运行时前提**：鸿蒙 PC 上**不能借用**设备上已有的 Node——公共 HNP 不存在，别的 App 私有 HNP 在人家沙箱里，app 域够不到。**一律自带**：宿主侧取 OpenHarmony 版 Node 产物（`DevNode-OH` 仓的 `hnp/arm64-v8a/`）打进私有 HNP、随执行器 HAP 装机，程序见 `pc-knowledge-base/platform/鸿蒙PC-设备语言运行时探测与供给.md`。验身 `node -p process.platform` 应输出 `openharmony`（通用 Linux 版跑不了）；确实拿不到产物才按 `built-pending-verification` 记 blocker。
+
+（历史记录：设备上别的应用的 Node 装在其 mount namespace 内，hdc shell 直连报 `inaccessible or not found`——**鸿蒙 PC 上 nsenter 也用不了**，所以这条路彻底不通。）自带后的跑法：
+
+```bash
+# 均在 hdc shell 内执行
+ps -ef | grep node                    # 找 node 进程 pid
+readlink /proc/<pid>/exe              # 定位 node 真实二进制路径
+nsenter -t <pid> -m -p -- <node路径> /data/local/tmp/<pkg>/run-tests.js
+```
+
+- `nsenter` 的 `--` 分隔符**必带**，否则被跑命令的选项（如 `-e`）会被 nsenter 吞掉报 `Unknown option`。机制详见 platform 笔记（下方资源引用）。
+- 测试聚合注意：TAP 的 plan 行是 `1..N`（按格式解析，别按固定偏移截取）；`--expose-gc` 类用例若跑出 0 断言应标注为无覆盖，而不是计入通过。
+- 此跑法依赖 root/可调试设备；零售机需 ELF 签名与正式部署路径，见 `pc-knowledge-base` 签名章节。
+
+## 本机编译路径（鸿蒙PC上直接编）
+
+> ⏳ 扩展口：待补充。预留以下结构骨架。
+
+### 环境准备
+
+（待补：鸿蒙 PC Node.js 运行时、npm 配置）
+
+### 构建命令
+
+（待补：node-gyp 本机编译、npm 本机构建）
+
+### 特有坑
+
+（待补）
+
+## 资源引用
+
+- 交叉编译骨干 → `pc-knowledge-base`
+- 设备端 mount namespace 与 nsenter 机制 → `pc-knowledge-base/platform/鸿蒙PC-进程视角与mount-namespace.md`
+- 报错定位 → `pc-error-atlas` 错误图谱
+
+## 已验证案例
+
+- classic-level 3.0.0（LevelDB N-API binding，vendored leveldb+snappy）：CMake + OHOS NDK 交叉编译，可调试鸿蒙 PC（HongMeng 1.12.0）设备端 Node 22.7.0 全量上游测试通过、相对原平台无回归。