桌面启动器 Yuan-x-303/dsh-desktop

DSH Desktop

DeepSeek Harness 的一键桌面启动器。它在原生窗口中启动 Harness Web UI，零配置——最终用户无需安装 Node.js 或任何其他东西。

- 零依赖：内置便携式 Node.js 运行时，因此 dsh web 开箱即用。
- 便携且可安装：可分发单个 .exe（便携版）或按用户安装的安装程序（NSIS）。
- 自动端口：传入 --port 0 并从 stdout 解析真实 URL——不会发生端口冲突。
- 仅限回环：强制使用 --host 127.0.0.1，因此 Harness 服务器绝不会暴露到局域网。
- 单实例：再次启动会聚焦到已有窗口。
- 干净的生命周期：关闭窗口会停止 dsh 及其子进程；如果 dsh 崩溃，应用也会关闭。
- 加固的渲染器：窗口拒绝所有浏览器权限请求（摄像头、地理位置、MIDI……），并且只允许 harness 源进行导航。
- 友好的启动体验：在 dsh 启动期间显示加载屏幕；失败时显示捕获的日志。

安装

从本仓库的 Releases 页面下载最新版本：

- DSH-Desktop--setup.exe —— 安装程序（按用户安装，无需管理员权限）。
- DSH-Desktop--portable.exe —— 便携版，无需安装。

首次运行时 Windows SmartScreen 可能会发出警告，因为二进制文件尚未进行代码签名；点击 更多信息 → 仍要运行。

开发

要求：Node.js ≥ 20（已在 v24 上验证）。基于 @deepseek-ai/dsh 0.1.5-rc.2 构建。

npm install
npm start # compiles TS and launches Electron

构建安装程序

npm run dist # compile + electron-builder --win

构建产物位于 release/。首次构建会下载便携式 Node 运行时（一次，缓存在 resources/runtime/node.exe）以及 electron-builder 的 NSIS 工具。

当 DSH Desktop 正从 release\win-unpacked 运行时，npm run dist 会拒绝执行（构建会清空该目录，而正在运行的应用会锁定其文件）。请先关闭应用，或者如果你清楚自己在做什么，设置 SKIP_GUARD=1。

配置

启动器会读取 config.json（可选）。查找顺序如下：

1. /config.json —— 仅开发环境。
2. %APPDATA%\dsh-desktop\config.json —— 打包构建以及共享的用户级覆盖配置（在这里可以将已安装/便携版构建指向你现有的工作区和 DSH 数据）。
3. ./config.json（进程工作目录）。

参见 config.example.json：

{
"workspace": "C:\\Users\\\\dsh-workspace",
"home": "C:\\Users\\\\.dsh"
}

| 字段 | 含义 | 默认值 |
| workspace | Harness 工作区根目录（agent 文件 I/O） | ~/dsh-workspace |
| home | Harness 数据目录（设置、密钥、会话） | ~/.dsh |
优先级：config.json → 环境变量 → 默认值。

环境变量：

| 变量 | 用途 | 默认值 |
| DSH_WORKSPACE | 工作区根目录（config.json 优先） | ~/dsh-workspace |
| DSH_HOME | Harness 数据目录（config.json 优先） | ~/.dsh |
| DSH_DESKTOP_NODE | 覆盖用于运行 dsh 的 node 可执行文件 | Electron 的 Node |

与官方 DeepSeek Harness 的互操作（会话数据位置）

会话是配置的 home 下的普通文件：

\sessions\\session-\session.jsonl.zstd

任何 dsh 实例——本应用内置的实例或官方的 dsh web CLI——只要指向相同的 home，就会读取相同的文件。默认情况下一切都已经对齐：

