> 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/how-dynamic-context-works.md).

# 动态上下文的工作原理

了解动态上下文如何跟踪运行时状态、批处理事件、选择响应行为并为 Convai 组装载荷。

动态上下文是指 Convai 角色如何获知会话开始时尚不可用或尚未发生的运行时信息。你可以通过蓝图推送更新；插件会在本地存储这些更新，将短时间内的多次更改合并批处理，并向 Convai 发送组装好的负载。

{% embed url="<https://www.youtube.com/watch?v=MPbr3b6r9bo>" %}
Unreal Engine 中的动态上下文：端到端详解
{% endembed %}

可以把动态上下文看作两个通道：

| 通道 | 含义        | 蓝图节点                                       | 示例                            |
| -- | --------- | ------------------------------------------ | ----------------------------- |
| 状态 | 可替换的当前事实  | `Set Context State` / `Set Context States` | `Health` 是 `80`               |
| 事件 | 会话中的一次性时刻 | `Add Context Event`                        | `Alarm triggered in sector 4` |

### 状态属性和事件

一个 **状态属性** 是一个带名称的键值对，用于表示当前且可替换的事实—— `Health` 是 `80`, `Zone` 是 `Market District`, `QuestActive` 是 `true`. `Set Context State` 和 `Set Context States` 会立即写入本地跟踪器。到刷新时，插件会发送一条 `Replace`模式的 `context-update` 消息，其文本为规范上下文，并可选择在下一行附加增量行。

一个 **事件** 是按时间顺序排列的自由格式字符串—— `Player picked up the red key`, `Alarm triggered in sector 4`. `Add Context Event` 会将文本暂存到待处理批次中。刷新时，事件会提交到跟踪器的时间顺序事件列表，并纳入规范上下文。常规上下文事件不会重复写入单独的增量行。

| 通道   | 可替换       | 典型用途            |
| ---- | --------- | --------------- |
| 状态属性 | 是——仅保留最新值 | 当前生命值、区域、装备配置   |
| 事件   | 否——仅追加    | 警报、里程碑、一次性的叙事节点 |

### 角色接收到的内容

刷新时，插件会根据所有启用的状态和事件，组装成以换行符分隔的上下文字符串：

```
{StateName} 是 {Value}
{AnotherState} 是 {Value}
事件文本第一行
事件文本第二行
```

状态优先显示，并按插入顺序排列。更新值不会改变其位置。事件则按时间顺序排列。

```
// Blueprint 伪代码 — 更新状态时会保留插入顺序
Set Context State  Name="Zone"   Value="Market District"   ShouldRespond=Never
Set Context State  Name="Health" Value="80"                ShouldRespond=Never
Add Context Event  Text="Player picked up the red key"     ShouldRespond=Auto
Set Context State  Name="Zone"   Value="Docks"             ShouldRespond=Never
```

执行以上四次调用后的规范化上下文：

```
Zone 为 Docks
Health 为 80
Player picked up the red key
```

您提供名称、值和事件文本。插件会在刷新时组装并发送规范化字符串。

### 防抖批处理

对 `Set Context State`, `Set Context States`和 `Add Context Event` 的调用会安排一次防抖刷新，而不是立即发送。 `Remove Context State` 仅当键存在于本地跟踪器中时，才会安排一次防抖刷新。

短时间内的快速更新会合并为一次发送。 `UConvaiChatbotComponent` 上的两个属性用于控制时序：

| 属性                         | Details 面板标签 | 默认值   | 含义                                           |
| -------------------------- | ------------ | ----- | -------------------------------------------- |
| `ContextDebounceWindow`    | `上下文防抖窗口（秒）` | `0.5` | 在最近一次暂存更新后，等待指定秒数再刷新。在此时间窗口内的每次新更新都会重置计时器。   |
| `ContextMaxDebounceWindow` | `最大防抖窗口（秒）`  | `3.0` | 从一连串更新中的首次更新开始计算的总延迟上限。这样可以防止持续不断的更新流无限推迟刷新。 |

一连串更新中的首次更新到达时，防抖计时器便会启动。后续更新会从最近一次调用开始重新计时，时长为 `ContextDebounceWindow` ，但不会超过从这组更新开始时起算的 `ContextMaxDebounceWindow` 。计时器触发时，所有暂存的更改会合并为一条 `context-update` 消息。

这两个属性在 Details 面板的 `Advanced Display` 下的 `Convai > DynamicContext` 中标记为高级显示。

### 角色何时可以响应

每个暂存的状态或事件都有自己的 `ShouldRespond` 值。批次会将这些值合并为一个总等级： `Always` > `Auto` > `Never`。刷新会发送一条 `context-update` ，其聚合值为 `run_llm`.

聚合等级决定是否输出状态差异行：

* **聚合等级 `Never`** — 不输出差异行。新的状态键会立即加入规范块，以便 Convai 保留这些键。
* **聚合等级 `Auto` 或 `Always`** — 差异行会追加到规范块之后（以单个换行符分隔）。本批次中全新的状态键不会在本次刷新时加入规范块，而只会作为差异行出现；它们会在下一次刷新时加入规范块。

