本页由英文机器翻译而成。阅读英文原文。

包清单参考

aigd-package.json 的每个字段:id 与版本、engines.aigd、激活事件、依赖,以及每个贡献点的结构与规则。

更新于 2026年11月19日 查看 Markdown 版本

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命令接收到的参数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。