Unity Cli

unity-cli:官方 Unity CLI 编辑器自动化

版本锚定(实测 2026-08-05):Unity CLI 1.0.0-beta.3 + com.unity.pipeline 0.4.0-exp.1(要求 Unity 6.0+)。 CLI 处于 beta,升级后先跑文末"验证清单"再继续用。

前置条件:装 CLI(irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex, macOS/Linux 见官方文档)→ unity auth login → 给目标工程装包:unity pipeline install --project-path 。 本机工程状态记录见 references/local-setup.md(如存在)。

本 skill 的边界与分工

• 读代码/理解架构/改 .cs → 宿主 agent 的 Read/Grep/Edit 文件工具,改完调 recompile 回编辑器。

不要用 eval 改代码——那是文件工具的事。

• 场景/资产/编辑器状态 → 本 skill 的 CLI 通道。
• 协同纪律:改一个由脚本驱动的场景对象前,先读那个脚本——序列化字段的含义和运行时行为在代码里,不在场景里。
• 项目专属知识(架构、核心系统、禁改对象、命名约定)→ 写在你工程自己的 CLAUDE.md,

模板见 references/project-context-template.md。本 skill 管通道,你的 CLAUDE.md 管工程知识。

• XR 任务(XR Origin / XRI 交互 / 手追踪 / 世界空间 UI / XR 验收)→

先读 references/xr-recipes.md 再动手,里面有搭 rig、抓取接线、射线排查、XR 专项体检的成套配方。

安全模型(诚实版)

本 skill 是文档,不是沙箱。eval 与内置命令以编辑器进程的权限执行——给 AI 编辑器控制权, 信任级别等同于给 AI 终端 Bash。四道真护栏:

1. git 干净状态前置(铁律):任何批量改动会话开始前,工作区必须 clean。

版本控制是唯一可靠的 undo;编辑器内的 Undo 栈不覆盖资产删除与外部文件写入。

1. 宿主层执法:Claude Code 用户可以用 permission rules 真正 gate 掉 eval,例如在

.claude/settings.json 里把 Bash(unity command eval*) 设为 ask/deny——这才是机制,prompt 约束不是。

1. 写域收窄:批量生成类任务先 set_authoring_root(如 Assets/AgentWork),

文件写入被限制在该子目录内;做完再设回 Assets。

1. 破坏性命令护栏:内置命令 confirm=true 才执行 + dry_run 预演;红线:禁止用 eval 绕过。

残余风险要认:eval 里的查询与场景编辑无法白名单化,这是灵活性的代价。 不接受此权衡 → 只用内置命令,并在宿主层 deny eval。

两种模式与决策树

1. 连接模式(编辑器开着):Pipeline 包在编辑器内起 HTTP 服务(默认 :7800),

unity command 亚秒级执行,无 domain reload。日常迭代首选。

1. headless 单发(编辑器关着):unity run --command / unity test / unity build

以 batchmode 起编辑器→执行→退出。适合跑测试、打包、CI。

决策:

• 编辑器开着 → 连接模式。硬约束:同一工程编辑器开着时禁走 headless(工程锁,batchmode 起不来)。
• 编辑器关着 + 一次性任务(测试/打包)→ headless。
• 编辑器关着 + 要连打多发 → unity projects open 起编辑器后走连接模式。
• 动手前先 unity status --format json 看有哪些实例、什么状态。

多实例规则(铁律)

同时开多个工程时命令可能连错实例。每条命令都显式带 --project-path 。

命令调用语法

# 发现能力:列出已连接编辑器上全部注册命令(140 个内置,见 references/pipeline-commands.md)
unity list --project-path  --format json

# 调用:命令参数放在 -- 之后,--参数名 值
unity command console --project-path  --format json -- --tail 20 --level error
unity command find_gameobjects --project-path  --format json -- --name Player
unity command set_transform --project-path  --format json -- --target "Root/Cube" --position "[0,1,0]"

# 环境
unity status --format json          # 已连接实例(端口/工程/版本/PID/状态)
unity editors running               # 运行中的编辑器(含未装 Pipeline 的)
unity doctor                        # 环境诊断

• Git Bash 路径改写坑(Windows):MSYS 会把以 / 开头的参数当 POSIX 路径改写

