> 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/unity-plugin-beta-overview/features/actions/debugging-and-troubleshooting.md).

# 调试与故障排除

## 调试动作系统

Convai SDK 包含一个内置调试组件，可在运行时跟踪每个动作事件——无需自定义日志代码。此页面将说明如何使用它以及如何诊断常见问题。

***

## ConvaiActionDebugProbe

`ConvaiActionDebugProbe` 是一个轻量级的 Inspector 组件，它会订阅所有调度器事件，并直接在 Inspector 中显示实时计数器和最近一次看到的动作数据。

**添加组件：** `Convai/Debug/Convai Action Debug Probe`

将其添加到 **同一个 GameObject** 作为你的 `ConvaiCharacter`。它会自动查找 `ConvaiCharacter` 是位于 `ConvaiActionDispatcher` 同一对象上的组件。

### Inspector 字段

| 字段           | 说明                                                  |
| ------------ | --------------------------------------------------- |
| **记录到控制台**   | 启用后，每个动作事件都会打印到 Unity 控制台，并附带完整细节。为减少生产环境中的噪声，请禁用它。 |
| **接收批次数**    | 自 Play 开始以来从后端接收到的动作批次数总计。                          |
| **已开始步骤数**   | 调度器已开始执行的步骤总数。                                      |
| **成功步骤数**    | 所有返回 `成功`.                                          |
| **失败步骤数**    | 所有返回 `失败`, `超时`，或缺少定义/目标。                           |
| **未处理步骤数**   | 执行器返回 `未处理`.                                        |
| **中止批次数**    | 由于失败而提前停止的批次数总计（停止批次策略）。                            |
| **最近接收的批次**  | 后端接收到的最新动作批次的 JSON 表示。                              |
| **最近开始的步骤**  | 最近开始的步骤详情（命令、定义、解析后的目标）。                            |
| **最近成功的步骤**  | 最近成功的步骤详情。                                          |
| **最近未处理的步骤** | 最近未处理的步骤详情。                                         |

### 上下文菜单操作

右键单击 `ConvaiActionDebugProbe` Inspector 中的组件标题以访问：

| 上下文菜单项     | 作用                                                                                     |
| ---------- | -------------------------------------------------------------------------------------- |
| **注入测试批次** | 发送一个 `Move To` 针对你的 `ConvaiActionConfigSource`列表中第一个已注册对象的动作。可用它来测试执行器连接是否正确，而无需对角色说话。 |
| **重置探针状态** | 重置所有计数器，并清空最近一次看到的文本字段。                                                                |

{% hint style="info" %}
**注入测试批次** 是检查你的执行器是否正确连接的最快方法。如果成功，则说明你的动作定义、目标和执行器都已正确配置。如果失败，请查看控制台输出中的原因。
{% endhint %}

***

## 诊断检查清单

当动作未按预期工作时，请按顺序完成此检查清单。

{% stepper %}
{% step %}
**检查已接收批次数**

添加 `ConvaiActionDebugProbe` 向你的 NPC 说话并与角色交互。是否 **接收批次数** 增加？

* **是** → 后端正在发送命令。进入下一步。
* **没有** → 角色没有从后端接收到动作命令。检查你的角色在 `ConvaiActionConfigSource` 中至少有一个动作定义，并且会话已处于活动连接状态。
  {% endstep %}

{% step %}
**检查已开始步骤计数**

不会 **已开始步骤数** 增加？

* **是** → 调度器正在接收并开始执行步骤。进入下一步。
* **没有** → 已接收到批次，但没有步骤开始。这通常意味着批次为空，或者调度器组件已禁用。检查 `ConvaiActionDispatcher` 已启用并与 `ConvaiCharacter`.
  {% endstep %}

{% step %}
**检查失败与成功情况**

不会 **失败步骤数** 增加而不是 **成功步骤数**?

打开 Unity 控制台。查找带有 `[ConvaiActionDebugProbe]`。失败消息会准确说明原因：

| 控制台消息                    | 含义                                                             |
| ------------------------ | -------------------------------------------------------------- |
| `未找到 'X' 的本地动作定义`        | 动作名称 `X` 来自后端的动作在 `ConvaiActionConfigSource`中没有匹配的定义。检查拼写和大小写。 |
| `动作 'X' 缺少有效的执行器`        | 该 **执行器** 定义中的字段为空，或者分配的组件未实现 `IConvaiActionExecutor`.         |
| `目标要求“对象”未满足（解析结果：None）` | 该动作需要对象目标，但你的 **可操作对象** 列表中的任何对象名称都与后端的目标字符串匹配。                |
| {% endstep %}            |                                                                |

{% step %}
**验证动作名称拼写**

比较动作名称 `ConvaiActionConfigSource` 与 **最近接收的批次** 调试探针中显示的内容。

名称匹配 **不区分大小写**，但拼写必须完全一致。 `Move To` 是位于 `Moveto` 是不同的。
{% endstep %}

{% step %}
**验证目标名称拼写**

