UnityAI/modules/frameworks/编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md

Codex 与 Unity MCP 使用规则

一、定位

Codex 通过本地 stdio MCP Server 调用 Unity Editor 内的 HTTP Bridge。Bridge 只监听 127.0.0.1:17777，并把 Unity API 工作排队到 Editor 主线程执行。

当前能力只面向 Unity Editor 自动化，不覆盖 Play Mode、真机运行时调试或远程网络访问。

二、对接点

MCP Server: UnityAI/Tools/CodexUnityMcp/
Codex config: .codex/config.toml
Unity Bridge: http://127.0.0.1:17777

本文档不维护 Unity Bridge 的打开方式或 Unity Editor 内部目录结构。

三、可用工具

工具	用途	成功依据与注意事项
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 白名单并验证风险。

四、标准调用流程

1. 每轮 Unity 自动化前先调用 unity_health。
2. 确认返回的项目路径就是当前目标工程。
3. 执行当前任务需要的最少工具调用。
4. 资源变化后调用 unity_refresh_assets。
5. 如果刷新触发编译或 Domain Reload，等待 Bridge 恢复，再次调用 unity_health 并重新核对项目路径。
6. 执行白名单菜单；若调用超时，按“结果未知”处理，不立即重试。
7. 调用 unity_get_console_logs 检查任务完成标记、新增 Error 和关键 Warning。
8. Prefab、动画、材质和 UI 继续做结构或实际显示验证，不能只确认命令返回成功。

unity_health 失败时停止后续 Unity 命令并报告错误，不假设 Bridge 已经执行任何操作。

推荐调用链：

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 进入 UI 文档，并阅读：

• UI 开发指南
• UI 界面拼接
• UI 拼接工具

随后按以下步骤执行：

1. 检查设计图、目标 Prefab、窗口脚本和现有资源。
2. 明确传入 JSON 路径和目标 Prefab 路径。
3. 调用 unity_generate_ui_prefab。
4. 刷新 Assets 并读取 Console。
5. 检查 Prefab 层级、RectTransform、组件状态和资源引用。
6. 需要核对双向转换时调用 unity_export_prefab_to_json。
7. 在 Unity 运行环境验证实际显示和交互。

不规定固定测试目录、测试窗口名或中间数据目录。任务产生的路径由调用方明确提供，覆盖正式 Prefab 前必须确认。

九、安全边界

• Bridge 只监听 127.0.0.1，禁止改为 0.0.0.0 或局域网地址。
• MCP Server 不直接操作 Unity 资源，资源变更交给 Unity Bridge。
• HTTP 线程只接收和返回数据，Unity API 回到主线程执行。
• 不开放任意菜单、任意 C# 执行、批量删除、构建发布或 Git 操作。
• 生成和导出只修改调用参数明确指定的目标。
• 日志和错误返回包含命令、路径和失败原因，不返回无上下文的“失败”。

十、排错

连接失败

1. 调用 unity_health 保留原始错误。
2. 检查 .codex/config.toml 的 Node command 和 server 入口。
3. 确认 Tools/CodexUnityMcp 依赖已经安装。
4. 连接恢复前不执行其他 Unity 工具。

端口占用

• Bridge 如果发现同端口已经存在有效服务，应连接到现有监听状态而不是重复启动。
• 不能通过同时启动多个监听器解决端口冲突。
• 状态仍不一致时记录端口、进程和 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。
2. 检查 JSON 和目标路径是否存在且格式正确。
3. 检查 Sprite、Font、Material 等 Asset 路径。
4. 检查 rectTransform、递归 children 和组件字段。
5. 检查目标 Prefab 是否被错误覆盖或无法写入。

十一、维护

新增 MCP tool 时同步更新：

• Tools/CodexUnityMcp/src/server.mjs
• Unity Bridge 对应命令
• 本文档工具列表和验证步骤
• 对应测试用例或示例调用
• Bridge 白名单（如适用）

Bridge 返回统一结构：

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

文档关联

文档	关联原因
MCP 工具入口	MCP 模块入口
UI 开发指南	UI 生命周期和列表规则
UI 界面拼接	Prefab 拼接流程
UI 拼接工具	JSON/Prefab 工具结构
MCP Server README	Server 安装和实现
工作流清单	Unity/MCP 验证流程