调试与故障排除

使用内置调试探针、控制台日志参考和诊断清单来识别并解决 Action 管道问题。

调试动作系统

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列表中第一个已注册对象的动作。可用它来测试执行器连接是否正确，而无需对角色说话。
重置探针状态	重置所有计数器，并清空最近一次看到的文本字段。

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

---

诊断检查清单

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

1

检查已接收批次数

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

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

2

检查已开始步骤计数

不会 已开始步骤数 增加？

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

3

检查失败与成功情况

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

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

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

4

验证动作名称拼写

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

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

5

验证目标名称拼写

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

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

6

检查组件分配

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

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

7

验证 NavMesh（如果使用 NavMesh 执行器）

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

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

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

---

常见问题

症状	可能原因	修复
已接收批次数从不增加	在 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 上并使用 注入测试批次 以在无需实时对话的情况下验证连接。启用 记录到控制台 在开发期间并阅读步骤失败消息——它们包含每个步骤失败的确切原因。一旦探针中一切正常，你的动作系统就可以进行全面测试了。