給 AI Agent 的 CLI：Unity、Unreal 和 Godot 最多省下 83% 的 token

我們的三個引擎命令列工具 unity-mcp-cli、unreal-mcp-cli 和 godot-cli，現在讓 AI agent 使用的成本低得多。在相同的編輯器任務上，冷啟動的 agent 花費的 token 少了 60% 到 83%，工具呼叫次數也明顯減少。我們的做法很簡單，甚至有點令人慚愧：我們只給一個小型 AI agent 這套 CLI，觀察它在哪裡卡住，把那裡修好，然後再量一次。

本文會走過這項工作的三個回合、各項數字（包括一個往反方向走的），以及任何正在為 AI agent 打造 CLI 的人都能套用的心得。如果你用 Claude Code、Codex 或其他 agent 搭配 Unity、Unreal Engine 或 Godot，這些改動意味著更短的工作階段、更少的重試，以及更低的帳單。

我們如何測試給 AI Agent 用的 CLI

每一回合的每一次執行都採用同樣嚴格的設定，因此結果反映的是真實 agent 在真實機器上會遇到的情況：

• Agent 是一個小而快的 LLM（DeepSeek Flash）。小模型會暴露出大模型會默默繞過的粗糙邊角。
• 它只拿到 CLI 和基本的檔案工具。沒有 MCP 連線、沒有文件，提示中也沒有任何暗示。
• 它從冷啟動開始：全新的專案、引擎關閉、沒有任何快取。
• 只有真實的最終狀態正確，這次執行才算通過：磁碟上的場景或關卡檔案，或編譯結果。Agent 說它做了什麼並不算數。

我們計算 agent 讀取和寫入的 token、回合或工具呼叫次數、工具錯誤以及通過的任務數。然後我們讀對話紀錄，因為數字告訴你某個地方很慢，而對話紀錄告訴你為什麼。

第一回合：Agent 找得到路嗎？

最初的對話紀錄很粗糙。Agent 根本找不到編輯器的 AI 工具。當 CLI 顯示「未登入」時，它們手動編輯設定檔來繞過。它們猜了不存在的指令名稱。這些都不是 agent 的錯：CLI 根本沒有告訴它需要知道的事。

所以第一回合的修正聚焦在探索性：

• 新的 tools 指令即使引擎關閉也能列出編輯器的 AI 工具。它會啟動一次無介面編輯器、快取清單，之後就從快取回答。
• --help 輸出現在結尾會附上一段簡短的日常工作流程說明：agent 實際需要的那幾個指令，依照它需要的順序排列。
• 從未登入 ai-game.dev 的機器現在會得到本機伺服器，而不是一條死路。已登入的機器則一律留在雲端。
• 無介面編輯器現在能撐過編譯錯誤，並告訴 agent 它的日誌在哪裡，而不是一聲不響地失敗。
• 新增 test 和 compile 指令（godot-cli 稱之為 check），以及 Unity 和 Unreal 的 dialog 指令，可列出阻擋編輯器的強制回應對話框，並能按下其中一個按鈕。
• 三個 CLI 的結束碼一致，面向 agent 的指令接受 --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。

三個引擎合計，agent 每解決一個任務所用的輸入 token 少了 1.9 倍（114k → 60k），而且 12 個任務全部通過，而不是 12 個中過了 11 個。

沒錯，Unreal 上升了。Agent 犯的錯更少、用更少回合完成，但過程中讀得更多。第一回合修好了 agent 能找到什麼，還沒修好它必須讀多少，而那就是下一回合要處理的事。

第二回合：每一個早讀的位元組，每一回合都要再付一次

這一回合的關鍵洞見一旦看懂就很簡單。Agent 的對話會隨著每一步增長，而它早期讀過的所有內容，在之後每一回合都會再送給模型一次。第一回合讀的一大頁說明，第二回合、第十回合、第三十回合都要再付一次。

在基準版本中，根層級的 --help（4.8 KB，而且永遠是 agent 讀的第一個東西）佔了所有工具輸出 token 重量的 43%。RQL schema 又佔了 24%。兩次早期讀取就佔了三分之二的成本。

修正方式：

• 精簡的 --help，附上可直接使用的 RQL 範例，讓 agent 可以複製可用的查詢，而不是研究一份參考文件。
• 精簡的 schema 概觀，取代完整版本。
• RQL 錯誤會附上關於正確來源或成員名稱的提示。
• 一等公民的 rql 指令，查詢直接當成一般參數傳入，不必處理容易出錯的 JSON 引號。
• 儲存操作會印出寫入磁碟的檔案。Agent 以前要花 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

許多 agent 支援 skill：當任務符合時由 agent 載入的簡短指示檔。每個 CLI 的 setup-skills 指令現在會離線寫出約 2.2 KB 的 skill，不需要開編輯器。這個 skill 與 --help 由同一份來源產生，因此兩者永遠不會走樣。

我們比較了沒有 skill 的 agent 與有 skill 的 agent，兩者都使用最佳化後的 CLI，涵蓋三個編輯器任務、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 的每一行在每一回合都會被重新讀取，就跟 help 一樣。
• 寫成警告的規則會讓 agent 多做額外檢查。平實陳述事實比提出警告更有效。
• 對於只涉及程式碼的任務，skill 幫助不大。它的價值在編輯器工作：場景、關卡、物件和資產。

給所有為 AI Agent 打造 CLI 的人的心得

這些都不是遊戲引擎特有的。如果你要打造一個 AI agent 會用的命令列工具，以下是我們想分享的心得：

• 把工作流程和範例放進 --help。Agent 會先讀 help。給它們真正重要的五個指令和每個指令的可用範例，而不是完整參考文件。
• 讓早期輸出維持精簡。Agent 在最初幾回合讀的任何東西，之後每一回合都要再付一次。第一螢幕要狠狠削。
• 讓結果能自我驗證。當儲存會印出「已寫入磁碟」和檔案路徑，agent 就不必再花呼叫去確認。
• 讓每個錯誤都附上下一步。一個指出有效選項的錯誤，能把死路變成再一次呼叫。
• 用冷啟動評測來量測。用小模型、全新專案，並檢查真實的最終狀態。讀對話紀錄，改一件事，再量一次。

試試看

新指令已在各引擎外掛的最新版本推出：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 做的變更會印出改了什麼、寫入了哪些檔案，讓你的 agent 可以直接進行下一步。

開始使用

• 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 成長，我們會持續執行這些冷啟動評測。如果你的 agent 在某處卡住，請在 Discord 告訴我們：一份它出錯位置的對話紀錄，正是我們需要的。