Ciclo de vida de complementos de DeepSeek Harness: máquina de estados Fiber

En capítulos anteriores ya hemos registrado listeners, herramientas, y también hemos escritoctx.effect()。

¿Alguna vez te has preguntado: en qué momento exacto un complemento comienza a «ejecutarse» y en qué momento comienza a «desinstalarse»?

Este capítulo presenta el modelo de complementos de Cordis y la máquina de estados del ciclo de vida, es decir,Máquina de estados Fiber。


¿Qué es Fiber?

Cada complemento cargado posee unFiberalcance (scope).

Fiber puede entenderse como la unidad de ejecución de la instancia del complemento; contiene todos los estados del complemento, desde la declaración, la carga, la ejecución hasta la desinstalación.

El framework sabe a través de Fiber en qué fase se encuentra un complemento ahora y qué puede hacer a continuación.

Fiber: el contenedor de estado de una instancia de complemento en el runtime de Cordis.

Registra el estado del ciclo de vida del complemento y también es la base para limpiar los registros al desinstalar.


Máquina de estados Fiber

Los estados de Fiber migran en el siguiente orden, describiendo la vida completa de un complemento desde la carga hasta la desinstalación.

Fiber 状态机

El camino principal esPENDING → LOADING → ACTIVE → UNLOADING → DISPOSED。

Si apply lanza una excepción en la fase LOADING, se pasa alFAILED。

estadoSignificadoMomento en que ocurre
PENDINGDeclarado, pero las dependencias necesarias no están listasEl complemento se añade al contexto; los servicios de inject aún no están listos
LOADINGDependencias listas, ejecutando applyTodos los servicios necesarios están listos; el framework llama a apply(ctx)
ACTIVEComplemento en ejecuciónapply retorna normalmente; los registros entran en vigor
FAILEDapply lanza una excepciónSe produce un error durante la ejecución de apply; la carga falla
UNLOADINGEl complemento se está desinstalando y liberando recursosLas dependencias desaparecen, se llama a dispose, o HMR desencadena la desinstalación
DISPOSEDTotalmente desinstaladoTodos los disposers se han ejecutado

Terminología: inject es el campo donde el complemento declara las dependencias de servicios que necesita; el framework espera a que todos estos servicios estén listos antes de ejecutar apply.


Carga impulsada por dependencias

Un complemento que declara inject espera a que todos los servicios necesarios estén listos antes de entrar en LOADING.

Si el servicio dependiente no aparece, el complemento permanece en PENDING y no ejecuta apply.

Ejemplo

// Ruta del archivo: scratch-plugin/src/my-plugin.ts
// Declara que este complemento necesita los servicios tools y llm; apply no se ejecutará hasta que ambos estén listos
export const inject = ['tools', 'llm']

export function apply(ctx: Context) {
  // Al llegar aquí, ctx.tools y ctx.llm ya están listos con seguridad
  // Puedes registrar herramientas y leer la configuración del modelo con tranquilidad
}

Esta es la forma en que Cordis expresa el orden de carga mediante dependencias de servicios, en lugar de orquestar manualmente la secuencia de inicio.


Mecanismo de limpieza automática

Cualquier registro realizado a través de ctx se revierte automáticamente al desinstalar el complemento.

Esta es la razón fundamental por la que dsh puede «limpiarse solo», y también el requisito previo para que la sustitución en caliente funcione de manera segura.

Operación de registroLimpieza al desinstalar
ctx.on(event, handler)Los listeners de eventos se eliminan automáticamente
ctx.tools.register(tool)Los registros de herramientas se eliminan automáticamente
ctx.llm.registerAdapter(names, adapter)Los registros de adaptadores LLM se eliminan automáticamente
ctx.effect(() => cleanup)El disposer devuelto se ejecuta al desinstalar

Donde ctx.effect se utiliza para gestionar recursos personalizados que no tienen un «registro» existente que pueda rastrearlos, como conexiones de red.


Orden de invocación de los disposers

Al desinstalar el complemento, los disposers se invocan en orden inverso al de registro.

Varios disposers asíncronos se ejecutan de forma concurrente, sin garantía de que se complete uno tras otro.

Los pasos de limpieza que dependen del orden deben colocarse dentro del mismo disposer devuelto por ctx.effect(), y ese disposer es responsable de esperar secuencialmente.

Por ejemplo, si registras dos efectos A y B en ese orden, al desinstalar se llamará primero al disposer de B y luego al de A.

Si la limpieza de B debe esperar a que la limpieza de A termine, hay que escribir ambos pasos en el mismo effect.


Ejemplo práctico: observar las transiciones de estado

La documentación oficial utiliza el siguiente complemento mínimo para demostrar los registros de carga y desinstalación.

Ejemplo

// Ruta del archivo: scratch-plugin/src/lifecycle-log.ts
// Usa console.log para imprimir los eventos del ciclo de vida y observa el orden entre apply y effect
export function apply(ctx: Context) {
  // Se llama a apply: el complemento pasa de LOADING a ACTIVE
  console.log('ejemplo plugin loading')

  // Registra un efecto: la función de limpieza devuelta se ejecuta al desinstalar
  ctx.effect(() => {
    // Registro del efecto completado (apply aún está en ejecución)
    console.log('ejemplo effect registered')
    // Devuelve el disposer: se llama al desinstalar el complemento
    return () => console.log('ejemplo effect cleaned up')
  })
}

Salida al cargar:

ejemplo plugin loading
ejemplo effect registered

Salida al desinstalar:

ejemplo effect cleaned up

Se puede ver que apply se ejecuta primero, luego se llega al registro del effect, y el disposer devuelto se llama en la fase de desinstalación.


Resumen y autoevaluación

La máquina de estados Fiber describe los seis estados del complemento, desde la declaración hasta la completa desinstalación; los disposers limpian los registros en orden inverso al de registro, de forma asíncrona y concurrente.

Ponte a prueba:

  1. ¿Cuáles son los seis estados de Fiber? ¿A qué estado se pasa cuando apply lanza una excepción?
  2. ¿Por qué los listeners registrados con ctx.on no necesitan removeListener manual?
  3. Dos pasos de limpieza con dependencia de orden, ¿cómo deberían escribirse para que sean seguros?
Otras extensiones