Pakete erstellen

Pakete sind nicht nur für First-Party-Features gedacht: Du kannst eigene schreiben, um eine wiederkehrende Aufgabe mit deinem Team zu teilen, ein Tool für den Agenten hinzuzufügen oder ein eigenes Dateiformat in der Vorschau anzuzeigen. Diese Seite zeigt den Aufbau eines Pakets, ein minimal funktionierendes Paket, die wichtigsten Manifest-Felder, wie du ein MCP-Tool hinzufügst, wie du ein Paket gegen eine laufende App entwickelst und wie du es teilst.

Was du brauchst#

• Die AI Game Dev Desktop-App oder die gamedev CLI, Version 0.18.0 oder neuer.
• Einen Texteditor. JavaScript ist optional: Ein Paket kann nur aus einem Manifest bestehen.

Pakete folgen dem Modell der VS-Code-Erweiterungen: ein Ordner mit einem Manifest, aigd-package.json, und optionalem Code, der activate(ctx) und deactivate() exportiert. Dein Code erreicht die App nur über ctx.aigd. Er läuft in einem separaten Extension-Host-Prozess, einen pro geöffnetem Projekt, und startet erst, wenn etwas ihn benötigt.

Aufbau eines Pakets#

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

Ein Paket muss eigenständig sein: Die App führt dafür nie npm install aus. Wenn dein Code Bibliotheken verwendet, bündle sie in die Datei, auf die main zeigt.

Ein minimales Paket#

Dieses Paket fügt einen /my-first-Slash-Befehl, einen Eintrag in der Befehlspalette, eine Schaltfläche in der Composer-Symbolleiste, ein Statusleisten-Element und eine Einstellung hinzu.

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

Und der Code, 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() {};

Der Slash-Befehl, die Symbolleisten-Schaltfläche und das Statusleisten-Element erscheinen aus dem Manifest, bevor irgendein Code läuft; activate wird beim ersten Einsatz eines davon aufgerufen.

IDs und Namensregeln#

• Die Paket-ID ist publisher.name in Kleinbuchstaben: hier you.my-first-package. Der Publisher besteht aus 2 bis 40 Zeichen (Buchstaben, Ziffern, einzelne Bindestriche). Verwende deinen eigenen Publisher-Namen; aigd gehört AI Game Dev.
• Jede ID, die ein Paket beiträgt (Befehle, Ansichten, Statusleisten-Elemente, Tutorials), beginnt mit der Paket-ID: you.my-first-package.hello.
• engines.aigd ist erforderlich: die älteste AI Game Dev-Version, die das Paket benötigt, zum Beispiel ">=0.18.0". Eine ältere App lehnt das Paket ab und nennt die benötigte Version.
• version ist semver. Installationen werden nach ID und Version zwischengespeichert, daher braucht jede Änderung, die du veröffentlichst, eine höhere Version.

Wichtigste Manifest-Felder#

Zu den Beitragspunkten in contributes gehören commands, slashCommands, capabilities (Schalter in der Tools-Zeile der Sitzung), mcpServers, settings, panels, viewsContainers und views (Baum- oder Webview-Ansichten in den Seitenleisten), menus und submenus, keybindings, customEditors, statusBar und tutorials. Menüs verwenden feste IDs wie commandPalette, composer/toolbar, explorer/context, editor/title und view/item/context, jeweils mit einer optionalen when-Klausel. Die CLI zeigt Slash-Befehle, Tools-Zeilen, Meldungen, Quick Picks, Eingabefelder und Formulare; Menüs und Panels gibt es nur in der Desktop-Version.

Dem Agenten mit einem MCP-Server ein Tool geben#

Der häufigste Grund, ein Paket zu schreiben, ist, dem Agenten neue Tools zu geben. Deklariere einen MCP-Server und eine Capability, die ihn pro Sitzung einschaltet:

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

• Der Servername muss <publisher>--<name> (oder <publisher>--<name>-<suffix>) der Paket-ID sein, höchstens 96 Zeichen, damit Namen verschiedener Autoren nie kollidieren. Ein nicht qualifizierter Name ist ein Fehler.
• Variablen, die du in einem stdio-Server verwenden kannst: ${node}, ${packageDir}, ${projectDir} und ${globalStorage}.
• Wenn in einer Sitzung bereits ein MCP-Server mit demselben Namen konfiguriert ist, wird der Server des Pakets nicht hinzugefügt und die Sitzung zeigt einen Hinweis.

Gegen die laufende App entwickeln#

Richte ein Projekt auf deinen Ordner statt auf eine veröffentlichte Version. Der Ordner wird direkt verwendet, lädt neu, wenn sich eine der mitgelieferten Dateien ändert, und wird nie automatisch aktualisiert. Die Standardebene ist Local, die nie committet wird.

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

Wenn dein Paket einen Build-Schritt hat (src/ wird nach dist/ gebaut), verwende stattdessen gamedev pkg dev. Es führt das dev-Skript des Pakets aus oder wiederholt build nach jeder Quelländerung, verknüpft den Ordner nach dem ersten erfolgreichen Build und beendet jeden gestarteten Prozess, wenn du Ctrl+C drückst:

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

In der Desktop-App findest du dasselbe im Packages-Fenster: Wähle das Paket und dann Use a local folder…, mit Stop using local folder gehst du zurück. Ein Ordner, dessen Manifest eine andere ID nennt, wird abgelehnt.

Teile dein Paket#

Die AI Game Dev-Registry enthält First-Party-Pakete. Um dein eigenes zu teilen, veröffentliche es auf GitHub oder npm; anschließend kann es jeder per Link hinzufügen:

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

Für ein Team füge es auf der Ebene Project hinzu, damit es in .ai-game-dev/packages.json committet wird und jeder Teamkollege es erhält, festgeschrieben durch die Lock-Datei des Projekts.

Bevor du eine neue Version veröffentlichst, erhöhe version in aigd-package.json. Eine geänderte Datei unter einer unveränderten Version erreicht nie eine Installation, die diese Version bereits hat.

Bewährte Praktiken#

• Halte Tools fokussiert. Jedes Tool, das der Agent sieht, belegt Kontext; ein kleines, gut beschriebenes Tool wird häufiger korrekt verwendet.
• Deklariere so viel wie möglich im Manifest, damit die UI sichtbar ist, bevor dein Code startet.
• Verwende scope: "project" für Einstellungen, die das Team teilen soll, und scope: "machine" für Pfade auf einem Rechner.
• Pakete laufen mit den Berechtigungen deines Benutzers und ohne Sandbox. Liefere keine Geheimnisse in einem Paket aus und sage den Nutzern, was dein Paket tut.

Mehr erfahren#

• Pakete für Ebenen, Updates und Einstellungen.
• Paketkatalog für das, was die First-Party-Pakete tun.
• Der Beitrag Pakete, Claude-Plugins und MCP-Server zu einem MCP-Server, der einem laufenden Chat hinzugefügt wird.