本頁面由英文機器翻譯而成。閱讀英文原文。

建立套件

撰寫自己的 AI Game Dev 套件：aigd-package.json 資訊清單、指令、斜線指令、MCP 工具、以 gamedev pkg dev 在本機開發，以及如何分享。

更新於 2026年11月4日 以 Markdown 檢視

套件不只是官方功能的專利：你也可以自己寫套件，把重複的工作分享給團隊、為 agent 新增工具，或預覽自訂的檔案格式。本頁說明套件的目錄結構、一個最小的可用套件、主要的資訊清單欄位、如何新增 MCP 工具、如何針對執行中的應用程式開發套件，以及如何分享。

你需要準備什麼

  • AI Game Dev 桌面應用程式，或 gamedev CLI，版本 0.18.0 以上。
  • 一個文字編輯器。JavaScript 為選用：套件可以只有資訊清單。

套件遵循 VS Code 擴充功能的模型：一個含資訊清單 aigd-package.json 的資料夾，以及選用的程式碼，匯出 activate(ctx) 與 deactivate()。你的程式碼只能透過 ctx.aigd 接觸應用程式。它會在獨立的擴充功能主機行程中執行，每個開啟的專案各有一個，並在需要時才延遲啟動。

套件目錄結構

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 斜線指令、一個命令選擇區項目、一個 composer 工具列按鈕、一個狀態列項目，以及一項設定。

{
  "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 會在第一次使用其中任何一項時被呼叫。

識別碼與命名規則

  • 套件識別碼是 publisher.name，全小寫：此處為 you.my-first-package。發行者名稱長度為 2 到 40 個字元（字母、數字、單一連字號）。請使用你自己的發行者名稱；aigd 是 AI Game Dev 專用的。
  • 套件所提供的每個識別碼（指令、檢視、狀態列項目、教學課程）都以套件識別碼開頭：you.my-first-package.hello。
  • engines.aigd 為必填：套件所需的最舊 AI Game Dev 版本，例如 ">=0.18.0"。較舊的應用程式會拒絕此套件，並說明它需要哪個版本。
  • version 採用 semver。安裝會依識別碼與版本快取，因此你每次發布變更都需要更高的版本號。

主要資訊清單欄位

欄位必填用途
publisher、name、version是識別碼與版本
engines.aigd是應用程式最低版本
displayName、description、icon、license、homepage、repository、keywords否套件視窗顯示的內容
main否程式碼進入點；沒有它，套件就只有貢獻項目
activationEvents否額外會啟動程式碼的事件，例如 onStartupFinished
hosts否desktop、cli 或兩者
dependencies否其他套件，{ "<id>": "<range>" }
claudePlugins否套件所需的 Claude 外掛，{ "<plugin>@<marketplace>": "<range>" }
contributes否套件新增的一切（見下文）

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，每個都可選擇搭配 when 子句。CLI 會顯示斜線指令、Tools 列、訊息、快速選單、輸入框與表單；選單與面板僅限桌面版。

用 MCP 伺服器給 agent 一個工具

撰寫套件最常見的理由，就是給 agent 新工具。宣告一個 MCP 伺服器，以及一個可依工作階段開啟它的 capability：

{
  "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"]
      }
    }
  }
}
  • 伺服器名稱必須是套件識別碼的 <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 即可還原。若資料夾的 manifest 寫的是別的 id，會被拒絕。

分享你的套件

AI Game Dev registry 收錄了第一方套件。若要分享你自己的套件，請將它發佈到 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，每位隊友都能取得，並由專案的 lock 檔固定版本。

發佈新版本前，請先提高 aigd-package.json 中的 version。版本沒變但檔案有變更，永遠不會送達已經安裝該版本的環境。

最佳實務

  • 讓工具保持專注。代理看到的每個工具都會佔用上下文；小而描述清楚的工具更常被正確使用。
  • 盡可能在 manifest 中宣告所有內容，這樣在你程式碼啟動之前 UI 就能顯示。
  • 團隊共享的設定使用 scope: "project"，單一電腦上的路徑使用 scope: "machine"。
  • 套件以你的使用者權限執行，且沒有沙箱。不要在套件中夾帶機密資訊，並告訴使用者你的套件做了什麼。

深入了解