DeepSeek Harness Desktop

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

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

English version | 中文

---

核心优势

本应用不是重新实现 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.1.0-arm64.dmg

使用

# 安装依赖
npm install

# 启动应用
npm start

---

配置（环境变量）

变量	默认值	说明
DSH_APP_PORT	4096	dsh web 监听端口（避开默认 3080）
DSH_BIN	自动探测	dsh CLI 路径
DSH_HOME	~/.dsh	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 所在）。应用已内置绝对路径探测（~/.local/bin/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