Agent 框架源码
第 2 节:Cordis 只承诺三件事,插件才敢热插拔
Cordis 只承诺三件事:按 key 取服务、事件有五种分发语义、注册是可撤销副作用。第三件最容易被当成细节,但它是 fork Worker、热重载、多实例能成立的全部原因。
- 事件分发模式
- emit·waterfall·parallel·serial·bail五种语义,只能用对应方法分发
- 注册回收
- fiber dispose 时撤销统一走 ctx.effect 或 ctx.on 安装
- 限制作用域
- 必须 agent.ctx全局限制会屏蔽所有 agent,实现里直接抛错
插件只有两种写法,都不需要继承框架
Cordis 是 vendored 进 dsh 的底层框架。它刻意做得很薄,薄到可以用一句话概括:插件是一个往共享上下文里放东西的对象,放进去的每样东西都能收回来。
写法只有两种。第一种是函数,带可选依赖声明和 apply:
export const name = 'my-tool'
export const inject = ['tools'] // 声明依赖:等 ctx.tools 就绪才启动
export function apply(ctx: Context) {
ctx.tools.register(defineTool({ /* … */ }))
}
第二种是 Service 子类,服务名即上下文里的键。dsh 自己大量用这种:AgentLoop extends Service implements AgentFactory,构造时 super(ctx, 'agentLoop'),于是全仓通过 ctx.agentLoop 找到它。
inject 那一行是加载顺序的全部机制。没有「先启动 A 再启动 B」的编排代码——声明了依赖的插件会自动等依赖就绪。顺序由依赖图决定,不由文件名或挂载位置决定,这是插件树能稳定重组的前提。
五种分发语义:为什么拦截和观察不能混用
事件在 Cordis 里不是一种东西,是五种。每种只能通过对应方法分发,且分发模式属于事件的公开约定,新事件要用 @mode 标签记录,生成器会拿声明和调用点交叉校验。
| 模式 | 是否 await | 顺序 | 有返回值 | 典型用途 |
|---|---|---|---|---|
emit |
否 | 注册顺序观察 | 无 | 纯通知,比如 session/event |
waterfall |
否 | 环绕中间件 | 有 | 拦截与决策,比如 tools/pre-execute |
parallel |
是 | 全部并行 | 无 | 扇出,比如广播到多个消费者 |
serial |
是 | 按序执行 | 有 | 有序收尾,比如 agent/turn-stopping |
bail |
否 | 按序,首个 bail 值停 | 有 | 首个有效答案即终止,比如查补全 |
waterfall 是这里最需要理解的。它是环绕中间件:监听器收到 (...args, next),调 next() 才把控制权交给下游,下游的返回值从 next() 返回上来,可以再包装一层往外传。不调 next() 直接返回,就是短路。
情形一:全部委托(协作)
┌────────┐ next() ┌────────┐ next() ┌──────────┐
│ 监听器A │ ─────────→ │ 监听器B │ ─────────→ │ 默认实现 │
└────────┘ └────────┘ └──────────┘
↑ ↑ │
│ 包装后返回 │ 包装后返回 │ 原始决定
└─────────────────────┴──────────────────────┘
最终决定往外传
情形二:A 短路(行使决策权)
┌────────┐
│ 监听器A │ ── 不调 next(),直接 return { deny }
└────────┘
↓
B 和默认实现根本没执行 → 最终决定 = { deny }
// 真实调用点:packages/core/tools/src/pipeline.ts
const decision = await this.ctx.waterfall(
scopeTarget(this.tools, exec.agent), 'tools/post-execute', exec, result,
() => Promise.resolve<PostToolDecision>({ kind: 'accept' }), // 无人监听时的默认
)
最后一个参数是「没人管的时候怎么办」。这个默认值决定了语义方向:post-execute 默认 accept,所以它是可选增强;如果默认是 deny,它就变成白名单式准入门。
短路是设计意图,不是缺陷。拥有决策权的策略监听器可以不调 next() 直接返回;只做观察或标注的监听器必须委托。这两类混在一起,就会出现「一个日志监听器意外拦截了调用」这种极难查的 bug。
注册是可逆副作用:热重载能成立的全部原因
第三件事最容易被当成细节跳过,但它是「一切皆插件」真正落地的地方:所有注册都必须是可撤销的副作用。提示词片段、工具 schema、模型适配器、提供方、监听器,一律通过 ctx.effect() 或 ctx.on() 安装。
// 真实实现:packages/core/tools/src/index.ts
register(definition: ToolDefinition, options: ToolRegistrationOptions = {}): () => void {
const name = definition.name
// … 前置校验:output 必须带 render、schema 必须受支持、名字不能占用保留名
return this.layers.effect(
this.ctx,
layer => layer.tools.insert(name, { definition, when: options.when }),
{ label: 'tools.register()' },
)
}
register() 返回的就是那个精确的 disposer。插件 fiber 被 dispose 时,layers.effect 里的插入被撤销,工具从所有 agent 的可见集合里消失。
为什么非要这样?因为 dsh 的插件树会动。fork 一个 Worker 就是挂一个新 fiber,销毁就是 dispose 它。如果注册是永久的,跑上一天之后,工具表里会堆满死掉的 Worker 留下的条目,而且名字冲突会越来越频繁。
配套的还有作用域。同一份注册在不同 fiber 下效果不同:tools.restrict() 要求必须有 scoped context(agent.ctx),全局限制会直接把所有 agent 屏蔽掉,所以它在实现里直接抛错拒绝。这类「不给你犯错的机会」的校验,在 dsh 里密度很高。
第 3 节接着往下:这些 fiber、服务和注册,到底是怎么在启动时一层层叠出来的。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 从 vendored Cordis 源码与 tools.register 实现反推三个不变量 | 全页 |