> 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 Troubleshooter、Action Monitor 以及症状与修复参考，排查角色动作的设置和运行时问题。

从以下位置开始： **Convai > Troubleshooter** ——它会检查角色的动作设置，并准确列出需要修复的内容；对于大多数检查结果，只需单击一次即可修复。若要查看场景运行时的行为，请将 `ConvaiActionDebugProbe` 添加到 NPC 的 `GameObject` 中，然后在播放模式下观察计数器更新。若要手动测试动作和运行时更新线协议，请打开 **Convai > Actions Editor** 并切换到实时模式。本页涵盖这三种工具、诊断清单，以及常见故障的完整排查表。

### 使用 Convai Troubleshooter 检查动作设置

`Convai > Troubleshooter` 会打开 Convai Troubleshooter，这是所有 Convai 模块共用的窗口，各模块都会在其中报告检查结果。Actions 是每个角色都具备的模块：即使是刚刚完成连接的 `ConvaiCharacter` ，即便没有其他模块，也会显示 Actions 行，因为 Actions 适用于所有角色，而非可选模块。请先从这里开始，再使用下面介绍的运行时工具——大多数动作故障都是设置问题，Troubleshooter 能在进入播放模式之前就发现。

打开窗口时会载入当前选中的角色；也可以在 `ConvaiCharacter` 的 **此场景** 模式下列出场景中的所有角色。你也可以从 Actions Editor 或 `ConvaiActionConfigSource`自己的检查器中直接打开此窗口，并自动定位到 Actions 行——这两种方式打开的都是同一个窗口，执行的也是相同检查，并非独立工具。请参阅 [验证设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md) ，了解 Troubleshooter 如何与场景范围的验证器配合使用。

每条检查结果都包含严重级别（错误、警告、信息或正常）、标题和消息。可自动修复的结果会显示修复按钮；关于已创作内容（而非场景对象）的结果会显示一个 **打开** 按钮，点击后会跳转到 Actions Editor 中对应的具体动作。修改后请使用 **重新检查** ，或者使用 **修复所有可修复项** 一次性应用所有一键修复。

常见检查结果：

| 标题               | 消息                                                                  | 含义                                                                |
| ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- |
| 已启用 Actions      | `此角色目前无法持有任何动作。`                                                    | 否 `ConvaiActionConfigSource` 未添加到角色上——请添加一个，或让修复按钮为你添加。           |
| 正在运行 Actions     | `尚未设置任何可运行的动作，因此无论要求此角色做什么，它都不会执行。`                                 | 否 `ConvaiActionDispatcher` 未添加到角色上（且未在自定义代码中声明该角色正在运行 Actions）。   |
| 已创作动作            | `尚未设置任何动作。请打开 Convai > Actions Editor，然后使用“+ Add Action”创作你的第一个动作。` | `ConvaiActionConfigSource` 目前尚无动作定义。这是提示信息，不是错误——该角色仍会对话，但不会执行动作。 |
| 动作行为 — '\<name>' | `尚未为此动作选择行为，也没有任何内容能自动推断出合适的行为。在 Actions Editor 中选择行为之前，此动作不会运行。`   | 此动作定义尚未绑定执行器。请在 Actions Editor 中打开该动作并选择一种行为。                     |
| 动作行为 — '\<name>' | `此动作已设置为使用 <behavior>，但该角色尚未配置此行为。`                                 | 此操作指定了真实存在的执行器类型，但该角色没有此组件。使用修复按钮添加该组件。                           |

这并非完整的发现项列表——故障排查工具还会报告目标关联、行为承载、操作反馈，以及必需的对等组件或目标组件问题。请参阅 [故障排查](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting.md) 了解 SDK 的全面故障排查中心，其中还涵盖 Actions 之外的故障类别。

### ConvaiActionDebugProbe（操作监视器）

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `Add Component → Convai → Actions → Diagnostics → Convai Action Monitor`

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

探针会自动解析 `ConvaiCharacter` 和 `ConvaiActionDispatcher` （它们位于同一个 `GameObject`上）。其 Inspector 标题为 **操作监视器**：在编辑模式下会显示提示，要求进入播放模式；在播放模式下会显示一个 **活动** 部分，其中仅列出至少触发过一次的事件类别，每项的格式为 `#<count> <category>` ，下方显示最近的详细信息文本，此外还有 **清除** 和 **复制** 按钮。

