> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/troubleshooting.md). # 排查 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 编码` 在窗口的导航栏中，以查看这三项的健康状态，并可对每一行提供 `修复方法` 按钮来修复它们。 {% hint style="info" %} “ `AI 编码` 该部分绝不会自动开始修复或写入受管指令文件。每个 `修复方法` 按钮点击只会运行一个修复步骤，而且修复绝不会替你退出 Play Mode——请在重试前先手动退出 Play Mode。 {% endhint %} ### 阅读 AI 编码部分状态 “ **Setup Health** 卡片显示四行状态： `Unity 6000+`, `Unity AI Assistant`, `打包的 Convai 技能`以及 `Convai MCP 工具`。每一行未就绪时，如果存在修复路径，都会显示一个 `修复方法` 按钮。 `Convai MCP 工具` 该行的详细文本会告诉你当前属于哪种情况： * `/44 已注册` —— 目录状态良好。 * `/44；请先安装 Unity AI Assistant` —— Assistant 包本身尚未就绪；请先修复该行。 * `/44；` —— Assistant 已就绪，但已注册工具集与预期的 44 个工具不匹配； `` 会准确列出问题所在。 一个 `修复方法` 按钮仅在其启动的某个修复已在运行时保持禁用。点击 `修复方法` 在 Unity 正在编译、更新包或处于 Play Mode 时，不会提前禁用该按钮——它会发布一条状态消息，说明阻塞条件，并且不会开始修复。 修复完成后，还会在这些行下方发布自己的摘要消息——例如 `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_`-前缀的名称，与 SDK 的工具目录相对应。 `Convai MCP 工具` 如果已注册的集合工具数量正确，但名称错误——例如部分完成的 SDK 更新留下的旧名称，或旧版 SDK 的工具从未被替换——则 `修复方法` 行仍会报告未就绪，并列出缺失的名称和意外的名称。重新运行 ### Unity AI Assistant 包安装失败 修复 `Unity AI Assistant` 行会通过 Unity Package Manager 安装一个特定的固定版本包。该安装可能以三种不同方式失败： * 安装请求本身无法启动（例如 Package Manager 操作已在进行中，或 manifest 状态不佳）——该部分会直接报告异常消息。 * Unity Package Manager 拒绝或失败了安装（网络失败、注册表不可达、版本冲突）——该部分会报告 Package Manager 自身的错误消息；如果 Package Manager 没有提供，则显示通用回退消息。 * Package Manager 报告成功，但最终安装的版本仍超出 Convai 可接受范围——当 60 秒修复窗口结束后，该部分会报告 Assistant 仍不可用，并要求你检查 Package Manager 和 Editor 日志。 {% hint style="warning" %} Convai 只接受介于 `2.13.0` 和 `3.0.0`之间的 Unity AI Assistant 版本。一个 `2.13.0` 预发布构建必须是 `pre.2` 或更高版本才算兼容；任何严格介于 `2.13.0` 和 `3.0.0` 之间的版本，无论是否带预发布标签，都可接受；而 `3.0.0` 本身则仅在预发布版本中被接受，绝不接受最终正式版。 {% endhint %} ### 故障排查表 | 症状 | 可能原因 | 修复方法 | 验证 | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | | `Convai MCP 工具` 该行显示 `/44；请先安装 Unity AI Assistant` | Unity AI Assistant 包未安装，或其版本超出 Convai 可接受范围 | 点击 `修复方法` 在 `Unity AI Assistant` 行上先执行；工具修复只有在 Assistant 就绪后才可用 | “ `Unity AI Assistant` 该行显示 `就绪`，然后 `Convai MCP 工具` 修复才会变为可用 | | `修复方法` 按钮保持禁用 | 该按钮启动的修复已在运行 | 等待当前修复完成 | 按钮会再次变得可点击 | | 点击 `修复方法` 不会有任何作用，并且会出现一条警告消息 | Unity 正在编译、更新包，或 Play Mode 已激活 | 等待编译或包更新完成，或退出 Play Mode，然后点击 `修复方法` 再次 | 警告消息会清除，修复继续进行 | | 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 > Convai Editor` 并选择 `AI 编码` 会显示 `Unity AI Assistant` 该行处于就绪状态 | | `Convai MCP 工具` 该行显示 `/44；` 其中 `` 等于 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` 抛出异常，或者其 `Stop`/`Start`/`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` 路径并 `就绪` | ### 下一步 {% content-ref url="/pages/d8c18409ae9c4e08b59f112c685f31eedd8cba20" %} [AI 编码助手](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant.md) {% endcontent-ref %} {% content-ref url="/pages/fef78cf340cc23d3c5966ea9c7099beadba8f247" %} [AI 编码助手快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md) {% endcontent-ref %} {% content-ref url="/pages/2556d68ab00a9475a0e5c6ca8c0541b3d69dc561" %} [MCP 工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.