> 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 故障排查器是一个编辑器窗口，用于逐个模块列出阻止 `ConvaiCharacter` 正常工作的原因，并在每项问题旁提供修复方法。可通过 `Convai → Troubleshooter` 打开。当角色的行为不符合预期时，请先查看此窗口，再查看 Unity Console——它是 SDK 的首选诊断工具。

### 打开故障排查器

在菜单栏中选择 `Convai → Troubleshooter` 。窗口会显示距离当前层级视图选中项最近的 `ConvaiCharacter` ——可能是选中对象本身，也可能是其最近的、带有该组件的祖先对象 `ConvaiCharacter`。如果没有选中对象，且场景中恰好只有一个 `ConvaiCharacter` ，则会自动选择它。

也可以从 SDK 中的其他位置打开故障排查器：Convai 其他组件检查器中的状态标签会打开同一个窗口，并滚动到该标签所报告的模块，同时短暂高亮显示具体问题。故障排查器窗口打开时，如果在层级视图中选择了另一个 `ConvaiCharacter` ，报告会自动切换到该角色。

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

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

| 模式      | 显示内容                                                              |
| ------- | ----------------------------------------------------------------- |
| **此角色** | 显示单个 `ConvaiCharacter`的报告。角色可通过层级视图中的选中项或 **角色** 对象字段选择           |
| **此场景** | 为打开的场景中的每个 `ConvaiCharacter` 显示一张卡片，包括活动和非活动角色；每张卡片都显示最严重的问题和状态标签 |

在 **此场景** 模式下选择一张卡片，会切换回该角色的 **此角色** 模式。如果没有选中角色，窗口会显示 **选择一个 Convai 角色** 并提示你在层级视图或 **角色** 字段中选择一个角色。如果已选中 **此场景** ，但打开的场景中没有 `ConvaiCharacter` ，窗口会显示 **没有 Convai 角色**.

### 查看问题

问题按模块分组，每个模块对应一个可折叠区域。每项问题有以下四种严重程度之一：

| 严重程度      | 含义                               | 是否计入“待修复项数”？      |
| --------- | -------------------------------- | ----------------- |
| `Error`   | 必须采取操作后，模块才能正常工作                 | 是                 |
| `Warning` | 模块可以运行，但效果不够理想                   | 是                 |
| `信息`      | 值得了解，但没有问题                       | 否 — 列在 **已检查且正常** |
| `正常`      | 本来就正确；将其报告出来，让通过的检查结果一目了然，而不是靠猜测 | 否 — 列在 **已检查且正常** |

模块的分区标题会在右侧显示摘要。当模块没有错误或警告时，摘要会显示就绪状态；否则会显示问题数量：

| 模块就绪状态                   | 分区摘要                    |
| ------------------------ | ----------------------- |
| 此角色上不存在该组件               | `尚未设置`                  |
| 组件已存在，但有因素导致其完全无法运行      | `已阻止`                   |
| 组件已存在且未被阻止，但尚未配置任何要运行的内容 | `目前不会有任何操作`             |
| 已设置并正常运行                 | `就绪`                    |
| 存在一个或多个错误或警告             | `有 1 项待修复` / `有 N 项待修复` |

窗口标题栏中的状态标记会在角色层面反映这一情况 — `无需修复`，或 `有 1 项待修复` / `有 N 项待修复` 表示当前角色的合并问题总数。

{% hint style="info" %}
`ConvaiActionSetupHealthProvider` (`SDK/Editor/Actions/ConvaiActionSetupHealthProvider.cs`) 是唯一通过完整的 `IConvaiSetupHealthProvider` 接口报告问题的模块，因此只有 Actions 的检查结果可以附带 **修复**, **显示位置**，或 **打开** 按钮。Gaze、Body Animation、Body Language、Emotion 和 Embodiment 仍仅注册为较旧的只读 `IConvaiModuleSurveyor`。当这些模块适用于所选角色时，故障排查工具仍会为每个模块显示一个分区；其检查结果以说明文字呈现，不附带按钮。
{% 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` 的提供程序会替换之前的注册，而不是重复添加，因此域重新加载不会为同一模块生成两个区块。

### 后续步骤

有关与故障排查工具并列的诊断界面（日志记录、延迟指标和按模块划分的编辑器窗口），请参阅调试工具参考。

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](https://docs.convai.com/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 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/troubleshooting/convai-troubleshooter.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.