#### Inspector 字段

| 字段                      | 类型                       | 说明                                        |
| ----------------------- | ------------------------ | ----------------------------------------- |
| `_character`            | `ConvaiCharacter`        | 自动解析。跟踪来自 Convai 的原始操作批次。                 |
| `_dispatcher`           | `ConvaiActionDispatcher` | 自动解析。跟踪执行生命周期事件。                          |
| `_logToConsole`         | `bool`                   | 启用后，每个记录的事件也会输出到 Console。关闭此项可在测试时减少日志输出。 |
| `_receivedBatchCount`   | `int`                    | 通过 `OnActionsReceived`.                   |
| `从 Convai 接收的批次数总计`     | `int`                    | \_startedStepCount                        |
| `调度器已开始执行的步骤总数。`        | `int`                    | \_succeededStepCount `返回`.                |
| `Succeeded`             | `int`                    | 成功的步骤总数 `_failedStepCount`.               |
| `返回`                    | `int`                    | 失败的步骤总数 `Failed`.                         |
| `_completedStepCount`   | `int`                    | 已完成的步骤总数，无论成功与否——它会与上述某个计数器同时触发。          |
| `_abortedBatchCount`    | `int`                    | 因以下内容而提前终止的批次数： `StopBatch` 失败策略。         |
| `_lastReceivedBatch`    | `string`                 | 最近收到的批次的 JSON。                            |
| `_lastStepStarted`      | `string`                 | 最近启动步骤的摘要。                                |
| `_lastStepSucceeded`    | `string`                 | 最近成功步骤的摘要。                                |
| `_lastUnhandledStep`    | `string`                 | 最近未处理步骤的摘要。                               |
| `_lastFailedStepDetail` | `string`                 | 最近失败步骤的摘要。                                |
| `_lastStepCompleted`    | `string`                 | 最近完成步骤的摘要，无论结果如何。                         |
| `_lastFailureReason`    | `string`                 | 最近完成步骤的报告中的失败消息（如果该步骤失败）。                 |

探针只保留每种事件类别最近一次的记录以及一个累计计数——这是按类别显示的“最新已知状态”，而不是按时间顺序排列的日志。若要从代码中注入测试批次或重置探针，请调用其公开的 `InjectTestBatch()` 或 `ResetProbeState()` 方法；若要通过交互方式注入，请使用下文介绍的 Actions Editor 的 Live 模式。

#### 控制台日志格式

启用 `_logToConsole` 后，探针会以以下格式向控制台写入日志：

```
[ConvaiActionDebugProbe] Received action batch #1: [{"name":"Move To","target":"Extinguisher"}]
[ConvaiActionDebugProbe] Dispatcher batch started.
[ConvaiActionDebugProbe] Step started #1: cmd='Move To Extinguisher', def='Move To', target=Object:Extinguisher
[ConvaiActionDebugProbe] Step succeeded #1: cmd='Move To Extinguisher', def='Move To', target=Object:Extinguisher
[ConvaiActionDebugProbe] Dispatcher batch completed.
```

发生失败时：

```
[ConvaiActionDebugProbe] Step failed #1: cmd='Move To Cupboard', def='<unresolved>', target=None:<none>
[ConvaiActionDebugProbe] Dispatcher batch aborted #1.
```

### 在 Actions Editor 中测试操作

`EditorWindow` — `Convai.Editor.Actions`

菜单路径： `Convai → Actions Editor`

Actions Editor 的 Live 模式可用于注入命令、测试目标解析，以及编写运行时操作配置补丁。切换到 Live 模式，选择一个角色，然后打开 **高级** 组，即可看到三个卡片：

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

**测试目标解析** 用于检查一段文本会解析到哪个目标，而不会发送动作——在 **目标文本** 中输入内容，然后选择 **解析**。打开“控制台”并将日志级别设为“调试”，即可查看哪个匹配步骤（名称完全匹配、别名、规范化文本、部分匹配或最近似匹配）找到了结果。

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

