桌面壳 citrusli2026/dsh-desktop

dsh-desktop

English · 官网

DeepSeek Harness 的可靠 Electron 桌面壳:官方 WebUI 的桌面封装,下载安装即用, 功能与 npx @deepseek-ai/dsh web 完全一致。社区维护,MIT 开源,与 DeepSeek AI 无关联; DeepSeek Harness 为 DeepSeek 的商标,本仓库仅做 MIT 许可下的再打包。

为什么用桌面版,而不是 npx?

同一内核、同一 WebUI——桌面壳替你搞定环境,再补上桌面该有的部分:

| 能力 | npx @deepseek-ai/dsh web | dsh-desktop |
| Node.js / pnpm | 自装自维护 | 内置锁定版 Node.js 24,零配置 |
| 启动方式 | 开终端敲命令 | 双击图标,或快捷键全局唤起(Ctrl/Cmd + Shift + Space) |
| 窗口与托盘 | 多占一个浏览器标签页 | 原生独立窗口，关闭即退出并停止服务 |
| 崩溃恢复 | 自己排查重启 | 指数退避自动重启,错误页一键重试 |
| 坏插件 | 可能卡死整个 WebUI | 错误页一键升级或禁用坏插件;安全模式兜底隔离 |
| 诊断 | 自己翻终端日志 | 一键体检 + 可导出脱敏诊断报告 |
| 更新 | 手动升级 npm 包 | Windows 原地自动更新;macOS 直达发布页 |

命令行与桌面版可以共存——详情见为什么选择桌面版,发布记录见更新日志。

产品定位与范围

dsh-desktop 是社区维护的个人项目，定位是可靠的 Electron 壳 + 开箱即用的支持。
它只负责把官方 Harness WebUI 稳定地带到桌面：运行时封装、原生窗口与托盘、进程守护、恢复、诊断、更新和必要的桌面入口；不另做一套 Agent 工作台或聊天产品。

社区插件始终由用户手动安装。安装包不包含社区插件，首次启动也不会自动播种；需要时在「设置 → 桌面设置 → 插件市场」手动安装 dsh-market，再由用户自行选择其他插件。
当前安装包未签名：macOS 首次打开需右键 → 打开，Windows 需「更多信息 → 仍要运行」；下载后可用随包发布的 .sha256 校验文件验证完整性。

官网: dsh-desktop.com —— 产品介绍与下载(GitHub 与验证过的 GitCode 镜像,按可用性排序展示),以及未签名 macOS 首启、SmartScreen、校验与来源验证等常见问题。官网随 GitHub Releases 自动同步。

你得到什么

- 无需配置运行时 —— 内置锁定版本的 Node.js 24 运行时与 @deepseek-ai/dsh 完整依赖闭包；不用另装 Node，也不用先跑命令行安装。
- 飞书消息执行任务 —— 内置 cc-connect，把一个已保存的机器人应用连接到本地工作区。「设置 → 飞书连接」或「桌面工具 → 连接 → 飞书连接」打开同一个管理器，支持扫码创建、显式开启/关闭与消息/卡片设置；浮窗还会分开显示当前应用、桌面进程与飞书通道状态，并提供显式开启/关闭/重连。模型凭据仍在 Harness 配置。长连接无需公网 IP 或局域网共享。详见连接指南。
- 默认独立 —— 自己的数据目录(~/.dsh-desktop),设置、会话、API Key、插件与 CLI 互不影响;DSH_HOME=~/.dsh 可共享。
- 可靠守护 —— 崩溃指数退避自动重启、错误页手动重试、托盘实时状态、单实例锁、窗口几何记忆、可导出的诊断报告。Windows 菜单栏隐藏时，仍可通过应用内「桌面工具」、窗口右键或系统托盘操作桌面功能。
- 随时唤回桌面应用 —— 最小化或设置为启动后隐藏时，在任意应用中按可自定义的唤起快捷键即可显示并聚焦 dsh-desktop，默认是 Ctrl/Cmd + Shift + Space（Windows/Linux 用 Ctrl，macOS 用 ⌘）。若快捷键被其他软件占用，托盘和右键入口仍然可用。关闭主窗口则完整退出，飞书和局域网服务随之停止。
- 清晰的首次成功路径 —— 主界面用可关闭的轻量引导展示“运行环境 → 工作区 → 模型 → 第一条任务”，成功后自动结束；插件市场明确为可选项。
- 一键运行体检 —— 「设置 → 桌面设置」检查随包运行时、数据目录与磁盘、Harness loopback、Profile、插件和版本。代理、registry、更新源仅在用户勾选后联网；结果只留本地、已脱敏，不自动修复文件。
- 按你的桌面习惯工作 —— 在 Harness「设置 → 桌面设置」中录入快捷键，选择是否开机启动、启动后隐藏，以及是否接收本地状态通知；配置保存在壳自己的数据文件中。
- 开箱即用的插件路径 —— 安装包不预装社区插件；需要时从「设置 → 桌面设置 → 插件市场」手动安装。面板会展示准备、下载、验证、重启阶段和实际安装版本；registry、代理、profile 或安装脚本失败时给出可重试的脱敏原因。
- 坏插件也能恢复 —— 启动因不兼容的社区插件失败时，错误页逐个列出可疑插件，一键「升级」（拉取最新版）或「禁用」（仅移出启动列表，文件保留，可在「设置 → 插件」恢复），也可「全部升级并重启」；官方内置包不可被这些操作触碰。安全模式（错误页、「桌面工具」或「桌面设置」）仍是兜底：第三方插件被隔离，官方与内置扩展照常运行；诊断报告会标出疑似肇事者。
- 便携 Agent 预设 —— 「设置 → 桌面设置 → Agent 预设」可把预设导出为单个 .dshpreset 文件，在另一台机器上导入时带冲突检查（跳过 / 替换 / 克隆）与信任提示。
- 渲染层收敛 —— 保持沙箱与上下文隔离、关闭 Node 集成、限制导航;摄像头、定位、Web 通知、文件系统权限默认拒绝。可选桌面通知只使用 Harness 公开状态，不读取屏幕；点击通知即可聚焦回桌面应用。
- 桌面垃圾桶 —— 删除的会话、预设都可在「设置 → 垃圾桶」还原;Agent 的删除命令会先移入垃圾桶,可疑删除直接拦截并说明原因。保留 30 天。
- 更新策略 —— Windows 原地自动更新;未签名 macOS 检查新版本并打开精确发布页。

