# 包 CLI 参考 — AI Game Dev 应用与 CLI · AI Game Developer Wiki

面向包作者的 gamedev pkg 命令：init、validate、pack、link、unlink、dev、logs、publish 和 publisher，以及它们的选项与输出。

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

`gamedev` CLI 包含包作者需要的所有工具：它可以创建新包，在你编辑时针对真实项目运行它，按应用和注册表的方式检查它，构建出用户安装的那个确切归档包，并将它发布出去。`init`、`validate`、`pack` 和 `logs` 无需登录即可运行。`link`、`unlink` 和 `dev` 会更改项目的包，和所有包变更一样需要你登录；`publish` 需要登录或发布者令牌，`publisher` 需要登录。使用包的命令（`add`、`remove`、`update`、`settings` 等）在 [CLI 页面](https://ai-game.dev/zh-hans/docs/wiki/app/cli#pkg) 上。

```text
gamedev pkg init [dir] [--engine] [--id <publisher.name>]
gamedev pkg validate [dir] [--json]
gamedev pkg pack [dir] [--out <dir>] [--allow-proposed] [--json]
gamedev pkg link <folder> [--user|--project|--local]
gamedev pkg unlink <id> [--user|--project|--local]
gamedev pkg dev <folder> [--user|--project|--local]
gamedev pkg logs <publisher.name> [-f|--follow] [--lines N]
gamedev pkg publish [dir] [--notes <file>] [--token <agd_pub_…>] [--oidc-audience <aud>] [--no-wait] [--json]
gamedev pkg publisher claim|list|token …
```

每个作者命令都可以用 `--help` 打印其用法。

## 创建包：`pkg init`

将一个新包写入一个新文件夹或空文件夹（包含 `.git` 文件夹也可以）：

```bash
gamedev pkg init level-tools --id acme.level-tools
```

```text
Created acme.level-tools (a package) in /home/you/src/level-tools
  aigd-package.json  src/extension.ts  dist/extension.js (prebuilt)  src/types/aigd.d.ts (package API 0.4.0)
```

| 文件 | 说明 |
| --- | --- |
| `aigd-package.json` | 清单文件，带有用于补全的 `$schema` |
| `src/extension.ts` | 你的代码：`activate(ctx)` 和 `deactivate()` |
| `dist/extension.js` | 预构建，因此包在你首次构建之前就能运行；`main` 指向这里 |
| `src/types/aigd.d.ts`、`src/types/aigd-package.schema.json` | 包 API 类型和清单 schema |
| `package.json`、`tsconfig.json` | `npm run build`（`src/` 到 `dist/`）和 `npm run dev`（监听） |
| `README.md`、`.gitignore` | 留给你编辑 |

不带 `--id` 时，发布者为 `you`，名称为文件夹名：在分享之前请填上你自己的发布者。`--engine` 则改为写入一个 [游戏引擎包](https://ai-game.dev/zh-hans/docs/wiki/app/game-engine-packages)。

## 在项目中运行：`pkg link`、`unlink` 和 `dev`

`link` 让项目指向你的文件夹，而不是已发布的版本，默认在本地层级生效。该文件夹会就地使用，当它随包发布的文件发生变化时，会在每个打开的应用和 CLI 中重新加载，且永远不会自动更新。`unlink` 会从缓存恢复到其他层级所声明的版本，无需下载。

`pkg dev` 是面向带构建步骤的包的 `pkg link`：它会运行包自带的 dev 脚本；如果没有，则在包不随包发布的文件（即其源码）发生变化时重新运行其构建脚本，在首次构建成功后链接该文件夹，并在按下 Ctrl+C 时停止它启动的所有进程。该链接会一直保持，直到你执行 unlink。

```text
Running its dev script (tsc -p tsconfig.json --watch --preserveWatchOutput). Ctrl+C stops it.
Waiting for its first build (dist/extension.js) before linking …
First build in 900 ms.
Linked acme.level-tools → ~/src/level-tools (local level, not committed).
```

清单中命名了另一个 id 的文件夹会被拒绝（`id-mismatch`）；被移动过的文件夹会连同恢复方法一起报告。

## 查看日志：`pkg logs`

按时间顺序打印应用后台服务中某个包的日志行：你的代码记录的所有内容（`ctx.log`、`console.*`）以及宿主关于该包的行（激活、带堆栈的失败）。`-f` 持续跟随；`--lines N` 更改最初显示的行数（100）。

```text
2026-11-16T10:12:03.114Z 41872 [10:12:03.114] INFO  [core:pkg-host] pkg=acme.level-tools state=active ms=4
2026-11-16T10:12:03.118Z 41872 [10:12:03.118] INFO  [pkg:acme.level-tools] activated
2026-11-16T10:12:09.502Z 41872 [10:12:09.502] ERROR [pkg:acme.level-tools] save failed: Error: EACCES …
```

## 检查：`pkg validate`

运行应用和注册表所执行的检查，并给出各自的文件和字段：

- 按应用读取清单的方式检查：schema、包所拥有的 id、`when` 子句、设置、菜单、游戏引擎规则；
- 注册表的规则：发布者、符合 semver 的 `version`、`engines.aigd`；提议中的 API 在此处只是一个警告（`pack` 和 `publish` 会拒绝它）；
- 清单中指定的文件（`main`、`icon`、某个引擎的图标、起始模板预览和技能）是否在随包发布的文件中；
- 应用所安装的归档包：最多 20,000 个文件和 512 MiB 解包后大小，路径需符合 tar 头部长度，不能有符号链接（会被跳过并给出警告）。注册表自身的限制更严格：5,000 个文件、单个文件 64 MiB、解包后 200 MiB、压缩后 50 MiB（参见 [注册表规则与检查](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry#limits)）。

```text
acme.level-tools 0.1.0 (/home/you/src/level-tools)
  error    aigd-package.json contributes.commands[1].command: "level.export" must be "acme.level-tools.<id>"
  error    aigd-package.json main: "dist/extension.js" does not exist (build it first: npm run build)
5 files ship, 4.2 KB.
Not valid: 2 errors.
```

通过时退出码为 0（允许警告），出现任何错误则为 1。`--json` 会打印供 CI 使用的结果。

## 构建归档包：`pkg pack`

先进行校验，然后写出注册表针对同一文件夹构建的那个确切归档包：确定性（条目排序、固定时间和所有者），因此相同的文件在每台计算机上都会产生相同的字节和相同的完整性哈希。

```text
Packed acme.level-tools 0.1.0 → /home/you/src/level-tools/acme.level-tools-0.1.0.aigd.tgz
  files      5 (4.2 KB unpacked)
  size       2025 bytes
  integrity  sha512-ZrbOleD47onMM7hMss123CDMOEp5sAlDig7ISGpjhE6JT3btOAtFoWE2+DzSSoVQcfqzRj4seI1T2xajawpsIQ==
  treeHash   sha256-BTeAbus6JQO+VKxsSOjfGN9A0v+nkfdmtRiJ/KvNpug=
```

**随包发布的内容：** 文件夹中的所有内容，除了顶层的 `src/`、`test/`、`tests/`、`coverage/`、`.turbo/`、`.agent-scratch/`、`.fixtures/`、`tsconfig*.json`、`vitest.config.*`、`*.tsbuildinfo`、`.aigd-install.json` 和 `*.tgz`，以及任意层级的 `node_modules/`、`.git/` 和 `.DS_Store`。应用从不为包运行 `npm install`：请把你的依赖库打包进 `dist/`。`--allow-proposed` 可打包使用提议中 API 的包，仅适用于 GitHub、npm 或文件夹来源。

## 发布：`pkg publish`

先打包（使用 `pkg pack` 的检查和字节），上传到社区注册表，然后等待其自动检查并打印报告：

```text
Packed acme.level-tools 0.1.0: 5 files, 2025 bytes, sha512-ZrbO…
Uploaded acme.level-tools 0.1.0 to ai-game.dev: uploaded
Waiting for the registry's checks (archive, manifest, rules, secrets, prompt injection, native code, virus scan)…
  state: checking
  state: published
Published acme.level-tools 0.1.0.
```

| 选项 | 作用 |
| --- | --- |
| `--notes <file>` | 一个 Markdown 文件（最大 20 KB），包含此版本的发布说明；若不提供，则使用 `CHANGELOG.md` 中该版本的章节 |
| `--token <agd_pub_…>` | 发布者令牌（或 `AI_GAME_DEV_PUBLISHER_TOKEN` 环境变量） |
| `--oidc-audience <aud>` | 覆盖 Trusted Publishing 使用的 OIDC audience（或 `AIGD_OIDC_AUDIENCE`）；CLI 会从仓库源推导该值，生产环境为 `ai-game.dev` |
| `--no-wait` | 上传完成后立即返回 |
| `--json` | 以 JSON 形式输出结果，便于脚本使用 |

`publish` 按以下顺序选择凭据：如果提供了发布者令牌则使用它，否则使用 GitHub Actions 或 GitLab CI 中的 OIDC 令牌（Trusted Publishing，需要 0.32.0 以上版本的 CLI；在 CI 中若缺少相关配置会直接报错，而不会回退），最后使用你已登录的会话。对已上传的版本再次运行 `publish` 时，它只会读取该版本的检查结果，而不会重复上传。版本被拒绝时以退出码 1 结束，并列出每个未通过的检查及其原因。关于频道以及在没有令牌的情况下从 CI 发布，请参阅 [Publishing packages](https://ai-game.dev/zh-hans/docs/wiki/app/publishing-packages) 和 [Trusted Publishing](https://ai-game.dev/zh-hans/docs/wiki/app/trusted-publishing)。

## 管理发布者：`pkg publisher`

```bash
gamedev login                                          # once, in the browser
gamedev pkg publisher claim acme --name "Acme Tools"   # claim a publisher id
gamedev pkg publisher list                             # your publishers and your role
gamedev pkg publisher token create acme --label github-actions --days 90
gamedev pkg publisher token list acme
gamedev pkg publisher token revoke acme <token id>
```

令牌只显示一次，有效期最长 365 天，且只能用于上传、读取版本状态和撤回版本。

## 相关页面

- 快速上手请参阅 [Creating packages](https://ai-game.dev/zh-hans/docs/wiki/app/creating-packages)。
- `validate` 和 `publish` 会拒绝哪些内容，请参阅 [Registry rules and checks](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry)。

---

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

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