鸿蒙桌面封装 fellow99/dsh-desktop-hos

| English

DSH Desktop · Electron on HarmonyOS Edition

Electron on HarmonyOS Edition — 官方 DeepSeek Harness（DSH）Web UI，未做任何修改，通过 Electron 37 跑在 HarmonyOS 2in1 / 平板设备上：这是真正跑在 HarmonyOS 上的 Electron 应用，不是把界面用 ArkUI 重写一遍。另一个 HarmonyOS 版本 HarmonyOS Edition 完全去掉了 Electron —— 改用系统 ArkWeb 加进程内 Node 运行时。

Device capture, not a mockup — HarmonyOS 6.1.0.135 (API 24), 2in1. The UI is the official dsh Web UI, loaded same-origin from the in-process dsh Host.

状态 0.2.1（versionCode 1009）—— 已构建并签名。核心流程（聊天、智能体循环、工具调用、会话持久化、插件市场、窗口状态）已在 HarmonyOS 6.1.0.135（API 24）设备上针对 0.2.0 验证通过；0.2.1 版本还没在设备上重新验证（只验证了构建和签名）。先把分发现状说清楚：debug 签名的 HAP 绑定签名账号和设备，release 签名的包只能通过 AppGallery 分发 —— 详见如何获取。

这次移植有何不同

把 DSH 搬到 HarmonyOS 上还有别的路子。取舍正是这个仓库的全部故事：

| | 本项目（Electron 路线） | 原生宿主路线（Node 运行时 + ArkUI 宿主） |
| 界面 | 官方 Web UI，逐字节一致 —— 没有任何重写 | 同一份 Web 内容外面套原生宿主；平台外壳是重写的 |
| 与桌面版的一致性 | 语义完全相同：同一个渲染进程、同一套 Node API、同一条数据通路 | 不错，但宿主层是重新实现，必须跟着上游走 |
| 运行时权限 | 需要 ACL 受限权限 ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY（JIT）—— 仅限 2in1 / 平板 | 不用 JIT，也就不需要这个权限 |
| 设备覆盖 | HarmonyOS 2in1 / 平板 | 可以扩展到手机 |
两者没有谁「更好」，各自优化的方向不同。这个仓库存在的意义，是把 Electron 路线端到端跑通——包括途中撞上的每一处沙箱冲突。其他版本共用同一套外壳架构和数据平面：dsh-desktop 面向 Windows / Linux / macOS，dsh-desktop-ark 面向鸿蒙版（系统 ArkWeb + 进程内 Node 运行时，不用 Electron）。

目前可用的能力

| 能力 | 状态 |
| 在窗口里跑 dsh Web UI（100% 复用 dsh 前端） | ✅ |
| 会话持久化 + 全文搜索（better-sqlite3，aarch64 ABI 138） | ✅ |
| 插件市场（内置 dshmarket） | ✅ |
| 窗口状态持久化（最大化 / 边界）+ F11 全屏 | ✅ |
| 命令执行——常驻 /system/bin/sh，不走 PTY，靠哨兵行协议驱动，工具层带路径围栏 | ✅ ⚠️ 围栏是尽力而为、可绕过，不是沙箱 |
| 图片附件——sharp 换成纯 JS 容器解析器；它做不了的转换，交给 ArkTS 桥接走平台图片框架（解码 / EXIF / 缩放 / 重编码） | ⚠️ 干净的 8 位 sRGB 文件可逐字节原样通过；桥接不可达时，所有转换都显式报错拒绝；没有缩略图 |
| 自带 Node / pnpm / Python 运行时 | ⛔ 做不到——要发布 ELF 就得有二进制证书（AGC certType: 4），华为不发给个人开发者。宿主机从系统终端装 pnpm 属于可选依赖，永远不算产品能力 |
| 进程沙箱（koffi / landlock） | ❌ 不在范围内 |

限制详解

- 命令执行。 上游的 tool-bash 一行保持禁用：node-pty 没有 aarch64 产物，PTY 又被 SELinux 拒绝。替代方案是拉起常驻的 /system/bin/sh，通过哨兵行读取回复；路径围栏放在工具层，按设计就可绕过。
- 自带运行时。 应用已经能在 PATH 里看到 /data/service/hnp/bin，那里有一个结构合法的 node——只缺 pnpm。用户从系统终端装好 pnpm 之后（软链禁令只针对应用域，所以不能从应用内部装），市场的 probePnpm() 就能通过，插件的安装 / 卸载即可工作。其余功能都不依赖自带运行时：命令执行拉起系统自带的 sh/toybox，文件 / 搜索 / 技能 / 子代理 / 工作流 / 图片这些功能都是纯 JS。分析见 docs/鸿蒙环境能力清单-v0.1.5.md §C.8。
- 图片。 桩代码解析 PNG/JPEG/GIF/WebP 容器头；无法转换的内容交给 ArkTS 桥接层处理（解码、EXIF 方向、缩放、重新编码为 JPEG/WebP/PNG）。限制范围内干净的 8-bit sRGB 输入按字节原样通过，零转换开销。没有可用桥接层时（纯 Node），每次转换都拒绝，并抛出明确的、带归属信息的错误。不生成缩略图。

