插件生命周期（可逆注册）

一句话定义

插件生命周期 = 插件从挂载到卸载的全过程管理，核心要求是「每个注册都有对应的撤销（disposer）」。

为什么必须可逆

不可逆的注册会带来三类问题：

实现方式

Cordis 提供两种自动管理的写法：

// 方式一：返回 disposer
ctx.effect(() => {
  const disposable = ctx.tools.register(tool)
  return () => disposable.dispose()
})

// 方式二：使用辅助方法自动管理
ctx.on('tools/pre-execute', handler)

官方规则：

每个注册都应有对应的 disposer：要么从 ctx.effect() 返回一个，要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求，请将相关工作放在同一个 effect 中。

teardown 顺序

顺序有时序要求。一个实际例子：

// 正确：先关监听器，再杀进程
async function dispose(proc) {
  proc.listeners.close()      // 1. 防止后续事件产生噪音
  proc.notifications.close()
  proc.kill()                 // 2. 发送终止信号
  await proc.done             // 3. 等待真正退出
  await proc.cleanup()        // 4. 清理资源
}

反模式：先 kill 再关监听器，导致进程退出事件触发时监听器已被移除或仍在处理，产生未处理的异常。

需要管理的资源

在 Agent Harness 中的位置

DeepSeek Harness 的整个架构建立在可逆注册之上：

这也是「一切皆插件」能成立的前提：如果插件不能干净卸载，就无法安全地替换。

相关

• Capability Seam（能力接缝） — 接缝的 Provider 需要可逆注册
• 第 8 讲 Skill 与插件体系
• Waterfall（瀑布式事件） — 事件监听是常见的可逆注册对象