桌面启动器 kimirong/deepseek-harness-desktop

DeepSeek Harness Desktop

一个极简、本地优先的桌面外壳，用于 DeepSeek Harness。

简体中文 · English

DeepSeek Harness Desktop 将 DeepSeek Harness Web 体验封装为独立桌面应用：自动探测本机服务、一键启动、退出时清理——无需手动操作 CLI 或管理端口。

本项目专注于桌面宿主能力，不 fork、不修改、不注入，也不重新实现 Harness UI。模型、会话、设置、插件和 Agent 能力均由本机安装的官方 @deepseek-ai/dsh 提供。

[!IMPORTANT]
本项目是非官方社区封装，早期版本。安装包未签名、未公证（macOS 首次打开需在「系统设置 → 隐私与安全性」中允许）。Windows 版本尚未在真机验证，暂未发布。

下载

| 平台 | 架构 | 安装包 | 下载 |
| macOS | Apple Silicon | DMG | 下载 arm64 版本 |
| Windows | x64 | — | 未验证、未发布（见已知限制） |

全部当前和历史安装包可在 GitHub Releases 查看。

为什么需要桌面版

DeepSeek Harness 已经提供完整的 Agent Runtime 和 Web UI。本项目不重复实现这些能力，而是补充桌面应用所需的宿主层：

- 自动探测本机已有的 Harness 服务并直接连接
- 没有实例时自动启动（或一键启动）dsh web，使用随机回环端口
- 等待服务就绪后再进入界面，启动失败不弹窗、可重试
- 应用退出时自动终止自启的子进程，不留孤儿进程

主要特性

- 自动连接已运行的 Harness 实例，不重复启动服务
- 启动器页面覆盖全部"服务未运行"场景：一键启动、进度提示、错误重试、配置指引
- 服务仅监听随机本地回环端口，不暴露到局域网
- 渲染进程启用沙箱、contextIsolation，禁用 Node.js 集成
- 连接已有实例时为只读连接，不接管其生命周期
- 打包时裁剪 Electron 语言包，安装包 103MB

界面预览

使用流程（打开应用 → 一键启动 → 进入界面）：

| 步骤 | 界面 | 说明 |
| 1. 检测 | 未检测到服务 | 打开应用，未检测到本机服务：显示「一键启动服务」按钮 |
| 2. 启动 | 正在启动服务 | 点击后启动 dsh web（随机回环端口），显示进度 |
| 3. 就绪 | 服务已就绪 | ✓ 服务已就绪，即将打开 GUI |
| 4. 进入 | DeepSeek Harness GUI | 进入完整的 DeepSeek Harness 界面 |

异常场景：

| 界面 | 说明 |
| 启动失败：错误详情与重试 | 启动失败：错误详情 +「重试启动」+「重新检测」 |
| 未找到 dsh：配置指引 | 未找到 dsh：配置指引 +「重新检测」 |

安装说明

macOS

安装包为本地未签名构建。首次启动：

1. 打开 DMG，将 DeepSeek Harness 拖入「应用程序」。
2. 尝试打开应用；若 macOS 阻止启动，点击「完成」。
3. 打开「系统设置 → 隐私与安全性」。
4. 在「安全性」区域找到 DeepSeek Harness，点击「仍要打开」。
5. 再次点击「打开」确认。该确认通常只需一次。

前置要求：本机已安装可用的 dsh（或通过环境变量 DSH_BIN 指定路径）。
使用说明

| 场景 | 行为 |
| 本机已有 dsh web 实例（默认 3080） | 自动连接，不重复启动 |
| 没有实例、已装 dsh | 自动启动，或点击「一键启动服务」 |
| 启动失败 | 页面显示错误详情 +「重试启动」+「重新检测」 |
| 未找到 dsh | 页面给出配置指引 +「重新检测」 |
| 服务运行中意外退出 | 回到启动器页面，可重试 |

常用配置（环境变量）：

| 变量 | 默认 | 说明 |
| DSH_BIN | — | 指定 dsh 可执行文件路径 |
| DSH_SHELL_PORT | 3080 | 探测端口：连接已运行实例时用 |
| DSH_SHELL_AUTO_START | 1 | 设 0 则不自动启动，只显示「一键启动服务」按钮 |

完整变量表见开发者文档。

运行架构