(/Root/Cube → C:/Program Files/Git/Root/Cube,报 "No GameObject at hierarchy path")。 对策(实测均可):hierarchy path 不写前导斜杠(Root/Cube),或命令前加 MSYS_NO_PATHCONV=1,或改用 PowerShell。

• 向量参数(position/rotation/scale 等 single[])传 JSON 数组字符串:--position "[0,1,0]"(实测)。
• 返回 JSON:外层 success,data.result 里是命令结果;失败看 errors[].message。
• --timeout 默认 30,长操作(烘焙/重编)记得加大或用对应的 *_status 轮询命令。
• 文件路径参数被限制在工程根内;裸相对路径按 authoring root(默认 Assets/)解析。

截图、写文件都必须落在工程内,再用普通文件工具取走。

eval:批量与长尾的兜底(也是对抗延迟的手段)

单次调用实测 0.65–0.92s(冷启动首发 ~3s)。多步操作不要拆成 N 次调用,合并成一个 eval:

# 必须是完整 C# 语句,以 return 结尾;编译错误会返回行列号
unity command eval "return UnityEngine.Application.unityVersion;" --project-path  --format json

# 批量示例:一次调用建 10 个对象 + 保存(代替 20 次小调用)
unity command eval "
for (int i = 0; i  --format json

# 超过 ~10 行写成文件用 eval_file。文件放工程根的 Temp/(不进 AssetDatabase、不被编译);
# 禁放 Assets/ 下——语句式片段不是合法 C# 类文件,会被 Unity 编译并刷错
unity command eval_file --project-path  --format json -- --file "Temp/snippet.cs"

高频片段见 references/eval-snippets.md。

红线:删资产、改工程设置、批量改 import settings 一律走带 confirm/dry_run 护栏的内置命令 (delete_asset 等),禁止用 eval 绕过护栏。eval 只用于查询、场景内容批量编辑、未封装的长尾操作。

实战纪律

• 显式保存:内置写操作不自动存盘。改完场景调 save_scene / save_all。
• 改脚本默认值 ≠ 改场景:改 [SerializeField] 默认值对已有场景组件无效,须同步改场景实例并核对。
• 子资产寻址:objectref 参数接受 path / guid / globalId;子资产(如 FBX 里的 mesh)用

globalId 显式寻址,别依赖"同 path 取第一个"。

• DDOL 场景:Play Mode 下查 DontDestroyOnLoad 对象优先用 eval(FindObjectsByType 按 scene.name 过滤)。
• 破坏性操作:内置命令自带 confirm=true 才执行 + dry_run 预演;批量改动先 dry_run 看清单。

测试与打包(headless)

# 跑测试(编辑器必须关着);exit code 非 0 = 有失败;NUnit XML 报告
unity test  --mode EditMode --output results.xml --format json
unity test  --mode EditMode --filter "MyTests*"

# 打包:--execute-method 必填(Unity 无内置命令行构建),绑定工程内静态构建方法
unity build  --target Android --execute-method Builder.PerformBuild --android-export-type apk

打包前必先重编:改过脚本直接打包可能报 "script class layout incompatible"(编辑器程序集陈旧)。 连接模式先 unity command recompile -- --focus true,轮询 recompile_status 到完成;headless 天然全新编译,无此问题。 装机部署与真机验收环(adb、外部覆盖资产不重导入等坑)→ references/build-and-deploy.md。

工作流配方(实测通过)

① 验证闭环(核心配方——客观清单先行,截图殿后,任一不过就修完从头再来):

# ── 客观层:每项都可脚本判断,不靠感觉 ────────────────────
# 1. console 零 error(改动引入的新报错最常在这暴露)
unity command console --project-path  --format json -- --tail 30 --level error
# 2. 一键体检:missing reference / missing script / 场景 dirty 状态(聚合 eval,片段库有)
unity command eval_file --project-path  --format json -- --file "Temp/health-check.cs"
# 3. 相关测试绿
unity command run_tests --project-path  --format json -- --mode EditMode --filter "相关模块*"
# 4. 性能不劣化(有基线时对比)
unity command get_performance_stats --project-path  --format json

# ── 主观层:只判断客观层测不了的(构图/氛围/交互状态是否对)──
unity command capture_game_view --project-path  --format json -- --save_path "Temp/accept.png" --include_inline_image false --width 960 --height 540
# savedPath 实际落在 Assets/Temp/ → 用 Read 工具直接看图 → 对照验收标准
# 清理注意:失焦编辑器还没 import 新文件时 delete_asset 会失败;
# 用 eval:AssetDatabase.Refresh() 后 DeleteAsset("Assets/Temp")(删文件夹连带内容)

Scene 视图版:capture_scene_view(不依赖相机,看布局用)。 顺序有讲究:客观层便宜且无歧义,先跑;截图贵且主观,只用来兜底视觉问题。

② 改代码后的标准冒烟:

unity command recompile --project-path  --format json -- --focus true
# 轮询 recompile_status 到完成 → console 查编译错
unity command console --project-path  --format json -- --tail 20 --level error
unity command editor_play --project-path  --format json
# 等几秒 → console 查运行时报错 → capture_game_view 看画面 → editor_stop

③ 连接模式跑测试(不关编辑器):

unity command run_tests --project-path  --format json -- --mode EditMode --filter "My*"
# 长测试套件轮询 test_status;取消用 cancel_tests

④ 性能测量(测量先行,凭感觉的改进不算改进):

unity command get_performance_stats --project-path  --format json
# 编辑器数字被 Scene 视图渲染污染:采样时关掉 Scene 视图,只留 Game 视图
# 帧间波动大:多相机位采样看尖峰,别信单次均值;优化前后对比以目标设备实测为准

已知限制与对策(2026-08-05 实测于 0.4.0-exp.1)

| 现象 | 现状 | 对策 | |---|---|---| | Play Mode 长会话后 CLI 502/unreachable(server 本身活着) | 已复现(2026-08-05,长 Play 会话多次进出后):unity status 全 unreachable、command 报 502,但 server 实际正常——是 Library/Pipeline/.unity-pipeline-port 的 lastHeartbeat 停更,CLI 判死 | 绕过:直连 HTTP。从 port 文件读 port+evalToken,POST http://127.0.0.1:/api/exec,Header Authorization: Bearer ,Body {"command":"eval","parameters":{"code":"...return ...;"}};GET /api/commands 列命令。恢复 CLI 通道需重启编辑器 | | 编辑器失焦不刷新/不解析包/不 import 新文件 | 已复现 | unity command editor_focus;长驻自动化开 set_autotick;长任务优先 headless | | 模态弹窗卡死无人值守流程 | 未复现但风险在 | 外部改开着的场景/脚本前先存盘;卡住时人工看编辑器 | | 每次调用 ~0.7–0.9s | 属实(冷启动 ~3s) | 多步合并进单个 eval;连打用 unity shell --protocol ndjson | | 路径限制在工程根内 | 属实(400 Parameter Validation Failed) | 输出落 Temp/ 或 Assets/Temp/,用完清理 | | 截图仅连接模式 | capture_game_view/capture_scene_view 需要视图存在 | headless 流程不排截图步骤 | | 编辑器异常无限刷屏(MissingReference/UIElements 等)拖垮自动化通道与打包 | 偶发,非代码错误 | 重启编辑器清除;console 出现高频重复异常时先重启再继续 |

错误处理约定

失败 → 先 unity status --format json 确认实例还在、state 是 ready → 重试一次 → 仍失败就把 errors[].message 原样报告,不要死循环重试。 编辑器重启/domain reload 后连接自动恢复,无需人工干预(实测)。

自定义命令(按需增补,不预先求全)

内置 140 命令覆盖不了、且真实缺口出现 ≥2 次才动手:做成本地 UPM 包(Editor-only asmdef), 静态方法 + [CliCommand] 注册,返回可序列化对象,破坏性必带 dryRun+save 参数,每命令配 EditMode 测试。 多工程共享用 manifest file: 引用。

CLI 升级后的验证清单(方法论见 references/verify-before-trust.md)

1. unity --version;unity status 能看到已开编辑器。
2. unity command eval "return UnityEngine.Application.unityVersion;" 通。
3. unity list 数一下命令数(基线 140),diff 新增/移除。
4. 跑一次 headless unity test --mode EditMode(编辑器关着)。
5. 重测已知限制表,更新本文档。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZHAO0424
• Source: ZHAO0424/unity-cli-skill
• License: MIT
• Homepage: https://docs.unity.com/en-us/unity-cli

Install and usage instructions live in the source repository linked above.