最近在研究 DeepSeek Harness 的插件开发,发现它底层 vendor 了一个叫 Cordis 的插件框架(源自 Koishi 生态)。官方文档的 Cordis Primer 信息量很密,我把它整理了一遍,并顺手把它和 Java 生态里大家更熟悉的 Reactor Flux、Spring 做了对比。如果你正在写 Harness 插件,或者单纯对"插件框架设计"感兴趣,这篇文章应该能帮你快速建立心智模型。
一、Cordis 是什么
Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。要读懂 Harness 子系统页面生成的服务/事件参考文档,需要先理解它的五个核心概念。简单说,它回答的问题是:“框架如何被插件扩展”——控制流、拦截点、依赖编排、生命周期,都在这一个框架里。
二、五个核心概念
- 插件是实现 Service 的对象。可以是一个带可选
inject和apply(ctx)字段的函数,也可以是一个Service子类,生命周期由 Cordis 挂载到当前上下文。 - 上下文是服务的容器。一个服务占据一个稳定的
ctx.<key>(如ctx.tools、ctx.llm、ctx.sessions);其他插件通过 key 查找服务,而不是 import 具体实现。 inject声明服务依赖。插件声明所需服务后,会等待服务就绪才启动——加载顺序由依赖关系表达,而非手动编排启动序列。- 类型化事件用于通信。服务通过 TypeScript 声明合并注册事件名,支持
emit、waterfall、parallel、serial、bail五种分发方式。 - 注册是可逆的副作用。提示词片段、工具 schema、适配器、监听器通过
ctx.effect()或ctx.on()安装,reload 和 teardown 时按预期撤销。
三、五种事件分发模式
每个事件有一种分发模式,且只能通过对应方法分发:
| 模式 | 是否 await | 分发顺序 | 有返回值 |
|---|---|---|---|
emit | 否 | 按注册顺序观察 | 否 |
waterfall | 否 | 按注册顺序观察(可包装) | 是 |
parallel | 是 | 所有监听器并行 | 否 |
serial | 是 | 按注册顺序 | 是 |
bail | 否 | 按注册顺序,遇 bail 值即停 | 是 |
分发模式是事件的公开约定,新事件通过 @mode 标签记录,生成的目录会做声明与调用点的交叉校验。
四、Waterfall:洋葱模型与短路语义
ctx.waterfall 是环绕中间件:监听器接收 (...args, next),调用 next() 执行下游,下游返回值经 next() 传回当前层,可被包装后继续向外返回;不调用 next() 直接返回则短路。
这对监听器提出了明确纪律:拥有决策权的策略监听器可以不调用 next() 短路;仅做标注或观察的监听器必须委托。prepend: true 只在必须在普通注册之前运行时才使用。
五、Loader 配置与实践规则
@deepseek-ai/cordis-plugin-include将!!js解析为表达式节点,在注入激活后基于插件上下文插值config,挂载决策时插值disabled;嵌套行表达式会保留到目标行激活。- 行为按域归位:工具流水线事件进
ctx.tools,模型流式输出进ctx.llm,实时 agent 协调进ctx.agents。 - 拦截和策略优先用事件;直接能力调用优先用服务方法。
- 每个注册都应有对应 disposer;teardown 顺序有要求的相关工作放进同一个 effect,确保按序释放。
六、横向对比一:Cordis vs Reactor Flux
看到这里你可能会问:这和 Reactor 的 Flux 差不多吧?——差很多,它们根本不在同一层:
| 维度 | Cordis | Flux |
|---|---|---|
| 本质 | 插件化架构框架(IoC + 事件 + 生命周期) | Reactive Streams 的 Publisher,0…N 元素异步序列 |
| 解决的问题 | 插件如何互相扩展、挂钩、安全挂载/卸载 | 异步数据流如何声明式变换、组合、背压 |
| 事件语义 | 离散扩展点/拦截点(waterfall 是洋葱中间件) | 持续数据序列流经操作符管道 |
| 背压 | 无概念(parallel 只是扇出) | 核心特性 |
| 生态对应物 | Koishi Cordis、tapable、VS Code API | RxJava / RxJS |
一句话:Cordis 管控制流,Flux 管数据流。Cordis 的事件更像类型化、可逆注册的 EventEmitter 加上 Koa 中间件。
七、横向对比二:Cordis vs Spring
这个直觉就对了——Cordis 的 IoC 部分基本可以看作 Spring 的迷你版,概念几乎一一对应:
| Spring | Cordis |
|---|---|
@Component / @Service | 插件(函数或 Service 子类) |
ApplicationContext | ctx 上下文 |
@Autowired / getBean() | ctx.<key> 按键查找 |
| 构造器注入 + 依赖图 | inject 声明,等服务就绪 |
@PostConstruct | apply(ctx) |
@PreDestroy / destroy() | disposer |
@EventListener | ctx.on(event) |
SpEL / @ConditionalOnProperty | !!js 表达式插值、disabled |
但有两处实质差异:
1. 事件的拦截语义。 Spring 的 ApplicationEvent 是纯观察式的——广播出去,listener 各看各的,无返回值、不能包装、不能短路。而 Cordis 的 waterfall(能改下游结果)、bail(遇值即停)是一等公民的可编程拦截链。在 Spring 里你得用 AOP MethodInterceptor 或 WebFilter 才能拼出等价物。
2. 热插拔。 Spring 的 bean 注册基本不可逆,单例常驻,卸载"插件"基本只能重启(OSGi 那种重方案除外)。Cordis 的核心设计就是插件可挂载、可 reload、可 teardown:万物皆有 disposer,卸载时事件监听、工具 schema、提示词片段全部按序干净撤销——这更像 Eclipse 插件体系或 VS Code Extension API。
八、总结
可以把 Cordis 理解为:Spring IoC 核心 + 事件总线 + AOP 拦截链 + OSGi 式热插拔的 TS 轻量浓缩版。写 Harness 插件时记住三条就够了:按键名找服务而非 import;拦截用事件、能力调用用服务方法;每个注册都配一个 disposer。而和 Flux 的关系则完全不同——一个是架构扩展点,一个是数据流管道,两者甚至可以在同一个系统里共存。
原文参考:DeepSeek Harness 官方文档《Cordis 入门》 https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/fenglingguitar/article/details/170712127




