# Unity Cli

> >

- **Type:** Skill
- **Install:** `agentstack add skill-zhao0424-unity-cli-skill-unity-cli-skill`
- **Verified:** Pending review
- **Seller:** [ZHAO0424](https://agentstack.voostack.com/s/zhao0424)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ZHAO0424](https://github.com/ZHAO0424)
- **Source:** https://github.com/ZHAO0424/unity-cli-skill
- **Website:** https://docs.unity.com/en-us/unity-cli

## Install

```sh
agentstack add skill-zhao0424-unity-cli-skill-unity-cli-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 栈不覆盖资产删除与外部文件写入。
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 ` 亚秒级执行,**无 domain reload**。日常迭代首选。
2. **headless 单发**(编辑器关着):`unity run --command ` / `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  --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**:

```bash
# 必须是完整 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)

```bash
# 跑测试(编辑器必须关着);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`。

## 工作流配方(实测通过)

**① 验证闭环**(核心配方——客观清单先行,截图殿后,任一不过就修完从头再来):
```bash
# ── 客观层:每项都可脚本判断,不靠感觉 ────────────────────
# 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`(不依赖相机,看布局用)。
**顺序有讲究**:客观层便宜且无歧义,先跑;截图贵且主观,只用来兜底视觉问题。

**② 改代码后的标准冒烟**:
```bash
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
```

**③ 连接模式跑测试(不关编辑器)**:
```bash
unity command run_tests --project-path  --format json -- --mode EditMode --filter "My*"
# 长测试套件轮询 test_status;取消用 cancel_tests
```

**④ 性能测量(测量先行,凭感觉的改进不算改进)**:
```bash
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](https://github.com/ZHAO0424)
- **Source:** [ZHAO0424/unity-cli-skill](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zhao0424-unity-cli-skill-unity-cli-skill
- Seller: https://agentstack.voostack.com/s/zhao0424
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.