# 建立套件 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

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

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/creating-packages)。

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

## 你需要準備什麼

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

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

## 套件目錄結構

```text
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 工具列按鈕、一個狀態列項目，以及一項設定。

```json
{
  "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）：

```text
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：

```json
{
  "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**，永遠不會被提交。

```bash
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 時停止它啟動的所有程序：

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

在桌面應用程式中，同樣的功能位於 Packages 視窗：選取套件後選擇 **Use a local folder…**，之後再選 **Stop using local folder** 即可還原。若資料夾的 manifest 寫的是別的 id，會被拒絕。

**提示**

來自你套件的日誌（`ctx.log`、`console.*`）會以 `pkg:<your id>` 標記出現在應用程式日誌中；若套件發生錯誤，會在 Packages 視窗的 **Errors** 分頁列出其錯誤。

## 分享你的套件

AI Game Dev registry 收錄了第一方套件。若要分享你自己的套件，請將它發佈到 GitHub 或 npm；任何人都可以透過連結加入：

```bash
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"`。
- 套件以你的使用者權限執行，且沒有沙箱。不要在套件中夾帶機密資訊，並告訴使用者你的套件做了什麼。

## 深入了解

- [Packages](https://ai-game.dev/zh-hant/docs/wiki/app/packages)：層級、更新與設定。
- [Packages catalog](https://ai-game.dev/zh-hant/docs/wiki/app/packages-catalog)：了解第一方套件提供哪些功能。
- 文章 [packages, Claude plugins and MCP servers](https://ai-game.dev/zh-hant/blog/ai-game-dev-packages-plugins-mcp)：將 MCP server 加入進行中的對話。

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/app/creating-packages

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/app/creating-packages