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 项 用于当前角色的综合问题数量。

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

对一条发现采取操作

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

• 修复方法 ——运行该发现的一键修复，并记录一个撤销步骤
• 显示给我 ——在 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)	针对该角色的只读报告；绝不修改场景

Assets/Editor/MyCustomSetupHealthProvider.cs

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);
    }
}

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

下一步

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

调试工具参考