> 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/debug-tools-reference.md).

# 调试工具参考

Convai SDK 调试工具参考，包括 Troubleshooter、按模块分开的编辑器窗口、日志记录和客户端延迟指标。

Convai Unity SDK 配备了一套分层诊断工具：Convai 故障排查工具、各模块的编辑器窗口、可配置的日志系统（支持按子系统控制详细程度）、用于调试操作的实时 Inspector 探针、在 `ConvaiRoomManager`上查看的实时会话诊断信息、输出到 Console 的会话指标，以及用于会话管线分析的客户端延迟测量。本页是这些工具的完整参考。

### Convai 故障排除工具

`Convai → Troubleshooter` 可逐个模块报告阻碍 `ConvaiCharacter` 正常工作的原因，并在每项问题旁提供修复方法。使用本页后续介绍的工具之前，请先从这里开始——大多数设置错误都会在故障排查工具中显示，并可一键修复，无需搜索 Console。

{% content-ref url="/pages/683b1f80f2d09bf9f43b94fabdbf62b3dd4466aa" %}
[Convai Troubleshooter](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/convai-troubleshooter.md)
{% endcontent-ref %}

### 各模块的编辑器窗口

每个化身模块和 Actions 都有各自的创作与诊断窗口，可从 `Convai` 菜单中打开：

| 窗口          | 菜单路径                             | 显示内容                                                                    |
| ----------- | -------------------------------- | ----------------------------------------------------------------------- |
| Actions 编辑器 | `Convai → Actions Editor`        | 创作、测试，以及 **实时** 选项卡——正在进行的批次、近期批次时间线（显示每个步骤的耗时和结果）、合并后的目标注册表，以及各操作的详细信息 |
| 化身编辑器       | `Convai → Embodiment Editor`     | **用于角色化身堆栈的设置、**, **预设**和 **实时** 选项卡                                    |
| 注视编辑器       | `Convai → Gaze Editor`           | 注视模块的设置与调节                                                              |
| 身体动画编辑器     | `Convai → Body Animation Editor` | 身体动画模块的设置与调节                                                            |
| 情绪编辑器       | `Convai → Emotion Editor`        | 设置、角色面部最终解析出的表情映射，以及播放模式下的实时视图                                          |

### 诊断

日志配置位于“诊断”部分，可通过 `Convai → Settings` 或 `Edit → Project Settings → Convai SDK`.

#### 配置位置

打开 `Convai → Settings` 或 `Edit → Project Settings → Convai SDK` 并滚动到 **诊断** 部分。两个入口显示的都是同一个 `DiagnosticsSectionView`，因此在一处所做的更改也会显示在另一处。控制 Unity Console 中显示内容的设置包括：

