Erweiterungen

Eine Erweiterung ist ein Ordner mit einer package.json, die das Feld spiritExtension enthält. Spirit installiert sie pro Benutzer und pro Host, nicht im .spirit/-Verzeichnis des Workspaces.

Das unterscheidet sich von Skills (SKILL.md-Ordner), MCP (externe Server) und Hooks (hooks.json-Skripte). contributes.cli.hooks gestaltet die CLI-TUI-Slots. Das ist nicht hooks.json.

Es gibt keinen pro Erweiterung deaktivierbaren Schalter. Nach der Installation trägt die Erweiterung bei. Der Schalter im CLI-Panel ist ein Platzhalter.

Paketstruktur

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

Der name in der package.json ist die Erweiterungs-ID. Er muss dem Muster ^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$ entsprechen.

Felder der package.json

main, spiritExtension.icon, CSS-Pfade und CLI-Hook-Pfade müssen relativ sein und innerhalb des Pakets bleiben.

spiritExtension

Fähigkeiten

desktop-ui / cli-ui und der passende contributes-Block müssen entweder beide vorhanden oder beide nicht vorhanden sein.

Aktivierungsereignisse

Der Host ruft activate auf, wenn die Erweiterung das Ereignis auflistet und eine lesbare main hat.

contributes.tools

Das Modell sieht name nicht unverändert. Der Host erstellt einen Aufrufnamen wie extension__{id}__{tool}__{hash}.

contributes.desktop

Erfordert desktop-ui.

contributes.cli

Erfordert cli-ui. hooks ist ein Objekt mit path, kein Inline-Array:

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

Die Datei muss { "hooks": [ ... ] } sein.

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

Token-Rollen: default, primary, secondary, muted, accent, success, warning, danger.

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

settingsSchema

Werte sind string, number, boolean oder null. null löscht eine nicht erforderliche Einstellung.

secretSlots

Desktop speichert Geheimnisse im OS-Keyring. Beim CLI-Daemon-Pfad sind secrets.set / secrets.delete möglicherweise nicht verfügbar.

activate

main wird mit dynamischem import geladen. Exportieren Sie eines von:

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

ctx

Rückgabewert

Geben Sie ein Objekt zurück oder exportieren Sie dieselben Felder aus dem Modul.

Tool-Handler ctx

Ein string-Ergebnis wird durchgereicht. Andere Werte werden JSON.stringify(value, null, 2). undefined wird zu "".

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 — Das Archiv muss genau eine package.json enthalten (sie darf in einem Unterverzeichnis liegen). Importieren Sie mit spirit extension import ./extension.zip oder über Einstellungen → Erweiterungen.
• Marktplatz-Tarball — Das Archivstammverzeichnis muss ein package/-Verzeichnis enthalten.

supportedHosts muss den aktuellen Host enthalten. Eine zweite Installation derselben ID ersetzt standardmäßig nicht die vorhandene Kopie. Siehe Marktplatz für Kanäle und die Installationsoberfläche.

Im offiziellen Registry veröffentlichen

Das SpiritAgents/registry-Repository ist ein Marktplatzindex. Es hostet keine Erweiterungsquellen, dist, ZIP-Dateien oder Tarballs.

Führen Sie diese Schritte in der angegebenen Reihenfolge aus:

1. Veröffentlichen Sie ein öffentliches npm-Paket.
2. Erstellen Sie einen Pull-Request, der dieses Paket auflistet.

1. Veröffentlichen Sie das npm-Paket

Das veröffentlichte package.json ist die Quelle der Wahrheit, insbesondere spiritExtension. Der Registry-Builder erfordert:

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

Es liest auch name, version, description, author, repository, homepage, keywords und optional spiritExtension.icon. Wenn Sie icon festlegen, fügen Sie diese Datei in das veröffentlichte Paket ein. Ein fehlendes spiritExtension-Objekt führt dazu, dass der Registry-Build für diese Version fehlschlägt.

Offizielles Beispiel: @spiritagent/extension-system-message-demo (spiritagent.system-message-demo).

2. Paket auflisten

Erstellen Sie registry/extensions/<extension-id>/ mit:

Bearbeiten Sie diese nicht von Hand (generieren Sie sie neu):

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

extensionId benötigt mindestens zwei durch Punkte getrennte Segmente, Kleinbuchstaben und Ziffern, mit Punkten oder Bindestrichen innerhalb eines Segments. Beispiele: spiritagent.system-message-demo, yourteam.some-extension. packageName und extensionId müssen im Repository eindeutig sein.

entry.json

Jedes versions[]-Element:

{
  "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."
      }
    }
  ]
}

Die Marktplatz-README sollte abdecken, was die Erweiterung tut, den Paketnamen, die standardmäßig genehmigte Version, die Kompatibilität von Host und Fähigkeiten sowie Hinweise für Marktplatz-Leser.

Generierte abgeleitete Dateien lokal neu erzeugen:

./scripts/build-registry.ps1

Das Skript ruft die npm-Metadaten für die aufgeführten Versionen ab, baut catalog.json und jede detail.json neu auf und validiert dann die Konsistenz.

Pull request

Fügen Sie entry.json, die Marktplatz-README.md sowie das neu generierte catalog.json / detail.json hinzu. Listen Sie nur Versionen auf, die bereits öffentlich auf npm verfügbar sind. Setzen Sie reviewStatus und channel genau. Neue Versionen starten typischerweise als unverified.

Committen Sie keine Extension-Source-Trees, dist, ZIP-Dateien, Tarballs oder andere Binärartefakte.

Das Eröffnen eines Pull Requests garantiert keine Auflistung. Die Überprüfung kann Änderungen anfordern, bevor eine Version genehmigt oder verifiziert wird.