使用示例

四个完整的模拟场景——安全演练、入职导览、导览游和紧急过渡——每个都展示了不同的上下文策略。

动态上下文实践：演练模拟场景

以下场景演示了动态上下文在学习和训练模拟中的应用。每个示例都是独立的，并展示了不同的上下文操作组合。它们共同覆盖了该功能的全部范围——从简单的状态更新到批量过渡和响应式事件。

场景 A — 安全演练：灭火评估

一名安全培训角色引导学习者完成灭火演练。该角色必须知道受训者所在的站点、当前危险级别以及受训者犯下的任何关键错误，以便提供有针对性的即时反馈。

初始上下文

在 NPC 的 ConvaiCharacter 检查器中，在 动态信息（连接请求），设置：

站点是灭火区
危险等级是极高

启用 初始动态信息保留在上下文中 ，以便角色在整个对话过程中始终保留场景框架。

区域进入：设置当前设备

当受训者进入 CO2 灭火剂区域时， ConvaiDynamicContextCommand 触发器碰撞体上的 Execute() ，带有：

• 命令类型： SetState
• 状态名称： 当前灭火剂
• 状态值： CO2
• 反应： SyncOnly

无需立即的角色回应——角色会在下一次对话轮次中自然提及该灭火剂。

错误：激活了错误的灭火剂

当受训者激活了错误的灭火剂（水用于电气火灾）时，模拟会从脚本中触发一个事件：

using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

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

    public void OnWrongSuppressorActivated()
    {
        _character.DynamicContext.AddEvent(
            "受训者在电气火灾上启用了水基灭火剂",
            ConvaiContextReactionMode.ReactImmediately
        );
    }
}

ReactImmediately 会迫使角色立即回应——例如： "停下——在电气火灾上使用水极其危险。让我们先讨论为什么这里应该选择 CO2，然后再继续。"

危险已清除：移除状态

当演练结束且危险得到解决时， ConvaiDynamicContextCommand 会触发：

• 命令类型： RemoveState
• 状态名称： 危险级别

规范化上下文会在不包含危险级别的情况下重建，因此角色不再提及当前紧急情况。

场景 B — 入职引导：设备交接

一名入职引导角色带领新员工完成一项流程性设备检查。该角色必须知道受训者已收集了哪些设备以及哪些检查点已清除——并且不应重复解释它已经知道受训者完成过的内容。

拾取物品时批量更新状态

当受训者拿起一整套 PPE 套装时，一次更新多个状态：

using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

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

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;

        _character.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "设备", "完整的 PPE 套装" },
                { "检查点", "更衣室已清除" }
            },
            ConvaiContextReactionMode.SyncOnly
        );
    }
}

将这两个更新批量合并为一次 SetStates 调用，可避免两次单独的规范化重建，并向角色发送一次原子更新——比两个顺序的 SetState 调用的影响。

使用 TryGetStateValue 的条件逻辑

在触发解释 PPE 使用的对话分支之前，检查 SDK 是否已经知道受训者拥有该设备。这样可以防止冗余更新，并避免重复解释角色已经知道的内容：

public void OnApproachEquipmentStation()
{
    if (!_character.DynamicContext.TryGetStateValue("Equipment", out string equipment)
        || equipment != "Full PPE kit")
    {
        _character.DynamicContext.SetState(
            "设备", "完整的 PPE 套装",
            ConvaiContextReactionMode.SyncOnly
        );
        TriggerEquipmentExplanationDialogue();
    }
}

TryGetStateValue 读取本地追踪器——它不会查询服务器——因此可以安全地频繁调用，而不会产生网络开销。

在下一个站点重置

当受训者移动到下一个入职站点并开始新的检查清单时，清除会话上下文：

public void OnAdvanceToNextStation()
{
    _character.DynamicContext.Reset();
}

这会清除所有已跟踪的状态和事件。最初设置的 ConvaiCharacter 上下文会被保留——只会擦除运行时跟踪的信息。

场景 C — 引导式参观：带有时间线事件的自适应叙述

一名引导式参观角色会随着访客浏览展品而提供自适应解说。两个 ConvaiDynamicContextCommand 组件被连接到 Playable Director 时间线信号——一个更新当前展品，另一个记录访客交互。

检查器设置

由于 ConvaiDynamicContextCommand 为 [DisallowMultipleComponent]，请将每个命令放在 NPC 的单独子 GameObject 上。将它们配置如下：

命令 A — 展品更新 （在子 GameObject ContextCmd_Exhibit)

• 命令类型： SetState
• 状态名称： 展品
• 状态值： 反应堆核心模型
• 反应： SyncOnly

命令 B — 访客交互 （在子 GameObject ContextCmd_Interaction)

• 命令类型： AddEvent
• 事件文本： 访客询问了遏制协议
• 反应： 自动

在 目标 部分中，将 NPC 的 ConvaiCharacter 显式地在 角色 字段中指定（因为这些命令位于子 GameObject 上，而不是 NPC 根对象上）。

将每个命令的 Execute() 连接到 Playable Director 时间线中相应的动画事件信号。

使用 OnExecuted 提供 UI 反馈

将 On Executed 上的命令 A 连接到一个 UI 组件，该组件会在界面中高亮显示当前展品标签：

命令 A → On Executed → ExhibitHighlight.Activate()

一次 Execute() 调用既更新角色的上下文，又驱动视觉 UI 响应——无需额外脚本。

场景 D — 多状态场景过渡与即时反应

一个训练场景从常规检查阶段过渡到应急响应阶段。多个状态值同时变化，而角色应立即确认新情况，而无需等待受训者开口。

过渡

using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

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

    public void TriggerEmergencyPhase()
    {
        _character.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "Phase", "Emergency Response" },
                { "Alert Level", "Red" },
                { "Time Remaining", "4 minutes" },
                { "Primary Hazard", "Uncontrolled gas release" }
            },
            ConvaiContextReactionMode.ReactImmediately
        );
    }
}

ReactImmediately 与 SetStates 结合后，会使角色在批量更新应用后立即生成响应——例如： "警报——我们已进入应急响应阶段。检测到失控气体释放，警报级别为红色，你还有四分钟。你的第一步行动是什么？"

为什么使用批量而不是顺序 SetState 调用

四次顺序的 SetState 调用会触发多达四次规范化重建和四次潜在的 LLM 重新提示，每次可能得到不同的反应模式结果。一次 SetStates 调用会发送一次原子更新——一次 Replace（如果有任何现有状态被触及）加上一次概括所有更改的 Append——并应用 ReactImmediately 反应且仅一次。结果是对完整场景变化给出一次干净、权威的角色回应。

接下来

• 脚本 API 参考 ——每个上面的脚本示例背后的完整方法签名和参数语义。
• 同步行为与时序 ——精确说明每种更新类型何时传输，以及 SDK 如何决定发送 Replace、Append，还是两者都发送。

结论

这四个场景覆盖了动态上下文操作的完整范围——从单个由 Inspector 驱动的状态更新，到带即时反应的脚本化批量过渡。有关每个脚本示例背后的方法签名，请参见 脚本 API 参考.