> 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).

# 同步行为和时序

动态上下文更新不会在每次 Blueprint 调用时都发送到 Convai。默认情况下，插件会短暂等待，使快速变化合并为一次发送。本页说明何时会刷新、每次刷新包含什么，以及何时绕过防抖计时器。

### 何时发送更新

| 情况                              | 发生什么                                                                                |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| 连接时的默认防抖调用                      | 更新会先在本地暂存；一次 `替换` `context-update` 会在 `ContextDebounceWindow` （默认 `0.5` 秒）内没有新更新时发送 |
| 快速突发的更新                         | 突发中的所有更改会合并为一次刷新；计时器会在每次调用时重置，但不会超过 `ContextMaxDebounceWindow` （默认 `3.0` 秒）自首次更新起   |
| `bFlushImmediately = true` 在连接后 | `FlushDynamicContext()` 会在当前帧运行，绕过防抖                                                |
| 会话连接前的更新                        | 更改会累积到 `PendingContextBatch`；首次刷新会在连接后和防抖截止时间到达时发生                                  |
| `重置动态上下文`                       | 先清空暂存内容，然后发送一个 `Reset` `context-update`，随后清除本地跟踪器                                   |

### 传输消息形式

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

| JSON 字段                    | 值（线上格式）                       | 何时出现                                                  |
| -------------------------- | ----------------------------- | ----------------------------------------------------- |
| `mode`                     | `append`, `replace`, `reset`  | 每条消息都会出现                                              |
| `run_llm`                  | `"auto"`, `"true"`, `"false"` | 每条消息都会出现 — 映射自 `EC_RunLLMOption` (`Auto`, `始终`, `从不`) |
| `文本`                       | 上下文字符串                        | 在 `Reset` 文本为空时省略                                     |
| `current_attention_object` | 对象名称字符串                       | 当注意对象被折叠进同一条消息时                                       |

Blueprint 枚举显示名称（`Append`, `替换`, `Reset`, `Auto`, `始终`, `从不`）与上面的线上字符串不同。

### 刷新负载结构

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

```
{StateName} 是 {Value}
{AnotherState} 是 {Value}
事件文本第一行
{Key} 从 {OldValue} 更改为 {NewValue}
{NewKey} 是 {NewValue}
```

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

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

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

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

#### 新状态 — 聚合 `ShouldRespond` 是 `从不`

**触发调用：** `设置上下文状态` 或 `设置上下文状态` 使用一个之前从未设置过的键，并且批次中的每个暂存项都保持聚合 `ShouldRespond` 在 `从不`.

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

```
设施是 Offshore Platform Alpha
```

#### 新状态 — 聚合 `ShouldRespond` 是 `Auto` 或 `始终`

**触发调用：** `设置上下文状态` 或 `设置上下文状态` 使用一个新键，并且至少有一个暂存项会提升聚合 `ShouldRespond` 设为 `Auto` 或 `始终`.

在这次刷新中，新键会 **被排除** 在规范上下文之外。会在规范块之后追加一条类似 `Health 是 50` 的增量行。

```
Zone 是 Market District
Health 是 50
```

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

#### 更新现有状态 — 聚合 `ShouldRespond` 是 `从不`

**触发调用：** `设置上下文状态` 使用一个已有的键，并且批次保持聚合 `ShouldRespond` 在 `从不`.

更新后的值会进入规范上下文。不会添加增量行。

```
Zone 是 Docks
```

#### 更新现有状态 — 聚合 `ShouldRespond` 是 `Auto` 或 `始终`

**触发调用：** `设置上下文状态` 使用一个已有的键，并且至少有一个暂存项会提升聚合 `ShouldRespond` 设为 `Auto` 或 `始终`.

更新后的值会进入规范上下文。会追加一条描述该变化的增量行。

```
Zone 是 Docks
Zone 从 Market District 更改为 Docks
```

#### 一次更新多个状态

**触发调用：** `设置上下文状态` 使用一个键值对映射，可能混合新键和已有键。

所有值都会写入跟踪器。当聚合不是 `从不`时，首次出现的延迟会按每个新键分别应用。所有更改共享一次刷新 — 一条 `替换` `context-update`.

```
Zone 是 Docks
Scenario 是 Active
Zone 从 Market District 更改为 Docks
Difficulty 是 Hard
```

#### 添加上下文事件

**触发调用：** `添加上下文事件`.

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

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

```
Zone 是 Docks
玩家到达了撤离点
```

#### 移除上下文状态

**触发调用：** `移除上下文状态`.

该键会从跟踪器中移除。 `bForceReplace` 被设为开启，因此刷新会发送不包含已移除键的规范上下文。移除不会添加增量行。

#### 动态上下文重置

**触发调用：** `重置动态上下文`.

插件会先清空任何已暂存的上下文批次，然后发送一个 `Reset` `context-update` (`模式：重置`, `run_llm: "false"`）且没有 `文本` 空 `Reset` 负载字段。该本地跟踪器会在 `Reset` 消息之后被清除。

当 `重置动态上下文` 被调用时，已存在的排队触发器会立即清除。排队在一个待处理离线 `Reset` 之后的触发器仍可能在 `Reset` 期间 `FlushDynamicContext()`.

当已连接时， `重置动态上下文` 会立即走刷新路径。当离线时，重置标志会等待首次连接后的刷新。

### 会话前排队

默认的防抖变更调用 — `设置上下文状态`, `设置上下文状态`, `添加上下文事件`, `移除上下文状态`，和 `重置动态上下文` — 会累积在 `PendingContextBatch` 中，同时 `IsChatbotConnected()` 是 `false`.

`TickDynamicContext()` 会持续累积，直到会话连接。连接后，当到达防抖截止时间时， `FlushDynamicContext()` 会发送待处理批次。

离线更新会折叠为上文所述的刷新行为——不会作为一系列单独消息重放。连接后，在首次到达防抖截止时间的 tick 中，聚合 `ShouldRespond` 保持 `从不` 的批次会从跟踪器发送当前规范快照；聚合 `Auto` 或 `始终` 的批次则遵循上文所述的规范加增量行为。任何待处理 `Reset` 会最后清除上下文。

```
// BeginPlay — 在会话连接前，这三项都会安全排队
设置上下文状态  名称="Facility"  值="Offshore Platform Alpha"
设置上下文状态  名称="Scenario"  值="Fire Drill"
添加上下文事件  文本="Session initialized"  ShouldRespond=Never

// 连接并超过防抖截止时间后 — 先一次替换上下文更新，然后如果已排队再重置：
// Facility 是 Offshore Platform Alpha
// Scenario 是 Fire Drill
// Session initialized
```

如果 `重置动态上下文` 并且后续更新都处于离线待处理状态，则刷新会先发送暂存内容，然后 `Reset` 最后发送。

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

### `bFlushImmediately`

每个变更函数 — `设置上下文状态`, `设置上下文状态`, `添加上下文事件`, `移除上下文状态` — 都提供一个 **`高级`** 参数 `bFlushImmediately`。当 `true`, `FlushDynamicContext()` 在当前帧运行。

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

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

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

### 下一步

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

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


---

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