> 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/features/character-actions/debugging-and-troubleshooting.md).

# 排查角色动作问题

从……开始 **Convai > 故障排查工具** ——它会检查角色的动作设置，并准确列出需要修复的内容，其中大多数问题都支持一键修复。若要查看场景播放时的运行时行为，请添加 `ConvaiActionDebugProbe` 到 NPC 的 `GameObject` ，并在播放模式下观察其计数器更新。若要手动测试动作和运行时更新的线协议，请打开 **Convai > 动作编辑器** 并切换到其实时模式。本页涵盖这三种工具、诊断清单以及常见故障的完整排查表。

### 使用 Convai 疑难解答工具检查动作设置

`Convai > 故障排查工具` 会打开 Convai 疑难解答工具，这是所有 Convai 模块都会向其报告结果的共享窗口。Actions 是每个角色都具备的模块：即使是刚刚接入的 `ConvaiCharacter` 、没有其他模块的角色，也会显示一行 Actions，因为 Actions 适用于每个角色，而不是可选启用。请先从这里开始，再看下面的运行时工具——大多数动作失败都是设置问题，疑难解答工具会在你进入播放模式之前就捕获到。

该窗口会载入你当前选中的角色，或者列出场景中每一个 `ConvaiCharacter` ，位于 **本场景** 模式中。它也可以直接打开，并且已经聚焦在 Actions 行上——可从 Actions 编辑器和 `ConvaiActionConfigSource`自身的检查器中打开——在这两种情况下，它都是同一个窗口、同一套检查，而不是单独的工具。有关疑难解答工具如何与全场景验证器协同工作，请参见 [验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md) 。

每条发现都有严重级别——错误、警告、信息或正常——、标题和消息。可以自动修复的发现会显示修复按钮；关于“已编写内容”（而不是场景对象）的发现会显示一个 **打开** 按钮，点击后会跳转到 Actions 编辑器中对应的具体动作。使用 **重新检查** 在做出更改后，或 **修复所有可修复项** 一次性应用所有一键修复。

常见发现：

| 标题               | 消息                                                            | 含义                                                              |
| ---------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| 已启用 Actions      | `这个角色还不能承载任何动作。`                                              | 没有 `ConvaiActionConfigSource` 在角色上——添加一个，或者让修复按钮帮你添加。           |
| 正在运行 Actions     | `没有任何内容被设置为运行动作，因此这个角色永远不会执行任何被要求的操作。`                        | 没有 `ConvaiActionDispatcher` 在角色上（并且该角色也未在自定义代码中声明为正在运行动作）。      |
| 已编写的动作           | `还没有设置任何动作。打开 Convai > Actions 编辑器，并使用“+ 添加动作”来编写你的第一个动作。`    | `ConvaiActionConfigSource` 还没有动作定义。这只是信息提示，不是错误——角色会说话，但不会执行动作。 |
| 动作行为 — “\<name>” | `该动作还未选择任何行为，而且也没有任何内容会自动建议一个。在 Actions 编辑器中选择一个之前，这个动作不会运行。` | 该动作定义没有绑定执行器。请在 Actions 编辑器中打开该动作并选择一个行为。                       |
| 动作行为 — “\<name>” | `该动作已设置为使用 <behavior>，但这个角色还没有它。`                             | 该动作命名了一个真实的执行器类型，但该角色没有那个组件。使用修复按钮添加它。                          |

这还不是完整的发现集合——疑难解答工具还会报告目标关联、行为宿主、动作反馈，以及所需的同伴或目标组件。请参见 [故障排除](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting.md) ，了解 SDK 范围内的排查中心，其中包括 Actions 之外的故障类别。

### ConvaiActionDebugProbe（动作监视器）

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `添加组件 → Convai → 动作 → 诊断 → Convai 动作监视器`

约束： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

该探针会自动解析 `ConvaiCharacter` 和 `ConvaiActionDispatcher` 来自同一个 `GameObject`。其检查器标题为 **动作监视器**：在编辑模式下，它会提示你进入播放模式；在播放模式下，它会显示一个 **活动** 区域，仅列出至少触发过一次的事件类别，每个都显示为 `#<count> <category>` ，其下方显示最近的详细文本，并带有 **清除** 和 **复制** 按钮。

#### Inspector 字段

