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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-/347/211/210/346/234/254/350/204/232/346/234/254/350/243/201/345/211/252/345/272/223/347/232/204/345/257/274/345/207/272/351/235/242/345/256/241/350/256/241.md

@@ -0,0 +1,73 @@
+---
+name: 鸿蒙PC-版本脚本裁剪库的导出面审计
+description: 凡构建走版本脚本/符号可见性裁剪的 C/C++ 库，交付前必做导出面四集对账：公共头文件声明的 API（H）必须 ⊆ 产物 .dynsym 导出（E）∪ sysroot libc 委托（L）；已实现（I）却未导出 = 版本脚本漏收实锤。区分 overlay 委托（asprintf/err 族→musl，合法）与裁剪缺陷（sl_delete/B003 reallocf，产物缺陷）。触发词：版本脚本、version script、libbsd.map、symbol visibility、-fvisibility、导出符号、dynsym、declared but unexported、链接失败、undefined reference、dlsym 返回 null、sl_delete、map 漏写、def 文件。
+metadata:
+  type: adaptation
+  source: libbsd 0.12.2 案例（2026-08 外部一致性测试 71 FAIL 实证，鸿蒙 PC aarch64）
+---
+
+# 版本脚本裁剪库的导出面审计
+
+## 为什么需要
+
+上游自带导出面 bug 是真实存在的库类别（libbsd 0.12.2 的 `libbsd.map.in` 漏写
+`sl_delete`——实现 ✓ 头文件声明 ✓ 版本脚本 ✗）。构建系统忠实执行了错误输入，
+产物对消费者就是坏的：`#include <stringlist.h>` 后调 `sl_delete` 链接必失败。
+**上游发行版用同一份 map 构建，对照上游二进制会显示「无差异」照样放行**——
+所以参照集必须是**头文件**（消费者视角的契约），不是上游二进制，也不是测试清单
+（测试面自选时恰好没测 stringlist，四道防线全放行——libbsd 案实证）。
+
+适用信号：构建命令出现 `--version-script=` / `-fvisibility=` / `.def` 文件 /
+CMake `CMAKE_CXX_VISIBILITY_PRESET` / `generate_export_header`——任何
+「显式控制导出面」的机制。openssl、libxml2、icu 等大库全系如此。
+
+## 四集模型与对账规则
+
+| 集 | 来源 | 说明 |
+|---|---|---|
+| H | 公共头文件（source/include 下 .h）的函数声明 | API 契约、消费者视角 |
+| I | build/obj 各 .o 的 symtab 全局定义符号 | 实际实现面（.o 从不 strip，strip 不影响取证） |
+| E | dist 产 .so 的 .dynsym defined GLOBAL/WEAK FUNC | 导出面 |
+| L | sysroot libc.so 的 .dynsym | 委托出口（$DEVECO_SDK_HOME 推导，不写绝对路径） |
+
+**L1（硬信号）**：`H − E − L ≠ ∅` → 声明了、没导出、libc 也不提供——链接必失败。
+**L2（实锤档）**：`(I ∩ H) − E ≠ ∅` → 已实现且已声明却被链接器藏起来——版本脚本
+漏收实锤（sl_delete 正是这一档）。L1 不含 L2 时提示「编译单元被裁或委托待核实」
+（B003：configure typo 让 reallocf 整个不编译，I 里就没有——归这一档的对照样本）。
+
+## 判定程序（拿到告警后怎么走）
+
+1. **逐个查 L**：符号在 sysroot libc 里吗？在 → overlay 委托，合法设计，核实后归档。
+   （libbsd overlay 的 asprintf/vasprintf/err/errx/warn/warnx/verr/vwarn 族全部委托 musl——
+   这是合法设计，不是缺陷。）
+2. **查 I**：`.o` 的 symtab 里有该符号吗？
+   - 有 → 版本脚本/可见性配置漏收。修 map 补符号 → 重链 → 复跑对账。
+   - 无 → 编译单元被裁：查 configure 的 ABI 开关是否误关
+     （B003 对照样本：`abi_reallocf=ues` typo → `LIBBSD_ABI_REALLOCF=0` → reallocf.c 不编）。
+3. **查上游**：上游 master 修了吗？没修 → 补丁回推上游（一行修复接受率高）。
+4. 修复落 `patches/`，走补丁交付链，重跑构建与对账。
+
+## 取证细节
+
+- strip 只删 .symtab 不删 .dynsym——E 集从 .so 直接可读；**I 集必须从 build/obj 的 .o 取**
+  （.so strip 后 symtab 没了）。
+- 手读 ELF 即可（Node Buffer 读 ELF64 header → section 遍历 → .dynsym/.symtab），
+  不依赖 llvm-readelf 在 PATH 上（DevEco 的 diff 坏桩教训：工具可用性不能假设）。
+- sysroot libc 位置：`$DEVECO_SDK_HOME/default/openharmony/native/sysroot/usr/lib/aarch64-linux-ohos/libc.so`。
+- 头文件解析的坑（libbsd 全量验证过）：多行声明拼行时括号计数要**每行全量重数**
+  （跨行累计会让多行声明永不归零）；`#if` 反斜杠续行要先合并再剔除；尾部装饰宏
+  （`__printflike(2,3);`）要剥掉而不是丢整条；头文件里的 `static __inline` 实现体
+  要整段丢弃（be32enc）。
+
+## 与流水线的关系
+
+本条知识被 `acceptance-checks.ts` 的 `export-surface-reconciled`（R15）规则引用：
+03-adapt.json 写入 built-* 时，PostWrite Hook 自动对工作区跑 L1/L2 对账，命中即
+告警并指回本文档。规则是事后安全网；**构建时**主动审计（识别到版本脚本信号就预检
+导出面）比等 hook 响更省一轮返工——scan/build 阶段可用
+`ohpt-agent knowledge -s 版本脚本` 检索到本文档。
+
+## 相关条目
+
+- [鸿蒙PC-C++库交叉编译要点.md](鸿蒙PC-C++库交叉编译要点.md) — strip 收益与边车（§10）、公共头传递依赖（§7）
+- [鸿蒙PC-musl与BSD-glibc语义分歧表.md](../platform/鸿蒙PC-musl与BSD-glibc语义分歧表.md) — 同一外部一致性测试的另一半产出：musl 行为差异（本表管导出面，那张管运行行为）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-/347/272/257JS/345/272/223/351/203/250/347/275/262/345/210/260HNP-node.md

