分发器与批处理策略

配置 ConvaiActionDispatcher 的批处理策略、失败策略和生命周期事件，并以编程方式注入动作批次用于测试或脚本化序列。

ConvaiActionDispatcher 是动作系统的运行时执行层。它会监听来自 Convai 的命令批次，将每个动作和目标与当前会话的配置进行解析，并一次一步地调用绑定的执行器组件。两种策略控制在执行过程中收到新批次时会发生什么，以及某一步失败时会发生什么。

组件概览

属性	值
菜单路径	添加组件 → Convai → Convai Action Dispatcher
命名空间	Convai.Runtime.Actions
约束	DisallowMultipleComponent, RequireComponent(ConvaiCharacter)

该分发器必须位于同一个 GameObject 作为 ConvaiCharacter。每个角色只允许一个分发器。

检查器中的 ConvaiActionDispatcher——两个策略下拉框控制队列和失败行为；七个生命周期 UnityEvent 字段公开完整的批处理和步骤执行流水线。

Inspector 字段

字段	类型	默认值	说明
_batchPolicy	ConvaiActionBatchPolicy	队列	当另一个批次正在执行时，传入批次的行为方式
_failurePolicy	ConvaiActionBatchFailurePolicy	StopBatch	某一步失败后，是中止剩余批次还是允许其继续执行
_onBatchStarted	UnityEvent	—	在批次开始执行时触发
_onStepStarted	ConvaiActionInvocationUnityEvent	—	在每一步开始时触发
_onStepSucceeded	ConvaiActionInvocationUnityEvent	—	在步骤执行器返回时触发 成功
_onStepFailed	ConvaiActionInvocationUnityEvent	—	当某一步因任何原因失败时触发
_onStepUnhandled	ConvaiActionInvocationUnityEvent	—	当执行器返回时触发 未处理
_onBatchCompleted	UnityEvent	—	当所有步骤都完成且未被中止时触发
_onBatchAborted	UnityEvent	—	当批次因失败策略而被提前截断时触发

ConvaiActionInvocationUnityEvent 是一个可序列化的 UnityEvent<ConvaiActionInvocation>。在检查器中将其像标准 UnityEvent 一样连接——事件参数承载完整的调用上下文（动作名称、目标、角色、批次和步骤索引）。

批处理策略

当 Convai 返回新的动作批次，而分发器仍在执行上一个批次时，批处理策略决定会发生什么。

策略	枚举值	行为
队列	0	新批次会在队列中等待。当前批次会先完成，然后下一个批次才开始。适用于大多数场景。
ReplaceCurrent	1	取消当前正在执行的步骤并清除所有已排队的批次。新批次会立即开始。适用于中断驱动的场景（例如：“停下，改来这里。”）。
DropIncoming	2	在当前批次及所有排队批次完成之前，丢弃新批次。用于正在进行的序列不能被中断的情况（例如，必须完成的安全演示）。

ReplaceCurrent 取消 当前正在运行的执行器步骤 通过 CancellationToken 并在启动新步骤前清除所有待处理批次。执行器必须遵守取消令牌，这样才能立刻生效——参见 编写自定义动作执行器.

批处理策略下拉框——Queue 是默认值，适用于大多数场景；ReplaceCurrent 处理中断驱动的 NPC 行为；DropIncoming 保护必须执行到完成的序列。

失败策略

失败策略控制当执行器返回非成功结果（失败, 未处理, Canceled，或 超时).

策略	枚举值	行为
StopBatch	0	批次中的剩余步骤会被跳过。 OnBatchAborted 会触发。
ContinueBatch	1	无论是否失败，执行都会继续到下一步。 OnBatchCompleted 会在末尾触发。

使用 ContinueBatch 适用于彼此独立的动作——失败的“指向”不应阻止后续的“挥手”。在 StopBatch （默认值）中用于相互依赖的序列——失败的“移动到”应该阻止后续原本也会失败的“拾取”。

失败策略下拉框——StopBatch（默认）会中止剩余步骤并触发 OnBatchAborted；ContinueBatch 会让失败继续向后执行，并在末尾触发 OnBatchCompleted。

生命周期事件

分发器会在批处理和步骤执行的每个重要阶段触发事件。可以通过 UnityEvent 字段在检查器中订阅，也可以通过属性在 C# 中订阅。

分发器生命周期 UnityEvent 字段——在检查器中连接这些字段，以响应批处理和步骤转换，而无需编写分发器侧 C# 代码。

事件触发顺序

OnBatchStarted
  → OnStepStarted       （每个步骤）
  → OnStepSucceeded     （如果执行器返回 Succeeded）
     或
  → OnStepFailed        （如果执行器返回 Failed、Canceled 或 TimedOut）
     或
  → OnStepUnhandled     （如果执行器返回 Unhandled）
OnBatchCompleted  （所有步骤完成，或 ContinueBatch 允许失败继续执行）
  或
OnBatchAborted    （StopBatch 策略在失败后提前终止了批次）

在 C# 中订阅

using Convai.Runtime.Actions;
using UnityEngine;

public sealed class ActionFeedback : MonoBehaviour
{
    [SerializeField] private ConvaiActionDispatcher _dispatcher;

