パッケージを作成する

パッケージはファーストパーティ機能のためだけのものではありません。チームで繰り返し行うタスクを共有したり、エージェントにツールを追加したり、独自のファイル形式をプレビューしたりするために、自分でパッケージを書くことができます。このページでは、パッケージのレイアウト、動作する最小構成のパッケージ、マニフェストの主なフィールド、MCP ツールの追加方法、実行中のアプリを相手にパッケージを開発する方法、そして共有方法を説明します。

必要なもの#

• AI Game Dev デスクトップアプリ、または gamedev CLI（バージョン 0.18.0 以降）。
• テキストエディタ。JavaScript は任意です。パッケージはマニフェストのみでも構いません。

パッケージは VS Code 拡張機能のモデルに従います。マニフェスト aigd-package.json を含むフォルダと、activate(ctx) と deactivate() をエクスポートする任意のコードです。コードがアプリに到達できるのは ctx.aigd 経由のみです。コードは開いているプロジェクトごとに 1 つずつ用意される別の拡張機能ホストプロセスで実行され、何かが必要としたときに遅延して起動します。

パッケージのレイアウト#

my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE

パッケージは自己完結している必要があります。アプリがそのパッケージのために npm install を実行することはありません。コードがライブラリを使う場合は、main が指すファイルにバンドルしてください。

最小構成のパッケージ#

このパッケージは、/my-first スラッシュコマンド、コマンドパレットの項目、コンポーザーのツールバーボタン、ステータスバーの項目、そして 1 つの設定を追加します。

{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}

そしてコード、extension.js（CommonJS）は次のとおりです:

const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};

スラッシュコマンド、ツールバーボタン、ステータスバーの項目は、コードが実行される前からマニフェストに基づいて表示されます。activate はそれらのいずれかが最初に使われたときに呼び出されます。

ID と命名規則#

• パッケージ ID は publisher.name の小文字形式です。ここでは you.my-first-package になります。publisher は 2〜40 文字（英字、数字、単一のハイフン）です。自前の publisher 名を使用してください。aigd は AI Game Dev のものです。
• パッケージが提供するすべての ID（コマンド、ビュー、ステータスバー項目、チュートリアル）は、パッケージ ID で始まります: you.my-first-package.hello。
• engines.aigd は必須です。パッケージが必要とする最も古い AI Game Dev のバージョンを指定します（例: ">=0.18.0"）。古いアプリはパッケージを拒否し、必要なバージョンを示します。
• version は semver です。インストールは ID とバージョンでキャッシュされるため、公開する変更ごとにバージョンを上げる必要があります。

マニフェストの主なフィールド#

contributes のコントリビューションポイントには、commands、slashCommands、capabilities（セッションの Tools 行にあるスイッチ）、mcpServers、settings、panels、viewsContainers と views（サイドパネルのツリーまたは webview ビュー）、menus と submenus、keybindings、customEditors、statusBar、tutorials があります。メニューは commandPalette、composer/toolbar、explorer/context、editor/title、view/item/context といった固定 ID を使用し、それぞれに任意の when 句を指定できます。CLI ではスラッシュコマンド、Tools 行、メッセージ、クイックピック、入力ボックス、フォームが表示されます。メニューとパネルはデスクトップ専用です。

MCP サーバーでエージェントにツールを提供する#

パッケージを書く最も一般的な理由は、エージェントに新しいツールを提供することです。MCP サーバーと、セッションごとにそれを有効化するケイパビリティを宣言します:

{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}

• サーバー名はパッケージ ID の <publisher>--<name>（または <publisher>--<name>-<suffix>）である必要があり、最大 96 文字です。これにより、異なる作者の名前が衝突することはありません。修飾されていない名前はエラーになります。
• stdio サーバーで使用できる変数: ${node}、${packageDir}、${projectDir}、${globalStorage}。
• 同じ名前の MCP サーバーがセッションにすでに設定されている場合、パッケージのサーバーは追加されず、セッションに通知が表示されます。

実行中のアプリを相手に開発する#

公開バージョンの代わりに、プロジェクトを自分のフォルダに向けます。フォルダはその場で使用され、同梱しているファイルが変更されると再読み込みされ、自動更新されることはありません。デフォルトのレベルは Local で、コミットされることはありません。

cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version

パッケージにビルドステップがある場合（src/ が dist/ にビルドされる）、代わりに gamedev pkg dev を使ってください。これはパッケージの dev スクリプトを実行するか、ソースが変更されるたびに build を再実行し、最初のビルドが成功した時点でフォルダをリンクし、Ctrl+C を押すと起動したすべてのプロセスを停止します：

gamedev pkg dev <path-to-your-package>

デスクトップアプリでは同じことを Packages ウィンドウで行えます。パッケージを選択して Use a local folder… を選び、元に戻すには Stop using local folder を選びます。マニフェストに別の id が記載されているフォルダは拒否されます。

パッケージを共有する#

AI Game Dev レジストリにはファーストパーティのパッケージが用意されています。自分のパッケージを共有するには GitHub または npm で公開してください。そうすれば誰でもリンクから追加できます：

gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range

チームで使う場合は Project レベルで追加してください。そうすれば .ai-game-dev/packages.json にコミットされ、プロジェクトのロックファイルで固定された状態でチームメイト全員が利用できます。

新しいバージョンを公開する前に、aigd-package.json の version を上げてください。バージョンが変わらないまま変更されたファイルは、そのバージョンが既にインストールされている環境には決して届きません。

ベストプラクティス#

• ツールは焦点を絞ってください。エージェントが見るすべてのツールはコンテキストを消費します。小さく、よく説明されたツールのほうが正しく使われる頻度が高くなります。
• 可能な限りマニフェストで宣言してください。そうすればコードが起動する前に UI が表示されます。
• チームで共有すべき設定には scope: "project" を、1 台のコンピューター上のパスには scope: "machine" を使用してください。
• パッケージはユーザーの権限で、サンドボックスなしで実行されます。パッケージにシークレットを含めて配布しないでください。また、パッケージが何をするのかをユーザーに伝えてください。

さらに詳しく#

• レベル、更新、設定については Packages をご覧ください。
• ファーストパーティパッケージの機能については Packages catalog をご覧ください。
• 実行中のチャットに MCP サーバーを追加する方法については、ブログ記事 packages, Claude plugins and MCP servers をご覧ください。