DSH plugin Client 模块:wire、扫描与 bundle 注入到底怎么接才不出错
客户端代码加载不到,通常不是构建失败,而是没进那张 entry 图。 DSH plugin 的 Client 模块服务把“扫描包”“组合图”“提供脚本”“注入 index”做成同一个服务的四个面;缺任何一面,页面都拿不到你的 bundle。 DSH插件 带了客户端代码却加载不到,先确认它有没有进那张 entry 图。
一个服务的四个面
它扫描、组图、发脚本、答注入,四件事共用一份状态。(来源)
dsh-client-modules 是 client 模块系统的 Node 半,以 ctx.clientModules 形式提供。它做四件事:
- 扫描宿主 Loader 的 entry,找出声明了
dsh.client的包; - 组合出
window.__DSH_BOOT__entry 图; - 在
/plugins下提供带版本的单资源或多资源 combo 脚本; - 以启动协议行回应每次 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 安装属于独立流程。
验证:一个最小客户端模块
验证要覆盖声明、图、路由与注入四个面。(来源) 六步:
- 新建一个包,声明
dsh.client.platform = 'web'并导出./client,重启后断言graph().entries出现该 id。 - 请求该包的
/plugins/<pkg>/client.js,断言 200 且带上sourceMappingURL。 - 请求带陈旧
rev的同一 URL,断言 404 而不是回退到 HTML。 - 请求
/plugins/<pkg>/client.js.map,断言首次 GET 生成并缓存组合 map。 - 改一行源码但不重启 fiber,调用
rebuilt(id),断言onRebuilt触发且onGraphChanged也随之触发。 - 只改 source map,断言
rebuilt返回的 rev 不变,页面不重载。
如果第 1 步 graph 里没有该 id,先检查 exports["./client"] 与 dsh.client 是否都在同一个包的 package.json 里,而不是分散在子目录。
打包与 profile 的完整流程见插件 bundle;客户端资源生命周期的边界见客户端资源生命周期。
一句话收束: 四个面共用一份图、wire 就是协议、同名源冲突即失败、combo 只拼一次、map 首次 GET 才生成、通知是拉取模型。
常见问题
靠 package.json 里的 dsh.client 与 exports。DSH plugin 要求 dsh.client 声明 platform 为 web,并在 exports["./client"] 导出构建好的 bundle。
有,DSH plugin 要求每条启动请求 URL 按 UTF-8 字节计算都不超过 3 KiB。DSH plugin 的切分按更长的 map 形式计算,避免 map 请求越界。
不会,DSH plugin 在启动、index 渲染、脚本 GET 与 HEAD 时都不读 map。DSH plugin 只在第一次 map GET 时读取、校验并缓存组合结果。
不是,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
来源
- DeepSeek Harness 官方参考 - Client 模块· deepseek-ai
- packages/client/modules/src/client/manifest.ts· deepseek-ai