如果步骤因目标解析错误而失败，请比较目标名称 **最近接收的批次** 与 **名称** 你在你的 **可操作对象** 或 **可操作角色** 列表中。

不区分大小写，但拼写必须相同。 `灭火器` 是位于 `FireExtinguisher` 是不同的名称。
{% endstep %}

{% step %}
**检查组件分配**

确认所有必需组件都已分配：

* `ConvaiActionConfigSource` → **执行器** 每个定义的字段都不为空
* 分配的执行器组件位于场景中的 **GameObject** （不是 Project 视图中的预制体）
* `NavMesh Move To Action Executor` → **代理** 字段已分配
* `Animator 触发器动作执行器` → **Animator** 字段已分配
* `拾取动作执行器` → **移动器**, **Animator**，以及 **附着点** 都已分配
  {% endstep %}

{% step %}
**验证 NavMesh（如果使用 NavMesh 执行器）**

如果你正在使用 `NavMesh Move To Action Executor` 并且该动作总是失败：

1. 打开 **窗口 → AI → 导航**.
2. 切换到 **烘焙** 选项卡。
3. 单击 **烘焙**.

场景的地面必须包含在 NavMesh 表面中。目标对象的位置必须能从 NPC 的起始位置到达。
{% endstep %}
{% endstepper %}

***

## 常见问题

| 症状                               | 可能原因                                                 | 修复                                 |
| -------------------------------- | ---------------------------------------------------- | ---------------------------------- |
| **已接收批次数从不增加**                   | 在 `ConvaiActionConfigSource`中没有动作定义，或者会话未连接          | 至少添加一个定义；确保 `ConvaiCharacter` 已连接  |
| **动作触发但没有任何反应**                  | 执行器字段为空，或者组件未实现 `IConvaiActionExecutor`              | 为该定义分配一个有效的执行器组件                   |
| **“未找到本地动作定义”** 在 Console 中      | 后端与 `ConvaiActionConfigSource`                       | 中的动作名称不匹配 **最近接收的批次** 查看以了解发送的确切名称 |
| **“未满足目标要求”** 在 Console 中        | 来自后端的目标字符串与 Actionable Objects/Characters 中的任何条目都不匹配 | 添加一个匹配项，或检查目标列表中的名称拼写              |
| **批次在第一个动作后停止**                  | 停止批次失败策略 + 第一个动作失败                                   | 修复第一个动作的执行器，或者切换到 **继续批次** 策略      |
| **NPC 在 NavMesh 移动过程中卡住**        | NavMesh 未烘焙，或者目标无法到达                                 | 烘焙 NavMesh；设置一个合理的 **超时秒数** 在定义上   |
| **重复动作定义警告**                     | Definitions 列表中的两个条目共享相同的动作名称                        | 移除重复项；始终使用第一个条目                    |
| **未处理步骤计数增加**                    | 执行器返回了 `未处理`                                         | 检查执行器的逻辑——它可能因目标类型或缺少状态而拒绝该调用      |
| **控制台中的初始注意对象警告**                | 该字段中的值与任何条目都不匹配 **可操作对象**                            | 验证拼写是否完全一致；请参阅注意力与指代锚定             |
| **AI 对模糊指代（“it”“that”）使用了错误的目标** | 未设置注意对象，或者对象描述过于模糊                                   | 设置 **初始注意对象** 并改进对象描述；请参阅注意力与指代锚定  |

***

## 控制台日志参考

当 **记录到控制台** 在……上启用时 `ConvaiActionDebugProbe`，以下消息会出现在 Unity 控制台中：

| 消息模式                                          | 含义                                    |
| --------------------------------------------- | ------------------------------------- |
| `收到动作批次 #N: [{"name":"X","target":"Y"}]`      | 已从后端接收到一个批次。JSON 显示原始动作名称和目标。         |
| `调度器批次已开始。`                                   | 调度器开始处理一个排队中的批次。                      |
| `步骤已开始 #N: cmd='X', def='Y', target=Object:Z` | 一个步骤已开始。显示命令名称、匹配的定义以及解析后的目标类型和名称。    |
| `步骤成功 #N: ...`                                | 一个步骤完成，结果为 `成功`.                      |
| `步骤失败 #N: ...` （黄色警告）                         | 一个步骤完成，结果为 `失败`, `超时`，或 `Canceled`.   |
| `步骤未处理 #N: ...` （黄色警告）                        | 执行器返回了 `未处理`.                         |
| `调度器批次已完成。`                                   | 批次中的所有步骤都已完成（成功或 `ContinueBatch` 模式）。 |
| `调度器批次已中止 #N。` （黄色警告）                         | 由于失败而提前停止批次（停止批次策略）。                  |

***

## 结论

从以下开始 `ConvaiActionDebugProbe` 在你的 NPC 上并使用 **注入测试批次** 以在无需实时对话的情况下验证连接。启用 **记录到控制台** 在开发期间并阅读步骤失败消息——它们包含每个步骤失败的确切原因。一旦探针中一切正常，你的动作系统就可以进行全面测试了。


---

# 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/unity-plugin-beta-overview/features/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.