# 套件資訊清單參考 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

aigd-package.json 的每個欄位：id 與版本、engines.aigd、啟用事件、相依套件，以及每個貢獻點的結構與規則。

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

`aigd-package.json` 是 AI Game Dev 套件的資訊清單：它的 id、版本、可搭配的應用程式版本，以及它貢獻的所有內容。應用程式不需執行任何套件程式碼就能讀取它，因此每個選單項目、斜線命令、Tools 開關與檢視在套件啟用前就已可見。本頁列出每個欄位與貢獻點及其規則。由 `gamedev pkg init` 建立的新套件已經有有效的資訊清單，以及供編輯器自動補全用的 JSON Schema（由 `$schema` 指定）。

## 頂層欄位

| 欄位 | 必填 | 說明 |
| --- | --- | --- |
| `publisher` | 是 | 你的發佈者 id：2 到 40 個字元，以字母開頭，其後為小寫字母、數字與單一連字號，不可有句點 |
| `name` | 是 | 套件名稱：2 到 64 個字元，小寫，以字母開頭 |
| `version` | 是 | 語意化版本 `MAJOR.MINOR.PATCH`（允許如 `1.3.0-beta.2` 的預發行版本後綴） |
| `engines.aigd` | 是 | 套件所需的最舊 AI Game Dev 版本，例如 `">=0.18.0"` |
| `displayName`、`description` | 否 | 顯示於套件視窗與目錄中（`displayName` 最多 60 個字元，`description` 最多 400 個字元） |
| `icon`、`avatarText` | 否 | 相對於套件的圖片，或最多 4 個字元繪製成頭像 |
| `license` | 否 | SPDX id（`MIT`、`Apache-2.0`），或 `SEE LICENSE IN <file>` |
| `homepage`、`repository`、`keywords` | 否 | 連結與最多 20 個關鍵字 |
| `main` | 否 | 匯出 `activate` 的程式碼入口（CommonJS 或 ESM）；若沒有它，套件就只是純貢獻型套件 |
| `activationEvents` | 否 | 額外觸發程式碼啟動的事件（見下文） |
| `hosts` | 否 | `["desktop"]`、`["cli"]` 或兩者（預設）；僅限桌面版的套件會被 CLI 略過 |
| `dependencies` | 否 | 其他套件，`{ "<publisher.name>": "<range>" }` |
| `claudePlugins`、`claudeMarketplaces` | 否 | 套件所需的 Claude Code 外掛，以及其市集的位置 |
| `enabledApiProposals` | 否 | 套件使用的提案中 API；登錄檔會拒絕此處的任何項目 |
| `dataVersion` | 否 | 你的程式碼所儲存資料的版本（僅供參考） |
| `contributes` | 否 | 套件新增的所有內容（見下文） |

套件 id 是 `publisher.name`：`acme.level-tools`。它必須等於套件安裝時所用的鍵，否則不會執行任何東西（`id-mismatch`）。發佈者 `aigd` 屬於 AI Game Dev，而引擎名稱 `unity`、`godot`、`unreal`、`brutal`、`bevy` 與 `threejs` 為保留名稱。

## 應用程式版本：engines.aigd

`engines.aigd` 是最低版本，例如 `">=0.18.0"`。比它更舊的應用程式會拒絕此套件，並說明它需要哪個版本。應用程式的 beta 版視同它所預覽的正式版本：`0.32.0-beta.1` 可滿足 `">=0.32.0"`。應用程式仍可載入的最低門檻是 `0.18.0`；請把你測試過的最舊應用程式版本設為你的值。遊戲引擎套件需要 `">=0.32.0"`。

安裝會依 id 與版本快取：你發佈的每次變更都需要更高的 `version`。

## 套件擁有的 id

套件貢獻的所有項目都命名於自己的 id 之內，因此兩個套件永遠不會衝突：

- 命令、面板、檢視、檢視容器、子選單、狀態列項目、教學與自訂編輯器：`<package id>.<local>`，例如 `acme.level-tools.export`。
- 能力：套件 id 本身或 `<package id>.<local>`。能力 id 會依聊天儲存，因此絕不要重新命名。
- MCP 伺服器名稱：`<publisher>--<name>` 或 `<publisher>--<name>-<suffix>`，最多 96 個字元：`acme.level-tools` 擁有 `acme--level-tools` 與 `acme--level-tools-preview`。模型會在每個工具名稱中看到這個名稱，這也是它使用 `--` 而非句點的原因。未加限定名稱即為錯誤。
- 你用 `aigd.commands.setContext` 設定的情境鍵：`<package id>.<key>`。

`gamedev pkg validate` 會列出每個不屬於你的 id，並標明其欄位。

## 貢獻點

