bolt.diy 鸿蒙 PC 适配全记录：让 AI 全栈开发工作台在 HarmonyOS PC 上真正跑起来

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_bolt.diy

环境搭建文章：https://blog.csdn.net/lbcyllqj/article/details/161286249?sharetype=blogdetail&sharerId=161286249&sharerefer=PC&sharesource=lbcyllqj&spm=1011.2480.3001.8118

一、为什么选择适配 bolt.diy

AI 编程工具正在从"回答代码问题"走向"直接参与工程生产"。用户给出一句需求，工具不仅要返回代码片段，还要创建项目、维护文件树、运行依赖安装命令、启动开发服务器，并把结果放进预览窗口。bolt.diy 正是这一类产品中很有代表性的开源项目：它基于 Remix、React 和 Electron 构建桌面端体验，在同一个工作台中组织 AI 对话、代码编辑、终端、预览、版本同步和工程导出。

选择适配 bolt.diy，一方面是希望为 HarmonyOS PC 补充一款面向开发者的 AI 全栈开发工具；另一方面，它也适合检验鸿蒙 Electron 方案面对复杂 Web 应用时的真实承载能力。相比普通信息展示类应用，bolt.diy 同时依赖 Electron 主进程、Remix 服务端、Preload IPC、浏览器存储、WebContainer、Service Worker、WASM 和外部模型服务。只要其中一层没有接通，界面可能仍能显示，但项目导入、代码运行或预览就会在后续环节暴露问题。

本次适配没有将原项目重写为 ArkTS，而是采用 OpenHarmony Electron 运行时封装现有业务产物。当前鸿蒙应用包名为 com.bolt.diy，应用版本为 1.0.0，支持 2in1 与 tablet 设备，目标 SDK 为 HarmonyOS 6.0.2(22)。

二、项目架构与适配路线

bolt.diy 的桌面版本并不是单纯给网页套一层窗口。它的主要组成如下：

层次	上游职责	鸿蒙侧处理
Electron 主进程	创建窗口、菜单、Cookie、协议转发和应用生命周期	由 OpenHarmony Electron v37.2.1 承载
Preload	通过 `contextBridge` 暴露受控 IPC 能力	保留原有构建产物并随应用注入
Remix 应用	首页、聊天、API 路由和工作台界面	继续使用 React/Remix 业务代码
WebContainer	在浏览器沙箱内运行 Node.js 工程	保留能力入口，按真机环境逐项验证
HAP 宿主	Ability、系统窗口、权限、签名和安装包	新增 `electron` 与 `web_engine` 模块

适配后的启动链路可以概括为：

text 复制代码

EntryAbility
    └── OpenHarmony Electron 运行时
          └── ohos-main-wrapper.js
                ├── 加载 ohos-electron-shims.js
                └── 动态导入 build/electron/main/index.mjs
                      ├── 启动 Remix 请求处理
                      ├── 创建 BrowserWindow
                      └── 加载 bolt.diy 工作台

这里最重要的取舍是把平台差异收敛在 HAP 宿主、启动 wrapper 和 shim 中。Remix 页面、编辑器和项目工作流仍来自上游构建产物，避免为鸿蒙单独维护一套功能相近但长期难以同步的界面。

三、鸿蒙工程的目录组织

适配内容集中在仓库的 bolt.diy-ohos-migration/ 目录中，源项目的业务结构保持不变。核心目录如下：

text 复制代码

bolt.diy-ohos-migration/
├── source/                         # 用于迁移的上游源码副本
├── reports/                        # 扫描、能力矩阵和验证记录
├── evidence/                       # 真机验证证据
└── ohos_hap/
    ├── AppScope/app.json5          # bundleName、版本、图标和应用名
    ├── build-profile.json5         # SDK、产品与签名配置
    ├── electron/                   # EntryAbility 与 Electron 原生库
    └── web_engine/
        └── src/main/resources/resfile/resources/app/
            ├── package.json
            ├── ohos-main-wrapper.js
            ├── ohos-electron-shims.js
            ├── build/              # Remix 与 Electron 构建产物
            └── node_modules/       # 裁剪后的运行期依赖

