Files

lms d31b49221e [docs][fix]: 补齐单文件模块状态字段与 MCP 维护 checklist

- 场景系统/数据配置框架/网络系统/Hotfix启动增加验证与当前状态
- 数据配置变更清单补充具体菜单/路径/命令
- 模块登记规则增加 README/使用指南/注意事项量化标准
- 模块文档模板明确 README 与使用指南分工
- MCP 使用规则维护要求改为 checklist

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-15 14:40:38 +08:00

4.7 KiB

Raw Permalink Blame History

CrystalBattle 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 版本
`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_execute_menu_item 不能执行任意菜单。新增菜单能力时必须同时修改 Bridge 白名单并验证风险。

四、标准调用流程

每轮 Unity 自动化前先调用 unity_health。
确认返回的项目路径就是当前目标工程。
执行当前任务需要的最少工具调用。
资源变化后调用 unity_refresh_assets。
调用 unity_get_console_logs 检查新增 Error 和关键 Warning。
Prefab/UI 继续做结构和实际显示验证，不能只确认命令返回成功。

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

五、UI 生成

UI 任务必须先从 UnityAI README 进入 UI 文档，并阅读：

随后按以下步骤执行：

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

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

六、安全边界

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

七、排错

连接失败

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

端口占用

Bridge 如果发现同端口已经存在有效服务，应连接到现有监听状态而不是重复启动。
不能通过同时启动多个监听器解决端口冲突。
状态仍不一致时记录端口、进程和 Bridge 状态，再处理占用来源。

UI 生成失败

读取 Unity Console。
检查 JSON 和目标路径是否存在且格式正确。
检查 Sprite、Font、Material 等 Asset 路径。
检查 rectTransform、递归 children 和组件字段。
检查目标 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 验证流程

4.7 KiB Raw Permalink Blame History Unescape Escape