AI 编码助手设置故障排除
诊断并修复 Convai Unity SDK 中的 Unity MCP 桥接重连、工具注册表刷新、过期工具拒绝以及 Unity AI Assistant 安装失败问题。
Convai Unity SDK 的 AI 编码集成依赖于三件事保持同步：兼容的 Unity AI Assistant 包、打包的 convai-unity-sdk 技能，以及在 Unity 的 MCP 服务器中注册的精确 20 个工具目录。打开 Convai > AI 编码设置 以打开 Convai 编辑器窗口的 AI 编码部分，并查看这三项的健康状态，以及每行的 修复 按钮来修复它们。
Convai > AI 编码设置 不会自动启动修复，也不会自动写入受管指令文件。每个 修复 按钮点击只会运行一个修复步骤，而且修复不会替你退出播放模式——请在重试前自己退出播放模式。
读取 AI 编码部分状态
该 设置健康状态 卡片显示四行状态： Unity 6000+, Unity AI Assistant, 已打包的 Convai 技能，以及 Convai MCP 工具。每个未就绪的行都会显示一个 修复 按钮，只要存在可用的修复路径。 Convai MCP 工具 该行的详细文本会告诉你当前属于哪种情况：
<count>/20 已注册——目录健康。<count>/20；请先安装 Unity AI Assistant——Assistant 包本身尚未就绪；请先修复该行。<count>/20；<issue>——Assistant 已就绪，但已注册的工具集与预期的 20 个工具不匹配；<issue>会准确列出问题所在。
A 修复 按钮在其启动的修复已在运行时才保持禁用。点击 修复 在 Unity 正在编译、更新包或处于播放模式时点击它，不会在之前禁用按钮——它会发布一条指出阻塞条件的状态消息，并不会启动修复。
修复完成后还会在这些行下方发布自己的摘要消息——例如 AI 编码设置已就绪。20/20 个 Convai 工具已注册。 用于已完成的工具注册修复。该摘要消息与上文所述每一行各自的详细文本是分开的。
Unity MCP 桥在工具修复后没有重新连接
A Convai MCP 工具 修复完成时会重启 Unity 的 MCP 桥（Unity.AI.MCP.Editor.UnityMCPBridge），这样外部 MCP 客户端——通过 stdio 或套接字连接的 IDE 代理——就能看到刷新的目录，而无需你重启 Unity。如果修复完成时桥并未运行，Convai 会将其视为无需重新连接，并在没有重新连接消息的情况下报告成功。如果桥正在运行，Convai 会停止并重启它；如果重启抛出异常，修复会完成工具注册，但会单独报告桥失败，而外部客户端会一直看到旧目录，直到你解决它。
Convai MCP 工具在注册表刷新后没有注册
工具注册修复会调用 Unity 的 MCP 工具注册表来刷新其列表，然后强制进行一次资源刷新并请求脚本重新编译，接着在最多 60 秒内轮询等待预期的 20 个工具出现。在轮询期间，Convai 会大约每秒重试一次注册表刷新，因此除了点击 修复之外，通常很少需要再手动刷新一次。如果连注册表类型本身都找不到——例如因为 Unity 的 MCP Server 包没有安装，或者尚未完成编译——刷新会报告注册表未加载，而在包到位之前无论重试多少次都无法解决。
即使数量匹配，工具目录仍被拒绝
Convai 按工具的精确名称而不是数量来验证已注册的工具集。预期集合是 20 个 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 和编辑器日志。
Convai 只接受 Unity AI Assistant 版本介于 2.13.0 和 3.0.0. A 2.13.0 预发行构建必须是 pre.2 或更高版本才算兼容；任何严格介于 2.13.0 和 3.0.0 之间的版本都可接受，不受预发行标签影响；而 3.0.0 本身仅在作为预发行版本时可接受，绝不接受最终发布版。
故障排查表
Convai MCP 工具 行显示 <count>/20；请先安装 Unity AI Assistant
Unity AI Assistant 包未安装，或其版本超出 Convai 可接受范围
点击 修复 在 Unity AI Assistant 行；只有在 Assistant 就绪后，工具修复才会变为可用
该 Unity AI Assistant 行显示 已就绪，然后 Convai MCP 工具 修复才会变为可用
修复 按钮保持禁用
该按钮启动的修复已在运行
等待当前修复完成
按钮会再次变为可点击
点击 修复 没有任何作用，并且会出现一条警告消息
Unity 正在编译、更新包或播放模式处于活动状态
等待编译或包更新完成，或退出播放模式，然后再次点击 修复 再次
警告消息会清除，修复继续
Assistant 修复报告 无法启动 Unity AI Assistant 安装 并附带异常消息
Unity Package Manager 无法开始安装请求
先解决报告的异常（通常是 Package Manager 操作已在进行中），然后点击 修复 再次
状态消息会变为安装中消息，随后变为结果消息
Assistant 修复报告 Unity AI Assistant 安装失败 并附带 Package Manager 错误
Unity Package Manager 拒绝或无法完成安装（网络、注册表或版本冲突）
先解决报告的 Package Manager 错误，然后点击 修复 再次
该 Unity AI Assistant 行显示已安装版本并且 已就绪
Assistant 修复报告 Assistant 在包刷新后仍不可用
安装已由 Package Manager 完成，但生成的版本超出 2.13.0–3.0.0
请在 Package Manager 中检查已安装版本；安装一个处于可接受范围内的版本
重新打开 Convai > AI 编码设置 会显示 Unity AI Assistant 行已就绪
Convai MCP 工具 行显示 <count>/20；<issue> 其中 <count> 等于 20
已注册工具集的数量正确，但包含缺失或意外的 Convai_前缀名称（来自先前版本的残留条目）
点击 修复 以强制再次刷新注册表并重新编译；如果问题仍然存在，请重新导入或更新 Convai SDK 包
该行显示 20/20 已注册 且没有问题文本
注册表刷新报告工具注册表 未加载
Unity 的 MCP Server 包未安装，或者其程序集尚未完成编译
安装或启用 Unity 的 MCP Server 包，并让 Unity 完成编译，然后重试 修复
注册表刷新不再报告此消息
注册表刷新报告工具注册表 没有兼容的 RefreshTools 方法
已安装的 Unity MCP Server 版本没有暴露 Convai 预期的反射 API
将 Unity 的 MCP Server 包更新到与此 Convai SDK 版本兼容的版本
注册表刷新完成时不再出现此消息
修复超时报告工具目录 不健康 在 Assistant 加载后
60 秒修复窗口在已注册名称匹配预期 20 个之前就已到期
点击 修复 再次；新安装的 Assistant 有时还需要再经过一次 Unity 编译
修复完成，并带有 AI 编码设置已就绪。20/20 个 Convai 工具已注册。
工具达到 20/20 但该行报告 Unity MCP 桥重新连接失败
重启 Unity.AI.MCP.Editor.UnityMCPBridge 抛出异常，或者其 Stop/Start/IsRunning 生命周期 API 缺失
检查编辑器日志中报告的桥错误；确认 Unity MCP Server 包暴露了兼容的桥生命周期
该行报告 AI 编码设置已就绪 ，参数为 Unity MCP 桥已重新连接
外部 MCP 客户端（IDE 代理）在修复完成后仍显示旧的工具列表
修复完成时桥未运行，因此无需重新连接，或者客户端在桥重启前已缓存了目录
重新连接或重启外部 MCP 客户端
客户端的工具列表与当前 20 工具目录匹配
已打包的 Convai 技能 该行保持未就绪，报告技能 仍然缺失
AIAssistantSkills/convai-unity-sdk/SKILL.md 在解析后的 Convai SDK 包文件夹中不存在（安装中断或包缓存损坏）
通过 Package Manager 重新导入或更新 Convai SDK 包，然后点击 修复
该行显示 SKILL.md 路径和 已就绪
后续步骤
AI 编码助手AI 编码助手快速开始MCP 工具参考最后更新于
这有帮助吗？