# Codex 与 Unity MCP 使用规则

## 一、定位

Codex 通过本地 stdio MCP Server 调用 Unity Editor 内的 HTTP Bridge。Bridge 只监听 `127.0.0.1:17777`，并把 Unity API 工作排队到 Editor 主线程执行。

当前能力只面向 Unity Editor 自动化，不覆盖 Play Mode、真机运行时调试或远程网络访问。

## 二、对接点

```text
MCP Server: UnityAI/Tools/CodexUnityMcp/
Codex config: .codex/config.toml
Unity Bridge: http://127.0.0.1:17777
```

本文档不维护 Unity Bridge 的打开方式或 Unity Editor 内部目录结构。

## 三、可用工具

| 工具 | 用途 | 成功依据与注意事项 |
|---|---|---|
| `unity_health` | 检查 Bridge、项目路径和 Unity 版本 | 必须核对 `projectPath`、`applicationDataPath` 和 `unityVersion`，不能只看 `ok` |
| `unity_refresh_assets` | 执行 `AssetDatabase.Refresh()` | 可能触发编译和 Domain Reload；短暂断连不等于刷新失败 |
| `unity_execute_menu_item` | 执行 Bridge 白名单中的菜单项 | 超时表示结果未知，不表示菜单失败；禁止立即重复执行 |
| `unity_get_console_logs` | 读取最近 Unity Console 日志 | 只覆盖当前 Bridge/Domain 生命周期内缓存的日志 |
| `unity_generate_ui_prefab` | 根据 JSON 生成 UI Prefab | 命令成功后仍需检查 Prefab 结构、引用和实际显示 |
| `unity_export_prefab_to_json` | 将 UI Prefab 导出为 JSON | 核对输出路径及导出内容，避免把文件存在当作内容正确 |

`unity_execute_menu_item` 不能执行任意菜单。新增菜单能力时必须同时修改 Bridge 白名单并验证风险。

## 四、标准调用流程

1. 每轮 Unity 自动化前先调用 `unity_health`。
2. 确认返回的项目路径就是当前目标工程。
3. 执行当前任务需要的最少工具调用。
4. 资源变化后调用 `unity_refresh_assets`。
5. 如果刷新触发编译或 Domain Reload，等待 Bridge 恢复，再次调用 `unity_health` 并重新核对项目路径。
6. 执行白名单菜单；若调用超时，按“结果未知”处理，不立即重试。
7. 调用 `unity_get_console_logs` 检查任务完成标记、新增 Error 和关键 Warning。
8. Prefab、动画、材质和 UI 继续做结构或实际显示验证，不能只确认命令返回成功。

`unity_health` 失败时停止后续 Unity 命令并报告错误，不假设 Bridge 已经执行任何操作。

推荐调用链：

```text
unity_health
  -> 修改项目文件
unity_refresh_assets
  -> 编译/Domain Reload 时等待并重试 unity_health
unity_execute_menu_item
  -> 超时时不重试，等待 Bridge 恢复
unity_get_console_logs
  -> 核对完成标记、统计数据和 Error
```

## 五、刷新、编译与超时判定

### 刷新后的暂时断连

`unity_refresh_assets` 会调用 `AssetDatabase.Refresh()`。新增或修改 C# 文件时，Unity 可能随后编译脚本并执行 Domain Reload，旧 Bridge 实例在这段时间内不可用。

处理方式：

1. 保留刷新调用的返回结果。
2. Bridge 断连时等待 Unity 完成编译，不连续发送其他命令。
3. 重试 `unity_health`，确认 Bridge 已恢复且仍连接目标工程。
4. 再继续菜单执行和日志检查。

编译错误应以 Unity Console 或 `Editor.log` 为依据，不能把编译期间的一次连接失败直接判定为脚本错误。

### 菜单执行超时

Bridge 把菜单任务排队到 Unity 主线程。同步导入大量资源、创建 Prefab 或重新序列化资源时，HTTP 请求可能先达到 MCP 超时，但 Unity 主线程仍在继续执行菜单。

此时状态是“结果未知”：

1. 不立即重复调用同一菜单，避免重复导入或覆盖资源。
2. 等待 Bridge 恢复后先调用 `unity_health`。
3. 调用 `unity_get_console_logs` 查找菜单输出的完成标记、统计数据或异常。
4. 当前 Domain 的日志不足时，再查看目标项目的 Unity `Editor.log`。
5. 只有确认上一次没有执行或执行失败后，才允许重试。

长任务对应的菜单实现应尽量幂等，并输出明确的开始、完成、失败标记和关键统计。

## 六、任务专用验证菜单

现有 MCP 不提供任意 Hierarchy、Animator、Play Mode 或 C# 操作。需要自动检查特定资产时，使用范围明确的 Editor 菜单作为适配层：

1. 在目标项目中实现确定性的 `[MenuItem]` 方法。
2. 把菜单完整路径加入 Bridge 的 `AllowedMenuItems` 白名单。
3. 刷新资源，等待编译和 Bridge 重连。
4. 用 `unity_execute_menu_item` 执行准确的菜单路径。
5. 菜单把验证结果以结构化摘要写入 Console，再用 `unity_get_console_logs` 读取。

菜单只完成当前任务所需的有限操作，不开放任意 C# 执行或通用层级修改。适合记录的验证指标包括：

