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

创建包

编写你自己的 AI Game Dev 包：aigd-package.json 清单、命令、斜杠命令、MCP 工具，用 gamedev pkg dev 本地开发，以及分享。

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

包并不专属于第一方功能：你也可以自己编写包，用来与团队分享重复性任务、为 agent 添加工具，或预览自定义文件格式。本页介绍包的目录结构、一个最小可用的包、主要清单字段、如何添加 MCP 工具、如何针对正在运行的应用开发包，以及如何分享它。

你需要什么

  • AI Game Dev 桌面应用或 gamedev CLI，版本 0.18.0 或更高。
  • 一个文本编辑器。JavaScript 是可选的：包可以只有清单。

包遵循 VS Code 扩展的模型：一个包含清单 aigd-package.json 的文件夹，以及可选的代码，代码导出 activate(ctx) 和 deactivate()。你的代码只能通过 ctx.aigd 访问应用。它运行在独立的扩展宿主进程中，每个打开的项目一个，并在需要时惰性启动。

包的目录结构

my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE

包必须自包含：应用不会为它运行 npm install。如果你的代码使用了库，请把它们打包进 main 指向的文件中。

一个最小的包

这个包添加了一个 /my-first 斜杠命令、一个命令面板条目、一个编写器工具栏按钮、一个状态栏项和一个设置。

{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}

以及代码 extension.js（CommonJS）：

const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};

斜杠命令、工具栏按钮和状态栏项在任何代码运行之前就由清单呈现出来；第一次使用其中任意一项时才会调用 activate。

ID 与命名规则

  • 包 ID 为 publisher.name，全部小写：此处是 you.my-first-package。发布者名称长度为 2 到 40 个字符（字母、数字、单个连字符）。请使用你自己的发布者名称；aigd 是 AI Game Dev 的。
  • 包贡献的每个 ID（命令、视图、状态栏项、教程）都以包 ID 开头：you.my-first-package.hello。
  • engines.aigd 是必需的：它表示该包所需的最低 AI Game Dev 版本，例如 ">=0.18.0"。较旧的应用会拒绝该包，并说明它需要哪个版本。
  • version 遵循 semver。安装会按 ID 和版本缓存，因此你发布的每次更改都需要更高的版本号。

主要清单字段

字段必需用途
publisher、name、version是ID 和版本
engines.aigd是最低应用版本
displayName、description、icon、license、homepage、repository、keywords否Packages 窗口显示的内容
main否代码入口；没有它，包就是仅贡献型
activationEvents否额外的启动代码事件，例如 onStartupFinished
hosts否desktop、cli 或两者
dependencies否其他包，{ "<id>": "<range>" }
claudePlugins否包所需的 Claude 插件，{ "<plugin>@<marketplace>": "<range>" }
contributes否包添加的所有内容（见下文）

contributes 中的贡献点包括 commands、slashCommands、capabilities（会话 Tools 行中的开关）、mcpServers、settings、panels、viewsContainers 和 views（侧边面板中的树视图或 webview 视图）、menus 和 submenus、keybindings、customEditors、statusBar 和 tutorials。菜单使用固定 ID，例如 commandPalette、composer/toolbar、explorer/context、editor/title 和 view/item/context，每个都可带可选的 when 子句。CLI 会显示斜杠命令、Tools 行、消息、快速选择、输入框和表单；菜单和面板仅桌面端可用。

通过 MCP 服务器为 agent 提供工具

编写包最常见的原因就是给 agent 提供新工具。声明一个 MCP 服务器，并用一个能力按会话启用它：

{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}
  • 服务器名称必须是包 ID 形式的 <publisher>--<name>（或 <publisher>--<name>-<suffix>），最多 96 个字符，这样不同作者的名称永远不会冲突。不带限定前缀的名称会报错。
  • 在 stdio 服务器中可使用的变量：${node}、${packageDir}、${projectDir} 和 ${globalStorage}。
  • 如果某个会话中已经配置了同名 MCP 服务器，则不会添加包中的服务器，并且会话中会显示一条提示。

针对正在运行的应用进行开发

将项目指向你的文件夹，而不是已发布的版本。该文件夹会被就地使用，当它携带的文件发生变化时会重新加载，并且永远不会自动更新。默认级别是 Local，它永远不会被提交。

cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version

如果你的包带有构建步骤（src/ 会构建到 dist/），请改用 gamedev pkg dev。它会运行包的 dev 脚本，或在每次源码变更后重新运行 build，在首次构建成功后链接该文件夹，并在你按下 Ctrl+C 时停止它启动的所有进程：

gamedev pkg dev <path-to-your-package>

在桌面应用中，同样的操作位于 Packages 窗口：选中包并选择 Use a local folder…，若要还原则选择 Stop using local folder。如果某个文件夹的 manifest 声明的是另一个 id，它会被拒绝。

分享你的包

AI Game Dev 注册表收录了第一方包。要分享你自己的包，可将其发布到 GitHub 或 npm；之后任何人都可以通过链接添加它：

gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range

如果是团队使用，请在 Project 级别添加它，这样它会被提交到 .ai-game-dev/packages.json 中，每位队友都能获得，并由项目锁文件固定版本。

在发布新版本之前，请先提升 aigd-package.json 中的 version。如果版本号未变而文件发生了改动，这项改动永远不会到达已经安装了该版本的安装实例。

良好实践

  • 让工具保持专注。智能体看到的每个工具都会占用上下文；一个小巧且描述清晰的工具往往更容易被正确使用。
  • 在 manifest 中尽可能声明所有内容，这样在你的代码启动之前，UI 就已经可见。
  • 对于团队应当共享的设置，使用 scope: "project"；对于某台计算机上的路径，使用 scope: "machine"。
  • 包以你用户的权限运行，且没有沙箱。不要在包中携带密钥，并告知用户你的包会做什么。

了解更多