UnityAI/06_工具脚本/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md

CrystalBattle Codex ↔ Unity MCP 使用规则

1. 目标与定位

MCP（Model Context Protocol）用于打通 Codex 与 Unity Editor。Codex 不直接操作 Unity 进程，而是通过本地 MCP Server 调用 Unity Editor 内的 HTTP Bridge，再由 Bridge 在 Unity 主线程执行 Editor 命令。

当前首版定位：

• 只支持 Unity Editor 工具桥，不覆盖 Play Mode 或真机运行时调试。
• 只监听本机 127.0.0.1，不开放局域网访问。
• 优先服务 UI 生成、Prefab 导出、资源刷新、日志读取等 Editor 自动化流程。
• Proxima 暂不作为 MCP 主通道，后续如做运行时调试再单独规划。

2. 工程结构

Unity Editor 侧：

CrystalBattle_Client/Assets/Editor/Command/
├── CodexUnityEditorBridge.cs
├── CodexUnityEditorBridgeWindow.cs
├── UIPrefabGenerator.cs
└── UIPrefabToJson.cs

MCP 测试数据目录：

CrystalBattle_Client/Assets/Editor/MCP_{功能名}/
└── <PrefabName>/

Codex MCP Server 侧：

UnityAI/Tools/CodexUnityMcp/
├── src/server.mjs
├── package.json
├── pnpm-lock.yaml
└── README.md

Codex 配置：

.codex/config.toml

Unity Bridge 默认地址：

http://127.0.0.1:17777

3. 启动与连接

1. 打开 CrystalBattle_Client Unity 工程，并等待脚本编译完成。
2. 打开 Unity 面板：

Tools/Codex Unity MCP/Bridge Panel

3. 面板中确认状态为 已连接。如果未连接，点击 开始连接。
4. Codex 侧重启或新开线程后，会读取 .codex/config.toml 中的 crystalbattle-unity MCP server 配置。
5. 每轮 Unity 自动化前，优先调用 unity_health 检查连通性。

禁止事项：

• 不允许把 Bridge 地址改成 0.0.0.0 或局域网 IP。
• 不允许绕过 MCP 直接让 Codex 执行 Unity Editor 侧业务逻辑。
• 不允许在 Unity 后台线程直接调用 Unity API，所有 Unity API 必须回到 Editor 主线程执行。

4. Codex 可用工具

工具名	用途	规则
unity_health	检查 Unity 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	输入 JSON 必须使用 Unity 工程相对路径或绝对路径
unity_export_prefab_to_json	从 UI Prefab 导出 JSON	Prefab 路径必须是 Unity Asset 路径

5. MCP 数据目录规则

所有 MCP 数据必须按功能单独放在 Unity Editor 目录下，并直接按目标预制体名分文件夹；不再额外创建 TestData 目录。统一格式：

Assets/Editor/MCP_{功能名}/<PrefabName>/

命名要求：

• {功能名} 只表示功能类别，不写具体窗口名、临时任务名或个人名。
• <PrefabName> 必须沿用目标预制体名称，和最终生成的 <PrefabName>.prefab 保持一致。
• UI 相关数据统一放在 Assets/Editor/MCP_UI/<PrefabName>/。
• 其它功能按能力命名，例如 Assets/Editor/MCP_Config/<PrefabName>/、Assets/Editor/MCP_Map/<PrefabName>/。
• Assets/Editor/Command/ 只放 Editor Bridge 和工具脚本，不再放数据文件夹。
• 新增、导出、临时验证用 JSON 都必须遵守该目录规则。

历史说明：

• 早期测试样例曾放在 Assets/Editor/Command/TestData/。
• 后续新增或整理数据时，应迁移到 Assets/Editor/MCP_UI/<PrefabName>/ 或对应功能目录。

6. UI 生成规则

标准流程：

1. 在 Assets/Editor/MCP_UI/<WindowName>/ 准备 UI JSON，文件夹名必须沿用预制体名。
2. 调用 unity_generate_ui_prefab。
3. 目标 Prefab 路径优先使用：

