kevenxz/dsh-desktop

DeepSeek Harness Desktop
把 DeepSeek Harness Web UI 带到原生 Windows 桌面。

Platform
Electron
DSH
License

DeepSeek Harness Desktop 是一个轻量的 Windows 桌面封装。应用启动时会在本机回环地址上运行随包提供的 dsh web，等待服务就绪后再用安全隔离的 Electron 窗口加载它。无需每次手动打开终端和浏览器，同时继续使用本机已有的 DSH profile、会话、凭据和设置。

[!NOTE]
这是社区项目，并非 DeepSeek 官方发行版。核心能力来自 DeepSeek Harness。

功能特性

- 双击启动：自动运行 dsh --profile web 并打开原生窗口
- 无端口冲突：默认动态选择一个空闲的本地端口
- 数据复用：沿用 $DSH_HOME，默认位置为 %USERPROFILE%\.dsh
- 托盘常驻：关闭窗口仅隐藏应用，后台会话和任务继续运行
- 托盘菜单：显示主窗口、浏览器打开、查看日志、完全退出
- 单实例：重复启动时自动聚焦已有窗口
- 安全隔离：仅监听 127.0.0.1，启用渲染进程沙箱并禁止 Node.js 集成
- 干净退出：退出应用时终止完整的 DSH 子进程树
- 两种分发形式：NSIS 安装包和免安装 Portable 单文件版

系统要求

- Windows 10 或 Windows 11
- 从源码运行或构建时需要 Node.js >= 22.12.0 和 npm

打包后的应用会携带 DSH 依赖；程序优先使用系统 Node.js，找不到时会回退到 Electron 自带的 Node.js 运行时。

从源码运行

git clone https://github.com/kevenxz/dsh-desktop.git
cd dsh-desktop
npm install
npm start

首次启动时，应用会自动创建默认工作区 %USERPROFILE%\DSHWorkspace。

配置

可以通过启动参数或环境变量指定 agent 的工作区：

启动参数
npx electron . --workspace "G:\workspace\deepseek"

环境变量
$env:DSH_DESKTOP_WORKSPACE = "G:\workspace\deepseek"
npm start

支持的配置项：

| 配置 | 用途 | 默认值 |
| --- | --- | --- |
| --workspace  | 指定 agent 工作区 | %USERPROFILE%\DSHWorkspace |
| DSH_DESKTOP_WORKSPACE | 通过环境变量指定工作区 | 同上 |
| DSH_DESKTOP_PORT | 固定本地 Web 服务端口 | 自动选择空闲端口 |
| DSH_DESKTOP_NODE | 指定 Node.js 可执行文件 | 系统 Node.js，随后回退到 Electron |
| DSH_DESKTOP_SMOKE=1 | 页面加载成功后自动退出，用于冒烟验证 | 关闭 |

启动参数 --workspace 的优先级高于 DSH_DESKTOP_WORKSPACE。

数据与日志

应用不会复制或迁移 DSH 数据，而是直接复用 $DSH_HOME 中的 profile、会话、凭据与设置。

桌面壳和 DSH 服务日志位于：

%APPDATA%\DeepSeek Harness\dsh-desktop.log

也可以右键托盘图标，选择“打开日志目录”。日志可能包含工作区路径和运行信息，公开日志前请先检查敏感内容。

构建

重新生成应用图标
npm run icon

同时构建 NSIS 安装包和 Portable 版本
npm run dist

只构建 Portable 版本
npm run dist:portable

构建解包目录，适合本地调试
npm run dist:dir

构建产物位于 release/：

DeepSeek-Harness-Setup-.exe
DeepSeek-Harness-Portable-.exe
win-unpacked/

release/ 和 node_modules/ 已从 Git 中排除，不会提交到仓库。

冒烟验证

冒烟模式会启动 DSH、等待页面完成加载、输出 SMOKE_OK，然后自动退出：

$env:DSH_DESKTOP_SMOKE = "1"
npx electron .
$env:DSH_DESKTOP_SMOKE = $null

工作原理

flowchart LR
A["启动桌面应用"] --> B["解析工作区与 Node.js"]
B --> C["选择本地端口"]
C --> D["启动 dsh web 子进程"]
D --> E["等待服务就绪"]
E --> F["Electron 窗口加载 127.0.0.1"]
F --> G["关闭窗口时驻留托盘"]
G --> H["退出时清理进程树"]
外部 HTTP(S) 链接不会留在应用窗口内，而是交给系统默认浏览器打开。

常见问题

启动后提示“未找到 dsh CLI”

确认依赖安装完整，然后重新安装：

Remove-Item -Recurse -Force node_modules
npm install

DSH 服务启动超时

从托盘菜单打开日志目录，检查 dsh-desktop.log 中最近的错误。也可以设置 DSH_DESKTOP_PORT，排除本机安全软件或端口策略的影响。

点击关闭按钮后应用仍在运行

这是预期行为。关闭窗口会隐藏到系统托盘；如需完全退出，请在托盘菜单中选择“退出”。

参与贡献

欢迎提交 Issue 和 Pull Request。提交改动前请至少运行一次冒烟验证；涉及打包配置时，也建议执行 npm run dist:dir。

许可证

本项目采用 MIT License。DeepSeek Harness 及其他依赖分别遵循各自的许可证。