Escribir tu primer plugin

Añadir una herramienta que el modelo pueda usar es el caso más habitual. La estructura es siempre la misma.

export const name = 'ejemplo-changelog'
export const inject = ['tools']

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'leer_changelog',
    description: 'Devuelve las entradas recientes del changelog del proyecto.',
    parameters: {
      version: { type: 'string', required: true, description: 'Versión a consultar' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, valor) => [{ type: 'text', text: valor }],
    },
    async execute(args, exec) {
      // exec.signal permite cancelar si el turno se aborta
      return await buscarEntrada(args.version, exec.signal)
    },
  }))
}

Cuatro reglas que evitan sorpresas

• Regla uno Los argumentos llegan validados Contra lo que declaraste, así que dentro del cuerpo tienen el tipo correcto. Lo que tu descripción no expresa, como que un número sea positivo, sigue siendo cosa tuya.
• Regla dos Se devuelve un dato, no un mensaje La explicación para el humano va aparte. Si devuelves prosa, obligas a quien la reciba a parsearla.
• Regla tres Las excepciones son para fallos reales Lanzar una excepción marca el resultado como error y eso es para fallos de infraestructura. Un resultado correcto pero no ideal, como un comando que termina mal, se representa en el dato.
• Regla cuatro Hay que respetar la cancelación Cuando la señal se dispara, el trabajo en curso se detiene.

Dos cosas que salen gratis

• Gratis uno Funciona en modo Code Cualquier herramienta registrada está disponible sin integración adicional, con los tipos derivados de la misma descripción
• Gratis dos Tiene interfaz por defecto Si no defines cómo se ve, aparece una tarjeta genérica. Hay formatos específicos para salida de terminal, cambios en ficheros y resultados de búsqueda

Detalle técnico opcional

Las funciones que dibujan la tarjeta tienen que ser puras, porque se ejecutan tanto en directo como al reproducir una sesión guardada. Nada de leer ficheros, consultar el reloj o usar aleatoriedad. Si necesitas el contenido anterior de un fichero dentro del presentador, eso pertenece a los metadatos del resultado, no ahí.

Publicarla

Un plugin se distribuye como un paquete que aporta una capa de configuración. El flujo recomendado es probar primero en modo Creator, donde se puede montar y desmontar en memoria, para empaquetar después.

Para que otros lo encuentren, se etiqueta el repositorio con dsh-plugin.