UnityAI新规则

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

@@ -2,7 +2,7 @@
 
 ## 一、定位
 
-Codex 通过本地 stdio MCP Server 调用 Unity Editor 内的 HTTP Bridge。Bridge 只监听 `127.0.0.1:17777`，并把 Unity API 工作排队到 Editor 主线程执行。
+Codex 通过本地 stdio MCP Server 调用 Unity Editor 内的 HTTP Bridge。Bridge 监听 `127.0.0.1` 上的可配置端口（默认 17777，按项目隔离），并把 Unity API 工作排队到 Editor 主线程执行。
 
 当前能力只面向 Unity Editor 自动化，不覆盖 Play Mode、真机运行时调试或远程网络访问。
 
@@ -11,7 +11,7 @@ Codex 通过本地 stdio MCP Server 调用 Unity Editor 内的 HTTP Bridge。Bri
 ```text
 MCP Server: UnityAI/Tools/CodexUnityMcp/
 Codex config: .codex/config.toml
-Unity Bridge: http://127.0.0.1:17777
+Unity Bridge: http://127.0.0.1:<可配置端口>  (默认 17777，详见第七节)
 ```
 
 本文档不维护 Unity Bridge 的打开方式或 Unity Editor 内部目录结构。
@@ -152,9 +152,17 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档
 
 ### 端口占用
 
-- Bridge 如果发现同端口已经存在有效服务，应连接到现有监听状态而不是重复启动。
-- 不能通过同时启动多个监听器解决端口冲突。
-- 状态仍不一致时记录端口、进程和 Bridge 状态，再处理占用来源。
+端口按以下优先级解析，冲突自动顺延，必要时手动固定：
+
+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 状态，再处理占用来源。
 
 ### 刷新后连接失败