DeepSeek Harness: declaración de dependencias: inject y servicios integrados
Antes ya aprendimos a crear complementos que se ejecutan de forma independiente, pero la mayoría de los complementos necesitan usar las capacidades de otros: registro de herramientas, LLM y Agent.
En este capítulo veremos cómo declarar dependencias y cómo el framework garantiza que las dependencias estén listas antes de ejecutar apply.
¿Qué es un servicio?
Un servicio es una capacidad con nombre que un complemento expone a otros complementos.
En Harness, tools, llm y agents son servicios que se montan en ctx: ctx.tools, ctx.llm, ctx.agents.
| Servicios integrados | Qué es | Uso típico |
|---|---|---|
| ctx.tools | Runtime de herramientas (ToolRuntime) | Registrar / invocar herramientas |
| ctx.llm | Servicio de modelo de lenguaje grande (LLM) | Registrar adaptadores, realizar solicitudes al modelo |
| ctx.agents | Servicio de agente (Agent) | Gestionar subagentes |
Declarar dependencias con inject
Si tu complemento necesita un servicio, escríbelo en el array inject.
El framework garantiza que estos servicios estén listos antes de cargar tu complemento.
Ejemplo
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-tool-plugin'
// Declarar dependencia: se necesita el servicio tools
export const inject = ['tools']
export function apply(ctx: Context) {
// Al llegar aquí, ctx.tools ya está listo con seguridad
ctx.tools.register(/* ... */)
}
Cuando apply se ejecuta, todos los servicios declarados en inject ya están listos.
Esta es la garantía del framework: no necesitas esperar nada en tu código.
Dependencia no lista: el complemento espera
Si un servicio aún no está listo, el complemento no se ejecuta.
Su Fiber permanece en estado PENDING, esperando a que aparezca el servicio.
En el ciclo de vida, PENDING significa "declarado, pero las dependencias requeridas no están listas".
Si el servicio nunca llega, el complemento sigue esperando, sin errores y sin ejecutar apply.
Dependencias obligatorias y opcionales
inject declara dependencias obligatorias: si el servicio está ausente, el complemento no se carga.
Si un servicio se puede usar o no, usa una dependencia opcional: no escribas inject y, donde lo uses, consulta con ctx.get().
Ejemplo
import type { Context } from '@deepseek-ai/cordis'
export function apply(ctx: Context) {
// El servicio metrics puede estar presente o no
const metrics = ctx.get('metrics')
// Encadenamiento opcional: si no existe, se omite sin error
metrics?.record('plugin_loaded', 1)
}
¿Qué sucede cuando un servicio desaparece?
Si durante la ejecución un servicio obligatorio desaparece (por ejemplo, su proveedor se desinstala), suceden dos cosas.
Primero, los complementos que dependen de él ejecutan dispose automáticamente (liberan recursos).
Segundo, cuando el servicio reaparece, los complementos se recargan automáticamente.
Esto evita que los complementos llamen a un servicio que ya no existe.
Consejo: esta regla se combina con la limpieza automática: la desinstalación activa el disposer explicado en la parte 8.
Resumen y autoevaluación
Declara los servicios obligatorios con inject; el framework garantiza que apply solo se ejecute cuando los servicios estén listos; los servicios opcionales se consultan con ctx.get().
Otras extensiones1. ¿Qué se declara en el array inject?
2. ¿En qué estado se encuentra el complemento cuando el servicio no está listo?
3. ¿Cómo se debe declarar una dependencia opcional?