# 套件 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

AI Game Dev 應用程式中有哪些套件、如何在 Packages 視窗或使用 gamedev pkg 安裝、更新、排除與移除套件，以及層級如何運作。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/packages)。

套件能以完整功能擴充 AI Game Dev 應用程式：Blender、以 SuperCollider 製作音樂、專案知識庫、Tripo 3D 生成、本機影像與視訊模型、雲端視訊與音訊模型，以及團隊自行打造的任何東西。本頁說明什麼是套件、應用程式內建哪些套件，以及如何在桌面版 Packages 視窗和用 `gamedev pkg` 指令管理它們。

## 什麼是套件

套件是一個含有資訊清單 `aigd-package.json` 的資料夾，可選擇性地包含一些 JavaScript。這個模型和 VS Code 擴充功能相同：套件所顯示的一切都宣告在其資訊清單中，並在其程式碼執行前就可見，而程式碼只在有需要時才啟動。

套件可以提供：

- **工作階段工具**，位於 Tools 列，通常由 MCP 伺服器支援，讓代理取得新工具。
- **斜線指令**，例如 `/blender` 或 `/kb`，可在桌面版聊天與 CLI 中使用。
- 供命令面板使用的**指令**、**選單**與 composer 工具列按鈕、**狀態列**項目。
- **面板**、側邊面板**檢視**、獨立視窗，以及針對檔案類型的**自訂編輯器**或預覽。
- **設定**、簡短的應用程式內**教學**，以及對其他套件或 Claude 外掛的**相依性**。
- 純資料：本機影像與視訊模型就是沒有程式碼的套件，它們宣告自己的檔案、下載大小、授權，以及適合的硬體。

每個套件都有一個 `publisher.name` 形式的 id。第一方套件使用發佈者 `aigd`，例如 `aigd.blender`。

## 套件、Claude 外掛、MCP 伺服器與引擎擴充功能

應用程式有四種擴充功能。它們最終都會成為代理可用的工具，但管理的位置不同：

