排查 AI 编码助手设置问题
诊断并修复 Unity MCP 桥重新连接、工具注册表刷新、过期工具拒绝,以及 Convai Unity SDK 中 Unity AI Assistant 的安装失败。
Convai Unity SDK 的 AI 编码集成依赖于三项内容保持同步:兼容的 Unity AI Assistant 包、打包的 convai-unity-sdk 技能,以及在 Unity 的 MCP 服务器中注册的精确 44 个工具目录。打开 Convai > Convai Editor中粘贴你的密钥,然后选择 AI 编码 窗口中的导航栏,查看这三项的健康状态,并可在每一行使用 修复方法 按钮进行修复。
阅读 AI 编码部分状态
该 设置健康 卡片显示四个状态行: Unity 6000+, Unity AI Assistant, 打包的 Convai 技能,以及 Convai MCP 工具。每个未就绪的行都会显示一个 修复方法 按钮,只要存在可修复路径。该 Convai MCP 工具 行的详细文本会告诉你当前属于哪种情况:
<count>/44 已注册——目录状态正常。<count>/44;请先安装 Unity AI Assistant——Assistant 包本身尚未就绪;请先修复该行。<count>/44;<问题>——Assistant 已就绪,但已注册的工具集与预期的 44 个工具不匹配;<问题>会准确列出具体问题。
一个 修复方法 按钮仅在其启动的修复已在运行时保持禁用。点击 修复方法 当 Unity 正在编译、更新包或处于 Play 模式时,不会在事前禁用按钮——它会发布一条状态消息,说明阻塞条件,并且不会启动修复。
修复完成后还会在这些行下方发布自己的摘要消息——例如 AI 编码设置已就绪。44/44 个 Convai 工具已注册。 这是工具注册修复完成后的提示。该摘要消息与上文所述的每一行自身详细文本是分开的。
工具修复后 Unity MCP 桥未重新连接
一个 Convai MCP 工具 修复通过重启 Unity 的 MCP 桥(Unity.AI.MCP.Editor.UnityMCPBridge)来完成,因此外部 MCP 客户端——通过 stdio 或 socket 连接的 IDE 代理——无需重启 Unity 就能看到已刷新的目录。如果修复完成时桥未运行,Convai 会将其视为无需重新连接,并在没有重连消息的情况下报告成功。如果桥当时在运行,Convai 会先停止再重启它;如果重启抛出异常,修复会完成工具注册,但会单独报告桥故障,而外部客户端会继续看到旧目录,直到你将其解决。
注册表刷新后 Convai MCP 工具未注册
工具注册修复会调用 Unity 的 MCP 工具注册表来刷新其列表,然后强制进行资源刷新并请求脚本重新编译,接着轮询最多 60 秒,等待预期的 44 个工具出现。在轮询期间,Convai 会大约每秒重试一次注册表刷新,因此通常不需要在点击 修复方法之外再手动刷新一次。如果注册表类型本身都找不到——例如因为 Unity 的 MCP Server 包未安装或尚未完成编译——刷新会报告注册表未加载,而在包可用之前,无论重试多少次都无法解决。
尽管数量匹配,工具目录仍被拒绝
Convai 通过精确名称而非数量来验证已注册的工具集。预期的集合是这 44 个 Convai_前缀名称,它们与 SDK 的工具目录相对应。如果已注册集合中的工具数量正确,但名称错误——例如部分完成的 SDK 更新留下了过时名称,或者旧版 SDK 的工具从未被替换——则 Convai MCP 工具 行仍会报告未就绪,并列出缺失的名称和意外的名称。重新运行 修复方法 会强制再次刷新注册表并重新编译;如果问题仍然存在,请重新导入或更新 Convai SDK 包,使已注册名称与当前版本的目录一致。
Unity AI Assistant 包安装失败
修复 Unity AI Assistant 行会通过 Unity Package Manager 安装一个特定的固定包版本。该安装可能以三种不同方式失败:
安装请求本身无法启动(例如 Package Manager 操作已在进行中,或者清单处于不良状态)——该部分会直接报告异常消息。
Unity Package Manager 拒绝或无法完成安装(网络故障、注册表不可达、版本冲突)——该部分会报告 Package Manager 自己的错误消息;如果 Package Manager 未提供,则使用通用回退消息。
Package Manager 报告成功,但最终安装的版本仍超出 Convai 可接受的范围——在 60 秒修复窗口结束后,该部分会报告 Assistant 仍不可用,并要求你检查 Package Manager 和 Editor 日志。
故障排除表
Convai MCP 工具 行显示 <count>/44;请先安装 Unity AI Assistant
Unity AI Assistant 包未安装,或其版本超出 Convai 的接受范围
点击 修复方法 在 Unity AI Assistant 先修复该行;只有当 Assistant 就绪后,工具修复才会可用
该 Unity AI Assistant 行显示 Ready,然后 Convai MCP 工具 修复变为可用
修复方法 按钮保持禁用
由该按钮启动的修复已在运行
等待当前修复完成
按钮会再次可点击
点击 修复方法 不会有任何作用,并会出现警告消息
Unity 正在编译、更新包或 Play 模式处于活动状态
等待编译或包更新完成,或退出 Play 模式,然后点击 修复方法 再次
警告消息会消失,修复继续进行
Assistant 修复报告 无法启动 Unity AI Assistant 安装 并带有异常消息
Unity Package Manager 无法开始安装请求
解决报告的异常(通常是已有 Package Manager 操作正在进行),然后点击 修复方法 再次
状态消息会变为安装中的消息,然后变为结果
Assistant 修复报告 Unity AI Assistant 安装失败 并带有 Package Manager 错误
Unity Package Manager 拒绝或无法完成安装(网络、注册表或版本冲突)
解决报告的 Package Manager 错误,然后点击 修复方法 再次
该 Unity AI Assistant 行显示已安装版本,并且 Ready
Assistant 修复报告 Assistant 在包刷新后仍不可用
Package Manager 显示安装已完成,但结果版本超出 2.13.0–3.0.0
请在 Package Manager 中检查已安装版本;安装位于接受范围内的版本
重新打开 Convai > Convai Editor 并选择 AI 编码 会显示 Unity AI Assistant 该行为已就绪
Convai MCP 工具 行显示 <count>/44;<问题> 其中 <count> 等于 44
已注册的工具集数量正确,但包含缺失或意外的 Convai_以 - 开头的名称(来自先前版本的过期条目)
点击 修复方法 以强制再次刷新注册表并重新编译;如果问题仍然存在,请重新导入或更新 Convai SDK 包
该行显示 44/44 已注册 且没有问题文本
注册表刷新报告工具注册表 未加载
Unity 的 MCP Server 包未安装,或其程序集尚未完成编译
安装或启用 Unity 的 MCP Server 包,并让 Unity 完成编译,然后重试 修复方法
注册表刷新不再报告此消息
注册表刷新报告工具注册表 没有兼容的 RefreshTools 方法
已安装的 Unity MCP Server 版本未公开 Convai 所期望的反射 API
将 Unity 的 MCP Server 包更新为与此 Convai SDK 版本兼容的版本
注册表刷新完成且不再出现此消息
修复超时,并报告工具目录 状态不健康 在 Assistant 加载后
60 秒修复窗口到期时,已注册名称仍未与预期的 44 个匹配
点击 修复方法 再次;全新的 Assistant 安装有时还需要再进行一次 Unity 编译
修复完成并带有 AI 编码设置已就绪。44/44 个 Convai 工具已注册。
工具达到 44/44 但该行报告 Unity MCP 桥重新连接失败
重启 Unity.AI.MCP.Editor.UnityMCPBridge 抛出异常,或者其 停止/开始/IsRunning 生命周期 API 缺失
请查看 Editor 日志中的桥接错误;确认 Unity MCP Server 包公开了兼容的桥接生命周期
该行报告 AI 编码设置已就绪 使用 Unity MCP 桥已重新连接
修复完成后,外部 MCP 客户端(IDE 代理)仍显示旧的工具列表
修复完成时桥未运行,因此无需重新连接,或者客户端在桥重启前缓存了目录
重新连接或重启外部 MCP 客户端
客户端的工具列表与当前 44 工具目录一致
打包的 Convai 技能 该行保持未就绪,并报告技能 仍然缺失
AIAssistantSkills/convai-unity-sdk/SKILL.md 未出现在已解析的 Convai SDK 包文件夹中(安装中断或包缓存损坏)
通过 Package Manager 重新导入或更新 Convai SDK 包,然后点击 修复方法
该行显示 SKILL.md 路径以及 Ready
下一步
AI 编码助手AI 编码助手快速入门MCP 工具参考最后更新于
这有帮助吗?