DeepSeek Harness Desktop
├── Electron Main
│ ├── 探测已有实例（127.0.0.1:3080） │ ├── 一键启动 / 自动启动 dsh web │ ├── 子进程生命周期与退出清理 │ └── 随机回环端口与就绪检测 │ ├── dsh web 子进程（本机已安装的 @deepseek-ai/dsh） │ └── http://127.0.0.1: │ └── Sandboxed BrowserWindow └── DeepSeek Harness Web UI

安全模型

- Harness 服务仅绑定 127.0.0.1（源码显式拒绝 --host 0.0.0.0，安全红线）
- 渲染进程禁用 Node.js 集成，启用 contextIsolation 与 Chromium sandbox
- 连接已有实例时为只读连接，壳不杀死非自启的服务
- 应用退出时自动终止自启子进程（SIGTERM → SIGKILL；Windows 用 taskkill /T 杀进程树）

验证状态

| 平台 | 构建 | 打包后启动 | Web UI |
| macOS Apple Silicon | DMG 通过 | 通过 | HTTP 200 |
| Windows x64 | ZIP 交叉构建通过 | 未验证 | 未验证 |
| Linux | 未支持 | — | — |

已知限制

- 壳不内置 Harness 运行时，需要本机已安装 dsh
- macOS 安装包未签名、未公证，首次打开需手动允许
- Windows 尚未真机验证、未发布安装包
- Linux 未支持
- 尚未集成自动更新

路线图

- [ ] Windows 真机验证并发布安装包
- [ ] Linux 支持
- [ ] 体积优化：electron-updater 差量更新 / Tauri 迁移（见开发者文档）

贡献

欢迎协作！无论是修复 bug、补充功能、完善文档，还是帮我们在 Windows / Linux 真机上做验证（目前仅 macOS 验证过）。

请通过 GitHub Issues 反馈，或直接提交 Pull Request。

上游版本与许可

桌面封装采用 MIT License。应用图标使用上游 DeepSeek Harness Web favicon 中的鲸鱼图案。

本项目与 DeepSeek 不存在隶属或官方合作关系。DeepSeek Harness 及相关名称的权利归其各自所有者所有。

开发者指引见 docs/DEVELOPMENT.md。

DeepSeek Harness Desktop 将 DeepSeek Harness Web 体验打包为独立桌面应用：它会探测本地服务器，一键启动，并在退出时清理——无需手动 CLI 或端口管理。

本项目专注于桌面托管。它不会 fork、修改、注入或重新实现 Harness UI。模型、会话、设置、插件和 agent 能力仍由你机器上安装的官方 @deepseek-ai/dsh 提供。

[!IMPORTANT]
这是一个非官方社区封装，且处于早期阶段。安装包未签名、未公证（macOS 首次启动需在系统设置中批准）。Windows 尚未在真机上验证，也未发布。

下载

| 平台 | 架构 | 安装包 | 下载 |
| macOS | Apple Silicon | DMG | 下载 Apple Silicon 版 |
| Windows | x64 | — | 未验证，未发布（见已知限制） |
所有当前和历史版本均位于 GitHub Releases 页面。

为什么会有这个项目

DeepSeek Harness 已经提供了完整的 agent 运行时和 Web UI。本项目提供桌面产品所需的主机能力：

- 探测已在运行的本地 Harness 实例并直接连接
- 当没有实例运行时，在随机回环端口上自动（或一键）启动 dsh web
- 在打开 UI 前等待就绪；失败时显示重试，而不是弹出对话框
- 退出时终止自行启动的子进程，不留孤儿进程

功能特性

- 自动连接到正在运行的 Harness 实例，不会重复启动服务器
- 启动界面覆盖所有“服务器未运行”的情况：一键启动、进度、错误重试、安装指引
- 服务器仅监听随机本地回环端口，绝不暴露到局域网
- 渲染进程在 contextIsolation 下沙箱化，禁用 Node.js 集成
- 对已有实例只读连接——绝不接管其生命周期
- 打包时剥离 Electron 语言文件；macOS 安装包为 103 MB

预览

用户流程（打开应用 → 一键启动 → 进入 UI）：

