DeepSeek Harness Desktop (dsh-desktop)

August 18, 2026 · View on GitHub

DeepSeek Harness（dsh）的 Electron 桌面封装：双击即打开一个独立的桌面应用窗口，自带独立后端（应用启动时拉起属于它自己的 dsh Web 服务，关闭时停止）。跨平台：Windows 10/11、Linux、macOS。

功能

🚀 一键启动：打开应用即拉起属于应用自己的 dsh Web 服务（独立后端，不与他人共享）
⚡ 秒开体验：窗口立即弹出并显示启动动画（蓝底白鲸鱼），服务就绪后以 100ms 粒度探活并载入 Web UI
🧹 干净退出：关闭窗口自动停止自己的服务，不残留后台进程
🔒 单实例：重复打开只聚焦已有窗口，不会起第二个服务
🐋 官方鲸鱼图标：窗口/任务栏/启动画面统一使用 DSH 鲸鱼 logo（Windows 用 icon.ico，Linux/macOS 用 assets/icon-256.png）

独立后端（不与他人共享）

桌面版启动时总是启动自己的 dsh 服务实例：

独立端口：DSH_PORT（本机建议设 3081 等不与常用端口冲突的值）
独立数据目录：DSH_HOME（Linux 默认 ~/.dsh-home），会话/配置/凭据与其它实例互不干扰
若 DSH_PORT 已被别的进程占用，应用会弹窗报错并退出，不会蹭用/接管他人的后端
关闭窗口即停止自己拉起的服务；网页端（如果在跑）完全不受影响

想与网页端共用同一份会话数据？把 DSH_HOME 指向网页端用的数据目录即可（如 /path/to/deepseek-harness/work/dsh-home）。

要求

一个受支持的桌面操作系统：Windows 10/11、Linux（X11/Wayland）、macOS
DeepSeek Harness 已克隆并完成构建（pnpm install && pnpm run build）
Node.js（>= 22.19）用于运行应用内启动的服务

安装与使用

Windows

git clone https://github.com/<your-name>/dsh-desktop.git
cd dsh-desktop
pnpm add -D electron   # 或 npm install -D electron
node node_modules/electron/install.js   # 若 postinstall 被跳过（pnpm strictDepBuilds）
pnpm start             # 或直接运行 node_modules/electron/dist/electron.exe .

国内网络下载 Electron 二进制失败时，可加镜像： ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js

Linux

git clone https://github.com/<your-name>/dsh-desktop.git
cd dsh-desktop
pnpm add -D electron        # Linux 会下载 Electron 的 linux-x64 二进制
pnpm start                  # 或 ./scripts/start-linux.sh

一键安装桌面入口（应用菜单图标 + 可选 ~/.local/bin/dsh-desktop 命令）：

./scripts/install-linux.sh -d /path/to/deepseek-harness

说明：

start-linux.sh 在 Chromium 沙箱不可用的发行版上（较老内核、受限 AppArmor 等）会自动用 --no-sandbox 重试；也可手动指定： DSH_ELECTRON_ARGS="--no-sandbox" ./scripts/start-linux.sh
若要卸载桌面入口：rm ~/.local/share/applications/dsh-desktop.desktop ~/.local/share/icons/hicolor/256x256/apps/dsh-desktop.png

配置

路径解析优先级：环境变量 > config.json > 平台默认值。config.json 与本仓库同目录、机器相关（已在 .gitignore 中，不入库），模板见 config.example.json。

环境变量	Windows 默认值	Linux/macOS 默认值	说明
`DSH_HARNESS_DIR`	`E:\deepseek-harness`	`~/deepseek-harness`（自动探测：仓库同级目录、`~/inference-lab/` 下的同名目录）	dsh 源码仓库路径
`DSH_NODE_EXE`	`E:\nodejs\node.exe`	`node`（按 PATH 解析）	Node.js 可执行文件路径
`DSH_HOME`	`E:\dsh-home`	`~/.dsh-home`	dsh 数据目录（profiles/会话/凭据）
`DSH_PORT`	`3080`	`3080`	独立后端的 Web UI 端口（建议设为不冲突的值，如 `3081`）

