taconotsandwich/unity-agentic-tools

Unity Agentic Tools

使用此技能进行 Unity Agentic Tools CLI 的设置、命令发现、命令执行、实时编辑器桥接工作流以及高级项目自动化。

关键：对 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 块

默认情况下，命令输出紧凑的单行 JSON；传递 --pretty 参数可输出带缩进格式的结果。建议使用 list <query> --brief 进行命令发现。

默认情况下，install 命令会写入 GitHub 包 URL。如需进行本地桥接器包开发，请使用 install --local [path]；如果传递了 install --remote，则会保留现有的 file: 依赖项。

默认工作流

1. unity-agentic-tools status -p <project>
2. unity-agentic-tools list <query> --brief -p <project>
3. 通过 query.*、scene.hierarchy、ui.snapshot 或屏幕截图检查当前状态。
4. unity-agentic-tools run <target> ... -p <project>
5. 使用匹配的查询、快照、屏幕截图、测试或控制台流验证结果。

示例

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", "构建 Addressables 内容。")]
    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：实时编辑器设置、修改、UI 和批量工作流
• reference/command-reference.md：包含参数提示（<required> [optional]）的生成别名参考
• reference/troubleshooting.md：桥接器、超时、引用、JSON 参数和验证

故障排除

详细信息请参阅 reference/troubleshooting.md。快速要点：

• 桥接器无法连接：请参阅“桥接器不可达”（安装、打开 Unity、等待编译、运行 status、清理）。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>。