UnityAI/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md

# CrystalBattle 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 版本 |
| `unity_refresh_assets` | 执行 `AssetDatabase.Refresh()` |
| `unity_execute_menu_item` | 执行 Bridge 白名单中的菜单项 |
| `unity_get_console_logs` | 读取最近 Unity Console 日志 |
| `unity_generate_ui_prefab` | 根据 JSON 生成 UI 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. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。
6. Prefab/UI 继续做结构和实际显示验证，不能只确认命令返回成功。

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

## 五、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 状态，再处理占用来源。

### 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 验证流程 |