From f2c1d8792bdb4d328425140a9948c798012f58c9 Mon Sep 17 00:00:00 2001 From: "JM\\Shiliang" <1353521835@qq.com> Date: Thu, 27 Aug 2026 16:48:43 +0800 Subject: [PATCH] =?UTF-8?q?[docs][feat]:=20=E5=AE=8C=E5=96=84=20Unity=20MC?= =?UTF-8?q?P=20=E4=BD=BF=E7=94=A8=E4=B8=8E=E6=8E=92=E9=94=99=E6=B5=81?= =?UTF-8?q?=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Tools/CodexUnityMcp/README.md | 10 ++ .../MCP工具/Codex_Unity_MCP使用规则.md | 115 +++++++++++++++--- .../frameworks/编辑器工具/MCP工具/README.md | 2 + 3 files changed, 113 insertions(+), 14 deletions(-) diff --git a/Tools/CodexUnityMcp/README.md b/Tools/CodexUnityMcp/README.md index 23c67b7..09c7bbd 100644 --- a/Tools/CodexUnityMcp/README.md +++ b/Tools/CodexUnityMcp/README.md @@ -39,6 +39,16 @@ If `pnpm` is not on `PATH`, locate the configured Codex bundled runtime for the - `unity_generate_ui_prefab` - `unity_export_prefab_to_json` +## Operational Notes + +- Start every automation run with `unity_health` and verify that the returned project path is the intended Unity project. +- `unity_refresh_assets` can trigger compilation and a domain reload. The bridge may be temporarily unavailable; reconnect with `unity_health` before continuing. +- A `unity_execute_menu_item` timeout means the result is unknown, not that the menu failed. Do not retry immediately; reconnect and inspect Unity Console logs or `Editor.log` first. +- Bridge log caching starts again after a domain reload. Use `Editor.log` when evidence from the previous bridge lifetime is required. +- A successful command proves Editor-side execution only. Prefab structure, animation sampling, Game View, Play Mode, build and device behavior require separate validation. + +The canonical Chinese workflow and troubleshooting rules are maintained in [Codex 与 Unity MCP 使用规则](../../modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md). + ## Environment Optional: diff --git a/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md b/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md index bb841bb..09e2ff2 100644 --- a/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md +++ b/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md @@ -18,14 +18,14 @@ Unity Bridge: http://127.0.0.1:17777 ## 三、可用工具 -| 工具 | 用途 | -|---|---| -| `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_health` | 检查 Bridge、项目路径和 Unity 版本 | 必须核对 `projectPath`、`applicationDataPath` 和 `unityVersion`，不能只看 `ok` | +| `unity_refresh_assets` | 执行 `AssetDatabase.Refresh()` | 可能触发编译和 Domain Reload；短暂断连不等于刷新失败 | +| `unity_execute_menu_item` | 执行 Bridge 白名单中的菜单项 | 超时表示结果未知，不表示菜单失败；禁止立即重复执行 | +| `unity_get_console_logs` | 读取最近 Unity Console 日志 | 只覆盖当前 Bridge/Domain 生命周期内缓存的日志 | +| `unity_generate_ui_prefab` | 根据 JSON 生成 UI Prefab | 命令成功后仍需检查 Prefab 结构、引用和实际显示 | +| `unity_export_prefab_to_json` | 将 UI Prefab 导出为 JSON | 核对输出路径及导出内容，避免把文件存在当作内容正确 | `unity_execute_menu_item` 不能执行任意菜单。新增菜单能力时必须同时修改 Bridge 白名单并验证风险。 @@ -35,12 +35,84 @@ Unity Bridge: http://127.0.0.1:17777 2. 确认返回的项目路径就是当前目标工程。 3. 执行当前任务需要的最少工具调用。 4. 资源变化后调用 `unity_refresh_assets`。 -5. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。 -6. Prefab/UI 继续做结构和实际显示验证，不能只确认命令返回成功。 +5. 如果刷新触发编译或 Domain Reload，等待 Bridge 恢复，再次调用 `unity_health` 并重新核对项目路径。 +6. 执行白名单菜单；若调用超时，按“结果未知”处理，不立即重试。 +7. 调用 `unity_get_console_logs` 检查任务完成标记、新增 Error 和关键 Warning。 +8. Prefab、动画、材质和 UI 继续做结构或实际显示验证，不能只确认命令返回成功。 `unity_health` 失败时停止后续 Unity 命令并报告错误，不假设 Bridge 已经执行任何操作。 -## 五、UI 生成 +推荐调用链： + +```text +unity_health + -> 修改项目文件 +unity_refresh_assets + -> 编译/Domain Reload 时等待并重试 unity_health +unity_execute_menu_item + -> 超时时不重试，等待 Bridge 恢复 +unity_get_console_logs + -> 核对完成标记、统计数据和 Error +``` + +## 五、刷新、编译与超时判定 + +### 刷新后的暂时断连 + +`unity_refresh_assets` 会调用 `AssetDatabase.Refresh()`。新增或修改 C# 文件时，Unity 可能随后编译脚本并执行 Domain Reload，旧 Bridge 实例在这段时间内不可用。 + +处理方式： + +1. 保留刷新调用的返回结果。 +2. Bridge 断连时等待 Unity 完成编译，不连续发送其他命令。 +3. 重试 `unity_health`，确认 Bridge 已恢复且仍连接目标工程。 +4. 再继续菜单执行和日志检查。 + +编译错误应以 Unity Console 或 `Editor.log` 为依据，不能把编译期间的一次连接失败直接判定为脚本错误。 + +### 菜单执行超时 + +Bridge 把菜单任务排队到 Unity 主线程。同步导入大量资源、创建 Prefab 或重新序列化资源时，HTTP 请求可能先达到 MCP 超时，但 Unity 主线程仍在继续执行菜单。 + +此时状态是“结果未知”： + +1. 不立即重复调用同一菜单，避免重复导入或覆盖资源。 +2. 等待 Bridge 恢复后先调用 `unity_health`。 +3. 调用 `unity_get_console_logs` 查找菜单输出的完成标记、统计数据或异常。 +4. 当前 Domain 的日志不足时，再查看目标项目的 Unity `Editor.log`。 +5. 只有确认上一次没有执行或执行失败后，才允许重试。 + +长任务对应的菜单实现应尽量幂等，并输出明确的开始、完成、失败标记和关键统计。 + +## 六、任务专用验证菜单 + +现有 MCP 不提供任意 Hierarchy、Animator、Play Mode 或 C# 操作。需要自动检查特定资产时，使用范围明确的 Editor 菜单作为适配层： + +1. 在目标项目中实现确定性的 `[MenuItem]` 方法。 +2. 把菜单完整路径加入 Bridge 的 `AllowedMenuItems` 白名单。 +3. 刷新资源，等待编译和 Bridge 重连。 +4. 用 `unity_execute_menu_item` 执行准确的菜单路径。 +5. 菜单把验证结果以结构化摘要写入 Console，再用 `unity_get_console_logs` 读取。 + +菜单只完成当前任务所需的有限操作，不开放任意 C# 执行或通用层级修改。适合记录的验证指标包括： + +- 导入资产数量、缺失材质或纹理引用数量。 +- 动画 `curveBindings` 总数、匹配目标骨骼的绑定数量。 +- 用 `AnimationMode.SampleAnimationClip` 采样前后的骨骼 Transform 变化数量。 +- Renderer Bounds 的主轴、尺寸和异常缩放。 +- Prefab 的 Animator、Controller、Avatar、材质和纹理引用。 + +推荐验证顺序是：磁盘产物检查 → Unity 导入/设置菜单 → 菜单输出具体指标 → Console 无新增 Error → 必要的 Scene/Game View 或设备验证。 + +## 七、日志与验证边界 + +- Bridge 返回 `ok: true` 只证明命令被 Bridge 成功处理，不证明最终画面、动画或设备运行正确。 +- `unity_get_console_logs` 缓存当前 Bridge/Domain 生命周期内的日志；Domain Reload 前的历史日志可能不可见。 +- 需要跨 Domain 追溯或菜单超时取证时，以目标工程的 Unity `Editor.log` 补充验证。 +- 日志结论应保留消息、堆栈、资产路径和统计值，区分 Error、预期 Warning 与无关历史日志。 +- Prefab 结构、动画采样和引用检查属于 Editor 证据；Game View、Play Mode、APK 或微信真机效果必须单独验证。 + +## 八、UI 生成 UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档，并阅读： @@ -60,7 +132,7 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档 不规定固定测试目录、测试窗口名或中间数据目录。任务产生的路径由调用方明确提供，覆盖正式 Prefab 前必须确认。 -## 六、安全边界 +## 九、安全边界 - Bridge 只监听 `127.0.0.1`，禁止改为 `0.0.0.0` 或局域网地址。 - MCP Server 不直接操作 Unity 资源，资源变更交给 Unity Bridge。 @@ -69,7 +141,7 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档 - 生成和导出只修改调用参数明确指定的目标。 - 日志和错误返回包含命令、路径和失败原因，不返回无上下文的“失败”。 -## 七、排错 +## 十、排错 ### 连接失败 @@ -84,6 +156,21 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档 - 不能通过同时启动多个监听器解决端口冲突。 - 状态仍不一致时记录端口、进程和 Bridge 状态，再处理占用来源。 +### 刷新后连接失败 + +1. 判断 Unity 是否正在编译脚本或执行 Domain Reload。 +2. 等待编译结束后重试 `unity_health`。 +3. Bridge 恢复后核对项目路径，再继续任务。 +4. 持续无法恢复时检查 Unity Console、`Editor.log` 和 Bridge Panel。 + +### 菜单执行超时 + +1. 把本次调用标记为“结果未知”，不要立即重试。 +2. 等待 `unity_health` 恢复。 +3. 读取 Console 或 `Editor.log` 中的完成标记和异常。 +4. 检查目标资产是否已经生成或修改。 +5. 确认未执行或失败后才重试。 + ### UI 生成失败 1. 读取 Unity Console。 @@ -92,7 +179,7 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档 4. 检查 `rectTransform`、递归 `children` 和组件字段。 5. 检查目标 Prefab 是否被错误覆盖或无法写入。 -## 八、维护 +## 十一、维护 新增 MCP tool 时同步更新： diff --git a/modules/frameworks/编辑器工具/MCP工具/README.md b/modules/frameworks/编辑器工具/MCP工具/README.md index 1a2f2df..8907746 100644 --- a/modules/frameworks/编辑器工具/MCP工具/README.md +++ b/modules/frameworks/编辑器工具/MCP工具/README.md @@ -20,6 +20,8 @@ Codex 通过本地 Node MCP Server 与 Unity Editor Bridge 交互。该实现不 具体调用、UI 前置阅读、安全边界和排错见 [Codex 与 Unity MCP 使用规则](Codex_Unity_MCP使用规则.md)。 +推荐顺序：`unity_health` → 修改文件 → `unity_refresh_assets` → 重连并再次健康检查 → 执行白名单菜单 → `unity_get_console_logs`。刷新触发编译时 Bridge 会暂时断连；菜单超时表示结果未知，确认日志和资产状态前不要重复执行。 + ## 文档关联 | 文档 | 关联原因 |