插件与生命周期
深入剖析 Cordis 插件的激活、依赖解析、就绪与卸载清理生命周期，掌握防内存泄漏的最佳实践。
在长周期自主运行的 AI 智能体系统中，插件并非简单地一次性加载并永久驻留内存。随着工具热更新、大模型适配器动态切换或多智能体子会话的创建与销毁，插件系统必须具备毫秒级动态调度与零残留资源回收能力。
在 DeepSeek Harness 底层，每一个插件实例均由一个轻量级的生命周期调度器——Fiber 进行状态控制。
本文将以一个 “分布式长连接网关与资源监控插件（Distributed Socket Gateway）” 为例，深入拆解 Fiber 六大生命周期状态机、ctx.effect 逆向清理与热重载自愈机制。
核心架构：Fiber 状态机与状态跃迁图
当一个插件被注册到 Cordis 微内核后，它将经历以下严格的状态机跃迁：
[ PENDING ] ──(所有依赖就绪)──> [ LOADING ] ──(apply 成功)──> [ ACTIVE ]
│ │ │
(缺少依赖服务) (apply 抛出异常) (卸载/HMR 重载)
│ ▼ ▼
└───────────────────────────> [ FAILED ] [ UNLOADING ]
│
(清理处置器完成)
▼
[ DISPOSED ]
状态机详细行为对照表：
| 生命周期状态 | 状态定义与微内核行为特征 |
|---|---|
PENDING | 插件已声明，但其在 inject 中声明的前置服务尚未完全就绪，微内核暂停执行挂起等待 |
LOADING | 依赖全部满足，微内核正在执行插件的 apply(ctx, config) 挂载函数 |
ACTIVE | 插件正常激活运行，事件监听器、工具与定时任务全部生效 |
FAILED | apply 执行期间发生未捕获异常，错误被沙箱隔离记录，不影响主进程 |
UNLOADING | 插件正在执行卸载，微内核并发触发 ctx.effect 中注册的所有 Disposer 清理回调 |
DISPOSED | 插件及其派生的所有子 Fiber 彻底销毁，内存句柄与网络连接完全释放 |
响应式自愈：基于 inject 的依赖驱动加载
通过导出 inject 数组，插件声明了自身运行所依赖的微内核服务：
import type { Context } from '@deepseek-ai/cordis';
export const name = 'distributed-socket-worker';
// 声明强依赖 tools 与 llm 服务
export const inject = ['tools', 'llm'];
export function apply(ctx: Context) {
// 微内核保证：进入 apply 时，ctx.tools 和 ctx.llm 必定处于 ACTIVE 状态
console.log('[SocketWorker] 前置依赖完全就绪，启动分布式服务通道...');
}
自动重载自愈特性（Self-Healing）： 如果运行时上游的
llm适配器被热替换或临时卸载，依赖它的当前插件会自动优雅卸载（ACTIVE → DISPOSED）；一旦新版本的llm适配器重新挂载就绪，微内核会自动重新激活当前插件，全程无需人工干预。
步骤一：使用 ctx.effect 实现精准资源释放
对于包含网络 Socket、数据库连接池或文件句柄等非托管资源的插件，必须通过 ctx.effect 注册析构清理函数：
import type { Context } from '@deepseek-ai/cordis';
import { createWebSocketClient } from './socket-client';
export const name = 'realtime-stream-gateway';
export function apply(ctx: Context) {
// 1. 被 Context 自动追踪的事件：插件卸载时由 Cordis 自动移除
ctx.on('trajectory/step', (step) => {
console.log(`[Stream] 捕获智能体执行轨迹: 步骤 #${step.index}`);
});
// 2. 外部物理资源：通过 ctx.effect 托管生命周期
ctx.effect(() => {
console.log('[Stream] 正在建立远程 WebSocket 长连接...');
const client = createWebSocketClient('wss://agent-hub.internal/events');
// 返回的 Disposer 函数将在插件进入 UNLOADING 阶段时被微内核自动调用
return async () => {
console.log('[Stream] 正在优雅关闭 WebSocket 连接并清理缓冲区...');
await client.close();
};
});
}
微内核自动托管的四大注册项：
ctx.on(event, handler)— 事件监听器自动解绑；ctx.tools.register(tool)— 大模型工具自动注销；ctx.llm.registerAdapter(name, adapter)— 推理适配器自动注销；ctx.effect(() => disposer)— 自定义资源连接池优雅释放。
步骤二：嵌套子 Fiber 与显式 dispose 销毁
当一个复杂插件需要在内部按需动态派生子插件时，可调用 ctx.plugin() 创建子 Fiber 控制句柄：
import type { Context } from '@deepseek-ai/cordis';
import SubWorkerPlugin from './sub-worker';
export function apply(ctx: Context) {
// 动态挂载子插件，并获得专属 Fork/Fiber 句柄
const workerFiber = ctx.plugin(SubWorkerPlugin, { workerId: 'worker-node-1' });
// 监听特定业务事件，显式销毁子 Fiber
ctx.on('admin/terminate-worker', async () => {
console.log('[Parent] 收到终止指令，正在注销子 Fiber 分支...');
await workerFiber.dispose();
});
}
调用 fiber.dispose() 会自顶向下递归触发该子树下的所有清理逻辑，并且其返回的 Promise 保证在所有异步 Disposer 全部执行完毕后才会 resolve。
常见问题解答 (FAQ)
Q1: 如果插件的 apply 函数在执行时抛出异常，整个 Harness 会崩溃吗？
解答：不会。Cordis 微内核在调用 apply 时内置了严格的异常隔离沙箱。发生错误的插件其 Fiber 状态会跃迁为 FAILED 并输出错误日志，而其他并行的插件和核心 Agent 循环依然保持健康运转。
Q2: 为什么不能把多个有严格先后顺序的清理逻辑分写在多个 ctx.effect 中？
解答：因为 Cordis 在插件卸载时，为了提高并发效率，会同时并发触发所有已注册的 Disposer。如果清理动作 A 必须严格在清理动作 B 之前完成，请将它们编写在同一个 ctx.effect 的返回函数中，并通过 await 顺序控制。
Q3: 父插件卸载时，通过 ctx.plugin() 挂载的子插件会自动被清理吗？
解答：是的。子插件继承于父级上下文作用域。当父插件被卸载时，微内核会自顶向下递归遍历子树，调用所有子 Fiber 的 dispose() 方法，确保整棵树上的事件与资源被全量释放。
Q4: 在 HMR 热重载代码时，旧版本的内存状态是如何被销毁的？
解答：HMR 监听到文件变动后，会首先调用旧模块 Fiber 实例的 dispose()，等待所有旧监听器注销与 ctx.effect 回调完成；随后重新 import 新模块，并为其分配全新的干净 Context 实例执行 apply()。