以下两项是主动决定推迟，不是遗漏：无边框窗口（把窗口控件移进渲染进程，代价大于收益）和开机自启（autoStartupManager 只暴露只读查询）。系统托盘今天已上线——状态栏图标加右键菜单。

界面

| | 浅色 | 深色 |
| 智能体对话 — 工具调用、会话追踪、模型与缓存遥测 | | |
| 设置 — 模型、插件、智能体预设、插件市场、外观 | | |

如何获取

三条路径，按便利程度排序：

1. AppGallery（计划中）。 发布签名的 App Pack 只能从 AppGallery 安装。上架有两个前置条件：ACL 受限权限（约 3 个工作日审核，仅限中国大陆开发者账号）和 AI 合规流程（算法备案 / 模型登记 / 安全评估）。见维护者指南。
2. 自行构建 —— 目前受支持的路径。四个阶段，然后得到本地 HAP：collect-runtime → build-dsh → collect-dsh → tar，再运行 scripts/build-debug.ps1。见维护者指南。要求：DevEco Studio 4.0+、HarmonyOS SDK API 17+（targetSdk 6.1.1(24)）、Node 18+、pnpm@11、HDC。
3. 用自己的账号重签调试构建。 调试配置档绑定设备，别人的调试 HAP 装不到你的机器上；在 DevEco 里重新生成配置档（File → Project Structure → Signing Configs）再重新构建。见维护者指南。

⚠️ 对发布签名的包执行 hdc app install 会失败，报 code:9568322 ... not trusted app source。设备上的回归测试请用 -BuildMode release -SignMode debug。

兼容性

| Shell | dsh（上游 tag） | 运行时 | 设备 / API | 验证状态 |
| 0.2.1 · versionCode 1009 | dsh-v0.2.1-rc.2 | Electron 37 / Node 22.17.0（harmonypc-electron） | HarmonyOS 6.1.0.135 · API 24 · 2in1 / 平板 | 已构建并签名；设备上复验待完成（0.2.0 已验证） |

每次提交 AppGallery，versionCode 都必须是数字，且必须严格递增。上游 dsh 是开发者预览版：每个 shell 固定一个 tag，patches/<dsh-tag>/ 随之移动。

架构

设备上单进程、单源：Electron 主进程托管 dsh Host（webserver + API + WebSocket），窗口从它加载标准 dsh Web UI——没有 CORS，没有鉴权，没有自定义协议，没有 IPC 载体。

EntryAbility (ArkTS) → Electron-on-HarmonyOS → main process (Node 22.17)
└─ dsh Host: webserver on 0.0.0.0:<port> · apiProxy · connection └─ window: the unmodified dsh Web UI, loaded same-origin from that port

三项 HarmonyOS 适配让它跑起来：回环隔离（绑定通配地址，再在会话内把 Host/Origin 改写回回环）、不支持符号链接与硬链接（发布配置档时用复制，原子写入用同目录 rename）、HOME 重定向进沙箱。监听地址是通配的，所以请把它当作单用户本地应用，别暴露在不可信网络上。补丁清单、威胁说明与完整理由见维护者指南。

技术栈

- Electron-on-HarmonyOS 运行时（harmonypc-electron）——Electron 37 / Node 22.17.0
- ArkTS / ArkUI（Stage 模型），搭配 web_engine 桥接 HAR
- 上游 deepseek-harness 锁定在 dsh-v0.2.1-rc.2；本外壳的补丁放在 patches/dsh-v0.2.1-rc.2/

构建、签名与安装

环境要求：DevEco Studio 4.0+ 或命令行工具，HarmonyOS SDK API 17+（target 6.1.1 / API 24），Node 18+，pnpm，hdc。

