Жизненный цикл плагина DeepSeek Harness: машина состояний Fiber

В предыдущих главах мы уже зарегистрировали слушателей, зарегистрировали инструменты и написалиctx.effect()。

Задумывались ли вы: в какой именно момент плагин начинает "работать" и в какой именно момент он начинает "выгружаться"?

В этом разделе представлена модель плагинов Cordis и машина состояний жизненного цикла, то естьмашина состояний Fiber。


Что такое Fiber

У каждого загруженного плагина естьFiberScope.

Fiber можно понимать как единицу выполнения экземпляра плагина; она хранит всё состояние плагина от объявления, загрузки и работы до выгрузки.

Через Fiber фреймворк знает, на какой стадии сейчас находится плагин и что можно сделать дальше.

Fiber: контейнер состояния экземпляра плагина в среде выполнения Cordis.

Он фиксирует состояние жизненного цикла плагина и также служит основой для очистки регистраций при выгрузке.


Машина состояний Fiber

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

Fiber 状态机

Основной путь:PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED。

Если apply выбрасывает исключение на этапе LOADING, он переходит вFAILED。

StateЗначениеКогда это происходит
PENDINGОбъявлен, но необходимые зависимости не готовыПлагин добавлен в контекст, а inject-сервисы ещё не готовы.
LOADINGЗависимости готовы, и выполняется apply.Все необходимые сервисы готовы, и фреймворк вызывает apply(ctx).
ACTIVEПлагин запущенapply завершается нормально, регистрация вступает в силу
ОШИБКАapply выбрасывает исключениеВо время выполнения apply возникает ошибка, и загрузка завершается неудачно.
ВЫГРУЗКАПлагин выгружается и освобождает ресурсыЗависимости исчезают, освобождаются, или HMR инициирует выгрузку.
ОСВОБОЖДЁНПолностью удалёнВсе функции освобождения выполнены

Терминология: inject — это поле, в котором плагин объявляет свои требуемые сервисные зависимости. Фреймворк ожидает, пока все эти сервисы не будут готовы, прежде чем выполнить apply.


Загрузка, управляемая зависимостями

Плагин, который объявляет inject, ожидает, пока все требуемые сервисы не будут готовы, прежде чем перейти в состояние LOADING.

Если зависимый сервис так и не появится, плагин останется в состоянии PENDING и не выполнит apply.

Пример

// Путь к файлу: scratch-plugin/src/my-plugin.ts
// Объявляем, что этому плагину требуются сервисы tools и llm; apply не выполнится, пока оба не будут готовы.
export const inject = ['tools', 'llm']

export function apply(ctx: Context) {
  // Когда выполнение доходит до этой точки, ctx.tools и ctx.llm уже должны быть готовы.
  // Здесь можно безопасно регистрировать инструменты и читать конфигурацию модели.
}

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


Механизм автоматической очистки

Любая регистрация, выполненная через ctx, автоматически отменяется при выгрузке плагина.

Это основная причина, по которой dsh умеет «убирать за собой», а также обязательное условие для безопасной горячей замены.

Операция регистрацииОчистка при выгрузке
ctx.on(event, handler)Слушатели событий автоматически удаляются
ctx.tools.register(tool)Автоматическое удаление регистрации инструмента
ctx.llm.registerAdapter(names, adapter)Автоматическое удаление регистрации адаптера LLM
ctx.effect(() => cleanup)Возвращённый disposer выполняется при выгрузке

Среди них ctx.effect используется для управления пользовательскими ресурсами, для которых нет готового "реестра" для отслеживания, например сетевых подключений.


Порядок вызова функций очистки

При выгрузке плагина функции очистки вызываются в порядке, обратном порядку регистрации.

Несколько асинхронных функций очистки выполняются одновременно; нет гарантии, что они завершатся одна за другой.

Шаги очистки, имеющие зависимости по порядку, должны быть помещены в одну и ту же функцию очистки, возвращаемую ctx.effect(), и эта функция очистки отвечает за последовательное ожидание.

Например, если вы регистрируете эффекты A и B последовательно, при выгрузке сначала вызывается функция очистки B, затем функция очистки A.

Если очистка B должна дождаться завершения очистки A, оба шага должны быть записаны в один и тот же эффект.


Практический пример: наблюдение за переходами состояний

Официальная документация использует следующий минимальный плагин для демонстрации логов загрузки и выгрузки.

Пример

// Путь к файлу: scratch-plugin/src/lifecycle-log.ts
// Используйте console.log для вывода событий жизненного цикла, наблюдайте порядок apply и effect
export function apply(ctx: Context) {
  // вызывается apply: плагин переходит из LOADING в ACTIVE
  console.log('загрузка примера плагина')

  // Регистрация эффекта: возвращаемая функция очистки выполняется при размонтировании
  ctx.effect(() => {
    // Регистрация эффекта завершена (apply всё ещё выполняется)
    console.log('пример эффекта зарегистрирован')
    // Возврат disposer: вызывается при выгрузке плагина
    return () => console.log('пример эффекта очищен')
  })
}

Вывод при загрузке:

example plugin loading
example effect registered

Вывод при выгрузке:

example effect cleaned up

Видно, что apply выполняется первым, затем выполняется регистрация эффекта, а возвращённый disposer вызывается на этапе выгрузки.


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

Конечный автомат Fiber описывает шесть состояний плагина от объявления до полной выгрузки; disposers очищают регистрации асинхронно и параллельно в порядке, обратном порядку регистрации.

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

  1. Каковы шесть состояний Fiber? В какое состояние он переходит, когда apply выбрасывает исключение?
  2. Почему слушатели, зарегистрированные через ctx.on, не требуют ручного removeListener?
  3. Если два шага очистки имеют зависимости по порядку, как их следует записать, чтобы это было безопасно?
Другие расширения