# 🎮 UnitySkills

Unity-Skills

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

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

> 当前官方维护基线为 **Unity 2022.3+**。仓库中仍可能保留部分对 Unity 2021 的兼容逻辑，但后续功能开发、回归验证与适配工作将以 **2022.3+ / Unity 6** 为主。 ## 🤝 致谢本项目基于 [unity-mcp](https://github.com/CoplayDev/unity-mcp) 的优秀理念深度重构与功能扩展。 --- ## 🚀 核心特性 - 🛠️ **726 REST Skills 全能库**：包含 51 个功能源码模块和 19 个 advisory 设计模块，支持 Batch 批处理，一次操控多个对象。 - ⚡ **调用效率革命性提升 (v2.0.1+)**：Schema 缓存 + 指数退避轮询 + BATCH-FIRST 引导 → **Token 消耗 ↓ 96%**，**简单任务 4-6 次调用 → 1 次（↓ 75-83%）**。当前：v2.0.5。 - 🔐 **三档权限模式 (v1.9.0+)**：Approval / Auto / Bypass，配合双轨审批渠道（Dialog / Panel），对齐 Claude Code permission modes；老用户升级零感知。 - 🤖 **4 大 IDE 原生支持**：Claude Code / Antigravity / Codex / Cursor，一键安装即用。 - 🛡️ **事务原子性保障**：操作失败自动回滚，场景永不残留，确保流程安全。 - 🌍 **多实例同时控制**：自动端口发现与全局注册表，支持同时操控多个 Unity 项目。 - 🔗 **超长稳定连接**：请求超时可配（默认 15 分钟），Domain Reload 后自动恢复，脚本编译/资源重导入等短暂中断会提示重试。 - 🛡️ **防幻觉 Guardrails**：每个 Skill 模块内置 DO NOT 清单和路由规则，防止 AI 调用不存在的命令或参数错误。 --- ## 🔐 操作模式 (v1.9.0+) UnitySkills 引入真正的服务端权限系统，对齐 Claude Code permission modes。模式切换统一在 Unity 面板（**Window > UnitySkills > Server**）完成，**不再支持对话触发词**。 | 模式 | 默认 | 行为 | 适用场景 | |:-----|:----:|:-----|:---------| | **Approval（审批）** | — | AI 想做事 → 服务端返回 `MODE_RESTRICTED` + grant token → 用户审批 → AI 重放 token 后执行 | 重控制、敏感项目 | | **Auto（自动）** | 新安装 | AI 直接执行 FullAuto skill；服务端仅拦自动判定的高危操作（NeverInSemi） | 日常开发 | | **Bypass（全部直接放行）** | 老安装升级保持 | 全部放行，仅保留高危 `ConfirmationToken` 二次确认 | 自动化任务、CI、快速迭代 | **Approval 模式双轨审批**： - **Dialog 渠道**（默认）—— AI 对话说明意图 + grant token，用户文字同意后 AI 调 `POST /permission/grant` 重放 - **Panel 渠道**（面板可选开启）—— grant token 必须在 Unity 面板点 **[Approve]** 才生效；AI 未经面板批准直接 grant 会返回 `GRANT_PENDING_APPROVAL` **老用户升级零感知**：插件检测旧版 `UnitySkills_*` EditorPrefs key 自动识别老安装，默认保持 **Bypass**，行为与原 Full-Auto 完全一致，无需任何操作。新安装默认 **Auto** —— FullAuto skill 直接执行，仅 NeverInSemi（Delete / MayEnterPlayMode / MayTriggerReload / 高危）操作会被服务端拦截。若需要按 skill 手动审批，进 Server 标签页切到 **Approval**。 > ❌ 不再识别对话触发词（如 `"全自动模式"` / `"semi-auto"`），请在 **Window > UnitySkills > Server** 面板切换。 > > 📜 审计日志：`Library/UnitySkillsAudit.jsonl`（per-project，jsonl，1MB 滚动，保留 3 份），记录每次 grant / revoke / 被拒命中 / 调用。打开 **Window > UnitySkills > Audit Log** 可浏览、过滤、单条删除（✕）或整体清空（🗑 Clear All）—— 删除动作本身会写 `audit_deleted` / `audit_cleared` 追踪事件，日志依然可审计。 > > 🗑 Skill Installer 卡片的"卸载"按钮按 scope 智能形变：未装为灰态；仅一处装则按钮自带 scope 标签直接卸载；两处都装则显示 `Uninstall ▾` 下拉，分别选择 Project / Global。 > > 19 个 advisory 设计模块（架构、性能、设计模式、可测试性、包级源码规则等）在所有模式下均可用，按需自动加载。 --- ## 🏗️ 快速安装支持的IDE/终端本项目针对以下环境进行了深度优化，确保持续、稳定的开发体验（未在下表中的不代表不支持，只是没有快捷安装，可选用 ***自定义安装*** 到对应目录）： | AI 终端 | 支持状态 | 特色功能 | | :--- | :---: | :--- | | **Antigravity** | ✅ 支持 | 基于开放 Agent Skills 标准，工作区使用 `.agents/skills/`，全局使用 `~/.gemini/antigravity/skills/`。 | | **Claude Code** | ✅ 支持 | 智能识别 Skill 意图，支持复杂多步自动化。 | | **Codex** | ✅ 支持 | 支持 `$skill` 显式调用和隐式意图识别。工作区与 Antigravity 共享 `.agents/skills/`。 | | **Cursor** | ✅ 支持 | 自动扫描 `.cursor/skills/` 和 `.agents/skills/`；支持 `/skill-name` 显式触发；可在设置 → Rules 查看已加载技能。 | --- ## 🏁 快速开始 > **总体路线**：安装 Unity 插件 → 开启 UnitySkills 服务器 → AI 使用 Skill

