可将 ZCode Electron 桌面应用移植到 HarmonyOS 2in1 设备，实现跨平台运行。项目包含 ArkTS 桥接层、Electron 模块适配、构建插件及原生 SQLite NAPI 扩展，解决多方面运行限制。【此简介由AI生成】

Files	Last commit	Last update
AppScope	chore: versionCode 1000003（强制 HNP 重解包，确保 agent bundle 带 spawn 看门狗注入）	11 days ago
account_quick_login	feat(engine): 换装 OHOS Electron 40.1（Chromium 144 / Node 24）+ JIT/主题/Write 修复 v40 迁移（本机实测：main/Renderer/NetworkService/NodeService×3 正常、UI 与 agent RPC 通过）： - web_engine 以 v40 vendor 树为基座重新落地我方适配（启动参数类型、setWindowRectAutoSave、沉浸式窗口、windowStatusDidChange、状态栏补偿、权限表裁剪、toolchain 自愈、 updateAvoidAreaStatus 无参、LogUtil 落盘、CUA/USB 桥接、前进深链接等），新增 HideKeeper/Continue/PowerMonitor 等 v40 适配器，删除 v40 已移除的 PasteBoard/PopupWindow/Screenshot/MessageBox/CommandLine 等死文件 - WebChildProcess 改用 runArkProcess(entryParams, fds, fdsId)，与 v40 libadapter 同源； module.json5 增加 electron_exec_path_ohos 元数据，启动器以 libs/arm64/electron 落盘 - 入口模块迁 v40（HideKeeperAbility/TaskManagerAbility、account_quick_login HAR） - Node 24 内建 sqlite/glob/node:sea 落地，删除 sqlite-adapter（补丁 47→39）；移除 hnp 打包链路与 glob-polyfill/node-sea-stub 模板 - 每进程 JIT 解锁改由 native/jit-unlock 的极小 addon 承担（显式导出 napi_register_module_v1，内联 svc 实现 prctl(0x6a6974)）本轮修复： - addon 加载路径：v40 的应用链接命名空间只允许 dlopen HAP libs 目录内的 addon，放 resfile/el2 会以 ERR_DLOPEN_FAILED: No error information 失败（连零依赖探针也一样）。 entry/wrapper/agent-host 三处改为 libs 优先，实机三进程 enableJIT rc=0； usb_shim_test.node 同步迁到 libs 路径 - 系统主题跟随：ArkTS 写 colorMode 到 el2/system-color-mode.json，main 侧拦截 nativeTheme.themeSource 并解析为 dark/light（fs.watchFile 跟随），冷启动实测生效 - Write 新建文件 ENOENT：agent-spawn-watch.cjs 对 O_CREAT\|O_NOFOLLOW 的 ENOENT 去掉 O_NOFOLLOW 重试一次（同 fs-probe.cjs 记录调用点） - devsh token 发布：端口改读 cua-port.json（缺省 12345）、连接失败重试、全过程同时写 hilog，避免 PC 侧看不到失败原因 - ClipboardItem 结构锚点补丁 + 硬兜底（3.17.2 压缩变量名漂移）工具与文档： - scripts/build.mjs（构建 + verify-build 门禁）、scripts/verify-build.mjs - docs/patch-inventory.md、docs/upstream-comparison.md	2 days ago
docs	docs: 文档盘点清理 —— 归档 10 月 runlog、参考资料归位、删除临时产物 - runlog 2026-10 的 293 行移入 docs/runlog-archive.md，主文件只留 11 月 - 7 套华为/样例参考资料移入 docs/reference/ 并新增索引 README - 删除 gitignored 的 .tmp-dl（723MB）与 temp（5.8MB） - 修正 PORTING_STATUS 版本/层数、log.md 行数与目录、upstream 引擎描述	2 days ago
electron	feat(perm): ACCESS_USER_FULL_DISK 免 Picker 授权 + kernel.* 实验负结论 - web_engine: 新增 ACCESS_USER_FULL_DISK（reason 三语资源）；启动改为检测→弹提示→跳设置页（grantMode=MANUAL_SETTINGS，运行时弹窗无效），删除 Picker 选目录 persistPermission 自愈链 - electron: 移除实验性 kernel.*/ALLOW_EXTERNAL_NATIVE_CODE（可授予但对 dlopen/exec 的 codesign 校验无收益，见 log.md 2026-11-07） - 修复 web_engine 基线编译错误：删除引用已删适配器的 PasteBoardAdapterBind 死代码 - 签名材料密文更新（用户重签 profile ACL） - runlog/log.md 记录验证结论（CDP 实测未签名 .so/ELF 仍被拒）	1 day ago
hotpatch	feat(hotpatch): 测试用动态补丁注入（默认编译期关闭） - ESM loader：entry.mjs/wrapper.mjs 在 import 业务 bundle 前注册，从 PC 服务拉 manifest，对 out/{main,host} 做源码级字符串/正则替换 - scripts/hotpatch.mjs：serve/status/restart/log；设备侧走 hdc rport 7891 - 默认关闭硬保证：ZCODE_HOTPATCH!=1 时不打包 loader、构建末强制删除，删除失败直接抛错拒绝构建；生成的 loader 加入 .gitignore - 纳入 3.17.2 相关修复：deviceName 结构锚点、凭据密钥三端统一、ClipboardItem 结构锚点+硬兜底、触摸设备用户消息操作栏常显	3 days ago
hvigor	fix(provider): 修复 UI 会话 modelUnavailable——账号配置 revision 路径哈希对齐 - 根因：agent 校验账号配置帧 basedOnZCodeBuiltinRevision 必须等于自身 builtin revision（sha256(active 文件路径)）；host（win32 伪装+3.17.2）与 agent（ohos+0.0.0-dev）的 runtime 路径必然不同 → 账号 provider 永远被 fail-closed 丢弃 → 所有 zhipu-account 模型（Start Plan）报 modelUnavailable - 修复：entry.mjs alignProviderConfigEnv() 对齐 agent 的 builtin env 指向 host 的 active 文件；zcode-cli 补丁豁免 basedOn 校验（双保险） - 附带：修复 web_engine PasteBoardAdapterBind 死引用（基线编译错误）； reg-debug 诊断探针暂留包内 - 真机验证：start-plan turn 完成消息落地（finish=completed）	10 hours ago
native	feat(engine): 换装 OHOS Electron 40.1（Chromium 144 / Node 24）+ JIT/主题/Write 修复 v40 迁移（本机实测：main/Renderer/NetworkService/NodeService×3 正常、UI 与 agent RPC 通过）： - web_engine 以 v40 vendor 树为基座重新落地我方适配（启动参数类型、setWindowRectAutoSave、沉浸式窗口、windowStatusDidChange、状态栏补偿、权限表裁剪、toolchain 自愈、 updateAvoidAreaStatus 无参、LogUtil 落盘、CUA/USB 桥接、前进深链接等），新增 HideKeeper/Continue/PowerMonitor 等 v40 适配器，删除 v40 已移除的 PasteBoard/PopupWindow/Screenshot/MessageBox/CommandLine 等死文件 - WebChildProcess 改用 runArkProcess(entryParams, fds, fdsId)，与 v40 libadapter 同源； module.json5 增加 electron_exec_path_ohos 元数据，启动器以 libs/arm64/electron 落盘 - 入口模块迁 v40（HideKeeperAbility/TaskManagerAbility、account_quick_login HAR） - Node 24 内建 sqlite/glob/node:sea 落地，删除 sqlite-adapter（补丁 47→39）；移除 hnp 打包链路与 glob-polyfill/node-sea-stub 模板 - 每进程 JIT 解锁改由 native/jit-unlock 的极小 addon 承担（显式导出 napi_register_module_v1，内联 svc 实现 prctl(0x6a6974)）本轮修复： - addon 加载路径：v40 的应用链接命名空间只允许 dlopen HAP libs 目录内的 addon，放 resfile/el2 会以 ERR_DLOPEN_FAILED: No error information 失败（连零依赖探针也一样）。 entry/wrapper/agent-host 三处改为 libs 优先，实机三进程 enableJIT rc=0； usb_shim_test.node 同步迁到 libs 路径 - 系统主题跟随：ArkTS 写 colorMode 到 el2/system-color-mode.json，main 侧拦截 nativeTheme.themeSource 并解析为 dark/light（fs.watchFile 跟随），冷启动实测生效 - Write 新建文件 ENOENT：agent-spawn-watch.cjs 对 O_CREAT\|O_NOFOLLOW 的 ENOENT 去掉 O_NOFOLLOW 重试一次（同 fs-probe.cjs 记录调用点） - devsh token 发布：端口改读 cua-port.json（缺省 12345）、连接失败重试、全过程同时写 hilog，避免 PC 侧看不到失败原因 - ClipboardItem 结构锚点补丁 + 硬兜底（3.17.2 压缩变量名漂移）工具与文档： - scripts/build.mjs（构建 + verify-build 门禁）、scripts/verify-build.mjs - docs/patch-inventory.md、docs/upstream-comparison.md	2 days ago
scripts	feat(engine): 换装 OHOS Electron 40.1（Chromium 144 / Node 24）+ JIT/主题/Write 修复 v40 迁移（本机实测：main/Renderer/NetworkService/NodeService×3 正常、UI 与 agent RPC 通过）： - web_engine 以 v40 vendor 树为基座重新落地我方适配（启动参数类型、setWindowRectAutoSave、沉浸式窗口、windowStatusDidChange、状态栏补偿、权限表裁剪、toolchain 自愈、 updateAvoidAreaStatus 无参、LogUtil 落盘、CUA/USB 桥接、前进深链接等），新增 HideKeeper/Continue/PowerMonitor 等 v40 适配器，删除 v40 已移除的 PasteBoard/PopupWindow/Screenshot/MessageBox/CommandLine 等死文件 - WebChildProcess 改用 runArkProcess(entryParams, fds, fdsId)，与 v40 libadapter 同源； module.json5 增加 electron_exec_path_ohos 元数据，启动器以 libs/arm64/electron 落盘 - 入口模块迁 v40（HideKeeperAbility/TaskManagerAbility、account_quick_login HAR） - Node 24 内建 sqlite/glob/node:sea 落地，删除 sqlite-adapter（补丁 47→39）；移除 hnp 打包链路与 glob-polyfill/node-sea-stub 模板 - 每进程 JIT 解锁改由 native/jit-unlock 的极小 addon 承担（显式导出 napi_register_module_v1，内联 svc 实现 prctl(0x6a6974)）本轮修复： - addon 加载路径：v40 的应用链接命名空间只允许 dlopen HAP libs 目录内的 addon，放 resfile/el2 会以 ERR_DLOPEN_FAILED: No error information 失败（连零依赖探针也一样）。 entry/wrapper/agent-host 三处改为 libs 优先，实机三进程 enableJIT rc=0； usb_shim_test.node 同步迁到 libs 路径 - 系统主题跟随：ArkTS 写 colorMode 到 el2/system-color-mode.json，main 侧拦截 nativeTheme.themeSource 并解析为 dark/light（fs.watchFile 跟随），冷启动实测生效 - Write 新建文件 ENOENT：agent-spawn-watch.cjs 对 O_CREAT\|O_NOFOLLOW 的 ENOENT 去掉 O_NOFOLLOW 重试一次（同 fs-probe.cjs 记录调用点） - devsh token 发布：端口改读 cua-port.json（缺省 12345）、连接失败重试、全过程同时写 hilog，避免 PC 侧看不到失败原因 - ClipboardItem 结构锚点补丁 + 硬兜底（3.17.2 压缩变量名漂移）工具与文档： - scripts/build.mjs（构建 + verify-build 门禁）、scripts/verify-build.mjs - docs/patch-inventory.md、docs/upstream-comparison.md	2 days ago
web_engine	fix(provider): 修复 UI 会话 modelUnavailable——账号配置 revision 路径哈希对齐 - 根因：agent 校验账号配置帧 basedOnZCodeBuiltinRevision 必须等于自身 builtin revision（sha256(active 文件路径)）；host（win32 伪装+3.17.2）与 agent（ohos+0.0.0-dev）的 runtime 路径必然不同 → 账号 provider 永远被 fail-closed 丢弃 → 所有 zhipu-account 模型（Start Plan）报 modelUnavailable - 修复：entry.mjs alignProviderConfigEnv() 对齐 agent 的 builtin env 指向 host 的 active 文件；zcode-cli 补丁豁免 basedOn 校验（双保险） - 附带：修复 web_engine PasteBoardAdapterBind 死引用（基线编译错误）； reg-debug 诊断探针暂留包内 - 真机验证：start-plan turn 完成消息落地（finish=completed）	10 hours ago
.gitattributes	添加 libelectron.so（LFS）	4 months ago
.gitignore	feat(engine): 换装 OHOS Electron 40.1（Chromium 144 / Node 24）+ JIT/主题/Write 修复 v40 迁移（本机实测：main/Renderer/NetworkService/NodeService×3 正常、UI 与 agent RPC 通过）： - web_engine 以 v40 vendor 树为基座重新落地我方适配（启动参数类型、setWindowRectAutoSave、沉浸式窗口、windowStatusDidChange、状态栏补偿、权限表裁剪、toolchain 自愈、 updateAvoidAreaStatus 无参、LogUtil 落盘、CUA/USB 桥接、前进深链接等），新增 HideKeeper/Continue/PowerMonitor 等 v40 适配器，删除 v40 已移除的 PasteBoard/PopupWindow/Screenshot/MessageBox/CommandLine 等死文件 - WebChildProcess 改用 runArkProcess(entryParams, fds, fdsId)，与 v40 libadapter 同源； module.json5 增加 electron_exec_path_ohos 元数据，启动器以 libs/arm64/electron 落盘 - 入口模块迁 v40（HideKeeperAbility/TaskManagerAbility、account_quick_login HAR） - Node 24 内建 sqlite/glob/node:sea 落地，删除 sqlite-adapter（补丁 47→39）；移除 hnp 打包链路与 glob-polyfill/node-sea-stub 模板 - 每进程 JIT 解锁改由 native/jit-unlock 的极小 addon 承担（显式导出 napi_register_module_v1，内联 svc 实现 prctl(0x6a6974)）本轮修复： - addon 加载路径：v40 的应用链接命名空间只允许 dlopen HAP libs 目录内的 addon，放 resfile/el2 会以 ERR_DLOPEN_FAILED: No error information 失败（连零依赖探针也一样）。 entry/wrapper/agent-host 三处改为 libs 优先，实机三进程 enableJIT rc=0； usb_shim_test.node 同步迁到 libs 路径 - 系统主题跟随：ArkTS 写 colorMode 到 el2/system-color-mode.json，main 侧拦截 nativeTheme.themeSource 并解析为 dark/light（fs.watchFile 跟随），冷启动实测生效 - Write 新建文件 ENOENT：agent-spawn-watch.cjs 对 O_CREAT\|O_NOFOLLOW 的 ENOENT 去掉 O_NOFOLLOW 重试一次（同 fs-probe.cjs 记录调用点） - devsh token 发布：端口改读 cua-port.json（缺省 12345）、连接失败重试、全过程同时写 hilog，避免 PC 侧看不到失败原因 - ClipboardItem 结构锚点补丁 + 硬兜底（3.17.2 压缩变量名漂移）工具与文档： - scripts/build.mjs（构建 + verify-build 门禁）、scripts/verify-build.mjs - docs/patch-inventory.md、docs/upstream-comparison.md	2 days ago
AGENTS.md	refactor: 移除自打包 git 全套额外操作（HNP/el2 农场/GIT_* env/探针改 PATH 查找），git 交由 harmonybrew；brew PATH 改轮询注入（/storage 早期不可见）	11 days ago
PORTING_STATUS.md	docs: 文档盘点清理 —— 归档 10 月 runlog、参考资料归位、删除临时产物 - runlog 2026-10 的 293 行移入 docs/runlog-archive.md，主文件只留 11 月 - 7 套华为/样例参考资料移入 docs/reference/ 并新增索引 README - 删除 gitignored 的 .tmp-dl（723MB）与 temp（5.8MB） - 修正 PORTING_STATUS 版本/层数、log.md 行数与目录、upstream 引擎描述	2 days ago
README.md	docs: 文档盘点清理 —— 归档 10 月 runlog、参考资料归位、删除临时产物 - runlog 2026-10 的 293 行移入 docs/runlog-archive.md，主文件只留 11 月 - 7 套华为/样例参考资料移入 docs/reference/ 并新增索引 README - 删除 gitignored 的 .tmp-dl（723MB）与 temp（5.8MB） - 修正 PORTING_STATUS 版本/层数、log.md 行数与目录、upstream 引擎描述	2 days ago
build-profile.json5	feat(perm): ACCESS_USER_FULL_DISK 免 Picker 授权 + kernel.* 实验负结论 - web_engine: 新增 ACCESS_USER_FULL_DISK（reason 三语资源）；启动改为检测→弹提示→跳设置页（grantMode=MANUAL_SETTINGS，运行时弹窗无效），删除 Picker 选目录 persistPermission 自愈链 - electron: 移除实验性 kernel.*/ALLOW_EXTERNAL_NATIVE_CODE（可授予但对 dlopen/exec 的 codesign 校验无收益，见 log.md 2026-11-07） - 修复 web_engine 基线编译错误：删除引用已删适配器的 PasteBoardAdapterBind 死代码 - 签名材料密文更新（用户重签 profile ACL） - runlog/log.md 记录验证结论（CDP 实测未签名 .so/ELF 仍被拒）	1 day ago
hvigorfile.ts	child_process.fork可运行版本与zcode适配	4 months ago
log.md	feat(perm): ACCESS_USER_FULL_DISK 免 Picker 授权 + kernel.* 实验负结论 - web_engine: 新增 ACCESS_USER_FULL_DISK（reason 三语资源）；启动改为检测→弹提示→跳设置页（grantMode=MANUAL_SETTINGS，运行时弹窗无效），删除 Picker 选目录 persistPermission 自愈链 - electron: 移除实验性 kernel.*/ALLOW_EXTERNAL_NATIVE_CODE（可授予但对 dlopen/exec 的 codesign 校验无收益，见 log.md 2026-11-07） - 修复 web_engine 基线编译错误：删除引用已删适配器的 PasteBoardAdapterBind 死代码 - 签名材料密文更新（用户重签 profile ACL） - runlog/log.md 记录验证结论（CDP 实测未签名 .so/ELF 仍被拒）	1 day ago
oh-package-lock.json5	child_process.fork可运行版本与zcode适配	4 months ago
oh-package.json5	首基线版本	4 months ago
runlog.md	fix(provider): 修复 UI 会话 modelUnavailable——账号配置 revision 路径哈希对齐 - 根因：agent 校验账号配置帧 basedOnZCodeBuiltinRevision 必须等于自身 builtin revision（sha256(active 文件路径)）；host（win32 伪装+3.17.2）与 agent（ohos+0.0.0-dev）的 runtime 路径必然不同 → 账号 provider 永远被 fail-closed 丢弃 → 所有 zhipu-account 模型（Start Plan）报 modelUnavailable - 修复：entry.mjs alignProviderConfigEnv() 对齐 agent 的 builtin env 指向 host 的 active 文件；zcode-cli 补丁豁免 basedOn 校验（双保险） - 附带：修复 web_engine PasteBoardAdapterBind 死引用（基线编译错误）； reg-debug 诊断探针暂留包内 - 真机验证：start-plan turn 完成消息落地（finish=completed）	10 hours ago