例如 Linux 上使用本机已构建的 harness：

# config.json
{ "DSH_HARNESS_DIR": "/home/you/inference-lab/deepseek-harness" }

# 或环境变量（一次性）
DSH_HARNESS_DIR=/home/you/inference-lab/deepseek-harness pnpm start

Windows 下设置：setx DSH_HARNESS_DIR "D:\your\harness"（新终端生效）。

服务日志写入 $DSH_HOME/desktop-server.log（Windows 为 %DSH_HOME%\desktop-server.log）。

提示：若 DSH_HARNESS_DIR 中没有 apps/cli/lib/bin.js，说明 harness 尚未构建，请先进入该目录执行 pnpm install && pnpm run build。

Linux 适配说明

本项目原为 Windows 专用（写死 E:\ 盘符路径、.exe、ICO 图标），现已支持 Linux/macOS。所有 Linux 专门适配在代码里统一以 [Linux 适配] 注释标注，可用 grep -rn '\[Linux 适配\]' . 快速定位。

适配点	位置	说明
POSIX 默认路径	`config.js`	不再写死盘符，默认 `~/deepseek-harness`、`~/.dsh-home`，node 走 PATH
harness 自动探测	`config.js`	优先显式配置，未配置时自动探测仓库并列目录、`~/inference-lab/` 下的同名目录
node 绝对路径兜底	`config.js`	桌面会话 PATH 常不含 node，探测 `/usr/bin/node`、nvm 等常见位置
子进程 PATH 补全	`main.js`	启动服务时把 node 目录 + harness 的 `node_modules/.bin` 并入 PATH，否则桌面环境下子进程找不到 node/npm/tsx
窗口图标 PNG	`main.js`	Linux 下 Electron 不接受 ICO，改用 `assets/icon-256.png`
Windows 专属 API 守卫	`main.js`	`setAppUserModelId`、`windowsHide` 仅在 `process.platform === 'win32'` 时生效
原生二进制启动	`scripts/start-linux.sh`	直接调用 `dist/electron`（ELF），不经过需要 node 的 `node_modules/.bin/electron` shim——桌面会话没有 node 时后者会静默失败
沙箱检测与回退	`scripts/start-linux.sh`	SUID `chrome-sandbox` 不可用时（较老内核/受限 AppArmor）自动 `--no-sandbox` 一步启动
桌面入口安装	`scripts/install-linux.sh`	生成 `config.json`、安装 `.desktop` 菜单项与 hicolor 图标、可选软链 `~/.local/bin/dsh-desktop`
Linux 安装指引	`README.md`	「安装与使用 → Linux」小节

原 Windows 行为（E 盘默认路径、ICO 图标、setAppUserModelId 等）保持不动，仅以 process.platform 分支区分。

项目结构

dsh-desktop/
├── main.js              # Electron 主进程（服务生命周期 + 窗口管理，跨平台）
├── config.js            # 跨平台配置解析（env > config.json > 平台默认值）
├── config.example.json  # 机器相关配置模板（复制为 config.json 使用）
├── splash.html          # 启动加载动画页面（内联鲸鱼 SVG，单文件自包含）
├── icon.ico             # Windows 图标（黑鲸鱼，13 档尺寸）
├── assets/              # 鲸鱼图标各尺寸 PNG（Linux/macOS 窗口图标用 icon-256.png）
├── make-icon.js         # 图标生成脚本（读取 assets/ 生成 icon.ico，纯 Node，无依赖）
├── scripts/
│   ├── start-linux.sh   # Linux 启动入口（含 no-sandbox 自动回退）
│   └── install-linux.sh # Linux 桌面入口安装脚本
└── package.json

说明

这是 dsh 的外部启动器，不是 dsh 插件（dsh 插件指注册进 Cordis 插件树的 bundle）。它管理 dsh 服务的启停并提供桌面窗口体验。
服务以构建产物启动（apps/cli/lib/bin.js web），比 tsx 源码模式快 2~3 倍；若仓库未构建，请先运行 pnpm run build。

License

MIT