动态上下文使用示例

用于健康跟踪、上下文事件、区域切换、状态移除和训练模拟中动态上下文重置的 Blueprint 配方。

这些示例展示了在 Blueprint 中使用动态上下文的常见方式。所有示例都假设有一个带有一个 Convai 聊天机器人 组件（UConvaiChatbotComponent）能够连接到已连接的会话。

先从最简单的模式开始。每个示例都包含一个场景、Blueprint 调用，以及在对话测试前需要在本地验证什么。

在会话连接前预置上下文

场景： 安全培训关卡会在 BeginPlay 中设置设施和场景事实，

默认去抖调用会在会话连接前安全排队。连接后并在去抖截止时间到达后，第一次刷新会发送一个 Replace 上下文更新 ，其中包含组装好的快照。

// Blueprint 伪代码 — 角色 Actor 上的 Event BeginPlay
→ Set Context State  Name="Facility"  Value="海上平台 Alpha"  ShouldRespond=Never
→ Set Context State  Name="Scenario"  Value="消防演练"               ShouldRespond=Never
→ 添加上下文事件  Text="受训者简报完成"                   ShouldRespond=Never

本地验证： 在第一次连接后的刷新之后， 获取上下文状态值 会返回预置的值，而无需额外的 Blueprint 调用。

跟踪玩家生命值

场景： 一个医疗培训模拟，讲师角色在被询问时会评论受训者的生命体征。

绑定到一个在生命值变化时触发的自定义事件。使用 ShouldRespond = Never ，这样就能静默跟踪该值，而无需在每次变化时都请求语音回复。

// Blueprint 伪代码
事件 HealthChanged（NewHealth: float）
  → ConvaiBotComponent → 设置上下文状态
      名称：          "PlayerHealth"
      值：         ToString(NewHealth)
      ShouldRespond：永不

本地验证： 事件触发后， 获取上下文状态值 返回 true 用于 PlayerHealth 是位于 输出值 会与最新值一致。询问 我当前的生命值是多少？ 仅作为端到端运行时测试；准确的回复措辞取决于角色配置。

在发送重复事件前读取状态值

场景： 一个 Blueprint 条件会检查角色在发送重复事件前是否已经知道当前警报。

// Blueprint 伪代码
→ 获取上下文状态值
    名称：     "AlertActive"
    输出值：→ 根据 OutValue == "true" 进行分支
如果为假：
  → 设置上下文状态
      名称：          "AlertActive"
      值：         "true"
      ShouldRespond：自动
  → 添加上下文事件
      文本：          "安全警报已激活"
      ShouldRespond：自动

本地验证： 获取上下文状态值 会立即返回当前值——无需网络往返。之后 设置上下文状态 运行后，返回引脚 true 是位于 输出值 会匹配。

宣布一个叙事事件

场景： 一个工业安全演练，在其中触发火警应发送高优先级上下文事件。

// Blueprint 伪代码
事件 AlarmActivated
  → ConvaiBotComponent → 添加上下文事件
      文本：          "3号区域火警已激活"
      ShouldRespond：始终

在去抖窗口结束后（默认 0.5 秒），插件会刷新 上下文更新 其带有 run_llm 设置为 "true"。若要在会话连接后更快刷新，请设置 bFlushImmediately = true 在 Add Context Event 节点进行暂存。

本地验证： 刷新后，该事件会包含在规范上下文中。使用一次对话轮次来测试你的角色配置所产生的运行时行为。

场景切换后更新多个状态

场景： 一个企业入职模拟，当受训者进入新区域时，会更改房间、可用设备和一天中的时间。

使用 设置上下文状态 ，以便在一次批量调用中推送所有更改的值。

// Blueprint 伪代码
事件 EnteredConferenceRoom
  → ConvaiBotComponent → 设置上下文状态集
      状态：{
        "CurrentZone": "会议室 B",
        "AvailableEquipment": "投影仪、白板",
        "TimeOfDay": "14:30"
      }
      ShouldRespond：自动

本地验证： 刷新后， 获取上下文状态值 会返回以下键的最新本地值，例如 CurrentZone。询问 我们在哪里？ 作为你角色配置的端到端运行时测试。

当条件结束时移除状态

场景： 一个训练物品已被使用，不应再成为角色感知的一部分。

// Blueprint 伪代码
事件 ItemUsed（ItemName: FString）
  → ConvaiBotComponent → 移除上下文状态
      名称：ItemName

本地验证： 去抖刷新后， 获取上下文状态值 返回 false 针对已移除的键。

在关键时刻结合状态和事件

场景： 一个军事模拟，其中一名士兵 NPC 需要知道其指挥官已倒下，并对该事件作出反应。

在同一执行链中推送状态变化和事件。两者会在同一次去抖突发中排队，并合并为一次刷新。

// Blueprint 伪代码
事件 CommanderDown
  → ConvaiBotComponent → 设置上下文状态
      名称：          "CommanderStatus"
      值：         "KIA"
      ShouldRespond：永不
  → ConvaiBotComponent → 添加上下文事件
      文本：          "指挥官已被消灭——接管指挥"
      ShouldRespond：始终

因为该事件使用 始终，合并后的更新会与 run_llm 设置为 "true".

本地验证： 该 CommanderStatus 状态在刷新到达 Convai 后，会与事件一起出现在同一有效载荷中。

关卡重启时重置上下文

场景： 玩家重新开始模拟时，应丢弃之前的所有运行时状态。

// Blueprint 伪代码
事件 OnLevelRestart
  → ConvaiBotComponent → 重置动态上下文
  → ConvaiBotComponent → 停止会话
  → ConvaiBotComponent → 开始会话

重置动态上下文 会清空已暂存的内容，发送一个 Reset 上下文更新，然后清除跟踪器。 停止会话 是位于 开始会话 会在该重置后重新连接；它们本身不会清除跟踪器。

本地验证： 获取上下文状态值 返回 false 在重置完成后针对上一次运行的键。

下一步

动态上下文 Blueprint 参考动态上下文故障排查