* **预设** — 一键按钮，可同时设置全局日志级别、包含堆栈跟踪和控制台彩色输出；请参阅 [日志预设](#logging-presets)
* **全局日志级别** — 应用于所有日志类别的最低详细程度
* **包含堆栈跟踪** — 警告和错误条目是否包含堆栈跟踪
* **控制台彩色输出** — Unity 控制台中的日志条目是否以颜色区分
* **类别覆盖** — 覆盖全局级别的子系统级设置

Diagnostics（诊断）部分标题也有自己的 **重置** 按钮，点击后会应用与下方 `Default` 预设相同的配置。

#### 日志预设

全局日志级别字段上方有三个预设按钮。每个预设都会同时设置全局级别和两个输出标志，然后清除所有类别覆盖。

| 预设            | 全局日志级别  | 包含堆栈跟踪 | 控制台彩色输出 | 类别覆盖 |
| ------------- | ------- | ------ | ------- | ---- |
| `Verbose`     | `Trace` | 开启     | 开启      | 已清除  |
| `Default`     | `Info`  | 开启     | 开启      | 已清除  |
| `Errors Only` | `Error` | 开启     | 开启      | 已清除  |

`Default` 与 SDK 的默认日志配置相同。应用任何预设都会覆盖全局日志级别、包含堆栈跟踪和控制台彩色输出，并移除现有的类别覆盖——点击预设后，请重新应用项目专属的覆盖设置。

#### 日志级别

SDK 使用六种日志级别。数值越大，详细程度越高。

| 级别     | 值 | 控制台中显示的内容         |
| ------ | - | ----------------- |
| **关闭** | 0 | 无 — 禁用所有 SDK 日志   |
| **错误** | 1 | 仅错误               |
| **警告** | 2 | 错误和警告             |
| **信息** | 3 | 错误、警告和信息消息 *（默认）* |
| **调试** | 4 | 以上所有内容，外加调试消息     |
| **跟踪** | 5 | 所有内容，包括细粒度的内部跟踪信息 |

默认级别为 **信息**。切换到 **调试** 进行问题调查时会产生多得多的输出——发布到生产环境前请将其关闭。设置 **全局日志级别** 设置为 **关闭** 以静默所有 SDK 日志。

{% hint style="warning" %}
`Debug`SDK 源代码中级别为 `[Conditional("UNITY_EDITOR")]`, `[Conditional("DEVELOPMENT_BUILD")]`和 `[Conditional("CONVAI_DEBUG_LOGGING")]`修饰。这意味着 **Debug 日志调用会从非开发版本中编译移除** 除非你将 `CONVAI_DEBUG_LOGGING` 添加到脚本定义符号中。将 `GlobalLogLevel` 设为 `Debug` 在发布版本中不会产生 Debug 消息，因为这些调用点并不存在于编译后的代码中。无需添加任何定义，Debug 消息在 Unity 编辑器和开发版本中仍会启用。这也是为什么 `[SessionMetrics]` 带有 Debug 标记的行以及 `[ClientLatency]` 条目（本页稍后会进一步介绍）只会在编辑器和开发版本中显示。
{% endhint %}

若要在生产版本中启用 Debug 消息，请将 `CONVAI_DEBUG_LOGGING` 添加到 **编辑 → 项目设置 → Player → 脚本定义符号**.

#### 日志类别覆盖

类别覆盖功能可让你提高某个子系统的日志详细程度，而不会让其他子系统的输出淹没控制台。例如，若要排查传输问题，同时不显示音频、界面和角色日志：

1. 打开 **诊断** 并展开 **类别覆盖** 折叠面板 — 其中列出所有日志类别，每个类别旁都有一个下拉菜单，默认值为 `Inherit`
2. 将 `Transport` 下拉菜单设为 `Debug`

其他类别仍采用全局级别。折叠面板标题会显示当前覆盖项数量，例如 **类别覆盖 (1)**。将某个类别的下拉菜单重新设为 `Inherit` 即可移除该覆盖项。

#### 日志类别参考

| 类别             | 涵盖的子系统                         |
| -------------- | ------------------------------ |
| `SDK`          | 常规 SDK 操作和初始化                  |
| `Character`    | 角色和 NPC 生命周期                   |
| `Audio`        | 音频输出和麦克风输入                     |
| `UI`           | 转录 UI 和通知组件                    |
| `REST`         | 对 Convai 的 REST API 调用         |
| `Transport`    | LiveKit 和 WebRTC 传输层           |
| `Events`       | 事件中继系统（会话、角色、转录事件）             |
| `Player`       | 玩家身份和输入                        |
| `Editor`       | 仅限编辑器使用的工具和验证器                 |
| `Vision`       | 摄像头采集和视频发布                     |
| `Bootstrap`    | SDK 初始化和 ConvaiSettings 加载     |
| `Transcript`   | 转录处理和路由                        |
| `Narrative`    | 叙事设计和故事触发系统                    |
| `LipSync`      | 口型同步处理和混合形状播放                  |
| `Animation`    | 身体动画系统（图层、过渡、移动）               |
| `Gaze`         | 注视系统（目标选择、策略、眼部/头部/身体求解器）      |
| `BodyLanguage` | 肢体语言系统（手势、姿势、呼吸、小动作）           |
| `Actions`      | 动作系统：收到哪些命令、哪些被丢弃及其原因，以及目标如何解析 |

#### 自定义日志接收器

通过实现 `ILogSink` 并将其注册到 `ConvaiLogger`.

`ILogSink` 需要实现以下成员：

| 成员                              | 说明                       |
| ------------------------------- | ------------------------ |
| `string Name { get; }`          | 在诊断信息中显示的接收器标识符          |
| `bool IsEnabled { get; }`       | 返回 `false` 以暂停接收器，而不取消注册 |
| `void SetEnabled(bool enabled)` | 在运行时切换接收器的启用状态           |
| `void Write(LogEntry entry)`    | 对每条通过级别筛选的日志条目调用         |
| `void Flush()`                  | 刷新所有缓冲条目——应用程序关闭前调用      |
| `void Dispose()`                | 移除接收器时清理资源               |

{% code title="FileLogSink.cs" %}

```csharp
using System.IO;
using Convai.Domain.Logging;

public class FileLogSink : ILogSink
{
    private readonly string _path;
    private bool _enabled = true;

    public FileLogSink(string path) => _path = path;

    public string Name => "FileLogSink";
    public bool IsEnabled => _enabled;
    public void SetEnabled(bool enabled) => _enabled = enabled;

    public void Write(LogEntry entry)
    {
        string line = $"[{entry.Level}][{entry.Category}] {entry.Message}";
        File.AppendAllText(_path, line + "\n");
    }

    public void Flush() { }
    public void Dispose() { }
}
```

{% endcode %}

尽早注册日志接收器——在 `Awake()` 或 `[RuntimeInitializeOnLoadMethod]` 回调中——并确保在任何 Convai 组件激活之前完成。 `ConvaiLogger` 会在首次使用时自动初始化；初始化后注册的日志接收器只能收到后续消息。

```csharp
// Register once before any Convai component activates
private void Awake()
{
    ConvaiLogger.RegisterSink(new FileLogSink(Application.persistentDataPath + "/sdk.log"));
}
```

不再需要时，移除日志接收器：

```csharp
ConvaiLogger.UnregisterSink(mySink);
```

`ConvaiLogger.SinkCount` 返回当前已注册日志接收器的数量。默认的 Unity Console 日志接收器（`UnityConsoleSink`）始终处于注册状态，无法通过公共 API 移除。

### ConvaiActionDebugProbe

`ConvaiActionDebugProbe` 是 Actions 功能的主要诊断工具。它会订阅每个调度器事件，并在 Inspector 中直接显示实时计数器和最近一次记录的动作数据——无需自定义日志记录。该组件在 Add Component 菜单中的条目为 **Convai/Actions/Diagnostics/Convai Action Monitor**；其 Inspector 标题为 **Action Monitor**.

**添加方式：** Add Component → **Convai/Actions/Diagnostics/Convai Action Monitor**

该组件要求同一个 GameObject 上存在 `ConvaiCharacter` ，并会自动解析 `ConvaiActionDispatcher`。如果 `ConvaiActionDispatcher` 不存在，探针仍会通过 `ConvaiCharacter.OnActionsReceived`记录收到的动作批次，但不会跟踪调度器生命周期事件（步骤开始、成功、失败）。

#### Inspector 字段

| 字段           | 说明                                                 |
| ------------ | -------------------------------------------------- |
| **输出到控制台**   | 启用后，每个动作事件都会连同完整详情一起输出到 Console。为避免日志过多，请在生产环境中禁用。 |
| **已接收批次数**   | 自 Play 开始以来收到的动作批次总数                               |
| **已启动步骤数**   | 调度器已开始执行的步骤总数                                      |
| **成功步骤数**    | 成功完成的步骤总数： `Succeeded`                             |
| **失败步骤数**    | 返回以下结果的步骤总数： `Failed`, `TimedOut`，或者缺少定义或目标的步骤数    |
| **未处理步骤数**   | 执行器返回以下结果的步骤总数： `Unhandled`                        |
| **中止批次数**    | 提前停止的批次总数（Stop Batch 失败策略）                         |
| **最近收到的批次**  | 从 Convai 收到的最新批次的 JSON                             |
| **最近启动的步骤**  | 最近启动步骤的详细信息                                        |
| **最近成功的步骤**  | 最近成功步骤的详细信息                                        |
| **最近未处理的步骤** | 最近未处理步骤的详细信息                                       |

#### 上下文菜单操作

在 Inspector 中右键单击 `ConvaiActionDebugProbe` 组件标题栏，即可访问：

| 项目         | 功能                                                                                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **注入测试批次** | 发送一个 `Move To` 操作，目标为第一个已注册对象——无需实时对话即可验证执行器连线是否正常。如果操作成功，则说明操作定义、对象目标和执行器均已正确配置；如果 `Unhandled Step Count` 增加而非 `Succeeded Step Count`，则此 GameObject 上未注册 `Move To` 的执行器。 |
| **重置探针状态** | 重置所有计数器并清除最近记录的文本字段                                                                                                                                                       |

### ConvaiRoomManager 运行时状态

`ConvaiRoomManager` 将诊断状态作为普通属性公开，无需订阅事件。可从任意脚本、编辑器中的 `[ContextMenu]` 方法或场景内调试面板读取这些属性。

#### 公共状态属性

| 属性                        | 类型             | 说明                                                                                          |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `CurrentState`            | `SessionState` | 活动会话状态： `Disconnected`, `Connecting`, `Connected`, `Disconnecting`, `Reconnecting`, `Error` |
| `IsConnected`             | `bool`         | `true` 当房间处于活动连接状态时                                                                         |
| `ConnectAttemptCount`     | `int`          | 自场景加载以来的连接尝试总次数                                                                             |
| `ReconnectCount`          | `int`          | 自场景加载以来的重新连接尝试总次数                                                                           |
| `LastSessionErrorCode`    | `string`       | 最近一次错误事件的错误代码                                                                               |
| `LastSessionErrorMessage` | `string`       | 最近一次错误的人类可读消息                                                                               |

{% hint style="warning" %}
`SessionState.Error` 表示会话发生了不可恢复的故障。处于此状态时，房间不会自动重新连接。调用 `DisconnectAsync()` 然后调用 `ConnectAsync()` 以重置会话。
{% endhint %}

#### IRoomDiagnostics 完整快照

如需更丰富的快照，请在 `GetDiagnostics()` 上调用 `ConvaiRoomManager.DiagnosticsCoordinator`。此方法会返回一个 `RoomDiagnosticsSnapshot` 其中包含自诊断实例创建以来累计的连接统计信息。 `DiagnosticsCoordinator` 在房间的内部程序集创建之前为 `null` ；内部程序集会在首次连接尝试时创建。因此，调用前请进行 null 检查。 `GetDiagnostics()`.

```csharp
var room = FindFirstObjectByType<ConvaiRoomManager>();
if (room?.DiagnosticsCoordinator != null)
{
    RoomDiagnosticsSnapshot snap = room.DiagnosticsCoordinator.GetDiagnostics();
    Debug.Log($"State:          {snap.CurrentState}");
    Debug.Log($"Connections:    {snap.SuccessfulConnections} / {snap.TotalConnectionAttempts} succeeded");
    Debug.Log($"Failed:         {snap.FailedConnections}");
    Debug.Log($"Total errors:   {snap.TotalErrors}");
    Debug.Log($"Last connected: {snap.LastConnectedAt}");
    Debug.Log($"Last error:     {snap.LastErrorCode} at {snap.LastErrorAt}");
    Debug.Log($"Uptime:         {snap.SessionUptime}");
    Debug.Log($"Characters:     {snap.RegisteredCharacterCount}");
    Debug.Log($"Players:        {snap.RegisteredPlayerCount}");
}
```

#### RoomDiagnosticsSnapshot 字段参考

| 字段                         | 类型          | 说明                                |
| -------------------------- | ----------- | --------------------------------- |
| `CurrentState`             | `string`    | 获取快照时的状态名称                        |
| `TotalConnectionAttempts`  | `int`       | 自启动或上次重置以来的所有连接尝试                 |
| `SuccessfulConnections`    | `int`       | 已达到 Connected 状态的尝试次数             |
| `FailedConnections`        | `int`       | 以失败告终的尝试次数                        |
| `TotalErrors`              | `int`       | 记录的错误总数                           |
| `LastConnectedAt`          | `DateTime?` | 上次成功连接的 UTC 时间戳； `null` 从未连接时     |
| `LastErrorAt`              | `DateTime?` | 上次记录错误的 UTC 时间戳； `null` 无错误时      |
| `LastErrorCode`            | `string`    | 上次错误的错误代码                         |
| `LastErrorMessage`         | `string`    | 上次错误的人类可读消息                       |
| `SessionUptime`            | `TimeSpan?` | 自当前会话连接以来经过的时间； `null` 断开连接时      |
| `RegisteredCharacterCount` | `int`       | `ConvaiCharacter` 当前在代理注册表中注册的实例数 |
| `RegisteredPlayerCount`    | `int`       | `ConvaiPlayer` 当前注册的实例数           |

### 会话指标控制台消息

`SessionMetrics` 会将会话生命周期事件记录到控制台。标记为 Debug 的消息遵循与其他所有 Debug 级别日志调用相同的条件编译规则——请参阅上方的 [日志级别](#log-levels) 提示。

SDK 的日志记录器会自动在每条控制台条目前加上前缀 `[SourceFileName]`，该前缀取自记录日志的源文件。以下消息是前缀之后的消息正文——请在控制台中搜索消息文本，而不是整行内容。

| 消息                                                                        | 级别 | 出现时机                                                              |
| ------------------------------------------------------------------------- | -- | ----------------------------------------------------------------- |
| `[SessionMetrics] Metrics reset`                                          | 调试 | 指标已通过程序重置                                                         |
| `[SessionMetrics] Session started`                                        | 调试 | 开始初始连接尝试（房间状态从 Disconnected 转为 Connecting）                        |
| `[SessionMetrics] Connected - starting duration timer`                    | 调试 | 初始连接进入 Connected 状态；会话运行时间计时器启动（重连时则会触发“Reconnection successful”） |
| `[SessionMetrics] Reconnection attempt #N`                                | 调试 | 每次开始重连尝试时                                                         |
| `[SessionMetrics] Reconnection successful (attempt #N, success rate: P%)` | 信息 | 重连尝试成功                                                            |
| `[SessionMetrics] Reconnection failed (error: X)`                         | 警告 | 重连尝试失败                                                            |
| `[SessionMetrics] Session error: X`                                       | 警告 | 记录了非重连类会话错误                                                       |
| `[SessionMetrics] Session ended (reason): {snapshot}`                     | 信息 | 会话因任何原因终止；快照包含完整指标                                                |

### 客户端延迟指标

`ClientLatencyMetricsCollector` 用于测量对话流水线的端到端延迟：从玩家停止说话，到角色开始播放音频。它在 Unity Editor 和 Development Builds 中启用，适用范围与本页上的其他 Debug 级诊断信息相同。

每轮对话完成后，延迟条目会自动显示在 Console 中：

```
[ClientLatency] Player: stop→finalTranscript=120ms | Character: stop→firstTranscript=450ms stop→ttsStarted=520ms stop→firstLipSync=600ms stop→audioPlaying=650ms (audioHoldForLipSync=130ms)
```

日志记录器会自动添加 `[SourceFileName]` 前缀，因此 Console 中显示的条目也会带有此前缀： `[ClientLatencyMetricsCollector] [ClientLatency] ...` — 搜索 `[ClientLatency]` 即可找到该条目。

#### 延迟阶段参考

| 阶段                     | 测量内容                                |
| ---------------------- | ----------------------------------- |
| `stop→finalTranscript` | 从玩家停止说话，到客户端收到玩家的最终转录文本             |
| `stop→firstTranscript` | 从玩家停止说话，到收到角色的第一个转录文本词元             |
| `stop→ttsStarted`      | 从玩家停止说话，到 Convai 开始文本转语音合成          |
| `stop→firstLipSync`    | 从玩家停止说话，到收到第一帧口型同步数据                |
| `stop→audioPlaying`    | 从玩家停止说话，到角色音频通过 `AudioSource`       |
| `audioHoldForLipSync`  | TTS 开始到音频播放之间的时间差——即播放开始前音频缓冲区的填充时长 |

#### 解读数值

| 阶段数值偏高                                       | 可能原因                        |
| -------------------------------------------- | --------------------------- |
| `stop→firstTranscript` > 500 ms              | 到 Convai 的网络延迟；请检查连接质量      |
| `stop→ttsStarted` 远高于 `stop→firstTranscript` | Convai 处理时间；对于复杂回复，这是预期现象   |
| `audioHoldForLipSync` > 200 ms               | 音频缓冲区较大；尚可接受，但会降低用户感知到的响应速度 |
| `stop→audioPlaying` > 1000 ms                | 网络延迟、处理时间和缓冲时间的总和；请逐一检查各阶段  |

### 口型同步偏差监视器

不支持注入自定义运行时接收器——SDK 没有公开的扩展接口。请改为通过 `ConvaiLipSyncComponent` 上受支持的映射或配置文件来驱动口型同步。相关类型包括 `SkinnedMeshBlendshapeSink`, `LipSyncDriftMonitor`, `LipSyncDriftSample`和 `LipSyncDriftEvent` 虽然存在于 SDK 中，但属于内部内容，不是公共 API 的一部分。

要打开漂移监视器，请在角色的 `ConvaiLipSyncComponent` 检查器中选择 **打开漂移监视器** （位于延迟设置附近）。打开的窗口标题为 **唇形同步漂移**.

监视功能默认关闭：启用 **监视** 开关，进入播放模式，然后与角色对话以填充数据。如果注册了多个角色，请从下拉菜单中选择一个角色——样本和事件按角色分别跟踪。

窗口显示：

* 测得的音频播放头与视觉（混合形状）时钟之间的实时漂移误差（毫秒）；正值表示嘴部动作落后于音频
* 绘制漂移误差和监视器累计校正量的图表，时间窗口可配置为 3–30 秒，并叠加生命周期事件标记
* 可见时间窗口内计算出的平均绝对误差、最大绝对误差和校正率
* 实时音频/视觉偏移覆盖滑块，可通过目测校准感知到的同步效果
* 事件日志，列出带时间戳的生命周期事件（例如门控开启、锚定、取消）

点击 **导出 CSV** 将当前样本和事件保存到文件。保存对话框标题为 **导出漂移样本**，默认文件名为 `lipsync-drift-<characterId>.csv`。导出的文件包含一个样本表，列名为 `time_s`, `error_ms`, `audio_target_s`, `visual_clock_s`, `cumulative_correction_ms`, `buffered_s`, `headroom_s`, `state`和 `audio_active`，之后是一个空行，再后面是一个事件表，列名为 `event_time_s` 和 `label`.

### 快速参考

| 工具                                                  | 诊断内容                     | 访问方式                                                                              |
| --------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| **Convai 故障排除工具**                                   | 针对单个角色或整个场景的跨模块分析结果及修复建议 | `Convai → 故障排除工具`                                                                 |
| **动作编辑器（实时）**                                       | 播放模式下的动作批次、目标注册表和各动作洞察   | `Convai → Actions Editor`                                                         |
| **具身 / 注视 / 身体动画 / 情绪编辑器**                          | 各具身模块的设置和调优              | `Convai → 具身编辑器`, `Convai → 注视编辑器`, `Convai → 身体动画编辑器`, `Convai → Emotion Editor` |
| **诊断**                                              | 所有 SDK 子系统——日志详细程度和筛选    | `Convai → Settings` 或 `Edit → Project Settings → Convai SDK` （诊断部分）               |
| **Convai Action Monitor（`ConvaiActionDebugProbe`)** | Action 分发、执行器连接、批处理失败    | Add Component → Convai/Actions/Diagnostics/Convai Action Monitor                  |
| **ConvaiRoomManager 属性**                            | 会话状态、错误代码、连接/重新连接次数      | `FindFirstObjectByType<ConvaiRoomManager>()` — 直接读取属性                             |
| **IRoomDiagnostics 快照**                             | 连接尝试次数、运行时间、上次错误、代理数量    | `room.DiagnosticsCoordinator.GetDiagnostics()`                                    |
| **Session Metrics 消息**                              | 重新连接成功率、会话生命周期、错误时间线     | 控制台筛选器 `[SessionMetrics]`；需要 Info 或 Debug 级别                                      |
| **Client Latency 指标**                               | 端到端对话管线延迟                | 控制台筛选器 `[ClientLatency]`；仅适用于编辑器和开发版本                                             |
| **LipSync Drift Monitor**                           | 音频与视觉口型同步情况、漂移误差、CSV 导出  | `ConvaiLipSyncComponent` 检查器 → **打开 Drift Monitor**                               |
| **自定义日志接收器**                                        | 将日志输出到文件、遥测系统或叠加层        | `ConvaiLogger.RegisterSink(new YourSink())`                                       |

### 后续步骤

如需解决特定平台问题——例如 WebGL AudioContext 解锁、Android 麦克风处理或平台构建设置——请参阅“平台指南”部分。

{% content-ref url="/pages/c548f38700d19163b7037cf3152f210077f0967b" %}
[平台指南](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides.md)
{% endcontent-ref %}

如需使用特定功能的诊断工具，请参阅该功能部分中的故障排除页面。Actions、Emotion、Vision 和 Narrative Design 功能均提供了详细的决策树和控制台日志参考，内容超出本文档所述范围。


---

# 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/debug-tools-reference.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.
