Extensiones

Una extensión es una carpeta con un package.json que contiene spiritExtension. Spirit la instala por usuario y por host, no bajo el directorio .spirit/ del espacio de trabajo.

Esto es diferente de Skills (carpetas SKILL.md), MCP (servidores externos) y Hooks (scripts de hooks.json). contributes.cli.hooks estiliza los slots de la TUI de CLI. No es hooks.json.

No hay un interruptor de habilitación por extensión. Después de la instalación, la extensión contribuye. El interruptor del panel de CLI es un marcador de posición.

Estructura del paquete

example-extension/
  package.json
  dist/index.js
  assets/icon.svg
  styles/desktop.css
  cli-hooks.json

{
  "name": "@example/spirit-extension",
  "version": "0.1.0",
  "description": "Example Spirit Agent extension.",
  "author": { "name": "example" },
  "homepage": "https://example.com/spirit-extension",
  "main": "dist/index.js",
  "spiritExtension": {
    "schemaVersion": 1,
    "displayName": "Example extension",
    "icon": "assets/icon.svg",
    "supportedHosts": ["cli", "desktop"],
    "activationEvents": ["onStartup", "onUserMessage"],
    "requestedCapabilities": [
      "tool-definitions",
      "tool-execution",
      "system-prompt",
      "settings",
      "secret-storage",
      "desktop-ui",
      "cli-ui"
    ],
    "contributes": {
      "tools": [
        {
          "name": "lookup_item",
          "description": "Look up an item by id.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "id": { "type": "string" }
            },
            "required": ["id"]
          },
          "approvalMode": "allowed",
          "executionMode": "foreground"
        }
      ],
      "desktop": {
        "css": [{ "path": "styles/desktop.css" }],
        "settingsPage": { "title": "Example extension" }
      },
      "cli": {
        "hooks": { "path": "cli-hooks.json" }
      }
    },
    "settingsSchema": [
      {
        "key": "region",
        "type": "select",
        "title": "Region",
        "required": true,
        "defaultValue": "us",
        "options": [
          { "value": "us", "label": "US" },
          { "value": "eu", "label": "EU" }
        ]
      }
    ],
    "secretSlots": [
      {
        "key": "api_token",
        "title": "API token",
        "required": true
      }
    ]
  }
}

El name en package.json es el id de la extensión. Debe coincidir con ^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$.

Campos de package.json

main, spiritExtension.icon, las rutas CSS y las rutas de hooks CLI deben ser relativas y deben permanecer dentro del paquete.

spiritExtension

Capacidades

desktop-ui / cli-ui y el bloque contributes correspondiente deben estar ambos presentes o ambos ausentes.

Eventos de activación

El host llama a activate cuando la extensión lista el evento y tiene un main legible.

contributes.tools

El modelo no ve name tal cual. El host construye un nombre de invocación como extension__{id}__{tool}__{hash}.

contributes.desktop

Requiere desktop-ui.

contributes.cli

Requiere cli-ui. hooks es un objeto con path, no un array en línea:

{
  "hooks": { "path": "cli-hooks.json" }
}

El archivo debe ser { "hooks": [ ... ] }.

Slots: message.user, message.assistant, message.tool, assistant.thinking, input.frame, bottom_form, bottom_form.section, slash_suggestions, approval.panel, questions.panel.

Roles de token: default, primary, secondary, muted, accent, success, warning, danger.

{
  "hooks": [
    {
      "slot": "input.frame",
      "variant": "accented",
      "tokens": { "border": "accent" },
      "prefix": "[",
      "suffix": "]"
    }
  ]
}

settingsSchema

Los valores son string, number, boolean, o null. null limpia un ajuste no requerido.

secretSlots

Desktop almacena secretos en el llavero del sistema. En la ruta del daemon de CLI, secrets.set / secrets.delete pueden no estar disponibles.

activate

main se carga con import dinámico. Exporta uno de:

• export function activate(ctx) { ... }
• export default function activate(ctx) { ... }
• export default { activate }

ctx

Valor de retorno

