发布包
将包发布到 AI Game Dev 社区注册表:认领发布者、上传、发布说明、beta 渠道、弃用、撤回及其他分享方式。
社区注册表是用户按 id 查找和安装包的地方:gamedev pkg add acme.level-tools,或在 Packages 窗口中点击 Browse,支持自动更新和 1 到 5 星评分。任何已注册的 ai-game.dev 账户都可以发布,包是免费的,每个版本都通过自动检查而非人工审核。本页覆盖完整流程:你的发布者、首次上传、发布说明、预发布渠道、弃用、撤回,以及分享包的其他方式。

认领发布者
你的发布者 id 是你发布的每个包 id 的前半部分(acme.level-tools 中的 acme)。只需认领一次;先到先得:
gamedev login
gamedev pkg publisher claim acme --name "Acme Tools"发布者 id 为 2 到 40 个字符,由小写字母、数字和单个连字符组成。AI Game Dev 自己的 id(aigd)、引擎名称(unity、godot、unreal、brutal、bevy、threejs)、商标以及形近名称(如 un1ty 或 unity-tools)均为保留。账户需要已验证的邮箱,且最多可拥有 3 个发布者。
认领发布者的账户即为其 owner。所有者可以通过邮箱添加 maintainers;维护者可以上传、撤回、弃用、编辑发布说明、移动渠道并生成令牌。只有所有者可以管理成员和受信任的发布者。
发布版本
在 aigd-package.json 中写入 "publisher": "acme",提升 version,构建,然后:
gamedev pkg publish level-toolsCLI 会打包该文件夹(与 gamedev pkg pack 相同的检查和字节),上传并等待检查结果。一个版本会经历以下状态:
| 状态 | 含义 |
|---|---|
uploaded、checking | 等待或正在运行自动检查 |
published | 通过所有检查;约一分钟内进入已签名索引 |
rejected | 某项检查失败;报告会列出每个失败项。修复后重新上传同一版本 |
yanked | 由发布者撤回:版本范围会跳过它,已安装的会保留 |
revoked | 由 AI Game Dev 移除(恶意软件、被盗账户):所有应用都会将其关闭 |
版本不可变。 已发布、已撤回或已吊销的版本号永远无法再次上传;只有被拒绝的版本可以。请以新版本发布修复。

发布说明
每个版本都可以携带 Markdown 格式的发布说明。用户可在 Packages 窗口(Versions)以及发布者面板中按版本查看。上传时提供:
gamedev pkg publish level-tools --notes RELEASE_NOTES.md如果没有 --notes,注册表会从版本标题(## 1.2.0、## [1.2.0] 或 ## v1.2.0)开始,一直取到下一个同级或更高级标题之前的 CHANGELOG.md(位于包文件夹中,随归档一起分发)内容,截断至 20 KB:
# Changelog
## [1.2.0]
- Export levels as glTF.
- Fix the collectible count in nested scenes.发布说明最多为 20 KB 的 Markdown,像 README 一样经过净化处理,并像包中其他所有文本一样接受提示注入检查。成员之后可在发布者面板中编辑它们。已签名索引包含前 4 KB,并附有指向其余部分的链接。
渠道:latest、beta 及其他
渠道(dist-tag)指定用户按名称请求时获得的版本:
gamedev pkg add acme.level-tools # the latest channel
gamedev pkg add acme.level-tools@beta # whatever beta points to- 预发布版本(
1.3.0-beta.1)默认永远不会被安装:latest是已发布的最高稳定版本,除非你自行设置,且它永远不能指向预发布版本。 - 其他渠道由你命名(
beta、next、nightly):小写、以字母开头、最多 16 个字符。一个包最多有 5 个渠道,包含latest。 - 被撤回或吊销的版本无法打标签;指向某个版本而该版本被撤回的渠道会被移除。
- 以 semver 预发布形式发布预发布版本(
1.3.0-beta.2)。名称中包含alpha、beta、rc、next、preview、canary、nightly、dev或experimental的预发布版本会自动把对应渠道指向自身,除非成员手动设置过该渠道;任何渠道也可在发布者面板(Channels)中移动。 gamedev pkg add acme.level-tools@beta会把 channel 写入packages.json,即{ "source": "^1.3.0-beta.1", "channel": "beta" }。测试者在 channel 的版本比最新稳定版更新时获得该版本,并在稳定版发布后于下一次更新时切换到稳定版。
弃用包或版本
弃用会提示用户迁移,同时不破坏任何已安装的内容:
- 包: 一条消息(最多 300 个字符),以及可选的替代包 id。应用和 CLI 会显示该消息和替代包;已安装的副本继续工作,并且该包仍然可以被添加。
- 版本: 一条消息,例如“导出嵌套场景时会发生数据丢失,请更新到 1.2.1”。
选择版本时,应用会优先选择未被弃用的版本。两种弃用操作都可撤销,并记录在 registry 的审计日志中。在 publisher 面板中设置。
撤下与吊销
撤下误发布的版本:此后版本范围会跳过它,而已经安装它的用户会保留它。撤下是可撤销的,publisher token 可以执行撤下。吊销是 AI Game Dev 针对恶意或被盗版本的“ kill switch”:它会被移出索引,所有已安装该版本的应用会在下一次读取索引时将其关闭。
从 CI 发布
有两种方式,均展示于 Trusted Publishing:
- Trusted Publishing(推荐): GitHub Actions 或 GitLab CI 证明是哪个仓库和工作流在发布;无需在任何地方存储密钥,并且每个版本都会记录其来源。那里还介绍了现成的 GitHub Action 和 GitLab CI 模板 IvanMurzak/gamedev-publish-action。
- publisher token:
gamedev pkg publisher token create acme --label ci --days 90,将其存为 CI 密钥,并作为AI_GAME_DEV_PUBLISHER_TOKEN传入。
publisher 面板
首次上传后发布者需要管理的一切都在 ai-game.dev/publisher 的 publisher 面板中,面向已登录的 owner 和 maintainer:你的 publisher 和包、每个版本及其状态和检查报告、发布说明、channel、弃用与撤下、成员和角色、publisher token,以及带可复制工作流片段的受信任发布者。参见 Registry 规则与检查。
其他来源:GitHub、npm 和文件夹
registry 并非共享包的唯一方式。这些来源安装时不会经过 registry 的检查,因此请自行运行 gamedev pkg validate;它们也是共享使用提案中 API 的包的方式:
gamedev pkg add github:acme/level-tools # the default branch: moves with each push
gamedev pkg add github:acme/level-tools@v1.2.0 # a tag: pinned, never auto-updated
gamedev pkg add npm:acme-level-tools@^1.2.0 # an npm package and range
gamedev pkg add file:../level-tools # a folder- GitHub: 带标签时,应用会下载名称以
.aigd.tgz结尾的 release 资源(附上gamedev pkg pack写出的文件);否则使用该提交处的仓库,因此aigd-package.json必须位于根目录,且dist/需已提交。 - npm: 对包文件夹执行
npm publish。npm 归档必须包含aigd-package.json和dist/;还要在package.json中添加"engines": { "aigd": "<range>" },这样应用无需下载就能跳过无法运行的版本。 - 团队: 在 Project 级别添加包,使其提交到
.ai-game-dev/packages.json,每位队友都能获得相同版本,并由项目的 lock 文件固定。
相关页面
- Trusted Publishing:无需存储密钥的 CI。
- Registry 规则与检查:了解检查会拒绝什么。
- Package CLI 参考:了解每个
publish选项。