ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发的多运行形态:web、headless 与 Electron 怎么兼容

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发headlessElectron
同一个插件在本地 web 能用,headless 下却毫无反应,Electron 里界面也出不来。本文用一张能力矩阵讲清三种形态差在哪,给出存在性探测、三条降级路径与一份可执行的兼容验证清单。

插件开发到了要兼容多种运行形态时,问题往往不是代码写错,而是假设了不该假设的东西。 同一个插件在 dsh web 下正常,换到 headless 就没反应,进 Electron 界面又出不来——三处差异不在业务逻辑,而在“有没有页面”。DSH插件 与 DeepSeek插件 在这三种形态下的边界是一致的。

DSH plugin 三种形态差在哪

差别集中在两处:有没有浏览器,以及客户端 bundle 会不会被加载。(来源)

形态宿主半浏览器半页面入口
web加载通过启动图加载HTTP 服务器提供
headless加载不加载无
Electron加载走 file:// 加载已构建文件不走 HTTP 服务器

这张表解释了大多数“形态相关”的故障:宿主侧能力(工具、服务、事件)在三种形态下都能注册;依赖 UI 的部分只在有页面时才有意义。

所以兼容的第一步不是写分支,而是把插件拆成“宿主能力”和“页面呈现”两层,认清哪些逻辑必须在宿主半完成。

先探测,别假设:DSH plugin 的存在性检查

用存在性检查代替读环境变量。(来源)

判断当前形态最稳的方式,是看你要用的东西在不在:注入的服务是否拿到、路由是否注册成功、启动图里是否有你的 entry。这些都是运行时可观察的事实,比读一个“当前是 web 吗”的标志可靠。

三条探测实践:

  1. 必需服务用 inject — 拿不到框架就不会加载,插件不用自己判断。
  2. 可选能力用运行时检查 — 在注册前确认对应服务存在,不存在就跳过。
  3. 页面相关逻辑只放在 client 半 — 宿主半不假设一定有人渲染。

最忌讳的是“读一个配置项决定形态”。配置描述的是部署意图,运行时事实才决定能力是否真的可用。

DSH plugin 降级的三条路

跳过、替代、报错,选哪条取决于该能力是不是核心职责。(来源)

  1. 跳过 — 可选能力缺失时不注册,并记录一条原因。适合“有更好、没有也能用”的功能。
  2. 替代 — 用宿主侧能力补位,例如没有页面就把结果写进日志或返回给调用方。
  3. 报错 — 核心能力缺失时直接让加载失败,早失败早发现。

三条路的共同要求是“可解释”:跳过要有日志,替代要说清差异,报错要带缺什么。最糟的是注册一个空实现,让调用方以为功能存在。

client 半只在 web 有意义:DSH plugin 的边界

没有页面时,client bundle 不会被加载,写了也不会执行。(来源)

客户端半通过 dsh.client 声明、打包成 bundle,再由 client 模块服务扫描进启动图。headless 没有页面,自然没有启动图,这份代码就不会跑。

因此插件作者要接受一个事实:client 半里不能放“必须先执行”的初始化逻辑。需要初始化的东西放宿主半,client 半只做呈现与交互。

同理,Electron 里页面走 file://,不经过 HTTP 服务器,所以依赖某个路由一定存在的 client 代码在 Electron 下会落空。

同一份代码的兼容写法:DSH plugin 怎么收敛分支

分支只留一处,其余代码对三种形态无感。(来源)

推荐的结构是:宿主半注册能力,页面相关的能力在注册前做一次探测,探测结果决定是否注册 client 贡献。这样业务逻辑只有一份,形态差异收敛在注册入口。

具体三条:

  1. 能力注册集中在一个函数 — 传入探测结果,返回注册了什么。
  2. client 贡献单独一个模块 — 只在探测通过时挂载,不影响宿主半。
  3. 错误信息写清形态 — 报错时说明“当前形态缺少 X”,比“初始化失败”有用得多。

这样在 web 下功能完整,headless 下自动退化为纯宿主能力,Electron 下也不会因为缺少 HTTP 路由而崩。

DSH plugin 兼容矩阵怎么验

三种形态各跑一遍,比在一种形态上反复调更有用。(来源)

  1. web — 确认宿主能力可用、页面入口出现、client 半加载成功。
  2. headless — 确认宿主能力仍可用,且没有因为缺少页面而抛错。
  3. Electron — 确认页面走 file:// 时功能可用,且不依赖 HTTP 路由。
  4. 能力缺失 — 人为移除一个可选服务,确认插件跳过而不是崩溃。
  5. 核心缺失 — 移除一个必需服务,确认插件不加载,而不是带着空实现运行。

验证:三形态矩阵

每次改动后按矩阵跑一遍,形态问题就不会留到发布。(来源)

  1. 在 web 下启动,断言工具可调用、页面能看到你的入口。
  2. 切到 headless 启动,断言同一工具仍可调用,且日志里没有“页面不存在”的异常。
  3. 在 Electron 下启动,断言界面可用且没有请求打到不存在的 HTTP 路由。
  4. 移除一个可选服务,断言插件仍加载、对应功能跳过并留下原因。
  5. 移除一个必需服务,断言插件不加载,且错误信息指出缺的是哪个服务。

如果第 2 步工具调用失败,多半是宿主能力被写进了 client 半;第 3 步出现 404,说明某段代码假设了 HTTP 路由一定存在。

profile 层面的差异可以对照不同 profile 的差异;客户端半的接入方式见界面开发。

一句话收束: 三种形态只差页面与 client bundle,探测用存在性而不是环境变量,降级要跳过、替代或报错且都可解释,初始化留在宿主半,最后按矩阵验一遍。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件在本地 web 能用,headless 下没反应,最先该查什么?

先查这个 DSH plugin 是不是依赖了只在 web 存在的能力。插件分宿主半与浏览器半,浏览器半要靠 client 模块进入启动图;headless 没有页面,自然也不会加载这份 bundle。宿主半里的能力注册通常会正常工作,沉默的多半是 UI 相关部分。

DSH plugin 插件开发时怎么探测当前运行形态,而不是靠猜?

DSH plugin 探测形态要用存在性检查代替环境判断。需要客户端渲染的能力依赖 client 模块与启动图,宿主侧只需要 ctx 上的服务;插件应检查自己注入的服务是否真的拿到,而不是读一个环境变量去分支,前者在三种形态下都准。

DSH plugin 插件开发时缺少可选能力,应该跳过还是直接报错?

看该能力是不是 DSH plugin 的核心职责。必需依赖缺失时框架本来就不会加载插件;可选能力缺失时应跳过对应注册并记录原因,核心能力缺失则直接注册失败。最糟的是静默注册一个永不工作的空实现。

DSH plugin 的 Electron 版本会走同一个 HTTP 服务器吗,插件需要注意什么?

不会,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 服务器

来源