Besty0728/Unity-Skills

UnitySkills – 用于 Unity 编辑器自动化的 AI 驱动 REST API

它是什么 – UnitySkills 是一个 Unity 2022.3+ 插件，在 Unity 编辑器内运行本地 HTTP 服务器。该服务器将 805 个“技能”（小型、专注的动作）公开为 REST 端点。AI 驱动的编码助手（Claude Code、Antigravity、Codex、Cursor、Kimi Code、OpenCode）可以调用这些端点来创建、修改或删除 Unity 资源、场景、预制件、着色器、UI、物理、网络、XR 设置以及许多其他编辑器任务。

为什么重要 – 通过将编辑器操作置于定义明确的 API 之后，UnitySkills 让大型语言模型 (LLM) 能够像真正的 Unity 开发者一样行动：它们可以发出具体指令，而不仅仅是生成代码片段。该项目增加了安全层（预演规划、单操作权限模式、审计日志、事务性回滚），解决了 AI 驱动场景编辑中最大的担忧——意外损坏。

核心功能

功能	说明
805 个 REST 技能	超过 800 个现成动作，分为 54 个类别（例如：YooAsset、Cinemachine、Netcode、UI Toolkit、XR、ShaderGraph 等）。每个技能都是一个微小且有文档记录的 HTTP 调用，可由 AI 助手编写脚本或调用。
三层权限系统	批准（人类授予令牌）、自动（全自动执行，高风险操作被封锁）、绕过（无限制）。模式可从 Unity 面板设置，并对应至 Claude Code 的权限模型。
预演 / 规划模式	在任何端点后附加 `?mode=dryRun` 或 `?mode=plan`，即可在不触碰项目的情况下获得参数验证和影响评估。
事务性批次执行	`POST /skills/batch` 将一系列技能作为单一事务执行：快速失败、可选的 `continueOnError`、跨步骤 `$ref`、失败时自动回滚，以及净变更的 `?diff=1` 预览。
审计轨迹	每次调用、授予、撤销和封锁的请求都会写入 `Library/UnitySkillsAudit.jsonl`。日志可在面板内查看，删除操作也会被记录。
回滚粒度	五种快照类型可在域重新加载后保留；`workflow_undo_task` 可回滚单一任务，而非整个项目。
多实例控制	服务器会自动检测可用端口，并可通过全局注册表同时管理多个 Unity 项目。
长效连接	可设置超时（默认 15 分钟）以及域重新加载后的自动重新连接。
防幻觉护栏	每个技能都附带“禁止”列表和路由规则，以防止 AI 发出不安全的操作。

支持的 AI 终端（一键安装）

终端	状态
Antigravity	✅ (与 Codex 共用 `.agents/skills/`)
Claude Code	✅
Codex	✅
Cursor	✅
Kimi Code	✅
OpenCode	✅

如果您使用其他工具，仍可手动安装技能（请参阅“手动技能安装”章节）。

快速入门（三个步骤）

添加 Unity 套件 – 在 Package Manager 中，添加 Git URL：
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```
（或使用 #beta 或特定版本的标签）。
启动服务器 – 打开 Window → UnitySkills（或按下 Alt + Shift + U）并切换服务器开关。服务器将在域重新加载后自动存续。
安装 AI 技能集 – 在同一个面板中，前往 AI Config 分页，选择您的终端图标，然后点击 Install。安装程序会将 unity-skills~/ 模板复制到终端的技能目录中，创建所需的 agent_config.json，并向 AI 工具注册这些技能。

安全与治理

执行前预览 – 使用 ?mode=dryRun/?mode=plan 查看技能将会变更的内容。
权限网关 – 高风险操作（标记为 NeverInSemi）除非用户通过允许列表明确允许，否则将被封锁。
结构化日志 – 所有活动皆存储为 JSONL，便于审计或重播。
回滚 – 快照是内容寻址的；您可以回滚单一任务或整个批次，而不会丢失其他工作。

谁适合使用？

游戏开发者：希望 LLM 进行关卡原型设计、生成 UI 或设置网络，而无需编写样板代码。
技术美术：希望通过 AI 指令批次处理资源（例如：YooAsset 绑定、ShaderGraph 调整、ProBuilder 网格）。
工具开发者：需要稳定、版本化的 API 来将 Unity 与外部自动化管线集成。
研究人员：探索在复杂编辑器环境中进行安全 AI 辅助内容创作。

深入了解

操作模式与治理 – docs/OPERATING_MODES.md
设置指南 – docs/SETUP_GUIDE.md (英文) / docs/SETUP_GUIDE_CN.md (中文)
技能目录 – README 中的“805 技能类别概览”章节列出了每个技能组及其核心功能。

总结

UnitySkills 将 Unity 编辑器转变为 AI 编码助手可以安全调用的 REST 驱动服务。它附带数百个现成动作、细粒度权限系统、审计日志和事务性回滚，使 AI 引导的场景编辑在实际项目中变得切实可行。