| 字段                      | 类型                       | 描述                                  |
| ----------------------- | ------------------------ | ----------------------------------- |
| `_character`            | `ConvaiCharacter`        | 已自动解析。跟踪来自 Convai 的原始动作批次。          |
| `_dispatcher`           | `ConvaiActionDispatcher` | 已自动解析。跟踪执行生命周期事件。                   |
| `_logToConsole`         | `bool`                   | 启用后，每条记录到的事件也会打印到控制台。关闭可减少测试时的输出噪音。 |
| `_receivedBatchCount`   | `int`                    | 通过 `OnActionsReceived`.             |
| `_startedStepCount`     | `int`                    | 调度器已开始执行的步骤总数。                      |
| `_succeededStepCount`   | `int`                    | 返回 `Succeeded`.                     |
| `_failedStepCount`      | `int`                    | 返回 `Failed`.                        |
| `_unhandledStepCount`   | `int`                    | 返回 `Unhandled`.                     |
| `_completedStepCount`   | `int`                    | 已完成的步骤总数，无论成功与否——会与上方某个计数器一起触发。     |
| `_abortedBatchCount`    | `int`                    | 被 `StopBatch` 失败策略提前中止的批次数。         |
| `_lastReceivedBatch`    | `string`                 | 最近一次接收到的批次的 JSON。                   |
| `_lastStepStarted`      | `string`                 | 最近一次开始步骤的摘要。                        |
| `_lastStepSucceeded`    | `string`                 | 最近一次成功步骤的摘要。                        |
| `_lastUnhandledStep`    | `string`                 | 最近一次未处理步骤的摘要。                       |
| `_lastFailedStepDetail` | `string`                 | 最近一次失败步骤的摘要。                        |
| `_lastStepCompleted`    | `string`                 | 最近一次完成步骤的摘要，无论结果如何。                 |
| `_lastFailureReason`    | `string`                 | 最近一次完成步骤的报告中的失败消息（如果失败）。            |

该探针只保留每个事件类别最近发生的一次记录，并持续维护一个计数——它是按类别划分的“最新已知状态”视图，而不是按时间顺序排列的日志。若要从代码中注入测试批次或重置探针，请调用其公开的 `InjectTestBatch()` 或 `ResetProbeState()` 方法；若要以交互方式注入，请使用下方描述的 Actions 编辑器实时模式。

#### 控制台日志格式

当 `_logToConsole` 已启用时，探针会以以下格式写入控制台：

```
[ConvaiActionDebugProbe] 收到动作批次 #1: [{"name":"Move To","target":"Extinguisher"}]
[ConvaiActionDebugProbe] 调度器批次已开始。
[ConvaiActionDebugProbe] 步骤已开始 #1: cmd='Move To Extinguisher', def='Move To', target=Object:Extinguisher
[ConvaiActionDebugProbe] 步骤成功 #1: cmd='Move To Extinguisher', def='Move To', target=Object:Extinguisher
[ConvaiActionDebugProbe] 调度器批次已完成。
```

对于失败情况：

```
[ConvaiActionDebugProbe] 步骤失败 #1: cmd='Move To Cupboard', def='<unresolved>', target=None:<none>
[ConvaiActionDebugProbe] 调度器批次已中止 #1。
```

### 在 Actions 编辑器中测试动作

`编辑器窗口` — `Convai.Editor.Actions`

菜单路径： `Convai → Actions Editor`

Actions 编辑器的实时模式现在负责注入命令、测试目标解析以及编写运行时动作配置补丁——此前独立的 Action Debug Window 自 `4.5.0`起已不再提供。切换到实时模式，选择一个角色，然后打开 **高级** 组即可看到三个卡片：

**发送原始命令** 会直接将一条动作命令发送给调度器，完全绕过对话——这与 Convai 中真实命令所走的调度路径相同，因此时序、策略和事件的行为都完全一致。输入一个 **动作名称** 以及可选的 **目标 / 参数**粘贴你的密钥，然后选择 **发送**，或者选择 **发送给第一个已知对象** ，将其指向角色已知对象列表中的第一项。每个已编写的动作也都有自己的单击按钮。如果项目注册了一个 `IConvaiActionDebugPresetProvider`，其模板和命名注入预设也会显示在这里。

