# 套件 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-hant/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 型別與資訊清單結構定義 |
| `package.json`、`tsconfig.json` | `npm run build`（`src/` 到 `dist/`）與 `npm run dev`（監看） |
| `README.md`、`.gitignore` | 供你自行編輯 |

若未指定 `--id`，發佈者會是 `you`，名稱則是資料夾名稱：分享前請先換成你自己的發佈者。`--engine` 則會改為寫入[遊戲引擎套件](https://ai-game.dev/zh-hant/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`

執行應用程式與登錄庫所進行的檢查，每項都會附上其檔案與欄位：

- 應用程式讀取資訊清單的方式：結構定義、套件所擁有的 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-hant/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 中的 CI OIDC 權杖（Trusted Publishing，需 CLI 版本高於 0.32.0；在 CI 中若設定不齊全會直接報錯，不會退回其他方式），最後才是你已登入的工作階段。對已上傳的版本再次執行 `publish` 時，會改為讀取它的檢查結果，而不會重複上傳。版本遭拒時會以退出碼 1 結束，並列出每個未通過的檢查及其原因。通道，以及在沒有權杖的情況下從 CI 發佈，請見[發佈套件](https://ai-game.dev/zh-hant/docs/wiki/app/publishing-packages)與 [Trusted Publishing](https://ai-game.dev/zh-hant/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 天，且僅能上傳、讀取版本狀態與 yank。

## 相關頁面

- 快速入門請見[建立套件](https://ai-game.dev/zh-hant/docs/wiki/app/creating-packages)。
- `validate` 與 `publish` 會拒絕哪些內容，請見[登錄檔規則與檢查](https://ai-game.dev/zh-hant/docs/wiki/app/package-registry)。

---

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

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