基于 REST API 的 AI 驱动型 Unity 编辑器自动化引擎
让 AI 通过Skills直接掌控 Unity 场景

🎉 我们已被 DeepWiki 收录！
有问题？查阅 AI 生成的项目文档 →

本项目基于 unity-mcp 的优秀理念深度重构与功能扩展。

• ⚡ 极致效能：支持 Result Truncation 与 SKILL.md 瘦身，最大化节省 Token。
• 🛠️ 全能工具库：内置 431 Skills，支持 Batch (批处理) 操作，大幅减少 HTTP 通信开销，显著提升执行效率。
• 🛡️ 安全第一：支持 Transactional (事务原子性)，操作失败自动回滚，场景零残留。
• 🌍 多实例支持：自动端口发现、全局注册表，支持同时控制多个 Unity 项目。
• 🤖 深度集成：独家支持 Antigravity Slash Commands，解锁 /unity-skills 交互新体验。
• 🔌 全环境兼容：完美支持 Claude Code, Antigravity, Gemini CLI 等主流 AI 终端。
• 🎥 Cinemachine 2.x/3.x 双版本支持：自动检测 Unity 版本并安装对应 Cinemachine，支持 MixingCamera, ClearShot, TargetGroup, Spline 等高级相机控制。
• 🔗 超长任务稳定连接：请求超时用户可配置（默认 60 分钟），Domain Reload 后自动恢复同一端口，Python 客户端自动同步超时配置，彻底解决长时间任务断连问题。

本项目针对以下环境进行了深度优化，确保持续、稳定的开发体验：

通过 Unity Package Manager 直接添加 Git URL：

稳定版安装 (main):

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity

开发测试版安装 (beta):

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta

指定版本安装 (如 v1.4.0):

https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.4.0

📦 所有版本包可在 Releases 页面下载

在 Unity 中点击菜单：Window > UnitySkills > Start Server

1. 打开 Window > UnitySkills > Skill Installer。
2. 选择对应的终端图标（Claude / Antigravity / Gemini / Codex）。
3. 点击 "Install" 即可完成环境配置，无需手动拷贝代码。

安装器落盘文件说明（生成于目标目录）：

• SKILL.md
• scripts/unity_skills.py
• scripts/agent_config.json（包含 Agent 标识）
• Antigravity 额外生成 workflows/unity-skills.md

Codex 特别说明：推荐使用全局安装。项目级安装需要在 AGENTS.md 中声明才能识别，全局安装后重启 Codex 即可。

📘 需要更完整的安装与使用说明，请查看：docs/SETUP_GUIDE.md

如果不支持不使用一键安装，可按以下标准流程手动部署（适用于所有支持 Skills 的工具）：

1. 自定义安装: 在安装界面，你可以选择 "Custom Path" 选项，将 Skills 安装到你指定的任意目录（例如 Assets/MyTools/AI），方便项目管理。

1. 定位 Skills 源码目录：本仓库的 unity-skills/ 即为可分发的 Skills 模板（根目录包含 SKILL.md）。
2. 找到工具的 Skills 根目录：不同工具路径不同，优先以该工具文档为准。
3. 完整复制：将整个 unity-skills/ 目录复制到工具的 Skills 根目录下。
4. 创建 agent_config.json：在 unity-skills/scripts/ 目录下创建 agent_config.json 文件：

   {"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"}

   将 your-agent-name 替换为你使用的 AI 工具名称（如 claude-code、antigravity、gemini-cli、codex）。
5. 目录结构要求：复制后需保持结构如下（示例）：
   • unity-skills/SKILL.md
   • unity-skills/skills/
   • unity-skills/scripts/unity_skills.py
   • unity-skills/scripts/agent_config.json
6. 重启工具：让工具重新加载 Skills 列表。
7. 验证加载：在工具内触发 Skills 列表/命令（或执行一次简单技能调用），确认可用。

以下为已验证的默认目录（若工具配置过自定义路径，请以自定义为准）：

• Claude Code：~/.claude/skills/
• Antigravity：~/.agent/skills/
• Gemini CLI：~/.gemini/skills/
• OpenAI Codex：~/.codex/skills/

若你使用的是其他支持 Skills 的工具，请按照该工具文档指定的 Skills 根目录进行安装。只要满足标准安装规范（根目录包含 SKILL.md 并保持 skills/ 与 scripts/ 结构），即可被正确识别。

⚠️ 大部分模块支持 *_batch 批量操作，操作多个物体时应优先使用批量 Skills 以提升性能。

.
├── SkillsForUnity/                 # Unity 编辑器插件 (UPM Package)
│   ├── package.json                # com.besty.unity-skills
│   └── Editor/Skills/              # 核心 Skill 逻辑 (37 个 *Skills.cs, 共 431 Skills)
│       ├── SkillsHttpServer.cs     # HTTP 服务器核心 (Producer-Consumer)
│       ├── SkillRouter.cs          # 请求路由 & 反射发现 Skills
│       ├── WorkflowManager.cs      # 持久化工作流 (Task/Session/Snapshot)
│       ├── RegistryService.cs      # 全局注册表 (多实例发现)
│       ├── GameObjectFinder.cs     # 统一 GO 查找器 (name/instanceId/path)
│       ├── BatchExecutor.cs        # 泛型批处理框架
│       ├── GameObjectSkills.cs     # GameObject 操作 (18 skills)
│       ├── MaterialSkills.cs       # Material 操作 (21 skills)
│       ├── CinemachineSkills.cs    # Cinemachine 2.x/3.x (23 skills)
│       ├── WorkflowSkills.cs       # Workflow 撤销/回滚 (22 skills)
│       ├── PerceptionSkills.cs     # 场景理解 (9 skills)
│       └── ...                     # 431 Skills 源码
├── unity-skills/                   # 跨平台 AI Skill 模板 (分发给 AI 工具)
│   ├── SKILL.md                    # 主 Skill 定义 (AI 读取)
│   ├── scripts/
│   │   └── unity_skills.py         # Python 客户端库
│   ├── skills/                     # 按模块分类的 Skill 文档
│   └── references/                 # Unity 开发参考文档
├── docs/
│   └── SETUP_GUIDE.md              # 完整安装使用指南
├── CHANGELOG.md                    # 版本更新记录
└── LICENSE                         # MIT 开源协议

本项目采用 MIT License 许可。