Electron + DeepSeek Harness (dsh) 桌面壳

用 Electron 把 DeepSeek 官方的开源 Agent 运行时 DeepSeek Harness（@deepseek-ai/dsh，命令行 dsh）封装成一个可双击运行的桌面应用：

• 主进程本地拉起 dsh web 服务（默认 http://127.0.0.1:3080）
• 用 BrowserWindow 承载官方 Web UI
• 启动期间显示带实时日志的「加载页」
• 系统托盘：显示窗口 / 重启 dsh 服务 / 刷新 / 退出
• 退出应用时自动停止本地 dsh 进程
• 若目标端口已有 dsh 在运行，则直接复用（方便开发者调试）

设计哲学：本工程只做「桌面壳」，不改动 dsh 本身。所有 Agent 能力、插件、MCP、模型配置都在 dsh 内完成（一切皆插件）。

---

环境要求

依赖	版本要求	说明
Node.js	^22.19 || >=24（偶数版本）	这是 dsh 自身的要求，奇数版本不支持
npm	任意较新版本	用于安装依赖
操作系统	macOS / Windows / Linux	Electron 跨平台

启动器会按以下优先级选择 Node 运行时（见 src/harness-launcher.js）：

1. 环境变量 DSH_NODE_PATH 显式指定
2. PATH 中的 node
3. 常见 nvm 位置（~/.nvm/versions/node/*）
4. 回退到 Electron 内置 Node（以 ELECTRON_RUN_AS_NODE=1 运行）

⚠️ 回退到 Electron 内置 Node 时，若 Electron 捆绑的 Node 版本低于 22.19，dsh 会启动失败。建议本机安装满足要求的 Node，或通过 DSH_NODE_PATH 指定。

---

快速开始

# 1. 安装依赖（会自动写入 package.json）
npm install @deepseek-ai/dsh
npm install --save-dev electron

# 2. 生成托盘图标（纯色占位，生产请替换 assets/icon.png）
npm run icon

# 3. 配置 DeepSeek API Key
export DEEPSEEK_API_KEY="你的密钥"      # macOS / Linux
# 或在 dsh Web UI 的 Settings → Models 中填写

# 4. 启动桌面应用
npm start

首次启动会先解析 @deepseek-ai/dsh 的 bin，选择合适的 Node，拉起 dsh web，并轮询端口直到就绪，随后窗口自动跳转到 http://127.0.0.1:3080。

---

配置项（环境变量）

变量	默认值	说明
DSH_PORT	3080	dsh web 监听端口
DSH_NODE_PATH	自动探测	指定运行 dsh 的 Node 可执行文件路径
DEEPSEEK_API_KEY	无	DeepSeek API 密钥（也可在 Web UI 中配置）
DSH_HOME	~/.dsh	dsh 配置/会话目录（dsh 自身使用）

DSH_PORT=8080 DEEPSEEK_API_KEY=sk-xxx npm start

---

目录结构

electron-deepseek-harness/
├── main.js                 # Electron 主进程：窗口 / 托盘 / 生命周期
├── preload.js              # 上下文隔离的预加载脚本（暴露安全的 api）
├── index.html              # 启动加载页（带实时状态日志）
├── src/
│   └── harness-launcher.js # 核心：解析 dsh bin、选 Node、拉起/轮询/停止服务
├── scripts/
│   ├── make-icon.js        # 生成占位 PNG 图标（无外部依赖）
│   └── smoke.js            # 无 GUI 冒烟测试：验证 dsh bin 与 CLI 可执行
├── assets/
│   └── icon.png            # 托盘 / 窗口图标（生产请替换为正式图标）
└── package.json

---

冒烟测试（无需 GUI）

npm run smoke

该命令验证：dsh 包可被解析、CLI 入口文件存在、选用 Node 可执行 dsh --help。

---

打包分发（electron-builder 注意）

dsh 依赖大量 npm 包（500+），且存在隐式的工作区提升（hoisting）依赖。electron-builder 默认会裁剪掉这些「未直接声明」的依赖，导致发布版运行时 ERR_MODULE_NOT_FOUND。

本工程的处理方式（build/afterPack.js）：

• 把开发期这份已验证可运行的 node_modules 整体 rsync 进打包目录的 app/node_modules，仅排除 electron / electron-builder 等构建期依赖。这样发布版用 ELECTRON_RUN_AS_NODE 拉起 dsh 时，依赖树与开发环境完全一致。
• asar 必须关闭（electron-builder.yml 中 asar: false），因为 dsh 在运行时需要动态 require 模块，asar 包无法支持。
• macOS 图标必须 ≥512×512（scripts/make-icon.js 已生成 1024×1024，生产环境请替换为品牌图标）。
• 注意 dsh 要求 Node ^22.19 || >=24：Electron 43 内置 Node 24，满足要求，因此发布版可纯靠内置 Node 运行，无需额外捆绑 Node。

正常流程

npm install            # 安装 dsh + electron + electron-builder
npm run icon           # 生成图标
npm run dist:mac       # 产出 dist/DeepSeek Harness.dmg 与 .zip（macOS）
# 或先出 .app：npm run pack，再自行用 hdiutil 打包

未配置签名证书时 identity: null，产物为未签名包。用户首次打开需右键「打开」或在终端 xattr -cr "DeepSeek Harness.app" 放行。

受限网络 / 离线构建（本仓库已验证）

1. 下载 electron 二进制：官方源不稳定时改用国内镜像：

   ELECTRON_MIRROR="https://cdn.npmmirror.com/binaries/electron/" \
     node node_modules/electron/install.js

2. 绕过安全删除拦截：electron-builder 解压前会清空 dist/mac-arm64，若被批量删除保护拦截，先「移走」遗留目录而非删除：

   mv dist/mac-arm64 /tmp/dsh-old-$$ 2>/dev/null

3. 本仓库的 pack / dist:mac / dist 脚本已把 ELECTRON_MIRROR 与 ELECTRON_BUILDER_BINARIES_MIRROR 固化进命令（见 package.json），受限网络下直接 npm run pack 即可自动走镜像、生成完整 .app，再用 hdiutil create 手工出 dmg（本仓库产物即如此制作）。

---

已知限制

• dsh 目前为 Developer Preview (v0.1)，命令/插件接口可能破坏性变更，请锁定版本。
• 本工程默认不代理任何云端流量；如需联网搜索等能力，在 dsh 内配置对应插件/MCP。
• 应用图标已替换为品牌图标（DeepSeek 蓝鲸 logo，1024×1024 PNG → 自动生成 macOS icns），位于 assets/icon.png。

---

相关链接

• DeepSeek Harness 仓库：https://github.com/deepseek-ai/deepseek-harness
• npm 包：@deepseek-ai/dsh
• 官方 Web UI 指南：npx @deepseek-ai/dsh web

许可证

MIT