第 12 课：组件加载器与 Koishi 案例

一句话版：这一课讲「组件加载器」——它把编排器写下的「想要什么组件」这份声明式配置，翻译成对运行中纤程的最小改动：条目按字段增量协调、改代码靠 HMR 不重启地热替换，而拥有 4000+ 社区插件的 Koishi 在真实生产中验证了这套设计的表达能力与通用性。

---

1. 为什么需要「声明式配置层」？

先回顾一下分工。 前几课我们认识了 Cordis 核心库的命令式原语：ctx.effect（安装效应）、ctx.use（加载组件）、ctx.set（提供服务）——这些是组件开发者在组件内部写代码时用的工具。

但「应用编排器」（把一堆现成组件组装成一个运行系统的人）面对的是另一类问题：

不是「怎么写一个组件」，而是「系统要哪些组件、它们的组合在系统生命周期里怎么变」。

Cordis 的答案是引入一个声明式配置层：

• 编排器用一份持久化数据结构描述「我想要的组合」——它只负责声明想要什么；
• 加载器把这份规格的每一次变化，翻译成相应的命令式纤程操作——它负责落实。

打个比方：编排器是「甲方」，只负责在图纸上改需求；加载器是「施工队」，负责把图纸的每一处修改精准地改到已建好的大楼上——而不是把楼推倒重盖。

1.1 配置树：条目就是「工单」

定义 26 说：一个条目（entry）声明一个纤程，并记录以下字段：

一句话记住：条目 = 一张「工单」，声明一个纤程该长什么样；运行时里，这个条目管理它所声明的纤程，并响应字段变化。

这些条目组织起来，构成一棵配置树——它是「系统当前加载了什么」的权威记录：

• 叶节点条目：映射到单个纤程；
• 分支节点条目：它的组件会继续加载更多组件，于是长出子树。

Cordis 还提供两个专用组件：@cordisjs/group 把一个子条目列表作为配置加载成子群组；@cordisjs/include 加载外部配置文件（YAML 或 JSON），把文件里的条目嫁接成一棵嵌套子树。

1.2 增量协调：只处理变化的字段

配置变了，加载器怎么落实？绝不整棵拆除重建，而是做增量协调：检查变化的字段，针对每个字段执行干扰最小的操作。

🎁 一个很容易忽略的妙处：@cordisjs/group 的 config 就是它的子条目列表，所以加载器以子条目的 id 为键做差分，分别创建、移除或更新各个子条目；而「更新仍存在的子条目」又会再次进入同一套按字段分派的过程——于是群组协调和条目更新沿着树一路递归下去。一套规则，处处适用。

另外，Cordis 还允许组件在运行时自己更新 config 或自行禁用。无论哪种情况，加载器都会把变更写回配置层——保证「持久化规格」始终忠实反映「正在运行的系统」，两边永不失联。

---

2. HMR：改代码不重启的三阶段

HMR（热模块替换，Hot Module Replacement） 是把「可回退效应」模式应用到模块层：

源文件变了（通常是开发期），系统原地替换受影响的模块，不重启进程。

为什么 Cordis 能做到？因为纤程已经为组件的所有效应和余效应划好了边界：释放旧纤程 = 自动恢复组件安装的一切；从重载后的模块实例化新纤程 = 把一切重新装回去。 模块本身就是组件，替换只需两个纤程操作。

对比 Webpack / Vite：它们的 HMR 需要开发者手写 accept 之类的接受边界（告诉构建工具「我这个模块允许热替换」），漏写就退化成整页刷新；Cordis 的 HMR 不需要任何开发者标注。

@cordisjs/hmr 组件提供 HMR 引擎，运行分三个阶段：

阶段 1：模块分类（算法 7）

引擎拿到两个输入：

• 暂存集（stashed）：自上次重载以来内容已发生变化的文件 URL；
• 外部模块集（externals）：无法热替换、会触发完整重启的模块。

然后对涉及变化的依赖子图做固定点计算，给每个模块打上「已接受」或「已拒绝」的标记：

（「固定点」就是说：以暂存文件的导入为种子，反复扩散，直到某一轮再也标不出新模块为止。）

阶段 2：失效条目检测（算法 8）

分类完，引擎用「已接受 / 已拒绝」去筛选组件条目，只保留依赖树可达已变更模块的失效条目：

• get_dependencies 沿依赖树收集一个模块的传递导入，遇到 declined 模块就停止（它是遍历边界）；
• 一个条目恰在它的依赖树与 accepted 相交时失效；随后这棵树被并入 accepted——于是沿途每个失效模块都会在下一阶段被作废。

阶段 3：事务性重载（算法 9）

最后，引擎先备份、再动手、失败就回滚：

function reload(ctx, accepted, staleEntries) {
  const backup = invalidateCaches(accepted);                       // ① 使已接受模块的缓存失效，并备份
  try {
    for (const entry of staleEntries) {
      entry.fiber.dispose();                                        // ② 释放旧纤程：自动撤销它安装的一切
      entry.fiber = ctx.use(import(entry.url), entry.config);      // ③ 导入新模块，换上新纤程
    }
  } catch (error) {
    restoreCaches(backup);                                          // ④ 失败：先恢复缓存
    for (const entry of staleEntries) {
      entry.fiber.dispose();
      entry.fiber = ctx.use(backup[entry.url], entry.config);      // ⑤ 用备份里的老组件重建每个失效条目
    }
    throw error;                                                    // ⑥ 把错误继续抛出去
  }
}

