ARTICLE · 1381485
DSH 系列·06|插件加载之后:沿源码看依赖、重载与释放

一个插件注册了工具、监听和连接,停用时能否把这些东西撤销?依赖服务换成另一份实现后,消费者会继续拿着旧对象,还是重新进入生命周期?
这些问题决定插件系统能否长期组合。本文沿 DSH 实际源码追踪加载、依赖、更新与释放,重点看 Cordis 的 Fiber,而不是把“支持热更新”当作一个无需解释的开关。
源码基线固定为 ca33fd6843b205e279c7ccb6cb73a472c78f5760。以下结论属于静态源码分析;行号对应这一提交,测试文件只用于核对设计意图,不代表本文执行了测试。
01先分清三种身份▪
●○源码阅读的前置与名词表
前置是能阅读 TypeScript 的对象、函数和 async/await。本文不要求先启动 DSH;终点是能够沿固定提交解释“依赖变化后为何先卸载旧实例,以及哪些清理会并行”。下文短代码是有范围的源码摘录,不是可单独执行的完整插件。
上下文 Context是插件访问服务、事件与资源归属的入口。callback是注册表最终采用的插件执行函数。runtime是围绕同一个执行函数复用的记录;Fiber是带着特定配置和依赖挂载的一份实例。这里的 Fiber 是 Cordis 源码对象,不表示操作系统线程,也不能套用其他框架同名概念的语义。
服务提供者发布一种能力,消费者在 inject 中声明要用它。uid区分同名服务键下不同的具体实现。epoch是本实现比较目标状态的字符串标记,包含实例修订号与依赖实现身份;不是时间戳。committed保存本轮已使用的依赖引用,卸载时仍据此解除关系。
effect(有归属的副作用)把资源取得与释放纳入 Fiber;disposer是实际撤销资源的函数;inertia在这里保存尚未稳定的异步过渡工作。HMR(Hot Module Replacement,模块热替换)涉及代码模块换新,不能与一次普通配置更新互换。
源码状态名中,Active 表示已激活,Loading 表示正在加载,Unloading 表示正在卸载;INACTIVE 是没有可用激活目标的标记。状态变化与异步过渡任务要一起看,不能只凭配置条目存在就推导实例已经 Active。
在阅读代码前,先区分模块、runtime 与 Fiber。
模块是导入得到的插件代码。插件可以是函数、对象或类,由注册表解析为可执行的 callback。
runtime 保存同一个 callback 对应的公共记录,例如插件名、配置 schema 和它拥有的 Fiber 列表。
Fiber 则是一份具体挂载实例,关联自己的父上下文、配置、依赖和副作用。相同插件可以产生不同 Fiber,因此不能用“一个包”替代“一个运行实例”来讨论退出。
在 vendor/cordis/src/registry.ts 第 316—335 行,RegistryService.plugin() 先解析 callback,复用或创建 runtime,再创建 Fiber。核心关系可以缩成:
const fiber = new Fiber( this.ctx, config, Inject.resolve(plugin.inject), runtime, getOuterStack,)这里省略了前后校验与包装,只展示依赖声明如何进入实例。注册表返回的包装对象还允许等待该 Fiber 的加载工作稳定。
02Loader 负责导入,再交给注册表▪
vendor/loader/src/config/entry.ts 第 263—275 行给出了配置条目的启动链:
moduleNamespace = await this.parent.tree.import( this.options.name, this.getOuterStack,)const plugin = this.loader.unwrapExports(moduleNamespace)await this._patchContext([])this.fiber = this.ctx.registry.plugin( plugin, this.options.config, this.getOuterStack,)Loader 读取条目中的模块名,解析导出,准备上下文,再把插件与配置交给注册表。因此,“安装了包”“配置中存在条目”“创建了 Fiber”“Fiber 已经 Active”是四个可以分别失败的阶段。
导入错误在这里被报告并退出;即使成功创建实例,后续也可能因依赖尚未就绪而等待。排错时应先确认卡在哪个阶段,而不是一律归结为插件没有安装好。
entry.ts 第 131—170 行还体现了另一层选择:禁用条目不会正常初始化;更新时会比较配置和上下文,决定走哪条处理分支。
03inject 怎样变成依赖关系▪
Fiber 创建时保留解析后的依赖声明。fiber.ts 第 338—346 行在初始插件通知后检查依赖,再调用 _refresh()。这种顺序允许相关观察者在激活前补充必要信息。
_refresh() 位于第 639—649 行。它从自身修订号开始建立 epoch,再逐个检查声明的依赖:
let epoch = `${this._revision}`for (const name of Object.keys(this.inject)) { const impl = this._store[name] if (!impl) { epoch = INACTIVE break } epoch += ':' + impl.uid}this._setEpoch(epoch)这段代码说明,激活条件不仅取决于服务名称是否存在,还把解析到的服务实现 uid 纳入目标 epoch。相同服务键换了实现,也可能改变消费者的生命周期目标。
_setEpoch() 第 652—666 行比较新旧目标:相同目标直接返回;从 Inactive 进入可用目标时加载,其余变化进入卸载。已有生命周期工作则通过 inertia 协调,避免把异步过渡当成一个瞬时布尔值。
这里还存在错误分支:失败的 Fiber 不会仅因普通目标变化就无条件自愈,代码要求通过 update() 清除 _error。因此,不宜笼统写成“依赖回来,一切失败都会自动恢复”。

