> 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-blueprint-reference.md).

# 动态上下文 Blueprint 参考

参考从 Unreal 角色在实时会话中向 Convai 发送运行时状态、事件、重置、时序和传递更新的 Blueprint 控件。

大多数动态上下文函数都在 `UConvaiChatbotComponent` （蓝图显示名称 **Convai 聊天机器人**）的 `Convai|DynamicContext` 类别下公开。 `Update Context` 是一个高级的直接 `context-update` 节点，位于 `Convai` 类别下；它会绕过用于跟踪状态/事件的辅助 API。属性显示在 Details 面板中的 **Convai > DynamicContext** （防抖和传递时机设置）以及 **Convai** (`DynamicEnvironmentInfo`下。

权威来源： `Source/Convai/Public/ConvaiChatbotComponent.h`, `Source/Convai/Private/ConvaiChatbotComponent.cpp`, `Source/Convai/Public/DynamicContext/ConvaiPendingContextBatch.h`, `Source/Convai/Public/DynamicContext/`以及 `Source/Convai/Private/ConvaiSubsystem.cpp`.

### 函数

#### `Set Context State`

在动态上下文中设置单个状态属性。如果已存在同名 `Name` 的属性，则会替换其值。

**适用场景：** 游戏过程中某个当前事实发生变化，例如生命值、区域或装备状态。

**蓝图类别：** `Convai|DynamicContext`

| 参数                  | 类型                       | 默认值             | 说明                                                                                                                                                      |
| ------------------- | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`              | `FString`                | —               | 用于标识此状态属性的键。区分大小写。                                                                                                                                      |
| `Value`             | `FString`                | —               | 状态属性的当前值。                                                                                                                                               |
| `ShouldRespond`     | `EC_RunLLMOption`        | `Never`         | 计入批次汇总的 `run_llm`.                                                                                                                                      |
| `Delivery`          | `EConvaiContextDelivery` | `Send Normally` | **高级选项。** `Wait Until Conversation Is Idle` 会将更新暂缓到对话暂停时发送，以免角色打断自己。仅当批次的汇总 `ShouldRespond` 为 `Auto`/`Always`.                                          |
| `bFlushImmediately` | `bool`                   | `false`         | **高级选项。** 绕过防抖，并在当前帧执行刷新流程。配合 `Delivery` 设置为 `Wait Until Conversation Is Idle`，更新仍会等待对话安静下来，但会跳过完整的 `Quiet Time Before Delivery (s)` 时间窗口。用于连接后必须送达的数据。 |

**刷新行为：** 单次替换 `context-update`。当聚合值为 `Never`时，新键会进入规范状态；否则，新键会在首次刷新时延后到增量行。更新后的键始终会出现在规范状态中；当聚合值不是 `Never`.

**会话前：** 使用默认防抖设置时，数据会安全暂存，并在会话连接且防抖期限到期后刷新。对于连接前必须送达的数据，请勿使用 `bFlushImmediately = true` 。

***

#### `Set Context States`

一次设置多个状态属性。所有键共用一次规范状态重建和一次刷新。

**适用场景：** 多个相关信息同时变化——例如场景切换后，区域、设备和一天中的时间发生变化。

**蓝图类别：** `Convai|DynamicContext`

| 参数                  | 类型                       | 默认值             | 说明                                                                                                                                                      |
| ------------------- | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `States`            | `TMap<FString, FString>` | —               | 要设置或更新的键值状态属性映射。                                                                                                                                        |
| `ShouldRespond`     | `EC_RunLLMOption`        | `Never`         | 为批次聚合提供数据 `run_llm` 所有提供的键。                                                                                                                             |
| `Delivery`          | `EConvaiContextDelivery` | `Send Normally` | **高级选项。** `Wait Until Conversation Is Idle` 会暂缓更新，直到对话暂停，从而避免角色打断自己。仅当批次的聚合 `ShouldRespond` 为 `Auto`/`Always`.                                          |
| `bFlushImmediately` | `bool`                   | `false`         | **高级选项。** 绕过防抖，并在当前帧执行刷新流程。配合 `Delivery` 设置为 `Wait Until Conversation Is Idle`，更新仍会等待对话安静下来，但会跳过完整的 `Quiet Time Before Delivery (s)` 时间窗口。用于连接后必须送达的数据。 |

**时生效。** 行为： `ShouldRespond` 会与同一防抖时间窗口内暂存的其他项目合并（`Always` > `Auto` > `Never`).

**会话前：** 使用默认防抖设置时，数据会安全暂存，并在会话连接且防抖期限到期后刷新。对于连接前必须送达的数据，请勿使用 `bFlushImmediately = true` 。

***

#### `Add Context Event`

将按时间顺序排列的事件文本追加到动态上下文中。

**适用场景：** 某件事只发生一次——例如警报、里程碑或叙事节点。

**蓝图类别：** `Convai|DynamicContext`

| 参数                  | 类型                       | 默认值             | 说明                                                                                                                                                        |
| ------------------- | ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Text`              | `FString`                | —               | 要追加的事件描述。                                                                                                                                                 |
| `ShouldRespond`     | `EC_RunLLMOption`        | `Auto`          | 计入批次汇总的 `run_llm`.                                                                                                                                        |
| `Delivery`          | `EConvaiContextDelivery` | `Send Normally` | **高级选项。** `Wait Until Conversation Is Idle` 会暂缓事件，直到对话暂停，从而避免角色打断自己。暂缓的事件最终发送时会追加到事件历史末尾。仅当 `ShouldRespond` 为 `Auto`/`Always`.                            |
| `bEphemeral`        | `bool`                   | `false`         | **高级选项。** 当 `true`时，角色只会在下一次更新时看到该事件一次，并且该事件不会提交到持久化上下文中——后续更新中不会再次出现。当 `false` 时（默认值），该事件会保留在运行时上下文中。                                                    |
| `bFlushImmediately` | `bool`                   | `false`         | **高级选项。** 绕过防抖，并在当前帧运行刷新流程。若将 `Delivery` 设置为 `Wait Until Conversation Is Idle`，事件仍会等待对话进入空闲状态，但会跳过完整的 `Quiet Time Before Delivery (s)` 时间窗口。用于连接后必须送达的数据。 |

**行为：** 相同的 `Text` 值若在同一防抖窗口内暂存多次，会被去重（临时事件和持久事件分别跟踪，因此文本相同的临时事件不会与持久事件互相去重）。刷新时，非临时事件会提交到跟踪器并包含在规范上下文中。临时事件会追加到待发送的刷新文本中一次，随后丢弃——它不会写入跟踪器，因此不会出现在后续更新的规范上下文中。常规（非临时）上下文事件不会重复写入单独的增量行。

**会话前：** 使用默认防抖设置时，数据会安全暂存，并在会话连接且防抖期限到期后刷新。对于连接前必须送达的数据，请勿使用 `bFlushImmediately = true` 。

***

#### `Remove Context State`

从动态上下文中移除一个状态属性，并据此重建规范上下文。

**适用情形：** 某项条件不再适用——例如，物品已被使用或警报已解除。

**蓝图类别：** `Convai|DynamicContext`

| 参数                  | 类型        | 默认值     | 说明                                       |
| ------------------- | --------- | ------- | ---------------------------------------- |
| `Name`              | `FString` | —       | 要移除的键。区分大小写。                             |
| `bFlushImmediately` | `bool`    | `false` | **高级选项。** 绕过防抖，并在当前帧运行刷新流程。用于连接后必须送达的数据。 |

**返回值：** 无。如果 `Name` 不存在，则调用不执行任何操作。

**行为：** 在待处理批次上设置 `bForceReplace` ，使刷新时发送更新后的规范上下文，其中不包含已移除的键。不会添加增量行。

**会话前：** 使用默认防抖设置时，数据会安全暂存，并在会话连接且防抖期限到期后刷新。对于连接前必须送达的数据，请勿使用 `bFlushImmediately = true` 。

***

#### `Reset Dynamic Context`

清除所有跟踪的状态属性和事件，并重置远程上下文。

**适用情形：** 模拟重新启动，或需要丢弃所有先前的运行时上下文。

**蓝图类别：** `Convai|DynamicContext`

| 参数 | 类型 | 默认值 | 说明   |
| -- | -- | --- | ---- |
| —  | —  | —   | 无参数。 |

**行为：** 标记 `bPendingReset`。不会立即清除跟踪器或丢弃暂存的更新。刷新时：先处理暂存批次，然后触发 Reset `context-update` （`mode: reset`, `run_llm: "false"`，由于 Reset 负载为空，省略 `text` ），随后清除本地跟踪器。请求重置时会清除 `PendingTriggers` 。连接时会立即调用刷新流程；离线时则排队等待连接后的首次刷新。

***

#### `获取上下文状态值`

返回已跟踪状态属性当前的客户端值。从本地跟踪器读取，不会查询 Convai。

**适用场景：** 蓝图条件需要在发送冗余更新前获取当前本地值。

**蓝图类别：** `Convai|DynamicContext`

| 参数         | 方向 | 类型        | 默认值 | 说明               |
| ---------- | -- | --------- | --- | ---------------- |
| `Name`     | 输入 | `FString` | —   | 要查找的键。区分大小写。     |
| `OutValue` | 输出 | `FString` | —   | 键存在时返回其当前值。      |
| 返回值        | 返回 | `bool`    | —   | `true` （如果找到该键）。 |

***

#### `更新上下文`

高级直接节点。发送原始的 `context-update` 消息，并显式指定 `Text`, `Mode`和 `ShouldRespond`。暂存的状态/事件刷新会在调用 `FlushDynamicContext()` 期间使用相同的传输消息类型，但不会通过此节点更新跟踪器。 `重置动态上下文` 重置消息使用相同的 C++ `UpdateContext` 发送路径。

**适用场景：** 已跟踪的节点系列无法满足你的格式要求。

**蓝图类别：** `Convai`

| 参数              | 类型                     | 默认值      | 说明                                      |
| --------------- | ---------------------- | -------- | --------------------------------------- |
| `Text`          | `FString`              | —        | 要应用的上下文文本。若 `Mode` 为 `Reset`.           |
| `Mode`          | `EC_ContextUpdateMode` | `Append` | 上下文的应用方式： `Append`, `Replace`或 `Reset`. |
| `ShouldRespond` | `EC_RunLLMOption`      | `Auto`   | 在传输过程中映射为 `run_llm` 。                   |

仅当已跟踪的节点系列无法满足你的格式要求时，才使用 `Update Context` 。它不会更新 `FConvaiDynamicContextTracker`，因此 `Get Context State Value` 无法读取仅通过此节点发送的值。请在 `Mode` 为 `Reset`时传入空字符串；SDK 会在 `text` 仅为空的 Reset 负载时省略该字段。

### 默认 ShouldRespond 参考

| 函数                      | 默认值 `ShouldRespond`           | 默认值 `Delivery`      |
| ----------------------- | ----------------------------- | ------------------- |
| `Set Context State`     | `Never`                       | `Send Normally`     |
| `Set Context States`    | `Never`                       | `Send Normally`     |
| `Add Context Event`     | `Auto`                        | `Send Normally`     |
| `Remove Context State`  | *（无 `ShouldRespond` 参数）*      | *（无 `Delivery` 参数）* |
| `Reset Dynamic Context` | *（Reset 在网络传输中始终使用 `Never` ）* | *（无 `Delivery` 参数）* |
| `更新上下文`                 | `Auto`                        | *（无 `Delivery` 参数）* |

### 返回的结果

#### `ContextDebounceWindow`

| Details 面板标签 | 上下文防抖窗口（秒） |
| ------------ | ---------- |
| 类型           | `float`    |
| 默认值          | `0.5`      |
| 限制为          | ≥ `0.1`    |
| 类别           | \`Convai   |

最近一次暂存的上下文更新后，等待多长时间再刷新。窗口内每次有新更新都会重置此计时器。

***

#### `ContextMaxDebounceWindow`

| Details 面板标签 | 最大防抖窗口（秒） |
| ------------ | --------- |
| 类型           | `float`   |
| 默认值          | `3.0`     |
| 限制为          | ≥ `0.1`   |
| 类别           | \`Convai  |

防抖突发中的首次更新最多可以延迟多久。必须 ≥ `ContextDebounceWindow`；较小的值会在刷新时被限制。

***

#### `ConversationIdleSettleSeconds`

| Details 面板标签 | 交付前的静默时间（秒） |
| ------------ | ----------- |
| 类型           | `float`     |
| 默认值          | `2.0`       |
| 限制为          | ≥ `0.0`     |
| 类别           | \`Convai    |

在交付 `Delivery` 为 `Wait Until Conversation Is Idle` 的更新之前，对话必须持续保持静默的时长。任何对话活动都会重新开始计时——总等待时间不会设上限，因此等待中的更新绝不会打断正在进行的交流。设置为 `0` 即可在检测到空闲时立即交付。

***

#### `DynamicEnvironmentInfo`

| Details 面板标签 | 动态环境信息    |
| ------------ | --------- |
| 类型           | `FString` |
| 默认值          | `""`      |
| 类别           | `Convai`  |

通过以下方式发送的自由格式文本： `update-dynamic-info` 在参与者连接时，以及已连接会话中的属性发生变化时发送。不会由 `FConvaiDynamicContextTracker`跟踪。对于运行时变化的事实，请使用 `Set Context State`.

### 枚举

#### `EC_RunLLMOption`

控制 Convai 在收到上下文更新后是否生成语音回复。

| 枚举项                       | 蓝图显示名称 | Wire 字符串（`run_llm`) | 行为              |
| ------------------------- | ------ | ------------------- | --------------- |
| `EC_RunLLMOption::Auto`   | 自动     | `"auto"`            | 发送更新，并请求自动处理回复。 |
| `EC_RunLLMOption::Always` | 始终     | `"true"`            | 发送更新，并请求处理回复。   |
| `EC_RunLLMOption::Never`  | 从不     | `"false"`           | 发送更新，但不请求处理回复。  |

***

#### `EC_ContextUpdateMode`

控制直接调用 `更新上下文` 时如何应用上下文字符串。

| 枚举项                             | 蓝图显示名称 | Wire 值（`mode`) | 行为                         |
| ------------------------------- | ------ | -------------- | -------------------------- |
| `EC_ContextUpdateMode::Append`  | 追加     | `append`       | 将文本追加到现有上下文。               |
| `EC_ContextUpdateMode::Replace` | 替换     | `replace`      | 使用提供的文本替换整个上下文。            |
| `EC_ContextUpdateMode::Reset`   | 重置     | `reset`        | 清除上下文。标准重置负载请传入空的 `Text` 。 |

***

#### `EConvaiContextDelivery`

控制 **何时** 状态、事件或事实更新到达角色；这与 [同步行为与时序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/sync-behavior-and-timing.md).

| 枚举项                                                   | 蓝图显示名称 | 行为                                                                                  |
| ----------------------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `EConvaiContextDelivery::SendNormally`                | 正常发送   | 默认值。将更新批量合并到下一个计划发送中——与此选项推出前的行为相同。                                                 |
| `EConvaiContextDelivery::WaitUntilConversationIsIdle` | 等待对话空闲 | 等待对话持续安静一段时间后再发送 `Quiet Time Before Delivery (s)`，以免更新导致角色打断自己或盖过用户说话。等待时间没有刻意设置上限。 |

仅当 `ShouldRespond` 为 `Auto`/`Always` — 静默（`Never`）更新没有可中断的内容，因此无论 `Delivery`.

### 传输消息

#### `context-update`

发送方 `UConvaiSubsystem::UpdateContext` 用于跟踪的动态上下文刷新以及直接 `Update Context` 调用。

| JSON 字段                    | 说明                                 |
| -------------------------- | ---------------------------------- |
| `mode`                     | `append`, `replace`或 `reset`       |
| `run_llm`                  | 字符串值 `"auto"`, `"true"`或 `"false"` |
| `text`                     | 组装后的上下文字符串；Reset 为空时省略             |
| `current_attention_object` | 注意力合并到刷新内容时可选的注意力对象名称              |

来自 `FlushDynamicContext` 的跟踪刷新始终使用 `mode: replace` 处理暂存的批次内容。

#### `update-dynamic-info`

发送方 `UpdateDynamicInfo` 用于 `DynamicEnvironmentInfo` 变更以及参与者连接时。

| JSON 字段             | 说明        |
| ------------------- | --------- |
| `dynamic_info.text` | 自由格式的环境文本 |

### 连接辅助函数

| 函数                             | 类别       | 说明   |
| ------------------------------ | -------- | ---- |
| `Get Chatbot Connection State` | \`Convai | 连接\` |

### 后续步骤

{% 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/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/dynamic-context-blueprint-reference.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.