**测试目标解析** 会检查一段文本会解析到哪个目标，而不会发送动作——在 **目标文本** 并选择 **Resolve**中输入。打开调试详细级别的控制台，查看哪个匹配步骤（精确名称、别名、规范化文本、部分匹配或最近匹配）找到了结果。

**运行时会话状态与补丁编写器** 仅在播放模式下可用，前提是角色已连接。在播放模式之外，它会提示你进入播放模式。运行后，它会显示 Convai 已为该角色确认的动作、对象、角色和注意力，以及每个待处理的运行时更新及其确认状态。其下方的编写器会构建一个 `ConvaiActionConfigPatch`: **加载已确认** 会将角色当前已确认的配置加载到草稿中，并勾选所有字段， **重置草稿** 会清空它， **预览** 会在不发送任何内容的情况下在本地验证草稿，并且 **发送补丁** 会发送它——仅当角色已连接且至少包含一个字段时才会启用。请参见 [在运行时更新角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md) ，了解完整的确认模型。

运行时动作状态由后端确认：更新会一直保持待处理状态，直到 Convai 返回确认；成功的确认会按发送顺序提交。错误状态、格式错误或不匹配的确认元数据，或 30 秒超时，都会丢弃待处理的修改且不会重试，控制台会记录 `运行时操作变更已丢弃 update_id=<id> reason=<reasonCode>` (`ConvaiCharacter.DynamicContext.cs:669`）。断开连接也会丢弃任何待处理的修改且不会重试，但会静默处理——不会记录此消息。若确认中的 action-generation-strategy 状态为 `requires_reconnect`，控制台还会记录 `运行时动作更新 ACK 需要重新连接；未执行自动重连（update_id=<id>）` (`ConvaiCharacter.DynamicContext.cs:628`）——SDK 会暴露此状态，但不会自动重连。

### 诊断清单

当动作未执行时，请按此清单顺序排查：

{% stepper %}
{% step %}

#### 先检查 Convai 疑难解答工具

打开 **Convai > 故障排查工具** ，并选中角色。如果它报告 Actions 错误，请先修复，再继续往下看——此清单中其余大部分步骤，本来就是疑难解答工具已经在帮你检查的内容。
{% endstep %}

{% step %}

#### 验证 Convai 是否正在发送动作

检查 `_receivedBatchCount` ，在播放模式下说出命令后，观察探针检查器中的活动区域。

* **计数器增加** → Convai 返回了一个动作批次；继续下一步。
* **计数器保持为 0** → Convai 没有返回动作响应。可能原因：
  * `ConvaiActionConfigSource` 没有动作定义（Convai 不知道有可用动作）
  * 该角色未配置为为此角色 ID 返回动作
  * 会话未成功连接
    {% endstep %}

{% step %}

#### 验证调度器是否正在处理该批次

如果 `_receivedBatchCount` 增加但 `_startedStepCount` 保持为 0：

* `ConvaiActionDispatcher` 可能在 NPC 的 `GameObject`
* 请确认调度器位于 **同一个 `GameObject`** 处于同一 `ConvaiCharacter`
* 在检查器中验证调度器组件已启用（组件名称旁边的复选框）
  {% endstep %}

{% step %}

#### 读取步骤失败消息

如果 `_failedStepCount` 增加时，请检查活动区域中的 **步骤失败** 行，或查看控制台中的失败消息。调度器会记录确切原因：

| 控制台消息                                             | 原因                            |
| ------------------------------------------------- | ----------------------------- |
| `未找到动作 'X' 的本地动作定义。`                              | 动作名称不匹配——见下一步                 |
| `动作 'X' 没有绑定任何动作行为。`                              | 执行器字段为空——请分配执行器组件             |
| `动作 'X' 的目标 'Y' 需要 <Requirement>，但解析得到的是 <Kind>。` | Convai 发送了一个与任何已注册对象都不匹配的目标名称 |
| {% endstep %}                                     |                               |

{% step %}

#### 检查动作名称是否不匹配

动作名称的匹配是 **不区分大小写的** 但 **空格具有意义**. `Move To` 和 `move to` 能匹配。 `Move To` 和 `MoveTo` 不能。

在 `_lastReceivedBatch`，找到 Convai 发出的确切名称。将它与 `ActionName` 中的 `ConvaiActionConfigSource`字段进行比较。它们必须逐字符匹配（忽略大小写）。
{% endstep %}

{% step %}

#### 验证组件引用

在 `ConvaiActionConfigSource`，展开每个 **动作定义** 条目：

* **执行器字段为空** → 步骤失败，并提示“没有绑定任何动作行为。” 将执行器组件引用拖到 Executor 字段中。
* **执行器未实现 `IConvaiActionExecutor`** → 步骤失败。自定义执行器必须实现该接口。
  {% endstep %}

{% step %}

#### 使用原始命令测试

打开 **Convai → Actions Editor**，切换到 **Live** 模式，打开 **高级**，并使用 **发送原始命令** （或选择某个已编写动作的一键按钮）。这会直接把命令提交给调度器，绕过 Convai。

* **步骤成功** → 流水线工作正常；问题在于 Convai 返回动作的方式，而不是你的 Unity 设置。
* **步骤失败** → 问题出在本地组件配置（执行器、NavMesh、缺失引用）。

选择 **清除** 在测试运行之间清空 Action Monitor，以保持其活动区域清晰易读。
{% endstep %}
{% endstepper %}

### 故障排查表

| 症状                                                                       | 可能原因                                                | 修复方法                                                                                           | 验证                                                              |
| ------------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Convai 疑难解答工具报告 `这个角色还不能承载任何动作。`                                         | 没有 `ConvaiActionConfigSource` 在角色上                  | 使用该发现项的修复按钮，或手动添加 `ConvaiActionConfigSource` 到角色上                                              | 在疑难解答工具中重新检查；Actions Enabled 行会变为 `此角色上的 Actions 已启用。`          |
| Convai 疑难解答工具报告 `没有任何内容被设置为运行动作，因此这个角色永远不会执行任何被要求的操作。`                   | 没有 `ConvaiActionDispatcher` 在角色上                    | 使用该发现项的修复按钮，或手动添加 `ConvaiActionDispatcher` 到同一个 `GameObject`                                   | 在疑难解答工具中重新检查；Running Actions 行会变为 `该角色已设置为运行动作。`                |
| `_receivedBatchCount` 在说话后仍保持为 0                                         | `ConvaiActionConfigSource` 缺失或没有动作定义                | 添加 `ConvaiActionConfigSource` 并至少包含一个动作定义；Convai 只有在知道已配置动作时才会返回动作                             | 再说一次； `_receivedBatchCount` 增加                                  |
| `_receivedBatchCount` 增加但 `_startedStepCount` 保持为 0                      | `ConvaiActionDispatcher` 缺失、被禁用，或位于错误的 `GameObject` | 将调度器添加到同一个 `GameObject` 处于同一 `ConvaiCharacter`；确认它已启用                                          | `_startedStepCount` 在下一批次增加                                     |
| `_failedStepCount` 增加： `未找到动作 'X' 的本地动作定义。`                              | Convai 发送的动作名称与任何 `ActionName` 本地定义中的               | 打开 `_lastReceivedBatch` 以查看确切名称；在 `ConvaiActionConfigSource`                                   | 中将其匹配（不区分大小写，但空格有意义） `_startedStepCount` 而不是 `_failedStepCount` |
| `_failedStepCount` 增加： `动作 'X' 没有绑定任何动作行为。`                              | `Executor` 中的 `ConvaiActionDefinition` 为空           | 将执行器组件引用拖入 `Executor` 中的 `ConvaiActionConfigSource`，或使用 Convai 疑难解答工具中的动作行为修复按钮                | 步骤到达 `_startedStepCount` ，并且执行器的行为开始运行                          |
| 某个 `ConvaiUnityEventActionExecutor` 动作从未触发其监听器                           | 执行器的 `UnityEvent` 在检查器中没有接好任何持久化监听器                 | 在执行器的 `UnityEvent` 字段上接好一个监听器；Convai 的 MCP 动作诊断工具会将其标记为 `ACTION_EVENT_UNWIRED`                 | 下次动作执行时，已接线的监听器就会运行                                             |
| `_failedStepCount` 增加： `动作 'X' 的目标 'Y' 需要 <Requirement>，但解析得到的是 <Kind>。` | 来自 Convai 的目标名称与任何已注册对象或角色都不匹配                      | 打开 `_lastReceivedBatch` 以查看目标名称；确认它匹配 `Name` 中的一项 **可行动对象** 或 **可行动角色** （不区分大小写）               | 步骤解析目标并 `_startedStepCount` 增加                                  |
| `_unhandledStepCount` 增加                                                 | 执行器返回 `Unhandled` ——执行器拒绝处理此调用                      | 检查执行器逻辑； `Unhandled` 这表示执行器选择不运行，而不是出了故障                                                       | 执行器返回 `Succeeded`, `Answered`，或 `Failed` ，待逻辑修正后再试              |
| `_abortedBatchCount` 增加                                                  | 某个步骤失败，且 `StopBatch` 策略中止了剩余步骤                      | 修复失败的步骤（见上文），或更改 `FailurePolicy` 到 `ContinueBatch` ，如果步骤彼此独立                                   | `OnBatchCompleted` 触发而不是 `OnBatchAborted` 在下一批次中                |
| NPC 会传送而不是导航移动                                                           | 正在使用基于自定义变换的移动执行器                                   | 使用 `ConvaiNavMeshLocomotion`驱动的移动方式，或一个尊重你的移动系统的自定义执行器                                         | NPC 会平滑地移动到目标，而不是直接跳到目标处                                        |
| NPC 开始移动然后冻结                                                             | 移动执行器的 `NavMeshAgent` 卡住了，或者其路径被阻挡了                 | 烘焙 NavMesh（**窗口 → AI → 导航 → 烘焙**）；确认 NPC 和目标都位于 NavMesh 表面上；在动作定义上设置 `TimeoutSeconds` ，以防止无限阻塞 | NPC 到达目标并且步骤完成，而不是超时                                            |
| 在检查器中已配置，但场景切换后不工作                                                       | 在连接时发送的配置现在已过时                                      | 结束会话并重新连接；动作配置只会在连接时发送一次                                                                       | 新的配置会在重新连接后对请求的动作生效                                             |
| 在编辑器中可用，但在构建中不工作                                                         | 构建中未包含执行器组件                                         | 验证执行器脚本是否位于项目的编译范围内；检查是否存在 `[assembly: ...]` 排除项                                               | 构建版控制台显示相同的 `ConvaiActionDebugProbe` 输出，和编辑器中一样                 |
| `DynamicContext.SetCurrentAttentionObject` 调用没有效果                        | 不在活动会话中，或者对象名称不在活动配置中                               | 仅在 `ConnectAsync` 完成后调用；对象名称必须匹配中已注册的条目 `ConvaiActionConfigSource.Objects`                     | 后续的动作目标解析会反映新的注意对象                                              |
| Actions 编辑器中的待处理运行时更新从未清除                                                | 该更新已被丢弃——ACK 错误、元数据格式错误/不匹配，或 30 秒超时（或者在断开连接时静默丢弃）  | 检查 Console 中的 `运行时动作修改已丢弃 update_id=... reason=...`；已丢弃的更新不会重试，请使用新的更新 ID 重新发送                 | 待处理条目消失，最后一次确认显示新的状态                                            |
| Actions 编辑器中的最后一次动作更新确认显示 `requires_reconnect`                           | Convai 已应用该更改，但动作生成策略需要新会话                          | 结束会话并重新连接；SDK 不会自动重连                                                                           | 重新连接后，最后一次确认会反映重新应用后的状态                                         |
| **发送补丁** 在运行时补丁编写器中保持禁用                                                  | 角色未连接，或者草稿中未包含任何字段                                  | 在会话连接后再发送；发送前至少勾选一个字段                                                                          | 一旦连接并且至少包含一个字段，该按钮就会启用                                          |

### 下一步

{% content-ref url="/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a" %}
[在运行时更新角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md)
{% endcontent-ref %}

{% content-ref url="/pages/0341126fa4c492311dab4fb6aca6d0c64191016b" %}
[角色动作脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/7905d34249d33be76079e6f5bb2876a37dea1fe2" %}
[将动作迁移到 v4.5.0](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/migrate-to-v4-5.md)
{% endcontent-ref %}

{% content-ref url="/pages/21a0b0c11649e9125ef5195167e66c3a2caaadf1" %}
[验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/aed151614a7019028126be07590213a17602a2f2" %}
[故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting.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/features/character-actions/debugging-and-troubleshooting.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.