●○手算一次 epoch,为什么同名服务还会触发变化
只考虑一个 tools 依赖,设 Fiber 自身修订号为 0,当前实现的 uid 为 101。按源码拼接规则,目标可写为 0:101。这些数字是为了手算的教学值,不是本文读取到的真实运行对象。
若 tools 暂时缺失,循环把目标设为 INACTIVE,不是生成 0:undefined 后照常运行。若同名服务换成 uid 202,目标变为 0:202;新旧字符串不同,框架需要协调旧目标退出与新目标进入。服务名称没变,服务实现身份已经变了。
这里的推导只说明 _refresh() 怎样形成目标,以及 _setEpoch() 怎样识别变化。不能从字符串变化直接跳到“新实例已经工作”:旧初始化可能还在等待、消费者可能未退出、释放可能尚未完成。可观察的 Active 与“已经请求切换”是两个时点。
04加载不是直接调用一次 apply▪
_reload() 第 703—731 行先把本次使用的依赖保存为 committed,并将消费者登记到提供者的 dependents 集合。随后才在目标 epoch 仍一致时执行插件。
这份已提交依赖关系很关键:卸载过程中需要知道“这次实例究竟依赖了谁”,不能在服务已经变化后只查当前配置。
若插件启动抛错,代码记录错误,并检查出错的加载是否仍属于当前目标。已经被更新目标取代的加载,不能把新目标直接标成失败。
随后还要重新检查目标。如果加载期间目标改变,就进入卸载清理;稳定后才清除当前过渡任务。这里处理的是异步工作可能被后续配置或依赖变化取代的问题。
在插件作者看来,这意味着初始化不应把“开始执行”当成“最终一定成为 Active”。资源创建与取消、清理必须配对设计,尤其是连接、子进程和异步注册。
●○加载还没结束,目标又变了,会发生什么
设初始目标为 A,_reload() 已保存 A 的依赖,插件初始化正在等待连接;此时依赖变成 B。旧加载结束时,代码再次比较目标;A 已过期,就走卸载,而不是把旧连接作为 B 的有效资源留下。等旧归属清理完成,才按当前目标继续加载。

图中的 A/B 是两次目标的示意标记,时间从左到右;不是声称两个独立插件一定串行运行。图只表达同一 Fiber 在目标变化下对旧加载、清理与再加载的协调。
“过期加载”与“当前加载失败”也有区别。_reload() 的错误分支仅在目标仍匹配时把错误写入当前状态,避免 A 的失败污染已切到 B 的目标;但 A 已取得的资源依然需要清理。反例是直接在模块顶层打开连接,这份连接若没有归属 effect,就不能从这些判断推导出自动关闭。
05卸载为什么先等消费者▪
_unload() 第 734—767 行的第一段,并没有立刻清理提供者自身:
while ([...this.provisions].some(impl => impl.dependents.size)) { await new Promise<void>((resolve) => this._release = resolve)}原因写在相邻注释中:消费者虽然已收到停用通知,但退出时仍可能需要访问它依赖的服务。因此,提供者先等这些消费者完成卸载,再释放自己的副作用。
消费者完成清理后,会从本次 committed 依赖的 dependents 中移除自身,并通知等待中的提供者继续。
这建立的是沿依赖关系的退出约束。例如,报告服务依赖数据库服务,报告服务退出时还要写最后一条状态;数据库连接不能先被关闭。
●○同一个 Fiber 的 disposer 并不保证逐个串行
第 742—752 行使用 Promise.all 处理自身的 disposables,并对每个释放错误分别记录。它与“按注册逆序逐个 await”不是同一种实现。
如果两个资源必须严格按顺序关闭,例如先停止接收新任务、再等待队列、最后关闭连接,应该把它们组织进同一个 effect 的释放函数中,显式写出顺序。
依赖图解决服务之间的所有权与退出关系;单个 effect 内的业务资源顺序,仍由插件作者表达。