单个键上的 `ShouldRespond` 仍会计入聚合等级，但当聚合等级不是 `Never`.

### 立即刷新

每个变更函数都提供一个 `Advanced` 参数 `bFlushImmediately`。当 `true`时，插件会在当前帧调用 `FlushDynamicContext()` ，绕过防抖计时器。仅在聊天机器人连接后，用于时间紧迫的更新。高频使用时，如果已连接且有待处理的工作，每次调用都可能发送一条 `context-update` 。

`Reset Dynamic Context` 不提供 `bFlushImmediately`。角色连接时，它会立即调用刷新路径；离线时，则会将重置操作排入队列，等待连接后进行下一次刷新。

### 会话前排队

默认情况下，在 `IsChatbotConnected()` 返回 `true` 之前发出的防抖调用会累积到 `PendingContextBatch`. `TickDynamicContext()` 在断开连接时会提前返回，因此不会发送消息。会话连接后，下一次达到防抖期限的 tick 会调用 `FlushDynamicContext()` ，并将待处理批次作为一条 `Replace`模式快照发送。对于必须送达的数据，不要在连接前使用 `bFlushImmediately = true` ，因为这会绕过断开连接时的 tick 保护。

你可以从 `BeginPlay` 无需延迟执行或连接状态检查：

```
// 蓝图伪代码——可以安全地在 BeginPlay 中于 Start Session 之前调用
Event BeginPlay
  → Set Context State  Name="Facility"  Value="Offshore Platform Alpha"  ShouldRespond=Never
  → Set Context State  Name="Scenario"  Value="Fire Drill"               ShouldRespond=Never
  → Add Context Event  Text="Session initialized"                         ShouldRespond=Never
```

### 重置顺序

`Reset Dynamic Context` 会在待处理批次中标记 `bPendingReset` 。已连接时，它会立即刷新；未连接时，它会安排在下次连接后的刷新中执行重置。它 **不会** 预先清除跟踪器或丢弃暂存的更新。刷新时：

1. 暂存的状态、事件和可选的注意力信息会作为一条 `Replace` `context-update 消息发送。`.
2. 待处理的环境元数据如果已排队，则会被发送。调用 `Reset Dynamic Context` 时已存在的排队叙事触发器会被该重置请求清除；但在离线待处理的 `Reset` 之后排队的触发器仍可能在重置之前发送。 `Reset`.
3. 一条 `Reset` `context-update` 消息最后发送（`mode: reset`, `run_llm: "false"`，空载荷不包含 `text` 字段 `Reset` ），随后清除本地跟踪器。

如果在同一离线期间调用 `Reset Dynamic Context` 并暂存新的更新，连接后的首次刷新会先发送暂存内容，然后由 `Reset` 清除远程和本地上下文。如果希望从空的动态层开始，请等重置刷新完成后再暂存新数据。

### 批次内的事件去重

在同一防抖窗口内多次暂存的相同事件字符串会被去重——该次刷新只保留第一次出现的内容。同一批次中不同的事件字符串则会按时间顺序全部保留。

### 动态环境信息使用独立通道

`DynamicEnvironmentInfo` 是一个 `FString` 类型的属性，属于 `UConvaiChatbotComponent`。当会话代理存在时，更改该属性会调用 `update-dynamic-info` 并传入 `dynamic_info.text` ；参与者连接时也会发送该值。它不由 `FConvaiDynamicContextTracker 跟踪。` 且不会经过防抖批处理。请参阅 [连接时的静态上下文](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/static-context-at-connection-time.md).

### 何时使用哪个函数

| 目标           | 用途                                                     |
| ------------ | ------------------------------------------------------ |
| 跟踪一个当前条件     | `Set Context State`                                    |
| 跟踪多个同时变化的条件  | `Set Context States`                                   |
| 记录某件事已经发生    | `Add Context Event`                                    |
| 移除不再适用的条件    | `Remove Context State`                                 |
| 清除所有运行时上下文   | `Reset Dynamic Context`                                |
| 发送外部构造的上下文文本 | `Update Context` — 绕过跟踪器                               |
| 推送会话级自由格式备注  | `DynamicEnvironmentInfo` — 独立 `update-dynamic-info` 通道 |

### 后续步骤

{% content-ref url="/pages/752c51862623321d86861772e63c55db752c58da" %}
[同步行为与时序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/sync-behavior-and-timing.md)
{% endcontent-ref %}

{% content-ref url="/pages/602e67296ec3ed2b843879adb48efa844ab06ec3" %}
[动态上下文快速开始](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/a80705d8480f2f63dc8b84ea2e437c9dac45b7c5" %}
[动态上下文 Blueprint 参考](https://docs.convai.com/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" %}
[排查动态上下文问题](https://docs.convai.com/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/how-dynamic-context-works.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.
