> 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/sync-behavior-and-timing.md).

# 同步行为与时序

了解动态上下文如何在去抖后刷新、Wait Until Conversation Is Idle 如何保持更新，以及离线排队如何工作。

动态上下文更新不会在每次调用蓝图时都发送到 Convai。默认情况下，插件会短暂等待，让快速连续的更改合并为一次发送；每个变更函数还带有一个单独的 `Delivery` 选项，可将更新暂缓，直到对话自然停顿时再发送。本页说明何时会执行刷新、每次刷新包含哪些内容、暂缓的更新何时会实际发送，以及何时可以绕过这两种等待。

### 何时发送更新

| 情况                                                                                    | 发生的情况                                                                                                                                        |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 已连接时的默认防抖调用， `Delivery` = `Send Normally`                                             | 更新先在本地暂存；在窗口内没有新更新后，经过 `Replace` `context-update` 发送一次，等待时间为 `ContextDebounceWindow` （默认 `0.5` 秒）                                            |
| 快速连续更新                                                                                | 连续更新中的所有更改会合并为一次刷新；每次调用都会重置计时器，但从首次更新开始的总等待时间不会超过 `ContextMaxDebounceWindow` （默认 `3.0` 秒）                                                    |
| `Delivery` = `Wait Until Conversation Is Idle`，聚合后的 `ShouldRespond` 为 `Auto`/`Always` | 更新会暂缓，不会纳入防抖批次，直到对话持续静默达到 `Quiet Time Before Delivery (s)` （默认 `2.0` 秒），然后执行刷新。请参阅 [暂缓的更新何时会实际发送](#when-a-held-update-is-actually-delivered) |
| `Delivery` = `Wait Until Conversation Is Idle`，聚合后的 `ShouldRespond` 为 `Never`         | 不适用暂缓机制——静默更新没有可打断的内容，因此会通过常规防抖流程正常发送                                                                                                        |
| `bFlushImmediately = true` 连接后， `Delivery` = `Send Normally`                          | `FlushDynamicContext()` 会在当前帧执行，绕过防抖                                                                                                         |
| `bFlushImmediately = true` 连接后， `Delivery` = `Wait Until Conversation Is Idle`        | 仍然会等待一段安静时间，但会在首次出现安静时立即发送，而不是等完整的 `Quiet Time Before Delivery (s)` 时间窗口结束                                                                   |
| 会话连接前的更新                                                                              | 更改会累积在 `PendingContextBatch`中；连接后且防抖截止时间到达时首次刷新                                                                                              |
| `Reset Dynamic Context`                                                               | 先排空暂存内容，然后发送一个 `Reset` `context-update`，然后清除本地跟踪器                                                                                            |

### 实际发送暂存更新时

`Set Context State`, `Set Context States`和 `Add Context Event` 各自都提供一个 `Delivery` 参数（`EConvaiContextDelivery`）。防抖和发送是两个独立的等待阶段，并按顺序执行：

1. **防抖** (`ContextDebounceWindow`, `ContextMaxDebounceWindow`）决定一批暂存更新何时可以从客户端发出。
2. **发送** 决定已就绪的更新是立即发送，还是先等待对话进入静默状态。

将 `Delivery` 设为 `Wait Until Conversation Is Idle` 的更新会被暂缓，而不会加入常规防抖批次。只有在对话持续静默达到 `Replace` `context-update`后，它才会被释放并作为 `Quiet Time Before Delivery (s)` （即 `ConversationIdleSettleSeconds` 属性，默认值为 `2.0` 秒）刷新。任何对话活动——角色说话或用户说话——都会重新开始这段静默计时。这里有意不设总暂缓时长的上限，因此等待中的更新绝不会打断正在进行的交流；对话持续多久，它就可以等待多久。暂缓的 `Add Context Event` 最终发送时会添加到事件历史的末尾，因此仍会被视为最近发生的事件。

只有当批次聚合后的 `ShouldRespond` 为 `Auto` 或 `Always`时才会暂缓。（静默的`Never`) 更新没有可中断的内容，因此 `Delivery` 对它不起作用，它始终通过常规防抖路径发送。

`bFlushImmediately = true` 改变的是等待条件，而不是是否等待：当 `Delivery` 设为 `Wait Until Conversation Is Idle`时，即时调用仍会等待一段安静时间，但会在检测到第一个安静时刻时立即发送，而不是等满整个 `Quiet Time Before Delivery (s)` 时间窗口。

### 传输消息格式

`UConvaiSubsystem::UpdateContext` 会发送一条带有 JSON 数据负载的 `context-update` 消息：

| JSON 字段                    | 取值（线上格式）                      | 出现条件                                                        |
| -------------------------- | ----------------------------- | ----------------------------------------------------------- |
| `mode`                     | `append`, `replace`, `reset`  | 每条消息中均存在                                                    |
| `run_llm`                  | `"auto"`, `"true"`, `"false"` | 每条消息中均存在——映射自 `EC_RunLLMOption` (`Auto`, `Always`, `Never`) |
| `text`                     | 上下文字符串                        | 在以下情况下省略： `Reset` 且文本为空                                     |
| `current_attention_object` | 对象名称字符串                       | 注意对象与其合并到同一条消息时                                             |

蓝图枚举显示名称（`Append`, `Replace`, `Reset`, `Auto`, `Always`, `Never`）与上述线上字符串不同。

### 刷新负载结构

每次刷新若包含暂存状态或事件，都会构建一个文本负载：

```
{StateName} is {Value}
{AnotherState} is {Value}
Event text line one
{Key} 从 {OldValue} 更改为 {NewValue}
{NewKey} 为 {NewValue}
```

第一个区块是 **规范上下文** — 按插入顺序排列的状态（`"{Key} is {Value}"` 每行一个），后面按时间顺序排列事件。它由以下内容构建： `FConvaiDynamicContextTracker::BuildCanonicalContext()`.

当批次的聚合 `ShouldRespond` 不是 `Never` 且存在状态差异行时，插件会将它们追加到 **下一行** 即规范上下文之后（一个 `\n` 分隔符，而不是空行）。差异行会在提示末尾显示状态变化。

对于新值包含超过三个以空白字符分隔的单词的状态更新，差异行使用 `"{Key} changed from {OldValue}"` 而不重复较长的新值。

### 活动会话期间的场景

#### 新状态 — 聚合 `ShouldRespond` 为 `Never`

**触发调用：** `Set Context State` 或 `Set Context States` 使用此前未设置过的键，并且批次中的每个暂存项都保持聚合值 `ShouldRespond` 为 `Never`.

新键会立即进入规范上下文。不会添加差异行。

```
设施是阿尔法海上平台
```

#### 新状态 — 聚合 `ShouldRespond` 为 `Auto` 或 `Always`

**触发调用：** `Set Context State` 或 `Set Context States` 使用新键，并且至少有一个暂存项将聚合值提升为 `ShouldRespond` 至 `Auto` 或 `Always`.

在这次刷新中，新键 **不会被纳入** 规范区块。类似 `Health is 50` 这样的增量行会追加在规范区块之后。

```
区域为 Market District
Health is 50
```

在 **下一次刷新**时，该键会正常进入规范区块。

#### 更新现有状态 — 聚合 `ShouldRespond` 为 `Never`

**触发调用：** `Set Context State` 调用中包含一个现有键，且批次将聚合 `ShouldRespond` 保持为 `Never`.

更新后的值会进入规范区块。不会添加增量行。

```
区域为 Docks
```

#### 更新现有状态 — 聚合 `ShouldRespond` 为 `Auto` 或 `Always`

**触发调用：** `Set Context State` 调用中包含一个现有键，且至少有一个暂存项会将聚合 `ShouldRespond` 提升为 `Auto` 或 `Always`.

更新后的值会进入规范区块。会追加一条描述状态转换的增量行。

```
区域为 Docks
区域从 Market District 更改为 Docks
```

#### 同时更新多个状态

**触发调用：** `Set Context States` 调用中包含键值对映射，可能同时包含新键和现有键。

所有值都会写入跟踪器。当聚合值不是 `Never`时，每个新键都适用首次出现延迟。所有更改共用一次刷新 — 一条 `Replace` `context-update`.

```
区域为 Docks
场景为 Active
区域从 Market District 更改为 Docks
难度为 Hard
```

#### 添加上下文事件

**触发调用：** `Add Context Event`.

事件文本会提交到跟踪器的事件列表中，并出现在规范上下文中。普通上下文事件不会重复添加为单独的增量行。

在同一防抖窗口内多次暂存的相同事件字符串会被去重——每次刷新只保留第一次出现的字符串。

```
区域为 Docks
玩家已到达撤离点
```

#### 移除上下文状态

**触发调用：** `Remove Context State`.

该键会从跟踪器中移除。 `bForceReplace` 会被设置，以便刷新时发送不含已移除键的规范上下文。移除操作不会添加增量行。

#### 重置动态上下文

**触发调用：** `Reset Dynamic Context`.

插件会先处理完暂存的上下文批次，然后发送一条  `Reset` `context-update` (`mode: reset`, `run_llm: "false"`），其中没有  `text` 字段，以表示空的  `Reset` 负载。本地跟踪器会在  `Reset` 消息之后清空。

调用  `Reset Dynamic Context` 时已存在的排队触发器会立即清除。在离线时待处理的  `Reset` 之后加入队列的触发器，仍可能在  `Reset` 之前由以下函数处理： `FlushDynamicContext()`.

连接时， `Reset Dynamic Context` 会立即调用刷新流程。离线时，重置标志会等到连接后的首次刷新才生效。

### 会话前排队

默认的防抖变更调用—— `Set Context State`, `Set Context States`, `Add Context Event`, `Remove Context State`以及 `Reset Dynamic Context` ——会累积在  `PendingContextBatch`  中；当  `IsChatbotConnected()` 为  `false`.

`TickDynamicContext()` 会继续累积，直到会话连接。连接后，防抖期限到达时， `FlushDynamicContext()` 会发送待处理批次。

离线更新会合并为上述刷新行为，而不是按顺序重放为多条独立消息。连接后，在防抖期限已过的第一个 tick 中，如果批次的聚合 `ShouldRespond` 仍为 `Never` 则发送跟踪器中的当前规范快照；聚合值为 `Auto` 或 `Always` 的批次则遵循上述规范快照加增量的行为。任何待处理的 `Reset` 操作最后清除上下文。

```
// BeginPlay — 会话连接前，三项操作都会安全地进入队列
Set Context State  Name="Facility"  Value="Offshore Platform Alpha"
Set Context State  Name="Scenario"  Value="Fire Drill"
Add Context Event  Text="Session initialized"  ShouldRespond=Never

// 连接后且防抖期限已过 — 先执行一次 Replace context-update，再执行已排队的 Reset：
// Facility is Offshore Platform Alpha
// Scenario is Fire Drill
// Session initialized
```

如果 `Reset Dynamic Context` 及后续更新都在离线期间待处理，刷新时会先发送暂存内容，然后 `Reset` 最后执行。

{% hint style="warning" %}
对于必须送达的上下文，不要在连接前使用 `bFlushImmediately = true` 。立即刷新会绕过断开连接时的 tick 保护，并可能在有效会话能够发送之前清除暂存的工作。
{% endhint %}

### `bFlushImmediately`

每个变更函数—— `Set Context State`, `Set Context States`, `Add Context Event`, `Remove Context State` ——都提供一个 **`Advanced`** 参数 `bFlushImmediately`。当该参数为 `true`, `时，` FlushDynamicContext()

会在当前帧运行。 `对于默认防抖延迟会造成明显滞后的时间敏感型更新，请使用` 。每次立即调用都会在当前帧运行 `FlushDynamicContext()` ，并在聊天机器人已连接且存在可发送的暂存工作时发送 `context-update` 。对于持续变化的值，请避免每个 tick 都调用它。

`重置动态上下文` 连接时会立即调用刷新路径。它没有 `bFlushImmediately` 参数。

`bFlushImmediately` 不会覆盖 `Delivery`。当更新时，若 `Delivery` 设置为 `等待对话空闲`, `bFlushImmediately` 仍会等待对话静下来——请参见 [暂存的更新实际发送时](#when-a-held-update-is-actually-delivered) ——它只是跳过完整的 `发送前静默时间 (s)` 等待时段（检测到静默后）。

{% hint style="warning" %}
高频使用 `bFlushImmediately` ——例如，同步每帧都会更新的值——在连接时每次调用都可能生成一个 `context-update` 。对于持续变化的值，请使用默认的防抖行为。
{% endhint %}

### 后续步骤

{% 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 %}

{% 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 %}


---

# 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/sync-behavior-and-timing.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.
