包的生命周期、宿主与权限
AI Game Dev 如何运行包:Extension Host、惰性激活、桌面端与 CLI、层级与更新、错误与日志、权限以及 API 版本管理。
本页说明一个包从安装到移除之间发生了什么:它的代码在哪里运行、何时启动和停止、被允许做什么、错误如何传到你手上,以及它所针对的 API 如何保持兼容。这是你发布一个供他人安装的包之前需要了解的背景知识。
包在哪里运行
应用在一个 Extension Host(独立进程)中运行包代码,方式与 VS Code 运行扩展相同。应用的背景服务(Kernel)为每个打开的项目运行一个 Extension Host,该项目所有打开的桌面窗口和 CLI 都共享这一个实例。你的代码只能通过消息通道、经由 ctx.aigd 与应用通信。
| 桌面应用 | gamedev CLI | |
|---|---|---|
| 它显示的 UI | 全部内容:菜单、面板、视图、自定义编辑器、状态栏、教程、webview | 斜杠命令、Tools 行、消息、快速选择、输入框、表单、进度行 |
| 仅桌面端可用的调用 | 正常工作 | 解析为 undefined 或无作用的对象,并记录一次日志 |
| Extension Host 进程 | 每个项目共享 | 每个项目共享 |
没有打开项目的窗口不会运行任何宿主。安装在用户级别的包会在每个打开的项目中运行,除非该项目将其排除。
惰性激活
- 安装。 应用读取清单,并一次性注册所有已声明的贡献点:斜杠命令、Tools 开关、菜单项和视图无需运行任何代码就会出现。
- 激活。 当第一次有东西需要这段代码时(运行命令、打开视图、启用某项能力、打开匹配的文件、发现引擎项目),宿主加载
main并调用activate(ctx)。依赖项先激活。activate有 30 秒时间。 - 运行。 你的处理函数应答应用的调用。你注册的所有内容都在
ctx.subscriptions中。 - 停止。 在移除、包被禁用、更新或宿主重启时,宿主调用
deactivate()(可选)并释放ctx.subscriptions。
只声明了 main 而没有任何事件的包会在首次渲染后启动(onStartupFinished)。完整的事件列表见清单参考。
当活动包集合发生变化时宿主会重启,崩溃后也会重启(分别在 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”以及带堆栈的近期列表。
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。
- 撤销。 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。
- 你存储的数据属于你自己:用
dataVersion为其标注版本,并在activate中进行迁移。
相关页面
- Package API 介绍各种调用。
- Packages 介绍用户侧的层级和更新。
- Package CLI reference 介绍
pkg logs、link和dev。