Unity Agentic Tools
使用此技能進行 Unity Agentic Tools CLI 的安裝設定、指令探索、指令執行、即時 Editor 橋接工作流程，以及高階專案自動化。
關鍵：對於 Unity 操作，請使用 CLI 指令執行器。除非使用者明確要求處理原始檔案，否則請勿手動修改 Unity 序列化檔案（.unity、.prefab、.asset、.mat、.anim、.controller、.meta、ProjectSettings/）。
指令列表
| 指令 | 功能說明 |
|---|---|
list [query] | 探索內建別名、帶有屬性的專案指令，以及可選的原始靜態 API。--brief 會省略每個參數的詳細資訊；--raw 則會加入原始靜態方法。 |
run <target> [args...] | 透過 Unity 橋接器執行指令別名或原始的公開靜態 C# 方法/屬性。 |
stream [topic] | 透過 WebSocket 觀看即時橋接器事件。 |
install | 安裝 Unity 橋接器套件。 |
uninstall | 移除 Unity 橋接器套件。 |
cleanup | 移除過時的橋接器狀態或可重建的 .unity-agentic 快取。 |
status | 檢查指令執行器和橋接器的可連線性，以及一個 readiness 區塊，顯示 Editor 正在忙於處理什麼。 |
指令預設輸出緊湊的單行 JSON；傳遞 --pretty 參數以獲得縮排輸出。進行探索時，建議使用 list <query> --brief。
預設情況下，install 會寫入 GitHub 套件網址。若要進行本地橋接器套件開發，請使用 install --local [path]；除非傳遞 install --remote，否則現有的 file: 依賴項將會被保留。
預設工作流程
unity-agentic-tools status -p <project>unity-agentic-tools list <query> --brief -p <project>- 使用
query.*、scene.hierarchy、ui.snapshot或螢幕截圖檢查當前狀態。 unity-agentic-tools run <target> ... -p <project>- 使用對應的查詢、快照、螢幕截圖、測試或控制台串流進行驗證。
範例
unity-agentic-tools list scene --brief -p <project>
unity-agentic-tools run project.refresh -p <project>
unity-agentic-tools run query.scene Assets/Scenes/Main.unity -p <project>
unity-agentic-tools run create.gameobject Assets/Scenes/Main.unity EnemyRoot Gameplay -p <project>
unity-agentic-tools run update.transform Assets/Scenes/Main.unity Player 1,2,3 0,90,0 1,1,1 -p <project>
unity-agentic-tools stream console --type Error -p <project>
unity-agentic-tools cleanup --cache -p <project>
使用單引號以位置參數的形式傳遞結構化參數——CLI 會自行編碼外層的 JSON 陣列，因此無需進行跳脫。對於以 - 開頭的參數，請保留 --args '<json array>'。請參閱 reference/troubleshooting.md 中的「JSON Args」。
unity-agentic-tools run update.batch Assets/Scenes/Main.unity '[{"gameObjectPath":"Player","propertyPath":"m_Name","value":"Hero"}]' -p <project>
當不存在別名或 [AgenticCommand] 包裝器時，可以直接呼叫原始的公開靜態 API。
unity-agentic-tools run UnityEditor.AssetDatabase.Refresh -p <project>
unity-agentic-tools run UnityEditor.EditorApplication.ExecuteMenuItem "File/Save" -p <project>
專案指令
請勿為每個 Unity 操作新增一個 CLI 指令。若要暴露專案特定的行為，請在 Unity Editor C# 中將 [AgenticCommand] 屬性新增至公開靜態方法/屬性：
using UnityAgenticTools.Commands;
public static class BuildCommands
{
[AgenticCommand("build.addressables", "Build Addressables content.")]
public static object BuildAddressables(string profile)
{
return new { success = true, profile };
}
}
然後使用：
unity-agentic-tools list build --brief -p <project>
unity-agentic-tools run build.addressables Production -p <project>
參考資料
reference/live-editor-workflows.md：即時 Editor 設定、修改、UI 以及批次工作流程reference/command-reference.md：生成的別名參考，包含參數提示（<required>[optional]）reference/troubleshooting.md：橋接器、超時、參考、JSON 參數以及驗證
故障排除
完整細節請參閱 reference/troubleshooting.md。快速提示：
- 橋接器無法連線：請參閱「橋接器無法連線」（安裝、開啟 Unity、等待編譯、檢查狀態、清理）。
reachable: true但is_stable: false表示忙碌中，並非故障。 - 長時間建置超時：
run預設超時時間為 60 秒；請參閱「長時間執行的指令」（--timeout 1200000、--no-wait）。 - 在
play.enter之後 Play 模式看起來不對：回應報告的是當前狀態，而非請求的狀態。請輪詢play.state；請參閱reference/live-editor-workflows.md中的「Play 模式轉換」。 - 在轉換期間讀取速度慢：這是預期行為。讀取操作會等待領域重新載入最多 30 秒，而不是直接失敗；請參閱「長時間執行指令」中的「領域重新載入」。
- 過時的
@hN/@uN參考：重新執行scene.hierarchy或ui.snapshot；請參閱「過時的參考」。 - 需要控制台日誌：
unity-agentic-tools stream console --duration 5000 -p <project>。 - 需要原始 API：
unity-agentic-tools list <type-or-namespace> --raw -p <project>。