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 工具。

端口占用

端口按以下优先级解析，冲突自动顺延，必要时手动固定：

1. 环境变量 UNITY_MCP_PORT（最高优先，手动指定绝对端口）。
2. 项目根目录 UnityMcpPort.txt（一行数字，可随项目入 Git，便于固定端口）。
3. 项目路径 FNV-1a 哈希派生（同一项目在任意机器得到同一端口，便于写死配置）。
4. 默认端口 17777。

• 多个 Unity 项目各自独立监听不同端口（按项目隔离），允许同时运行多个监听器，互不干扰。
• 绑定首选端口失败时，Bridge 向后递增重试（最多 20 个端口），不再静默“连接到现有监听”，避免请求串到别的项目。
• 实际端口与首选端口不一致时，Unity Console 输出 Warning，并提示把 UNITY_MCP_PORT 或 UnityMcpPort.txt 设为实际端口（或释放首选端口）以保持 MCP 路由稳定。
• 连接恢复前不执行其他 Unity 工具；状态仍不一致时记录端口、进程和 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 验证流程