包清单参考
aigd-package.json 的每个字段:id 与版本、engines.aigd、激活事件、依赖,以及每个贡献点的结构与规则。
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 | 参见 游戏引擎包 | 每个包对应一个引擎 |
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> 读取。
{
"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" }]
}
}
}无法解析的子句属于清单错误,会丢弃该项贡献。
设置
{
"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 插件
{
"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 介绍这些贡献背后的代码。
- 生命周期、宿主与权限 介绍激活、状态与版本管理。
- 注册表规则与检查 说明注册表接受哪些内容。