unity-cli

---
name: unity-cli
description: >
  用官方 Unity CLI(unity 命令 + com.unity.pipeline 包)自动化 Unity 编辑器:
  场景/GameObject/组件/材质/prefab 增删改、console 读取、跑测试、打包、eval 执行任意 C#。
  当用户要操作 Unity、改场景、跑测试、打包、或说"在 Unity 里…"时使用。
  Automate the Unity Editor via the official Unity CLI: scene/GameObject/component/material/prefab
  edits, console reading, running tests, builds, and eval'ing arbitrary C#.
---

# 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 <P>`。
本机工程状态记录见 `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 栈不覆盖资产删除与外部文件写入。
2. **宿主层执法**:Claude Code 用户可以用 permission rules 真正 gate 掉 eval,例如在
   `.claude/settings.json` 里把 `Bash(unity command eval*)` 设为 ask/deny——这才是机制,prompt 约束不是。
3. **写域收窄**:批量生成类任务先 `set_authoring_root`(如 `Assets/AgentWork`),
   文件写入被限制在该子目录内;做完再设回 `Assets`。
4. **破坏性命令护栏**:内置命令 `confirm=true` 才执行 + `dry_run` 预演;红线:禁止用 eval 绕过。

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

## 两种模式与决策树

1. **连接模式**(编辑器开着):Pipeline 包在编辑器内起 HTTP 服务(默认 :7800),
   `unity command <name>` 亚秒级执行,**无 domain reload**。日常迭代首选。
2. **headless 单发**(编辑器关着):`unity run --command <name>` / `unity test` / `unity build`
   以 batchmode 起编辑器→执行→退出。适合跑测试、打包、CI。

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

## 多实例规则(铁律)

同时开多个工程时命令可能连错实例。**每条命令都显式带 `--project-path <绝对路径>`**。

## 命令调用语法

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

# 调用:命令参数放在 -- 之后,--参数名 值
unity command console --project-path <P> --format json -- --tail 20 --level error
unity command find_gameobjects --project-path <P> --format json -- --name Player
unity command set_transform --project-path <P> --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**:

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

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

写之前先翻 `references/eval-snippets.md`(批量改组件参数、一键体检、missing reference 扫描、
DDOL 查询、物理探测等高频片段都在那)。

**红线**:删资产、改工程设置、批量改 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 跑测试、出包、adb 装机、真机验收环,以及三个实战坑(改脚本不重编 → script class
layout incompatible、外部覆盖资产不重导入 → 出旧包、改 `[SerializeField]` 默认值不生效)
→ **`references/build-and-deploy.md`**。

两条不查文档也要记住的:**打包前必先 `recompile` 并等完成**;**同一工程编辑器开着时 headless 起不来**。

## 验证闭环(核心配方)

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

# ── 主观层:只判断客观层测不了的(构图/氛围/交互状态是否对)──
unity command capture_game_view --project-path <P> --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`(不依赖相机,看布局用)。
**顺序有讲究**:客观层便宜且无歧义,先跑;截图贵且主观,只用来兜底视觉问题。

其余场景化配方(改代码冒烟、连接模式跑测试、性能测量、断连恢复),以及一条端到端的**复合配方**
「从零做一个可交互按钮并验收」——示范命令怎么组合成任务、什么时候才该退到 eval
→ `references/recipes.md`。

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

| 现象 | 现状 | 对策 |
|---|---|---|
| Play Mode 长会话后 CLI 502/unreachable(server 本身活着) | **已复现**:port 文件 lastHeartbeat 停更,CLI 误判编辑器已死 | 绕过 CLI **直连 HTTP** 继续干活,恢复 CLI 通道要重启编辑器——完整步骤见 `references/recipes.md` §④ |
| 编辑器失焦不刷新/不解析包/不 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 后连接自动恢复,无需人工干预(实测)。

## references(用到才查)

| 文件 | 什么时候查 |
|---|---|
| `pipeline-commands.md` | 找具体命令名/参数;内置命令不够时怎么自建 |
| `eval-snippets.md` | 要写 eval 之前——先看有没有现成片段 |
| `recipes.md` | 冒烟、连接模式跑测试、性能测量 |
| `build-and-deploy.md` | 跑测试(headless)、出包、装机、真机验收 |
| `xr-recipes.md` | **任何 XR 任务动手前必读** |
| `project-context-template.md` | 给你自己的工程写 CLAUDE.md |
| `verify-before-trust.md` | CLI 升级后重测(含 5 步验证清单);以及本 playbook 的制作方法 |