# 注册表规则与检查 — AI Game Dev 应用与 CLI · AI Game Developer Wiki

社区包注册表：命名规则、限额、自动检查、签名索引、发布者面板、其 API 以及供智能体阅读的 Markdown 页面。

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

上传到 AI Game Dev 社区注册表的每个版本都会在任何人安装之前自动接受检查；这里没有人工审核队列。本页列出了包必须遵循的规则、每项检查拒绝什么以及为什么、已发布的版本如何通过签名索引到达用户、发布者面板、注册表的 API，以及 AI 智能体读取的 Markdown 页面。

## 名称

- **发布者 ID** 为 2 到 40 个小写字母、数字和单个连字符，先到先得。保留项包括：`aigd`、引擎名称 `unity`、`godot`、`unreal`、`brutal`、`bevy` 和 `threejs`、商标和角色词（`anthropic`、`claude`、`openai`、`official`、`admin`、`samples` 等）、将数字折叠为字母后的形似名称（`un1ty`），以及任何将保留名称用作单词或前缀的 ID（`unity-tools`、`my-godot`）。AI Game Dev 可以将保留名称分配给其真正的所有者。
- **包 ID** 为 `<publisher>.<name>`，必须与 manifest 一致。诸如 `aigd.image` 之类的应用保留 ID 会被拒绝。
- **优先级：** 对于 `aigd.*` 的 ID 或 AI Game Dev 自有索引中列出的任何 ID，应用会忽略对应的社区条目，因此任何人都无法遮蔽官方包。

## 限额

| 限制项 | 值 |
| --- | --- |
| 归档包（gzip） | 压缩后 50 MiB，解压后 200 MiB |
| 文件数 | 每个归档包 5,000 个，单个文件 64 MiB |
| 每个账户的发布者数 | 3 |
| 上传次数 | 每小时 20 次（按账户计，使用令牌上传时按发布者计） |
| 等待检查的版本数 | 每个发布者 5 个 |
| 活跃的发布者令牌 | 每个发布者 10 个，每个有效期最长 365 天 |
| 受信任的发布者 | 每个包 10 个 |
| 发布说明 | 每个版本 20 KB 的 Markdown |
| 通道 | 每个包 5 个 |

## 自动检查

归档包被视为不可信数据：它在内存中按大小上限解包，并以字节形式读取，绝不执行。检查按以下顺序运行，报告中会列出每一项及其结果：

| 检查 | 拒绝内容 |
| --- | --- |
| `archive` | 非 gzip 的任何格式；超出限额的归档包；符号链接、硬链接、设备、绝对路径、`..`、控制字符、在 Windows 上无效的名称、忽略大小写后重复的名称、`.git/` |
| `manifest` | 应用无法加载的 manifest，使用应用自带的校验器检查：schema、所属 ID、游戏引擎规则 |
| `registry-rules` | 你并不拥有的发布者；保留 ID；任何 `enabledApiProposals` 条目；不在归档包中的 `main`；不是真实 PNG、JPEG、GIF、WebP 或 ICO 的图标，或包含脚本、样式、外部引用或事件处理器的 SVG |
| `secrets` | 私钥和凭据（云服务、GitHub、GitLab、Slack、Stripe、Google、Anthropic、OpenAI、npm、PyPI、Hugging Face、ai-game.dev 的密钥）、JWT、诸如 `.env`、`.npmrc` 或 `id_rsa` 的文件。报告只指出文件和行号，绝不显示具体值 |
| `prompt-injection` | 试图向智能体下达指令的文本（见下文） |
| `native-code` | 无：原生二进制文件会被允许并加以标记，用户会在包上看到“原生代码” |
| `virus-scan` | 病毒扫描器标记的任何内容，包括嵌套过深而无法扫描的归档包 |

未通过检查的版本会被标记为 `rejected` 并列出所有原因；修复后重新上传同一版本即可。当扫描器短暂不可用时，该版本会等待并重试；它绝不会未经扫描就通过。

### 提示注入

包中的文本会到达智能体：工具描述、skills、README、发布说明。注册表会用全部规则读取每个 manifest 字符串、`README*`、Markdown 和文本文件、`SKILL.md`、`CLAUDE.md`、`AGENTS.md` 以及 `skills/`、`agents/`、`commands/` 和 `prompts/` 下的文件，并用高置信度规则检查你的代码文件。文本会先被规范化（HTML 实体、Unicode 形似字符、不可见字符、Markdown 强调），因此伪装无效。它会拒绝：

- 要求忽略或覆盖先前指令，或要求泄露系统提示的指令；
- 聊天角色标记（`<|im_start|>`、`[INST]`、`<system>` 等）；
- 隐藏字符：零宽字符和双向控制字符、Unicode 标签字符；
- 解码后为可读文本的长 base64 字符串；
- 针对 AI 的 HTML 注释或隐藏元素；
- 要求将密钥、令牌、凭据或对话内容发送到任何地方；
- 越狱短语、要求对用户隐藏操作，以及要求自动批准工具或绕过权限检查。

普通的游戏词汇（“god mode”）、emoji、徽章和 API 文档都能通过。如果某项检查标记了无害的文本，请改写它，或向 AI Game Dev 报告该误报。

