DeepSeek Harness 事件系统

基本用法

插件之间如何松耦合通信？事件是 Cordis 的通信核心机制。事件分监听与触发两端，ctx.on 注册的监听器会在插件卸载时自动移除：

// 监听事件
ctx.on('event-name', (payload) => {
  // 处理事件
})

// 触发事件：广播给所有监听器
ctx.emit('event-name', payload)

五种分发模式

每个事件有且只有一种分发模式，只能用对应方法触发。官方入门文档把 waterfall 标为「不 await」，但监听器通常是异步函数，示例里普遍写 await ctx.waterfall(...) 等待最终结果，两种写法都不算错。bail 模式下，监听器返回 null、false 或 undefined 表示「没意见」，第一个有效返回值即成为最终结果。

waterfall：流水线

监听器接收 (...args, next)，调用 next() 执行下游并取回其返回值，加工后向上返回：

const output = await ctx.waterfall('my-plugin/transform', input, async () => input)

ctx.on('my-plugin/transform', async (_input, next) => {
  const downstream = await next()
  return downstream.trim()
})

waterfall 监听器必须调用 next()，否则短路整条流水线——这是有意设计：拥有决策权的策略监听器可以不调用 next() 直接返回以拦截全链，仅做观察的监听器则必须委托给下游。

类型安全与两类事件

用 declare module '@deepseek-ai/cordis' 合并 Events 接口注册事件名与签名，拼错事件名或参数类型会在编译期报错。Harness 的 Cordis 事件遵循 namespace/action 命名，如 agent/step、tools/result、session/event。注意区分：turn/*、step/*、tool/call、tool/result、compaction/* 是持久化的会话事件类型而非同名 Cordis 事件，观察它们要监听 session/event 并检查 event.type。

动手示例：日志插件

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

export const name = 'tool-logger'

export function apply(ctx: Context) {
  // 每次工具执行完成都会触发
  ctx.on('tools/result', (exec, result) => {
    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
    const text = result.content
      .map(block => block.type === 'text' ? block.text : '')
      .join('')
    console.log(`[tool result] ${text.slice(0, 100)}`)
  })
}

小结自测

五种模式覆盖「广播、决策、按序、流水线、并行」五类契约；waterfall 必须调用 next()；声明合并让事件有类型保障。自测：哪些模式有返回值？waterfall 不调 next() 是 bug 还是设计？turn/start 这类持久化事件应监听哪个事件、检查哪个字段？