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

Star9
2
代码
代码
Issues
Pull Requests
项目讨论
Wiki
分析
Star9
2

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

分支2Tags3
文件最后提交记录最后更新时间
AppScope
chore: versionCode 1000003（强制 HNP 重解包，确保 agent bundle 带 spawn 看门狗注入）
21 小时前
docs
docs: 拆分 log.md 与 runlog.md —— 归档区移入 docs/log-archive.md（2135 行）与 docs/runlog-archive.md，主文件只留结论速查与近期记录
22 小时前
electron
diag: opendir 增加改写/直通 trace（用于判断程序是否真的在枚举 usb 路径）
1 分钟前
hnp
chore: versionCode 1000003（强制 HNP 重解包，确保 agent bundle 带 spawn 看门狗注入）
21 小时前
hvigor
diag: 加 WEDGE_SCAN 周期性 /proc 取证（只记录不杀）；撤销 LD_PRELOAD 全局注入，fakesys 改按需手动加载
20 小时前
native
diag: opendir 增加改写/直通 trace（用于判断程序是否真的在枚举 usb 路径）
1 分钟前
scripts
fix: 阻塞 REAPURB 不再有超时兜底，改为 close 唤醒（对齐内核 usbdev_release） - 有限超时返回 EAGAIN 会让 adb 判 read failed 拆 transport - 纯无限阻塞又会让 kill-server 的读线程永不退出（新旧 server 抢端口 → protocol fault） - 现在只有两条唤醒路径：URB 完成，或 fd 被 close（ohb_dev_known 检测注销） - 新增 scripts/devbench-adb.sh：设备侧测量 adb 冷/热启动与命令耗时 实测：devices 热查询 5 次共 3s、shell 5 次共 3s、kill-server 后冷启动 3s 且设备立即可见、仅剩 1 个 server 进程
18 分钟前
web_engine
fix: adb 全链路打通（claim 顺序/重枚举自愈/URB 阻塞语义/真实序列号） - claim：先 requestRight，再 usbManager.claimInterface，失败才落回 raw ioctl （只做 raw 时 claim 假成功，随后 bulk 被内核判 EACCES） - 删掉 SET_CONFIGURATION(0) 解绑驱动：会触发设备重枚举（1-6→1-7→1-8）， 程序缓存的 fd 当场失效；改为按 VID/PID reopen，句柄号不变 - 兼容层新增 openid 命令与 (bus,addr)→VID/PID 身份表，open 失败自动重定位 - 阻塞版 USBDEVFS_REAPURB 改为无限阻塞（30s 到期返回 EAGAIN 会让 adb 判 read failed） - 序列号改读设备描述符 iSerialNumber 的字符串描述符（usbManager.device.serial 为空） - bulk64 补 claim 只在句柄未成功传过时做一次，去掉 IN 轮询里的冗余 binder - LogUtil 将 UsbBridge 日志落盘到 cache/usb-adapter.log（应用域读不到 hilog） - 新增 native/usb-compat/preload_probe.c 与 scripts/probe-renum.cjs 排障探针 实测：adb devices=31f025c3 device；shell echo 连续成功；push 14.6MB/s、pull 字节一致
29 分钟前
.gitattributes
添加 libelectron.so（LFS）
4 个月前
.gitignore
chore: 移除误提交的 .tmp 构建产物，加入 .gitignore
3 小时前
AGENTS.md
refactor: 移除自打包 git 全套额外操作（HNP/el2 农场/GIT_* env/探针改 PATH 查找），git 交由 harmonybrew；brew PATH 改轮询注入（/storage 早期不可见）
1 天前
PORTING_STATUS.md
docs: harmonybrew 工具链接入复盘 + PORTING_STATUS 更新（CUSTOM_SANDBOX/SHELL 钉死/授权自愈三约束）
1 天前
README.md
docs: README 增补 USB 外设访问（桥接器架构 + usbctl 用法 + libusb shim + DDK 取舍），指向 usb-bridge skill
1 天前
build-profile.json5
feat: READ_WRITE_USB_DEV 打通 USB 直连（探针 available=true），桥接与 shim 降级为兜底
21 小时前
hvigorfile.ts
child_process.fork可运行版本与zcode适配
4 个月前
log.md
fix: adb 全链路打通（claim 顺序/重枚举自愈/URB 阻塞语义/真实序列号） - claim：先 requestRight，再 usbManager.claimInterface，失败才落回 raw ioctl （只做 raw 时 claim 假成功，随后 bulk 被内核判 EACCES） - 删掉 SET_CONFIGURATION(0) 解绑驱动：会触发设备重枚举（1-6→1-7→1-8）， 程序缓存的 fd 当场失效；改为按 VID/PID reopen，句柄号不变 - 兼容层新增 openid 命令与 (bus,addr)→VID/PID 身份表，open 失败自动重定位 - 阻塞版 USBDEVFS_REAPURB 改为无限阻塞（30s 到期返回 EAGAIN 会让 adb 判 read failed） - 序列号改读设备描述符 iSerialNumber 的字符串描述符（usbManager.device.serial 为空） - bulk64 补 claim 只在句柄未成功传过时做一次，去掉 IN 轮询里的冗余 binder - LogUtil 将 UsbBridge 日志落盘到 cache/usb-adapter.log（应用域读不到 hilog） - 新增 native/usb-compat/preload_probe.c 与 scripts/probe-renum.cjs 排障探针 实测：adb devices=31f025c3 device；shell echo 连续成功；push 14.6MB/s、pull 字节一致
29 分钟前
oh-package-lock.json5
child_process.fork可运行版本与zcode适配
4 个月前
oh-package.json5
首基线版本
4 个月前
runlog.md
docs: runlog 记录 adb 耗时归因（测试通道假象）与 kill-server 回归修复
18 分钟前
temp_shot_z.jpeg
fix: 删除 ~/.zcode 后无法启动——wrapper 补 zcode.cjs 存储准备入口 - 现象: 删除 ~/.zcode 重装后卡在"无法完成启动准备 / 当前配置的 Agent 不支持独立存储准备" - 根因: 存储准备 worker 入口是 ~/.zcode/server/agents/glm/zcode.cjs（原本由应用自己落盘）， 删除 ~/.zcode 后应用无法重建（其 agent 部署走远端 release，本环境 HTTP 400）， 而 wrapper 只补了 zcode-cli.cjs（文件名不同）→ unsupported_runtime - 修复: wrapper.mjs staging 时把 zcode-cli.cjs 复制一份为 zcode.cjs（副本自带 node:sqlite → ./sqlite-adapter.cjs 补丁，依赖文件同目录已就位）；仅缺失时复制，不覆盖应用版本 - 诊断: 应用卡在启动错误页时 CDP 仍可用，用 renderer fetch('file://…') 逐个探测关键文件 是否存在，比翻日志更快（本次直接定位 zcode.cjs 缺失） - 文档: log.md 新增小节，PORTING_STATUS 第 5 层补充说明
21 天前

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
vendor/           ZCode 运行时资源（gitignored）