| 種類 | 擴充什麼 | 管理位置 |
| --- | --- | --- |
| 套件 | 應用程式本身：工具、指令、面板、編輯器、模型 | Packages 視窗、`/packages`、`gamedev pkg` |
| Claude 外掛 | Claude 代理：技能、指令、代理、外掛的 MCP 伺服器 | **Settings**、**Claude Plugins**，或 `/plugin` |
| MCP 伺服器 | 來自任何 MCP 伺服器（本機或遠端）的工具，供目前專案使用 | **Settings**、**MCP servers**，或 `/mcp` |
| 引擎擴充功能 | Unity、Unreal 或 Godot 外掛內更多工具 | 側邊欄的 extensions 動作，或 `/install-extension`（請見 [extensions](https://ai-game.dev/docs/extensions)） |

你在 Settings 中新增的 MCP 伺服器屬於新增時所開啟的專案，在其他專案中永遠看不到。新的外掛或 MCP 伺服器會從下一則訊息起套用到已經開啟的聊天。

## 應用程式隨附的套件

首次啟動時，應用程式會在使用者層級為你安裝預設套件，因此每個專案都能使用：

| 套件 | 新增什麼 |
| --- | --- |
| `aigd.blender` | Blender：代理在真正的 Blender 中建立與編輯 3D 模型 |
| `aigd.supercollider` | 音樂：以 SuperCollider 作曲、算繪與匯出遊戲音樂 |
| `aigd.knowledge` | 知識庫：專案中的 Markdown 筆記，代理會讀取並更新 |
| `aigd.tripo` | Tripo：3D、貼圖、網格、骨架與動畫工具 |
| `aigd.sdcpp` | 使用 stable-diffusion.cpp 進行本機影像與視訊生成 |

你移除的預設套件不會再次被加入。安裝套件並不代表每個聊天都會帶著它：你需要在 Tools 列依工作階段開啟它的工具。本機影像與視訊模型，以及雲端模型系列，都是獨立的套件；全部請見 [套件目錄](https://ai-game.dev/zh-hant/docs/wiki/app/packages-catalog)。

## Packages 視窗

從視窗右下角狀態列的套件圖示開啟（「Open Packages」）。視窗上方會顯示專案及其層級，並有以下分頁：

- **Installed**：此專案中啟用的套件，包含其狀態、版本與層級。
- **Browse**：搜尋 AI Game Dev 套件登錄庫。
- **Claude plugins**：此專案中套件所需的 Claude 外掛。
- **Models**：可下載的本機影像與視訊模型，會在專案具有生成執行環境時顯示。

標頭有 **Check for updates** 與 **Reload**，後者會重新啟動專案的套件。選取套件即可查看其詳細資料、層級、設定與錯誤。

## 安裝套件

### 在桌面版應用程式中

1. 開啟 Packages 視窗並選擇 **Browse**。
2. 搜尋，例如 `hello`，然後選取該套件。
3. 在新增按鈕下方選擇層級：**User**、**Project** 或 **Local**（請見 [層級](https://ai-game.dev/zh-hant/docs/wiki/app/packages#levels)）。
4. 點選 **Add to Project**（或 **Add to User**、**Add to Local**）。

若要新增登錄庫以外的套件，請在新增方塊中輸入。它接受登錄庫 id（`aigd.blender`，可選擇加上版本範圍，例如 `aigd.blender@^1.2`）、GitHub 連結或 `owner/repo`、npm 套件（`npm:<name>` 或其 npmjs.com 連結），或資料夾路徑。

### 在 CLI 中

在專案資料夾中執行 `gamedev pkg`（或傳入 `--cwd <path>`），或在互動式 CLI 中使用 `/packages`。預設層級為 `--project`。

```bash
gamedev pkg list                          # the packages in effect for this project
gamedev pkg list --user                   # the user level alone
gamedev pkg add aigd.blender --user       # from the registry, for every project
gamedev pkg add github:owner/repo         # from GitHub, for this project
gamedev pkg add npm:some-package --local  # from npm, this machine only
```

未指定版本範圍而新增的登錄庫套件會寫成 `^<installed version>`，因此能取得相容的更新。

## 層級：user、project、local

套件及其設定會在三個層級宣告。較高層級會覆寫較低層級：local 優先於 project，project 優先於 user。

| 層級 | 適用於 | 宣告於 | 是否提交至 Git |
| --- | --- | --- | --- |
| User | 此電腦上的每個專案 | `~/.ai-game-dev/packages.json` | 否 |
| Project | 開啟此專案的每個人 | `<project>/.ai-game-dev/packages.json` | 是 |
| Local | 僅限此電腦上的此專案 | `<project>/.ai-game-dev/packages.local.json` | 否（應用程式會將它加入 `.ai-game-dev/.gitignore`） |

每個層級旁邊也各有一個鎖定檔（`packages-lock.json`、`packages-lock.local.json`），會釘住確切版本，讓共用專案鎖定檔的隊友安裝到完全相同的位元組。

團隊全體需要的套件請用 **Project**，個人工具用 **User**，而只在特定機器上適用的選擇（例如指向你電腦上安裝的某個工具的路徑）則用 **Local**。

## 在單一專案中排除套件

若要在某個專案中關閉使用者層級的套件，請選取它並在層級列上選擇 **Exclude**，或：

```bash
gamedev pkg exclude aigd.blender            # off in this project (written to the project file)
gamedev pkg include aigd.blender            # undo
```

專案檔便會包含 `"aigd.blender": false`；其他專案不受影響。

## 更新套件

自動更新預設為開啟。應用程式會在啟動後不久、每四小時，以及你點選 **Check for updates** 時檢查。它會在每個層級所宣告、且與你的應用程式相容的範圍內安裝最新版本，並每次執行顯示一則通知，例如「Updating 1 package… (1/1)」，接著顯示「Updated 1 package」。

- 在 Packages 視窗中以套件的 **Auto-update** 開關，或用 `gamedev pkg auto-update off <id>` 關閉單一套件的自動更新。此選擇依電腦而定。
- 用 `gamedev pkg update`（全部）或 `gamedev pkg update <id>` 立即更新。
- 來自本機資料夾的套件，以及釘在標籤上的 GitHub 來源，永遠不會自動更新。

需要較新應用程式的套件會這麼說（「requires AI Game Dev >=X, you have Y」）；請先更新應用程式。

## 移除套件

選取它並選擇 **Remove**，或：

```bash
gamedev pkg remove <id>              # remove it from the project level
gamedev pkg remove <id> --user       # remove it from the user level
```

只作為其他套件相依性而安裝的套件沒有 Remove，只有 Exclude；當沒有東西需要它時，它會自行消失。

## 套件設定

選取套件並開啟 **Settings**。每個設定旁可選擇要寫入的層級；標籤會顯示目前值的來源。有些設定是附有 **Browse…** 與可用空間檢查的資料夾選擇器，有些則提供來自應用程式的選項。

在 CLI 中：

```bash
gamedev pkg settings aigd.blender                 # every key, its value and level
gamedev pkg settings <id> <key> <value> --local   # write a value at a level
gamedev pkg settings <id> <key> --unset --project # clear the value at a level
```

值在儲存前會依其宣告的型別檢查；被拒絕的值不會改變任何東西，並以代碼 1 結束。

## 相依性

套件可以相依於其他套件與 Claude 外掛。應用程式會替你安裝它們，並且每個專案中每個套件只保留一個版本。Packages 視窗會將相依性列為「installed for `<id>`」並顯示其層級。套件所需的 Claude 外掛會依專案安裝到應用程式擁有的快取中，且只會在那個專案的工作階段中載入，永遠不會載入到你自己的 Claude Code。

## 安全性與錯誤

套件以你的使用者權限執行，就像 VS Code 擴充功能一樣：沒有沙箱。請只從你信任的來源安裝套件。來自 AI Game Dev 登錄庫的套件在解壓縮前會依其發佈的校驗碼驗證。

如果套件失敗，其卡片會顯示警告數量，其 **Errors** 分頁會列出詳細資料。第三方套件的錯誤永遠不會被傳送到任何地方；來自我們登錄庫的第一方 `aigd` 套件錯誤，只會在你同意傳送當機報告時回報給我們。已安裝的套件無需網路連線即可啟動。

## 後續步驟

- 在 [套件目錄](https://ai-game.dev/zh-hant/docs/wiki/app/packages-catalog) 中查看所有可用的套件。
- 在 [建立套件](https://ai-game.dev/zh-hant/docs/wiki/app/creating-packages) 中打造你自己的套件。
- 文章 [套件、Claude 外掛與 MCP 伺服器](https://ai-game.dev/zh-hant/blog/ai-game-dev-packages-plugins-mcp) 示範了 Packages 視窗與專案 MCP 伺服器的實際運作。

---

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

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