# 发布包 — AI Game Dev 应用与 CLI · AI Game Developer Wiki

将包发布到 AI Game Dev 社区注册表：认领发布者、上传、发布说明、beta 渠道、弃用、撤回及其他分享方式。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/app/publishing-packages)。

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

![ai-game.dev 上的包目录：一个精选引擎包、分类筛选器，以及成排的官方包和社区包](https://ai-game.dev/images/wiki/app/catalog-packages.webp)

包目录：官方包和社区包，每个都带有自己的安装命令。

## 认领发布者

你的发布者 id 是你发布的每个包 id 的前半部分（`acme.level-tools` 中的 `acme`）。只需认领一次；先到先得：

```bash
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**；维护者可以上传、撤回、弃用、编辑发布说明、移动渠道并生成令牌。只有所有者可以管理成员和[受信任的发布者](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing)。

## 发布版本

在 `aigd-package.json` 中写入 `"publisher": "acme"`，提升 `version`，构建，然后：

```bash
gamedev pkg publish level-tools
```

CLI 会打包该文件夹（与 `gamedev pkg pack` 相同的检查和字节），上传并等待检查结果。一个版本会经历以下状态：

| 状态 | 含义 |
| --- | --- |
| `uploaded`、`checking` | 等待或正在运行自动检查 |
| `published` | 通过所有检查；约一分钟内进入已签名索引 |
| `rejected` | 某项检查失败；报告会列出每个失败项。修复后重新上传同一版本 |
| `yanked` | 由发布者撤回：版本范围会跳过它，已安装的会保留 |
| `revoked` | 由 AI Game Dev 移除（恶意软件、被盗账户）：所有应用都会将其关闭 |

**版本不可变。** 已发布、已撤回或已吊销的版本号永远无法再次上传；只有被拒绝的版本可以。请以新版本发布修复。

![目录中某个包的页面：名称、发布者、版本、安装按钮和命令、入门预览、About 面板以及最新发布](https://ai-game.dev/images/wiki/app/catalog-package-page.webp)

目录中某个社区包的页面。用户可一键或一条命令安装。

## 发布说明

每个版本都可以携带 Markdown 格式的发布说明。用户可在 Packages 窗口（**Versions**）以及发布者面板中按版本查看。上传时提供：

```bash
gamedev pkg publish level-tools --notes RELEASE_NOTES.md
```

如果没有 `--notes`，注册表会从版本标题（`## 1.2.0`、`## [1.2.0]` 或 `## v1.2.0`）开始，一直取到下一个同级或更高级标题之前的 `CHANGELOG.md`（位于包文件夹中，随归档一起分发）内容，截断至 20 KB：

```text
# 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）指定用户按名称请求时获得的版本：

```bash
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](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing)：

- **Trusted Publishing（推荐）：** GitHub Actions 或 GitLab CI 证明是哪个仓库和工作流在发布；无需在任何地方存储密钥，并且每个版本都会记录其来源。那里还介绍了现成的 GitHub Action 和 GitLab CI 模板 [IvanMurzak/gamedev-publish-action](https://github.com/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](https://ai-game.dev/publisher) 的 publisher 面板中，面向已登录的 owner 和 maintainer：你的 publisher 和包、每个版本及其状态和检查报告、发布说明、channel、弃用与撤下、成员和角色、publisher token，以及带可复制工作流片段的受信任发布者。参见 [Registry 规则与检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry#panel)。

## 其他来源：GitHub、npm 和文件夹

registry 并非共享包的唯一方式。这些来源安装时不会经过 registry 的检查，因此请自行运行 `gamedev pkg validate`；它们也是共享使用提案中 API 的包的方式：

```bash
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](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing)：无需存储密钥的 CI。
- [Registry 规则与检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry)：了解检查会拒绝什么。
- [Package CLI 参考](https://ai-game.dev/zh-hans/docs/wiki/app/package-cli#publish)：了解每个 `publish` 选项。

---

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

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