Retorna un objeto, o exporta los mismos campos desde el módulo.

ctx del manejador de herramientas

Un resultado string se pasa directamente. Otros valores se convierten con JSON.stringify(value, null, 2). undefined se convierte en "".

Escritorio host.showMessageBox

export function activate(ctx) {
  return {
    systemPrompt: "Use lookup_item when the user asks for an item by id.",
    async invokeTool({ toolName, arguments: args, settings, secrets }) {
      if (toolName !== "lookup_item") {
        throw new Error(`Unknown tool: ${toolName}`);
      }
      const region = await settings.get("region");
      const token = await secrets.get("api_token");
      return { id: args.id, region, hasToken: Boolean(token) };
    },
    dispose() {
      ctx.log("example-extension disposed");
    },
  };
}

Instalación

• ZIP — el archivo debe contener exactamente un package.json (puede estar en un subdirectorio). Importa con spirit extension import ./extension.zip o Configuración → Extensiones.
• Paquete de marketplace — la raíz del archivo debe contener un directorio package/.

supportedHosts debe incluir el host actual. Una segunda instalación del mismo id no reemplaza la copia existente por defecto. Consulta Marketplace para los canales y la interfaz de instalación.

Publicar en el registro oficial

El repositorio SpiritAgents/registry es un índice de marketplace. No aloja el código fuente de extensiones, dist, archivos ZIP ni paquetes.

Realiza estos pasos en orden:

1. Publica un paquete npm público.
2. Abre una pull request que liste ese paquete.

1. Publica el paquete npm

El package.json publicado es la fuente de verdad, especialmente spiritExtension. El constructor del registro requiere:

• spiritExtension.schemaVersion
• spiritExtension.displayName
• spiritExtension.supportedHosts
• spiritExtension.requestedCapabilities

También lee name, version, description, author, repository, homepage, keywords y el opcional spiritExtension.icon. Si estableces icon, incluye ese archivo en el paquete publicado. Un objeto spiritExtension faltante hace que la compilación del registro falle para esa versión.

Ejemplo oficial: @spiritagent/extension-system-message-demo (spiritagent.system-message-demo).

2. Lista el paquete

Crea registry/extensions/<extension-id>/ con:

No edites estos archivos manualmente (regéralos):

• registry/catalog.json
• registry/extensions/<extension-id>/detail.json

extensionId necesita al menos dos segmentos separados por puntos, letras minúsculas y dígitos, con puntos o guiones dentro de un segmento. Ejemplos: spiritagent.system-message-demo, yourteam.some-extension. packageName y extensionId deben ser únicos en el repositorio.

entry.json

Cada elemento de versions[]:

{
  "schemaVersion": 1,
  "extensionId": "example.spirit-extension",
  "packageName": "@example/spirit-extension",
  "status": "listed",
  "featured": false,
  "defaultVersion": "0.1.0",
  "defaultReviewStatus": "unverified",
  "versions": [
    {
      "version": "0.1.0",
      "channel": "stable",
      "reviewStatus": "unverified",
      "changelog": {
        "summary": "Initial public release.",
        "body": "- Initial public release."
      }
    }
  ]
}

El README del marketplace debe cubrir qué hace la extensión, el nombre del paquete, la versión aprobada predeterminada, la compatibilidad de host y capacidades, y notas para los lectores del marketplace.

Regenera los archivos derivados localmente:

./scripts/build-registry.ps1

El script obtiene los metadatos de npm para las versiones enumeradas, reconstruye catalog.json y cada detail.json, y luego valida la consistencia.

Pull request

Incluye entry.json, el README.md del marketplace, y los catalog.json / detail.json regenerados. Enumera solo versiones que ya sean públicas en npm. Establece reviewStatus y channel con precisión. Las nuevas versiones típicamente comienzan como unverified.

No confirmes árboles de código fuente de extensiones, dist, archivos ZIP, tarballs u otros artefactos binarios.

Abrir una pull request no garantiza la publicación. La revisión puede solicitar cambios antes de que una versión sea aprobada o verificada.