花千树|企业级 Agent 工程化头像
Cordis 入门:DeepSeek Harness 背后的插件框架,以及它和 Flux、Spring 的本质区别封面图

Cordis 入门:DeepSeek Harness 背后的插件框架,以及它和 Flux、Spring 的本质区别

最近在研究 DeepSeek Harness 的插件开发,发现它底层 vendor 了一个叫 Cordis 的插件框架(源自 Koishi 生态)。官方文档的 Cordis Primer 信息量很密,我把它整理了一遍,并顺手把它和 Java 生态里大家更熟悉的 Reactor Flux、Spring 做了对比。如果你正在写 Harness 插件,或者单纯对"插件框架设计"感兴趣,这篇文章应该能帮你快速建立心智模型。

一、Cordis 是什么

Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。要读懂 Harness 子系统页面生成的服务/事件参考文档,需要先理解它的五个核心概念。简单说,它回答的问题是:“框架如何被插件扩展”——控制流、拦截点、依赖编排、生命周期,都在这一个框架里。

二、五个核心概念

  1. 插件是实现 Service 的对象。可以是一个带可选 inject 和 apply(ctx) 字段的函数,也可以是一个 Service 子类,生命周期由 Cordis 挂载到当前上下文。
  2. 上下文是服务的容器。一个服务占据一个稳定的 ctx.<key>(如 ctx.tools、ctx.llm、ctx.sessions);其他插件通过 key 查找服务,而不是 import 具体实现。
  3. inject 声明服务依赖。插件声明所需服务后,会等待服务就绪才启动——加载顺序由依赖关系表达,而非手动编排启动序列。
  4. 类型化事件用于通信。服务通过 TypeScript 声明合并注册事件名,支持 emit、waterfall、parallel、serial、bail 五种分发方式。
  5. 注册是可逆的副作用。提示词片段、工具 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 差不多吧?——差很多,它们根本不在同一层:

维度CordisFlux
本质插件化架构框架(IoC + 事件 + 生命周期)Reactive Streams 的 Publisher,0…N 元素异步序列
解决的问题插件如何互相扩展、挂钩、安全挂载/卸载异步数据流如何声明式变换、组合、背压
事件语义离散扩展点/拦截点(waterfall 是洋葱中间件)持续数据序列流经操作符管道
背压无概念(parallel 只是扇出)核心特性
生态对应物Koishi Cordis、tapable、VS Code APIRxJava / RxJS

一句话:Cordis 管控制流,Flux 管数据流。Cordis 的事件更像类型化、可逆注册的 EventEmitter 加上 Koa 中间件。

七、横向对比二:Cordis vs Spring

这个直觉就对了——Cordis 的 IoC 部分基本可以看作 Spring 的迷你版,概念几乎一一对应:

SpringCordis
@Component / @Service插件(函数或 Service 子类)
ApplicationContextctx 上下文
@Autowired / getBean()ctx.<key> 按键查找
构造器注入 + 依赖图inject 声明,等服务就绪
@PostConstructapply(ctx)
@PreDestroy / destroy()disposer
@EventListenerctx.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

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--