> 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).

# 排查角色动作问题

诊断动作管线问题的最快方法是 `ConvaiActionDebugProbe`。将其添加到你的 NPC 的 `GameObject`，进入 Play 模式，并观察其计数器实时更新。本页涵盖探针的完整 Inspector 参考、其上下文菜单工具，以及针对每种常见故障模式的完整故障排查表。

### ConvaiActionDebugProbe

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `添加组件 → Convai → 调试 → Convai Action Debug Probe`

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

探针会自动解析 `ConvaiCharacter` 是位于 `ConvaiActionDispatcher` 来自同一 `GameObject` on `Awake`。两者都会在 Inspector 中显示为只读引用字段，以确认自动解析成功。

#### Inspector 字段

| 字段                    | 类型                       | 说明                                           |
| --------------------- | ------------------------ | -------------------------------------------- |
| `_character`          | `ConvaiCharacter`        | 已自动解析。跟踪来自后端的原始动作批次。                         |
| `_dispatcher`         | `ConvaiActionDispatcher` | 已自动解析。跟踪执行生命周期事件。                            |
| `_logToConsole`       | `bool`                   | 启用后，所有探针事件都会打印到 Console。禁用可让测试更安静。           |
| `_receivedBatchCount` | `int`                    | 通过以下方式从 Convai 接收的批次总数： `OnActionsReceived`. |
| `_startedStepCount`   | `int`                    | 调度器已开始执行的步骤总数。                               |
| `_succeededStepCount` | `int`                    | 返回结果的步骤总数。 `成功`.                             |
| `_failedStepCount`    | `int`                    | 返回结果的步骤总数。 `失败`, `Canceled`，或 `超时`.          |
| `_unhandledStepCount` | `int`                    | 返回结果的步骤总数。 `未处理`.                            |
| `_abortedBatchCount`  | `int`                    | 被以下原因中断的批次总数： `StopBatch` 失败策略。              |
| `_lastReceivedBatch`  | `string` (TextArea)      | 最近一次从 Convai 接收的批次的 JSON。                    |
| `_lastStepStarted`    | `string` (TextArea)      | 调度器最近开始的步骤摘要。                                |
| `_lastStepSucceeded`  | `string` (TextArea)      | 最近成功的步骤摘要。                                   |
| `_lastUnhandledStep`  | `string` (TextArea)      | 最近未处理的步骤摘要。                                  |

#### 上下文菜单操作

在 Inspector 中右键单击探针组件标题以访问：

| 命令         | 效果                                               |
| ---------- | ------------------------------------------------ |
| **注入测试批次** | 提交一个 `Move To` 指向第一个已注册对象的命令给调度器。无需实时对话即可测试完整管线。 |
| **重置探针状态** | 将所有计数器重置为 `0` 并清空所有文本字段。在测试运行之间使用，以保持计数器有意义。     |

#### Console 日志格式

当 `_logToConsole` 启用后，探针会按以下格式写入 Console：

```
[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。
```

### 诊断检查清单

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

{% stepper %}
{% step %}

#### 验证后端是否在发送动作

检查 `_receivedBatchCount` 在 Play 模式下说出命令后，查看探针 Inspector。

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

{% step %}

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

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

* `ConvaiActionDispatcher` 可能在 NPC 的上缺失或被禁用 `GameObject`
* 检查调度器是否位于 **相同的 `GameObject`** 作为 `ConvaiCharacter`
* 确认 Inspector 中的调度器组件已启用（组件名称旁的复选框）
  {% endstep %}

{% step %}

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

如果 `_failedStepCount` 递增时，展开 `_lastStepStarted` 并检查 Console 中的失败消息。调度器会记录确切原因：

| Console 消息                    | 原因                      |
| ----------------------------- | ----------------------- |
| `未找到 'X' 的本地动作定义`             | 动作名称不匹配 — 见下一步          |
| `动作 'X' 缺少有效的执行器`             | Executor 字段为空 — 分配执行器组件 |
| `未满足目标要求 'Object'（解析结果：None）` | 后端发送的目标名称与任何已注册对象都不匹配   |
| {% endstep %}                 |                         |

{% step %}

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

动作名称匹配 **不区分大小写** 但 **空格是有意义的**. `Move To` 是位于 `移动到` 则匹配。 `Move To` 是位于 `MoveTo` 则不匹配。

