Система событий DeepSeek Harness: emit / bail / serial / waterfall

Как плагины взаимодействуют слабосвязанным способом? События — основной механизм коммуникации Cordis.

Harness широко использует события для реализации расширяемых точек расширения. В этой статье чётко объясняются пять режимов диспетчеризации.


Базовое использование

События разделены на две стороны: прослушивание и инициирование.

Пример

// Прослушивать события: зарегистрировать обратный вызов
ctx.on('event-name', (payload) => {
  // Обрабатывать события
})

// Инициировать событие: широковещательная рассылка всем слушателям
ctx.emit('event-name', payload)

Слушатели, зарегистрированные через `ctx.on`, автоматически удаляются при выгрузке плагина.


Пять режимов распространения

Cordis предоставляет несколько режимов диспетчеризации, подходящих для разных контрактов взаимодействия.

五种分发模式行为示意图

ModeСпособ распространенияНужно ли ожидатьПоследовательностьЕсть ли возвращаемое значениеТипичные сценарии
emitШироковещательная рассылкаctx.emitнетВ порядке регистрациинетТип уведомления: все слушатели получают уведомление
bailДосрочное прерываниеctx.bailнетВ порядке регистрацииДаТип решения: побеждает первое допустимое возвращаемое значение
serialПоследовательностьctx.serialДаВ порядке регистрацииДаПоэтапная инициализация: выполнять по порядку и ожидать
waterfallКонвейерctx.waterfallнетВ порядке регистрацииДаЦепочка обработки: возвращаемые значения нижестоящих обработчиков оборачиваются слой за слоем
parallelПараллелизмctx.parallelДаВсе параллельнонетВеерная рассылка: несколько слушателей обрабатывают параллельно

Каждое событие имеет ровно один режим диспетчеризации и может быть отправлено только через соответствующий метод.

В официальной вводной документации `waterfall` помечен как «не await»; однако, поскольку слушатели обычно являются асинхронными функциями, в примерах руководства часто пишут `await ctx.waterfall(...)`, чтобы дождаться окончательного результата всей цепочки обработки. Просто запомните это различие — оба стиля допустимы.


emit: широковещательная рассылка

Все слушатели выполняются синхронно, а возвращаемые значения игнорируются.

Пример

// Сторона-инициатор: широковещательно отправить сообщение 'ready'
ctx.emit('my-plugin/ready', { id: 'example-worker-1' })

// Слушатель: получает сообщение ready, печатает лог
ctx.on('my-plugin/ready', ({ id }) => {
  console.log(`${id} готов`)
})

bail: короткое замыкание

Слушатели выполняются по порядку; первое возвращаемое значение, не являющееся `null`, `false` или `undefined`, становится окончательным результатом.

Пример

// Диспетчер: выполнить одну проверку, взять первый результат с возражением
const result = ctx.bail('some-check', input)

// Слушатель: если условие перехвата выполнено, вернуть 'blocked', иначе продолжить
ctx.on('some-check', (input) => {
  if (shouldBlock(input)) return 'blocked'
  // Вернуть null / false / undefined, чтобы указать 'у меня нет возражений', позволяя последующим слушателям продолжить.
})

serial: выполнять последовательно

Слушатели выполняются один за другим в порядке регистрации, ожидая асинхронные результаты.

Первое возвращаемое значение, не равное null, false или undefined, прекращает последующее выполнение.

Пример

// Последовательно выполнить поэтапную инициализацию, ожидая завершения каждой фазы
await ctx.serial('setup-phase', context)

waterfall: конвейер

Каждый слушатель может обернуть возвращаемое значение ниже по цепочке, образуя цепочку обработки.

Слушатели получают (...args, next); вызов next() запускает нижестоящие слушатели, а возвращаемое значение нижестоящего слушателя возвращается текущему обёртывающему слою через next().

Пример

// Диспетчер: начальное значение — input, передаётся первому слушателю
const output = await ctx.waterfall('my-plugin/transform', input, async () => input)