- 本应用默认 home = ~/.dsh 和 workspace = ~/dsh-workspace——与官方 CLI 的默认值完全相同。因此开箱即用，在这里和在官方 Web UI 中创建的会话就是相同的文件，并且可以互操作（home 中的设置和 API 密钥也是共享的）。
- 侧边栏按工作区分组会话；同一 home 中的不同工作区都会列出（每个作为独立的分组）。新会话会落在当前工作区中。
- 工作区注册表（\storages\workspace.json）会在启动时从会话文件夹重建，因此由另一个实例创建的会话会在重启后出现——不存在实时的跨进程同步。

有两件事会破坏这种共享视图，而它们通常都是“我的会话消失了”的原因：

1. 不同的 home：如果你为本应用创建了 %APPDATA%\dsh-desktop\config.json（或设置了 DSH_HOME），但在启动官方 CLI 时没有使用相同的设置，那么每个入口点读取的就是不同的文件夹。要共享，请使用相同的 home/workspace 启动官方 CLI，例如在 PowerShell 中： $env:DSH_HOME='E:\somewhere\.dsh'; $env:DSH_WORKSPACE='E:\somewhere\workspace'; dsh web

2. 同时运行两者：每个实例都会向同一个会话日志文件（zstd 帧）追加内容，且没有跨进程锁。两个实例同时写入一个 home 可能会撕裂或损坏会话日志。请一次只使用一个入口点（端口永远不会冲突——本应用使用随机端口，官方 CLI 使用 3080）。

版本固定：本应用捆绑了特定版本的 @deepseek-ai/dsh（参见 package.json）。会话日志带有格式版本；如果官方 harness 发布了更新的会话格式，本应用会拒绝打开这些会话，直到捆绑的 harness 被升级（参见升级）。

管理插件

本应用运行标准的 web 配置文件，插件会安装到共享数据目录中的该配置文件里——也就是所有其他 dsh 入口点读取的同一位置。使用默认的 home（~/.dsh）时：

~/.dsh/profiles/web/
├── package.json ← 插件依赖项放在这里 ├── cordis.patch.yml ← 你自己的插件配置层 └── node_modules/ ← pnpm 安装插件的位置

你在这里安装的任何内容都会被此应用、官方 CLI，或任何其他指向同一 home 的 dsh 实例识别——无需额外步骤。

要安装插件，你的 PATH 中需要有 Node.js 和 pnpm（应用本身不捆绑它们）。在终端中：

pnpm 本身未捆绑——安装一次即可（需要 Node.js）：
corepack enable pnpm # 或者：npm install -g pnpm

让 dsh 指向应用使用的同一 home，然后管理 web 配置文件：
dsh plugin --profile web add
dsh plugin --profile web remove
dsh plugin --profile web list

注意事项：

- dsh plugin 是一个轻量转发器：它在配置文件目录中运行 pnpm ，并在之后协调配置文件清单。如果你的 home 不是默认值，请先导出它，例如 DSH_HOME=C:\path\.dsh。
- 应用首次启动时已为你创建了配置文件；如果它还不存在，请先运行一次 dsh web（或直接启动应用）再管理插件。
- 插件配置（与安装相对）放入配置文件的 cordis.patch.yml（或用于全局补丁的 $DSH_HOME/cordis.patch.yml）。

工作原理

start.bat（仅开发用） └─ electron . 主进程 ├─ spawn dsh web --host 127.0.0.1 --port 0 （打包构建中使用捆绑的 Node） ├─ 解析 stdout："dsh web: http://127.0.0.1:PORT"（严格的回环/端口验证） ├─ 在 dsh 启动时显示加载屏幕 └─ 在该 URL 打开 BrowserWindow（+ ?dsh-desktop-platform=win32）
- 外部链接转到系统浏览器
- 所有浏览器权限请求均被拒绝

node_modules 以未打包形式发布（asar: false），以便捆绑的 Node 能将 @deepseek-ai/dsh 作为普通文件读取。原生模块不会为 Electron 重新构建，因为 dsh 运行在捆绑的 Node 下，而非 Electron 内部。

项目结构

