ARTICLE · 1371753
03-Cordis地基-插件上下文与事件分发
从 0 到 1 学 DeepSeek Harness(三):Cordis 地基——插件、上下文、事件分发与可逆副作用
本系列基于 deepseek-ai/deepseek-harness@e8f7b93a(v0.2.2-rc.2)。前两篇我们认识了 dsh 的整体定位和 monorepo 布局。这一篇钻到最底层:Cordis——那个让"一切皆插件"成为可能的框架。理解了它,后面讲 Profile、LLM、Agent Loop 时你会觉得水到渠成。
Cordis 是什么,为什么 dsh 要自己 vendor 它
Cordis(仓库 vendor 的版本在 vendor/cordis/)是一个 TypeScript 插件框架,整个实现只有 9 个源文件、约 2800 行。dsh 不是通过 npm 依赖它,而是把源码 vendor 进仓库(vendor/ 目录还装着 cosmokit、schemastery 等配套库),原因在第二篇讲过:可以打本地补丁、控制版本、即时生效。
整个 harness 的哲学浓缩成一句话:
产品的每一部分都是插件,包括模型适配器、工具注册表、会话日志,以及 agent loop 本身,因此每个都可以从配置替换。
换句话说,不存在需要打补丁的特权内核。你想换掉 agent loop?你想让工具走不同的审批策略?你想把本地 bash 换成远程沙箱?在 dsh 里这些都是"在配置树里换一个插件"的问题——而这一切的机制基础就是 Cordis。
五个核心概念
docs/cordis-primer.zh.md 开篇就给出了五个核心概念,我按理解逐条展开:
1. 插件(Plugin)是实现 Service(服务)的对象。
插件可以是带可选 inject 和 apply(ctx) 字段的函数,也可以是一个 Service 子类。最朴素的插件长这样(来自 docs/cordis-tutorial/01-first-plugin.zh.md):
importtype{ Context }from'@deepseek-ai/cordis'exportconst name ='hello'exportfunctionapply(ctx: Context){console.log('hello from my first plugin')}这个文件只要放在 cordis.yml 的组合配置里就会被加载:
-name:'./hello.ts'注意插件里没有框架启动代码:插件只描述"我贡献什么",cordis.yml 负责"把谁组装进来"。Cordis 加载模块时会用 context 调用 apply(ctx),插件通过这个 ctx 注册一切。
2. 上下文(Context)是服务的容器。
一个服务占据一个稳定的 ctx.<key>:ctx.tools、ctx.llm、ctx.sessions……其他插件通过 key 查找服务,而不是导入具体实现。这是依赖反转的极致形态。
vendor/cordis/src/context.ts 的实现很有意思:Context 类本身是个代理(new Proxy(this, ReflectService.handler)),普通属性读取会经过服务解析器,而 extend() / isolate() / intercept() 会创建带作用域的子上下文而不修改父级。
extend() 创建原型继承的子上下文;isolate(name, label) 为某个服务创建独立的解析作用域;intercept(name, config) 给某服务的配置注入额外片段。这三个原语是 dsh 实现"按 agent 作用域隔离工具"、"按 profile 覆盖配置"的地基。
3. 通过 inject 声明服务依赖。
插件声明需要哪些服务后,Cordis 会等待这些服务就绪才启动插件。加载顺序通过依赖表达,而不是手动编排启动序列。这就是 Cordis 教程里强调的:"各项会并发启动,因此它们在列表中的位置不保证加载先后;顺序由服务依赖决定,而非文件中的位置。"
4. 类型化事件(Typed Events)用于通信。
这是 Cordis 最漂亮的设计之一。服务通过 TypeScript 声明合并(declaration merging)注册事件名,然后以五种模式分发。dsh 里大量使用:
declaremodule'@deepseek-ai/cordis'{interfaceEvents{'llm/adapters-updated'():void'llm/models-updated'(provider:string):void}}这就是在 packages/llm/llm/src/types.ts 里真实存在的代码。接口合并让事件名、参数、返回类型全部类型安全——写错的监听器在编译期就报错。
五种分发模式(表格来自 cordis-primer):
emit | |||
waterfall | |||
parallel | |||
serial | |||
bail |
emit 是"观察者模式":广播事实,谁爱听谁听。waterfall 是"环绕中间件":监听器拿到 (...args, next),调用 next() 执行下游,返回值逐层包装——这是 dsh 里策略钩子的载体。parallel/serial 对应并发/顺序异步处理。bail 是"第一个给出结论的说了算"。
5. 注册是可逆的副作用(Effect)。
提示词片段、工具 schema、适配器、提供方、监听器——一切注册都是副作用,会在插件卸载时自动撤销。这让 reload 和 teardown 变得可靠:你停掉一个插件,它装过的所有东西都被拆干净,不留垃圾。
Waterfall:最值得玩味的语义
Cordis 的 waterfall 语义(docs/cordis-primer.zh.md 有专门一节)是整个 dsh 拦截器架构的基石,值得多花几句:
ctx.waterfall是环绕中间件。监听器接收(...args, next)。调用next()会执行下游监听器;下游返回值通过next()返回当前包装层,可由该层包装后继续向外返回。不调用next()直接返回则短路。
协作式监听器通常修改共享的请求或决策对象,然后委托;也可以完全替换结果。对于单决策事件,短路是设计意图:策略监听器在拥有决策权时可以不调用 next() 直接返回(比如"这工具我拒绝执行"),而仅做标注或观察的监听器必须委托。
dsh 里的实例:agent/pre-step、agent/request、llm/stream、tools/pre-execute / tools/execute / tools/post-execute 都是 waterfall——监听器必须调用 next() 才能继续。我们到第五、六、八篇会反复见到它们。
Effect:Cordis 的可逆性如何落地
vendor/cordis/src/context.ts 的 docstring 说得很清楚:Context 是一个 proxy,属性读取走服务解析器;而 extend/isolate/intercept 创建子上下文。与可逆性配套的还有 ctx.effect()——vasdordis 提供"注册副作用并返回 disposer"的机制:
const dispose = ctx.effect(()=>{// 注册一些东西……return()=>{// 撤销……}})primers 里的实践规则是:
每个注册都应有对应的 disposer:要么从
ctx.effect()返回一个,要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求,请将相关工作放在同一个 effect 中。
这条规则保证 plugin 卸载时按声明的逆序拆掉所有注册,就像把积木一块块放回盒子。
dsh 里的事件域
dsh 在此基础上把事件分成三个域,各自有明确的持久性语义(docs/architecture.zh.md 的 Events 节):
session/event 广播的持久事实。需要"重启后还在"的信息放这里。agent/*):携带活跃 Agent:inbox、步骤、状态、请求、验证、续跑。用于观察或拦截进行中的工作。fs/*、tools/*、telemetry/*)附加策略和适配器。三者的分界是非常实用的工程决策:哪些必须落盘、哪些只在运行时流转、哪些是"插槽",dsh 用事件域把它们物理分开。
事件的"@mode"约定与生成目录
docs/cordis-primer.zh.md 提到:分发模式是事件公开约定的一部分,新的 harness 事件通过 @mode 标签记录模式,以便生成的目录可以把"声明"与"分发调用点"做交叉校验。
这让我们看到 dsh 工程体系的一个贯穿性特征(第二篇也见过):约定不是纸上的,而是可以机器校验的。事件声明写在类型里,分发调用点散落各处,生成器把它们对起来检查——事件名打错、模式用错,CI 会拦下来。
一个完整的迷你例子:从教程到 harness
Cordis 教程第七篇叫 07-into-the-harness,把学习者从玩具示例带进真正的 harness。docs/cordis-tutorial/ 一共有 7 章:
而 dsh 里已经写好的"最长插件组合"就是 packages/bundle/base/cordis.patch.yml——base 组合包,它是一份非常长的插件列表,由部署 overlay 再修补。它把模型适配器、工具、持久化、沙箱、审批、设置、凭据、遥测一次性组装起来。理解了 Cordis 的组合语义,这个文件就是"产品的配方单"。
深入源码:Context 是一个 Proxy
让我们真正读一点 Cordis 源码。vendor/cordis/src/context.ts 的 Context 构造函数非常简短但信息密度极高:
constructor(){this[symbols.isolate]= Object.create(null)this[symbols.intercept]= Object.create(null)const self =newProxy(this, ReflectService.handler)this.root = selfthis.baseUrl =undefinedthis.fiber =newFiber(self,{}, Object.create(null),null,()=>[])this.reflect =newReflectService(self)this.registry =newRegistryService(self)this.events =newEventsService(self)this.logger =newLoggerService(self)this.fiber._disposables.clear()return self}重点:
new Proxy(this, ReflectService.handler)——每次属性读取都会经过反射服务的解析器。ctx.llm、ctx.tools 这种"看起来像属性"的服务,实际上底层是消息解析;reflect(代理反射层)、registry(插件注册表)、events(事件总线)、logger(日志);fiber 是"纤程"——Cordis 用 Fiber 描述插件生命周期与副作用,所有 disposables 挂在 fiber 上,teardown 时统一清理;constructor 最后清空了 fiber 的 disposables——内置服务不是"被注册的副作用",而是根上下文的地基。再看三个扩展方法(docstring 都写得很清楚):
extend(meta):创建原型继承的子上下文,meta 属性覆盖继承值,父级不被修改——这是所有"子作用域"的基础;isolate(name, label?):为某服务创建独立解析作用域。isolate 返回的子上下文里,ctx.<name> 解析到新 label,不会影响父作用域——dsh 用这个实现"每个 agent 有自己的一套服务实例";intercept(name, config):为某服务注入配置片段,影响该上下文以下的所有插件。这三个方法的组合,就是 dsh 实现"作用域化 agent 上下文"的机制。比如 subagent(子 agent)场景:每个 agent 拿到一个 isolated 的 tools/fs 视图,共用同一个 llm(一张账单),工具可见性却不互相污染。
事件分发:events.ts 与五种模式的语义
vendor/cordis/src/events.ts(371 行)实现了事件系统。五种模式的设计意图我们已经在表格里看过,这里补几个源码层面的细节:
waterfall 的"短路"即决策。ctx.waterfall(carrier, name, exec, fallback) 的监听器签名是 (event, next)。监听器可以调用 next() 委托给下游并包装返回值,也可以不调用直接返回——短路。dsh 里几乎所有"策略决定处"都用它:agent/pre-step(接纳/改写/拒绝)、llm/stream(包装流)、tools/pre-execute(审批决策)。一个监听器说"不",整条链就停在那。
serial 是有序的 async 责任链。 与 waterfall 的区别是它不提供 next 包装语义,而是按注册顺序 await 每个监听器,返回值可被后续利用(agent/turn-stopping 就是 serial——没有 next,因为它是"收尾通告"而不是"策略委托")。
bail 是"第一个有结论的赢"。 监听器按序执行,直到某个返回 bail 值(真值),后面的不再执行。
每种模式都有明确的 await 性、顺序、返回值约定,这正是 @mode 标签能机器校验的原因:声明说 emit,分发就必须 emit,否则目录交叉校验会报错。
类型化事件:声明合并在 dsh 中的真实用法
Cordis 的类型化事件依赖 TypeScript 的模块增强(declaration merging)。dsh 的各包在自己的入口文件里这样"挂"事件名(真实代码,来自 packages/llm/llm/src/types.ts 和 packages/core/session/src/index.ts):
declaremodule'@deepseek-ai/cordis'{interfaceEvents{/** @mode emit */'llm/adapters-updated'():void/** @mode emit */'llm/models-updated'(provider:string):void}}declaremodule'@deepseek-ai/cordis'{interfaceContext{ sessions: SessionStore}interfaceEvents{/** @mode emit */'session/created'(this: Scoped<Session>, session: Session):void/** @mode emit */'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent):void}}注意到两个细节:
Context 也被合并:interface Context { sessions: SessionStore }——服务既挂事件又挂属性;@mode JSDoc 标签:生成目录的脚本解析 JSDoc,把事件声明与 ctx.emit/ctx.waterfall 调用点交叉校验。this: Scoped<Session> 这种签名表示事件带作用域过滤——dsh-scope 利用它实现"agent 作用域的监听者只收到自己会话的事件",这正是 Cordis 隔离语义与 dsh 子系统的结合点。Service:service.ts 的角色
vendor/cordis/src/service.ts(115 行)定义了 Service 基类。Cordis 的"服务"概念比普通对象多两样东西:
[symbols.config] 类型的配置描述(schemastery),intercept 就是往这个配置里注入片段;Service 子类的构造函数由 Cordis 挂载到上下文时调用,卸载时走 fiber 清理。dsh 里大量服务都是 Service 的子类,例如 ToolsService、LlmRuntime、SessionStore——它们都"占据一个稳定的 ctx.<key>",消费方通过 key 使用,通过事件观察,不需要知道具体类。这达成了第二篇说的依赖铁律:扩展依赖接口,不依赖实现。
Loader:配置如何变成运行中的插件
Cordis 生态还有一个配套包 @deepseek-ai/cordis-plugin-include——它解析 !!js 表达式节点(我们在第四篇会详述)。Loader 的工作是:
cordis.yml / cordis.patch.yml 的条目列表;config;disabled 字段;"条目并发启动、顺序由依赖决定"这个规则,就是 Loader 的实现行为:它不排序,而是让每个插件声明 inject,由 Cordis 在依赖就绪时自动激活。dsh 的 profile 启动器(app-boot)就是在这个 Loader 之上加了一层"profile → bundle → patch"的装配逻辑。
小结
Context 是一个 proxy,extend/isolate/intercept 提供作用域隔离的扩展点。waterfall 是 dsh 拦截器架构的灵魂:监听器调用 next() 委托、不调用则短路,单决策事件短路是设计意图。ctx 属性,@mode 标签让"声明与分发的交叉校验"可以自动化。Service 基类让服务可携带配置 schema 与生命周期;Loader 决定配置如何变成运行中的插件树。下一篇,我们站在 Cordis 的肩膀上看配置:Profile(产品形态)、组合包(bundle)和 patch(覆盖层)是怎么叠出一棵可拆可换的插件树的,以及 HMR 如何让配置热生效。
本文基于 deepseek-harness@e8f7b93a(v0.2.2-rc.2)源码与文档撰写。















































































