# 包清单参考 — 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` | 否 | 显示在 Packages 窗口和目录中（`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 插件，以及在哪里找到它们的 marketplace |
| `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?}` | 聊天中 Tools 里某项能力的配置界面（由你的代码解析的 webview 视图） |
| `gameEngines` | 参见 [游戏引擎包](https://ai-game.dev/zh-hans/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" }]
    }
  }
}
```

无法解析的子句属于清单错误，会丢弃该项贡献。

### 设置

```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"` 写入项目级，项目级设置会被提交并与团队共享。
- 取值的顺序依次是本地级、项目级、用户级，最后是清单中的默认值。
- `type: "path"` 接收绝对路径；`directories: false` 表示要求选择文件，`mustBeWritable` 和 `showFreeSpace` 会为表单添加校验。
- `userLevelOnly: true`（配合 `scope: "machine"`）会使某个键在整个机器范围内生效：项目和本地的值都会被忽略。
- `enum` 提供固定选项；`options: { "provider": "<id>" }` 则在运行时从提供方取值（目前仅限应用自带的提供方）。

### 激活事件

大多数包无需配置：每个贡献的命令、斜杠命令、视图、自定义编辑器、带状态的能力、webview 教程和游戏引擎都会自行启动代码。当代码必须在其他时机运行时，请在 `activationEvents` 中列出额外事件：

| 事件 | 触发时机 |
| --- | --- |
| `onStartupFinished` | 应用首次渲染之后，或 CLI 首次提示之后（对于带 `main` 且没有其他事件的包，这是默认值） |
| `onCommand:<id>`、`onSlashCommand:/<name>` | 命令运行之前 |
| `onView:<viewId>`、`onCustomEditor:<viewType>` | 视图首次显示时，或匹配的文件打开时 |
| `onFileType:.<ext>` | 当具有该扩展名的文件在任意窗格中打开时 |
| `onCapability:<id>`、`onAgentProvider:<id>` | 首次需要某项能力或提供方时 |
| `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 插件按项目安装到应用自己的缓存中，固定到该项目 lock 文件中的某个提交，并交给该项目的对话使用。它们绝不会改动你自己的 `~/.claude`。市场来源包括 `github`、`git`、`git-subdir` 和 `url`。

## 相关页面

- [Package API](https://ai-game.dev/zh-hans/docs/wiki/app/package-api) 介绍这些贡献背后的代码。
- [生命周期、宿主与权限](https://ai-game.dev/zh-hans/docs/wiki/app/package-lifecycle) 介绍激活、状态与版本管理。
- [注册表规则与检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry) 说明注册表接受哪些内容。

---

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

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