【更新】调整Codex Unity MCP使用规则
This commit is contained in:
Shiliang
@@ -13,57 +13,23 @@ MCP（Model Context Protocol）用于打通 Codex 与 Unity Editor。Codex 不
|
||||
|
||||
## 2. 工程结构
|
||||
|
||||
Unity Editor 侧：
|
||||
本文档只说明 Codex 如何对接 Unity MCP，不说明 Unity Editor 内部脚本目录结构，也不在本节维护数据目录。
|
||||
|
||||
Codex 需要知道的对接点：
|
||||
|
||||
```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
|
||||
Unity MCP Server: UnityAI/Tools/CodexUnityMcp/
|
||||
Codex config: .codex/config.toml
|
||||
Unity Bridge URL: 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` 检查连通性。
|
||||
1. 确认 `.codex/config.toml` 中存在 `crystalbattle-unity` MCP server 配置。
|
||||
2. 确认 MCP Server 入口指向 `UnityAI/Tools/CodexUnityMcp/src/server.mjs`。
|
||||
3. Codex 侧重启或新开线程后，会重新读取 MCP server 配置。
|
||||
4. 每轮 Unity 自动化前，优先调用 `unity_health` 检查连通性。
|
||||
5. 如果 `unity_health` 不通，只记录错误并停止后续 Unity 操作；Unity 侧如何打开或重启 Bridge 不在本文档说明范围内。
|
||||
|
||||
禁止事项：
|
||||
|
||||
@@ -84,7 +50,7 @@ Tools/Codex Unity MCP/Bridge Panel
|
||||
|
||||
## 5. MCP 数据目录规则
|
||||
|
||||
所有 MCP 数据必须按功能单独放在 Unity Editor 目录下，并直接按目标预制体名分文件夹；不再额外创建 `TestData` 目录。统一格式：
|
||||
所有 MCP 数据必须按功能单独放在 Unity Editor 目录下，并直接按目标预制体名分文件夹；不再增加中间层目录。统一格式：
|
||||
|
||||
```text
|
||||
Assets/Editor/MCP_{功能名}/<PrefabName>/
|
||||
@@ -96,28 +62,30 @@ 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>/` 或对应功能目录。
|
||||
整理旧数据时，应迁移到 `Assets/Editor/MCP_UI/<PrefabName>/` 或对应功能目录。
|
||||
|
||||
## 6. UI 生成规则
|
||||
|
||||
标准流程：
|
||||
|
||||
1. 在 `Assets/Editor/MCP_UI/<WindowName>/` 准备 UI JSON，文件夹名必须沿用预制体名。
|
||||
2. 调用 `unity_generate_ui_prefab`。
|
||||
3. 目标 Prefab 路径优先使用：
|
||||
1. 先读取 `F:/JMNet/AIMCP/UnityAI/README.md` 中的 `UI相关` 索引。
|
||||
2. 根据 README 的 UI 相关入口，优先阅读：
|
||||
- `F:/JMNet/AIMCP/UnityAI/03_核心功能/UI/UI开发指南.md`
|
||||
- `F:/JMNet/AIMCP/UnityAI/03_核心功能/UI/UI界面拼接设计指南.md`
|
||||
3. 需要使用 JSON 与 Prefab 双向转换时，再阅读 README 中的 `UI工具` 入口：
|
||||
- `F:/JMNet/AIMCP/UnityAI/06_工具脚本/UI工具/`
|
||||
4. 按 UI 指南确认窗口命名、层级、资源路径和布局规则后，准备 UI JSON。
|
||||
5. 调用 `unity_generate_ui_prefab`。
|
||||
6. 目标 Prefab 路径优先使用：
|
||||
|
||||
```text
|
||||
Assets/Game/GameHFResource/CN/UIWindows/<WindowName>/<WindowName>.prefab
|
||||
```
|
||||
|
||||
4. 调用 `unity_get_console_logs` 查看是否有 Error 或关键 Warning。
|
||||
5. 如需要验证双向转换，再调用 `unity_export_prefab_to_json`。
|
||||
7. 调用 `unity_get_console_logs` 查看是否有 Error 或关键 Warning。
|
||||
8. 如需要验证双向转换，再调用 `unity_export_prefab_to_json`。
|
||||
|
||||
JSON 约束：
|
||||
|
||||
@@ -147,15 +115,14 @@ MCP 工具可以触发 Unity Editor 行为，因此必须保持最小权限：
|
||||
|
||||
连接失败：
|
||||
|
||||
1. 在 Unity 中打开 `Tools/Codex Unity MCP/Bridge Panel`。
|
||||
2. 点击 `开始连接` 或 `重启连接`。
|
||||
3. 用浏览器或 PowerShell 检查：
|
||||
1. 调用 `unity_health` 获取错误信息。
|
||||
2. 用浏览器或 PowerShell 检查：
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:17777/health"
|
||||
```
|
||||
|
||||
4. 如果端口占用，先在 Unity 面板断开连接，再重新开始连接。
|
||||
3. 如果连接仍失败，停止后续 Unity 操作并记录错误；Unity 侧启动、重启、面板操作不在本文档说明范围内。
|
||||
|
||||
MCP 工具不可见：
|
||||
|
||||
@@ -183,12 +150,6 @@ UI 生成失败：
|
||||
- `unity_export_prefab_to_json` 能把测试 Prefab 导出 JSON。
|
||||
- Unity Console 无新增 Error。
|
||||
|
||||
测试数据路径必须遵守：
|
||||
|
||||
```text
|
||||
Assets/Editor/MCP_{功能名}/<PrefabName>/
|
||||
```
|
||||
|
||||
UI 测试样例推荐路径：
|
||||
|
||||
```text
|
||||
@@ -202,7 +163,7 @@ Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.exported.json
|
||||
新增 MCP tool 时必须同步更新：
|
||||
|
||||
- `UnityAI/Tools/CodexUnityMcp/src/server.mjs`
|
||||
- `CrystalBattle_Client/Assets/Editor/Command/CodexUnityEditorBridge.cs`
|
||||
- Unity Bridge 侧对应命令代码
|
||||
- 本文档的工具列表与测试基准
|
||||
|
||||
新增 Unity 命令时必须满足：
|
||||
@@ -222,6 +183,6 @@ Assets/Editor/MCP_UI/CodexMcpTestWindow/CodexMcpTestWindow.exported.json
|
||||
|
||||
文档版本：
|
||||
|
||||
- v1.3
|
||||
- v1.4
|
||||
- 生效日期：2026-07-03
|
||||
- 适用项目：CrystalBattle_Client
|
||||
|
||||
Reference in New Issue
Block a user