src/electron/main.ts 窗口 + 生命周期 + 导航守卫 + 权限加固 src/electron/dsh.ts 启动 dsh + 解析捆绑的 Node / dsh bin + 严格的就绪解析器 scripts/fetch-node.mjs 下载便携式 Node 运行时 scripts/generate-icon.mjs 重新生成默认的 build/icon.png 和 build/icon.ico scripts/import-icon.mjs 从 build/icon-source.jpg 导入自定义图标 scripts/guard-dist.mjs predist 守卫：应用运行时拒绝打包 build/installer.nsh NSIS 包含：用新的 exe 图标重建快捷方式 electron-builder.yml 打包配置（NSIS + 便携版） config.example.json 配置模板

故障排除

- 首次运行时出现 Windows SmartScreen 警告——二进制文件尚未进行代码签名；点击 更多信息 → 仍要运行。
- 首次启动较慢——首次启动会在以下位置安装配置文件的插件： $DSH_HOME/profiles；后续启动会很快。
- 安装插件时提示“pnpm not found on PATH” —— 按设计，应用不捆绑用于插件管理的 pnpm/Node；请安装 Node.js 并运行 corepack enable pnpm（或 npm install -g pnpm），然后重试 —— 参见管理插件。
- 我的数据在哪里？ —— 会话/设置位于配置的 home （默认 ~/.dsh）下，工作区文件位于 workspace（默认 ~/dsh-workspace）下。
这位于安装文件夹之外：卸载或重新安装应用不会删除你的数据。若要在多台机器之间（或在重新安装 Windows 之后）保留会话，请备份 ~/.dsh 和 ~/dsh-workspace。
- 我昨天的会话不见了 —— 会话文件从未被删除；应用很可能读取的是与之前不同的 home。请检查 %APPDATA%\dsh-desktop\config.json：如果它设置了 home，应用只会读取该 home 下的会话。在不存在配置时写入的会话位于默认的 ~/.dsh 下。将 home 指回原处（或复制会话文件夹）即可再次看到它们 —— 参见与官方 DeepSeek Harness 的互操作。
- 不要同时运行此应用和官方 dsh web —— 两者都会在没有锁的情况下追加到相同的会话日志文件；并发使用可能会损坏会话。打开其中一个之前请先关闭另一个。
- npm run dist 拒绝运行 —— DSH Desktop 仍在从 release\win-unpacked 运行；请先关闭它（参见构建部分）。
- 升级后，开始菜单/桌面快捷方式显示的是过期的图标（与安装文件夹中的 exe 不同）—— electron-builder 的升级路径会重命名旧的 .lnk，而不是重新创建它，而且 Windows 还会缓存图标。自 v0.2.1 起，安装程序（build/installer.nsh）会在每次安装时使用新安装的 exe 的图标重新创建这两个快捷方式。如果你仍然看到过期的图标，那是 Windows 图标缓存的问题：右键单击桌面 → 刷新，或重启资源管理器（任务管理器 → Windows 资源管理器 → 重新启动），或用 ie4uinit.exe -show 清除缓存。全新安装从不会受影响 —— 只有已存在并经过升级的安装才会。

升级 DeepSeek Harness

桌面外壳只是一个轻量封装；所有功能都来自捆绑的 @deepseek-ai/dsh 包，它不会自动更新。当新的 Harness 版本发布时，请手动升级：

1. 在 package.json 中的每个 @deepseek-ai/dsh 条目上设置新版本（它们必须一起更新 —— 混合版本树会解析失败，因为上游对等依赖范围通常要求最新的补丁版本）： "@deepseek-ai/dsh": "0.1.5-rc.2"

