ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Client 模块:wire、扫描与 bundle 注入到底怎么接才不出错

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessClient 模块WebBootGraphbundle
插件带了客户端代码,页面却加载不到,或 bundle 路由与 index 注入对不上。本文讲 ctx.clientModules 的四个面、WebBootGraph 的 wire 契约、dsh.client 扫描与增量对账,以及 combo 脚本与 source map 的生成规则。

客户端代码加载不到,通常不是构建失败,而是没进那张 entry 图。 DSH plugin 的 Client 模块服务把“扫描包”“组合图”“提供脚本”“注入 index”做成同一个服务的四个面;缺任何一面,页面都拿不到你的 bundle。 DSH插件 带了客户端代码却加载不到,先确认它有没有进那张 entry 图。

一个服务的四个面

它扫描、组图、发脚本、答注入,四件事共用一份状态。(来源)

dsh-client-modules 是 client 模块系统的 Node 半,以 ctx.clientModules 形式提供。它做四件事:

  1. 扫描宿主 Loader 的 entry,找出声明了 dsh.client 的包;
  2. 组合出 window.__DSH_BOOT__ entry 图;
  3. 在 /plugins 下提供带版本的单资源或多资源 combo 脚本;
  4. 以启动协议行回应每次 index 注入收集。

它是 Web GUI 栈的一项可选能力,不属于 agent 循环主干,并且是 dsh-host-webserver 的消费方:载体提供本服务注册的前缀路由与其回应的 webserver/index-inject 事件。

同一个包的浏览器半(ctx.modules,即拉取并物化这些 bundle 的 lazy CJS 模块表)属于内核机件,记录在包 README 中,不在这一层。

wire 是唯一真源

图的形状就是协议,页面没有有效清单就无法启动。(来源)

图是 Node 半与浏览器半之间协议层的唯一真源。宿主从扫描到的包组合出 WebBootEntry 行与 WebBootBatch 描述,随后在 Vite entry 之前向结构化 index 注入表贡献四个东西:registration facade、application preload、bootstrap 脚本与图全局量。

global 行渲染为 globalThis["__DSH_BOOT__"],其中 < 已转义,插件可控的字符串因此无法逃出 script 元素。

没有有效 manifest 的页面无法启动:浏览器解析器会拒绝畸形 row 或批次、未知成员,以及未恰好归属一个初始 combo 描述的 entry。

WebBootEntry 的字段各有用途:id 等于包名;url 是带修订的单资源 combo 引用,由 HMR 使用,且相对文档解析;rev 是不透明的插件产物修订,用于 HMR 缓存破除;inject 是包名依赖边;immediately 标记第一阶段预取;external 携带精确的非 inject 模块请求。

WebBootBatch 则描述一个初始 combo 脚本:phase 是 bootstrap 或 application,调度阶段可以跨多个描述;url 是内容寻址的 combo 引用;rev 由有序 entry 修订派生;entries 是脚本注册 factory 的执行顺序。

WebBootGraph 汇总为 rev、可选 release、按模块图顺序排列的 entries 与 batches。每个 entry 必须恰好属于一个 descriptor。

扫描:dsh.client 与增量对账

同名包来自不同 Loader 源时,组合会直接失败。(来源)

包加入这张表的方式,是在自己的 package.json 中声明 dsh.client(platform: 'web'、可选 inject 边、可选 immediately),并在 exports["./client"] 导出构建好的 bundle。

每个 live row 都从自己的 Loader specifier 与所属 tree baseUrl 解析;若 loader.internal.resolveSync 可用,则使用 Host face import 所用的同一个实现。最近归属的 package manifest 提供浏览器模块 id,因此相对 source 与 built overlay 仍保留包身份。

若不同的 active Loader source 解析到同一包名,组合会失败。一个来源卸载后,仍存活的来源无需重启 fiber 即可提供该 row。

对账是按 Loader entry 名增量进行的:fiber 构造或 dispose 时的每次 Cordis internal/plugin 事件都会把该 fiber 的 entry 名标脏;每次非空 flush 在开始时枚举全部 Loader entries 一次并按名称建索引;待处理名称使用索引中的全部同名来源,缺失名称使用空列表移除已卸载的来源。包解析过程不得在对账期间同步添加或移除 Loader entries。

失败处理分两个阶段,这点很容易误判:激活时,畸形声明、缺失 bundle 与 flush 枚举失败会聚合为一个组合错误,fiber 失败并由启动流程报告;稳态下,包失败只记录警告,不妨碍其他名称继续对账。枚举失败会消费失败批次、记录一条警告,并保持包状态与已发布的图不变,受影响的每个名称要等另一次通知才会重试。

bundle 路由与 source map

combo 脚本只拼接一次,map 只在第一次请求时生成。(来源)

GET 与 HEAD 的 /plugins/??<package-a>/client.js,<package-b>/client.js&rev=<rev> 寻址一份生成的 combo 脚本;单资源请求采用同一形式,也是 HMR 路径。/plugins/<package>/assets/<path> 提供包发布的图片。

脚本在首次 GET 时只拼接一次,并以 sourceMappingURL 结尾,该引用只携带 combo 查询串,且按脚本自身目录而非文档解析。启动、index 渲染、脚本 GET 与 HEAD 都不会读取 map 文件;首次 map GET 才会读取并校验这些文件、组合一份 Indexed Source Map v3,并缓存该 body。