| 項目 | 結構 | 備註 |
| --- | --- | --- |
| `commands` | `{command, title, shortTitle?, category?, icon?, palette?, hosts?, enablement?}` | 命令面板項目；`enablement` 是一個 `when` 條件 |
| `slashCommands` | `{name, description, argumentHint?, hosts?}` | `name` 即輸入的名稱，如 `/export`；名稱衝突時內建命令優先，其次依 id 排序的第一個套件 |
| `capabilities` | `{id, label, description, defaultEnabled?, mcpServer?, gatesClaudePlugin?, statusful?, hidden?, icon?}` | 聊天 Tools 列中的開關；`mcpServer` 指定它要開啟的伺服器 |
| `mcpServers` | `{ "<server name>": {command, args?, env?} or {type: "http" or "sse", url, headers?} }` | Stdio 伺服器可使用 `${node}`、`${packageDir}`、`${projectDir}`、`${globalStorage}` |
| `agentProviders` | `{id, serverName, capabilityId, sessionToolViewId?}` | 你的程式碼透過 `aigd.agent.registerProvider` 在記憶體中提供的工具 |
| `settings` | `{ "<key>": {type, default?, description, enum?, scope?, …} }` | 型別為 `string`、`number`、`boolean`、`string[]`、`path` |
| `menus` | `{ "<menu id>": [{command or submenu, group?, when?, alt?}] }` | 固定的選單 id（如下） |
| `submenus` | `{id, label, icon?}` | 子選單 id 同時也是選單的鍵 |
| `keybindings` | `{command, key, mac?, win?, linux?, when?, args?}` | 桌面版；除非指定 `mac`，否則 `ctrl` 在 macOS 上代表 Cmd |
| `statusBar` | `{id, text, tooltip?, command?, alignment?, priority?, when?}` | 桌面版 |
| `panels` | `{viewType, title, icon?}` | 你的程式碼所開啟的 webview 面板 |
| `viewsContainers` | `{left?: [{id, title, icon}], right?: [...]}` | 新的側邊面板分頁 |
| `views` | `{ "left" or "right" or "<container id>": [{id, name, type: "tree" or "webview", icon?, when?, welcome?, titleBar?}] }` | 側邊面板中的樹狀檢視與 webview 檢視 |
| `customEditors` | `{viewType, displayName, selector: [{filenamePattern}], priority?}` | `priority` 為 `default`（預設值）時會取代符合檔案的內建預覽；`option` 則會出現在「開啟方式」中 |
| `tutorials` | `{id, title, anchor, markdown? and media? or webview?, size?, trigger?, when?, after?, priority?}` | 應用程式內的簡短提示，每位使用者只顯示一次 |
| `claudePlugin` | 相對於套件的資料夾 | 隨套件一起提供的 Claude Code 外掛 |
| `mediaProviders` | `{id, capabilityId, execution: "local"}` | 你的程式碼透過 `aigd.media.registerProvider` 註冊的本機媒體產生器 |
| `sessionTools` | `{id, capabilityId, title, modules?}` | 聊天室「工具」中某項能力的設定介面（由你的程式碼解析的 webview 檢視） |
| `gameEngines` | 請參閱 [遊戲引擎套件](https://ai-game.dev/zh-hant/docs/wiki/app/game-engine-packages) | 每個套件一個引擎 |
| `runtimes`, `imageModels`, `videoModels`, `model3dModels`, `mediaModels` | 宣告式，無需程式碼 | 本機產生執行環境與其執行的模型，以及雲端模型系列 |

圖示可以是 `$(name)`（應用程式圖示集中的圖示），或是套件內的路徑。`composerButtons` 仍會載入但已棄用：請改用 `composer/toolbar` 選單項目。

### 選單 id

| 選單 id | 指令會收到 | `when` 用的內容鍵 |
| --- | --- | --- |
| `commandPalette` | 無 | — |
| `composer/toolbar` | `{sessionId}` | `sessionId` |
| `session/title` | `{sessionId}` | `sessionId` |
| `session/tool` | `{sessionId, capabilityId}` | `sessionId`, `capability`, `capabilityPackage`, `sessionToolModule` |
| `session/context` | `{sessionId}` | `sessionId`, `sessionState` |
| `chat/message/context` | `{sessionId, messageId, role}` | `sessionId`, `messageRole` |
| `explorer/context` | `{path, isDirectory}` | `resourcePath`, `resourceFilename`, `resourceExtname`, `resourceDirname`, `resourceRelativePath`, `explorerResourceIsFolder` |
| `editor/title` | `{path, viewType}` | 資源相關的鍵、`activeCustomEditor`、`previewKind` |
| `preview/<kind>/toolbar` | `{path}` | 資源相關的鍵、`previewKind` |
| `view/title` | `{viewId}` | `view` |
| `view/item/context` | `{viewId, itemId}` | `view`, `viewItem` |
| `packages/item/context` | `{packageId}` | `packageId`, `packageLevel`, `packageState` |
| `statusBar/item/context` | `{itemId}` | `statusBarItem` |

群組 `navigation` 會產生行內工具列按鈕；其他群組則會進入「…」溢位選單，而 `group@order` 可在群組內排序。預覽種類有 `code diff image svg texture audio video model font markdown table binary`。未知的選單 id 只會產生警告而非錯誤，因此為較新版本應用程式撰寫的套件仍可載入。

### when 子句

選單、`enablement`、按鍵綁定、檢視、狀態列項目與教學都接受 VS Code 語法的 `when` 子句：`! && || == != < <= > >= =~ /regex/ in` 與 `not in`，並支援括號。全域鍵包括 `host`、`platform`、`projectOpen`、`projectEngine`、`activePane`、`activeFilePath`、`activeFileExtname`、`sessionActive`、`sessionRunning`、`attachedCapabilities`、`activePackages`、`installedPackages`、`workspaceEngines`，以及開啟資料夾中每個引擎對應的 `workspaceHasEngine:<engine>`。你的設定可透過 `config.<package id>.<key>` 讀取，你自己的鍵則為 `<package id>.<key>`。

```json
{
  "contributes": {
    "commands": [{ "command": "acme.level-tools.export", "title": "Export level", "enablement": "projectEngine == 'godot'" }],
    "menus": {
      "explorer/context": [{ "command": "acme.level-tools.export", "when": "resourceExtname == '.tscn'", "group": "navigation" }]
    }
  }
}
```

無法解析的子句屬於 manifest 錯誤，並會捨棄該項貢獻。

### 設定

```json
{
  "contributes": {
    "settings": {
      "outputDir": { "type": "path", "description": "Where exports go", "scope": "project", "mustBeWritable": true },
      "quality": { "type": "string", "enum": ["draft", "final"], "default": "draft", "description": "Export quality" },
      "cachePath": { "type": "path", "description": "A cache on this computer", "userLevelOnly": true }
    }
  }
}
```

- `scope: "machine"`（預設值）會寫入使用者層級；`scope: "project"` 會寫入專案層級，該層級會提交並與團隊共用。
- 值的讀取順序為本機層級、專案、使用者層級，最後才是 manifest 預設值。
- `type: "path"` 接受絕對路徑；`directories: false` 表示要求選擇檔案，`mustBeWritable` 與 `showFreeSpace` 會為表單加上檢查。
- `userLevelOnly: true`（搭配 `scope: "machine"`）會讓該鍵適用於整台機器：專案與本機的值都會被忽略。
- `enum` 提供固定選項；`options: { "provider": "<id>" }` 則在執行時向 provider 取得（目前僅限應用程式自家的 provider）。

### 啟用事件

大多數套件都不需要：每個提供的命令、斜線命令、檢視、自訂編輯器、具狀態的能力、webview 教學和遊戲引擎都會自行啟動程式碼。當程式碼必須在其他時機執行時，請在 `activationEvents` 中列出額外事件：

| 事件 | 時機 |
| --- | --- |
| `onStartupFinished` | 應用程式首次渲染後，或 CLI 首次提示後（具有 `main` 且沒有其他事件的套件之預設值） |
| `onCommand:<id>`, `onSlashCommand:/<name>` | 命令執行前 |
| `onView:<viewId>`, `onCustomEditor:<viewType>` | 檢視首次顯示時，或開啟符合的檔案時 |
| `onFileType:.<ext>` | 該副檔名的檔案在任何窗格中開啟時 |
| `onCapability:<id>`, `onAgentProvider:<id>` | 首次需要某項能力或 provider 時 |
| `onTutorial:<id>`, `onWebviewPanel:<viewType>` | webview 教學顯示前，或還原已儲存的面板時 |
| `onGameEngine:<id>` | 開啟的資料夾含有該引擎的專案時 |
| `*` | 主機啟動時（不建議） |

## 相依性與 Claude 外掛

```json
{
  "dependencies": { "acme.core-3d": "^1.0.0" },
  "claudePlugins": { "level-design@acme-marketplace": "*" },
  "claudeMarketplaces": { "acme-marketplace": { "source": "github", "repo": "acme/claude-plugins" } }
}
```

- 一個專案對每個套件只執行一個版本：在應用程式接受的前提下，滿足所有版本範圍的最高版本。相依套件會在其依賴者之前啟用。衝突、循環相依或被排除的相依性會顯示在需要它的套件上。
- Claude 外掛會依專案安裝到應用程式自家的快取中，鎖定在專案鎖定檔中的某個 commit，並提供給該專案的對話使用。它們絕不會動到你自己的 `~/.claude`。市集來源有 `github`、`git`、`git-subdir` 和 `url`。

## 相關頁面

- [套件 API](https://ai-game.dev/zh-hant/docs/wiki/app/package-api) 說明這些貢獻背後的程式碼。
- [生命週期、主機與權限](https://ai-game.dev/zh-hant/docs/wiki/app/package-lifecycle) 說明啟用、狀態與版本控管。
- [註冊表規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry) 說明註冊表接受哪些內容。

---

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

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