下载

各平台安装包(Release 另含 Windows 原地更新所需的 latest.yml 与 .exe.blockmap):

| 平台 | 安装包 |
| macOS(仅 Apple Silicon,未签名) | dsh-desktop-<版本>-arm64-mac.dmg |
| Windows | dsh-desktop-setup-<版本>.exe(NSIS) |
| Linux | dsh-desktop-<版本>-amd64.deb(Debian/Ubuntu/UOS/Deepin/麒麟) |

从官网(按可用性展示 GitHub 与 GitCode 镜像)、
GitHub Releases或 GitCode Releases下载;
官网若在你的网络无法访问(个别网络对托管边缘不稳定),直接用后两个渠道即可。
校验:核对旁侧的 .sha256,或 gh attestation verify <文件> -R citrusli2026/dsh-desktop 验证来源证明,各平台完整步骤见官网 FAQ。

常见问题

- 插件坏了，Harness 起不来怎么办？ 错误页会列出可疑插件：「升级」通过与插件市场相同的安装通道拉取最新版；「禁用」只移除启动 bundle 条目（文件保留，可在「设置 → 插件」重新启用）；「全部升级并重启」一次修好所有可疑插件。官方内置包会被拒绝操作。也可以在错误页点「以安全模式启动」（或从「桌面工具」/「桌面设置」进入）作为兜底；导出的诊断报告会标出疑似肇事者。
- 应用能打开，但怀疑环境不正常怎么办？ 打开「设置 → 桌面设置 → 运行体检」。默认本地检查不联网；需要判断代理、registry 或更新源时再单独勾选联网检查。结果不上传，也不会修改用户文件。
- 插件市场安装失败怎么办？ 桌面设置会区分网络、代理、超时、profile、安装脚本和随包工具故障。展开脱敏技术详情或导出诊断，修复对应环境问题后直接重试；失败的安装不会被标记成已安装。
- 想把 Agent 预设分享给同事或另一台机器？ 「设置 → 桌面设置 → Agent 预设」选中预设后点「导出预设」，得到单个 .dshpreset 文件；对方从同一面板「导入预设」。导入会先检查重名（跳过 / 替换 / 克隆），且只会安装为用户预设——绝不会覆盖内置预设。
- 桌面偏好存在哪里? 在 Electron 用户数据目录下的壳私有 shell-preferences.json，与 Harness 的 settings.yaml 和 CLI 数据(DSH_HOME)完全分开。
- 诊断报告? 错误页或 ⋮ → 导出诊断，会把仅限本地的报告(最近 harness 输出、插件清单、疑似坏插件、壳/内核版本)写到自选路径。

版本号

版本与 tag 为复合式:<dsh 版本>.shell.<壳修订号>——如 0.2.2-alpha.2.shell.0 表示打包 @deepseek-ai/dsh 0.2.2-alpha.2、壳第 0 次修订。源码版本不等于已发布下载，官网只列实际已发布构建。版本字段由 scripts/version.mjs 统一管理;dsh-watch 工作流每日检查上游 npm, 发现新版自动开经验证的 bump PR。

开发

要求:Node ^22.19.0 || >=24.0.0,pnpm 10.33.2。

pnpm install # 依赖 + Electron 二进制
pnpm run bootstrap # 物化 harness 闭包 + 内置 Node 24.21.0
pnpm run dev # 本机运行
pnpm run smoke # 冒烟:harness 就绪 → 窗口加载 → 校验页面 → 退出
pnpm run verify # typecheck + 单测与覆盖率 + site check + 构建
pnpm run dist # 打当前平台安装包(产物在 dist/)

- 局域网 Web 连接：「桌面工具 → 连接移动设备」启动独立 mobile-shell Web 代理并显示一次性配对码。壳只消费另一仓库的 Web 产物 (dsh-mobile-shell,不可变 tag v1.0.2);已配对会话可跨 Harness/代理重启继续使用, DSH_LAN_IP 可指定多网卡时的地址。
- Android 模拟器门禁:启动带 Chrome 的 AVD 后执行 DSH_E2E_ANDROID_SERIAL=<adb-serial> pnpm run test:e2e:android。该用例使用模拟器里的真实浏览器覆盖配对、后台恢复、共享重启和桌面应用完整重启。
- 内置 Node 在 manifest/node-runtime.json 里 pin 死版本与各平台 SHA-256, bootstrap 从仓库提交值复现。

目录结构

src/main/ Electron 主进程:监督、窗口、占位/错误页、托盘 src/preload/ 沙箱桥接(错误页的"重试启动") scripts/ fetch-node / deploy-harness / install-electron / build / gen-icons manifest/ @deepseek-ai/dsh 及其闭包的依赖 pin docs/decisions/ ADR 风格的决策记录

文档

- 文档索引与治理 · 决策记录
- CONTEXT.md —— 领域词汇表(给 agent 对齐)· HANDOFF.md —— 发布记录与运维历史

License

MIT。内置的 DeepSeek Harness 运行时来自
@deepseek-ai/dsh(MIT)。