> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-usage-examples.md).

# 动态上下文使用示例

这些示例展示了在 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` 在重置完成后针对上一次运行的键。

### 下一步

{% content-ref url="/pages/a80705d8480f2f63dc8b84ea2e437c9dac45b7c5" %}
[动态上下文 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/b420c88b0fe545f2bdf932b279270d9c5974103c" %}
[动态上下文故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-usage-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.