# 包 — 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 中都能使用。
- 用于命令面板的**命令**、**菜单**和编辑器工具栏按钮、**状态栏**项。
- **面板**、侧边栏**视图**、独立窗口，以及针对文件类型的**自定义编辑器**或预览。
- **设置**、应用内简短的**教程**，以及对其他包或 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 插件内部的更多工具 | 侧边栏的扩展操作，或 `/install-extension`（见[扩展](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-hans/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-hans/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-hans/docs/wiki/app/packages-catalog)中查看所有可用的包。
- 在[创建包](https://ai-game.dev/zh-hans/docs/wiki/app/creating-packages)中构建你自己的包。
- 博文[包、Claude 插件与 MCP 服务器](https://ai-game.dev/zh-hans/blog/ai-game-dev-packages-plugins-mcp)展示了 Packages 窗口和项目 MCP 服务器的实际效果。

---

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

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