面向 AI 智能体的 CLI：在 Unity、Unreal 和 Godot 中最多减少 83% 的 token

我们的三个引擎命令行工具 unity-mcp-cli、unreal-mcp-cli 和 godot-cli，现在让 AI 智能体使用起来的成本低得多。在相同的编辑器任务上，冷启动的智能体消耗的 token 比旧版本减少 60% 到 83%，工具调用次数也明显更少。做到这一点靠的是一件简单又有点让人汗颜的事：我们只给一个小型 AI 智能体一个 CLI，观察它卡在哪里，把那里修好，然后再测一遍。

本文会走一遍这项工作的三轮迭代、相关数字（包括那个往反方向走的数字），以及适用于任何为 AI 智能体构建 CLI 的人的经验。如果你在 Unity、Unreal Engine 或 Godot 中使用 Claude Code、Codex 或其他智能体，这些改动意味着更短的会话、更少的重试和更低的账单。

我们如何测试面向 AI 智能体的 CLI

每一轮的每一次运行都采用同样严格的设置，因此结果反映的是真实智能体在真实机器上会遇到的情况：

• 智能体是一个小而快的 LLM（DeepSeek Flash）。小模型会暴露出大模型会悄悄绕开的粗糙边缘。
• 它只能拿到 CLI 和基本的文件工具。没有 MCP 连接，没有文档，提示词里也没有任何提示。
• 它从冷启动开始：全新的项目，引擎已关闭，没有任何缓存。
• 只有真实的最终状态正确，一次运行才算通过：磁盘上的场景或关卡文件，或者编译结果。智能体声称自己做了什么不算数。

我们统计了智能体读入和写出的 token、轮次或工具调用次数、工具错误次数以及通过的任务数。然后我们读了对话记录，因为数字告诉你某处慢，而对话记录告诉你为什么。

第一轮：智能体能找到路吗？

最初的对话记录很糟糕。智能体根本找不到编辑器的 AI 工具。当 CLI 提示“未登录”时，它们手动编辑配置文件来绕过。它们猜了一些并不存在的命令名。这些都不是智能体的错：CLI 只是没有告诉它需要知道的东西。

所以第一轮修复针对的是可发现性：

• 新增的 tools 命令即使在引擎关闭时也能列出编辑器的 AI 工具。它会启动一次无头编辑器，缓存列表，之后就从缓存中作答。
• --help 的输出现在结尾有一段简短的日常工作流脚注：智能体实际需要的那几条命令，按它需要的顺序排列。
• 从未登录 ai-game.dev 的机器现在会得到一个本地服务器，而不是死路一条。已登录的机器则始终留在云端。
• 无头编辑器在编译出错后仍能存活，并告诉智能体它的日志在哪里，而不是一声不响地失败。
• 新增的 test 和 compile 命令（godot-cli 称之为 check），以及 Unity 和 Unreal 的 dialog 命令，它可以列出阻塞编辑器的模态对话框，并能按下其中一个的按钮。
• 三个 CLI 的退出码保持一致，面向智能体的命令支持 --format json，输出可被脚本解析。

比较本阶段第一轮与最后一轮（每个任务一次运行）：

• Unity：输入 token 275k → 104k（−62%），轮次 46 → 30。
• Godot：输入 token 598k → 203k（−66%），轮次 71 → 40，通过任务 3/4 → 4/4，工具错误 27 → 6。
• Unreal：输入 token 383k → 414k（+8%），轮次 66 → 60，工具错误 13 → 8。

在三个引擎上合计，智能体每解决一个任务所用的输入 token 少了 1.9 倍（114k → 60k），并且 12 个任务全部通过，而不是 12 个里通过 11 个。

是的，Unreal 上升了。智能体犯的错误更少，用更少的轮次完成，但它在过程中读了更多内容。第一轮修的是智能体“能找到什么”，还没修它“必须读多少”，这正是下一轮要解决的。

第二轮：早期读的每一个字节，之后每一轮都要再付一次钱

这一轮的关键洞见一旦点破就很简单。智能体的对话会随着每一步增长，而它早期读过的所有内容，在之后的每一轮都会再次发给模型。第一轮读到的一大页帮助文档，会在第二轮、第十轮和第三十轮再次付费。

在基线中，根 --help（4.8 KB，而且总是智能体读到的第一样东西）占所有工具输出 token 权重的 43%。RQL schema 又占了 24%。两次早期读取就占了三分之二的成本。

修复措施：

• 简短的 --help，附上可直接使用的 RQL 配方，让智能体可以复制一个能跑的查询，而不是去研读参考文档。
• 用紧凑的 schema 概览代替完整版。
• RQL 错误中附带关于正确 source 或成员名的提示。
• 一等公民的 rql 命令，把查询作为普通参数传入，不必担心 JSON 引号写错。
• 保存操作会打印写入磁盘的文件。过去智能体要额外花 4 到 9 次调用去确认保存真的发生了。