事务性保证：系统绝不会停在「只完成一半的重载」状态。若任一模块导入失败（比如出现语法错误），就恢复缓存，并用 backup[entry.url]（缓存刚被恢复的、重载前的组件）重建每个失效条目——所有已经完成的交换被整体撤销，就像什么都没发生过。

💡 小知识：在 Node.js 上，「使缓存失效」意味着同时清掉 ES 模块和 CommonJS 两套模块系统的缓存——因为经 ES 加载器导入的模块可能同时出现在两者之中。

把三阶段连起来，就是下面这条流水线：

---

3. Koishi：4000+ 插件的生产验证

前两节讲的是「设计」，这一节看「实战」。Koishi 是一个构建在 Cordis 之上的开源聊天机器人应用框架：经过四年多开发，积累了 4000+ 个社区贡献的插件，涵盖即时通信（IM）适配器、数据库驱动、管理控制台和面向终端用户的功能。这个规模和多样性，让它成为在生产环境中验证 Cordis 动态可组合性的代表性案例。

📌 两个术语小贴士：Koishi 现在用的是 Cordis v3，论文介绍的是细化效应/余效应语义、重新设计加载器的 v4，两者共享核心组合模型；Koishi 里的「插件（plugin）」就是论文里形式化的「组件（component）」。

Koishi 印证了 Cordis 模型的两组属性：

3.1 表达力与通用性：一个模型，两个世界

• 表达力：Koishi 作为服务端机器人运行，它的所有能力都是在上下文原语之上以插件形式实现的，Koishi 自己只提供聊天机器人领域的词汇——说明原语足以承载一个完整生产系统。
• 通用性：同样的模型出现在一个全然不同的运行时——Koishi 的 Web 控制台是另一个独立的 Cordis 应用，它的插件组合的是浏览器和用户界面的原语，而不是服务器原语。

同一个组合模型，同时跑在「服务端机器人」和「浏览器 UI」两个世界——这正是通用性的直接证据：模型只规定效应与余效应如何组合，把它们的含义留给各个应用决定，因此既不预设领域，也不预设运行时。

3.2 时间可组合性：开关插件，零认知开销

还记得论文第 1.2.1 节吗？传统插件系统无法在不重启宿主的情况下卸载单个扩展的效应。Koishi 却经常这么干：

• 编排器从控制台停用某个插件 → 它的效应随即在原处撤销；
• 开发期间，HMR 引擎在保存时重新应用编辑过的插件，同时保留系统其他部分的缓存状态与活动连接。

关键在于插件作者几乎无须为此付出额外工作：经由上下文安装的效应会被自动跟踪，其逆函数也会自动组合——即使经验不足的作者没写卸载路径，插件里经由上下文安装的效应也会按顺序得到清理。「关注点局部性」这个原本要靠每位作者勤勉才能满足的正确性要求，被这一抽象一次性统一履行。

3.3 空间可组合性：不同作者写的插件能拼起来

传统插件系统大多缺乏插件间依赖；Koishi 生态则呈现真正的依赖拓扑：

• IM 适配器提供对各个消息平台的访问；
• 数据库驱动提供持久化存储；
• 功能插件把这些能力声明为余效应并加以访问。

在运行时重新配置提供者（比如切换存储后端、重新连接适配器），只会重新激活那些解析结果发生变化的依赖方；依赖项暂不可用的插件会保持非活跃状态，直到该依赖项出现——不会报错。

而插件和它的依赖项通常由不同作者编写，作者之间除连接二者的余效应外无须协调任何事项。也就是说：反应式余效应让这个组合体在由独立贡献者构成的开放生态中保持一致。

---

4. 效度威胁：这份证据有多硬？

论文在结尾做了一次诚实的方法论自检，指出这份案例研究的两个局限：

1. 单一宿主语言：证据来自单一宿主语言（TypeScript）中的单一生态系统，所以无法把「范式本身的优点」与「TypeScript 实现或 Koishi 特定领域的优点」区分开；
2. 观察性证据：证据来自观察，而不是与替代架构的受控对比实验。

因此结论要读得准确：这个案例研究证明的是该范式存在且已被采用，而不是定量结果——以某个基线为参照、衡量这一抽象的开销及其对开发者生产力的影响，仍有待未来工作完成。

⚠️ 翻译成人话：这就像「名厨的菜好吃」能证明菜谱可行，但要说「比另一份菜谱好吃 30%」，还需要更严格的对照实验。

---

关键点回顾

这一课信息量不小，记住这五句话就够了：

1. 声明式配置层：编排器把「想要什么组件」写成配置树；条目（id / url / isolate / intercept / config / disabled）声明一个纤程，加载器把配置变化翻译成纤程操作。
2. 增量协调：只处理变化的字段——id/url 重建、isolate 迁移、intercept 原地更新、config 差分、disabled 卸载/加载；绝不整棵重建。
3. HMR 三阶段：模块分类（固定点：任一导入被接受则接受、全部被拒绝则拒绝、环内默认拒绝）→ 失效条目检测（依赖树可达已变更模块的条目失效）→ 事务性重载（先备份、换新纤程、失败回滚）；全程不重启，也无需手写 accept 边界。
4. Koishi 验证：4000+ 插件的生产系统，服务端机器人和 Web 控制台两个不同运行时都跑 Cordis——印证表达力、通用性，以及无认知开销的时间可组合性、跨开放生态的空间可组合性。
5. 效度威胁：证据来自单一宿主语言 + 观察，证明「范式存在且被采用」，而非定量结论。

🚀 下一课（第 13 课）我们进入论文的收尾——讨论、相关工作与总结，把「时空可组合性」范式放进更广阔的坐标系里看。