不要动 @deepseek-ai/cordis-plugin-group；它独立进行版本管理。
2. npm install
3. npm run dist
4. npm run check:deps —— dsh 生态系统将许多插件声明为 peerDependencies，而 electron-builder 不会打包它们。此脚本比较开发版和打包后的 @deepseek-ai 目录树，并打印任何缺失的包（及其确切版本）以及一段可粘贴到 package.json 的 dependencies 中的 JSON 片段。它会读取 release/win-unpacked，因此必须在
npm run dist 之后运行——如果该目录树不存在，它会中止并给出提示。
反复运行 npm install && npm run dist && npm run check:deps，直到它报告
没有缺失为止。
5. 对 release\win-unpacked\DSH Desktop.exe 进行冒烟测试。
6. 提升应用版本，然后执行 git tag vX.Y.Z && git push origin --tags。

package.json 的 dependencies 中显式的 @deepseek-ai/ 条目之所以存在，正是因为第 4 步——它们是启动器必须声明的 peer 依赖，以便 electron-builder 将它们包含进来。升级时请保留它们。

allowScripts 有意固定到版本。 npm ≥ 11 会暂缓执行生命周期脚本，直到每个包被批准，而 package.json 的 allowScripts 会以确切版本为键记录这些批准（koffi@3.2.1）。当这些包之一升级时，其键不再匹配，脚本会被悄悄跳过——npm 只会发出警告。原生二进制文件通常仍会通过可选的平台依赖（@koromix/koffi-win32-x64）以预构建形式提供，所以这并不致命，但如果未来的构建出现异常，请先检查 npm approve-scripts --allow-scripts-pending。
该列表是本地策略，不会记录在 package-lock.json 中，因此 CI 的 npm ci 不会因为它而失败。

会话格式兼容性：会话日志带有格式版本。如果较新的上游 Harness 提升了该版本，较旧的构建将拒绝打开新日志（反之亦然）。请在它落后之前升级捆绑包——一个已安装的应用如果其捆绑的 Harness 较旧，会将你的较新会话显示为不可读，而不是已删除。

自定义应用图标

应用图标是 build/icon.ico（Windows exe/任务栏）和 build/icon.png （512px，被图标流水线用作基础）。有两种更改方式：

1. 从图像文件（推荐）：将一张具有纯色近白背景的图片（例如白色背景上的吉祥物 JPEG）放到 build/icon-source.jpg，然后运行：

npm run icon:import # 默认使用 build/icon-source.jpg
npm run icon:import path\to\my.png # 或指向任意文件

该脚本会从图像边缘对近白背景进行泛洪填充（保留主体内部的白色区域），对边界进行羽化，去除白色光晕，并写入全新的 build/icon.png + build/icon.ico 以及一张位于仓库根目录的棋盘格 icon-preview.png，以便你肉眼检查抠图效果。
源文件保持不变。

2. 从头开始：npm run icon 会重新生成默认的终端提示符图标（这会覆盖任何自定义图标——只有在你想要恢复默认图标时才运行它）。

然后重新构建安装程序（npm run dist）——exe 和快捷方式会自动采用新图标。

自动更新

已安装的构建会在启动时检查更新（便携版构建无法自我更新）。新版本通过 electron-updater 从 GitHub Releases 提供。

要进行配置：

1. 创建一个 GitHub 仓库并推送此项目。
2. 在 electron-builder.yml 中，将 publish.owner（当前为 YOUR_GITHUB_USERNAME）替换为你的 GitHub 用户名。
3. 推送一个版本标签——git tag v0.3.0 && git push origin --tags——发布工作流会构建并将安装程序 + latest.yml + blockmap 发布到 GitHub Releases。
4. 如果发布被创建为草稿，请在发布页面上点击 Publish，以便已安装的应用能够看到它。

最终用户随后会自动收到“重启以更新”的提示；无需重新下载。注意：二进制文件尚未进行代码签名，因此防病毒软件可能会像对待初始安装程序一样，将下载的更新标记为可疑。

贡献

欢迎提交 PR。根据需要，使用 npm run icon 和 npm run fetch:node 重新生成资源；不要提交 release/ 或 resources/runtime/。

许可证

MIT。本项目是一个社区启动器，与 DeepSeek 无关联，也未获得其认可。