本页由英文机器翻译而成。阅读英文原文。

包的生命周期、宿主与权限

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

更新于 2026年11月19日 查看 Markdown 版本

本页说明一个包从安装到移除之间发生了什么:它的代码在哪里运行、何时启动和停止、被允许做什么、错误如何传到你手上,以及它所针对的 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)。完整的事件列表见清单参考。

当活动包集合发生变化时宿主会重启,崩溃后也会重启(分别在 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 中进行迁移。