    private void OnEnable()
    {
        _dispatcher.OnBatchStarted.AddListener(HandleBatchStarted);
        _dispatcher.OnStepSucceeded.AddListener(HandleStepSucceeded);
        _dispatcher.OnStepFailed.AddListener(HandleStepFailed);
        _dispatcher.OnBatchCompleted.AddListener(HandleBatchCompleted);
        _dispatcher.OnBatchAborted.AddListener(HandleBatchAborted);
    }

    private void OnDisable()
    {
        _dispatcher.OnBatchStarted.RemoveListener(HandleBatchStarted);
        _dispatcher.OnStepSucceeded.RemoveListener(HandleStepSucceeded);
        _dispatcher.OnStepFailed.RemoveListener(HandleStepFailed);
        _dispatcher.OnBatchCompleted.RemoveListener(HandleBatchCompleted);
        _dispatcher.OnBatchAborted.RemoveListener(HandleBatchAborted);
    }

    private void HandleBatchStarted() => Debug.Log("批次已开始");
    private void HandleStepSucceeded(ConvaiActionInvocation inv) =>
        Debug.Log($"步骤成功：{inv.Command.Name}");
    private void HandleStepFailed(ConvaiActionInvocation inv) =>
        Debug.LogWarning($"步骤失败：{inv.Command.Name}");
    private void HandleBatchCompleted() => Debug.Log("批次已完成");
    private void HandleBatchAborted() => Debug.LogWarning("批次已中止");
}

手动批次注入

EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions) 以编程方式向分发器提交一个批次，并遵循当前的批处理与失败策略。可用于脚本化演示流程、自动化测试运行，或由游戏事件而非玩家语音触发的 NPC 行为。

using System.Collections.Generic;
using Convai.Runtime.Actions;
using Convai.Shared.Types;
using UnityEngine;

public sealed class DemoTrigger : MonoBehaviour
{
    [SerializeField] private ConvaiActionDispatcher _dispatcher;

    public void RunSafetyDemo()
    {
        _dispatcher.EnqueueActions(new List<ConvaiActionCommand>
        {
            new ConvaiActionCommand("Move To", "Extinguisher"),
            new ConvaiActionCommand("Pick Up", "Extinguisher"),
            new ConvaiActionCommand("Move To", "Exit")
        });
    }
}

分发器会按顺序执行这些步骤。如果 BatchPolicy 为 队列，则该批次会排在任何已在进行中的批次之后等待。

绕过分发器

如果你希望在不经过分发器的目标解析和执行流水线的情况下响应原始动作命令，请订阅 ConvaiCharacter.OnActionsReceived ：

using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Shared.Types;
using UnityEngine;

public sealed class ManualActionHandler : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;

    private void OnEnable() =>
        _character.OnActionsReceived += HandleActions;

    private void OnDisable() =>
        _character.OnActionsReceived -= HandleActions;

    private void HandleActions(IReadOnlyList<ConvaiActionCommand> commands)
    {
        foreach (ConvaiActionCommand cmd in commands)
            Debug.Log($"动作：{cmd.Name}，目标：{cmd.Target}");
    }
}

绕过分发器意味着没有自动目标解析、没有批处理/失败策略，也没有生命周期事件。这适用于只读观察或自定义分发流水线，但不适用于 SDK 应驱动行为的典型游戏玩法。

分发器生命周期行为

情况	分发器行为
分发器已禁用	活动工作被取消；队列被清空
分发器被销毁	与禁用时相同
收到空批次	静默忽略——不触发任何事件
动作名称不在本地定义中	步骤失败： OnStepFailed 触发； StopBatch 中止批次
未分配执行器字段	步骤失败： OnStepFailed 触发
未满足目标要求	步骤失败： OnStepFailed 触发
执行器返回 未处理	OnStepUnhandled 触发；在……中被视为失败 StopBatch 策略

使用示例

示例 1——培训清单集成

场景： 企业入职模拟。NPC 完成每个设备演示后，清单 UI 会前进一步。

连接 OnBatchCompleted 在检查器中将其连接到 TrainingChecklistManager.AdvanceStep()。每当 NPC 完成一个完整序列时，清单会自动前进。

// TrainingChecklistManager.cs
public void AdvanceStep()
{
    _currentStep++;
    UpdateChecklistUI();
}

分发器侧不需要额外代码——只需将 OnBatchCompleted UnityEvent 在检查器中连接即可。

示例 2——导航失败时的备用对话

场景： 当 NPC 无法到达目标（NavMesh 路径被阻挡）时，它应该说出一条备用台词，而不是静默停止。

订阅 OnStepFailed 并注入一个动态上下文更新：

private void HandleStepFailed(ConvaiActionInvocation invocation)
{
    if (invocation.Command.Name == "Move To")
    {
        string targetName = invocation.Command.Target ?? "那个位置";
        // 注入到动态上下文中，以便 NPC 自然地承认失败
        _character.DynamicContext.AddEvent($"无法到达 {targetName}——路径被阻挡了。");
    }
}

下一步

编写自定义动作执行器角色动作脚本参考