> 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 方案。

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

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

### 在会话连接前预置上下文

**场景：** 一个安全培训关卡会将设施和场景事实设置到 `BeginPlay` 中，在自动初始化完成之前。

默认的防抖调用会在会话连接前安全排队。连接建立并达到防抖截止时间后，第一次刷新会发送一个 `替换` `上下文更新` 以及组装好的快照。

```
// Blueprint 伪代码 — 在角色 Actor 的 Event BeginPlay 中
→ Set Context State  Name="设施"  Value="海上平台 Alpha"  ShouldRespond=Never
→ Set Context State  Name="场景"  Value="消防演练"               ShouldRespond=Never
→ 添加上下文事件  Text="学员简报完成"                   ShouldRespond=Never
```

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

### 跟踪玩家生命值

**场景：** 一个医疗培训模拟，教官角色在被询问时会评论学员的生命体征。

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

```
// 蓝图伪代码
事件 HealthChanged（NewHealth: float）
  → ConvaiBotComponent → 设置上下文状态
      Name:          "PlayerHealth"
      Value:         ToString(NewHealth)
      ShouldRespond: Never
```

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

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

**场景：** Blueprint 条件会在发送重复事件之前检查角色是否已经知道有一个正在进行的警报。

```
// 蓝图伪代码
→ 获取上下文状态值
    Name:     "AlertActive"
    OutValue: → 根据 OutValue == "true" 分支
如果为假：
  → 设置上下文状态
      Name:          "AlertActive"
      Value:         "true"
      ShouldRespond: Auto
  → 添加上下文事件
      Text:          "已激活安全警报"
      ShouldRespond: Auto
```

**在本地验证：** **获取上下文状态值** 会立即返回当前值——无需网络往返。在 **设置上下文状态** 运行后，返回引脚为 `true` 和 `OutValue` 一致。

### 播报叙事事件

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

```
// 蓝图伪代码
事件 AlarmActivated
  → ConvaiBotComponent → 添加上下文事件
      Text:          "3 号舱位已触发火警"
      ShouldRespond: Always
```

在防抖窗口结束后（默认 `0.5` 秒），插件会刷新 `上下文更新` 使用 `run_llm` 设置为 `"true"`。如果希望在会话连接后更快刷新，请设置 `bFlushImmediately = true` 在 **添加上下文事件** 节点一起暂存。

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

### 只提醒角色一次，而不会累积

**场景：** 一个谜题房间中，提示道具会闪烁，而角色在下一次上下文刷新时应注意到它，但这种闪烁本身并不是世界永久状态的一部分。

设置 `bEphemeral = true` 在 **添加上下文事件**。角色会在下一次更新时恰好看到一次该事件，并且它永远不会被提交到持久化上下文中——它不会在后续更新中再次出现，也不需要匹配的 **移除上下文状态** 调用来清理它。

```
// 蓝图伪代码
事件 HintPropFlickered
  → ConvaiBotComponent → 添加上下文事件
      Text:        "墙面面板短暂闪烁了一下"
      ShouldRespond: Auto
      bEphemeral:  true
```

**在本地验证：** 在不同的防抖窗口中触发两次该事件，并确认角色每次都会作出反应——持久化的 `添加上下文事件` 只会把第二次出现添加到不断增长的历史中，而临时事件两次都会以相同方式到达并清除。

### 用一次性的提示设置对象关注

**场景：** 一个导游角色应该转向并关注玩家高亮的任意展品，并在注意力被查询时简短地确认新的焦点，而不是每次都重复这种确认。

`SetObjectInAttention` （类别 `Convai|Actions`）默认会发出一次性的关注提示—— `bAddAttentionEvent = true` ——因此角色会像处理临时上下文事件一样，只对新的焦点作出一次反应。将 `bAddAttentionEvent = false` 可在不发声的情况下更改焦点。

```
// 蓝图伪代码
事件 PlayerHighlightedExhibit（Exhibit: FConvaiObjectEntry）
  → ConvaiBotComponent → SetObjectInAttention
      AttentionObject:    展品
      ShouldRespond:       Auto
      bAddAttentionEvent:  true   // 默认值——省略即可保持原样
```

**在本地验证：** 刷新后，角色的下一条回复会一次提到该展品。再高亮另一个展品时，会为该对象生成一个新的提示，而不是累积玩家关注过的每个对象的历史记录。

### 在场景转换后更新多个状态

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

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

```
// 蓝图伪代码
事件 EnteredConferenceRoom
  → ConvaiBotComponent → 设置上下文状态
      States: {
        "CurrentZone": "B 会议室",
        "AvailableEquipment": "投影仪、白板",
        "TimeOfDay": "14:30"
      }
      ShouldRespond: Auto
```

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

### 在条件结束时移除一个状态

**场景：** 某个训练道具已被使用，不应再属于角色的感知范围。

```
// 蓝图伪代码
事件 ItemUsed（ItemName: FString）
  → ConvaiBotComponent → 移除上下文状态
      Name: ItemName
```

**在本地验证：** 在防抖刷新后， **获取上下文状态值** 返回 `false` 用于已移除的键。

### 将状态和事件结合，用于一个关键时刻

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

在同一执行链中推送状态变更和事件。两者会在同一次防抖突发中暂存，并合并为一次刷新。

```
// 蓝图伪代码
事件 CommanderDown
  → ConvaiBotComponent → 设置上下文状态
      Name:          "CommanderStatus"
      Value:         "KIA"
      ShouldRespond: Never
  → ConvaiBotComponent → 添加上下文事件
      Text:          "指挥官已被消灭——接管指挥"
      ShouldRespond: Always
```

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

**在本地验证：** 该 `CommanderStatus` 状态一起作为同一载荷发送，并在刷新到达 Convai 后可用。

### 在关卡重启时重置上下文

**场景：** 玩家重新启动一个模拟，所有先前的运行时状态都应被丢弃。

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

**重置动态上下文** 会清空暂存内容，发送一个 `重置` `上下文更新`，然后清除追踪器。 `停止会话` 和 `开始会话` 在该重置之后重新连接；它们不会自行清除追踪器。

**在本地验证：** **获取上下文状态值** 返回 `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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.