在 `_lastReceivedBatch`，找出后端发送的确切名称。将其与 `ActionName` 中的字段 `ConvaiActionConfigSource`。它们必须逐字符匹配（忽略大小写）。
{% endstep %}

{% step %}

#### 验证组件引用

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

* **Executor 字段为空** → 该步骤将因“缺少有效的执行器”而失败。将执行器组件引用拖入 Executor 字段。
* **执行器未实现 `IConvaiActionExecutor`** → 该步骤将失败。自定义执行器必须实现该接口。
  {% endstep %}

{% step %}

#### 使用注入测试批次进行测试

右键单击 `ConvaiActionDebugProbe` → **注入测试批次**。这会提交一个 `Move To` 直接针对你的第一个已注册对象的命令给调度器，绕过后端。

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

单击 **重置探针状态** 在测试运行之间以保持计数器易读。
{% endstep %}
{% endstepper %}

### 故障排查表

| 症状                                                 | 可能原因                                                | 修复                                                                                                   |
| -------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `_receivedBatchCount` 说话后仍为 0                      | `ConvaiActionConfigSource` 缺失或没有动作定义                | 添加 `ConvaiActionConfigSource` 并至少包含一个动作定义；只有在后端知道已配置动作时才会返回动作                                        |
| `_receivedBatchCount` 递增但 `_startedStepCount` 仍为 0 | `ConvaiActionDispatcher` 缺失、被禁用，或位于错误的 `GameObject` | 将调度器添加到相同的 `GameObject` 作为 `ConvaiCharacter`；确认其已启用                                                  |
| `_failedStepCount` 递增：“未找到 'X' 的本地动作定义”            | 后端发送的动作名称与任何都不匹配 `ActionName` 本地定义中的                | 打开 `_lastReceivedBatch` 以查看确切名称；在中将其匹配（不区分大小写，空格有影响） `ConvaiActionConfigSource`                      |
| `_failedStepCount` 递增：“缺少有效的执行器”                   | `执行器` 中的字段 `ConvaiActionDefinition` 为空              | 将执行器组件引用拖入 `执行器` 中的字段 `ConvaiActionConfigSource`                                                     |
| `_failedStepCount` 递增：“未满足目标要求”                    | 后端的目标名称与任何已注册对象或角色都不匹配                              | 打开 `_lastReceivedBatch` 以查看目标名称；确认其匹配 `名称` 中的条目 **可操作对象** 或 **可操作角色** （不区分大小写）                       |
| `_unhandledStepCount` 递增                           | 执行器返回 `未处理` — 执行器拒绝处理此次调用                           | 检查执行器逻辑； `未处理` 表示执行器选择不运行，而不是出了故障                                                                    |
| `_abortedBatchCount` 递增                            | 某一步失败，并且 `StopBatch` 策略中止了其余步骤                      | 修复失败的步骤（见上文），或更改 `FailurePolicy` 到 `ContinueBatch` 如果步骤彼此独立                                          |
| NPC 传送而不是导航                                        | `TransformMoveToActionExecutor` 正在使用                | 替换为 `NavMeshMoveToActionExecutor` 或使用你的移动系统的自定义执行器                                                   |
| NPC 开始移动然后冻结                                       | `NavMeshMoveToActionExecutor` 代理卡住或路径被阻塞            | 烘焙 NavMesh（**窗口 → AI → Navigation → 烘焙**）；确认 NPC 和目标都位于 NavMesh 表面；设置 `TimeoutSeconds` 在动作定义上以防止无限阻塞 |
| NPC 会导航，但对象未被拾取                                    | `PickUpActionExecutor._mover` 为空                    | 分配一个 `NavMeshMoveToActionExecutor` 引用到 `_mover` 在 `PickUpActionExecutor` 检查器                         |
| 在 Inspector 中配置的动作在场景切换后不工作                        | 连接时发送的配置现在已过期                                       | 结束会话并重新连接；动作配置只会在连接时发送一次                                                                             |
| 动作在编辑器中有效，但在构建中无效                                  | 构建中未包含执行器组件                                         | 确认执行器脚本位于项目的编译范围内；检查 `[assembly: ...]` 排除项                                                           |
| `SetCurrentAttentionObject` 调用没有效果                 | 不在活动对话中，或对象名称不在活动配置中                                | 仅在以下之后调用 `ConnectAsync` 完成；对象名称必须匹配中的已注册条目 `ConvaiActionConfigSource.Objects`                        |

### 下一步

{% 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/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19" %}
[角色动作快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/quick-start.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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.