> 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 编码助手设置 Convai Unity SDK 的 AI 编码集成依赖于三项内容保持同步：兼容的 Unity AI Assistant 包、打包的 `convai-unity-sdk` 技能，以及在 Unity 的 MCP 服务器中注册的精确 37 个工具目录。打开 `Convai > Convai Editor`粘贴你的密钥，然后选择 `AI Coding` 在窗口的导航栏中，查看这三项的健康状态，并在每行提供 `修复方法` 用于修复它们的按钮。 {% hint style="info" %} 该 `AI Coding` 该部分不会自动启动修复，也不会写入托管指令文件。每次 `修复方法` 按钮点击只会执行一步修复，而且修复不会替你退出播放模式——请先自行退出播放模式再重试。 {% endhint %} ### 查看 AI 编码部分状态 该 **Setup Health** 卡片显示四行状态： `Unity 6000+`, `Unity AI Assistant`, `已打包的 Convai 技能`，以及 `Convai MCP 工具`。每个未就绪的行都会显示一个 `修复方法` 按钮，只要存在可用的修复路径。 `Convai MCP 工具` 该行的详细文本会告诉你当前属于哪种情况： * `/37 已注册` —— 目录状态正常。 * `/37；请先安装 Unity AI Assistant` —— Assistant 包本身尚未就绪；请先修复该行。 * `/37；` —— Assistant 已就绪，但已注册的工具集与预期的 37 个工具不匹配； `` 会准确列出问题所在。 某个 `修复方法` 按钮仅在其启动的修复正在运行时保持禁用。点击 `修复方法` 当 Unity 正在编译、更新包或处于播放模式时，不会事先禁用按钮——它会发布一条状态消息，说明阻塞条件，并且不会启动修复。 修复完成后还会在各行下方发布自己的摘要消息——例如 `AI 编码设置已就绪。37/37 个 Convai 工具已注册。` 这是一次已完成的工具注册修复的示例。该摘要消息与上面描述的每一行自己的详细文本是分开的。 ### 工具修复后 Unity MCP 桥未重新连接 某个 `Convai MCP 工具` 修复通过重启 Unity 的 MCP 桥（`Unity.AI.MCP.Editor.UnityMCPBridge`），从而使外部 MCP 客户端——通过 stdio 或套接字连接的 IDE 代理——无需重启 Unity 就能看到刷新的目录。如果修复完成时桥未运行，Convai 会将其视为无需重新连接，并在没有重新连接消息的情况下报告成功。如果桥正在运行，Convai 会停止并重启它；如果该重启抛出异常，修复会完成工具注册，但会单独报告桥故障，而外部客户端会一直看到旧目录，直到你解决问题。 ### 注册表刷新后 Convai MCP 工具未注册 工具注册修复会调用 Unity 的 MCP 工具注册表刷新其列表，然后强制刷新资源并请求脚本重新编译，接着轮询最多 60 秒，等待预期的 37 个工具出现。在轮询期间，Convai 大约每秒会重试一次注册表刷新，因此在点击 `修复方法`之外，通常很少需要再手动刷新一次。如果根本找不到注册表类型——例如因为 Unity 的 MCP Server 包未安装或尚未完成编译——刷新会报告注册表未加载，并且在该包存在之前，任何重试都无法解决。 ### 工具目录被拒绝，尽管数量匹配 Convai 按精确名称验证已注册的工具集，而不是按数量。预期的集合是这 37 个 `Convai_`以该前缀开头的名称，它们与 SDK 的工具目录对应。如果已注册的集合数量正确但名称错误——例如部分完成的 SDK 更新留下的旧名称，或者从未被替换的旧版 SDK 工具——则 `Convai MCP 工具` 该行仍会报告未就绪，并列出缺少哪些名称以及哪些名称是意外的。重新运行 `修复方法` 会强制再次刷新注册表并重新编译；如果之后不匹配仍然存在，请重新导入或更新 Convai 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 仅接受位于以下范围内的 Unity AI Assistant 版本： `2.13.0` 和 `3.0.0`。一个 `2.13.0` 预发布版本必须是 `pre.2` 或更高版本才算兼容；任何严格介于 `2.13.0` 和 `3.0.0` 无论预发布标记如何都被接受；而 `3.0.0` 本身仅在预发布版本中被接受，绝不接受最终正式版。 {% endhint %} ### 故障排查表 | 症状 | 可能原因 | 修复方法 | 验证 | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `Convai MCP 工具` 行显示 `/37；请先安装 Unity AI Assistant` | Unity AI Assistant 包未安装，或者其版本超出 Convai 接受的范围 | 点击 `修复方法` 组件上的 `Unity AI Assistant` 先修复该行；工具修复只有在 Assistant 就绪后才可用 | 该 `Unity AI Assistant` 行显示 `Ready`，然后 `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` 该行显示已安装版本并且 `Ready` | | Assistant 修复报告 Assistant `在包刷新后仍不可用` | 按 Package Manager 的结果看安装已完成，但得到的版本超出 `2.13.0`–`3.0.0` | 请在 Package Manager 中检查已安装版本；安装一个在接受范围内的版本 | 重新打开 `Convai > Convai Editor` 并选择 `AI Coding` 会显示 `Unity AI Assistant` 该行为已就绪 | | `Convai MCP 工具` 行显示 `/37；` 其中 `` 等于 37 | 已注册的工具集数量正确，但包含缺失或意外的 `Convai_`以该前缀开头的名称（来自先前版本的旧条目） | 点击 `修复方法` 以强制再次刷新注册表并重新编译；如果问题仍然存在，请重新导入或更新 Convai SDK 包 | 该行显示 `37/37 已注册` 且没有问题文本 | | 注册表刷新报告工具注册表 `未加载` | Unity 的 MCP Server 包未安装，或者其程序集尚未完成编译 | 安装或启用 Unity 的 MCP Server 包，并让 Unity 完成编译，然后重试 `修复方法` | 注册表刷新不再报告此消息 | | 注册表刷新报告工具注册表 `没有兼容的 RefreshTools 方法` | 已安装的 Unity MCP Server 版本未公开 Convai 期望的反射 API | 将 Unity 的 MCP Server 包更新到与此 Convai SDK 版本兼容的版本 | 注册表刷新完成且不再出现此消息 | | 修复超时并报告工具目录 `异常` 在 Assistant 加载后 | 在已注册名称与预期的 37 个名称匹配之前，60 秒修复窗口已到期 | 点击 `修复方法` 再次；全新安装的 Assistant 有时还需要再经过一次 Unity 编译 | 修复完成并显示 `AI 编码设置已就绪。37/37 个 Convai 工具已注册。` | | 工具达到 `37/37` 但该行报告 `Unity MCP 桥重新连接失败` | 重启 `Unity.AI.MCP.Editor.UnityMCPBridge` 抛出异常，或者其 `Stop`/`Start`/`IsRunning` 生命周期 API 缺失 | 请检查 Editor 日志中的桥错误；确认 Unity MCP Server 包提供了兼容的桥生命周期 | 该行报告 `AI 编码设置已就绪` 和 `Unity MCP 桥已重新连接` | | 修复完成后，外部 MCP 客户端（IDE 代理）仍显示旧的工具列表 | 修复完成时桥未运行，因此无需重新连接；或者客户端在桥重启之前缓存了目录 | 重新连接或重启外部 MCP 客户端 | 客户端的工具列表与当前 37 工具目录一致 | | `已打包的 Convai 技能` 该行保持未就绪并报告技能 `仍然缺失` | `AIAssistantSkills/convai-unity-sdk/SKILL.md` 未出现在解析后的 Convai SDK 包文件夹中（安装中断或包缓存损坏） | 通过 Package Manager 重新导入或更新 Convai SDK 包，然后点击 `修复方法` | 该行显示 `SKILL.md` 路径以及 `Ready` | ### 下一步 {% 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.