electron 是入口 HAP 模块，负责应用生命周期与系统窗口；web_engine 携带 OpenHarmony Electron 运行时以及应用资源。最终运行时会把 resources/app 当作 Electron 应用根目录，package.json 的 main 指向 wrapper，再由 wrapper 加载真实主进程入口。

四、真机上的核心工作流

以下 5 张图片均在 HarmonyOS PC 2in1 真机上重新启动应用后采集，设备分辨率为 3120×2080，测试对象为设备桌面上的真实 demo 工程。

1. 首页、提示输入与工程入口完整呈现

应用冷启动后首先进入 "Where ideas begin" 首页。提示输入区、模型配置、文件上传、URL 获取、语音入口，以及 Import Chat、Import Folder、Clone a repo 等工程入口均能正常渲染。窗口使用 HarmonyOS PC 原生窗框，顶部仍保留 Electron 菜单，最大化后内容会随可用区域重新布局。

这一步验证的不只是静态页面。启动过程中已经依次经过 EntryAbility、libelectron.so、wrapper、主进程和 BrowserWindow.loadURL，最终由 Remix 页面完成首屏渲染；任何一层发生异常，通常都会表现为闪退、白屏或只剩空窗口。

2. 模型与上下文长度可以在真机界面选择

展开模型选择器后，界面能够列出当前提供方下的 Amazon Nova、Claude、Mistral 等模型，并显示 4K、5K、8K、200K 等上下文长度。提供方选择、模型选择与 API Key 状态处于同一个输入区域，用户可以在正式发起请求前确认调用目标。

模型服务需要用户自行配置合法的 API Key。此次记录没有在截图中写入密钥，也没有把"模型列表能够显示"等同于"外部模型请求已经成功"；它验证的是配置界面、下拉交互和模型元数据能够在鸿蒙 Electron 渲染进程中工作。

3. 通过系统选择器导入真实工程目录

点击 Import Folder 后，应用拉起 HarmonyOS 文件选择器。选择器明确提示应用只能访问用户选定的文件或文件夹，并展示桌面中的真实目录。本次选择 demo，而不是在应用内构造一份静态文件树。

这一环节涉及桌面 Web 应用经常忽略的权限边界：鸿蒙应用不能把开发机上的任意绝对路径直接带入沙箱，必须由用户通过系统选择器明确授权。导入成功后，bolt.diy 才将选中的目录内容交给项目工作区和 WebContainer 流程处理。

4. 文件树、代码编辑器和终端组成连续工作区

导入完成后，左侧对话区记录 "I've imported the contents of the demo folder"，右侧工作台展开真实文件树，并在 Monaco 编辑器中打开 server/init-mongo.js。代码语法高亮、行号、目录层级、Code/Diff/Preview 标签和 Bolt Terminal 同时可见。

从截图可以看到，public、server、package.json、README.md 和 start.sh 等文件已经进入同一个项目上下文，编辑器展示的是工程中的 MongoDB 初始化脚本。左侧项目记录与右侧编辑器并非两个孤立页面：导入动作创建项目上下文，随后文件浏览、代码修改、命令执行和预览都围绕该上下文继续进行。

5. WebContainer 终端与工程导出入口可用

工作台终端已经进入 /project，并显示 Node.js v22.22.3 的运行信息；Export 菜单可展开 Download Code 与 Export Chat 两个操作。由此可以确认 WebContainer 的基础启动、终端界面和导出交互已经进入真实运行链路。

本次导入的 demo 服务依赖 MongoDB 模块及对应运行环境，执行 npm run start 时仍出现模块加载链路错误，因此没有把 Preview 写成"已完全可用"。当前结果说明 Node.js 沙箱与终端基础能力可以启动，但具体项目能否预览，还取决于依赖安装结果、Service Worker、SharedArrayBuffer、网络访问以及项目自身对数据库等外部服务的要求。

