Cordis 是 DeepSeek Harness 底层的插件运行时。理解它的生命周期，是区分“能在升级中存活下来的插件”和“泄漏处理器、搞坏别人会话的插件”的关键。好消息是，这个模型很小：插件被加载、注册，然后被销毁。
三个阶段
| 阶段 | 发生什么 | 你该做什么 |
|---|---|---|
| 加载 | 运行时解析包并调用 apply(ctx) | 只注册你需要的东西，校验配置 |
| 活跃 | 事件触发、工具被调用、界面渲染 | 通过处理器响应，把状态保存在 profile 目录 |
| 销毁 | 运行时卸载插件并执行清理 | 释放资源，移除你添加的一切 |
中间那个阶段得到了全部关注，而大多数插件缺陷恰恰出在第三个阶段。
上下文对象给了你什么
apply(ctx) 收到的上下文，就是你在 harness 上的把手。这个对象有三点最重要。
作用域内的注册。 你通过上下文注册的任何东西都归你的插件所有。当插件被卸载时，运行时知道该移除什么。反过来，如果你把监听器挂到全局对象上，或者启动了一个永不停止的后台循环，这些工作就会比你的插件活得更久，并在一个你已不再与之有契约关系的 harness 上改动状态。
顺序。 插件按确定的顺序加载，并且可以依赖其他插件提供的能力。一个记忆提供方应当在消费者请求它之前就注册好这项能力。如果你的插件是提供方，就尽早注册，并让“已就绪”可被观测，而不是假定自己一定先启动。
事件。 事件处理器是大多数插件响应会话的方式：一轮对话开始、一个工具完成、一个会话结束。处理器要保持快。同步路径上的慢处理器会拖慢它后面的一切，而抛异常的处理器可能中断一轮用户本来没打算丢掉的对话。
销毁不是可选项
一个只注册、不销毁的插件会留下残留，症状有三种：重新加载后输出重复、处理器触发两次、长会话中内存缓慢增长。这三个症状都源自同一个错误，就是把 apply 当成了一条单行道。
避免它的做法是：一切都通过上下文注册，把清理交给运行时。下面这段代码展示了一个在销毁阶段被显式移除的处理器：
import type { Context } from '@deepseek-ai/dsh';
export function apply(ctx: Context) {
const onTurnEnd = (sessionId: string) => {
ctx.log.debug(`turn finished for ${sessionId}`);
};
ctx.on('session:turn-end', onTurnEnd);
ctx.onDispose(() => {
ctx.off('session:turn-end', onTurnEnd);
});
}如果你启动了定时器、打开了 socket 或派生了子进程，就在销毁路径里把它停掉。没有停掉的后台工作，是插件“看起来一切正常”却让 harness 在几个小时后变慢的最常见原因。
状态属于 profile
需要保存数据的插件，应当把数据写在 profile 目录内部，而不是某个全局缓存路径。有两个理由：卸载插件时能干净地移除它的数据；同时使用多个 profile 的用户，状态也不会互相串在一起。
保持格式向前兼容。在存储的 JSON 里放一个 schema 版本字段，现在不花什么成本，却能让你免于在再下一个版本上陷入迁移难题。
值得提前设计的失败模式
依赖缺失。 如果你的插件需要一项尚未注册的能力，就在加载时失败，并在报错信息里点明这项能力，以及你期望由哪个插件提供它。
事件负载发生变化。 负载会演进。校验你读取的字段，优雅降级，而不是在处理器里直接抛异常。
外部服务缓慢。 绝不要在同步路径上让会话等待一次网络调用。把工作放到异步里做，等结果回来再上报。
FAQ
我必须手动调用 onDispose 吗？
如果你的一切注册都通过上下文完成，运行时自会处理拆卸。对于上下文并不拥有的资源，比如定时器、socket 和子进程，你仍然需要它。
插件可以在不重启 harness 的情况下重新加载吗？
可以，这正是销毁正确性重要的原因。重新加载一个从不销毁其处理器的插件，损害会立刻显现出来。
如何调试加载顺序问题？
检查你的插件是否在别的插件消费它之前就注册好了能力。提供方插件应当尽早注册并暴露就绪状态。
生命周期在各版本间稳定吗？
概念是稳定的。具体的事件名和负载字段可能在预览版本之间变化，所以要校验你读取的内容。