一键安装演示

### 1. 安装 Unity 插件通过 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.6.0): ``` https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.6.0 ``` > 📦 所有版本包可在 [Releases](https://github.com/Besty0728/Unity-Skills/releases) 页面下载 ### 2. 启动服务在 Unity 中点击菜单：`Window > UnitySkills > Start Server` > ⏳ `script_*`、`debug_force_recompile`、`debug_set_defines`、部分资源重导入、包安装/移除等操作会触发编译或 Domain Reload，REST 服务短暂不可达属于正常现象，请稍候重试。 ### 3. 一键配置 AI Skills 1. 打开 `Window > UnitySkills > Skill Installer`。 2. 选择对应的终端图标（Claude / Antigravity / Codex / Cursor）。 3. 点击 **"Install"** 即可完成环境配置，无需手动拷贝代码。 > 安装器会复制包内的 `unity-skills~/` 模板目录到目标位置。 > > 安装器落盘文件说明（生成于目标目录）： > - `SKILL.md` > - `skills/` > - `references/` > - `scripts/unity_skills.py` > - `scripts/agent_config.json`（包含 Agent 标识） > **Codex 特别说明**：Antigravity 和 Codex 工作区都使用 `.agents/skills/` —— 装一次即两边可用。Codex 自动扫描 `.agents/skills/` 发现 skills，无需在 `AGENTS.md` 中声明。 📘 需要更完整的安装与使用说明，请查看：[安装指南](docs/SETUP_GUIDE_CN.md) | [Setup Guide](docs/SETUP_GUIDE.md)

4. 手动安装 Skills（可选）

如果不使用一键安装，可按以下**标准流程**手动部署（适用于所有支持 Skills 的工具）： #### ✅ 标准安装规范 A 1. **自定义安装**：在安装界面选择 "Custom Path" 选项，将 Skills 安装到任意指定目录（例如 `Assets/MyTools/AI`），方便项目管理。 #### ✅ 标准安装规范 B 1. **定位 Skills 源码目录**：UPM 包内的 `SkillsForUnity/unity-skills~/` 即为可分发的 Skills 模板（根目录包含 `SKILL.md`）。 2. **找到工具的 Skills 根目录**：不同工具路径不同，优先以该工具文档为准。 3. **完整复制**：将整个 `unity-skills~/` 目录内容复制到工具的 Skills 根目录下（重命名为 `unity-skills/`）。 4. **创建 agent_config.json**：在 `unity-skills/scripts/` 目录下创建 `agent_config.json` 文件： ```json {"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"} ``` 将 `your-agent-name` 替换为你使用的 AI 工具名称（如 `claude-code`、`antigravity`、`codex`、`cursor`）。 5. **目录结构要求**：复制后需保持结构如下（示例）： - `unity-skills/SKILL.md` - `unity-skills/skills/` - `unity-skills/references/` - `unity-skills/scripts/unity_skills.py` - `unity-skills/scripts/agent_config.json` 6. **重启工具**：让工具重新加载 Skills 列表。 7. **验证加载**：在工具内触发 Skills 列表/命令（或执行一次简单技能调用），确认可用。 #### 🔎 常见工具目录参考以下为已验证的默认目录（若工具配置过自定义路径，请以自定义为准）： - Claude Code：`~/.claude/skills/` - Antigravity：`~/.gemini/antigravity/skills/`（全局）或 `.agents/skills/`（工作区） - OpenAI Codex：`~/.agents/skills/`（全局）或 `.agents/skills/`（工作区，与 Antigravity 共享） - Cursor：`~/.cursor/skills/`（全局）或 `.cursor/skills/`（工作区）；也会自动扫描 `.agents/skills/` #### 🧩 其他支持 Skills 的工具若你使用的是其他支持 Skills 的工具，请按照该工具文档指定的 Skills 根目录进行安装。只要满足**标准安装规范**（根目录包含 `SKILL.md` 并保持 `skills/`、`references/` 与 `scripts/` 结构），即可被正确识别。

---

📦 Skills 分类概要 (726)

--- ## 📂 项目结构 ```bash . ├── SkillsForUnity/ # Unity 编辑器插件 (UPM Package) │ ├── package.json # com.besty.unity-skills │ ├── unity-skills~/ # 跨平台 AI Skill 模板 (波浪线隐藏目录, 随包分发) │ │ ├── SKILL.md # 主 Skill 定义 (AI 读取) │ │ ├── scripts/ │ │ │ └── unity_skills.py # Python 客户端库 │ │ ├── skills/ # 68 个模块文档（49 个 REST/模块文档 + 19 个 advisory 文档） │ │ └── references/ # Unity 开发参考文档 │ └── Editor/Skills/ # 核心 Skill 逻辑 (51 个 *Skills.cs, 共 726 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 (34 skills) │ ├── WorkflowSkills.cs # Workflow 撤销/回滚 (23 skills) │ ├── PerceptionSkills.cs # 场景理解 (18 skills) │ └── ... # 726 Skills 源码 ├── docs/ │ └── SETUP_GUIDE.md # 完整安装使用指南 ├── CHANGELOG.md # 版本更新记录 └── LICENSE # MIT 开源协议 ``` --- ## ⭐Star History

--- ## 📄 开源协议本项目采用 [MIT License](LICENSE) 许可。