DSH Desktop 为什么存在:DeepSeek Harness 的桌面运行时适配层与插件化边界设计
DSH Desktop 为什么存在:DeepSeek Harness 的桌面运行时适配层与插件化边界设计
导读:本文基于仓库 docs/why-desktop.md 展开,回答 DSH Desktop 为什么不是一个"二次分叉的 Harness",而是一个把官方 DeepSeek Harness 运行时搬进原生桌面应用的产品入口与运行时适配层。你将理解它要解决的用户问题、坚持"一切皆插件"的三个理由、它自己提供与刻意不做的能力边界,以及对应的源码实现与配套文档入口。
我们解决什么问题
DeepSeek Harness(DSH)的核心是一个可组合的 agent harness。它通过命令行和 Web UI 使用,也允许开发者把模型、工具、会话和工作流组合成自己的运行时——这正是它的强大之处。但对于第一次运行的用户来说,Node.js、profile、依赖安装、端口和进程生命周期,仍然是一道不低的门槛。
DSH Desktop 的目标不是重新实现 Harness,而是把同一个运行时放进一个容易启动、容易管理、符合操作系统习惯的应用里。这份定位在 docs/why-desktop.md 中被概括为四层分工:
- 安装包负责提供 Electron、Node 运行时和固定版本的 DSH 依赖;
- 应用负责窗口、托盘、单实例、退出和本地服务生命周期;
- 用户仍然使用官方 DSH 的 profile、插件、会话和 Web UI;
- 上游 Harness 继续拥有 agent、模型、工具、会话和 Web 客户端的核心语义。
因此 Desktop 是一个产品入口和运行时适配层,不是上游项目的替代品,也不是把上游源码复制一份再长期分叉。这一点在 docs/architecture.md 中有更底层的印证:DSH Desktop 是一个薄的 Electron 宿主,它在 Electron main 进程中启动官方 DSH Host,Host 再通过 HTTP/WebSocket Web carrier 提供普通 Web UI;carrier 默认只监听回环地址,只有在用户明确确认风险后才向局域网开放。Desktop 没有另造一条 renderer IPC 插件系统,也不把 Electron API 暴露给页面。
从 dsh-plugin-desktop/src/main.ts 的源码结构看,Electron 入口只承担最薄的引导职责:获取单实例锁(app.requestSingleInstanceLock())、解析选中的 DSH profile、提供 native runtime 能力,然后在 Electron main 进程中启动 Host Cordis root。窗口、托盘、导航策略、设置命名空间与"关闭还是退出"的生命周期,全部由 Host 插件通过 Cordis effect 承担。
为什么坚持插件化
"一切皆插件"让 Harness 的能力可以被组合,而不是被一个固定应用绑死。Desktop 采用同一原则有三个直接好处(原文档核心内容):
- 上游能力保持可替换。 Desktop 可以使用官方 Web client,用户的 profile 也可以加入模型、工具、界面和工作流插件。
- 桌面能力保持可扩展。 profile 管理和打包环境提供的能力可以通过明确的 Host service 给插件使用,而不是让每个插件猜 Electron 的内部对象。
- 边界更容易维护。 上游 DSH 负责 agent 语义,Desktop 负责原生窗口和系统集成,第三方插件只依赖自己真正需要的 contract。
插件化也意味着不是所有东西都应该暴露。第三方插件只能使用明确公开的接口,不能直接控制窗口、托盘、安装器等内部实现;稳定的边界比"什么都能访问"更容易升级和排错。
公开接口到底有哪些:三个 service
这条边界在 dsh-plugin-desktop/docs/plugin-services.md 中被精确化为三个公开 service:
| Service | 类型 | 职责 |
|---|---|---|
desktopProfiles |
Host service | 读取当前 profile、发现可选 profile,并请求安全的 profile 切换 |
desktopPnpm |
Host service | 在当前 profile 中执行 pnpm,或通过官方 dsh plugin 语义管理插件 |
desktopWindow |
Client service | 只读暴露窗口模式、平台、材质、安全区 inset 与拖动区域等原生布局事实 |
从源码边界表(dsh-plugin-desktop/docs/plugin-services.md)可以看到更细的分工:
desktopRuntime是 Launcher 提供的 native adapter,仅供 Desktop 自有 shell、tray、terminal、profile 和 update 行使用,第三方插件不得注入它;desktopPnpmBootstrap包含打包绝对路径、profile 事实、Electron ABI 值等 launcher 私有信息,永远不要读取、提供、拦截或声明为依赖。
换句话说,"私有类型出现在声明文件里"并不等于它是受支持的第三方能力,只有 desktopProfiles、desktopPnpm、desktopWindow 三个名字及其 contract 模块才是兼容性边界。这正是 docs/why-desktop.md 中"不是所有东西都应该暴露"的落地实现,也是插件开发的基础,详见 插件开发。
Desktop 自己提供什么
当前 Desktop 主要提供以下能力(原文档核心清单,结合源码与配套文档深化):
原生窗口、托盘与单实例生命周期
macOS 和 Windows 原生窗口、托盘和单实例生命周期。从 dsh-plugin-desktop/README.md 的 Native lifecycle 部分可以确认:关闭窗口只会隐藏它,Host Cordis 树继续运行;托盘负责重开窗口、选择 profile、打开终端、检查更新、切换模式或显式退出。profile 与模式的变更都会先 dispose 当前 Cordis 树再重启 Electron;原生退出、SIGINT 和 SIGTERM 也会先请求 dispose,五秒超时或重复请求才强制退出。
三种呈现模式
兼容、扩展窗口和增强三种呈现模式,这是 Desktop 对外观能力最核心的抽象:
- 兼容模式:在独立 Desktop frame 下保留上游默认客户端。官方 layout、root、sidebar 与 conversation 作为完全无关的内容 viewport 从 frame 下方开始,官方 dialog 只占用与 frame 无关的下方内容 viewport。
- 扩展窗口:使用自己独立注册的 Desktop layout/sidebar surface 承载官方 occupant 并形成倒 L 材质区域——36 像素顶部 frame 与左侧 sidebar surface 组成一个带圆角内拐角的连续玻璃表面。
- 增强模式:保留独立 root registration 与紧凑内部 caption。macOS 使用 20 像素内容 inset 和 32 像素拖动区域,Windows 使用 32 像素 caption row,不复用扩展窗口的独立 frame。
Desktop frame 还会按能力提供原生材质与拖动区域:macOS 提供 Off 与 Transparent,Windows 提供 Off 与原生 Acrylic;Mica 仅在 Windows 11 build 22621 及以上出现。模式与材质的切换都会触发一次有序重启,绝不在运行中的 renderer 里热替换 root slot 或窗口材质。Linux 只提供兼容模式。窗口选项的这些平台差异在 dsh-plugin-desktop/tests/window-options.spec.ts 中有对应的单元测试覆盖,例如兼容模式会拒绝 advanced spec(unsupported compatibility window mode advanced)、Windows 11 22H1 才启用 Mica 等。
多 profile 选择
当前 generation 的 profile 身份由 Desktop 明确提供,切换通过有序重启生效。在 dsh-plugin-desktop/docs/plugin-services.md 中,desktopProfiles.current 在一个 generation 内不可变,包含激活 profile 的 name 与绝对 dir;list() 是只读发现;select(name) 是重启操作而非原地变更——它先持久化接受的目标,再请求有序的 Cordis teardown 和 Electron relaunch。profile 名字与绝对目录不能从 argv、settings 或 URL 猜测。
内置终端与固定版本 pnpm
内置终端和固定版本 pnpm 环境,它们只作用于 Desktop 自己创建的进程,不修改用户的全局 PATH。Desktop 会在自己的 user-data 目录生成私有的 dsh、pnpm、node shim,只对终端进程设置 PATH,不会编辑全局环境或 shell 启动文件。desktopPnpm.run() 直接运行打包的 pnpm 入口(以激活 profile 目录为 cwd),runPlugin() 通过打包的 DSH CLI 维持 profile 初始化、相对 source 和 bundle reconcile。服务每个 generation 至多允许一个 package operation 并发,完整子进程树退出后 done 才会 settle。
受控扩展接口与更新链路
面向插件开发者的一组受控扩展接口,详见 插件开发。另外还提供版本检查、用户确认后的安装包下载,以及 macOS DMG / Windows NSIS 的平台交接。更新链路在 dsh-plugin-desktop/README.md 中描述得相当具体:启动 60 秒后查询版本接口、每六小时一次、每次请求带 X-DSH-Desktop-Channel header、下载前先确认广告版本未变化、流式下载上限 1 GiB、拒绝不完整的 DMG 或 Windows PE 文件;macOS 打开 DMG 由用户替换到 Applications,Windows 在 NSIS 安装器就绪后再询问"Restart and Install"。
我们刻意不做什么
原文档明确列出了五条"不做"清单,这是理解产品边界最直接的一节,也是社区项目避免承诺过度的重要声明:
- 不把上游 Web UI 重新实现成 Electron 原生页面。 Web UI 继续由官方
dsh-web-app提供,通过共享 Web carrier 工作。 - 不在兼容模式中覆盖上游 layout、sidebar 或 conversation 组合。 兼容模式只通过 overlay slot 加入一条独立的 36 像素 Desktop frame,官方组合原样保留。
- 不把记录复制到另一个"Desktop 数据库"。 官方 profile 默认共享 DSH home 中的会话和设置,切换 profile 不会复制或迁移记录。
- 不给第三方插件一个未定义的 Electron 私有 API。 与上文"稳定边界"一致,private 类型出现在声明中也不构成受支持能力。
- 不把 roadmap(插件市场、手机远程、Channels)写成当前版本已经交付的功能。 这是对发布纪律的明确约束——当前文档只陈述已实现的能力。
这五条在源码与测试中都能找到对应:兼容模式的 Client face 会校验环境且只做 frame overlay(dsh-plugin-desktop/README.md);desktopRuntime、desktopPnpmBootstrap、ELECTRON_RUN_AS_NODE 等被明确列为非第三方兼容 contract(插件开发);平台 adapter 的 Linux 分支只保留普通原生 frame(dsh-plugin-desktop/tests/window-options.spec.ts)。
边界背后的实现:Host 启动顺序与 generation 隔离
理解"Desktop 只是适配层"最直观的证据是 docs/architecture.md 记录的启动顺序:
- Electron 获取单实例锁,读取 Desktop 私有的 profile/mode 状态;
- Launcher 准备激活 profile,但不会为了列举 profile 而改写用户 profile;
- Launcher 提供当前 generation 的 native runtime、
desktopProfilesbootstrap 和内置 pnpm 环境; - Host Cordis root 启动 Loader entries,Desktop service 在第三方插件可读取前注册;
- 官方
dsh-base、dsh-web-app和 profile 中的第三方 bundle 组成 Web carrier; - Host 默认绑定 loopback,也可按已确认的设置绑定所有网络接口;Electron 创建 BrowserWindow 并从 loopback 地址加载同源页面;
- Web surface 成功加载后才创建托盘并提交 profile 的 last-known-good 状态。
任何 profile 或模式切换都会 dispose 当前 generation 再启动新的 generation;service reference、窗口对象和 subprocess handle 都不能跨 generation 缓存。ElectronShellGeneration 模块完整拥有 BrowserWindow、Tray 及相关 listener,释放必须通过幂等的 release() 接口完成。
适合谁
原文档按读者类型给出了三条入口,这里保留并补充对应的仓库路径:
- 只想安装后直接使用 Harness 的用户:从 用户指南 开始。安装包自带 Electron、Node 与 DSH 依赖,普通用户无需另行安装 Node.js 或 pnpm;日常涉及 profile 切换、窗口模式与材质、本地端口设置、插件管理、终端与更新排查。
- 想安装或开发 DSH 插件的用户:先读 插件开发,再看 Desktop service contract。重点掌握两层插件模型:普通 DSH 插件应尽量只依赖官方 DSH contract 以便在命令行、普通 Web profile 和 Desktop 中复用;只有需要 profile 信息或 pnpm 能力时才注入
desktopProfiles/desktopPnpm,并遵循"Desktop-only 用 required injection、跨环境用嵌套ctx.inject()+ 普通 DSH fallback"两种模式。插件作者还必须遵守十条失败与 teardown 检查清单(如:package mutation 只能来自显式用户动作、始终 drain stdout/stderr、分别处理 rejection / 非零exitCode/ 终止signal、把select()视为重启边界等)。 - 想理解启动、profile 和打包边界的维护者:阅读 架构说明 和包级 README。这里包含发行通道协议(稳定版与 Beta 是两个实体 npm 包、
upstream.json记录双通道清单)、打包与运行时闭包(app.asar.unpacked、packaged-runtime gate)以及完整的模式设置与重启边界(dsh-desktop.mode是 DSH homesettings.yaml中的唯一事实来源)。
总结:一个"无特权"的桌面壳
DSH Desktop 的设计可以浓缩为一句话:它是 DSH 插件生态的第一个实践者——桌面壳本身就是一个普通插件,与官方、第三方插件走同一条组合路径,没有任何特权。这个判断有三层支撑:
- 架构上,Electron 只是薄宿主,agent 语义、会话、Web client 全部归上游;Desktop 只拥有窗口、托盘、profile、终端、更新这些原生集成(docs/architecture.md)。
- 契约上,第三方只依赖
desktopProfiles、desktopPnpm、desktopWindow三个公开 service,launcher 私有能力一律不构成 API(dsh-plugin-desktop/docs/plugin-services.md)。 - 纪律上,刻意不做清单把"重写 UI、覆盖上游组合、另建数据库、暴露私有 API、提前宣传 roadmap"全部排除在产品范围之外(docs/why-desktop.md)。
如果你的目标是"装完就能用",从 用户指南 出发;如果你的目标是"写一个能同时在 DSH 与 Desktop 复用的插件",从 插件开发 与 Desktop service contract 出发;如果你的目标是维护这条边界本身,架构说明 和包级 README 是继续深入的入口。