拡張機能

拡張機能は、spiritExtension を含む package.json を持つフォルダです。Spirit はこれをワークスペースの .spirit/ ディレクトリではなく、ユーザーごと、ホストごとにインストールします。

これは Skills（SKILL.md フォルダ）、MCP（外部サーバー）、Hooks（hooks.json スクリプト）とは異なります。contributes.cli.hooks は CLI TUI スロットをスタイルします。これは hooks.json ではありません。

拡張機能ごとの有効化スイッチはありません。インストール後、拡張機能が貢献します。CLI パネルのトグルはプレースホルダーです。

パッケージレイアウト

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

package.json の name は拡張機能 ID です。^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$ に一致する必要があります。

package.json フィールド

main、spiritExtension.icon、CSS パス、CLI フックパスは相対パスで、パッケージ内に収まる必要があります。

spiritExtension

機能

desktop-ui / cli-ui と対応する contributes ブロックは、両方存在するか、両方存在しないかのどちらかでなければなりません。

アクティベーションイベント

ホストは、拡張機能がイベントをリストし、読み取り可能な main を持っている場合に activate を呼び出します。

contributes.tools

モデルは name をそのまま認識しません。ホストは extension__{id}__{tool}__{hash} のような呼び出し名を構築します。

contributes.desktop

desktop-ui が必要です。

contributes.cli

cli-ui が必要です。hooks はインライン配列ではなく、path を持つオブジェクトです:

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

ファイルは { "hooks": [ ... ] } の形式である必要があります。

スロット: message.user, message.assistant, message.tool, assistant.thinking, input.frame, bottom_form, bottom_form.section, slash_suggestions, approval.panel, questions.panel。

トークンの役割: default, primary, secondary, muted, accent, success, warning, danger。

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

settingsSchema

値は string, number, boolean, または null です。null は必須でない設定をクリアします。

secretSlots

デスクトップはシークレットをOSキーリングに保存します。CLIデーモンパスでは、secrets.set / secrets.delete が利用できない場合があります。

activate

main は動的な import で読み込まれます。次のいずれかをエクスポートします:

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

ctx

戻り値

オブジェクトを返すか、モジュールから同じフィールドをエクスポートします。

ツールハンドラー ctx

string の結果はそのまま渡されます。その他の値は JSON.stringify(value, null, 2) になります。undefined は "" になります。

デスクトップ 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");
    },
  };
}

インストール

• ZIP — アーカイブには正確に 1 つの package.json が含まれている必要があります（サブディレクトリにある場合もあります）。spirit extension import ./extension.zip または Settings → Extensions でインポートします。
• マーケットプレイスの tarball — アーカイブのルートに package/ ディレクトリが含まれている必要があります。

supportedHosts には現在のホストが含まれている必要があります。同じ ID の 2 回目のインストールは、デフォルトでは既存のコピーを置き換えません。チャンネルとインストール UI については Marketplace を参照してください。

公式レジストリに公開

SpiritAgents/registry リポジトリはマーケットプレイスのインデックスです。拡張機能のソース、dist、ZIP ファイル、または tarball はホストされません。

次の手順をこの順序で実行してください：

1. 公開のnpmパッケージを公開します。
2. そのパッケージをリストする pull request を開きます。

1. npmパッケージを公開する

公開された package.json が信頼できる情報源であり、特に spiritExtension が重要です。レジストリビルダーには次のものが必要です：

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

また、name、version、description、author、repository、homepage、keywords、およびオプションの spiritExtension.icon も読み取ります。icon を設定する場合は、そのファイルを公開パッケージに含めてください。spiritExtension オブジェクトがないと、そのバージョンのレジストリビルドは失敗します。

公式例：@spiritagent/extension-system-message-demo（spiritagent.system-message-demo）。

2. パッケージをリストする

registry/extensions/<extension-id>/ を作成し、次のものを含めます：

これらを手動で編集しないでください（再生成するものです）：

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

extensionId は、少なくとも2つのドット区切りのセグメント、小文字の英数字、セグメント内にドットまたはハイフンを使用する必要があります。例：spiritagent.system-message-demo、yourteam.some-extension。packageName と extensionId はリポジトリ内で一意である必要があります。

entry.json

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

マーケットプレイスのREADMEでは、拡張機能の機能、パッケージ名、デフォルトの承認バージョン、ホストと機能の互換性、マーケットプレイスの読者向けのメモをカバーする必要があります。

派生ファイルをローカルで再生成します:

./scripts/build-registry.ps1

スクリプトは、リストされたバージョンのnpmメタデータを取得し、catalog.jsonと各detail.jsonを再構築して、一貫性を検証します。

Pull request

entry.json、マーケットプレイスのREADME.md、再生成されたcatalog.json / detail.jsonを含めてください。npmで公開されているバージョンのみをリストしてください。reviewStatusとchannelを正確に設定してください。新しいバージョンは通常unverifiedから始まります。

拡張機能のソースツリー、dist、ZIPファイル、tarball、その他のバイナリアーティファクトをコミットしないでください。

pull request を開いてもリスト掲載が保証されるわけではありません。レビューでは、バージョンが承認または検証される前に変更が要求される場合があります。