- 导入资产数量、缺失材质或纹理引用数量。
- 动画 `curveBindings` 总数、匹配目标骨骼的绑定数量。
- 用 `AnimationMode.SampleAnimationClip` 采样前后的骨骼 Transform 变化数量。
- Renderer Bounds 的主轴、尺寸和异常缩放。
- Prefab 的 Animator、Controller、Avatar、材质和纹理引用。

推荐验证顺序是：磁盘产物检查 → Unity 导入/设置菜单 → 菜单输出具体指标 → Console 无新增 Error → 必要的 Scene/Game View 或设备验证。

## 七、日志与验证边界

- Bridge 返回 `ok: true` 只证明命令被 Bridge 成功处理，不证明最终画面、动画或设备运行正确。
- `unity_get_console_logs` 缓存当前 Bridge/Domain 生命周期内的日志；Domain Reload 前的历史日志可能不可见。
- 需要跨 Domain 追溯或菜单超时取证时，以目标工程的 Unity `Editor.log` 补充验证。
- 日志结论应保留消息、堆栈、资产路径和统计值，区分 Error、预期 Warning 与无关历史日志。
- Prefab 结构、动画采样和引用检查属于 Editor 证据；Game View、Play Mode、APK 或微信真机效果必须单独验证。

## 八、UI 生成

UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档，并阅读：

- [UI 开发指南](../../UI窗口系统/开发指南.md)
- [UI 界面拼接](../../UI窗口系统/界面拼接.md)
- [UI 拼接工具](../UI拼接工具.md)

随后按以下步骤执行：

1. 检查设计图、目标 Prefab、窗口脚本和现有资源。
2. 明确传入 JSON 路径和目标 Prefab 路径。
3. 调用 `unity_generate_ui_prefab`。
4. 刷新 Assets 并读取 Console。
5. 检查 Prefab 层级、RectTransform、组件状态和资源引用。
6. 需要核对双向转换时调用 `unity_export_prefab_to_json`。
7. 在 Unity 运行环境验证实际显示和交互。

不规定固定测试目录、测试窗口名或中间数据目录。任务产生的路径由调用方明确提供，覆盖正式 Prefab 前必须确认。

## 九、安全边界

- Bridge 只监听 `127.0.0.1`，禁止改为 `0.0.0.0` 或局域网地址。
- MCP Server 不直接操作 Unity 资源，资源变更交给 Unity Bridge。
- HTTP 线程只接收和返回数据，Unity API 回到主线程执行。
- 不开放任意菜单、任意 C# 执行、批量删除、构建发布或 Git 操作。
- 生成和导出只修改调用参数明确指定的目标。
- 日志和错误返回包含命令、路径和失败原因，不返回无上下文的“失败”。

## 十、排错

### 连接失败

1. 调用 `unity_health` 保留原始错误。
2. 检查 `.codex/config.toml` 的 Node command 和 server 入口。
3. 确认 `Tools/CodexUnityMcp` 依赖已经安装。
4. 连接恢复前不执行其他 Unity 工具。

### 端口占用

- Bridge 如果发现同端口已经存在有效服务，应连接到现有监听状态而不是重复启动。
- 不能通过同时启动多个监听器解决端口冲突。
- 状态仍不一致时记录端口、进程和 Bridge 状态，再处理占用来源。

### 刷新后连接失败

1. 判断 Unity 是否正在编译脚本或执行 Domain Reload。
2. 等待编译结束后重试 `unity_health`。
3. Bridge 恢复后核对项目路径，再继续任务。
4. 持续无法恢复时检查 Unity Console、`Editor.log` 和 Bridge Panel。

### 菜单执行超时

1. 把本次调用标记为“结果未知”，不要立即重试。
2. 等待 `unity_health` 恢复。
3. 读取 Console 或 `Editor.log` 中的完成标记和异常。
4. 检查目标资产是否已经生成或修改。
5. 确认未执行或失败后才重试。

### UI 生成失败

1. 读取 Unity Console。
2. 检查 JSON 和目标路径是否存在且格式正确。
3. 检查 Sprite、Font、Material 等 Asset 路径。
4. 检查 `rectTransform`、递归 `children` 和组件字段。
5. 检查目标 Prefab 是否被错误覆盖或无法写入。

## 十一、维护

新增 MCP tool 时同步更新：

- [ ] `Tools/CodexUnityMcp/src/server.mjs`
- [ ] Unity Bridge 对应命令
- [ ] 本文档工具列表和验证步骤
- [ ] 对应测试用例或示例调用
- [ ] Bridge 白名单（如适用）

Bridge 返回统一结构：

```json
{
  "ok": true,
  "message": "done",
  "data": {},
  "logs": []
}
```

## 文档关联

| 文档 | 关联原因 |
|---|---|
| [MCP 工具入口](README.md) | MCP 模块入口 |
| [UI 开发指南](../../UI窗口系统/开发指南.md) | UI 生命周期和列表规则 |
| [UI 界面拼接](../../UI窗口系统/界面拼接.md) | Prefab 拼接流程 |
| [UI 拼接工具](../UI拼接工具.md) | JSON/Prefab 工具结构 |
| [MCP Server README](../../../../Tools/CodexUnityMcp/README.md) | Server 安装和实现 |
| [工作流清单](../../../../rules/40-工作流清单.md) | Unity/MCP 验证流程 |