Система событий 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: широковещательная рассылка
Все слушатели выполняются синхронно, а возвращаемые значения игнорируются.
Пример
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().
Пример
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, чтобы обеспечить типобезопасность событий.
Пример
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`.
Пример
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 обеспечивает типовые гарантии для имён событий и параметров.
Проверьте себя:
- Какой метод запускает каждый из пяти режимов диспетчеризации? У каких из них есть возвращаемые значения?
- Что произойдёт, если слушатель waterfall не вызовет next()? Это ошибка или так задумано?
- Для постоянных событий сессии, таких как turn/start, какое событие нужно слушать и какое поле нужно проверять?