node scripts/collect-runtime.mjs # ① copy the runtime, then re-apply this app's customizations
node scripts/build-dsh.mjs # ② apply the 13 patches, build dsh + dsh-market
node scripts/collect-dsh.mjs # ③ materialize dsh-dist
powershell scripts\build-debug.ps1 # ④ build + sign the HAP
hdc app install -r entry/build/default/outputs/default/entry-default-signed.hap

签名材料绝不进仓库（signing.<mode>.local.json，已 gitignore）。发布签名、ACL 受限权限、AppGallery 上架、真机调试与四阶段流水线，详见维护者指南。

目录结构

本项目、3 个被消费的项目，外加 1 个架构参考项目，都放在同级目录里（不是子模块）：

(sibling directories)
├── dsh-desktop-hos/ # This project (HarmonyOS HAP, HarmonyOS desktop port)
│ ├── AppScope/ # App scope (icon/name/signing)
│ ├── electron/ # Entry module (copied from harmonypc-electron, contains SOs)
│ ├── web_engine/ # Bridge HAR (ArkTS bridge layer + resfile carries dsh artifacts)
│ ├── src-main/ # Main process main.js (extract + runProfile + loadURL + HarmonyOS adaptations)
│ ├── scripts/ # Four-stage build: collect-runtime → build-dsh → collect-dsh, plus build-debug / build-release
│ ├── runtime-overlays/ # 每次复制运行时后重新应用的应用定制（prune + overlay） │ ├── profiles/desktop/ # 自定义桌面配置档（cordis.patch.yml + package.json） │ ├── patches/ # dsh 上游补丁（14） │ ├── docs/ # 工程规划与最终实现记录 │ ├── plugins/ # 本项目自有插件（harmony-plugin-XXX；烘焙进 HAP，默认全部加载） │ ├── skills/ # 本项目自有工具技能（kebab-case，无前缀；作为内置技能根目录随 HAP 发布） │ └── specs/ # 规格文档（as-built；索引见 specs/README.md） │ ├── harmonypc-electron/ # 鸿蒙上的 Electron 运行时（Electron 37 / Node 22.17.0） │ └── ohos_hap/ # electron + web_engine 模块 + SO 源码（collect-runtime 的复制来源） │ ├── deepseek-harness/ # 被包装的宿主（dsh，源码参考，非子模块） │ ├── apps/ # cli（dsh bin / profile-boot）、web（前端，build:web 产出 dist） │ ├── packages/ # host / client / core / session 工作区包 │ ├── vendor/ # 内置的 cordis 框架包（cordis / loader / hmr / …）
│ └── native/ # landlock-run 原生模块（Linux 沙箱，MVP 中已裁掉） │ └── dsh-market/ # 插件市场（源码参考，npm 包名 "dshmarket"） ├── src/ # 宿主侧（挂载 /dsh-market/* 路由） ├── client/ # 浏览器侧（设置页 UI） ├── lib/ # 编译后的宿主产物（落地到 dsh-dist/node_modules/dshmarket） └── cordis.patch.yml # loader 插入声明（{ id: dsh-market, name: dshmarket }）

../dsh-desktop 是架构设计参考（复用其架构决策 + 补丁 + 主进程编排逻辑），不参与本项目的构建与打包。

相关文档

- docs/鸿蒙环境能力清单-0.2.1.md — 0.2.1 能力清单：本版本上哪些能用、哪些不能用，以及与 ArkWeb 版本的对比
- docs/构建签名与上架.md — 维护者指南：架构、技术栈、构建阶段、签名、真机调试、AppGallery 上架
- docs/工程规划.md — 完整工程规划 + 最终实现记录（Electron 37 落地、关键适配改动、MVP 取舍、交叉编译优化路径）
- specs/README.md — 规格文档索引（项目级 + 9 个模块的 spec/plan，as-built）

参考资料

- deepseek-harness（同级目录 ../deepseek-harness）— 被包装的宿主；其 docs/ 目录包含完整架构文档
- dsh-market（同级目录 ../dsh-market）—— 内置的可视化插件市场（npm 包 dshmarket），由 collect-dsh.mjs 生成
- harmonypc-electron（同级目录 ../harmonypc-electron）—— Electron 在 HarmonyOS 上的运行时
- dsh-desktop（同级目录 ../dsh-desktop）—— 架构设计参考（Electron 桌面外壳）
- dsh-desktop-ark（同级目录 ../dsh-desktop-ark）—— HarmonyOS 版：同一套 dsh Host 跑在 ohos-node-bridge 上（进程内 Node v24.2.0），由系统 ArkWeb 渲染，不用 Electron
- DSH Desktop 官网—— 三个版本、真机截图、架构故事，一页看完

许可证

MIT © 2026 fellow99