企业官网建设流程全解析

Unity-Skills 是专为 Unity 编辑器打造的 AI 自动化插件，它为每个打开的 Unity 项目启动一个本地 REST 服务器，让 AI 客户端（如各类编程助手）可以真正"动手"操作场景、资源与脚本。当你同时打开多个 Unity 项目时，最头疼的问题是：该连哪个端口？会不会操作错项目？本文带你完整理解 Unity-Skills 的端口发现、全局注册表与实例锁定三大机制，快速解决多项目并行开发场景下的 AI 自动化难题。

为什么多项目并行会"连错服务器"？

传统做法里，工具往往写死localhost:8090这样的固定端口。但 Unity-Skills 的设计是：每个 Unity 编辑器实例各自占用一个端口。当你在同一台电脑上打开 3 个 Unity 项目，就会有 3 个 UnitySkills 服务器同时在跑。

如果客户端"猜"端口，就可能出现：你以为在操控 A 项目，实际请求打到了 B 项目的编辑器上——AI 把场景对象创建到了错误的工程里。这正是 Unity-Skills 要用三层机制解决的核心问题：

1. 端口发现：项目自动认领空闲端口，客户端自动找到正确的端口
2. 全局注册表：一份共享文件记录所有在线实例的身份信息
3. 实例锁定：客户端锁定目标项目，连错时服务端直接拒绝

端口发现机制：8090–8100 自动认领

UnitySkills 服务器启动时不会"抢"固定端口，而是按顺序探测 8090 到 8100 的端口范围，按启动顺序认领第一个空闲端口：

• 第一个启动的编辑器拿到8090
• 第二个启动的拿到8090已被占用，自动落到8091
• 以此类推，最多支持 11 个并发实例

这个逻辑实现在 SkillsHttpServer.cs 的启动流程中：先尝试用户偏好的端口，失败则逐个扫描，直到找到可用端口。因此要牢记一条关键原则：端口号 ≠ 项目身份。编辑器重启、重新编译后端口可能变化，任何"记死端口"的做法都不可靠。

全局注册表：所有实例的"户口本"

比端口探测更可靠的方案，是 Unity-Skills 的全局注册表——一份位于用户主目录下的 JSON 文件：

~/.unity_skills/registry.json

每个 Unity 实例启动服务器时都会把自己的"身份信息"写入这份文件，核心字段包括：

这个服务由 RegistryService.cs 实现，几个细节值得新手注意：

• 心跳保鲜：运行中的实例每 30 秒发一次心跳，超过 120 秒没有心跳的条目会被判定为"僵尸"并自动清理，见 Heartbeat 方法。
• 原子写入：多个编辑器进程同时写同一份文件，靠跨进程文件锁 + 临时文件原子替换保证不互相覆盖，见 AtomicReadModifyWrite。
• 重载感知：Unity 重新编译脚本（域重载）时，实例不会从注册表消失，而是标记为reloading，客户端会原地等待它复活，而不是转投其他项目。

客户端读取注册表时同样内置"活性判断"规则，与服务器侧的清理逻辑保持一致，相关实现见 unity_skills.py。

实例锁定：如何确保"只操作对的项目"

端口发现解决了"连得上"，实例锁定解决"连得对"。这里有双向保护。

客户端：自动锚定当前项目

内置 Python 客户端的自动发现策略（_find_first_available）遵循一个非常贴心的优先级：

1. 当前工作目录属于哪个已注册项目，就连哪个——你在 A 项目目录里跑命令，就绝不会碰 B 项目
2. 若当前目录不属于任何项目，按心跳新鲜度尝试其他存活实例
3. 最后兜底：扫描 8090–8100 全部端口

一旦锁定目标，客户端会记住该实例的instanceId，并在后续每个请求上都携带它。就算目标项目正在重新编译，客户端也会在同端口原地等待它复活，而不是悄悄切换到你不想动的项目。

服务端：连错了就直接 409 拒绝

反向的保险在服务端：请求可以通过查询参数或 HTTP 头声明"我期望操作的是谁"：

• expectInstance/X-Expect-Instance：精确的实例 ID
• expectProject/X-Expect-Project：项目名或项目文件夹名

如果请求打到了"不是你"的编辑器上，服务器什么都不会执行，而是返回409 INSTANCE_MISMATCH，错误体里会列出所有在线实例、各自的端口和状态，并附上"应该把请求重发到哪个端口"的修复建议。这套守卫逻辑实现在 SkillsHttpServer.InstanceExpectation.cs，错误体构建见 BuildInstanceMismatchResponse。

此外，所有响应都会附带X-Unity-Instance与X-Unity-Project响应头，/health接口也返回projectName和instanceId——你可以随时验证"回答我的到底是哪个编辑器"，这部分协议细节可参考 SKILL_FULL.md 的 Boot Handshake 章节。

实战清单：多项目协作的 5 个最佳实践

1. 🎯启动前先看注册表：用python unity_skills.py --list-instances打印所有存活实例（名称、路径、端口、Unity 版本），再决定连谁
2. 🎯用身份而不是端口指定目标：客户端支持--port <n>、--version "2022"、按项目名/实例 ID 匹配（target参数），比裸端口可靠得多，见 客户端构造函数
3. 🎯编辑器重启后重新探测：端口可能在重启后变化，不要复用会话中记下的旧端口
4. 🎯看到 409 就停下：收到INSTANCE_MISMATCH说明打错了项目，按错误体里的建议改端口重发，而不是"硬试"
5. 🎯批量操作前核对 projectName：每个项目的服务器都独立，操作场景、批量写资源前，先确认/health返回的项目名与你的目标一致

相关文档与源码入口

常见问题

问：最多能同时开几个 Unity 项目？答：端口池 8090–8100 共 11 个端口，理论上支持最多 11 个 UnitySkills 服务器并发。

问：注册表文件损坏或丢失了怎么办？答：注册表是可重建的——任何编辑器重启服务器都会重新写入自己的条目；客户端在读不到注册表时会自动退化为端口扫描，不影响基本连接。

问：reloading 状态会卡住 AI 吗？答：不会。客户端对reloading实例会按健康检查上报的超时上限（默认 120 秒）原地等待并轮询，期间每 1.5 秒复查一次注册表，实例复活后立即继续，无需人工干预。

掌握端口发现、全局注册表与实例锁定这三层设计后，你就可以放心地在同一台机器上并行多个 Unity 项目，让 AI 自动化"各回各家、各找各妈"——这也是 Unity-Skills 多实例架构最优雅的地方。