| 步骤 | 界面 | 说明 |
| 1. 检测 | 未检测到服务器 | 未找到本地服务器——“启动服务器”按钮 |
| 2. 启动 | 正在启动服务器 | 在随机回环端口上启动 dsh web，显示进度 |
| 3. 就绪 | 服务器已就绪 | ✓ 服务器已就绪，正在打开 GUI |
| 4. 进入 | DeepSeek Harness GUI | 完整的 DeepSeek Harness 界面 |

边界情况：

| 界面 | 说明 |
| 启动失败：错误详情与重试 | 启动失败——错误详情 +“重试启动”+“重新检测” |
| 未找到 dsh：安装指引 | 未找到 dsh——安装指引 +“重新检测” |

安装

macOS

该安装包是本地构建的未签名二进制文件。首次启动时：

1. 打开 DMG，将 DeepSeek Harness 拖入 Applications。
2. 尝试打开应用；如果 macOS 阻止，请点击 Done。
3. 打开 System Settings → Privacy & Security。
4. 在 Security 部分找到 DeepSeek Harness，然后点击 Open Anyway。
5. 再次点击 Open 确认。通常只需执行一次。

前提条件：本地必须安装可用的 dsh（或通过 DSH_BIN 环境变量指定）。

使用

| 场景 | 行为 |
| 已有 dsh web 实例正在运行（默认端口 3080） | 自动连接，不重复启动服务器 |
| 没有实例，已安装 dsh | 自动启动，或按“启动服务器” |
| 启动失败 | 页面上显示错误详情 +“重试启动”+“重新检测” |
| 未找到 dsh | 页面上显示安装指引 +“重新检测” |
| 服务器意外退出 | 返回启动界面，可重试 |
常见配置（环境变量）：

| 变量 | 默认值 | 用途 |
| DSH_BIN | — | dsh 可执行文件的路径 |
| DSH_SHELL_PORT | 3080 | 用于连接正在运行的实例的探测端口 |
| DSH_SHELL_AUTO_START | 1 | 设为 0 可禁用自动启动，仅显示“启动服务器”按钮 |

完整变量列表请参阅开发者文档。

运行时架构

DeepSeek Harness Desktop
├── Electron Main
│ ├── Probe for an existing instance (127.0.0.1:3080)
│ ├── One-click / auto start of dsh web
│ ├── Child-process lifecycle and exit cleanup
│ └── Random loopback port and readiness checks
│
├── dsh web child process (locally installed @deepseek-ai/dsh)
│ └── http://127.0.0.1:
│
└── Sandboxed BrowserWindow
└── DeepSeek Harness Web UI

安全模型

- Harness 服务器仅绑定到 127.0.0.1（源码明确拒绝 --host 0.0.0.0，这是一条安全红线）
- 渲染进程中禁用了 Node.js 集成；已启用 contextIsolation 和 Chromium 沙箱
- 连接到现有实例是只读的——外壳程序绝不会终止并非由它启动的服务器
- 退出时，自行启动的子进程会被终止（SIGTERM → SIGKILL；在 Windows 上使用 taskkill /T 终止进程树）

验证状态

| 平台 | 打包 | 打包后启动 | Web UI |
| macOS Apple Silicon | DMG 通过 | 通过 | HTTP 200 |
| Windows x64 | ZIP 交叉构建通过 | 未验证 | 未验证 |
| Linux | 不支持 | — | — |

已知限制

- 外壳程序不捆绑 Harness 运行时；需要本地安装 dsh
- macOS 安装程序未签名且未公证；首次启动需要手动批准
- Windows 未在真实硬件上验证，且尚未发布安装程序
- 不支持 Linux
- 未集成自动更新

路线图

- [ ] 在真实 Windows 硬件上验证并发布 Windows 安装程序
- [ ] 支持 Linux
- [ ] 体积路线图：electron-updater 增量更新 / 迁移到 Tauri（请参阅开发者文档）

贡献

欢迎贡献！无论是修复 bug、添加功能、改进文档，还是帮助我们在真实的 Windows / Linux 机器上验证（目前仅验证了 macOS）。

请提交 GitHub Issue 或直接提交 pull request。

上游版本与许可证

桌面封装程序基于 MIT 许可证 提供。应用程序图标使用了上游 DeepSeek Harness Web favicon 中的鲸鱼图案。

本项目与 DeepSeek 无关联，也未获得其认可。DeepSeek Harness 及相关名称归其各自所有者所有。

开发者指南：docs/DEVELOPMENT.md。