Автоматическая очистка и 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:

Пример

// Путь к файлу: scratch-plugin/src/heartbeat.ts
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?

Другие расширения