// На стороне слушателя: необходимо вызвать next(), после получения результата от нижестоящего слушателя обработать его один раз и затем вернуть.
ctx.on('my-plugin/transform', async (_input, next) => {
  const downstream = await next()
  return downstream.trim()
})

Слушатели Waterfall должны вызывать next(). Если не вызвать next(), весь конвейер прерывается; это намеренное проектное решение для реализации перехвата или логики шлюза.

Слушатели Strategy, когда они обладают правом принимать решения, могут возвращаться напрямую, не вызывая next(), тем самым блокируя всю цепочку.

Слушатели, которые только аннотируют или наблюдают, должны делегировать управление нижестоящему звену.


Типобезопасные события

Используйте объединение объявлений TypeScript, чтобы обеспечить типобезопасность событий.

Пример

// Путь к файлу: scratch-plugin/src/events.ts
import '@deepseek-ai/cordis'

// Объединение объявлений: регистрация имени и сигнатуры события
declare module '@deepseek-ai/cordis' {
  interface Events {
    'my-plugin/ready': (payload: { id: string }) => void
    'my-plugin/check': (input: string) => boolean | undefined
    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
  }
}

// После этого ctx.on('my-plugin/ready', ...) и ctx.emit('my-plugin/ready', ...)
// аргументы будут автоматически выведены; опечатки в именах событий или типах параметров приведут к ошибкам времени компиляции

События Cordis и записи сессий

События Cordis в Harness следуют схеме именования namespace/action, например, agent/step, agent/request, agent/request-error, tools/result и session/event.

Обратите внимание на различие между двумя типами событий:

EventsЧто этоКак наблюдать
agent/step, tools/result и т. д.События Cordis, распространяемые в реальном времениНепосредственно ctx.on('tools/result', ...)
turn/*、step/*、tool/call、tool/result、compaction/*Сохраняемые типы событий сессииСлушайте session/event, проверяйте event.type

turn/*, step/*, tool/call, tool/result и compaction/* — это сохраняемые типы событий сессии, а не одноимённые события Cordis.

Чтобы наблюдать за ними, слушайте session/event и проверяйте event.type.


Практический пример: плагин логирования

Официальная документация использует следующий плагин для логирования вызовов инструментов и результатов инструментов, прослушивая событие Cordis `tools/result`.

Пример

// Путь к файлу: scratch-plugin/src/tool-logger.ts
import type { Context } from '@deepseek-ai/cordis'
import '@deepseek-ai/dsh-tools'

export const name = 'tool-logger'

export function apply(ctx: Context) {
  // Слушать событие tools/result: срабатывает каждый раз, когда завершается выполнение инструмента.
  ctx.on('tools/result', (exec, result) => {
    // Вывести имя инструмента и аргументы
    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
    // Объединить текстовые блоки в содержимом результата и вывести только первые 100 символов.
    const text = result.content
      .map(block => block.type === 'text' ? block.text : '')
      .join('')
    console.log(`[tool result] ${text.slice(0, 100)}`)
  })
}

Этот плагин выводит имя инструмента, параметры и сводку результата в терминал после каждого вызова инструмента Агентом.

Слушатели регистрируются через `ctx.on` и автоматически удаляются при выгрузке плагина.


Итоговая самопроверка

Пять режимов диспетчеризации охватывают пять типов контрактов: broadcast, decision, sequential, pipeline и parallel; waterfall обязан вызывать next(); объединение declare module обеспечивает типовые гарантии для имён событий и параметров.

Проверьте себя:

  1. Какой метод запускает каждый из пяти режимов диспетчеризации? У каких из них есть возвращаемые значения?
  2. Что произойдёт, если слушатель waterfall не вызовет next()? Это ошибка или так задумано?
  3. Для постоянных событий сессии, таких как turn/start, какое событие нужно слушать и какое поле нужно проверять?
Другие расширения