sidleo/dsh-desktop

DeepSeek Harness 桌面应用

DeepSeek Harness 桌面应用（DeepSeek Harness / DSH 的 Electron 桌面壳）

一个极简的 Electron 桌面壳：打开应用 = 启动 dsh web 服务 + 内置浏览器加载其界面；关闭应用 = 自动停止 dsh web 服务。

英文版 |

核心优势

本应用不是重新实现 dsh 界面的第三方客户端，而是直接加载官方 dsh web 界面——因此官方 dsh web 支持的所有插件、配置、会话，本应用 100% 支持，与终端里的 dsh web 完全一致，没有任何功能阉割。

特性

- 启动即用：应用打开时自动在后台启动 dsh web（默认端口 4096，避开 dsh 默认 3080），等界面就绪后在内置窗口中展示
- 界面即应用：窗口就是 dsh web 的完整界面，无浏览器地址栏、标签页
- 关闭即停：关闭窗口/退出应用时，自动终止 dsh web 进程树，不留后台残留
- 复用现有数据：直接使用 ~/.dsh 配置、会话与插件（与终端里的 dsh web 是同一份数据）
- 冲突处理：检测到另一个 dsh web 实例（task-board 单实例锁）或端口占用时，弹窗让用户选择（关闭旧实例 / 换端口 / 取消）
- 流畅体验（v1.1.0）：渲染进程关闭严格沙箱（sandbox: false），消除 macOS 上沙箱导致的界面卡顿；同时移除误伤 SPA 路由的导航拦截器

下载

最新的 macOS（Apple Silicon / arm64）安装包见右侧 Releases 页面：Download → dsh-desktop-1.3.0-arm64.dmg

使用

安装依赖
npm install

启动应用
npm start

配置（环境变量）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| DSH_APP_PORT | 4096 | dsh web 监听端口（避开默认 3080） |
| DSH_BIN | 自动探测 | dsh CLI 路径（显式指定时优先使用） |
| DSH_HOME | ~/.dsh | dsh 数据目录（保持默认即复用现有配置） |

自动发现 dsh（多级探测）

不同用户的 dsh 安装位置差异很大（npm 全局 / pnpm / nvm / 自定义目录，甚至不在 PATH 中）。应用启动时会按优先级自动探测：

1. 环境变量 DSH_BIN（用户显式指定）
2. 上次手动选择（记住的路径）
3. 常见安装路径：~/.local/bin、~/.npm-global/bin、~/.npm/bin、~/.yarn/bin、~/.volta/bin、/usr/local/bin、/opt/homebrew/bin 等
4. PATH（which dsh，覆盖 nvm/volta/asdf shims）
5. npm 全局目录（npm root -g）
6. pnpm 全局目录（pnpm bin -g）
7. Spotlight 搜索（macOS mdfind，兜底）

全部探测失败时：应用会弹窗让你手动选择 dsh 可执行文件，选择后路径会被记住（存入应用配置），下次启动自动使用。

提示：若 dsh 未安装，可先安装它（npm install -g @deepseek-ai/dsh）再重新打开应用。

使用独立数据目录（可选）

应用与现有 3080 实例完全隔离，各自独立配置/会话：

mkdir -p ~/.dsh-desktop-app
DSH_HOME=~/.dsh-desktop-app npm start

开发验证（smoke 模式）

无人值守验证完整链路（启动服务 → 开窗口 → 页面加载 → 自动退出清理），适合 CI/自检：

DSH_HOME=/tmp/dsh-test DSH_APP_PORT=5101 npx electron . --smoke

工作原理

1. 启动：主进程检测 task-board 锁（~/.dsh/task-board/ledger-v2.lock）——若有其他实例，弹窗询问是否关闭；然后 spawn('dsh', ['web', '--port', PORT, '--no-open'])
2. 等待就绪：轮询 http://127.0.0.1:PORT 直到返回 200，再创建 BrowserWindow 加载界面
3. 退出：before-quit 中 SIGTERM 终止 dsh 进程树（按端口定位，不误杀其他实例），然后退出应用

打包为 macOS 应用

使用 electron-builder 将应用打包为 .app / .dmg：

一步完成：打包 .app -> 完整 adhoc 签名 -> 生成 .dmg（推荐）
npm run dist

分步执行
npm run pack     # 1. 生成 .app（dist/mac-arm64/）
npm run sign     # 2. 对 .app 做完整 adhoc 签名（修复未签名导致的启动崩溃）
npm run dmg      # 3. 用已签名 .app 生成 .dmg 安装包

为什么需要签名：本机无 Apple Developer ID 证书，electron-builder 默认跳过签名，导致产物 Info.plist 未绑定、资源未 seal，从 DMG 安装后 macOS 会因 quarantine + translocation 启动崩溃（"Library not loaded: Electron Framework"）。scripts/sign-app.js 用 adhoc 签名（codesign --force --deep --sign -）补全签名，安装后即可正常运行。

注意事项
- GUI 环境 PATH：从 Finder/Dock 双击启动时，应用 PATH 只有 /usr/bin:/bin:/usr/sbin:/sbin，不含 ~/.local/bin（dsh 和 node 所在）。应用会自动多级探测 dsh 位置（见上文「自动发现 dsh」），并在启动 dsh 时把 node 注入 PATH；若 dsh 装在特殊位置，可在首次启动时手动选择，或设 DSH_BIN 指向绝对路径
- 复用 ~/.dsh 时 task-board 是单实例锁：应用运行时，终端里的 dsh web 不能同时开（反之亦然）

目录结构

| 文件/目录 | 说明 |
|-----------|------|
| main.js | 主进程：服务生命周期管理（启动/就绪/停止）+ 窗口 |
| preload.js | 渲染进程桥（向页面暴露服务状态，预留） |
| smoke-test.js | 服务生命周期冒烟测试（不依赖 Electron GUI） |
| scripts/sign-app.js | adhoc 签名脚本 |
| build/icon.icns | 应用图标 |
| dist/ | 打包产物（.app / .dmg，不入库） |
| package.json | Electron + electron-builder 配置 |

License

MIT