运行时动作状态由后端确认：更新会一直处于待处理状态，直到 Convai 返回确认；成功的确认会按发送顺序提交。如果状态为错误、确认元数据格式错误或不匹配，或等待超过 30 秒，则会丢弃待处理的变更且不会重试；控制台会记录 `Runtime action mutation discarded update_id=<id> reason=<reasonCode>` (`ConvaiCharacter.DynamicContext.cs:669`）。断开连接也会丢弃所有待处理变更且不会重试，但不会记录任何信息。如果确认中的动作生成策略状态为 `requires_reconnect`，控制台还会记录 `Runtime action update ACK requires reconnect; no automatic reconnect performed (update_id=<id>)` (`ConvaiCharacter.DynamicContext.cs:628`）——SDK 会显示此状态，但不会自动重新连接。

### 诊断检查清单

动作未执行时，请按顺序使用此检查清单：

{% stepper %}
{% step %}

#### 先检查 Convai 故障排除工具

打开 **Convai > 故障排除工具** 并选中角色。如果工具报告 Actions 错误，请先修复再继续——此检查清单中其余大多数步骤，都是故障排除工具已经替你检查的内容。
{% endstep %}

{% step %}

#### 确认 Convai 是否正在发送动作

在播放模式下说出一条命令后，检查探针 Inspector 的 Activity 部分中的 `_receivedBatchCount` 。

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

{% step %}

#### 确认调度器正在处理批次

如果 `_receivedBatchCount` 递增，但 `_startedStepCount` 仍为 0：

* `ConvaiActionDispatcher` 可能缺失，或在 NPC 的 `GameObject`
* 上已禁用。请确认调度器位于与 **相同的 `GameObject`** 上， `ConvaiCharacter`
* 请在 Inspector 中确认调度器组件已启用（组件名称旁的复选框）
  {% endstep %}

{% step %}

#### 查看步骤失败消息

如果 `_failedStepCount` 递增，请查看 Activity 区域中的 **Step Failed** 行，或在 Console 中查找失败消息。调度器会记录具体原因：

| Console 消息                                                          | 原因                         |
| ------------------------------------------------------------------- | -------------------------- |
| `No local action definition found for action 'X'.`                  | 操作名称不匹配——请参见下一步            |
| `Action 'X' has no action behavior bound to it.`                    | Executor 字段为空——请指定执行器组件    |
| `Action 'X' target 'Y' required <Requirement> but resolved <Kind>.` | Convai 发送的目标名称与任何已注册对象都不匹配 |
| {% endstep %}                                                       |                            |

{% step %}

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

操作名称匹配时 **不区分大小写** ，但 **空格有区别**. `Move To` 和 `move to` 匹配。 `Move To` 和 `MoveTo` 则不匹配。

在 `_lastReceivedBatch`中找到 Convai 发送的确切名称。将其与 `ActionName` 字段中的值进行比较，该字段位于 `ConvaiActionConfigSource`中。两者必须逐字符匹配（忽略大小写）。
{% endstep %}

{% step %}

#### 验证组件引用

在 `ConvaiActionConfigSource`中，展开每个 **Action Definition** 条目：

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

{% step %}

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

打开 **Convai → Actions Editor**，切换到 **实时** 模式，打开 **高级**，然后使用 **发送原始命令** （或者点击已创建操作对应的一键按钮）。这会直接向调度器提交命令，绕过 Convai。

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

选择 **清除** 在每次测试之间清除 Action Monitor，以便 Activity 部分保持清晰易读。
{% endstep %}
{% endstepper %}

### 故障排除表

| 症状                                                                                                                      | 可能原因                                                 | 解决方法                                                                                                    | 验证                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Convai Troubleshooter 报告 `This character can't hold any actions yet.`                                                   | 角色上没有 `ConvaiActionConfigSource` 组件                  | 使用问题项中的修复按钮，或手动将 `ConvaiActionConfigSource` 添加到角色上                                                      | 在 Troubleshooter 中重新检查；Actions Enabled 行会变为 `Actions are enabled on this character.`   |
| Convai Troubleshooter 报告 `Nothing is set up to run actions, so this character will never do anything it's asked to do.` | 角色上没有 `ConvaiActionDispatcher` 组件                    | 使用问题项中的修复按钮，或将 `ConvaiActionDispatcher` 添加到同一个 `GameObject`                                             | 在 Troubleshooter 中重新检查；Running Actions 行会变为 `This character is set up to run actions.` |
| `_receivedBatchCount` 说话后仍为 0                                                                                           | `ConvaiActionConfigSource` 缺失或没有操作定义                 | 添加 `ConvaiActionConfigSource` 并至少添加一个操作定义；只有在知道已配置操作的情况下，Convai 才会返回操作                                  | 再次说话； `_receivedBatchCount` 递增                                                         |
| `_receivedBatchCount` 递增，但 `_startedStepCount` 仍为 0                                                                     | `ConvaiActionDispatcher` 缺失、已禁用或位于错误的 `GameObject`   | 将调度器添加到同一个 `GameObject` 上，与 `ConvaiCharacter`相同；确认其已启用                                                  | `_startedStepCount` 在下一批次时递增                                                           |
| `_failedStepCount` 递增： `No local action definition found for action 'X'.`                                               | Convai 发送的操作名称与本地定义中的任何 `ActionName` 都不匹配            | 打开 `_lastReceivedBatch` 查看确切名称；在 `ConvaiActionConfigSource`                                             | 中按该名称匹配（不区分大小写，但空格必须一致） `_startedStepCount` 而不是 `_failedStepCount`                     |
| `_failedStepCount` 递增： `Action 'X' has no action behavior bound to it.`                                                 | `Executor` 字段 `ConvaiActionDefinition` 为空            | 将执行器组件引用拖入 `Executor` 字段 `ConvaiActionConfigSource`中，或使用 Convai 故障排查工具中的“修复操作行为”按钮                      | 该步骤到达 `_startedStepCount` 并且执行器的行为会运行                                                  |
| A `ConvaiUnityEventActionExecutor` 操作从未触发其监听器                                                                           | 执行器的 `UnityEvent` 在 Inspector 中未绑定持久化监听器             | 为执行器的 `UnityEvent` 字段绑定监听器；Convai 的 MCP 操作诊断工具会将此问题标记为 `ACTION_EVENT_UNWIRED`                           | 操作下次执行时，绑定的监听器将会运行                                                                     |
| `_failedStepCount` 递增： `Action 'X' target 'Y' required <Requirement> but resolved <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 到达目标并完成步骤，而不是因超时而中止                                                                |
| 在 Inspector 中配置的动作在场景切换后不起作用                                                                                            | 连接时发送的配置已过时                                          | 结束会话并重新连接；动作配置仅在连接时发送一次                                                                                 | 重新连接后，新配置会对后续请求的动作生效                                                                   |
| 动作在编辑器中有效，但在构建版本中无效                                                                                                     | 执行器组件未包含在构建版本中                                       | 确认执行器脚本位于项目的编译范围内；检查是否存在 `[assembly: ...]` 排除项                                                          | 构建版本的 Console 显示与编辑器相同的 `ConvaiActionDebugProbe` 输出                                    |
| `DynamicContext.SetCurrentAttentionObject` 调用没有效果                                                                       | 当前不在进行中的对话中，或对象名称不在当前配置中                             | 仅在 `ConnectAsync` 完成后调用；对象名称必须与 `ConvaiActionConfigSource.Objects`                                      | 中注册的条目匹配                                                                               |
| Actions Editor 中待处理的运行时更新始终无法清除                                                                                         | 更新已被丢弃——ACK 错误、元数据格式错误或不匹配，或发生 30 秒超时（断开连接时也可能被静默丢弃） | 检查 Console 中是否有 `Runtime action mutation discarded update_id=... reason=...`；已丢弃的更新不会重试，请使用新的更新 ID 重新发送 | 待处理条目消失，且最后一条确认信息显示新状态                                                                 |
| Actions Editor 中最后一条动作更新确认信息显示 `requires_reconnect`                                                                     | Convai 已应用更改，但动作生成策略需要在新会话中生效                        | 结束会话并重新连接；SDK 不会自动重新连接                                                                                  | 重新连接后，最新的确认会反映重新应用的状态                                                                  |
| **发送补丁** 在运行时补丁编辑器中仍处于禁用状态                                                                                              | 角色尚未连接，或草稿中未包含任何字段                                   | 会话连接后再发送；发送前至少勾选一个字段                                                                                    | 连接成功且至少包含一个字段后，该按钮便会启用                                                                 |

### 后续步骤

{% content-ref url="/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a" %}
[在运行时更新角色动作](https://docs.convai.com/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" %}
[角色动作脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/aed151614a7019028126be07590213a17602a2f2" %}
[故障排查](https://docs.convai.com/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 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/features/character-actions/debugging-and-troubleshooting.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.