●○effect 内部又是另一种顺序
继续看 fiber.ts 第 446—469 行,可以看到 effect() 为一次注册建立了自己的 disposer 数组,并用 disposing 保存是否已经开始释放。释放时先取出并反转数组;遇到异步结果后,把后续清理接到同一条 Promise 链上。
因此,准确的层级是:同一个 effect 内收集的释放动作按其实现安排逆序衔接;Fiber 卸载时,对它拥有的多个独立 effect 使用并行等待。把这两层混在一起,就会得到一个过度简化的“所有资源都按逆序串行释放”。
第 456 行在已开始释放时直接返回已有任务,也解释了为何同一个公开 disposer 不应重复执行清理。这个幂等边界属于该 effect;如果业务代码还在其他地方重复关闭连接,框架不能替它消除所有重复操作。
●○先登记所有权,再进入用户初始化
第 532—550 行先把 wrapper 放进 Fiber 的副作用列表,再执行用户提供的初始化。这样,初始化内部如果重入触发 owner 卸载,外层仍能看到这份尚未完成的资源归属。
若 setup 尚在执行,释放路径通过 barrier 等待;如果 setup 同步抛错,第 551—564 行处理已收集的回滚与任务收尾。这里解决的是“资源刚创建一半,退出就已经开始”的竞争情况。
普通的 try/finally 能处理单次调用中的资源,但插件系统还要处理外层 owner 随时变化。框架把初始化、所有权和退出放在同一个机制里,插件作者才不必到处维护互相独立的状态标记。
这种保障依赖资源确实被纳入 effect。模块顶层直接创建的定时器、与上下文无关的事件监听,不能因为文件被当作插件导入,就自动获得完整的回滚关系。
06restart、update 与热替换有什么区别▪
Fiber.restart() 第 790—795 行增加自身修订号,刷新目标,并等待生命周期工作稳定。它描述的是当前实例体系中的重新加载。
Fiber.update() 第 805—840 行先处理候选配置,保存原始配置并清除错误,再通过 internal/update waterfall 交给相应处理链。默认后续可以触发 restart,但监听者也可能处理更新而不重启。
因此,不能把所有配置更新都写成“必然销毁旧实例再创建新实例”。
Loader 还有更具体的优化。entry.ts 第 155—210 行检查是否只有符合约束的 volatile 配置变化:Fiber 必须 Active,上下文关系也要满足条件。满足时可以更新运行中的引用;候选无效时记录警告,保留已有运行引用。
这类“原始配置已保留、有效配置未改变”的状态,说明配置文件内容与运行实例实际生效值也需要区分。
●○模块代码是否换新,还要看上层组合
配置更新与“磁盘上换了一个包版本”仍不是同一层问题。后者涉及运行时解析、模块文件与 HMR 服务。
packages/boot/plugin-manager/src/index.ts 第 1347—1366 行中,publishAndReload() 与 reload() 根据 HMR 是否存在选择路径:没有 HMR 时检查保存的组合;有 HMR 时调用 reconcileProfile(),并返回 warnings、pending 或需要重启的原因。
不能据此承诺每次装包都能立即切换全部运行实例。包已经落盘与新代码已经接管运行状态,必须分别观察。
●○配置流与代码流,要用两条检查线
rawConfig 是保留下来的原始输入,effectiveConfig 是成功解析并提交给当前激活或有效更新的值。volatile 更新表示满足特定条件时保持正在运行的配置引用并更新内容;不是任意字段都能直接改内存,也不是跳过 schema。
源码中的 waterfall 是一条依次传递控制或结果的钩子链。update() 把解析后的候选交给更新链,并提供默认 restart 路径;监听者可能处理它而不重启。因此,看到配置文件变化时,先查候选校验、更新处理和最终有效值;看到包文件换新时,再查模块解析、HMR 与待重启结果。
例如“更新后工具出现两次”,可以先检查是否同时启用了本地 patch 和已安装 bundle;只有一个条目时,再查旧 Fiber 的 effect 是否撤销注册;释放正常但新代码未接管,再看 HMR 或 restart-required。修复后重复“启用 → 调用 → 更新 → 再调用 → 停用”这个相同序列,分别核对工具数量、实现版本与资源状态。本文说明如何设计这组检查,不把它写成已执行的测试记录。
07用回归用例检验理解▪
固定提交中的 packages/extensions/tool-cordis/tests/cordis-lifecycle.spec.ts 包含几个值得阅读的用例:
初始化过程中发生重入 restart,要等待 setup 与异步 cleanup。
同步 setup 失败时,已经收集的清理需要回滚。
普通释放可以同步完成,公开 disposer 多次调用不会重复清理。
卸载阶段再尝试注册新的 effect,会被拒绝。
这些测试表达的是对所有权和重入边界的要求,不意味着任何任意异步业务都能自动获得相同保障。插件绕开上下文创建的资源,仍需要自己接入释放路径。
插件管理器的 package-reload.spec.ts 还覆盖无 HMR 时保留运行版本、安装失败不发布解析结果,以及部分情况要求重启的分支。这与前面的源码路径相互印证。
阅读这些用例时,要把“测试断言了什么”与“在目标环境实际跑过什么”分开。平台、第三方连接与插件业务逻辑,需要额外的对应验证。
●○一个无 HMR 分支怎样读
package-reload.spec.ts 第 249—260 行检查禁用 bundle 但没有 HMR 的情形:返回结果包含 application: 'restart-required',运行中的 Fiber 仍是原对象,并且保持 Active,服务版本也仍是旧值。
这比“禁用按钮已经点了”提供了更准确的语义:期望配置发生变化,当前运行态尚未切换。等待重启时保留旧解析关系,是为了避免让仍运行的代码忽然失去自己的私有依赖。
这个用例只覆盖它构造的条件,不能扩大成所有禁用都会等待重启。对照前面的 reload(),关键条件仍是 HMR 是否存在、组合是否可协调,以及具体 pending 或 restartReason。
08写插件时可以带走的规则▪
依赖使用服务键声明,资源在创建时确定归属;异步初始化要能承受目标被后续变化取代,释放函数要覆盖正常退出和失败回滚。
遇到热更新问题,依次查配置条目、Fiber 状态、已提交依赖、effect 清理,以及模块解析与 HMR 结果。这个顺序能把问题定位到具体层次,也能避免用一次全局重启掩盖遗留资源。
需要保证先后顺序时,把规则写进同一释放过程;需要确认新代码已接管时,检查实际运行结果和待重启原因。插件的可组合性,最终依赖这些可以逐项复查的约束。
对于一个“更新后工具出现两次”的缺陷,可以据此分层调查:先确认是否存在两个配置条目,再确认同一 callback 下有几份 Fiber,接着检查旧 Fiber 是否进入卸载、工具注册是否属于其 effect,最后检查新模块是不是由另一条加载路径再次挂载。
如果直接从界面现象跳到“清一下缓存”,可能暂时隐藏重复,却留下真正的所有权问题。同样,连接未关闭时,应先查看消费者退出是否仍在等待、具体 disposer 是否未完成,再决定是否需要终止异常进程。
源码还保留了诊断入口,例如 getEffects() 可以查看已登记 effect 的元数据。诊断信息帮助理解归属,却不会自动证明某个第三方资源已正确退出;最终仍要用该资源本身的状态与任务结果核对。
参考资料
〔1〕固定提交:RegistryService:插件解析与 Fiber 创建。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/vendor/cordis/src/registry.ts
〔2〕固定提交:Fiber:依赖、更新与释放。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/vendor/cordis/src/fiber.ts
〔3〕固定提交:Loader Entry:条目导入与配置变更。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/vendor/loader/src/config/entry.ts
〔4〕固定提交:插件管理器:组合重载与 HMR 分支。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/packages/boot/plugin-manager/src/index.ts
〔5〕固定提交:生命周期回归用例:重入、回滚和释放边界。https://github.com/deepseek-ai/deepseek-harness/blob/ca33fd6843b205e279c7ccb6cb73a472c78f5760/packages/extensions/tool-cordis/tests/cordis-lifecycle.spec.ts
DeepSeek Harness / DSH · 项目速览
作者:deepseek-ai
地址:https://github.com/deepseek-ai/deepseek-harness
许可:MIT License
关注公众号
✦
关注公众号:开源技术探索
关注「开源技术探索」,持续阅读开源工具、开发实践与技术详解。

使用与内容说明
资料截至2026年11月18日。本文依据官方资料、相关原文与固定版本源码编写,示例需按实际宿主和服务核对;未将资料整理或静态分析写成软件实测。各软件和服务分别适用其授权与条款,源码开源不等于模型服务免费。















































































