Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

【更新】调整Codex Unity MCP使用规则

Browse Source
This commit is contained in:
Shiliang
2026-07-03 15:59:14 +08:00
parent b213e39b28
commit 21db0c0b47
1 changed files with 29 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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