> 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 角色学习运行时信息的一种方式，这些信息在会话开始时不可用——或尚未发生——。你从 Blueprint 推送更新；插件会将它们本地存储、批量处理快速变更，并将组装好的载荷发送到 Convai。

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

| 通道    | 它表示什么      | Blueprint 节点          | 示例              |
| ----- | ---------- | --------------------- | --------------- |
| State | 一个可替换的当前事实 | `设置上下文状态` / `设置上下文状态` | `Health` 为 `80` |
| 事件    | 会话中的一次性时刻  | `Add Context Event`   | `4 区触发了警报`      |

### 状态属性和事件

A **状态属性** 是一个有名称的键值对，表示一个当前、可替换的事实—— `Health` 为 `80`, `区域` 为 `市场区`, `QuestActive` 为 `true`. `设置上下文状态` 是位于 `设置上下文状态` 会立即写入本地跟踪器。在刷新时，插件会发送一条 `Replace`-模式 `上下文更新` 其文本为规范上下文，下一行可选附加增量行。

一条 **事件** 是一个自由格式的时间顺序字符串—— `玩家拾取了红色钥匙`, `4 区触发了警报`. `Add Context Event` 会将文本暂存到待处理批次中。在刷新时，该事件会提交到跟踪器的时间顺序事件列表，并包含在规范上下文中。常规上下文事件不会被复制到单独的增量行中。

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

### 角色接收到什么

在刷新时，插件会将所有活动状态和事件组装成一个以换行分隔的上下文字符串：

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

状态会首先出现，按插入顺序排列。更新值不会移动其位置。事件则按时间顺序排列。

```
// Blueprint 伪代码——更新状态时会保留插入顺序
Set Context State  Name="Zone"   Value="市场区"   ShouldRespond=Never
Set Context State  Name="Health" Value="80"                ShouldRespond=Never
Add Context Event  Text="玩家拾取了红色钥匙"     ShouldRespond=Auto
Set Context State  Name="Zone"   Value="码头区"             ShouldRespond=Never
```

四次调用后的规范上下文：

```
Zone 是 码头区
Health 是 80
玩家拾取了红色钥匙
```

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

### 防抖批处理

对……的调用 `设置上下文状态`, `设置上下文状态`，以及 `Add Context Event` 会安排一次防抖刷新，而不是立即发送。 `移除上下文状态` 仅当本地跟踪器中存在该键时，才会安排一次防抖刷新。

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

| 属性                         | 详情面板标签       | 默认值   | 含义                                      |
| -------------------------- | ------------ | ----- | --------------------------------------- |
| `ContextDebounceWindow`    | `上下文防抖窗口（秒）` | `0.5` | 在最近一次暂存更新后，等待这么多秒再刷新。窗口内的每次新更新都会重置计时器。  |
| `ContextMaxDebounceWindow` | `最大防抖窗口（秒）`  | `3.0` | 对突发事件首次更新起算的总延迟设置硬上限。可防止连续不断的更新无限期推迟刷新。 |

防抖计时器在突发中的第一条更新到达时启动。后续更新会将计时器重置为 `ContextDebounceWindow` 自最近一次调用起，但绝不会延长超过 `ContextMaxDebounceWindow` 自突发开始起算。当计时器触发时，所有暂存的更改会合并为一条 `上下文更新` 消息。

这两个属性都标记为 `高级显示` 位于 `Convai > DynamicContext` 在详情面板中。

### 角色可能响应时

每个暂存的状态或事件都带有自己的 `ShouldRespond` 值。批次会将它们合并为一个聚合等级： `始终` > `Auto` > `从不`。刷新时会发送一条 `上下文更新` ，并将该聚合值作为 `run_llm`.

聚合等级控制是否输出状态增量行：

* **聚合 `从不`** ——不输出增量行。新的状态键会立即进入规范上下文，以便 Convai 保留它们。
* **聚合 `Auto` 或 `始终`** ——增量行会附加在规范块之后（以单个换行符分隔）。该批次中的全新状态键在该次刷新时会从规范中排除，仅作为增量行出现；它们会在下一次刷新时进入规范。

按键 `ShouldRespond` 在单独调用中仍会计入聚合等级，但当聚合不是时，首次出现延后规则会适用于批次中的每个新状态键 `从不`.

### 立即刷新

每个修改函数都提供一个 `高级` 参数 `bFlushImmediately`。当 `true`，插件会调用 `FlushDynamicContext()` 在当前帧中执行，绕过防抖计时器。仅在聊天机器人连接后对时间敏感的更新使用此功能。高频使用可能会发送一条 `上下文更新` 在连接且有暂存工作时，每次调用

`重置动态上下文` 不提供 `bFlushImmediately`。当角色已连接时，它会立即调用刷新路径；离线时，则会将重置排队到下次连接后的刷新中。

### 会话前排队

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

你可以从……填充初始状态 `BeginPlay` ，而无需延迟执行或连接保护：

```
// Blueprint 伪代码——可在 Start Session 之前从 BeginPlay 调用
Event BeginPlay
  → Set Context State  Name="Facility"  Value="海上平台 Alpha"  ShouldRespond=Never
  → Set Context State  Name="Scenario"  Value="消防演练"               ShouldRespond=Never
  → Add Context Event  Text="会话已初始化"                         ShouldRespond=Never
```

### 重置顺序

`重置动态上下文` 会标记 `bPendingReset` 在待处理批次上。当连接时，它会立即刷新；当断开连接时，它会将重置安排到下次连接后的刷新中。它不会 **不是** 在一开始就清空跟踪器或丢弃已暂存的更新。在刷新时：

1. 暂存的状态、事件和可选注意力会作为一条 `Replace` `上下文更新`.
2. 如果已排队，待处理的环境元数据也会一并排出。那些在……时已经存在的已排队叙事触发器 `重置动态上下文` 被该重置请求清除；在待处理的离线 `Reset` 之后排队的触发器仍可能在……之前排出 `Reset`.
3. A `Reset` `上下文更新` 最后触发（`模式：重置`, `run_llm: "false"`时，不会 `text` 空的……字段 `Reset` 载荷），然后清空本地跟踪器。

如果您调用 `重置动态上下文` 并在同一个离线窗口中暂存新更新，则首次连接后的刷新会先传递暂存内容，然后再 `Reset` 清除远程和本地上下文。若你打算从空的动态层开始，请先让重置刷新完成，再暂存新数据。

### 批次内事件去重

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

### 动态环境信息是独立通道

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

### 何时使用哪个函数

| 目标           | 使用                                                     |
| ------------ | ------------------------------------------------------ |
| 跟踪一个当前条件     | `设置上下文状态`                                              |
| 跟踪多个会同时变化的条件 | `设置上下文状态`                                              |
| 记录某事已发生      | `Add Context Event`                                    |
| 移除不再适用的条件    | `移除上下文状态`                                              |
| 清除所有运行时上下文   | `重置动态上下文`                                              |
| 发送外部构造的上下文文本 | `更新上下文` ——绕过跟踪器                                        |
| 推送会话级自由格式备注  | `DynamicEnvironmentInfo` ——独立 `update-dynamic-info` 通道 |

### 下一步

{% content-ref url="/pages/752c51862623321d86861772e63c55db752c58da" %}
[同步行为和时序](/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" %}
[动态上下文快速入门](/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 参考](/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/how-dynamic-context-works.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.