# 包的生命周期、宿主与权限 — AI Game Dev 应用与 CLI · AI Game Developer Wiki

AI Game Dev 如何运行包：Extension Host、惰性激活、桌面端与 CLI、层级与更新、错误与日志、权限以及 API 版本管理。

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

本页说明一个包从安装到移除之间发生了什么：它的代码在哪里运行、何时启动和停止、被允许做什么、错误如何传到你手上，以及它所针对的 API 如何保持兼容。这是你发布一个供他人安装的包之前需要了解的背景知识。

## 包在哪里运行

应用在一个 **Extension Host**（独立进程）中运行包代码，方式与 VS Code 运行扩展相同。应用的背景服务（Kernel）为每个打开的项目运行一个 Extension Host，该项目所有打开的桌面窗口和 CLI 都共享这一个实例。你的代码只能通过消息通道、经由 `ctx.aigd` 与应用通信。

|  | 桌面应用 | `gamedev` CLI |
| --- | --- | --- |
| 它显示的 UI | 全部内容：菜单、面板、视图、自定义编辑器、状态栏、教程、webview | 斜杠命令、Tools 行、消息、快速选择、输入框、表单、进度行 |
| 仅桌面端可用的调用 | 正常工作 | 解析为 `undefined` 或无作用的对象，并记录一次日志 |
| Extension Host 进程 | 每个项目共享 | 每个项目共享 |

没有打开项目的窗口不会运行任何宿主。安装在用户级别的包会在每个打开的项目中运行，除非该项目将其排除。

## 惰性激活

1. **安装。** 应用读取清单，并一次性注册所有已声明的贡献点：斜杠命令、Tools 开关、菜单项和视图无需运行任何代码就会出现。
2. **激活。** 当第一次有东西需要这段代码时（运行命令、打开视图、启用某项能力、打开匹配的文件、发现引擎项目），宿主加载 `main` 并调用 `activate(ctx)`。依赖项先激活。`activate` 有 30 秒时间。
3. **运行。** 你的处理函数应答应用的调用。你注册的所有内容都在 `ctx.subscriptions` 中。
4. **停止。** 在移除、包被禁用、更新或宿主重启时，宿主调用 `deactivate()`（可选）并释放 `ctx.subscriptions`。

只声明了 `main` 而没有任何事件的包会在首次渲染后启动（`onStartupFinished`）。完整的事件列表见[清单参考](https://ai-game.dev/zh-hans/docs/wiki/app/package-manifest#activation-events)。

当活动包集合发生变化时宿主会重启，崩溃后也会重启（分别在 1 秒、5 秒和 30 秒后）。如果五分钟内崩溃三次，宿主会保持停止状态，直到用户点击 Packages 窗口中的 **Reload**。

## 层级、锁定与更新

用户可以在以下三个层级之一添加包：

| 层级 | 声明于 | 共享范围 |
| --- | --- | --- |
| 用户 | `~/.ai-game-dev/packages.json` | 该用户的所有项目 |
| 项目 | `<project>/.ai-game-dev/packages.json` | 提交到仓库：每个队友都会获得 |
| 本地 | `<project>/.ai-game-dev/packages.local.json` | 仅限此计算机，永不提交 |

本地覆盖项目，项目覆盖用户。每个层级旁边的锁文件固定确切的版本、tarball 和哈希，因此队友安装的是完全相同的字节。自动更新默认开启（按包、按计算机）：每四小时，应用会把每个包升级到其声明范围内应用可运行的最新版本，并为整次运行显示一条通知。`file:` 链接和固定到某个 tag 的 GitHub 源永远不会自动更新。

## 错误与日志

宿主会把每次失败归属到对应的包：`activate`、`deactivate` 或处理函数中的抛出、来自你的文件的未捕获异常或未处理的 rejection、`ctx.reportError(err)` 以及 `ctx.log.error(msg, err)`。Packages 窗口中每个包的 **Errors** 标签页会显示“N errors · M crashes”以及带堆栈的近期列表。

```bash
gamedev pkg logs acme.level-tools          # its last 100 lines
gamedev pkg logs acme.level-tools -f       # and every new one until Ctrl+C
```

日志位于所有平台上的 `~/.ai-game-dev/daemon/logs/`。第三方包的错误永远不会发送到 AI Game Dev 的崩溃报告；只有 AI Game Dev 自家的包会上报，并且仅在用户同意崩溃报告时才会上报。

## 权限与信任

AI Game Dev 遵循 VS Code 的模式：**没有沙盒，也没有权限提示**。包的代码以用户自己的权限运行：它可以读写文件、启动进程并使用网络，就像用户安装的任何程序一样。取而代之，让用户知情的是：

- **一切先可见。** 包所展示的一切都在其清单中声明，并在其代码运行之前就可见。
- **所有权会被强制执行。** 一个包只能注册或更改它自己拥有的 id（`<package id>.<local>` 命令、视图和上下文键，`<publisher>--<name>` 服务器），在加载时以及每次调用时都会检查。它可以运行任何命令：它自己的、其他包的命令或应用命令；而 webview 页面只能运行它自己包的命令和应用命令。
- **它声明的内容都会显示出来。** 安装前，Packages 窗口会显示注册表索引所描述的内容：原生代码、Claude 插件、依赖项。安装后，它还会显示该包是否会运行代码、启动工具服务器或提供一个游戏引擎。这些只是信息，绝不是门槛。
- **注册表检查。** 社区注册表中的每个版本都通过了自动检查，包括凭据、针对 agent 的提示注入、恶意软件和压缩包花招；参见 [Registry rules and checks](https://ai-game.dev/zh-hans/docs/wiki/app/package-registry)。
- **撤销。** AI Game Dev 可以撤销某个恶意版本；每个应用会在下一次读取索引时（大约半小时内）将其禁用。
- **Webview 页面是隔离的。** 页面运行在没有 Node.js 的沙箱框架中；webview 窗口则完全没有网络访问权限。

作为作者：不要发布密钥，要让你的包所做之事从 README 和 manifest 中一目了然，并且在执行任何破坏性操作前先询问用户。

## 版本管理与兼容性

API 的版本由两个数字表示，二者都不是你的包的 `version`：

- **包 API 版本**（当前为 0.4.0）只会通过新增来增长：新增成员和贡献点。你的 `aigd.d.ts` 中写明了它所对应的版本。
- **最低受支持的 `engines.aigd`**（当前为 0.18.0）是应用仍会加载的最低版本下限。只有提高它，稳定成员才会被移除，而且要在至少两个次版本发布弃用警告之后。

你需要遵循的规则：

- 将 `engines.aigd` 设置为你测试过的最旧的应用版本。比它更旧的应用会拒绝该包，并提示用户更新。
- 当你需要支持早于某个成员的应用版本时，请对可选成员（`aigd.gameEngines?`、`item.pulse?.()`）做特性检测。
- 提案中的成员不在此列。参见 [stable and proposed API](https://ai-game.dev/zh-hans/docs/wiki/app/package-api#stable-vs-proposed)。
- 你存储的数据属于你自己：用 `dataVersion` 为其标注版本，并在 `activate` 中进行迁移。

## 相关页面

- [Package API](https://ai-game.dev/zh-hans/docs/wiki/app/package-api) 介绍各种调用。
- [Packages](https://ai-game.dev/zh-hans/docs/wiki/app/packages) 介绍用户侧的层级和更新。
- [Package CLI reference](https://ai-game.dev/zh-hans/docs/wiki/app/package-cli) 介绍 `pkg logs`、`link` 和 `dev`。

---

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

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