DSH plugin 插件开发的多运行形态:web、headless 与 Electron 怎么兼容
插件开发到了要兼容多种运行形态时,问题往往不是代码写错,而是假设了不该假设的东西。 同一个插件在 dsh web 下正常,换到 headless 就没反应,进 Electron 界面又出不来——三处差异不在业务逻辑,而在“有没有页面”。DSH插件 与 DeepSeek插件 在这三种形态下的边界是一致的。
DSH plugin 三种形态差在哪
差别集中在两处:有没有浏览器,以及客户端 bundle 会不会被加载。(来源)
| 形态 | 宿主半 | 浏览器半 | 页面入口 |
|---|---|---|---|
| web | 加载 | 通过启动图加载 | HTTP 服务器提供 |
| headless | 加载 | 不加载 | 无 |
| Electron | 加载 | 走 file:// 加载已构建文件 | 不走 HTTP 服务器 |
这张表解释了大多数“形态相关”的故障:宿主侧能力(工具、服务、事件)在三种形态下都能注册;依赖 UI 的部分只在有页面时才有意义。
所以兼容的第一步不是写分支,而是把插件拆成“宿主能力”和“页面呈现”两层,认清哪些逻辑必须在宿主半完成。
先探测,别假设:DSH plugin 的存在性检查
用存在性检查代替读环境变量。(来源)
判断当前形态最稳的方式,是看你要用的东西在不在:注入的服务是否拿到、路由是否注册成功、启动图里是否有你的 entry。这些都是运行时可观察的事实,比读一个“当前是 web 吗”的标志可靠。
三条探测实践:
- 必需服务用 inject — 拿不到框架就不会加载,插件不用自己判断。
- 可选能力用运行时检查 — 在注册前确认对应服务存在,不存在就跳过。
- 页面相关逻辑只放在 client 半 — 宿主半不假设一定有人渲染。
最忌讳的是“读一个配置项决定形态”。配置描述的是部署意图,运行时事实才决定能力是否真的可用。
DSH plugin 降级的三条路
跳过、替代、报错,选哪条取决于该能力是不是核心职责。(来源)
- 跳过 — 可选能力缺失时不注册,并记录一条原因。适合“有更好、没有也能用”的功能。
- 替代 — 用宿主侧能力补位,例如没有页面就把结果写进日志或返回给调用方。
- 报错 — 核心能力缺失时直接让加载失败,早失败早发现。
三条路的共同要求是“可解释”:跳过要有日志,替代要说清差异,报错要带缺什么。最糟的是注册一个空实现,让调用方以为功能存在。
client 半只在 web 有意义:DSH plugin 的边界
没有页面时,client bundle 不会被加载,写了也不会执行。(来源)
客户端半通过 dsh.client 声明、打包成 bundle,再由 client 模块服务扫描进启动图。headless 没有页面,自然没有启动图,这份代码就不会跑。
因此插件作者要接受一个事实:client 半里不能放“必须先执行”的初始化逻辑。需要初始化的东西放宿主半,client 半只做呈现与交互。
同理,Electron 里页面走 file://,不经过 HTTP 服务器,所以依赖某个路由一定存在的 client 代码在 Electron 下会落空。
同一份代码的兼容写法:DSH plugin 怎么收敛分支
分支只留一处,其余代码对三种形态无感。(来源)
推荐的结构是:宿主半注册能力,页面相关的能力在注册前做一次探测,探测结果决定是否注册 client 贡献。这样业务逻辑只有一份,形态差异收敛在注册入口。
具体三条:
- 能力注册集中在一个函数 — 传入探测结果,返回注册了什么。
- client 贡献单独一个模块 — 只在探测通过时挂载,不影响宿主半。
- 错误信息写清形态 — 报错时说明“当前形态缺少 X”,比“初始化失败”有用得多。
这样在 web 下功能完整,headless 下自动退化为纯宿主能力,Electron 下也不会因为缺少 HTTP 路由而崩。
DSH plugin 兼容矩阵怎么验
三种形态各跑一遍,比在一种形态上反复调更有用。(来源)
- web — 确认宿主能力可用、页面入口出现、client 半加载成功。
- headless — 确认宿主能力仍可用,且没有因为缺少页面而抛错。
- Electron — 确认页面走 file:// 时功能可用,且不依赖 HTTP 路由。
- 能力缺失 — 人为移除一个可选服务,确认插件跳过而不是崩溃。
- 核心缺失 — 移除一个必需服务,确认插件不加载,而不是带着空实现运行。
验证:三形态矩阵
每次改动后按矩阵跑一遍,形态问题就不会留到发布。(来源)
- 在 web 下启动,断言工具可调用、页面能看到你的入口。
- 切到 headless 启动,断言同一工具仍可调用,且日志里没有“页面不存在”的异常。
- 在 Electron 下启动,断言界面可用且没有请求打到不存在的 HTTP 路由。
- 移除一个可选服务,断言插件仍加载、对应功能跳过并留下原因。
- 移除一个必需服务,断言插件不加载,且错误信息指出缺的是哪个服务。
如果第 2 步工具调用失败,多半是宿主能力被写进了 client 半;第 3 步出现 404,说明某段代码假设了 HTTP 路由一定存在。
profile 层面的差异可以对照不同 profile 的差异;客户端半的接入方式见界面开发。
一句话收束: 三种形态只差页面与 client bundle,探测用存在性而不是环境变量,降级要跳过、替代或报错且都可解释,初始化留在宿主半,最后按矩阵验一遍。
常见问题
先查这个 DSH plugin 是不是依赖了只在 web 存在的能力。插件分宿主半与浏览器半,浏览器半要靠 client 模块进入启动图;headless 没有页面,自然也不会加载这份 bundle。宿主半里的能力注册通常会正常工作,沉默的多半是 UI 相关部分。
DSH plugin 探测形态要用存在性检查代替环境判断。需要客户端渲染的能力依赖 client 模块与启动图,宿主侧只需要 ctx 上的服务;插件应检查自己注入的服务是否真的拿到,而不是读一个环境变量去分支,前者在三种形态下都准。
看该能力是不是 DSH plugin 的核心职责。必需依赖缺失时框架本来就不会加载插件;可选能力缺失时应跳过对应注册并记录原因,核心能力缺失则直接注册失败。最糟的是静默注册一个永不工作的空实现。
不会,DSH plugin 的 Electron 不走这条路径,它通过 file:// 加载已构建文件,fetch 请求走 IPC 桥接,HTTP 服务器只服务浏览器。所以依赖“某个路由一定存在”的插件在 Electron 下会落空,能复用的只有宿主侧能力,不是页面入口。
相关术语
- WebBootGraph
- WebBootGraph 是 Host 写入 window.__DSH_BOOT__ 的启动图,描述浏览器侧每个 entry 与依赖,只有 web 形态才会用到它。— DeepSeek Harness 官方参考 - Client 模块
- client 半
- client 半是插件面向浏览器的部分,通过 package.json 的 dsh.client 声明并打包成 bundle,由 client 模块服务扫描进启动图。— DeepSeek Harness 官方参考 - Client 模块
- HTTP 服务器
- HTTP 服务器是 GUI Host 的浏览器载体,提供具名路由与 index 注入,只服务浏览器,Electron 不走这条路径。— DeepSeek Harness 官方参考 - HTTP 服务器
- IPC 桥接
- IPC 桥接是 Electron 里替代 HTTP 请求的通道,页面通过它与宿主通信,不经过 dsh-host-webserver 的路由。— DeepSeek Harness 官方参考 - HTTP 服务器
来源
- DeepSeek Harness 官方参考 - Client 模块· deepseek-ai
- DeepSeek Harness 官方参考 - HTTP 服务器· deepseek-ai