组件有自带 map 时直接用于对应 section;没有时则获得 identity section,其 sourcesContent 是捕获的 bundle,source 名取打包后的 sourceURL 或插件路由。

两条硬约束:每条启动请求 URL 按 UTF-8 字节计算都不超过 3 KiB,切分按更长的 map 形式计算;所有 application URL 都会预加载,所有 bootstrap URL 都会在图全局量与 Vite entry 之前执行。

错误路径也很明确:未知或被修改的资源列表、缺少 revision 及陈旧 revision 都返回 404,绝不提供其他字节,也不会让 SPA fallback 把 HTML 当作 JavaScript 返回;其他方法返回 405。

服务读取面与重建面

图是稳定对象,通知是拉取模型。(来源)

ClientModuleRegistry 暴露读取面与重建面:

  • graph() 返回当前组合出的图,两次变更之间是同一个稳定对象;
  • clientPath(id) 返回 bundle 绝对路径;
  • artifactBaseline(id) 返回读取当前快照前捕获的 stat 值,含 path、mtimeMs、ctimeMs 与 size;
  • fetchBundle() 返回与 HTTP 路由相同的响应,包资源每次请求都读取;
  • rebuilt(id) 发布没有伴随条目重启的 bundle 重建:从文件系统元数据派生 revision,只有 revision 变化才读取新字节、重新组合图并发出通知。

两条通知路径:onRebuilt 按发生变化的 bundle 逐个触发并携带新 revision;onGraphChanged 在任何一次重新组合了图的 flush 之后触发,采用拉取模型——监听器自行重读 graph()。两者都会兜住监听器异常,因此一个抛错的订阅者既不能让后续订阅者被跳过,也不能杀死触发这次 flush 的一方。

HMR 与页面本地状态

图描述目标状态,不声称 Host 清理已完成。(来源)

随包提供的 Web 组合通过 dsh-client-hmr 交付动态图快照。Host 立即转发现有图变化通知,重连会发送当前完整图。图描述浏览器的目标条目,不声明 Host 清理已经完成;产物轮询另外报告重建 revision。

仅 source map 变化不会触发重载;新 combo-map URL 只会在 bundle revision 变化后出现,每份 map body 由其首次 GET 固定。

Client Modules 校验快照,并将对账与重建串行协调;它持有启动创建的条目映射,负责单资源到达、异步移除、未使用模块与样式清理,以及页面本地重试状态。静态平台模块与 bootstrap 保持页面生命周期;Electron 安装属于独立流程。

验证:一个最小客户端模块

验证要覆盖声明、图、路由与注入四个面。(来源) 六步:

  1. 新建一个包,声明 dsh.client.platform = 'web' 并导出 ./client,重启后断言 graph().entries 出现该 id。
  2. 请求该包的 /plugins/<pkg>/client.js,断言 200 且带上 sourceMappingURL。
  3. 请求带陈旧 rev 的同一 URL,断言 404 而不是回退到 HTML。
  4. 请求 /plugins/<pkg>/client.js.map,断言首次 GET 生成并缓存组合 map。
  5. 改一行源码但不重启 fiber,调用 rebuilt(id),断言 onRebuilt 触发且 onGraphChanged 也随之触发。
  6. 只改 source map,断言 rebuilt 返回的 rev 不变,页面不重载。

如果第 1 步 graph 里没有该 id,先检查 exports["./client"] 与 dsh.client 是否都在同一个包的 package.json 里,而不是分散在子目录。

打包与 profile 的完整流程见插件 bundle;客户端资源生命周期的边界见客户端资源生命周期。

一句话收束: 四个面共用一份图、wire 就是协议、同名源冲突即失败、combo 只拼一次、map 首次 GET 才生成、通知是拉取模型。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的客户端模块靠什么声明,要写在 package.json 哪个字段?

靠 package.json 里的 dsh.client 与 exports。DSH plugin 要求 dsh.client 声明 platform 为 web,并在 exports["./client"] 导出构建好的 bundle。

DSH plugin 的启动脚本 URL 有长度限制吗,上限是多少?

有,DSH plugin 要求每条启动请求 URL 按 UTF-8 字节计算都不超过 3 KiB。DSH plugin 的切分按更长的 map 形式计算,避免 map 请求越界。

DSH plugin 的 source map 在启动时就读取吗?

不会,DSH plugin 在启动、index 渲染、脚本 GET 与 HEAD 时都不读 map。DSH plugin 只在第一次 map GET 时读取、校验并缓存组合结果。

DSH plugin 的图变化通知会推送负载,还是只是拉取信号?

不是,DSH plugin 用的是拉取模型。DSH plugin 的 onGraphChanged 不带载荷,监听器收到通知后自行重读 graph()。

相关术语

WebBootEntry
WebBootEntry 是 Host 组合出的一条客户端 entry 行,含 id、url、rev 与可选的 inject、immediately、external。— packages/client/modules/src/client/manifest.ts
WebBootBatch
WebBootBatch 是一个初始 combo 脚本描述,含调度阶段、URL、由行修订派生的 rev 与 entries 执行顺序。— packages/client/modules/src/client/manifest.ts
WebBootGraph
WebBootGraph 是注入为 window.__DSH_BOOT__ 的组合图,含一致性 rev、可选 release、entries 与 batches。— packages/client/modules/src/client/manifest.ts
artifactBaseline
artifactBaseline 是读取当前 bundle 前捕获的文件系统基线,含路径、mtime、ctime 与大小。— packages/client/modules/src/index.ts

来源