> 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 中的 Unity MCP 桥接重连、工具注册表刷新、过期工具拒绝，以及 Unity AI Assistant 安装失败问题。

Convai Unity SDK 的 AI 编码集成依赖以下三项保持同步：兼容的 Unity AI Assistant 包、打包好的 `convai-unity-sdk` 技能，以及向 Unity MCP 服务器注册的准确 44 项工具目录。打开 `Convai > Convai Editor`，然后在窗口的导航栏中选择 `AI Coding` ，即可查看这三项的健康状态；每行旁边都有 `Fix` 按钮可用于修复。

{% hint style="info" %}
AI Coding `部分绝不会自动开始修复，也不会自动写入受管理的指令文件。每次点击` Fix `按钮只会执行一个修复步骤；修复过程也不会替你退出播放模式——请先自行退出播放模式，再重试。` 查看 AI Coding 部分的状态
{% endhint %}

### “

设置健康状态 **”卡片显示四行状态：** Unity 6000+ `Unity AI Assistant`, `Packaged Convai Skill`, `以及`Convai MCP Tools `。如果某行尚未就绪，且存在对应的修复方式，该行就会显示`Fix `按钮。` 该行的详细信息会说明当前情况： `。如果某行尚未就绪，且存在对应的修复方式，该行就会显示` \<count>/44 registered

* `— 工具目录状态正常。` \<count>/44; install Unity AI Assistant first
* `— Assistant 包本身尚未就绪；请先修复该行。` \<count>/44; \<issue>
* `— Assistant 已就绪，但已注册的工具集与预期的 44 项不符；` \<issue> `会准确列出问题所在。` 只有在由该按钮启动的修复正在运行时，

Fix `按钮才会保持禁用。Unity 正在编译、更新包或处于播放模式时点击` ，按钮不会提前禁用；系统会发布一条指出阻止条件的状态消息，并且不会启动修复。 `按钮才会保持禁用。Unity 正在编译、更新包或处于播放模式时点击` 修复完成后，还会在各状态行下方发布一条修复摘要消息，例如

AI coding setup ready. 44/44 Convai tools registered. `表示工具注册修复已完成。此摘要消息与上述各行自己的详细信息是分开的。` Unity MCP 桥接器在工具修复后未重新连接

### Convai MCP Tools

修复完成后，会重启 Unity 的 MCP 桥接器（ `Unity.AI.MCP.Editor.UnityMCPBridge` ），这样外部 MCP 客户端（通过标准输入/输出或套接字连接的 IDE 智能体）就能看到更新后的工具目录，而无需重启 Unity。如果修复完成时桥接器未运行，Convai 会将其视为无需重新连接，并报告成功且不显示重新连接消息。如果桥接器正在运行，Convai 会停止并重启它；如果重启时发生异常，工具注册仍会完成，但桥接器故障会单独报告。在解决该问题之前，外部客户端仍会看到旧的工具目录。`刷新注册表后，Convai MCP Tools 未注册`工具注册修复会调用 Unity 的 MCP 工具注册表以刷新其列表，然后强制刷新资源并请求重新编译脚本，接着最多轮询 60 秒，等待预期的 44 项工具出现。轮询期间，Convai 大约每秒重试一次注册表刷新，因此通常不需要在点击

### 之后再手动刷新

。 `修复`。如果无法找到注册表类型（例如，未安装 Unity 的 MCP Server 包，或该包尚未完成编译），刷新操作会报告注册表未加载。无论重试多少次，在安装该包之前都无法解决此问题。

### 工具目录被拒绝，但工具数量相符

Convai 会逐一核对注册的工具名称，而非仅检查数量。预期的工具集合是这 44 个 `Convai_`前缀名称，与 SDK 的工具目录保持一致。如果注册的工具数量正确，但名称不匹配（例如，SDK 更新未完全完成而遗留的旧名称，或旧版 SDK 中未被替换的工具名称）， `Convai MCP Tools` 行仍会显示未就绪，并列出缺少的名称和多出的名称。再次运行 `修复` 会强制再次刷新注册表并重新编译；如果之后仍不匹配，请重新导入或更新 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 日志。

