【迁移】迁移Codex Unity MCP工具到UnityAI

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

@@ -0,0 +1,227 @@
+# 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 侧：
+
+```text
+CrystalBattle_Client/Assets/Editor/Command/
+├── CodexUnityEditorBridge.cs
+├── CodexUnityEditorBridgeWindow.cs
+├── UIPrefabGenerator.cs
+└── UIPrefabToJson.cs
+```
+
+MCP 测试数据目录：
+
+```text
+CrystalBattle_Client/Assets/Editor/MCP_{功能名}/
+└── <PrefabName>/
+```
+
+Codex MCP Server 侧：
+
+```text
+UnityAI/Tools/CodexUnityMcp/
+├── src/server.mjs
+├── package.json
+├── pnpm-lock.yaml
+└── README.md
+```
+
+Codex 配置：
+
+```text
+.codex/config.toml
+```
+
+Unity Bridge 默认地址：
+
+```text
+http://127.0.0.1:17777
+```
+
+## 3. 启动与连接
+
+1. 打开 `CrystalBattle_Client` Unity 工程，并等待脚本编译完成。
+2. 打开 Unity 面板：
+
+```text
+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` 目录。统一格式：
+
+```text
+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 路径优先使用：
+
+```text
+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 检查：
+
+```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。
+
+测试数据路径必须遵守：
+
+```text
+Assets/Editor/MCP_{功能名}/<PrefabName>/
+```
+
+UI 测试样例推荐路径：
+
+```text
+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` 主线程队列执行。
+- 返回值使用统一结构：
+
+```json
+{
+  "ok": true,
+  "message": "done",
+  "data": {},
+  "logs": []
+}
+```
+
+文档版本：
+
+- v1.3
+- 生效日期：2026-07-03
+- 适用项目：CrystalBattle_Client

06_工具脚本/MCP工具/README.md

@@ -0,0 +1,13 @@
+# MCP工具
+
+本目录用于沉淀 Codex 与 Unity Editor 打通相关的规则、工具说明和排错流程。
+
+当前文档：
+
+- [CrystalBattle Codex ↔ Unity MCP 使用规则](CrystalBattle_Codex_Unity_MCP使用规则.md)
+
+当前实现位置：
+
+- Unity Editor Bridge：`CrystalBattle_Client/Assets/Editor/Command/`
+- MCP Server：`UnityAI/Tools/CodexUnityMcp/`
+- Codex 配置：`.codex/config.toml`