Assets/Game/GameHFResource/CN/UIWindows/<WindowName>/<WindowName>.prefab

4. 调用 unity_get_console_logs 查看是否有 Error 或关键 Warning。
5. 如需要验证双向转换，再调用 unity_export_prefab_to_json。

JSON 约束：

• 根对象使用 UILayoutData 结构：name/type/layer/rectTransform/canvas/children。
• UI 节点使用 UIElementData 结构：name/type/rectTransform/image/button/text/.../children。
• 资源路径使用 Unity Asset 路径，例如 Assets/...。
• 测试 UI 命名必须带明确测试标识，例如 CodexMcpTestWindow。

当前注意事项：

• UnityEngine.JsonUtility 解析递归 children 结构时可能出现 serialization depth warning。
• 如果 Prefab 已成功生成且没有 Error，该 warning 暂不阻塞测试。
• 后续如大量使用 UI JSON，应考虑把解析器替换为更适合递归结构的 JSON 库。

7. 安全与权限

MCP 工具可以触发 Unity Editor 行为，因此必须保持最小权限：

• execute_menu_item 必须使用白名单，禁止开放任意菜单执行。
• 只允许监听 127.0.0.1。
• 不在 MCP Server 中直接读写 Unity 资源，资源变更统一交给 Unity Bridge 执行。
• 生成测试资源时使用独立测试目录或明确测试命名，避免覆盖正式 UI。
• 覆盖已有 Prefab 前必须确认目标路径是否为预期文件。
• 不通过 MCP 执行批量删除、批量移动、构建发布、Git 操作等高风险动作。

8. 排错流程

连接失败：

1. 在 Unity 中打开 Tools/Codex Unity MCP/Bridge Panel。
2. 点击 开始连接 或 重启连接。
3. 用浏览器或 PowerShell 检查：

Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:17777/health"

4. 如果端口占用，先在 Unity 面板断开连接，再重新开始连接。

MCP 工具不可见：

1. 确认 UnityAI/Tools/CodexUnityMcp/node_modules 已安装。
2. 确认 .codex/config.toml 中 command 和 args 路径有效。
3. 重启 Codex，让 MCP server 配置重新加载。

UI 生成失败：

1. 调用 unity_get_console_logs 查看 Unity Console。
2. 检查 JSON 文件是否存在。
3. 检查 JSON 是否位于 Assets/Editor/MCP_UI/<PrefabName>/。
4. 检查 rectTransform 数组字段是否齐全。
5. 检查 Sprite、Font、Material 等资源路径是否存在。
6. 确认 Prefab 目标目录可写且未被外部程序锁定。

9. 测试基准

每次修改 MCP 或 Unity Bridge 后，至少验证：

• unity_health 返回 ok=true。
• unity_get_console_logs 能返回日志。
• unity_generate_ui_prefab 能生成一个最小测试 Prefab。
• 生成的 Prefab 文件存在，并包含预期节点名。
• unity_export_prefab_to_json 能把测试 Prefab 导出 JSON。
• Unity Console 无新增 Error。

测试数据路径必须遵守：

Assets/Editor/MCP_{功能名}/<PrefabName>/

UI 测试样例推荐路径：

Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.json
Assets/Game/GameHFResource/CN/UIWindows/CodexMcpTestWindow/CodexMcpTestWindow.prefab
Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.exported.json

10. 维护规则

新增 MCP tool 时必须同步更新：

• UnityAI/Tools/CodexUnityMcp/src/server.mjs
• CrystalBattle_Client/Assets/Editor/Command/CodexUnityEditorBridge.cs
• 本文档的工具列表与测试基准

新增 Unity 命令时必须满足：

• HTTP 请求只负责收包和回包。
• Unity API 在 EditorApplication.update 主线程队列执行。
• 返回值使用统一结构：

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

文档版本：

• v1.3
• 生效日期：2026-07-03
• 适用项目：CrystalBattle_Client