deepseek-harness-desktop

DeepSeek Harness Desktop

为 DeepSeek Harness（DeepSeek 开源的可插拔 AI Agent harness）打造的桌面应用壳，把官方 dsh web 界面包装成原生质感、常驻后台的桌面应用，直接复用你已安装的 dsh 命令行工具。

English | 简体中文

特性

后端（dsh）集成

• 零侵入包装 — 以子进程方式运行你全局安装的 dsh CLI（node <dsh>/lib/bin.js web），加载其 localhost 界面；harness 源码零改动。终端与桌面端共用同一份 dsh——插件、设置、凭证、会话与版本永远一致（DSH_HOME，默认 ~/.dsh）
• 首次启动引导安装 — 未检测到 dsh？应用提供可复制的安装命令或壳内一键安装，装完自动进入
• 应用内更新 dsh — 设置 → 桌面显示当前 dsh 版本；一键检查 npm 最新版并升级，无需碰命令行

桌面体验

• 无边框沉浸窗口 — 无原生标题栏；自绘窗口控制按钮（最小化/最大化/关闭）以 DeepSeek 品牌蓝 hover 融入页面，并随明暗主题切换
• 托盘常驻 — 关闭窗口隐藏到系统托盘而非退出，后端持续运行，随时秒开
• 开机自启 — 托盘菜单一键开关（Windows/macOS 原生实现；Linux 走 XDG autostart）
• 端口策略可配 — 默认固定 3080（与 dsh web 一致，页面 origin 稳定，浏览器侧设置跨重启保留），设置页可改为自定义端口或随机；固定端口被占时自动降级随机并提示。注意：壳常驻托盘期间占用该端口，终端裸跑 dsh web 需带 --port 避让；从旧版本升级后页面侧设置（如会话宽度）需重设一次，之后跨重启保留
• 单实例 — 重复启动会聚焦已有窗口
• 插件自由不受限 — 动态插件（cordis_define/cordis_run）、$DSH_HOME/cordis.patch.yml、npm 插件生态均与 Web 版完全一致
• 设置页桌面分区 — 设置页新增「桌面」标签页（UI 契合 harness 设计）：dsh 版本卡片（检查并一键升级）、桌壳自身更新检查、开机自启开关、启动最小化开关、关于卡片，均与托盘菜单双向同步
• 桌壳自更新 — 启动 15 秒后静默检查：Windows 下载后引导运行安装包（未签名无法静默安装）；Linux AppImage 全自动替换；macOS 暂不支持（需签名）

界面预览

安装

前置条件

• Node.js ≥ 22 与 dsh CLI（npm i -g @deepseek-ai/dsh）——若未安装，应用会显示引导页，提供可复制命令或壳内一键安装

下载

从 Releases 下载对应平台的安装包：

平台	安装包	说明
Windows	deepseek-harness-desktop-<ver>-setup.exe	NSIS 安装包，x64
macOS	.dmg（Apple Silicon / Intel）	未签名 — 首次运行需右键 → 打开
Linux	.AppImage + .deb	x64

首次启动

1. 启动应用 — 自动定位你的 dsh CLI，后台启动 dsh web 服务，界面就绪后自动打开（未装 dsh 会先进入引导安装页）
2. 关闭「预览版」提示
3. 打开 设置 → 模型 配置你的 LLM 供应商（API Key、模型、Base URL），与 Web 版一致
4. 选择一个工作区，开始对话

日常使用

• 关闭窗口 → 应用隐藏到托盘（系统时钟附近出现 DeepSeek 鲸鱼图标），后端继续运行
• 托盘菜单（右键点击图标）：重新打开窗口、开关开机自启、退出 — 只有「退出」才会真正停止后端
• 只能通过托盘退出；关闭窗口永远不会退出应用

开发

npm install        # 安装 electron 43 及工具链
npm run dev        # dev 模式：系统 Node + 你全局安装的 dsh CLI

electron 二进制下载卡住？（一直显示 Downloading Electron binary...） GitHub 托管的二进制在某些网络下很慢。可手动下载 https://npmmirror.com/mirrors/electron/<版本>/electron-v<版本>-win32-x64.zip 放入 %LOCALAPPDATA%\electron\Cache\electron-v<版本>-win32-x64\，然后：

printf "electron.exe" > node_modules/electron/path.txt
# 并把 zip 解压到 node_modules/electron/dist/

打包

npm run build:runtime     # 从上游 favicon 生成 resources/icon.png（+ build/icon.png）
npm run dist:win          # Windows NSIS 安装包 → release/
# npm run dist:mac        # macOS dmg（需 macOS 环境；CI 负责构建）
# npm run dist:linux      # Linux AppImage + deb

CI 工作流（.github/workflows/release.yml）在每个 v* tag 上构建全平台产物并自动发布到 GitHub Release。

数据与日志

• 数据（DSH_HOME）：默认 ~/.dsh（尊重 $DSH_HOME 环境变量）— profile、会话、存储
• 日志：<userData>/logs/main.log
• dsh CLI：壳运行你全局安装的 dsh（通过 PATH + npm root -g 定位）；可在设置 → 桌面一键升级，或 npm i -g @deepseek-ai/dsh

项目结构

src/
  main.ts          应用生命周期：单实例锁、窗口、托盘、dsh 编排
  paths.ts         dev/prod 资源路径解析（图标、preload、桌面插件 patch）
  dsh-locator.ts   定位用户已装的 dsh CLI（PATH 验证 + npm root -g）+ semver 比较
  dsh-updater.ts   设置页后端卡片：检查 npm 最新版 / 一键 npm i -g 升级
  settings.ts      壳设置（userData/settings.json — 启动最小化、监听端口策略）
  updater.ts       electron-updater（Windows 引导 / Linux AppImage 全自动）
  dsh/spawn.ts     spawn dsh web --port <策略端口> --patch，解析 stdout URL 行，优雅停止
  dsh/ready.ts     HTTP 就绪探测
  tray.ts          托盘菜单（打开 / 开机自启 / 退出）+ 自启勾选同步
  autostart.ts     开机自启（win/mac 原生 + linux XDG 文件）
  preload.ts       contextBridge 桥（窗口控制 + 桌面 IPC；编译为 CJS）
scripts/
  install-runtime.mjs  构建时填充 resources/（Node + dsh 树 + 图标 + 平台裁剪）
  smoke.mjs            无 GUI 冒烟：spawn dsh，断言 URL 行 + HTTP 200
resources/
  desktop-integration/ 设置页「桌面」分区插件（dsh 浏览器 half）
  desktop-patch.yml    壳注入的 patch（挂载该插件）
assets/
  wordmark.svg         项目标识

已知限制（v1）

• 需要 Node.js ≥ 22 与全局安装的 dsh CLI（引导页提供一键安装）；壳不再内置运行时——安装包很小，但 dsh 本身必须存在
• macOS 构建未签名 — Gatekeeper 首次运行需右键 → 打开；macOS 暂不支持自动更新（需签名证书）
• Windows 自动更新为引导模式（下载后运行安装包）而非静默安装，源于未签名构建

反馈

发现 Bug？有功能想法？非常欢迎提交 issue — 问题报告、使用疑问、功能建议都行。

• 新建 issue（中文或 English 均可）
• harness 本身的问题，可同步查阅上游 deepseek-harness discussions

许可

MIT。DeepSeek Harness 本体为 MIT © DeepSeek AI。