@@ -0,0 +1,35 @@
+---
+name: 鸿蒙PC-纯JS库部署到HNP-node
+description: 纯 JavaScript npm 库（无 native）在鸿蒙PC 上跑通的最简套路，以 bcrypt-pbkdf 为例
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+> **前置（鸿蒙 PC 商用机）**：下文的 `/data/service/hnp/…`、`/data/app/el1/…` 路径与 `nsenter` **对 hdc shell（uid 2000）都够不到**——公共 HNP 目录不存在、应用沙箱 Permission denied、nsenter 被拒（2026-09-01 实测）。本篇适用于这些路径可及的环境；商用机上的等价做法是**把运行时与程序打进私有 HNP 随 HAP 装机**，见 [[鸿蒙PC-app域执行二进制与JIT限制]]、[[鸿蒙PC-hdc能力边界与取证通道]]。
+
+纯 JS 的 npm 库（无 `binding.gyp`/`*.node`）适配鸿蒙PC **零交叉编译**，只要设备有 Node 运行时。以 bcrypt-pbkdf@1.0.2（OpenBSD bcrypt_pbkdf 的 JS 移植，依赖 tweetnacl）为例，**源码改动 0 处**，真机一次通过。
+
+## 设备 Node 运行时
+
+设备装了社区 **DevNode HNP**（bundle `com.develop.opensource.ohdpc.devnode`），提供 **node v24.13.0**：
+- 绝对路径 `/data/app/el1/bundle/<userId>/hnppublic/bin/node`，**hdc root 可直接 exec**（和 [[鸿蒙PC-设备Python运行时]] 同一 hnppublic 目录）。
+- 注意旧的 `/data/local/tmp/usr/local/bin/node` exec 报 `Operation not permitted`（未签名/标签不对），别用它，用 HNP 那个。
+- 交互式 HiShell 的 PATH 含 HNP bin，直接敲 `node` 即可；自动化一律用绝对路径。
+
+## 关键平台事实
+
+- 设备 node：**`process.platform === 'openharmony'`**（不是 `linux`！）、`process.arch === 'arm64'`。
+  → 任何按 `process.platform === 'linux'` 分支的库都要补 `openharmony` 分支。本库无分支，所以零改动。
+
+## 套路（4 步）
+
+1. `cp` 上游源码到 `src/`，`npm install --omit=dev` 拉运行期依赖。
+2. **守卫**：`find node_modules -name '*.node' -o -name binding.gyp`——若命中说明依赖含 native，得转走 N-API 交叉编译流程（见 [[鸿蒙PC-C++库交叉编译要点]] / node-pty 案例），不再是"纯 JS"。
+3. 组装自包含 bundle：`index.js` + `node_modules/` + 一个 `require('./index.js')` 的冒烟脚本（把 KAT 期望值内联）。
+4. `hdc file send` → 用 HNP node 跑冒烟脚本。
+
+## 验证设计：跨机一致性 KAT
+
+最稳的端到端验证是**确定性一致性**：同一输入在 Mac node 和设备 node 各算一遍，hex 输出必须逐字节相等（证明在设备上正确执行，且无平台相关偏差）。比依赖记忆里的"标准测试向量"更可靠——基准由 Mac 现算。
+

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-/351/200/232/347/224/250/350/247/206/347/252/227/346/241/245ohos_window_bridge.md