USB 外设访问

普通应用读不到 /dev/bus/usb（节点 open 恒 EACCES），libusb 直接枚举必失败。 本项目用 @ohos.usbManager（无 @permission 限制，用户授权一次即可）在应用内起一个 本地桥接服务，让 agent 和原生工具都能访问 USB 设备：

原生工具(pk2cmd) ─ libusb-1.0.so.0(shim) ─┐
agent 终端 ─ node usbctl.mjs ─────────────┴─→ 127.0.0.1:7788 ─→ usbManager ─→ USB 设备
  • 服务：web_engine/src/main/ets/adapter/UsbBridgeServer.ets，窗口就绪 6 秒后监听 127.0.0.1:7788，行协议：list / open <bus> <addr> / claim / control / bulk / close。 不做任何 VID/PID 假设，任意设备可打开。
  • 客户端：node <resfile>/usbctl.mjs <命令>（随包部署，PATH 已含 node）。 用法示例与排障见 skill usb-bridge（~/.zcode/skills/usb-bridge/SKILL.md）。
  • 原生工具：native/usb-libusb-shim/ 提供 libusb-1.0.so.0，把 libusb 调用转发到 7788；LD_LIBRARY_PATH 已在 entry.mjs / wrapper.mjs 中注入，pk2cmd 之类 源码不用改即可用（静态链接 libusb 的除外）。重建：bash native/usb-libusb-shim/compile.sh。
  • 首次访问会弹系统授权框，需前台确认；授权按设备名（bus-addr）记忆。

DDK（ACCESS_DDK_USB）不是这里的通路：UsbDdk 只能在 DriverExtensionAbility 内调用， 且其 metadata 的 vid/pid 白名单不支持通配符，运行时按 deviceId 绑定所需的 ACCESS_DDK_DRIVERS 在调试签名下装不上。需要“设备固定 + 白名单写死”的专项驱动时再用。

更新 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（缺权限）

项目介绍

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

ArkTS190提交数openharmony应用typescript
定制我的领域
README
规则集