ZCode for HarmonyOS

将 ZCode（Electron 桌面应用）移植到 HarmonyOS 2in1 设备的桥接项目。

EntryAbility → XComponent → libadapter.so → libelectron.so
                                                   ↓
                                         entry.mjs → host → agent

web_engine/       ArkTS 桥接层（含 USB 桥接服务 UsbBridgeServer / UsbBridgeAdapter）
electron/         Electron 模块（权限、Ability）
hvigor/plugin/    构建插件 + 运行时模板（含 usbctl.mjs 客户端）
native/           NAPI addon：SQLite、node-pty、libusb shim；另含 usb-compat（兼容层）、
                  arduino（.ino 编译脚本）、usb-libusb-shim（libusb 转发）
vendor/           ZCode 运行时资源（gitignored）
docs/             文档（外设访问见 docs/peripherals.md；华为/样例参考资料见 docs/reference/）

外设访问

USB 设备与串口（Arduino 等）如何在本域内可用——伪造 sysfs、fd 分发、桥接兜底、虚拟串口，以及维护这层时不能踩的坑，见 docs/peripherals.md。

一句话版：entry.mjs 自动注入 LD_PRELOAD/LD_LIBRARY_PATH，原生 USB 工具（adb、 fastboot、pk2cmd、avrdude）源码不用改即可直接跑；串口通过虚拟 tty 提供，系统串口服务不覆盖 CH34x 时也能用。实测可用清单、硬约束与调试方式都在该文档里。

更新 ZCode

下载新版 linux-arm64 AppImage 解压到 vendor/ZCode-x.x.x-linux-arm64/，构建插件自动选最高版本。

已知限制

fs/promises.glob → polyfill
node:sqlite → 自定义 NAPI addon（静态编译 SQLite 3.49.1）
child_process.spawn → spawn-wrapper 重定向（seccomp）
process.title 写 → setter 拦截（uv_set_process_title SIGSEGV）
Renderer 进程无 JIT（缺权限）

Introduction

ArkTS 274Commitsopenharmony 应用 typescript

Customize your domain

README

Rulesets

ZCodeHMOS:基于 HarmonyOS 的 Electron 桌面应用桥接项目

ZCode for HarmonyOS

目录

外设访问

更新 ZCode

已知限制

Introduction