## 签名索引

已发布的版本写入它自己的存储（`community-packages.ai-game.dev`），并列在一个由注册表用 Ed25519 签名的社区索引中。每个应用都会用内置在应用中的密钥校验该签名，拒绝已过期或比它已经接受过的版本更旧的索引，并在解包前校验每个归档的 `sha512` 完整性、解包后校验其树哈希。除每个版本的归档外，索引还按包记录发布者、评分、README、图标、通道和弃用状态，并按版本记录发行说明（前 4 KB）、弃用、来源以及原生代码标志。

被 AI Game Dev 撤销的版本会列入索引的 `revoked` 列表：每个应用会在下一次读取时将其关闭（运行中的应用大约每 30 分钟读取一次索引），并且再也不会安装它。

## 发布者面板

位于 [ai-game.dev/publisher](https://ai-game.dev/publisher) 的发布者面板，是已登录的所有者和维护者管理其发布内容的地方：

- 你的发布者、你在每个发布者中的角色，以及它们的成员；
- 每个包的各个版本及其状态和完整检查报告；
- 发行说明、通道、弃用和撤下；
- 发布者令牌（创建、列出、撤销）；
- GitHub 和 GitLab 的可信发布者，附带可复制的工作流片段；
- 仍在检查中的上传任务的状态。

## 注册表 API 的路由

CLI 和面板所做的一切都通过 `https://ai-game.dev/api/registry/v1` 完成。错误使用统一的响应封装，`{"error": {"code", "message", "fields"}}`。

| 路由 | 谁 | 做什么 |
| --- | --- | --- |
| `POST /publishers`、`GET /publishers`、`GET /publishers/{slug}` | 已登录、成员 | 认领一个发布者；列出你的发布者；查看某个发布者及其包和版本 |
| `GET /me/publishers` | 已登录 | 你的发布者以及你在其中的角色 |
| `GET /publishers/{slug}/members` | 成员 | 成员列表（邮箱仅对所有者可见） |
| `POST /publishers/{slug}/members`、`DELETE …/members/{userId}` | 所有者 | 添加或移除维护者 |
| `POST /publishers/{slug}/tokens`、`GET …/tokens`、`DELETE …/tokens/{id}` | 成员 | 发布者令牌 |
| `POST /uploads`（multipart `tarball`，可选 `notes`） | 成员或令牌 | 上传一个版本 |
| `GET /packages/{id}/versions/{version}` | 成员或令牌 | 状态、检查报告和发行说明 |
| `PATCH /packages/{id}/versions/{version}` | 成员 | 编辑发行说明 |
| `POST /packages/{id}/versions/{version}/yank` | 成员或令牌 | 撤下或恢复 |
| `POST`、`DELETE /packages/{id}/deprecate` 以及 `…/versions/{version}/deprecate` | 成员 | 弃用或取消弃用 |
| `GET /packages/{id}/dist-tags` | 公开 | 通道 |
| `PUT`、`DELETE /packages/{id}/dist-tags/{tag}` | 成员 | 设置或移除通道 |
| `GET`、`POST /packages/{id}/trusted-publishers`、`DELETE …/{tpId}` | 读取需成员，修改需所有者 | 可信发布者 |
| `POST /oidc/token` | CI | 用 CI 身份令牌换取上传凭据 |
| `GET /packages/{id}/ratings`、`PUT` 和 `DELETE …/rating` | 公开，需登录 | 评分（包所属发布者的成员不能为该包评分） |

## 面向 Agent 的 Markdown 页面

AI Agent 以 Markdown 形式读取本站，因此关于包的一切内容都有对应的 Markdown 版本：

- **目录。** `ai-game.dev/packages` 的包目录（正在逐步推出）列出了所有官方和社区包，每个包在 `/packages/<id>` 都有自己的页面。在任一地址后加上 `.md`，或用 `Accept: text/markdown` 请求，即可获得相同内容的 Markdown 版本：名称、id、版本、发布者、描述以及安装命令。
- **这些文档。** 本 wiki 的每个页面在 `/docs-md/` 下都有 Markdown 镜像（本页为 `/docs-md/wiki-app-package-registry.md`），可从页面顶部的 **View as Markdown** 链接进入。镜像中每张截图都保留为图片链接。
- **面向 LLM 的站点索引。** `https://ai-game.dev/llms.txt` 列出了这些页面，因此当 Agent 需要编写一个包时，可以直接找到清单参考和包 API。

**提示**

要让 Agent 为你编写一个包，请把它指向 [package API](https://ai-game.dev/zh-hans/docs/wiki/app/package-api) 和 [manifest reference](https://ai-game.dev/zh-hans/docs/wiki/app/package-manifest) 的 Markdown 镜像，并让它在每次修改后运行 `gamedev pkg validate`。

## 相关页面

- [发布包](https://ai-game.dev/zh-hans/docs/wiki/app/publishing-packages)，介绍发布工作流。
- [可信发布](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing)，介绍 CI 和来源信息。
- [生命周期、宿主和权限](https://ai-game.dev/zh-hans/docs/wiki/app/package-lifecycle#permissions)，介绍包安装后可以做什么。

---

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

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