让AI直接操控Unity编辑器：Unity-Skills REST自动化引擎完全指南
让AI直接操控Unity编辑器：Unity-Skills REST自动化引擎完全指南
Unity-Skills 是一个 基于 REST API 的 AI 驱动 Unity 编辑器自动化引擎，让 AI 在对话中直接操控 Unity 场景——创建物体、修改脚本、批量编辑资产、运行测试等 805 项编辑器操作，全程通过本地 HTTP 请求完成，无需编写任何 Unity 插件代码。
🧠 一分钟了解 Unity-Skills 的核心能力
| 能力 | 说明 |
|---|---|
| 🛠️ 805 项 REST Skills | 覆盖 54 个模块：场景、脚本、材质、光照、UI、物理、Timeline、Shader Graph 等，多数支持 *_batch 批量操作 |
| 🌍 多实例控制 | 自动端口发现（8090–8100）+ 全局注册表，同时操控多个 Unity 项目 |
| 🔐 三级权限模式 | Approval（审批）/ Auto（自动）/ Bypass（放行），服务端强制执行 |
| 🛡️ 事务与回滚 | 批量操作即事务，失败自动回滚；五类持久快照支持按任务回滚 |
| 🤖 6 大 AI 工具一键接入 | Claude Code / Antigravity / Codex / Cursor / OpenCode / Kimi Code 一键安装即用 |
架构上非常简洁：Unity 编辑器内运行一个本地 REST 服务器（核心见 SkillsHttpServer.cs 与请求路由 SkillRouter.cs），AI 工具则加载包内的 Skill 模板文档（SKILL.md），用"读文档 + 发 HTTP 请求"的方式驱动编辑器。
🚀 三步完成安装配置
第 1 步：在 Unity 中安装插件包
要求 Unity 2022.3+（推荐 LTS 或 Unity 6）。打开编辑器，依次点击：
Window → Package Manager → + → Add package from git URL
在弹出框中填入 Git URL（stable 渠道指向 main 分支），确认后即可，详细渠道说明见完整安装指南。
第 2 步：打开面板并启动 REST 服务器
Window → UnitySkills （或快捷键 Alt + Shift + U）
在面板顶栏打开服务器开关，成功时 Console 会显示：
[UnitySkills] REST Server started at http://localhost:8090/
用一条命令验证服务是否就绪：
curl http://localhost:8090/health
💡 开启 Settings → Server → Start on Editor launch 可让服务器随项目自动启动，并在脚本编译（Domain Reload）后自动恢复。
第 3 步：一键配置 AI Skills
- 打开 AI Config 标签页；
- 选择你使用的 AI 工具（如 Claude Code），点击 Install；
- 安装器会自动把 unity-skills~/ 模板（技能文档 + Python 客户端）复制到该工具的技能目录，无需手动复制。
之后你只需对 AI 说一句话，例如："帮我创建一个红色立方体并放到 (0, 1, 0)"，AI 就会通过 REST 接口操作编辑器。
🎮 第一次让 AI 动手：理解 REST 调用方式
所有技能都遵循统一的调用格式：POST /skill/<技能名> + JSON 参数。以"创建一个立方体"为例：
curl -X POST http://localhost:8090/skill/gameobject_create \
-H "Content-Type: application/json" \
-d '{"name":"MyCube","primitiveType":"Cube","x":1,"y":2,"z":3}'
返回结果是统一的成功格式，且会回读编辑器中的真实状态（如世界坐标、已设置的属性值），AI 可以直接用它验证操作是否生效：
{
"status": "success",
"result": { "success": true, "instanceId": 12345, "position": {"x": 1, "y": 2, "z": 3} }
}
对于不确定的操作，AI 还可以先做意图发现——用一句话描述需求，服务器会返回最匹配的技能及其参数结构：
curl "http://localhost:8090/skills/recommend?intent=create+cube&topN=5"
常用入口速查
| 接口 | 用途 |
|---|---|
GET /health |
健康检查，同时返回权限模式、实例 ID 等状态 |
GET /skills |
查询全部技能，支持 category / operation 过滤 |
GET /skills/recommend |
按自然语言意图推荐技能 |
POST /skill/<name> |
执行单个技能 |
POST /skills/batch |
批量事务执行（≤50 步，失败回滚，支持 ?diff=1 查看净变化） |
如果你偏好 Python，项目自带客户端库 unity_skills.py：
import unity_skills
unity_skills.health() # 检查服务器状态
unity_skills.call_skill("gameobject_create",
name="MyCube", primitiveType="Cube", x=0, y=1, z=0)
🔐 三种权限模式：AI 失控了怎么办？
AI 直接写真实场景，"它做错时会发生什么"比"它能不能做到"更重要。Unity-Skills 在服务端强制权限（而非依赖 AI 自觉），对齐 Claude Code 的权限模型，切换入口在面板 ⚙ Settings → Server 区，详细说明见操作模式与治理层文档：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| Approval（审批） | 每个写操作先返回授权令牌，用户批准后 AI 才重放执行；支持对话/面板双通道审批 | 敏感项目、重控制 |
| Auto（自动） | 常规技能直接执行；服务端自动拦截删除、触发重载等高危操作 | 日常开发（新安装默认） |
| Bypass（放行） | 全部放行，仅保留高危操作的二次确认 | CI 自动化、快速迭代 |
🛡️ 治理层：让自动化"可预演、可审计、可回滚"
| 时机 | 机制 |
|---|---|
| 执行前 | ?mode=dryRun / ?mode=plan 预演：只做参数校验和影响预估，不写任何内容 |
| 执行时 | 每个技能自带风险元数据（RiskLevel / MayEnterPlayMode 等），服务端据此自动拦截高危操作，Allowlist 可按技能持久放行 |
| 执行后 | 每次调用、授权、拦截都记入审计日志 Library/UnitySkillsAudit.jsonl，面板内可浏览与过滤 |
| 出错后 | Workflow 五类持久快照（创建/删除/移动/修改/设置）跨编译存活，workflow_undo_task 只回滚单个任务而非整个项目 |
📚 关键文件与文档索引
| 资源 | 路径 |
|---|---|
| 安装与使用指南（中文） | docs/SETUP_GUIDE_CN.md |
| 操作模式与治理层 | docs/OPERATING_MODES_CN.md |
| 完整技能 API 参考 | SkillsForUnity/unity-skills~/SKILL.md |
| 协议参考文档 | SkillsForUnity/unity-skills~/references/ |
| Python 客户端库 | SkillsForUnity/unity-skills~/scripts/unity_skills.py |
| REST 服务器与路由源码 | SkillsForUnity/Editor/Skills/ |
小结：Unity-Skills 用"本地 REST 服务器 + 技能文档 + 服务端治理"三件套，把 AI 变成真正能安全操作 Unity 编辑器的自动化引擎——安装三步完成，一句话驱动编辑器，权限与回滚全程可控。