Waterfall（瀑布式事件）

一句话定义

Waterfall = 一种事件分发模式，监听器接收 (...args, next)，可以调用下游、包装返回值，或直接短路返回。

它是实现「不侵入主流程的横切关注点」的关键机制。

与其他分发模式的区别

Cordis 定义了五种模式，waterfall 是其中唯一具备环绕语义的：

前三种（emit、parallel、serial）的监听器是「旁观者」；waterfall 的监听器是「参与者」，能改变流程走向。

环绕中间件语义

type Listener<T> = (value: T, next: () => Promise<T>) => Promise<T>

// 监听器有三种选择：
// 1. 直接委托：调用 next()，返回值原样透传
// 2. 修改后委托：改 value，再调用 next()
// 3. 短路：不调用 next()，直接返回

这允许表达「我检查通过后让下游继续，然后我再看结果」这类逻辑，这是钩子列表做不到的。

在 Agent Harness 中的体现

DeepSeek Harness 的工具执行管线用三个 waterfall 承载全部治理：

tools/pre-execute  waterfall   ← hooks、权限、沙箱
tools/execute      waterfall   ← 超时、重试、指标
tools/post-execute waterfall   ← 接受、阻断、替换、添加上下文

官方文档说明了这样设计的价值：

This lets hooks span tool families without coupling the tools to one policy service.

即：钩子可以跨越工具家族，而不需要让工具耦合到某个具体策略服务。

短路是设计意图

对单决策事件，短路是正常的：

// 策略监听器：我拥有决策权，直接返回
ctx.on('tools/pre-execute', async (call, next) => {
  if (isDenied(call)) return { decision: 'deny' }   // 不调用 next
  return await next()                                // 委托下游
})

// 观察监听器：只记录，必须委托
ctx.on('tools/pre-execute', async (call, next) => {
  logger.info('tool call', call)
  return await next()                                // 必须委托
})

规则：拥有决策权的监听器可以短路；仅做标注或观察的监听器必须委托。

危险点

1. 未调用 next 导致意外短路：观察者忘记委托会静默截断流程。
2. 重复调用 next：会导致下游执行两次。
3. 错误处理不当：监听器抛异常需要被捕获，否则破坏整体流程。

相关

• Capability Seam（能力接缝） — waterfall 常作为接缝的扩展点
• 第 07 讲 工具执行管线
• 第 08 讲 Skill 与插件体系