Extensions

Une extension est un dossier avec un package.json contenant spiritExtension. Spirit l'installe par utilisateur et par hôte, pas dans le répertoire .spirit/ du workspace.

Cela diffère des Skills (dossiers SKILL.md), des MCP (serveurs externes) et des Hooks (scripts hooks.json). contributes.cli.hooks stylise les emplacements CLI TUI. Ce n'est pas hooks.json.

Il n'y a pas d'interrupteur d'activation par extension. Après l'installation, l'extension contribue. Le bouton bascule du panneau CLI est un placeholder.

Structure du package

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
      }
    ]
  }
}

Le name du package.json est l'identifiant de l'extension. Il doit correspondre à ^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$.

Champs de package.json

main, spiritExtension.icon, les chemins CSS et les chemins de hooks CLI doivent être relatifs et doivent rester dans le package.

spiritExtension

Capacités

desktop-ui / cli-ui et le bloc contributes correspondant doivent être tous deux présents ou tous deux absents.

Événements d'activation

L'hôte appelle activate lorsque l'extension répertorie l'événement et possède un main lisible.

contributes.tools

Le modèle ne voit pas name tel quel. L'hôte construit un nom d'invocation comme extension__{id}__{tool}__{hash}.

contributes.desktop

Requiert desktop-ui.

contributes.cli

Requiert cli-ui. hooks est un objet avec path, pas un tableau en ligne :

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

Le fichier doit être { "hooks": [ ... ] }.

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

Rôles de jeton : default, primary, secondary, muted, accent, success, warning, danger.

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

settingsSchema

Les valeurs sont string, number, boolean ou null. null efface un réglage non requis.

secretSlots

Desktop stocke les secrets dans le trousseau du système d'exploitation. Sur le chemin du démon CLI, secrets.set / secrets.delete peuvent ne pas être disponibles.

activate

main est chargé avec import dynamique. Exportez l'un des éléments suivants :

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

ctx

Valeur de retour

Renvoie un objet, ou exportez les mêmes champs depuis le module.

Contexte ctx du gestionnaire d'outil

Un résultat string est transmis tel quel. Les autres valeurs sont JSON.stringify(value, null, 2). undefined devient "".

Desktop 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");
    },
  };
}

Installation

• ZIP — l'archive doit contenir exactement un package.json (il peut se trouver dans un sous-répertoire). Importez avec spirit extension import ./extension.zip ou Settings → Extensions.
• Tarball du marketplace — la racine de l'archive doit contenir un répertoire package/.

supportedHosts doit inclure l'hôte actuel. Une deuxième installation de la même id ne remplace pas la copie existante par défaut. Voir Marketplace pour les canaux et l'interface d'installation.

Publier sur le registre officiel

Le dépôt SpiritAgents/registry est un index marketplace. Il n'héberge pas le code source des extensions, dist, les fichiers ZIP ou les tarballs.

Effectuez ces étapes dans l'ordre :

1. Publiez un package npm public.
2. Ouvrez une pull request qui liste ce package.

1. Publier le package npm

Le package.json publié est la source de vérité, en particulier spiritExtension. Le générateur de registre exige :

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

Il lit également name, version, description, author, repository, homepage, keywords, et spiritExtension.icon optionnel. Si vous définissez icon, incluez ce fichier dans le package publié. Un objet spiritExtension manquant fait échouer la construction du registre pour cette version.

Exemple officiel : @spiritagent/extension-system-message-demo (spiritagent.system-message-demo).

2. Lister le package

Créez registry/extensions/<extension-id>/ avec :

Ne modifiez pas ces fichiers à la main (régénérez-les) :

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

extensionId doit avoir au moins deux segments séparés par des points, des lettres minuscules et des chiffres, avec des points ou des traits d'union à l'intérieur d'un segment. Exemples : spiritagent.system-message-demo, yourteam.some-extension. packageName et extensionId doivent être uniques dans le dépôt.

entry.json

Chaque élément 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."
      }
    }
  ]
}

Le README du marché doit couvrir ce que fait l'extension, le nom du package, la version approuvée par défaut, la compatibilité avec les hôtes et capacités, et des notes pour les lecteurs du marché.

Régénérez localement les fichiers dérivés :

./scripts/build-registry.ps1

Le script récupère les métadonnées npm pour les versions répertoriées, reconstruit catalog.json et chaque detail.json, puis vérifie la cohérence.

Pull request

Incluez entry.json, le README.md du marketplace, ainsi que les fichiers catalog.json / detail.json régénérés. Ne listez que les versions déjà publiques sur npm. Définissez précisément reviewStatus et channel. Les nouvelles versions commencent généralement par unverified.

Ne committez pas les arborescences source des extensions, les répertoires dist, les fichiers ZIP, les tarballs ou autres artefacts binaires.

Ouvrir une pull request ne garantit pas la publication. La revue peut demander des modifications avant qu'une version soit approuvée ou vérifiée.