RQL 是我们的编辑器工具用来读取和修改场景、对象、组件和资产的查询语言。你可以在 ai-game.dev/docs/rql 了解更多。

在叠加下一项之前，我们先单独测量每一个想法。在 Unreal 上，每个任务跑三次，阶梯是这样的：

1. 基线：403k token，60 次工具调用。
2. 带配方的简短帮助、紧凑 schema、RQL 提示：123k token（−69%）。
3. 加上一等公民的 rql 命令：106k token（−74%）。
4. 加上会打印写入文件的保存操作：68k token（−83%），31 次工具调用（−48%）。

同样的改动应用到三个 CLI，每次运行都从冷启动测量（Unreal 每个任务三次运行，Unity 和 Godot 两次）：

• Unreal：token 403k → 68k（−83%），工具调用 60 → 31。
• Unity：token 248k → 82k（−67%），工具调用 33.5 → 26，通过任务 4/4。
• Godot：token 131k → 53k（−60%），工具调用 34 → 28.5，通过任务 4/4。

第三轮：由 CLI 自己编写的小型 skill

许多智能体支持 skill：当任务匹配时由智能体加载的简短指令文件。现在每个 CLI 的 setup-skills 命令会离线写出一个约 2.2 KB 的 skill，无需运行编辑器。该 skill 与 --help 由同一份源生成，因此两者永远不会脱节。

我们在优化后的 CLI 上，对比了没有 skill 的智能体与有 skill 的智能体，涵盖三个编辑器任务、共 207 次隔离运行：

• Unity：token 160k → 60k（−63%），工具调用 42 → 23，18/18 通过。
• Unreal：token 87k → 53k（−39%），工具调用 37 → 24，9/9 通过。
• Godot：token 117k → 81k（−31%），工具调用 49 → 39，18/18 通过。

在调优 skill 的过程中，有三件事让我们意外：

• 更短的 skill 胜过更长的。skill 的每一行都会在每一轮被重新读取，就跟帮助文档一样。
• 把规则写成警告，会让智能体去做额外的检查。平实地陈述事实比警告它更有效。
• 对于只涉及代码的任务，skill 帮助不大。它的价值在于编辑器工作：场景、关卡、对象和资产。

给所有为 AI 智能体构建 CLI 的人的经验

这些没有一条是游戏引擎特有的。如果你要构建一个会被 AI 智能体使用的命令行工具，以下是我们要传下去的经验：

• 把工作流和配方放进 --help。智能体最先读帮助。给它们真正重要的五条命令和每一条的可运行示例，而不是完整参考。
• 让早期输出尽可能小。智能体在最初几轮读到的任何东西，之后每一轮都要再付一次钱。狠狠砍掉第一屏。
• 让结果能自我验证。当保存操作打印出“已保存到磁盘”和文件路径时，智能体就不会再花调用去核对。
• 给每个错误一个下一步。一个列出有效选项的错误，能把死路变成再一次调用。
• 用冷启动评测来衡量。用小模型、全新项目，并检查真实的最终状态。读对话记录，改一件事，再测一遍。

试一试

新命令已随各引擎插件的最新版本发布：unity-mcp-cli 1.11.1、unreal-mcp-cli 0.31.1 和 godot-cli 0.39.1。如果 unity-mcp-cli --help（或 Unreal、Godot 的对应命令）没有列出 rql 和 tools，说明你用的是更早的版本，update 命令可以把你带到最新版。

npx unity-mcp-cli tools
npx unity-mcp-cli rql 'objects | where name starts-with "Tree" | count'
npx unity-mcp-cli compile
npx unity-mcp-cli setup-skills claude-code

npx unreal-mcp-cli tools --filter rql
npx unreal-mcp-cli rql 'actors | where Label starts-with "Rock" | set Scale = Scale * 1.5'
npx unreal-mcp-cli rql 'editor | call SaveLevel()'

npx godot-cli rql 'nodes | where name contains "Enemy" | count'
npx godot-cli check
npx godot-cli setup-skills claude-code

第一条编辑器命令会启动一个无头编辑器并让它保持热状态，所以不必先打开引擎。用 rql 做的修改会打印改了什么、写入了哪些文件，所以你的智能体可以直接进入下一步。

开始使用

• Unity：ai-game.dev/engines/unity
• Unreal Engine：ai-game.dev/engines/unreal
• Godot：ai-game.dev/engines/godot
• RQL 查询语言：ai-game.dev/docs/rql
• 快速上手指南：ai-game.dev/docs/quickstart
• Discord 社区：https://discord.gg/cfbdMZX99G

随着 CLI 的发展，我们会继续运行这些冷启动评测。如果你的智能体在某处卡住了，在 Discord 上告诉我们：一份它出错过程的对话记录正是我们需要的。