> 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 → 故障排查器` 在阅读 Unity 控制台之前先查看它，当角色表现不符合预期时——它是 SDK 的第一线诊断工具。

### 打开故障排查器

选择 `Convai → 故障排查器` 在菜单栏中。窗口会打开到 `ConvaiCharacter` 最接近当前 Hierarchy 选择项的位置——所选对象本身，或者其最近的、带有 `ConvaiCharacter`的祖先对象。若未选择任何内容，它会回退到唯一的 `ConvaiCharacter` 当场景中恰好只有一个时。

故障排查器也可以从 SDK 的其他位置打开：其他 Convai 组件检查器中的状态芯片会打开同一个窗口，并已滚动到该芯片所报告的模块，同时会短暂高亮具体问题。选择不同的 `ConvaiCharacter` 在窗口打开时，Hierarchy 中的角色会自动将报告切换为该角色。

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

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

| 模式      | 显示内容                                                           |
| ------- | -------------------------------------------------------------- |
| **此角色** | 针对一个 `ConvaiCharacter`的报告，可从 Hierarchy 选择项或 **Character** 对象字段 |
| **此场景** | 打开场景中每个 `ConvaiCharacter` 的卡片——无论激活与否——每张卡片都显示其最严重的问题以及一个状态标签  |

在 **此场景** 模式下选择一张卡片会切回该角色的 **此角色** 模式。若未选择角色，窗口会显示 **选择一个 Convai 角色** 并要求你在 Hierarchy 或 **Character** 字段中选择一个。若已选择 **此场景** 且打开的场景中没有 `ConvaiCharacter` ，它会显示 **没有 Convai 角色**.

### 阅读一条问题

问题会按每个模块分组到一个可折叠部分中。每条问题都带有以下四种严重程度之一：

| 严重程度    | 含义                            | 是否计入“需修复 N 项”？   |
| ------- | ----------------------------- | ---------------- |
| `Error` | 在有人处理之前，该模块无法完成其工作            | 是                |
| `警告`    | 模块可以运行，但效果不如它本可以达到的水平         | 是                |
| `信息`    | 值得了解，但没有任何问题                  | 否——列在 **已检查且正常** |
| `正常`    | 已经正确；因此会显示一条通过检查的记录，而不是默认假设通过 | 否——列在 **已检查且正常** |

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

| 模块就绪状态                | 分区摘要                  |
| --------------------- | --------------------- |
| 该角色上不存在此组件            | `未设置`                 |
| 存在，但有东西会让它完全无法工作      | `已阻止`                 |
| 已存在且未被阻止，但没有配置任何内容来运行 | `目前不会发生任何事`           |
| 已设置并正常工作              | `Ready`               |
| 存在一个或多个错误或警告          | `需修复 1 项` / `需修复 N 项` |

窗口标题中的芯片在角色层面也会反映这一点—— `无需修复`，或 `需修复 1 项` / `需修复 N 项` ，用于当前角色的总问题数量。

{% hint style="info" %}
`ConvaiActionSetupHealthProvider` (`SDK/Editor/Actions/ConvaiActionSetupHealthProvider.cs`）是唯一通过完整 `IConvaiSetupHealthProvider` 接口报告的模块，因此 Actions 的问题是唯一可以带有 **修复方法**, **显示给我**，或 **打开** 按钮。凝视、身体动画、肢体语言、情绪和具身化仍然只作为较旧的、只读的 `IConvaiModuleSurveyor`注册。只要该模块适用于所选角色，故障排查器就仍会为这些模块各显示一个分区——它们的问题是信息性文本，没有附带按钮。
{% endhint %}

### 对一条问题采取操作

问题行最多会显示四个操作，具体取决于发出问题的模块提供了什么：

* **修复方法** — 运行该问题的一键修复并记录一个撤销步骤
* **显示给我** — 在 Hierarchy 或 Project 窗口中选择并闪烁定位该问题所指向的对象
* **打开** — 打开回答该问题的创作界面，例如 Actions 编辑器，并聚焦到相关动作
* **了解更多** — 打开该问题的文档链接（如果已设置）

### 重新检查并修复全部

页脚会显示报告构建于多久之前（`刚刚检查`, `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 => "Quest Giver";
    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: "No active quest",
                message: "This quest giver has no active quest, so it will not offer one.",
                fixLabel: "Assign default quest",
                fix: () => questGiver.ActiveQuest = QuestGiver.DefaultQuest);

            return new ConvaiSetupHealthResult(
                ModuleId, DisplayName, ConvaiCapabilityReadiness.Inert,
                summary: "No quest", findings: new[] { finding });
        }

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

{% endcode %}

注册具有幂等性——带着相同 `ModuleId` 再次注册同一提供器会替换先前的注册，而不会重复，因此域重新加载永远不会为同一模块生成两个分区。

### 下一步

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

{% 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 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.