DeepSeek Harness 桌面版 (Desktop)

⚠️ 社区项目,非官方出品:本项目是第三方社区开发的桌面外壳, 与 DeepSeek 公司无隶属关系。DeepSeek Harness 本体、@deepseek-ai/* 软件包 及官方前端版权归 deepseek-ai 及其贡献者所有, 详见其 MIT 许可。

将 DeepSeek Harness 官方网页版 一比一 复刻为 Windows 桌面应用。

UI 与网页版像素级一致:桌面版直接加载官方 dsh web 服务器与官方前端 (@deepseek-ai/dsh + @deepseek-ai/dsh-web-frontend 构建产物),未对界面做任何改动; Electron 只提供原生桌面外壳:窗口、托盘、菜单、服务器托管。

特性

• 零配置,双击即用:安装包自带 Electron 运行时(内嵌 Node)与完整依赖树, 用户无需安装 Node.js 或任何环境;应用自动托管官方 dsh 服务器
• 一比一 UI:与浏览器版完全相同的界面与交互(同一个前端,同一个服务器)
• 启动动画:白/蓝光点构成的官方鲸鱼(呼吸动画)加载页,启动与恢复时展示
• 智能复用:若 127.0.0.1:3080 已有官方服务器在运行(例如浏览器版), 桌面版直接复用,不重复启动
• 掉线自动恢复:运行期间每 5 秒探活;复用的外部服务器被关闭时, 自动自建接管并重载页面(不再出现"UI 还在但发不了消息")
• 自动回退 npx:内置服务器缺失或启动失败时,自动执行 npx -y @deepseek-ai/dsh web —— 用户手动跑 npx 那一步由应用代劳
• 崩溃自动重启:托管的服务器意外退出时自动拉起并恢复页面(静默完成)
• 系统托盘:关闭窗口后驻留托盘,随时恢复;托盘菜单可打开浏览器、关于、退出
• 纯净窗口:无菜单栏;快捷键保留 Ctrl+Shift+I 开发者工具 / Ctrl+R 重载 / Ctrl+Shift+O 在浏览器中打开
• 单实例:重复启动只会聚焦已有窗口
• 窗口状态记忆:记住上次窗口位置与大小
• 会话数据共享:与 CLI / 浏览器版共用同一 ~/.dsh 数据目录

快速开始

最终用户无需 Node.js:直接安装 Release 里的安装包即可,双击即用。 以下步骤仅从源码开发时需要。

npm install        # 安装依赖(含 electron 与官方 dsh)
npm run icon       # 由官方 favicon.svg 生成应用图标(仅首次需要)
npm start          # 启动桌面应用

启动后:

1. 应用会先探测 127.0.0.1:3080 是否已有官方 dsh 服务器(有则复用);
2. 否则自动托管一个内置服务器(3080 被占用时自动改选空闲端口);
3. 官方 UI 在一个原生窗口中打开 —— 与网页版完全一致。

冒烟测试

npm run smoke                 # 复用模式:探测/复用 127.0.0.1:3080 上的官方服务器
npm run smoke -- --port 0     # 自建模式:强制启动一个内置服务器(系统分配端口)

自动启动、加载页面、校验 window.__DSH_BOOT__ 注入与页面标题,然后退出 (退出码 0 = 通过,1 = 校验失败,2 = 超时,9 = 被单实例锁拒绝)。结果同时写入 userData/smoke-result.json,供自动化读取。--port N 可强制自建服务器到 指定端口并跳过复用逻辑(0 = 系统分配),也适用于正常启动: npm start -- --port 0。

打包发行

npm run dist

流程:electron-packager(原样复制 node_modules,含嵌套依赖结构)→ electron-builder --prepackaged(生成安装包)。输出到 release/:

• DeepSeek Harness-0.1.0-x64.exe —— NSIS 安装包(可选安装目录、桌面/开始菜单快捷方式)
• DeepSeek Harness-0.1.0-portable-x64.exe —— 免安装便携版(首次启动需解压,较慢)

为什么不用 electron-builder 直接打包:其 node-modules 智能收集器会 丢弃 peerDependencies(官方 dsh 大量使用 peer 依赖,如 @deepseek-ai/cordis-plugin-group 等 90+ 个包),导致打包产物缺模块。 本项目已把全部 peer 依赖显式声明在 package.json 的 dependencies 中, 并用 electron-packager 原样复制依赖树,保证运行时自包含。

更新官方 dsh

官方发新版后,两种方式跟上:

自动感知(已配置):

• Dependabot 每周扫描 @deepseek-ai/*(含 dsh 本体), 官方一发新版就自动开聚合升级 PR;
• CI 对每个 PR 跑 Windows 冒烟(装依赖 → 语法检查 → 内置服务器起真服务加载官方 UI 校验 __DSH_BOOT__),绿了再合并。

一键升级出包:

npm run update:dsh              # 查最新版 → 对齐全部 dsh-* 依赖 → 安装 → 冒烟 → 出包
npm run update:dsh -- --dry-run # 只预览版本改动
npm run update:dsh -- --force   # 版本未变时强制重跑冒烟+出包

脚本只对齐 dsh monorepo 家族(@deepseek-ai/dsh 精确锁定,@deepseek-ai/dsh-* 用 ^ 对齐到同一版本,避免同仓版本错位);cordis / cordis-plugin-* / schemastery 是独立版本线的库,交给 Dependabot 单独升级。冒烟不通过会中止,不会出坏包。 完成后照脚本末尾提示 commit + 发 Release 即可。

配置

设置保存在 Electron userData 目录的 settings.json:

键	默认	说明
closeToTray	true	关闭窗口时最小化到托盘
workspace	用户主目录	内置服务器的模型工作目录(agent 的 cwd)

也可通过环境变量 DSH_WORKSPACE 指定工作目录。

目录结构

├── src/
│   ├── main.js          # Electron 主进程:服务器托管、窗口、托盘、单实例、快捷键
│   ├── preload.js       # 只读桌面环境信息(window.dshDesktop),不干预页面
│   └── status-page.js   # 鲸鱼光点加载动画页(纯 canvas,无图片资源)
├── scripts/
│   ├── make-icon.js           # 由官方 favicon.svg 生成 icon.png / tray.png
│   ├── scan-deps-bounded.js   # 打包产物依赖完整性体检(诊断工具)
│   └── update-dsh.js          # 一键升级官方 dsh 并重新出包
├── assets/            # 生成的图标
└── package.json

工作原理

• 服务器:spawn(process.execPath, [dsh/lib/bin.js, "web", "--host", "127.0.0.1", "--port", N]) 并以 ELECTRON_RUN_AS_NODE=1 让 Electron 充当 Node 运行时 —— 打包后无需用户另装 Node; 打包布局无 asar(resources/app/),服务器子进程全部从真实磁盘加载;
• 就绪检测:解析服务器 stdout 的 dsh web: http://127.0.0.1:PORT 行, 并对该地址轮询直到返回官方首页;
• 原生模块(node-pty / koffi)使用随包预编译产物(为 Node ABI 构建, 恰好匹配 ELECTRON_RUN_AS_NODE 运行时);
• 远程桌面/无 GPU 环境:主进程已调用 app.disableHardwareAcceleration(), 规避 Chromium 硬件加速路径的偶发 fail-fast 崩溃;
• 复用模式:应用退出时不会关闭外部服务器;托管模式:退出时随应用关闭。

常见问题

• npm 11 的 allow-scripts 策略拦截安装脚本:若 npm install 后提示 install scripts not yet covered by allowScripts,执行 npm approve-scripts koffi @deepseek-ai/dsh-subprocess-local, 并确认 node_modules/@koromix/koffi-win32-x64/win32_x64/koffi.node 存在 (缺失时用 npm install @koromix/koffi-win32-x64@3.1.4 --no-save 补装)。
• 打包后启动报 "找不到 dsh 服务器入口":确认安装包由 npm run dist 生成(带 peer 依赖补全的完整依赖树);resolveDshBin 兼容有/无 asar 两种布局。

许可

本项目以 MIT 协议开源。DeepSeek Harness 本体、@deepseek-ai/* 软件包及官方前端版权归 DeepSeek 及其贡献者所有。