Besty0728/Unity-Skills

UnitySkills – 面向 Unity 编辑器自动化的 AI 驱动 REST API

是什么 – UnitySkills 是一个适用于 Unity 2022.3+ 的插件，它运行一个本地 HTTP 服务器，将 技能（预编写好的编辑器命令）作为 REST 端点公开。外部 AI 助手（Claude Code、Antigravity、Codex、Cursor、OpenCode 等）可以调用这些端点，代表用户创建、修改或删除场景、预制件、资产和 .meta 文件。

---

核心理念

层级	功能
技能目录	784 个“技能”模块，分为 25 个设计建议模块（如 UI、Netcode、XR、ShaderGraph）。每个技能都是一个小型、类型化的操作，知道其所需参数、风险等级以及是否修改场景或资产。
REST 接口	POST /skill/{name}（单个）或 POST /skills/batch（事务性）。支持查询参数 ?mode=dryRun 或 ?mode=plan，可在不修改项目的情况下预览验证错误和影响评估。
权限系统	三种模式 – 审批、自动、绕过 – 模仿 Claude Code 的权限模型。每个技能的元数据（RiskLevel、MayEnterPlayMode 等）控制执行。可选的 ConfirmationToken 为高风险调用添加第二步用户审批。
审计与回滚	每个请求、授权、撤销和被阻止的调用都会追加到 Library/UnitySkillsAudit.jsonl（在 1 MiB 时轮换）。每个文件变更的快照以内容地址方式存储在 Library/UnitySkills/ 下，允许使用类型化的 workflow_undo_task 在域重新加载后回滚单个操作。
批量事务	POST /skills/batch 可以是 fail-fast 或 continueOnError，支持 $ref 重用先前步骤的输出，并可在失败时自动回滚。?diff=1 标志返回整个批次的文件系统差异。
长连接	可配置超时（默认 15 分钟），域重新加载后自动重连，并在 Unity 重新编译脚本时提供重试提示。
防幻觉护栏	每个技能都附带“DO NOT”列表和路由规则，在命令或参数格式错误到达编辑器前拒绝调用。

---

工作流程（高层次）

1. 安装 Unity 包 – 通过 Unity 包管理器使用 Git URL（稳定版、Beta 版或标记版本）安装。该包会添加 Window → UnitySkills 面板和 Library/UnitySkills 下的服务器代码。
2. 启动服务器 – 从面板中启动（或使用快捷键 Alt+Shift+U）。服务器在任何域重新加载后自动重启。
3. 配置 AI 终端 – 在面板的 AI 配置 选项卡中选择 Claude Code、Antigravity、Codex、Cursor 或 OpenCode，点击 安装。安装程序将模板技能包（unity-skills~/）复制到终端的技能目录，并写入 agent_config.json 以标识 AI 代理。
4. AI 调用技能 – 例如 POST /skill/createGameObject?mode=plan，JSON 请求体为 { "name": "Enemy", "position": [0,1,0] }。服务器验证参数，返回计划（或错误），如果用户已授权，则在 Unity 编辑器中执行操作。
5. 审计与回滚 – 每个调用都会被记录；用户可从面板查看日志、过滤条目或删除（删除本身也会被记录）。若发生错误，用户可运行 POST /skill/workflow_undo_task 并传入快照 ID 以仅回滚该变更。

---

快速入门检查清单

步骤	命令 / UI 操作
1️⃣ 安装	Unity 包管理器 → 从 Git URL 添加包 → https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity（或 #beta, #v1.6.0 等）
2️⃣ 启动服务器	Window → UnitySkills → 打开 服务器（或 Alt+Shift+U）
3️⃣ 链接 AI	在同一面板中转到 AI 配置，选择你的终端，点击 安装
4️⃣ 测试技能	curl -X POST http://localhost:5000/skill/createGameObject?mode=plan -d '{"name":"Test","position":[0,0,0]}'
5️⃣ 审查	从面板的齿轮图标打开 审计日志，查看请求及其结果

---

适合谁使用

• 游戏开发者：希望借助 AI 辅助进行关卡设计、批量资产调整或快速原型开发，而无需手动点击编辑器的人。
• CI/CD 流水线：需要可确定性、可脚本化的 Unity 编辑（如自动生成预制件、更新包版本），同时保留完整审计日志的人。
• 工具构建者：创建自定义 AI 代理来操作 Unity 项目的人。REST 协议使集成与语言无关。
• 大型团队：需要细粒度权限控制（审批模式）和 AI 生成变更的回滚安全保障的人。

---

限制与注意事项（文档说明）

• 服务器是本地专用；公开暴露需要额外安全层。
• 域重新加载或脚本重新编译期间，REST 端点暂时不可用（客户端需短暂停顿后重试）。
• 官方支持 Unity 2022.3+；部分 2021 代码仍存在，但不会获得新功能。
• 新安装与升级的权限默认不同（新安装默认为 自动，升级保持 绕过 以保留先前行为）。
• AI 必须理解技能目录；不支持的终端需要 自定义安装 技能文件。

---

更多信息获取

• 文档 – docs/SETUP_GUIDE.md（英文）和 docs/SETUP_GUIDE_CN.md（中文）提供完整安装步骤。
• 发布资产 – 所有版本包均在 GitHub Releases 页面提供。
• DeepWiki 文档 – 自动生成文档位于 https://deepwiki.com/Besty0728/Unity-Skills。
• 许可证 – MIT（参见 LICENSE）。

---

总结 – UnitySkills 将 Unity 编辑器转变为一个可信、可审计、REST 驱动的自动化接口，AI 代理可安全调用，内置风险控制、干运行预览和操作级回滚。这是一个真正面向 AI 增强游戏开发的软件项目。