DeepSeek Harness 桌面版

把 dsh web 包成一个能双击启动的 Windows 桌面应用，不用每次开终端敲 npx @deepseek-ai/dsh web。

A desktop shell for DeepSeek Harness. It spawns dsh web on an OS-assigned port, waits for the host to announce its URL on stdout, and loads it in an Electron window with a tray icon and clean process-tree shutdown. Workspaces are left entirely to the harness itself.

这是非官方的第三方外壳，与 DeepSeek 没有任何隶属或背书关系。 它不修改 harness，也不包含 harness 的任何代码。

它做什么，不做什么

外壳只负责一件事——管理 dsh web 主机进程的生命周期，和指向它的那个窗口：

• 用真实的 node.exe 拉起 dsh web --port 0，端口交给操作系统分配，所以重复启动不会撞端口
• 监听 stdout 上的 dsh web: http://… 一行来判断就绪，而不是盲等或轮询端口（实测冷启动约 1.1–1.5 秒）
• 就绪后加载窗口；退出时用 taskkill /T 收掉整棵进程树
• 启动失败时给出错误面板、主机输出尾部和重试按钮，而不是白屏
• 托盘菜单：显示窗口 / 重启 dsh web / 在浏览器中打开 / 打开日志目录 / 打开配置文件

它不管理工作区。 harness 自带工作区注册表（@deepseek-ai/dsh-workspace）：持久化、可排序、会话按工作区归类，UI 侧边栏还有目录选择器，Windows 上弹的是原生 IFileOpenDialog。所以外壳不锁定工作目录——换项目在 UI 里点就行，任意目录都可以。spawn 时的 cwd 只是首个会话的默认目录。

前置条件

• Windows 10/11
• Node.js ≥ 20
• @deepseek-ai/dsh 已全局安装：

npm i -g @deepseek-ai/dsh

外壳会按「配置指定 → npm 全局目录 → node 同级 node_modules → npx 缓存（取最新）」的顺序自行查找入口；找不到会在错误面板里直接给出安装命令。

安装

用安装包：从 Releases 下载 DeepSeek-Harness-Setup-*.exe。每用户安装，装到 %LOCALAPPDATA%\Programs\DeepSeek Harness，自动创建桌面和开始菜单快捷方式。安装包未做代码签名，Windows SmartScreen 可能拦一次。

从源码跑：

git clone https://github.com/<用户名>/dsh-desktop.git
cd dsh-desktop
npm install
npm run icon     # 生成 build/icon.ico，见下方「图标」
npm start

配置

%APPDATA%\DeepSeek Harness\config.json，首次启动自动生成：

日志在 %APPDATA%\DeepSeek Harness\logs\dsh-web.log（超过 5 MB 轮转一次）。托盘和「应用」菜单里都有日志目录与配置文件的入口。

安装 harness 插件

插件装在 profile（~\.dsh\profiles\web）里，不在本项目内，所以外壳无需任何改动：

dsh plugin --profile web add <包名>

dsh plugin 是 pnpm 的转发器：以 profile 目录为 cwd 执行 pnpm <参数>，成功后比对安装结果——凡是包清单声明了 dsh.bundle.patch 的依赖，自动追加进 package.json 的 dsh.profile.bundles 层列表。

关键：对账只在 pnpm 退出码为 0 时执行。 pnpm 一旦失败，包会留在 dependencies 里但不会进 bundles——看起来装上了，其实没挂载。带原生模块的插件在 pnpm 10+ 上第一次几乎必然失败（构建脚本默认被拦），所以正确顺序是：

# ① 先装。第一次可能报 ERR_PNPM_IGNORED_BUILDS 而失败，这是预期的
dsh plugin --profile web add <包名>

# ② pnpm 会往 ~\.dsh\profiles\web\pnpm-workspace.yaml 写一个 allowBuilds 存根，
#    把里面的待填项改成 true

# ③ 重跑，让 pnpm 干净退出以触发对账
dsh plugin --profile web install

先跑 pnpm approve-builds 再装是无效的——那时还没有包，只会得到「no packages awaiting approval」。

验证是否真的挂上：

(Get-Content ~\.dsh\profiles\web\package.json -Raw | ConvertFrom-Json).dsh.profile.bundles
dsh --profile web --dump-config      # 合成后的树里应出现该插件的行

装完在应用里：托盘或「应用」菜单 →「重启 dsh web」，再按 Ctrl+Shift+R 强制刷新前端。

图标

npm run icon 用 Electron 自己把 DeepSeek 官方鲸鱼渲染成 512px 母图，降采样后手工封装成 PNG-in-ICO（工具链本来就依赖 Chromium，不必为此引入 SVG 光栅化库）。

素材不随仓库分发，而是构建时从你本机已安装的 @deepseek-ai/dsh-web-frontend 现取。这样既不再分发别家的商标，也让图标始终与你装的 dsh 版本一致。想用自己的图，把任意 SVG 放到 build/whale.svg 即可覆盖。

npm run dist 会通过 predist 自动先跑一次 npm run icon。

两个不能改的地方

必须用真实 node.exe spawn，不能用 ELECTRON_RUN_AS_NODE。 Windows 上的原生目录选择器是 spawn(process.execPath, ['worker.cjs']) 去开 COM 的 IFileOpenDialog；如果 process.execPath 是 Electron，那个孙进程会启动第二个 Electron GUI 而不是对话框。childEnv() 因此会剥掉所有 ELECTRON_* 变量。

就绪判定读 stdout，不要探测端口。 端口是 --port 0 动态分配的，真实 URL 只有那一行日志知道。

已知情况

• 用普通 HTTP 客户端（curl / Invoke-WebRequest）直接请求会返回 502，包括不存在的路径。这是 harness 的浏览器信任栅栏在挡非浏览器客户端，不是外壳故障——排查请以窗口内的实际渲染为准，或用 dsh --profile web --dump-config。
• 原生目录选择器由主机子进程弹出，不属于 Electron 窗口，因此不是模态的，偶尔会出现在窗口后面。
• 安装包未签名。

开发与打包

npm start          # 直接运行
npm run icon       # 重新生成 build/icon.ico
npm run pack       # 只出 dist/win-unpacked，不打安装包
npm run dist       # 打包出 dist/DeepSeek-Harness-Setup-<版本>.exe

国内网络下建议给 Electron 二进制和打包工具链设镜像：

$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"

tools/capture-window.ps1 用 PrintWindow 抓取应用窗口自身的像素（不是屏幕区域截图，所以不会把挡在前面的其他窗口拍进去），验证界面时比 HTTP 探测可靠。

项目结构

src/main.js        主进程：进程生命周期、就绪探测、托盘、菜单、窗口状态
src/dsh-paths.js   定位本机安装的 dsh（主进程和图标脚本共用）
src/splash.html    启动/错误面板
src/preload.js     仅供启动面板；主窗口不挂 preload
tools/make-icon.js 由官方鲸鱼生成 icon.ico
tools/capture-window.ps1

许可与致谢

本项目以 MIT 许可发布，见 LICENSE。

DeepSeek Harness 由 DeepSeek 以 MIT 许可发布（Copyright © 2026 DeepSeek）。本项目不包含其代码。应用图标由其官方鲸鱼标识生成——该标识为 DeepSeek 所有，此处仅作标识用途，不构成任何隶属或背书关系。