五、适配中真正棘手的几个问题

难点一：Electron 主进程不是普通静态资源

bolt.diy 的 Remix 服务端与 Electron 主进程共同参与页面加载。鸿蒙侧不能只复制 build/client，否则首屏资源可能存在，但 API 路由、Cookie 初始化和协议处理会缺失。适配时完整保留 build/client、build/server 与 build/electron，并通过 wrapper 动态导入主进程入口，使资源路径和加载时序与打包后的应用根目录保持一致。

难点二：桌面专属 API 需要明确降级

自动更新、macOS Dock、Touch Bar、桌面通知和电源事件并不都具备鸿蒙等价语义。如果仍按原平台执行，应用可能在启动阶段就因对象或方法不存在而退出。ohos-electron-shims.js 对这些能力提供受控的空实现，自动更新则主动停用，交由 HAP 或应用市场分发流程负责。这里的目标不是伪造成功，而是让不影响核心工作台的桌面附属能力退出关键路径。

难点三：异常退出在 appspawn 下会被放大

桌面 Node.js 程序常用 process.exit(1) 结束失败流程，但在鸿蒙 appspawn 管理下，直接退出可能被记录为 SIGABRT，并造成用户看到窗口瞬间消失。启动 wrapper 因此改为记录异常并让 Electron 生命周期接管收尾，避免可诊断错误被误判为原生崩溃。

难点四：运行期依赖既影响兼容性，也影响包体

源项目完整 node_modules 约 4.2 GB，其中包含 Rollup、fsevents 等仅用于 macOS 或构建阶段的二进制。将其原样塞入 HAP，不但包体失控，还可能带入无法在 arm64 OpenHarmony 上加载的 .node 文件。适配工程使用生产依赖重新安装并移除构建期平台二进制，运行期依赖约 571 MB；加上 Electron/Chromium 原生运行库后，签名 HAP 约 482 MB。这个体积仍然偏大，但依赖边界已经从"整个开发环境"收敛为"应用实际运行环境"。

难点五：WebContainer 可启动不代表所有工程都能预览

WebContainer 依赖 SharedArrayBuffer、COOP/COEP、Service Worker、WASM 和浏览器沙箱中的 Node.js 能力。真机上看到终端和 Node.js 版本，只能证明底座已启动；依赖安装、开发服务器端口转发和 Preview 渲染还需要按项目验证。本次 demo 工程又引入 MongoDB，进一步增加了外部服务约束。因此适配报告把"终端基础能力可用"和"任意工程均可预览"分开表述，避免用首屏成功掩盖后半段链路的条件。

六、关键适配改动

1. 补齐 HAP 应用宿主

AppScope/app.json5 将包名配置为 com.bolt.diy，同步应用名、版本和图标；module.json5 声明 EntryAbility、2in1/tablet 设备类型，并申请 ohos.permission.INTERNET 与 ohos.permission.GET_NETWORK_INFO。这些权限用于模型请求、依赖下载以及在线部署等网络功能。

2. 用 wrapper 固定启动顺序

resources/app/package.json 不再直接指向构建后的主进程，而是先进入 ohos-main-wrapper.js。wrapper 先建立鸿蒙平台兼容层，再动态导入 build/electron/main/index.mjs，从而保证主进程第一次访问 Electron API 时，必要的降级对象已经存在。

3. 调整窗口与自动更新策略

原桌面窗口使用的 macOS vibrancy 效果不适用于 HarmonyOS PC，适配后使用系统原生窗框。electron-updater 相关流程在鸿蒙环境中关闭，避免桌面安装包更新机制与 HAP 分发机制冲突。

4. 注入完整 Remix/Electron 产物