{% 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 Tools` 行显示 `<count>/44; install Unity AI Assistant first`          | 未安装 Unity AI Assistant 软件包，或其版本不在 Convai 接受的范围内                                          | 点击 `修复` 中的 `Unity AI Assistant` 行；只有 Assistant 准备就绪后，工具修复功能才会启用 | 当 `Unity AI Assistant` 行显示 `就绪`后，再 `Convai MCP Tools` 修复功能变为可用               |
| `修复` 按钮仍处于禁用状态                                                                 | 该按钮启动的修复操作已在运行                                                                           | 等待当前修复操作完成                                                      | 按钮会再次变为可点击状态                                                                 |
| 点击 `修复` 不会有任何反应，并会显示一条警告消息                                                     | Unity 正在编译、更新软件包，或处于播放模式                                                                 | 等待编译或软件包更新完成，或退出播放模式，然后点击 `修复` 再次                               | 警告消息消失，修复继续进行                                                                |
| 助手维修报告 `无法启动 Unity AI Assistant 安装` 并附带异常消息                                    | Unity 包管理器无法开始安装请求                                                                       | 解决报告的异常（通常是软件包管理器操作已在进行中），然后点击 `Fix` 再次                         | 状态消息会先变为正在安装，然后显示结果                                                          |
| Assistant 修复报告 `Unity AI Assistant installation failed` 并显示 Package Manager 错误 | Unity Package Manager 拒绝了安装，或无法完成安装（网络、注册表或版本冲突）                                         | 解决报告的 Package Manager 错误，然后再次点击 `Fix` 再次                        | 该 `Unity AI Assistant` 行显示已安装的版本以及 `Ready`                                   |
| Assistant 修复报告称 Assistant `still unavailable after the package refresh`        | Package Manager 显示安装已完成，但最终安装的版本不在 `2.13.0`–`3.0.0`                                      | 在 Package Manager 中检查已安装的版本；安装一个符合接受范围的版本                       | 重新打开 `Convai > Convai Editor` 并选择 `AI Coding` 会将 `Unity AI Assistant` 行显示为就绪 |
| `Convai MCP Tools` 行显示 `<count>/44; <issue>` 其中 `<count>` 等于 44                | 已注册的工具集数量正确，但包含缺失或意外的 `Convai_`前缀名称（来自先前版本的过时条目）                                         | 点击 `Fix` 以强制再次刷新注册表并重新编译；如果问题仍然存在，请重新导入或更新 Convai SDK 包         | 该行显示 `44/44 registered` 且未提供问题文本                                             |
| 注册表刷新报告工具注册表 `is not loaded`                                                   | 未安装 Unity 的 MCP Server 软件包，或其程序集尚未完成编译                                                   | 安装或启用 Unity 的 MCP Server 软件包，并等待 Unity 完成编译，然后重试 `修复`           | 注册表刷新不再报告此消息                                                                 |
| 注册表刷新报告工具注册表 `has no compatible RefreshTools method`                           | 已安装的 Unity MCP Server 版本未提供 Convai 所需的反射 API                                             | 将 Unity 的 MCP Server 软件包更新到与此 Convai SDK 版本兼容的版本                | 注册表刷新完成，且不再显示此消息                                                             |
| 修复超时，报告工具目录 `unhealthy` 在 Assistant 加载后                                        | 在注册名称与预期的 44 个名称匹配之前，60 秒修复时限已用尽                                                         | 再次点击 `修复` ；全新安装 Assistant 有时需要再让 Unity 完成一次编译                   | 修复完成，显示 `AI coding setup ready. 44/44 Convai tools registered.`              |
| 工具已达到 `44/44` 但该行报告 `Unity MCP bridge reconnect failed`                        | 重启 `Unity.AI.MCP.Editor.UnityMCPBridge` 时发生异常，或者其 `Stop`/`Start`/`IsRunning` 生命周期 API 缺失 | 检查 Editor 日志中报告的桥接错误；确认 Unity MCP Server 软件包提供了兼容的桥接生命周期        | 该行报告 `AI coding setup ready` 并显示 `Unity MCP bridge reconnected`              |
| 修复完成后，外部 MCP 客户端（IDE 代理）仍显示旧的工具列表                                              | 修复完成时桥接未运行，因此无需重新连接；或者客户端在桥接重启前缓存了工具目录                                                   | 重新连接或重启外部 MCP 客户端                                               | 客户端的工具列表与当前包含 44 个工具的目录一致                                                    |
| `Packaged Convai Skill` 行仍显示未就绪，并报告技能 `is still missing`                       | `AIAssistantSkills/convai-unity-sdk/SKILL.md` 在解析到的 Convai SDK 软件包文件夹中不存在（安装中断或软件包缓存损坏）  | 通过 Package Manager 重新导入或更新 Convai SDK 软件包，然后点击 `修复`             | 该行显示 `SKILL.md` 路径以及 `就绪`                                                    |

### 后续步骤

{% content-ref url="/pages/d8c18409ae9c4e08b59f112c685f31eedd8cba20" %}
[AI 编码助手](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant.md)
{% endcontent-ref %}

{% content-ref url="/pages/fef78cf340cc23d3c5966ea9c7099beadba8f247" %}
[AI 编码助手快速入门](https://docs.convai.com/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 工具参考](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
