# Unity 操作规范

本文规定 Agent 进行 Unity 开发时的工具选择、内容操作边界与验证要求。

## 1. 核心工具

- 统一通过 Unity CLI/Pipeline 与 Unity 交互，不使用 Unity MCP。
- 与 Unity 交互时必须使用 `unity-pipeline` 技能，并遵循其中的命令、参数、状态轮询和操作流程说明。
- 存在多个可连接的 Unity Editor 或开发版 Player 时，必须显式指定目标，避免误操作。
- 以当前实例的 `unity command` 列表为准，不假定 Pipeline 能力。

## 2. 操作边界

### 可直接编辑

- 普通 `.cs` 源码由 Agent 直接创建或修改。
- Shader、CSV、JSON、Markdown 等纯文本也可直接编辑。
- 涉及多个脚本或文本文件时，应先批量修改，再按文件类型统一执行必要的 Unity 刷新或编译，避免逐文件处理引发重复编译与重载。
- Pipeline 不可达时仅可编辑上述纯文本，不得修改序列化资源；未完成必要验证时必须明确说明。

### 必须使用 Pipeline

- 创建或修改场景、Prefab、Material、ScriptableObject、AnimationClip、AnimatorController、Timeline 等由 Unity 管理的序列化内容。
- 外部资源的 Unity 导入、导入设置和验证必须使用 Pipeline；批量导入时可先将源文件复制到目标目录。
- 移动、重命名、复制或删除 `Assets/` 下的既有文件和文件夹时必须使用 Pipeline，不得直接使用文件系统工具。
- 场景对象操作，包括 GameObject 的创建、删除、层级、Transform、组件及其序列化字段。
- Unity 工程设置，包括 Build Settings、Tags/Layers、Input、Quality、Graphics、Player Settings 等。
- 场景、Prefab、材质和视觉效果等项目内容，应在编辑器中制作并持久化，提供必要的可调参数。不得以运行时代码临时创建来替代资产制作。

### 禁止直接操作

- 禁止手动创建、修改或删除 `.meta`，不得将其中的 GUID 复用于其他资源。
- 禁止手动修改 Unity 序列化资源文件，如 `.unity`、`.prefab`、`.mat`、`.asset`、`.controller`、`.anim` 等。
- 禁止手动修改 Unity 生成内容或本地状态文件，如 `Library/`、`Temp/`、`Logs/`、`UserSettings/`、`*.csproj`、`*.sln` 等。
- 禁止以字节方式改写二进制资产。

## 3. 操作原则

- 同类目标批量查询、修改并统一验证，避免逐项往返。
- 更改序列化字段、组件类或程序集结构时，必须维护资源兼容与脚本绑定。
- 大范围重新导入、切换构建目标、构建 Player 或批量改写资源必须获得明确授权。
- 优先使用 `unity command` 的专用操作；仅在无合适操作时使用 `eval`，代码限于任务所需的最小范围，并按需处理 Undo、脏标记和保存。
- 批量导入时先检查路径和覆盖；无 `.meta` 的资源复制到目标目录后由 Unity 刷新导入；自带 `.meta` 的资源连同其 `.meta` 复制，并检查 GUID 冲突。

## 4. 验证与收尾

- 修改后执行与改动匹配的必要验证；非必要不运行全量测试。
- 视觉改动按批次截图，必要时分阶段验证，避免无信息重复。
- 区分 Console 的本轮新增日志与历史日志，避免误归因。
- Scene、Prefab 编辑或 Play Mode 操作结束后，保存有意义的修改，丢弃临时测试变更；不得擅自保存或丢弃用户已有的未保存内容。