构建输出中的 Remix client/server、Electron main/preload、运行期配置和生产依赖统一放入 web_engine 资源目录。HAP 加载后，Electron 的 app.getAppPath() 能够定位该应用根目录，主进程再从这里启动 Remix 请求处理和窗口加载流程。

七、编译、安装与启动

1. 构建上游 Web 与 Electron 产物

bash 复制代码

pnpm install
pnpm run build
pnpm exec vite build --config vite-electron.config.ts

构建完成后应得到：

text 复制代码

build/
├── client/      # Remix 客户端资源
├── server/      # Remix 服务端构建
└── electron/    # Electron 主进程与 preload

2. 构建签名 HAP

确认 DevEco Studio 已安装项目要求的 HarmonyOS API 22 SDK，并为 com.bolt.diy 配置签名。在 bolt.diy-ohos-migration/ohos_hap 目录执行：

bash 复制代码

hvigorw --mode module \
  -p module=electron@default \
  -p product=default \
  assembleHap --no-daemon

产物位于：

text 复制代码

electron/build/default/outputs/default/
├── electron-default-unsigned.hap
└── electron-default-signed.hap

3. 安装并启动真机应用

bash 复制代码

hdc list targets
hdc install -r electron/build/default/outputs/default/electron-default-signed.hap
hdc shell aa start -a EntryAbility -b com.bolt.diy

真机可通过 bm dump -n com.bolt.diy 核对包信息。本次设备返回的兼容 API 为 50005017，目标 API 为 60002022，CPU ABI 为 arm64-v8a；重新冷启动后主应用进程和 GPU 子进程均保持运行，首页与导入后的工作区没有出现白屏。

八、当前可用范围与边界

当前版本已经验证以下能力：

签名 HAP 可安装，EntryAbility 可启动；
OpenHarmony Electron 主进程、Preload 和 Remix UI 可加载；
BrowserWindow、loadURL、contextBridge 和默认 Session 进入启动链路；
首页、模型选择、API Key 配置入口和提示输入区可以交互；
HarmonyOS 系统文件选择器可以打开，并能导入用户授权的真实目录；
项目文件树、Monaco 代码编辑器、聊天记录和 Bolt Terminal 可以在同一工作区显示；
WebContainer 能进入 /project 并提供 Node.js 终端基础环境；
Download Code、Export Chat 和 Sync Files 等菜单能够展开。

仍需注意以下限制：

AI 对话依赖用户自行配置模型服务及有效 API Key；
WebContainer 对浏览器隔离能力和网络环境敏感，不应据一次启动结果推断所有 npm 工程都能运行；
本次 demo 的 MongoDB 依赖未满足，开发服务未启动成功，因此 Preview 没有形成可访问页面；
自动更新已按鸿蒙分发方式停用，Touch Bar、Dock 等平台专属能力只做兼容降级；
HAP 包含 Electron/Chromium 运行时和较大的 JavaScript 依赖集，包体仍有继续裁剪的空间；
菜单、对话框及部分事件 API 虽已进入适配层或官方支持范围，仍应在具体业务触发点继续做专项真机验证。

九、总结

bolt.diy 的鸿蒙 PC 适配并不是把首页显示出来就结束。真正有价值的验证路径是：从 HAP 冷启动进入 Remix 首页，完成模型配置交互，通过系统选择器导入真实目录，再进入文件树、代码编辑器和 WebContainer 终端，最后检查预览与导出边界。本次真机记录已经把这条链路推进到项目工作区和 Node.js 终端，并且如实保留了示例工程在依赖与预览阶段的限制。

这次实践也说明，复杂 Electron 工具迁移到 HarmonyOS PC 时，最稳妥的顺序是先保留成熟业务代码，把平台差异集中到 HAP 宿主与启动兼容层；随后用真实工程验证文件授权、主进程服务、运行期依赖和浏览器沙箱；最后再逐项打通模型服务、开发服务器与预览。这样得到的不只是"能够安装"的包，而是一条可以继续演进、问题边界也足够清楚的适配路径。