DSH 插件开发 · 第 6 章：组合与热重载 • 我的博客

本文对应官方教程第 6 章：组合与 HMR，示例代码在其基础上改编。

学习目标：掌握 cordis.yml 的身份与分组语义，跑通热重载，学会诊断停在 PENDING 的插件。

entry 的身份：id

前面几章的组合条目都只是模块路径，其实每一项都是完整的 entry 对象，支持元数据字段：

- id: my-greeter
  disabled: false
  ./greeter.ts:
    config:
      greeting: hi

多个 entry 可以打包成一个组（列表嵌列表），组内插件共享一个生命周期——一起加载、一起卸载，适合“一个功能由几个协作插件构成”的场景。反过来，isolate 让 entry 在独立的上下文里运行，与其他插件隔离（多租户/多配置实例时有用）。

这两个特性的日常使用频率不高，但读别人的 cordis.yml 时必须认识它们。

热重载由官方插件 @deepseek-ai/cordis-plugin-hmr 提供，把它加进组合：

- @deepseek-ai/cordis-plugin-hmr
- ./greeter.ts

之后修改 greeter.ts 保存，框架自动对该插件执行 unload → load：旧的 effect 全部清理（第 2 章的机制在这里兑现），新代码重新 apply。不需要重启进程，也不需要手动 dispose。

id 在这里变得致命：HMR 的 diff 以 id 为身份。没有 id 的 entry，每次重新读取组合文件都被视为一个“全新插件”——也就是说你改任何一行，它都会走“卸旧的 + 挂新的”全量重挂载，而不是原位重载。给想热重载的插件配 id，是教程里明确强调的实践。

插件永远不加载、日志也不报错？多半是卡在 PENDING——依赖的服务没出现（第 3 章）。最常见的原因是 inject 里的服务名拼错：框架忠实地等待一个永远不会来的服务。

诊断方法：在任意已加载插件的 apply 里（或调试入口）遍历注册表：

for (const fiber of ctx.registry) {
  if (fiber.state !== 'active') {
    ctx.log(fiber.id, fiber.state) // 例如: my-plugin pending
  }
}

把状态不是 active 的 fiber 挑出来，再结合它的 inject 列表逐个核对服务名，基本都能定位。