Автоматическая очистка и ctx.effect() в DeepSeek Harness
Предыдущая главаDeepSeek Harness: загрузка локальных плагиновВывод одной строки лога — это всё, что он делает, но настоящие плагины регистрируют слушателей, инструменты и таймеры.
В этом разделе решается одна проблема: когда плагин выгружается, кто очищает эти ресурсы?
Регистрация делегируется ctx, и очистка также делегируется ctx.
Механизм автоматической очистки
Всё, зарегистрированное через ctx — слушатели событий, инструменты, таймеры — автоматически очищается при выгрузке плагина.
Вам не нужно вручную вызывать removeListener или clearInterval.
Фреймворк может автоматически очищать, потому что все регистрации через ctx записываются в области Fiber плагина.
При выгрузке фреймворк отменяет их в обратном порядке регистрации.
Какие операции отслеживаются автоматически
Следующие операции автоматически отслеживаются и очищаются.
| Операция регистрации | Поведение при удалении |
|---|---|
| ctx.on(event, handler) | Слушатели событий автоматически удаляются |
| ctx.tools.register(tool) | Автоматическая отмена регистрации инструмента |
| ctx.llm.registerAdapter(names, adapter) | Автоматическая отмена регистрации LLM-адаптера |
| ctx.effect(() => cleanup) | Выполните возвращённую функцию очистки disposer. |
ctx.effect(): передайте ресурсы, управляемые вручную, фреймворку.
Некоторые ресурсы отсутствуют в приведённом выше списке, например сетевое соединение.
Используйте ctx.effect(), чтобы сообщить фреймворку, как его очистить.
ctx.effect принимает callback. В этой callback-функции создайте ресурсы и верните функцию очистки (disposer).
Этот disposer будет выполнен при выгрузке плагина.
disposer(функция очистки) — это возвращаемое значение callback-функции ctx.effect.
Он описывает «как уничтожить ресурсы, созданные в этот раз».
При выгрузке плагина фреймворк вызовет его.
Вот пример таймера heartbeat:
Пример
import type { Context } from '@deepseek-ai/cordis'
export function apply(ctx: Context) {
ctx.effect(() => {
// Создаём таймер: выводим heartbeat каждые 5 секунд
const timer = setInterval(() => {
console.log('heartbeat')
}, 5000)
// Возвращаемая функция очистки выполняется при выгрузке плагина
// Эквивалентно: не нужно вручную вызывать clearInterval в логике выгрузки
return () => clearInterval(timer)
})
}
Если при выгрузке ничего не нужно делать, disposer можно опустить.
Но как только такие ресурсы, как таймеры и соединения, созданы, обязательно возвращайте соответствующую функцию очистки.

Подробности порядка выполнения
При выгрузке плагина функции очистки вызываются в порядке, обратном порядку регистрации.
Несколько асинхронных функций очистки выполняются одновременно; нет гарантии, что они завершатся одна за другой.
Этапы очистки, имеющие зависимости по порядку, должны быть помещены в одну и ту же функцию очистки, возвращаемую одним вызовом ctx.effect(), и эта функция очистки отвечает за последовательное ожидание.
Примечание: это правило означает: сначала регистрируй, позже очищай — ресурсы, зарегистрированные позже, очищаются первыми.
Итог и самопроверка
Ресурсы, зарегистрированные через ctx, автоматически очищаются при выгрузке; для ручных ресурсов используйте ctx.effect(), чтобы предоставить функцию очистки.
Другие расширения
1. Нужно ли вручную вызывать clearInterval для таймеров, зарегистрированных через ctx?
2. Когда выполняется disposer из ctx.effect(() => disposer)?
3. Почему очистку, зависящую от порядка, следует помещать в один и тот же effect?