角色动作故障排查

使用 ConvaiActionDebugProbe 的 Inspector 计数器和测试批量注入来诊断动作管线问题——并提供常见故障的症状/原因/修复完整参考。

诊断动作管线问题的最快方法是 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。

诊断检查清单

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

1

验证后端是否在发送动作

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

• 计数器递增 → 后端返回了一个动作批次；继续下一步。
• 计数器保持为 0 → Convai 未返回动作响应。可能原因：

  • ConvaiActionConfigSource 没有动作定义（后端不知道可用动作）
  • Convai 后端角色未配置为针对此角色 ID 返回动作
  • 会话未成功连接

2

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

如果 _receivedBatchCount 递增但 _startedStepCount 仍为 0：

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

3

读取步骤失败消息

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

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

4

检查动作名称是否不匹配

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

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

5

验证组件引用

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

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

6

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

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

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

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

故障排查表

症状	可能原因	修复
_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

下一步

角色动作脚本参考角色动作快速入门