在 DeepSeek Harness 插件中注册 ctx.on(...) 并不难;真正棘手的是排查时才发现监听器没有按预期执行,或新加的监听器截断了其他逻辑。 实际开发中,最常见的问题有三类:
- 给
ctx.emit注册了一个async函数,以为发布方会自动await它执行完毕,结果后续逻辑已经继续运行; - 写了一个本想只打印日志的
waterfall监听器,却忘了在结尾调用next(),无意中把整条下游调用链短路了; - 想监听工具调用记录,直接去
ctx.on('tool/call', ...),等了半天却没有任何触发——因为tool/call根本不是 Cordis 事件名,而是session/event里的持久会话事件类型。
要在 DeepSeek Harness 中稳妥地发布和监听事件,关键是先厘清 类型契约、五种分发模式、waterfall 的环绕续传、Cordis 实时事件与持久会话记录的区别,以及 Fiber 生命周期清理 这五个方面。站内教程版可参考DeepSeek Harness:Cordis 事件如何发布和监听?。
一、怎样在插件里声明并发送类型化事件?
官方 Cordis 入门将类型化事件作为插件间的通信方式来介绍:插件通过 TypeScript 声明合并(declaration merging),把事件名和函数签名加入 @deepseek-ai/cordis 的 Events 接口。事件系统指南还提供了一个携带 payload 的同步 ready 通知示例。
把声明与收发组合在一个最小插件里,结构如下(从零搭建插件目录可参考开始开发第一个 DSH 插件):
import type {
Context } from '@deepseek-ai/cordis'
import '@deepseek-ai/cordis'
declare module '@deepseek-ai/cordis' {
interface Events {
'my-plugin/ready': (payload: {
id: string }) => void
}
}
export function apply(ctx: Context) {
ctx.on('my-plugin/ready', ({
id }) => {
console.log(`${
id} is ready`)
})
ctx.emit('my-plugin/ready', {
id: 'worker-1' })
}
这段最小示例体现了四个会直接影响排障的事实:
- 共享名称与 payload 类型:声明合并让监听方(
ctx.on)和分发方(ctx.emit)在编译期共享同一个事件名和参数类型; ctx.emit同步分发且忽略返回值:ctx.on负责注册监听器,ctx.emit则同步触发通知,并且完全忽略监听器的返回值;- 实时通知不是持久消息队列:这个示意通知只针对当前已注册的监听器触发;如果等到
ctx.emit之后才挂载插件、注册ctx.on,就收不到这条历史通知。实际插件必须在目标事件触发前完成注册,并遵循事件所属方定义的契约; - 日志边界:只有当 payload 里的数据确实允许写入日志时,才应当像示例这样直接打印。
二、五种分发模式怎么选?为什么不能随便换?
官方 Events API 参考列出了 Cordis 定义的五种分发方法。入门文档特别强调:分发模式本身就是事件公开契约的一部分。
无论是发布还是监听一个已有事件,动手前都应先查阅该事件所属子系统生成的类型签名和分发模式——绝不能因为另一种分发方法的返回形式更顺手,就在调用处擅自替换。
| 方法 | 监听器行为 | 结果 |
|---|---|---|
emit |
按注册顺序同步通知 | 忽略返回值 |
parallel |
并发运行监听器 | 所有监听器结束后 promise 完成,无结果值 |
serial |
按顺序等待,直到某个监听器中止 | 第一个中止值,若存在 |
bail |
按顺序同步调用,直到某个监听器中止 | 第一个中止值,若存在 |
waterfall |
每个监听器通过 next 包装后续链 |
最外层监听器的返回值 |
对照这张表,尤其要留意两个容易写错的细节:
1. serial 与 bail 的「中止值」到底是什么?
不少开发者会直觉地认为「返回 false 就代表拦截或中止」。但 Events API 的定义恰好相反:serial 和 bail 的中止值被定义为除 null、false、undefined 之外的任何值。
也就是说,监听器返回 false 或不返回值(undefined)时,分发器会认为「当前监听器没有中止」,并继续调用下一个监听器;只有返回了非 null / 非 false / 非 undefined 的具体值时,才会停止后续监听器的执行,并将该值作为结果返回给发布方。
2. parallel 是并发等待,不是顺序协调
当事件契约要求并发通知多个监听器、且发布方需要等所有异步处理完成时,才使用 parallel。注意:不要把 parallel 当成有顺序保证的协调机制——如果你写的逻辑依赖「前一个监听器改完状态,后一个监听器再读」,放在 parallel 中,就可能遇到竞态条件;文档并未保证监听器按特定顺序完成。
三、waterfall 监听器怎么协作才不会误伤下游?
五种模式中,waterfall 能力最强,也最容易因漏掉一行代码而引发生产故障。
1. waterfall 是环绕式中间件,不是平铺通知列表
在 waterfall 模式下,每个监听器接收的最后一个参数是 continuation 函数 next:
- 调用
next()会进入链条上的下一个监听器,层层向内,最终到达发布方提供的最内层行为; - 如果不调用
next()就直接返回,就会直接否决(短路)剩余的整条调用链。
事件系统指南中的 transform 示例展示了标准写法:先等待 next() 取得下游结果,再对结果执行 trim() 并返回。这意味着,一个 waterfall 监听器同时握有两项权力:既能决定下游还要不要运行,也能改写调用方最终拿到的返回值。
2. 观察型监听器 vs 策略型监听器
正因为权限很大,编写 waterfall 监听器前必须先明确自己的角色:
- 只负责观察或补充信息的协作监听器:通常必须继续调用
next(),把处理委托给下游。入门文档说明,协作监听器经常在修改共享请求或决定对象后继续委托,或者在拿到next()的结果后做包装替换。如果只是想打一行日志或做一次统计,却意外漏掉了next(),就会把后续正常业务全部掐断。 - 契约赋予决策权的策略监听器:如果事件契约明确允许某类策略监听器做拦截决策,它才可以有意不调
next()来短路后续链条。即便如此,也应在文档和代码评审里明确告知调用方与其他监听器这一预期行为。
3. 别把「返回 Promise」和分发语义混为一谈
关于异步,还有两个常见误解:
- 不要因为看到某个处理器返回了 Promise,就推断所有
waterfall事件都是异步的。API 返回最外层监听器的返回值;具体是同步还是异步,完全由该事件的类型签名定义,调用方应严格遵循签名; - 不要指望给
emit传一个async函数就能让发布方等待它。前面表里已经写明,emit忽略一切监听器返回值;给它注册异步回调,并不会把同步通知自动变成等待完成的屏障(barrier)。
归根结底:始终使用事件声明规定的分发模式,不要在调用处或监听处单方面改变它的语义。
四、在插件里增加监听器的五步标准流程
要在插件中稳妥地新增监听器,可按以下五步逐项核对。关于插件树与服务依赖的整体组织,可参考Cordis 插件树是怎么组织的与插件服务与依赖注入。
- 查清事件归属与契约:先找到事件所属的子系统,查阅生成的参考文档,确认事件名称、参数类型和分发模式。如果是你自己新增的事件,先按入门文档用
declare module '@deepseek-ai/cordis'声明类型签名,并在文档里写明它采用哪种分发模式。 - 在对应插件上下文注册:调用
ctx.on(name, listener)注册监听器。如果某个事件在生命周期内最多只需要响应一次,可以直接用ctx.once;这两个方法都会返回一个可随时调用的释放函数(disposer),用于提前移除监听。 - 严格按契约实现回调:如果是已有
waterfall事件,除非你的插件明确承担短路裁决职责,否则务必调用next();如果是观察型监听器,不要依赖任何会被emit/parallel忽略的返回值。 - 按所属方指定的方法分发:作为发布方时,只用契约规定的方法(如
emit、serial、waterfall),并且只在契约要求时await。至于异常抛出和取消(cancellation)怎么处理,要查阅该事件所属子系统的具体文档——通用 Events API 并没有规定一套通吃所有事件的错误恢复策略。 - 覆盖边界路径与卸载验证:用有代表性的监听器做验证,不仅要测正常路径,还要测「没有任何监听器注册时」以及「中途触发中止或短路时」的表现;最后卸载或重载插件,确认旧监听器已被彻底移除。
Fiber 生命周期、prepend 与 global
第 5 步提到的自动清理由 Cordis 的 Fiber 机制负责(作用域与资源释放的完整关系见插件作用域与资源清理):
- 通过
ctx.on注册的监听器归当前插件的 fiber 所有,插件卸载时会自动移除; - 如果你在一次更短的局部操作里提前调用了返回的
disposer(),且该监听器此前仍处于注册状态,它会返回true; ctx.once则会在第一次触发执行后自动释放自己;- 此外,API 还提供了两个会改变默认行为的选项:
prepend(把当前监听器插到已有监听器队列的最前面)和global(不受上下文过滤检查限制地接收事件)。这两个选项会直接改变执行顺序或接收范围,只有事件契约和插件设计明确需要时才应使用。
五、为什么监听 tool/call 没反应?分清 Cordis 事件与持久会话记录
排查「监听器不触发」时,最容易在这里走弯路:Cordis 实时事件不等于持久会话记录(session events)。
事件系统指南清楚列出了这两套名称:
- 真正的 Cordis 事件:例如
agent/pre-step、tools/result、session/event; - 持久会话事件类型(并非同名 Cordis 事件):例如
tool/call、tool/result、turn/*和step/*。
因此:
- 如果你想在插件里观察持久会话记录,正确做法是监听
session/event这个 Cordis 事件,并在回调中检查event.type,而不是去写ctx.on('tool/call', ...); - 反过来,Cordis 的实时通知不会自动持久化到磁盘。如果某项事实需要在进程重启或插件重载后依然保留,应该使用所属子系统文档规定的持久化机制,而不能指望
ctx.emit替你落盘。
指南还提供了监听 tools/result 的示例:先导入工具包的事件类型声明,再注册 ctx.on('tools/result', ...),从参数中读取工具执行信息和最终结果。这个示例有助于理解事件签名与生命周期,但生产环境有一条必须遵守的边界:不要把示例中直接打印参数和返回内容的日志代码原样搬进生产环境。工具参数与执行结果里极易包含代码、路径、凭据或业务敏感数据,采集范围和留存方式必须按实际部署要求严格控制。
监听器没执行时的四步排查表
发现注册的回调没有执行时,可以按下面四个方向逐一核对:
- 事件名与类型体系:确认你填的是真正的 Cordis 事件名(如
tools/result、session/event),而不是持久会话记录里的event.type; - 挂载与注册时机:检查插件是否已成功挂载,以及
ctx.on是否在目标事件触发之前执行; - 上下文过滤范围:检查当前插件所在的上下文(context filter)是否允许接收来自该来源的事件;
- 上游短路(针对
serial/bail/waterfall):检查排在前面的监听器是否已经返回中止值,或者是否有监听器在waterfall中有意/无意地漏调了next()。
还要注意:不要仅凭终端里没有某行日志,就断定事件没有分发。日志级别、输出通道或日志处理器自身的过滤条件,都可能让已经执行的回调在控制台里「看起来没动静」。
六、代码评审时,怎么检查一次事件改动?
在团队中评审涉及 Cordis 事件的 PR,不能只检查「回调函数写得对不对」,还要确认发布方和消费方遵守的是同一份契约:
- 核对契约四要素:在评审记录中写清事件所属方、参数类型、分发模式和监听器的作用范围,方便后续维护者判断这次改动是否破坏了上下游共同依赖的约定;
- 按模式验证返回值:通知类事件(
emit/parallel)的回调不应指望发布方读取其返回值;决策类事件(serial/bail)要分别测试「继续往下走」的返回值(null/false/undefined)和「应当停止链条」的中止值;对于waterfall事件,则从发布方拿到的最终结果向内追踪,分别检查正常调用next()委托和有意短路是否符合所属方预期; - 核对生命周期与重载表现:确认监听器是通过
ctx.on交由当前 fiber 托管,还是手工注册在 fiber 生命周期之外(后者必须自行负责清理);在支持插件热重载的场景下,重点对比卸载前后的行为,防止旧实例残留的监听器与新实例同时响应; - 核对顺序假设:检查是否把「依赖前一步处理结果」的逻辑放进了
parallel并发通知,或忽略了serial/bail中途停止后,后续监听器就不会再运行。
七、限制与安全边界
- 类型声明通过编译不等于运行时 payload 可信:TypeScript 声明合并能在开发期抓出签名不匹配的调用,但不能证明传入的 payload 数据安全可信,也不能保证各个监听器的内部实现正确。
- 监听器运行的是实打实的插件代码:
waterfall监听器可以直接篡改结果或阻止下游执行;当事件涉及安全策略、审批或外部操作时,必须一并审查处理器代码、注册顺序(含prepend)及所有权。 global会绕过上下文过滤检查:启用global选项会让监听器跨上下文接收事件,使用前必须确认其接收范围不会造成越权或串扰。- Cordis 事件不是持久消息总线:Events API 文档没有承诺持久投递、失败重试或跨进程消息队列能力,不要因为名字叫「事件」就假定它具备这些分布式总线属性。
- 参数与结果可能含敏感信息:避免在监听器里无差别打印 payload 或工具返回结果;分享诊断日志前务必先检查并脱敏。
八、相关术语速查
- 事件契约(Event Contract):事件所属方和消费方共同遵守的约定,包括事件名称、参数类型、返回值类型及分发模式。
- 监听器(Listener):通过
ctx.on/ctx.once在插件上下文中注册、用于接收和处理事件的回调函数。 - 中止值(Bail Value):在
serial或bail模式中,除null、false、undefined之外任何能够停止后续监听器继续执行的值。 - 续传函数(Continuation /
next):waterfall监听器接收的最后一个参数;调用它,执行才会进入下游调用链。 - Fiber:Cordis 中管理插件注册效果生命周期的所有者;当 fiber 释放(如插件卸载)时会自动撤销对应的事件监听。
相关阅读
本文依据 DeepSeek Harness 官方 Cordis 入门、事件系统指南与 Cordis Events API 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog