> 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/troubleshooting/convai-troubleshooter.md).

# Convai Troubleshooter

Convai Troubleshooter 窗口参考，包括如何报告发现、应用修复，以及允许项目添加自己的检查项。

Convai Troubleshooter 是一个编辑器窗口，用于列出阻止某个 `ConvaiCharacter` 对象正常工作的原因，按模块逐一列出，并在每个发现旁提供修复。可从 `Convai → Troubleshooter` 在阅读 Unity Console 之前先使用它——当角色行为不符合预期时，它是 SDK 的第一道诊断手段。

### 打开 Troubleshooter

选择 `Convai → Troubleshooter` 在菜单栏中。该窗口会打开到 `ConvaiCharacter` 离当前 Hierarchy 选择最近的对象——即所选对象本身，或者其携带该组件的最近祖先 `ConvaiCharacter`。在没有任何选择时，它会回退到场景中唯一的 `ConvaiCharacter` 对象（如果恰好只有一个）。

Troubleshooter 也可从 SDK 的其他位置打开：在其他 Convai 组件检查器中的状态标签会打开同一个窗口，并自动滚动到该标签所报告的模块，同时短暂高亮具体发现。若选择不同的 `ConvaiCharacter` Hierarchy 中的对象，窗口会自动切换报告到该角色。

### 检查单个角色或整个场景

窗口右上角的切换开关可在两种模式间切换：

| 模式      | 显示内容                                                                    |
| ------- | ----------------------------------------------------------------------- |
| **此角色** | 某个角色的报告 `ConvaiCharacter`，从 Hierarchy 选择或从 **角色** 对象字段                  |
| **此场景** | 为每个 `ConvaiCharacter` 开放场景中的角色——包括激活和未激活的——显示一张卡片，每张卡片都带有其最严重的发现和一个状态标签 |

在 **此场景** 模式下选择一张卡片会切换回 **此角色** 该角色的模式。若未选择任何角色，窗口会显示 **选择一个 Convai 角色** 并提示你在 Hierarchy 中或在 **角色** 字段中选择一个。对于 **此场景** 已选中且在开放场景中没有 `ConvaiCharacter` 时，它会显示 **没有 Convai 角色**.

### 阅读一条发现

发现按模块分组到可折叠的部分中。每条发现都有四种严重级别之一：

| 严重级别 | 含义                            | 是否计入“需修复 N 项”？   |
| ---- | ----------------------------- | ---------------- |
| `错误` | 在有人采取措施之前，该模块无法完成其工作          | 是                |
| `警告` | 模块可以运行，但效果未达到最佳               | 是                |
| `信息` | 值得了解，但没有问题                    | 否——列在 **已检查且正常** |
| `正常` | 已经正确；会报告出来，以便能看到通过的检查，而不是默认假定 | 否——列在 **已检查且正常** |

模块的分节标题会显示一个右对齐的摘要。当模块没有错误或警告时，摘要是就绪短语；否则就是问题数量：

| 模块就绪状态               | 分节摘要                  |
| -------------------- | --------------------- |
| 该角色上不存在此组件           | `未设置`                 |
| 存在，但有某些因素使其完全无法工作    | `阻塞`                  |
| 已存在且未被阻止，但未配置任何可运行内容 | `暂时不会发生任何事情`          |
| 已设置并正常工作             | `就绪`                  |
| 存在一个或多个错误或警告         | `需修复 1 项` / `需修复 N 项` |

窗口标题栏中的状态标签会在角色层级上反映这一点—— `无需修复`，或 `需修复 1 项` / `需修复 N 项` 用于当前角色的综合问题数量。

{% hint style="info" %}
`ConvaiActionSetupHealthProvider` (`SDK/Editor/Actions/ConvaiActionSetupHealthProvider.cs`) 是唯一通过完整 `IConvaiSetupHealthProvider` 接口进行报告的模块，因此 Actions 的发现是唯一可以带有 **修复方法**, **显示给我**，或 **打开** 按钮的。Gaze、Body Animation、Body Language、Emotion 和 Embodiment 仍然只作为较旧的只读 `IConvaiModuleSurveyor`。只要该模块适用于所选角色，Troubleshooter 仍会为这些模块分别显示一个部分——它们的发现是信息文本，不附带按钮。
{% endhint %}

### 对一条发现采取操作

一条发现行最多显示四个操作，具体取决于触发它的模块提供了什么：

* **修复方法** ——运行该发现的一键修复，并记录一个撤销步骤
* **显示给我** ——在 Hierarchy 或 Project 窗口中选中并定位该发现所涉及的对象
* **打开** ——打开能处理该发现的创作界面，例如 Actions Editor，并聚焦到相关操作
* **了解更多** ——在已设置文档链接时，打开该发现的文档链接

### 重新检查并修复所有内容

页脚显示报告是在多久之前生成的（`刚刚检查`, `N 秒前检查`，或 `N 分钟前检查`）以及一个 **重新检查** 按钮会立即重新运行所有检查，忽略缓存的报告。

一个 **全部修复** 当整份报告中有多条发现都带有一键修复时，页脚中会出现该按钮。按下后会打开一个确认对话框，列出即将应用的所有修复，然后将它们作为一个撤销步骤一次性应用—— `Ctrl+Z` 可一起撤销所有修复。某个模块自己的分节会显示一个更小的 **修复这些（N）** 按钮，规则相同，但仅限于该部分中可修复的可见发现。

所有通过的内容—— `正常` 和 `信息` 发现——会折叠到报告底部的一个 **已检查且正常** 部分中，因此即使没有问题的角色也仍可被检查，而不是仅仅凭信任。

### 报告你自己的发现

项目可以通过实现 `IConvaiSetupHealthProvider` 并将其注册到 `ConvaiSetupHealthRegistry.Register`。已注册提供程序的发现会与 Convai 自己的发现并列显示，并具有相同的 **修复方法**, **显示给我**以及 **打开** 支持，只要提供程序提供这些内容。注册还会让这些发现对 `Convai.InspectScene` 和 `Convai.ValidateSetup` MCP 工具可见，因此 AI 编码助手读取到的报告与人在窗口中看到的报告相同。

`IConvaiSetupHealthProvider` 需要：

| 成员                                                          | 说明                                  |
| ----------------------------------------------------------- | ----------------------------------- |
| `string ModuleId { get; }`                                  | 稳定的带点 ID，例如 `myproject.quest-giver` |
| `string DisplayName { get; }`                               | 用户在窗口中称呼该模块的名称                      |
| `int Order { get; }`                                        | 该部分在报告中的位置；数值越小越靠前                  |
| `bool AppliesTo(GameObject characterRoot)`                  | 该模块是否与该角色相关；此判断必须开销很小               |
| `ConvaiSetupHealthResult Inspect(GameObject characterRoot)` | 针对该角色的只读报告；绝不修改场景                   |

{% code title="Assets/Editor/MyCustomSetupHealthProvider.cs" %}

```csharp
using Convai.Editor.AI;
using Convai.Editor.Diagnostics;
using UnityEditor;
using UnityEngine;

[InitializeOnLoad]
internal sealed class MyCustomSetupHealthProvider : IConvaiSetupHealthProvider
{
    static MyCustomSetupHealthProvider() =>
        ConvaiSetupHealthRegistry.Register(new MyCustomSetupHealthProvider());

    public string ModuleId => "myproject.quest-giver";
    public string DisplayName => "任务发布者";
    public int Order => 100;

    public bool AppliesTo(GameObject characterRoot) =>
        characterRoot.GetComponent<QuestGiver>() != null;

    public ConvaiSetupHealthResult Inspect(GameObject characterRoot)
    {
        var questGiver = characterRoot.GetComponent<QuestGiver>();
        if (questGiver.ActiveQuest == null)
        {
            var finding = new ConvaiSetupFinding(
                id: "myproject.quest-giver.no-active-quest",
                severity: ConvaiModuleFindingSeverity.Warning,
                title: "没有活动任务",
                message: "这个任务发布者没有活动任务，因此不会提供任务。",
                fixLabel: "分配默认任务",
                fix: () => questGiver.ActiveQuest = QuestGiver.DefaultQuest);

            return new ConvaiSetupHealthResult(
                ModuleId, DisplayName, ConvaiCapabilityReadiness.Inert,
                summary: "没有任务", findings: new[] { finding });
        }

        return new ConvaiSetupHealthResult(
            ModuleId, DisplayName, ConvaiCapabilityReadiness.Working,
            summary: questGiver.ActiveQuest.Title);
    }
}
```

{% endcode %}

注册是幂等的——同一提供程序以相同的 `ModuleId` 重新注册时会替换先前的注册，而不是重复注册，因此域重新加载时绝不会为同一模块生成两个部分。

### 下一步

有关与 Troubleshooter 并列的诊断界面，请参阅调试工具参考——日志、延迟指标以及按模块划分的编辑器窗口。

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/debug-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/troubleshooting/convai-troubleshooter.md?ask=<question>&goal=<endgoal>
```

`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.