【Cordis学习第四课】事件——让插件在“微信群”里广播消息,而不用互相@

插件通信只能一对一？

发一条消息，所有插件都收到

事件系统实战

Events · emit / on · waterfall

PART 01

最简单的例子

统计 + 报告

PART 02

五种分发模式

不只是广播

PART 03

深入 Waterfall

洋葱模型

PART 04

事件 vs 服务

何时用哪个

PART ///

写在最后

四课知识树

01

PART

先看一个最简单的例子：统计服务 + 报告监听器

FIRST EXAMPLE

创建统计服务（stats.ts）——它提供服务，也发出事件

import { Service, type Context } from '@deepseek-ai/cordis'

// 声明事件：'stats/report'事件会携带两个参数：事件名称和当前计数

declare module '@deepseek-ai/cordis' {

　　interface Context {

　　　　stats: StatsService

　　}

　　interface Events {

　　　　'stats/report'(name: string, count: number): void

　　}

}

export class StatsService extends Service {

　　private counts = new Map<string, number>()

　　constructor(ctx: Context) {

　　　　super(ctx, 'stats')

　　}

　　bump(name: string) {

　　　　const next = (this.counts.get(name) ?? 0) + 1

　　　　this.counts.set(name, next)

　　　　// 关键：计数变化后，发出事件

　　　　this.ctx.emit('stats/report', name, next)

　　}

}

export const name = 'stats'

export function apply(ctx: Context) {

　　ctx.plugin(StatsService)

}

创建报告插件（reporter.ts）——它消费服务，也监听事件

import type { Context } from '@deepseek-ai/cordis'

import type {} from './stats.ts' // 仅用于类型声明

export const name = 'reporter'

export const inject = ['stats'] // 依赖stats服务

export function apply(ctx: Context) {

　　// 监听'stats/report'事件

　　ctx.on('stats/report', (name, count) => {

　　　　console.log(`[stats] ${name} -> ${count}`)

　　})

　　// 触发几次统计

　　ctx.stats.bump('tool_call')

　　ctx.stats.bump('tool_call')

　　ctx.stats.bump('prompt')

}

组合配置（cordis.yml）

- name: './stats.ts'

- name: './reporter.ts'

[stats] tool_call -> 1

[stats] tool_call -> 2

[stats] prompt -> 1

声明事件：通过interface Events声明事件名称和参数类型，让TypeScript提供类型安全。

发送事件：ctx.emit('stats/report', name, next)。

监听事件：ctx.on('stats/report', (name, count) => { ... })。

自动清理：ctx.on()本身是effect，当监听器插件卸载时，监听器自动移除，无需手动removeListener。

02

PART

五种事件分发模式：不只是“广播”

5 DISPATCH MODES

emit：就像你在群里发了一条消息，发完就不管了，爱回不回。

parallel：就像你在群里发了一份问卷，等所有人填完才汇总。

serial：就像你挨个打电话问问题，第一个人回答了，后面的人就不用再问了。

waterfall：就像你在群里发了一句话，每个人都可以在上面修改，最后变成一个完整的结果（类似中间件）。

03

PART

深入 Waterfall：理解“洋葱模型”与短路机制

WATERFALL DEEP DIVE

import type { Context } from '@deepseek-ai/cordis'

declare module '@deepseek-ai/cordis' {

　　interface Events {

　　　　'demo/transform'(input: string, next: () => Promise<string>): Promise<string>

　　}

}

export const name = 'waterfall-demo'

export function apply(ctx: Context) {

　　// 监听器1：后注册，但它是“外层”

　　ctx.on('demo/transform', async (input, next) => {

　　　　const downstream = await next()

　　　　return downstream.toUpperCase()

　　})

　　// 监听器2：先注册，但它是“内层”

　　ctx.on('demo/transform', async (input, next) => {

　　　　if (input.includes('blocked')) return '** blocked **'

　　　　return next()

　　})

　　// 触发两次waterfall

　　void (async () => {

　　　　console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello'))

　　　　console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'hello'))

　　})()

}

HELLO

** BLOCKED **

监听器的执行顺序从先注册到后注册。但关键在于每个监听器中的next()调用会“跳转”到下一个监听器。

形成了层层包裹的结构：监听器1（外层）包裹监听器2（内层）；外层通过await next()等待内层执行完，然后对结果做后处理（转大写）；内层如果检测到'blocked'，直接返回拦截信息，不调用next()，从而短路了更内层的逻辑（本例中最内层是async () => 'hello'）。

即使内层短路，外层依然能捕获结果，并做统一处理（转大写）。

权限校验：外层负责记录日志，内层负责校验权限。校验不通过时，内层直接返回错误，外层记录日志后也返回错误。

缓存拦截：外层负责查缓存，内层负责查数据库。缓存命中时，外层直接返回，不再调用内层。

04

PART

事件 vs 服务：什么时候用哪个？

EVENT VS SERVICE

服务（Service）：用于“我需要一个特定的能力”。比如“我需要一个能统计的服务”，你会明确知道你要调用ctx.stats.bump()。

事件（Event）：用于“我想通知别人发生了什么事”或“我想在某个时机插入逻辑”。比如“用户提交了表单，我想让所有对此感兴趣的插件都能收到通知”。

///

LAST

写在最后

CONCLUSION

第一课：插件是什么——导出一个apply函数。

第二课：如何善后——用effect管理资源清理。

第三课：如何协作——用Service提供能力，用inject消费能力。

第四课：如何通知——用Event广播消息，用waterfall实现中间件链。