@@ -0,0 +1,57 @@
+---
+name: 鸿蒙PC-通用视窗桥ohos_window_bridge
+description: OWB——把 XComponent→OHNativeWindow 缝形式化的可复用公共层(纯C)，GPU(EGL/Vulkan)+CPU-blit 双上屏 + 库中立事件队列 + 帧扇出 + 双向窗口控制 + 线程入口壳(owb_ohos_app.h，存量桌面 main() 零改动上鸿蒙，Qt QPA 同款)，其他视窗/图形库(SDL/GTK/Qt-raster/ImGui/bgfx)照抄 Layer3 即可
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+`ohos_window_bridge`(OWB) 是把"任意自绘像素的视窗/图形库搬到鸿蒙 PC"这件事**抽出来一次写好**的公共层。2026-07-01 随 GLFW 鸿蒙化沉淀，第一个消费者是 GLFW（[[鸿蒙PC-GLFW视窗后端-EGL-XComponent]]）。核心洞见：鸿蒙上"搬一个渲染像素的库"平台相关的**只有一道缝**，其余库逻辑不动——把缝写成库，新库只写薄薄一层 Layer3。
+
+## 分层（新库只碰 Layer3）
+- **L0 ArkTS**：`XComponent({type:SURFACE, libraryname:'<lib>'})` 9 行，系统按 libraryname 自动加载 `lib<lib>.so` 的 napi 模块。ETS 侧不 import .so、不要 @types 声明。
+- **L1 NAPI 胶水**（可选/可复用）：napi 模块 Init 里 `OH_NativeXComponent_RegisterCallback`，把 surface created/changed/destroyed + touch/mouse/key + `RegisterOnFrameCallback` 转成 `OWB_*`。
+- **L2 OWB 核心**（纯 C，libc+pthread；CPU 路径另需 libnative_window）：surface 注册表 + 库中立事件队列(mutex+condvar) + 帧扇出 + 反向通道 + **双上屏 helper**。
+- **L3 按库后端**（薄，库相关）：把 `OWB_Event` 翻成库自己的事件、选 GPU/CPU 上屏。GLFW=填 `_GLFWplatform` vtable；SDL=`SDL_VideoDevice` 驱动；GTK/Qt-raster=软件后端接 CPU helper。
+
+## 双上屏路径（关键设计——一个缝覆盖 GPU 库和 CPU 工具包）
+- **GPU**：`void* OWB_GetNativeWindow(surfaceId)` 拿 `OHNativeWindow*` → 交给 `eglCreateWindowSurface` / `vkCreateSurfaceOHOS`。适配 GLFW/SDL/bgfx。
+- **CPU-blit**：`OWB_AcquireFrame(surfaceId,&fb)` 内部 `RequestBuffer→GetBufferHandle→mmap`，**`fb.stride` 已取 BufferHandle 真值**（杜绝 `stride!=width*4` 花屏这唯一易错点）；写完 `OWB_CommitFrame`(FlushBuffer+munmap) 或 `OWB_AbortFrame`。适配 GTK gdk-ohos / Qt raster QPA / ImGui 软件后端。
+
+## 实现要点（bridge.c）
+- 头文件**零 NDK 依赖**：`nativeWindow` 一律 `void*`（避开 GLFW C99 下 `OHNativeWindow` typedef 重定义；消费者自己 cast）。
+- CPU 路径用 `#ifdef OWB_HAVE_NATIVE_WINDOW` 包起来：OHOS 构建定义它、链 libnative_window；**不定义就是纯 libc+pthread 核心**，可在 Mac host 单测事件队列。
+- musl 严格 c99：`bridge.c` 顶部 `#define _POSIX_C_SOURCE 200809L`（暴露 clock_gettime/timedwait）。
+- 链接 `.so` 加 `-Wl,-z,max-page-size=0x1000`（4KB 对齐，见 [[鸿蒙PC-64KB页对齐so崩溃]]）。
+- 事件 mods 位掩码故意定义成与 GLFW `GLFW_MOD_*` 同值，直传省一次翻译。
+
+## 构建
+`build/build.sh` 用 SDK 自带 `native/build/cmake/ohos.toolchain.cmake` + `-DOHOS_ARCH=arm64-v8a` 出 `.a`+`.so`。静态 `.a` 不链 native_window（消费者最终 `.so` 再链）。
+
+## 复用配方（其他库开箱）——见 docs/PORTING_KIT.md
+- SDL2/3(GPU)：`CreateWindow`=`OWB_Acquire`+存 window、`GL_CreateContext`=EGL、`PumpEvents`=`OWB_PollEvent`→`SDL_Send*`。
+- GTK gdk-ohos / Qt raster(CPU)：软件后端输出接 `OWB_AcquireFrame/CommitFrame`（注意 cairo ARGB32 预乘 BGRA ↔ OHOS RGBA8888 通道换序），事件接 `OWB_PollEvent`。
+
+## 双向窗口控制（2026-07-01 补，真机验证）
+反向通道从「只 close」升级成「窗口控制」。分两层：
+- **Tier A 纯 native**（`OWB_LockCursor/UnlockCursor/GetWindowRect/SetWindowTouchable` + `OWB_SetWindowId`）：包 `OH_WindowManager_*`（`libnative_window_manager.so`），做光标锁定（GLFW disabled/原始鼠标）、真实窗口 pos、passthrough。
+- **Tier B 经反向桥**（`OWB_RequestWindowOp(sid, OWB_WOP_SIZE/POS/ICONIFY/RESTORE/MAXIMIZE/FULLSCREEN/TITLE/LIMITS, ...)`）：几何控制**无 native 路径**（见 [[鸿蒙PC-窗口几何控制无native只ArkTS]]），填一个 `OWB_EVENT_REQ_WINDOW_OP` 事件同步调反向回调 → 宿主 NAPI 用 `napi_threadsafe_function` marshal 到 JS 线程 → 直调 ArkTS `@ohos.window` 的 `resize/moveWindowTo/minimize/maximize/recover/setWindowLayoutFullScreen`。ArkTS 经 `XComponentController.getXComponentContext()` 把 mainWindow 对象 + windowId 传下来（不 import .so）。
+- **踩过的坑**：`OWB_Initialize()` 原来会清 `g_reverseCb` —— 但宿主 NAPI 模块 Init 阶段（早于 OnSurfaceCreated 里的 OWB_Initialize）就注册了反向回调，被清掉 → 窗口控制静默失效。**修：Initialize 不碰 reverse cb**（它是库级注册，非 surface 状态）。这类「生命周期钩子清了不该清的全局」是反向桥最隐蔽的 bug。
+
+## 线程入口壳 owb_ohos_app.h（2026-07-02 补，真机验证）——存量桌面 main() 零改动上鸿蒙
+让存量桌面 GLFW/SDL 应用**原样的 `int main(){ …; while(!glfwWindowShouldClose(w)){ render(); glfwPollEvents(); } }`** 一行不改跑上鸿蒙。库中立，放 `napi/owb_ohos_app.h`（不含任何 glfw* 符号，SDL/bgfx 复用同一个壳）。
+- **机制**：鸿蒙无 main()、渲染在 JS/UI 线程且不能被应用阻塞主循环占死。壳 = 一行宏 `OWB_OHOS_THREAD_APP("<libraryname>")`，展开成 napi 模块 Init：`OWB_NAPI_HookXComponent`（JS 线程收 surface+输入）+ `OWB_NAPI_InstallWindowControl`（窗口控制桥）+ `pthread_create` 起 worker 线程跑应用 `main()`。**Qt 鸿蒙 QPA 实证同款**（源码：`qohmain.cpp:181 pthread_create(startMainMethod)` 跑 `startQtApplication`；JS→Qt 用 `runOnQtMainThread`、Qt→@ohos.window 用 `safeExec` marshal）。
+- **改名 main（SDL 同款）**：头里 `#define main owb_app_main` + 声明 `int owb_app_main(int,char**)`，壳的 worker 用合成 argv 调它。约束：应用 main 须 `int main(int,char**)` 签名（`int main(void)` 改下签名即可）。C++ 不能直接调 main，故用 rename。
+- **跨线程两个方向 OWB 已兜底**（开发者不碰线程）：① 输入 JS 线程 `OWB_PostEvent` → worker `OWB_PollEvent`，靠事件队列 mutex+condvar；② 窗口控制 worker `OWB_RequestWindowOp` → `napi_threadsafe_function` → JS 线程调 `@ohos.window`（就是上面 Tier B 的 TSFN，天生跨线程安全）。
+- **新增 `OWB_WaitForSurface(timeoutSec)`**（bridge.c，复用 `g_cond`）：worker 线程 `glfwCreateWindow`→`bindSurface` 首轮找不到 surface 就阻塞等 JS 线程 `OnSurfaceCreated`→`OWB_RegisterSurface`（内部 `OWB_PostEvent` broadcast `g_cond`）。检查+等待在同一 `g_lock` 下原子，无 missed-wakeup。GLFW 侧 bindSurface 改成 2 轮：先扫、没有则 `OWB_WaitForSurface(10.0)` 再扫。
+- **节流**：`glfwSwapInterval(1)` 让 `eglSwapBuffers` 阻塞到 vblank 驱动 worker 循环，**不需要 XComponent OnFrame**。真机实测 CPU 状态 `S`（非忙等）。
+- **生命周期**：surface destroy → `OWB_UnregisterSurface` → 投 `SURFACE_DESTROYED` → worker `glfwPollEvents` → `glfwWindowShouldClose` 变真 → 循环退出 → main 返回 → worker 结束。force-stop 无 cppcrash。
+- **真机验证**（HAD-W32）：worker 线程建 EGL/GLES3 + 用 JS 线程抛来的 OHNativeWindow → 旋转三角形；tap→`glfwSetWindowSize(900,600)`、tap→`glfwMaximizeWindow` 均生效（worker→JS 跨线程窗口控制）。demo 应用侧 = 纯桌面 `int main()`，不 include 任何 OWB/XComponent 头。
+- **对比"回调式"**：无阻塞主循环的新应用可改走 `OWB_RegisterFrameCallback`/OnFrame（渲染拆进帧回调）；线程壳是给"存量 main() 零改动"用的。
+- **解释器变体（2026-07-02）**：`napi/owb_ohos_python_app.h` —— worker 的 main() 换成嵌入 CPython 执行脚本（`OWB_OHOS_PYTHON_APP("模块名","app/main.py")` 一行）。给**语言绑定库**（pyGLFW 等 ctypes/FFI）用：脚本发出的就是 worker 线程上的 C 调用，OWB 链路零改动。配套：原生库须出**共享库**并**动态链 OWB.so**（进程内同一 OWB 实例——静态嵌两份状态直接坏，CMake 加了 `OHOS_WINDOW_BRIDGE_LIBRARY`）。详见 [[鸿蒙PC-pyGLFW-Python绑定库迁移]]。
+
+## 相关
+- [[鸿蒙PC-窗口几何控制无native只ArkTS]] —— 为什么 Tier B 必须走 ArkTS（NDK 无几何 + Qt 实证）。
+- [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]] —— OWB 的 CPU 路径来源（nmap spike 真机验证过的原始接法）。
+- [[鸿蒙PC-GLFW视窗后端-EGL-XComponent]] —— 第一个消费者(GPU/EGL 路径)。
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— 库链进 app 自己的 .so 进程内渲染，绕开 spawn/JIT 三关，app 域干净。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/electron/addon-build.md

@@ -0,0 +1,249 @@
+# Electron addon（原生 `.node`）鸿蒙适配
+
+适用：一个 npm 原生模块（`binding.gyp`/`node-gyp`/`node-addon-api`，如 node-sqlite3、better-sqlite3）
+要被 **Electron-OH 内置的 Node** 加载。交叉编译骨干见 `pc-knowledge-base`。
+
+> **先确认宿主再动手。** 同一个 `.node`，给 Electron-OH 和给设备端 Node 的产物 **ABI 互不兼容、
+> 不可互换**。宿主是设备 Node（自带私有 HNP）走 `pc-delivery-forms/references/languages/node.md`，
+> 别用本篇。判定与取值见 `01-scan.json` 的 `harmony_adaptation.host_runtime`。
+
+> **版本适用范围**：历史实测不保证其他发行版兼容。按目标 Electron-OH 的 headers、shim 和
+> libelectron.so 核对实际接口、符号与 libuv ABI；尤其不能仅凭 N-API 稳定性推断 libuv 结构体兼容。
+
+## 为什么要垫片
+
+Electron-OH 的 `napi_*` 实现在 HAP 内的 `libelectron.so` 里，addon 被 dlopen 时**解析不到**它。
+方案是随包 vendored 的 `templates/build-tools/electron-napi-library/`（**官方工件**：出处为 Electron 鸿蒙化
+指导文档随附的 `electron-loading-addon-guide` demo，MIT）：当前 `libshim.a` 提供 161 个全局函数定义
+（145 个 `napi_*`、7 个 `node_api_*`、9 个 `uv_*`），不覆盖全部 libuv API，运行时 `dlopen("libelectron.so")` + `dlsym` 转发过去（唯二未定义符号是
+`dlopen`/`dlsym`）。详见 `templates/build-tools/electron-napi-library/README.md`。
+
+工具链与垫片位置一律问 `ohpt-agent env`（`capabilities.electron_toolchain.targets`），
+**不要写死路径**；`$ELECTRON_NAPI_LIBRARY` / `$ELECTRON_OHOS_LLVM_BIN` / `$OHPT_ELECTRON_SRC` /
+`$OHPT_ELECTRON_OHOS_HAP` 可覆盖。
+
+## 为什么不需要 Electron 源码树的 llvm（实测）
+
+厂商文档说「addon 编译需使用相同的编译工具链」——**那句话是对裸 V8 路线说的**。N-API 这条路
+**没有 C++ 跨界面**，用 DevEco NDK 编不是「侥幸过了」，是本来就不该出问题。
+
+对真机跑通的 `node_sqlite3.node` 实测：
+
+| 观测 | 值 |
+|---|---|
+| 未定义符号总数 | 126 |
+| 其中 C++ mangled | 19，**全是 `_ZNSt…`/`_ZTI…`/`_ZTV…`，即 libc++ 标准库** |
+| 向 V8 / node / electron 要的 C++ 符号 | **0** |
+| 那 19 个 vs Electron 自带 `libc++_shared.so`（2357 导出） | **缺口 0** |
+| ABI 内联命名空间 | 两侧同为 `std::__n1`（Electron 的 libc++ 里 `__1` 出现 0 次） |
+
+道理：N-API 本就是 C ABI，垫片又把它显式化成 `dlopen`+`dlsym` 的函数指针；node-addon-api 是
+header-only，C++ 全编进 addon 内部、不跨界。唯一的 C++ ABI 面是 addon ↔ `libc++_shared.so`，
+而那个 `.so` 就在同一个 HAP 的 `libs/` 里、由 Electron 工程自带。
+
+这条不变量**已经是机器执法的**（装载契约的 `forbidUndef` 覆盖 `_ZN2v8`/`_ZN4node`），
+`ohpt-agent check -w <ws> --stage 3` 会替你查。要手工复核用这两条：
+
+```bash
+NM=$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin/llvm-nm
+# ① 与宿主之间不得有 C++ 界面 —— 应为 0
+$NM -D -u <x>.node | awk '{print $2}' | grep -cE '_ZN2v8|_ZN4node'
+# ② C++ 未定义符号应全是 libc++，且被 HAP 自带的 libc++_shared.so 覆盖 —— 应为空
+comm -23 <($NM -D -u <x>.node | awk '{print $2}' | grep '^_Z' | sort -u) \
+         <($NM -D --defined-only <hap>/libs/arm64-v8a/libc++_shared.so | awk '{print $3}' | sort -u)
+```
+
+## 构建（首选：CMake；node-gyp 为厂商原版备选）
+
+厂商指导文档走 node-gyp + `CC/CXX/LD/AR…` 环境变量，那是在 Ubuntu 上验证的。**macOS 宿主上
+gyp 会生成 `-bundle`/`-mmacosx-version-min` 一类平台专属链接参数**，换掉 `CC` 后大概率不通；
+本项目既有路子（手写 `CMakeLists.txt`，`node.md` 与 classic-level 实证）天然规避，且 include
+顺序由我们控制。**两条路的产物由同一条验收规则判定**，选哪条都行——配方可以有多条，判据只有一条。
+
+```cmake
+# 三个路径全部取自 `ohpt-agent env -w <ws> --json` 的 capabilities.electron_toolchain：
+#   napi_include_dir / napi_shim（结构化字段，直接用，别去解析 targets 里的中文）
+cmake_minimum_required(VERSION 3.16)
+project(<name> CXX)
+set(CMAKE_CXX_STANDARD 17)                  # 编 .node 的最低要求
+
+add_library(<name> SHARED ${SOURCES})       # SOURCES 从 binding.gyp 的 sources 迁
+set_target_properties(<name> PROPERTIES PREFIX "" SUFFIX ".node")
+target_compile_definitions(<name> PRIVATE
+    HIDE_NAPI_AND_UV
+    NAPI_VERSION=8
+    NAPI_DISABLE_CPP_EXCEPTIONS=1           # 用 node-addon-api 的库必须给（上游 binding.gyp 也给）
+    __MUSL__=1)
+target_include_directories(<name> PRIVATE
+    "${ELECTRON_NAPI_INCLUDE_DIR}"          # = capabilities.electron_toolchain.napi_include_dir
+    "${NODE_ADDON_API_DIR}")                # node-addon-api 的头（见下）
+target_link_libraries(<name> PRIVATE "${ELECTRON_NAPI_SHIM}")   # = …napi_shim，**必须排在目标文件之后**
+```
+
+传参：`cmake -S <staging> -B <build> -DELECTRON_NAPI_INCLUDE_DIR=… -DELECTRON_NAPI_SHIM=… -DNODE_ADDON_API_DIR=…`
+
+**node-addon-api 从哪来**：它是 header-only 的 npm 包（不是随包资产）。取头文件用
+`npm pack node-addon-api@<上游 package.json 要求的版本>` 解开即可，**不必 `npm install` 整棵依赖树**，
+也不需要联网装 node-gyp。include 目录是解开后的包根（`napi.h` 在那一层）。
+
+要点：
+
+- **`libshim.a` 必须真进链接行**，且排在目标文件**之后**（归档语义）。没有 hidden 引用或严格链接检查时，
+  漏链可能让 `napi_*` 留在 UNDEF，直到 dlopen 才失败。
+  验收规则 `load-contract-consistent` 抓的就是它——跑 `ohpt-agent check -w <ws> --stage 3` 自查。
+- 仅使用 Node-API C 头时不需要 uv include；直接调用 libuv 或依赖引用 uv.h 的 addon，必须提供
+  与目标运行时匹配的 uv 头目录，并核对下节的 shim 覆盖。
+- **不要链 `libace_napi.z.so`**（那是 ArkTS/HAP 模块的 NAPI），也**不要**把 `libelectron.so`
+  写进 `DT_NEEDED`（垫片自己在运行时 dlopen 它；HAP 命名空间里没有那条搜索路径）。
+- **`HIDE_NAPI_AND_UV` 一定要加，但它的作用不是文档说的那个**（实测）：垫片里 161 个符号本就是
+  `STV_HIDDEN`，所以最终 `.dynsym` 定不定义这个宏都一样。它真正的价值是**让漏链变成链接期错误**——
+  定义了它，`napi_*` 的引用是 hidden，漏链 `libshim.a` 时 `ld.lld` 直接报
+  `undefined hidden symbol: napi_*`，当场失败；**不定义它才会静默**（引用是 default 可见，
+  共享库允许未定义符号 → 编得过、装得上、dlopen 才死）。所以：加宏 = 快速失败，
+  验收规则 `load-contract-consistent` 兜的是「宏也没加」的那条路。
+- vendored 的 C/C++ 依赖编成**静态库并入 `.node`**，避免设备侧多 so 部署与 RUNPATH 问题。
+  这类依赖的编译宏要**逐条照抄上游**（node-sqlite3 的在 `deps/sqlite3.gyp`：`SQLITE_ENABLE_FTS5`
+  等 9 条）——漏了照样编得出、增删改查也全绿，只是功能残缺；用一条真正用到该特性的用例去证（FTS5）。
+- 上游若用 `node` 脚本解压 vendored 压缩包（node-sqlite3 的 `deps/extract.js` 依赖 npm 的 `tar` 包），
+  **直接用系统 `tar xzf` 即可**，不必为这一步装整棵依赖树。
+
+## libuv 补充转发
+
+直接调用 libuv 的 addon（如 ffi 的异步调用和线程回调）可能报 `undefined hidden symbol: uv_*`。
+这表示当前链接输入缺少相应 hidden 定义；宿主导出了同名函数也不能直接满足这种引用。
+不要删 HIDE_NAPI_AND_UV、放开未定义符号或改链 ArkTS NAPI 来绕过。
+
+当前 vendored shim 的 uv 覆盖为：`uv_close`、`uv_mutex_init`、`uv_mutex_init_recursive`、
+`uv_mutex_destroy`、`uv_mutex_lock`、`uv_mutex_trylock`、`uv_mutex_unlock`、`uv_async_init`、`uv_async_send`。
+`napi_get_uv_event_loop` 属于 napi 接口，不计入 uv 数量。覆盖须按实际归档复核，不能把这个清单当作所有发行版的保证。
+
+```bash
+# 静态归档读取普通符号表；-D 仅用于共享库动态符号表
+llvm-nm --defined-only --extern-only <实际libshim.a>
+llvm-nm --undefined-only <addon目标文件.o>
+llvm-nm -D --defined-only <目标libelectron.so>
+```
+
+结合链接诊断与实际目标文件，计算“addon 所需 uv 符号 − 当前链接输入提供的符号”，再逐一核对宿主导出。
+源码搜索只提供候选，不能替代编译后符号证据。宿主也缺失的接口不能用转发解决；有导出仍需验证签名、结构体布局和运行语义。
+
+[补充 shim 示例](examples/uv-supplement/uv_supplement_shim.c) 演示 ffi 案例的十个缺失函数，
+配套 [头文件](examples/uv-supplement/uv_supplement_shim.h) 提供初始化入口。
+这是本插件维护的源码示例，不是厂商归档的一部分，也不是任意 addon 的固定配方：
+根据实际缺口调整函数表和包装函数，已由其他链接输入定义的函数必须移除以避免重复定义。
+用目标 uv.h 编译，不链接第二份 libuv 来接管宿主 loop/handle。
+
+- 示例用 pthread_once 一次性解析函数表，缓存失败原因；句柄保持到进程结束，不在回调存活时 dlclose。
+- 在 addon 初始化且尚未创建异步句柄/任务前调用 `ohpt_uv_shim_init()`；非 NULL 时用 Node-API 抛出该错误并停止初始化。初始化失败不能继续创建回调。无入口接线时，包装函数会输出错误并 abort 以防静默损坏；这是最后防线，不替代初始化报错。
+- 示例只负责忠实转发。调用方仍必须检查 uv_queue_work/uv_cond_init 等真实返回码，失败时按所有权释放任务并向 JS 报错；不伪造成功或同步执行回调。诊断与用例复用 [原生运行诊断](../../../pc-node-library/references/native-runtime.md#async-work)。
+- 主线实现修改由 03 完成。远程专用 shim 与头文件放入 `.ohos-adaptation-pc/remote-build/inputs/`，不得由准备 agent 写 source/src；若缺初始化接线或调用方错误处理，记录候选补丁交回 03。
+
+03 可在使用 Node-API C 的模块初始化函数开头接入（node-addon-api 按其异常配置等价处理）：
+
+```c
+#include "uv_supplement_shim.h"
+/* 位于已有 napi_value Init(napi_env env, napi_value exports) 内，创建资源之前 */
+const char *shim_error = ohpt_uv_shim_init();
+if (shim_error != NULL) {
+    napi_throw_error(env, "ERR_ELECTRON_UV_SHIM", shim_error);
+    return NULL;
+}
+```
+
+在远程 inputs/CMakeLists.txt 中按实际目标接入：
+
+```cmake
+target_sources(ffi_bindings PRIVATE "${CMAKE_CURRENT_LIST_DIR}/uv_supplement_shim.c")
+target_include_directories(ffi_bindings PRIVATE "${ELECTRON_UV_INCLUDE}")
+target_compile_definitions(ffi_bindings PRIVATE HIDE_NAPI_AND_UV)
+find_package(Threads REQUIRED)
+target_link_libraries(ffi_bindings PRIVATE "${ELECTRON_NAPI_SHIM}" ${CMAKE_DL_LIBS} Threads::Threads)
+```
+
+把 .c/.h 都纳入 recipe.inputs；已有源码若调用初始化入口，还需将头文件所在目录加入该目标 include 路径。
+最后检查 .node 无未定义 napi_/node_api_/uv_，并在目标 Electron 验证加载、同步调用、连续/并发异步任务和真实跨线程回调。
+主机模拟测试和远程 ELF 验收都不能替代设备验证。
+
+### node-gyp 路径（厂商原版）
+
+```bash
+npm install --build-from-source --runtime=electron --target=<Electron 版本> \
+  --dist-url=https://electronjs.org/headers
+```
+
+`package.json` 加 `"binary": { "napi_versions": [8] }`；`binding.gyp` 在**每个 target**（含
+`conditions` 内的）加 `include_dirs` 与 `libraries`、`defines` 加 `HIDE_NAPI_AND_UV`。
+
+> ⚠️ **`--target` 填 Electron 版本，不是 `node --version`。** 厂商文档那句「需要根据自己安装的
+> nodejs 版本填写」与同一行的 `--dist-url=electronjs.org/headers` 自相矛盾（`--runtime=electron`
+> 时 `--target` 就是 Electron 版本），照抄会去拉一个不存在的 release 的头文件。
+>
+> ⚠️ `node-pre-gyp`/`prebuild` 会**重写 `binding.gyp`**，改动要在它之后重新施加。
+
+## JS 侧改造
+
+`.node` 在 HAP 沙箱里必须**按绝对路径 require**——`bindings` / `node-pre-gyp` /
+`prebuild-install` / `node-gyp-build` 的解析全部失效。逐个揪出来换掉。
+
+路径**不要写死一条**：厂商文档给的是 `/data/storage/el1/bundle/libs/arm64/`，而模板
+原 hap-project 模板的 `app-shell/main.js`（已随模板更替移除） 的 `findLibsDir()` 实际探四个候选且首选是
+`/data/storage/el1/bundle/electron/libs/arm64`（DevEco 打包会把 `arm64-v8a` 改名成 `arm64`）。
+照模板的探测写，命中哪个用哪个。
+
+## 落位与载体
+
+`ohpt-agent state -w <ws> --json` 的 `verify_carriers` 会给出 `supply: "host-project"` ——
+**载体不是 `ohpt-agent scaffold` 生成的**，而是既有的 Electron-OH `ohos_hap` 工程（`libelectron.so`
+151MB，不可能进包，须自备并由 `$OHPT_ELECTRON_OHOS_HAP` 指出）。也**没有 CLI 载体**：链了垫片的
+`.node` 需要活的 `libelectron.so`，私有 HNP 执行器里没有 Electron 进程——那一半是物理上不可能，
+不是省略。
+
+| 放什么 | 放哪 |
+|---|---|
+| `<name>.node` | `<ohos_hap>/electron/libs/arm64-v8a/` |
+| 包的 `lib/` + `package.json`（**不含二进制**） | `<ohos_hap>/web_engine/src/main/resources/resfile/resources/app/node_modules/<pkg>/` |
+| 冒烟载荷（`main.js`/`index.html`/`renderer.js`） | 同上 `resources/app/` |
+
+**bundleName 必须逐工作区派生**（如 `com.ohpt.<lib>.electron`），不要沿用 Electron 工程自带的
+固定值——固定 bundle 会让 `install -r` 整包互相顶掉、`force-stop` 杀到对方、抓到对方的日志
+（同 `scaffold` 的 `deriveBundle` 记录过的「张冠李戴」）。`ohpt-agent sign-demo` 用 SDK 自带
+OpenHarmony 材料签名，**任意 bundleName 皆可**，不必改签名 profile。
+
+构建装机：`hvigorw --daemon assembleHap` → `ohpt-agent sign-demo -w <ws> --install`。
+
+## 取证（已实测定论）
+
+**Electron 主进程的 `console.log` 不进 hilog。** 实测：同一 pid 下 `chromium:` 与 `[WebEngine]:`
+两个 tag 的日志正常流出（通道是通的），而 `console.log` 一行都不出现。所以**别把 hilog 当 addon 的
+主证据通道**——「日志为空」在这里不是适配失败，是通道本就不承载它。
+
+可用的通道，按性价比：
+
+1. **沙箱结果文件（推荐）**——载荷把 `OHPTCASE result=… id=… detail=…` 同时写进
+   `app.getPath('userData')`。调试签名的 HAP 其沙箱在设备上可读：
+   `/mnt/debugtmp/100/debug_hap/<bundle>/data/storage/el2/base/files/`，`hdc shell cat` 直接取，
+   `hdc file recv` 可把产物（如生成的 .db）拉回宿主做独立核验。
+2. **渲染进程显示**——载荷读回结果文件渲染到窗口，`ohpt-agent device shot -w <ws> --out <路径>`
+   截屏存档，人工可核。
+3. `--inspect=9229` + `hdc fport tcp:9229 tcp:9229` 接 DevTools（厂商文档的判据），最重。
+
+> `ohpt-agent device files --bundle <b>` 目前探不到 Electron HAP 的 files 目录（它按另一套路径规律
+> 推 userId 沙箱），先用上面第 1 条的 `/mnt/debugtmp` 路径直取。
+
+## 已验证案例
+
+**node-sqlite3 5.1.7**（commit `ba4ba07f`）→ 鸿蒙 PC 真机跑通，2026-09-09。
+
+| | |
+|---|---|
+| 设备 | HAD-W32 / OpenHarmony-6.1.1.135 / aarch64 / 2in1（商用机，调试签名装机） |
+| 宿主 | Electron-OH **25.3.2**（`libelectron.so` 151MB） |
+| 工具链 | **DevEco NDK 的 `OHOS clang 15.0.4`**（本机无 Electron 源码树；与垫片的编译器同版本，仅 llvm 提交不同） |
+| 构建 | CMake（非 node-gyp）：SQLite 3.44.2 amalgamation 编静态库 + 4 个 `.cc` + 链 `libshim.a`，**一次编过** |
+| 源码改动 | **只有 1 处**——`lib/sqlite3-binding.js` 改成按绝对沙箱路径 require（四候选探测）。`napi_versions` 与 `binding.gyp` 都不用改（CMake 路线直接给 `-DNAPI_VERSION=8`） |
+| 产物 | `node_sqlite3.node` 2.2MB，`napi_*` UND=0，`DT_NEEDED=[libc++_shared.so, libc.so]` |
+| 用例 | 5/5 通过：加载 / 内存库 CRUD（10 行）/ **落盘库**（沙箱 8192B，拉回宿主经 `file(1)` 独立确认为 SQLite 3.44.2）/ 事务回滚 / **FTS5 全文检索** |
+
+未覆盖：上游 mocha 套件（本轮只验链路，未建阶段 2 必跑名册）。
+四个 `installDirs` 候选里究竟命中哪一条**未观测到**——`el1/bundle` 不经 `/mnt/debugtmp` 暴露；
+探测本身证明有效（加载用例通过）。下次可让加载器把命中路径打进 detail 一并留证。