DeepSeek 发布了第一款 Agent 产品,DeepSeek Harness。这次的重点放在了运行时架构上,官方给的关键词是"everything is a plugin",模型接入、工具执行、会话记录、循环本身、界面,全部走插件机制。
这篇文章跳过 agent 领域已经成为共识的那部分——检测工具调用、执行、回填、循环,这套流程眼下几乎每个框架都长一个样,不值得再讲一遍。重点放在 DeepSeek Harness 真正跟别人不一样的几处设计:Cordis 这套插件运行时具体怎么管生命周期,preset 的 scope 继承链为什么拆成两层,Code Mode 为什么选了一个听起来不太"安全"的隔离方案,工具注册的遮蔽算法怎么写。顺带会跟 Codex 的几个具体工程决策做对比,只挑不一样的地方讲。
一、为什么是 Cordis
"everything is a plugin" 的基础是 Shigma 的开源项目 Cordis。定位是"Meta-Framework for Modern JavaScript Applications",一个通用的插件框架,处理依赖注入、作用域服务、生命周期清理这几件事,与 agent、与 LLM 都没有直接关系,在 DeepSeek Harness 出现之前就已经存在。
Cordis 在开源社区有实际的使用者。最典型的是 Koishi,一个跨平台聊天机器人框架(QQ / Discord / Telegram / 微信都接)。聊天机器人场景天然是"几十个插件拼在一起、热插拔、随时改配置",与 agent 的场景几乎相同,只是没有 LLM。DeepSeek Harness 把整个框架的源码 vendor 进自己的仓库,改了个 scope 叫 @deepseek-ai/cordis,然后把公司自己写的每一个包,都设成对它的 peer dependency。这比"使用一个第三方库"更进一步:整个产品都构建在 cordis 之上。
先对比几种常见的插件形态:传统 DI 容器、轻量钩子方案、Cordis。这三种方案各有取舍,值得摆在一起看。
传统 DI 容器的三个缺口。 "主流"方案是一个 DI 容器加生命周期注解。你 bind 了一个 service,谁来负责 unbind 和 cleanup?传统 DI 要么不管(泄漏),要么要求你手写 lifecycle hook。LLM provider 热替换了,依赖它的 ToolRegistry 应该自动重启,传统 DI 做不到这种"依赖驱动的重载"。配置上,传统 DI 的配置在启动时读一次;而 cordis.yml 里一行就是一个插件实例,改配置直接触发 HMR。
Pi也是Agent界的明星产品了,但Pi 的 Extension 走的是另一条路。 Pi 的自我定位是 "self extensible coding agent",它的插件叫 Extension(扩展),基于 TS,在扩展点上通过钩子塞逻辑:没有依赖注入,没有插件间依赖管理(加载顺序即优先级),也不能卸载。Cordis 的插件是带依赖声明、生命周期、可逆副作用的"组件":有依赖注入,有反应性 coeffects,插件间可以声明依赖,卸载时能完整逆转副作用。
这最后一点——"可逆副作用"——是整篇文章的地基。Cordis 的设计论文把这件事上升到理论层面,核心问题问得很直接:
有没有一种 programming model,能让动态本身具备类似进程那样的生命周期隔离?
进程和容器的好处在于:kill 掉再启动,状态就清空了。代价是重启会丢掉进程内的 cache、connection、partial computation。插件系统希望不用重启,也能完成同样的清理。论文为此给了两个定义:
- 时间可组合性:卸载组件时,组件对共享环境所做的修改必须被完整、安全地逆转——这要求追踪组件执行的每一次资源分配、事件注册和状态变更。
- 空间可组合性:依赖变化时,相关组件自动激活或停用。
时间可组合性是这篇文章的主线。剩下的事情——Fiber、effect、系统边界、preset、Code Mode——都在回答同一个问题:怎么在工程上实现"卸载 = 完整逆转"。
Cordis 生态还带了几个配套包,随项目一起 vendor 进来:一个配置文件加载器(负责解析 cordis.yml 这类声明式配置),一个 include 插件(负责把一份配置当成子树挂载进来,preset 机制用的就是它改名后的版本),一个 HMR 模块(支持插件热替换),外加日志和定时器这两个基础设施插件。这几块拼起来,才能真正理解"everything is a plugin"。
二、Fiber 与 effect:可逆副作用的地基
Cordis 里,插件的类型定义是一个联合类型:
type Plugin
裸函数、类、带 apply 方法的对象,三种写法最终都被解析成一个统一的回调。挂载一个插件调用 ctx.plugin(plugin, config),内部先找有没有已经存在的 Runtime 记录(按回调函数身份做 key,同一个插件多次挂载共享同一条 Runtime),没有就新建,再造一个 Fiber,塞进这条 Runtime 的 fibers 列表里。
Fiber 是插件实例的生命周期状态机,六个状态:PENDING、LOADING、ACTIVE、FAILED、DISPOSED、UNLOADING。插件声明了 inject: ['tools', 'shell'],对应的 Fiber 会停在 PENDING,直到这两个服务都在依赖链上出现,才真正跑这个插件的代码,进入 ACTIVE。这套等待机制是 Cordis 自己实现的依赖解析,插件作者不需要手写"等对方准备好"的轮询逻辑。这对应空间可组合性:依赖出现后,组件自动激活。
卸载一个插件是否安全,由 effect 机制决定。插件注册的任何东西——事件监听、服务、定时器——都通过 ctx.effect() 登记。登记时立刻执行一次,返回的撤销函数被推进一个 disposables 列表。论文 5.1.1 指出:Cordis 中每一次上下文变更都通过唯一原语 ctx.effect 完成——提供服务、实例化组件、所有修改上下文的操作都归约成一次 ctx.effect 调用。用法长这样:
ctx.effect(() => { // 做副作用:注册监听、开定时器、提供服务…… return () => { /* 逆:撤销上面的操作 */ } // 返回 disposer})
callback 可以返回一个 disposer 函数、一个 Promise
在这里,"副作用"的定义是:任何通过 Context 对共享环境进行的修改。这张表把日常操作都覆盖了:
| 类别 | 例子 |
|---|---|
| 事件注册 | ctx.on("foo", handler) —— 往共享事件总线挂监听器 |
| 提供服务 | ctx.provide(name, service) —— 往上下文上"放"一个服务 |
| 挂载子组件 | ctx.plugin(plugin) —— 子插件本身就是一个"父级上的副作用" |
| 上下文扩展 | ctx.extend() / ctx.intercept() / ctx.isolate() |
| 外部资源 | 定时器、文件监听、HTTP server、子进程、DB 连接等 |
| 状态变更 | 改 config、改注册表、改 store |
Koishi 里 ctx.command(...) 注册命令、ctx.router.get(...) 注册 HTTP 路由;DSH 里注册工具、挂 HMR 监听、起调度器——全是副作用。"怎么逆转",实现上很直接:每个副作用都带着自己的撤销函数,运行时把它们按 LIFO 叠起来,卸载时整体执行一遍:
disposables.splice(0).reverse().forEach(dispose => dispose())
按注册的相反顺序逐个撤销,类似退栈。子 Fiber 的销毁函数本身也是通过 parent.fiber.effect(...) 挂在父 Fiber 上注册的——在源码里就是 Fiber 构造函数末尾这一行:
this.dispose = parent.fiber.effect(() => { /* 注册插件 */ return async () => { /* 注销插件 */ }})
也就是说,一个插件本身 = 父 fiber 上的一个 effect:插件的启动逻辑就是副作用,卸载逻辑就是逆。子组件的逆会被 prepend 到父上下文的累加器上,形成递归结构(论文里叫 twisted composition,记作 𝜕²Γ)。所以卸载一个插件,会连带把它下面挂的子插件一起按栈的顺序拆干净,不需要单独维护一张"谁依赖谁"的清理表。
这个机制还有两个细节保证可靠性。一是幂等:dispose() 首次调用把 armed 标志置 false,之后再次调用直接返回——每个逆最多执行一次。"执行两次会在从未产生过该效应的状态上应用逆,无从还原。"二是中断:如果 callback 返回的是迭代器,每一步之前会查 guard,一旦失效立即停止,只执行已累积的逆——热重载、卸载中途失败都能安全停住。事件监听器也遵循同样的可逆机制:ctx.on(...) 返回 unsubscribe 函数,监听器登记在 fiber 的 hook 表里,fiber 卸载时统一移除。_unload() 跑完所有撤销函数后,如果发现依赖又重新满足了,会立刻调 _reload() 重新拉起来——"换掉某个服务的实现"在运行时层面就是一次自动的卸载再加载。
一个插件的写法大致是这样(在UI界面上添加一个时钟):
// 会话日志插件:注册一个事件监听 + 一个定时器,卸载时自动清理export const name = 'session-logger'export function apply(ctx: Context) { // effect 回调在注册时立即执行 ctx.effect(() => { // 副作用 1:订阅事件总线,把事件追加进日志 const off = ctx.on('tool/result', (event) => appendToLog(event)) // 副作用 2:开一个定时器,定期把缓冲刷到磁盘 const timer = setInterval(flushBuffer, 1000) // 返回撤销函数:卸载时按注册的相反顺序执行 return () => { clearInterval(timer) // 后注册,先撤销 off() // 再退订监听 } })}
挂载这个插件时,ctx.effect 的回调立即执行:监听器挂上、定时器启动,返回的撤销函数被推进 disposables 列表。卸载时(插件被移除、会话结束、HMR 重载),disposables.splice(0).reverse() 按逆序逐个执行——先 clearInterval,再 off()。撤销逻辑写在注册逻辑旁边,作者不需要在别处维护一份"哪里注销"的清单。
这个写法真的很像 React。 useEffect 的形状几乎一样:useEffect(() => { subscribe(); return () => unsubscribe() }, deps)——回调里做副作用,返回清理函数,组件卸载时自动调用。两边共享同一个核心约定:副作用和它的逆写在一起,销毁由框架触发。差异也清楚:React 的 effect 在渲染后执行,依赖变化时先清理再重建;Cordis 的 effect 在注册时立即执行,卸载时统一撤销,清理顺序有明确的 LIFO 保证(后注册的先撤销,子插件随父插件逆序级联)。
那"逆转"为什么值得花这么大篇幅?论文把"自进化 Agent Harness"列为两大动机之一,原文非常尖锐:
未来的 harness 会在持续服务请求的同时生成并部署对自己组件的修改……没有时间可组合性,每次自我修改都迫使完整重启,丢弃所有进程内累积状态;更糟的是,一个有缺陷的自我修改可能废掉唯一能用来恢复的那个进程。
这是"自进化"的前提:Agent 自己写插件/工具,运行时装进自己。装了坏的能回滚,而且回滚机制本身(宿主进程)不能被新组件弄坏。普通插件系统做不到这一点,因为重启宿主意味着丢失当前进程的所有状态。对照一下现有生态:VSCode 的扩展宿主无法卸载单个扩展,禁用/卸载必须重启整个宿主;Koishi 社区里,改完配置 reload daemon 是很常见的操作。Cordis 的逆转让"卸载"成为与"加载"对称的一等操作——服务不中断,其他插件不受影响。
这套机制顺带解决了两个常见工程问题。一是失败原子性:插件初始化中途抛错(配置校验失败、依赖缺失),fiber 进入 FAILED 状态并 dispose——已经应用的一半效应被逆序清掉,不会残留部分初始化状态。二是级联清理,作者不用写卸载代码。论文 5.3 的关键论断是:
因为通过 context 的效应被自动追踪、逆自动复合,即使是没经验的作者,也能为一个插件的 context 介导效应获得有序清理,而不用写卸载路径——正确性从依赖每个作者的自觉,变成由抽象层一次性承担。
卸载一个插件 → 逆序级联卸载它的子插件、释放它的定时器/监听器/HTTP server/DB 连接。清理正确性从"每个作者写对 deactivate"变成"框架结构保证"。VSCode 模型在这里有一个短板:它的 deactivate 钩子和 activate 分离,"效应清理与创建分离,违背关注点局部性,完整清理难以验证"。
逆转机制的关键作用可以归纳为四点:① 开发期 HMR(改代码不重启、出错可事务回滚);② 生产期运行时插件装卸(服务零中断);③ 自进化 Agent(改自己、坏了能自救);④ 失败原子性与级联清理(坏插件不残留影响、作者不用写卸载代码)。它把"卸载"从手动善后变成框架保证的结构性操作,这是"一切皆插件、插件可热插拔"能成立的前提。
三、四条约束与系统边界:框架怎么保证 effect 被执行
看到这里可能有人会问:如果作者把副作用写在 effect 外面,比如直接给 globalThis.foo 赋值,这套机制还有效吗?论文正面回答了这个问题。框架的处理分两边:一边在 API 层面约束,上下文修改只能通过 effect 完成;一边明确声明系统边界,边界外的操作不受追踪。
框架从四个层面约束 effect 的用法。
第一,API 入口唯一。想用框架的任何能力——事件 ctx.on、服务 ctx.provide、挂插件 ctx.plugin、配服务 ctx.use——都只有 ctx 这一个入口,而 ctx 上的每个操作内部都是 ctx.effect 的封装。API 设计上不存在绕过 effect 使用框架功能的路径。
第二,Context 是 Proxy。源码里就是一行:const self = new Proxy。对 ctx 的属性 get/set 全部走代理,这也是反应性 coeffect("访问即通知")和 interception 的机制来源。所以 ctx.foo = x 这种直接赋值也会被拦截并记录。
第三,生命周期状态机。每个 fiber 有状态机,ctx.effect() 第一行是 this.assertActive(),在已卸载的 fiber 上创建 effect 会直接抛 CordisError INACTIVE_EFFECT。卸载之后再注册副作用会被框架拒绝,从时间上消除了这类泄漏。
第四,事务性 HMR。即使作者的逆写得有问题,新代码 import 失败(比如语法错误)时,Algorithm 10 的 backup/restore 会让整个重载回滚到旧版本,系统不会停留在部分加载的状态。这是机制层面的最后一道保障。
边界外的操作,框架明确不追踪。 论文 §6.1 把环境分成两半:边界内(inside)是系统能独占修改、且能恢复原状的位置,操作记录在 Γ,可以 recover;边界外(outside)二者缺一,操作表现为 idΓ,既不追踪也不恢复。注意边界按位置划分,与介质无关:私有路径的 scratch 文件、只有本系统写的内存属于边界内;公共文件、别的进程也在写的东西属于边界外。直接改全局变量、monkey-patch、写公共文件,都是边界外的操作。框架不会追踪这些操作,也不会声称能恢复它们。这是设计上明确声明的边界。
更细的一层是获取/发射两阶段:获取阶段(open/malloc/fork)在边界内、可逆;发射阶段(write/send 的数据离开系统)在边界外、不可逆——恢复只能靠 withholding(暂缓发射,直到状态确定)或 compensation(补偿动作:删除创建的文件、退还收到的款项)。补偿也按 LIFO 组合,但元理论不再保证。
工程上怎么处理边界外的资源?论文 §6.1 给了一个手段:coeffect 通过物化外部位置来移动边界——把所有对该位置的访问限制在一组操作内,其中每个操作都提供逆,于是原本表现为 idΓ 的操作变得可追踪、可恢复。在工程上,这就是服务(service)抽象:开发者通过 ctx.database、ctx.assets 访问这些资源,不直接接触数据库连接、文件句柄、子进程。资源生命周期被关进服务自己的 effect 里,服务提供者负责写对的逆,消费者只面对高层接口。副作用从插件代码各处集中到服务实现内部,作者义务集中到少数服务实现者身上。
还有最后一个问题:逆写得对不对,怎么判定?论文 §3.3.2 不要求"物理复原",因为那做不到(free 不会还原堆布局,生成式名字不会再生)。恢复保证读作观察等价:
两个状态相关,当没有任何观察者能区分它们。比较行为而非表示……等价关系由 coeffect 各自携带的等价组装而成。
"逆转"的含义是观察层面的还原:恢复前后的状态,没有任何观察者能区分。这就是逆的正确性标准。堆布局没有还原也没关系,只要没有任何 coeffect 操作能察觉差异,就算恢复成功。
这一章的保证可以分层整理成一张表:
| 层次 | 谁保证 | 内容 |
|---|---|---|
| 路径强制 | 框架(API 设计) | 用框架功能只能走 ctx,ctx 内操作全是 effect 封装 → 必然被追踪 |
| 时间强制 | 框架(状态机) | 已卸载 fiber 上建 effect 直接抛 INACTIVE_EFFECT |
| 属性拦截 | 框架(Proxy) | ctx 属性读写被代理拦截、可记录 |
| 模块级事务 | 框架(HMR backup/restore) | import 失败整体回滚,不进半重载态 |
| 逆的正确性 | 作者义务 | 运行时不验证 witness(g(δ)=γ),论文明说 |
| 边界外行为 | 无保证 | 全局变量 / 公共文件 / 发射出去的数据 = idΓ |
| 边界移动 | coeffect / 服务物化 | 把外部位置封装成"可逆的服务",访问受限、逆由服务提供 |
总结一下。框架把"必须通过 ctx.effect 修改上下文"变成唯一路径,把"逆是否正确"留给作者义务,并明确声明系统边界。工程上的落点是服务物化:副作用集中在服务实现内部,义务从"每个插件作者"收敛到"少数服务实现者"。论文还有一句很诚实的话:"回调提供了逆,但该逆是否真的恢复了伴随它的效应,是组件作者的责任(obligation),而不是运行时验证的性质(property)"。运行时保证"逆会被调用"(结构性),不保证"逆写得对"(语义性)。
顺带一个观察:这套设计在 TS/JS 里落地最直接。 大多数编译语言的类型系统基于类,类型布局在编译期固定,无法通过动态加载新的编译结果来覆盖;加载进内存的类型信息通常也无法卸载。TS/JS 是原型系统,类型结构可以动态调整:Agent 造一个新工具,直接…