> 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` (Blueprint 显示名称 **Convai 聊天机器人**）下位于 `Convai|DynamicContext` 类别。 `更新上下文` 是一个高级直连 `上下文更新` 节点，位于 `Convai` 类别中；它绕过已跟踪状态/事件辅助 API。属性显示在 **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`.

### 函数

#### `设置上下文状态`

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

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

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

| 参数                  | 类型                       | 默认      | 说明                                                                                                |
| ------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `名称`                | `FString`                | —       | 标识此状态属性的键。区分大小写。                                                                                  |
| `值`                 | `FString`                | —       | 该状态属性的当前值。                                                                                        |
| `ShouldRespond`     | `EC_RunLLMOption`        | `从不`    | 计入批次聚合 `run_llm`.                                                                                 |
| `发送`                | `EConvaiContextDelivery` | `正常发送`  | **高级。** `等待直到对话空闲` 会将更新保留到对话暂停，因此不会让角色打断自己。仅在该批次的聚合 `ShouldRespond` 是 `自动`/`始终`.                  |
| `bFlushImmediately` | `bool`                   | `false` | **高级。** 绕过防抖并在当前帧运行刷新路径。使用 `发送` 设置为 `等待直到对话空闲`，更新仍会等待安静时机，但会跳过完整的 `发送前静默时间（秒）` 时间窗口。连接后用于必须送达的数据。 |

**刷新行为：** 单次替换 `上下文更新`。当聚合为 `从不`；否则，新键会在首次刷新时延后到 delta 行。更新后的键始终出现在 canonical 中；当聚合不是 `从不`.

**会话前：** 使用默认防抖时，会安全暂存，并在会话连接且防抖截止时间到期后刷新。不要使用 `bFlushImmediately = true` 在连接前用于必须送达的数据。

***

#### `设置上下文状态集`

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

**使用场景：** 多个相关事实同时变化——场景切换后的区域、装备和一天中的时间。

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

| 参数                  | 类型                       | 默认      | 说明                                                                                                |
| ------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `状态`                | `TMap<FString, FString>` | —       | 要设置或更新的键值状态属性映射。                                                                                  |
| `ShouldRespond`     | `EC_RunLLMOption`        | `从不`    | 计入批次聚合 `run_llm` 适用于所有提供的键。                                                                       |
| `发送`                | `EConvaiContextDelivery` | `正常发送`  | **高级。** `等待直到对话空闲` 会将更新保留到对话暂停，因此不会让角色打断自己。仅在该批次的聚合 `ShouldRespond` 是 `自动`/`始终`.                  |
| `bFlushImmediately` | `bool`                   | `false` | **高级。** 绕过防抖并在当前帧运行刷新路径。使用 `发送` 设置为 `等待直到对话空闲`，更新仍会等待安静时机，但会跳过完整的 `发送前静默时间（秒）` 时间窗口。连接后用于必须送达的数据。 |

**行为：** 空映射会被忽略。聚合 `ShouldRespond` 会与同一防抖窗口中的其他暂存项合并（`始终` > `自动` > `从不`).

**会话前：** 使用默认防抖时，会安全暂存，并在会话连接且防抖截止时间到期后刷新。不要使用 `bFlushImmediately = true` 在连接前用于必须送达的数据。

***

#### `添加上下文事件`

将按时间顺序的事件字符串追加到动态上下文中。

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

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

| 参数                  | 类型                       | 默认      | 说明                                                                                                |
| ------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `文本`                | `FString`                | —       | 要追加的事件描述。                                                                                         |
| `ShouldRespond`     | `EC_RunLLMOption`        | `自动`    | 计入批次聚合 `run_llm`.                                                                                 |
| `发送`                | `EConvaiContextDelivery` | `正常发送`  | **高级。** `等待直到对话空闲` 会将事件保留到对话暂停，因此不会让角色打断自己。被保留的事件在最终发送时会落到事件历史末尾。仅在 `ShouldRespond` 是 `自动`/`始终`.  |
| `bEphemeral`        | `bool`                   | `false` | **高级。** 当 `true`，角色只会在下一次更新中看到该事件一次，且它绝不会提交到持久化上下文中——后续更新中也不会再次出现。当 `false` （默认），事件会保留在运行中的上下文里。  |
| `bFlushImmediately` | `bool`                   | `false` | **高级。** 绕过防抖并在当前帧运行刷新路径。使用 `发送` 设置为 `等待直到对话空闲`，事件仍会等待安静时机，但会跳过完整的 `发送前静默时间（秒）` 时间窗口。连接后用于必须送达的数据。 |

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

**会话前：** 使用默认防抖时，会安全暂存，并在会话连接且防抖截止时间到期后刷新。不要使用 `bFlushImmediately = true` 在连接前用于必须送达的数据。

***

#### `移除上下文状态`

从动态上下文中移除一个状态属性，并在不包含它的情况下重建 canonical 上下文。

**使用场景：** 某个条件不再适用——物品已使用，警报已清除。

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

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

**返回：** 无。如果 `名称` 不存在，则该调用无操作。

**行为：** 设置 `bForceReplace` 到待处理批次上，使刷新发送不包含已移除键的更新后 canonical 上下文。不添加 delta 行。

**会话前：** 使用默认防抖时，会安全暂存，并在会话连接且防抖截止时间到期后刷新。不要使用 `bFlushImmediately = true` 在连接前用于必须送达的数据。

***

#### `重置动态上下文`

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

**使用场景：** 模拟重新开始，或你需要丢弃之前所有运行时上下文。

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

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

**行为：** 标记 `bPendingReset`。不会提前清空跟踪器或丢弃已暂存的更新。刷新时：先清空暂存批次，然后发送 Reset `上下文更新` 触发（`模式：重置`, `run_llm: "false"`，其中 `text` 对于空 Reset 负载则省略），然后清除本地跟踪器。清除 `PendingTriggers` 在请求重置时。当已连接时，立即调用刷新路径；离线时，则排队直到首次连接后的刷新。

***

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

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

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

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

| 参数         | 方向 | 类型        | 默认 | 说明              |
| ---------- | -- | --------- | -- | --------------- |
| `名称`       | 在  | `FString` | —  | 要查找的键。区分大小写。    |
| `OutValue` | 输出 | `FString` | —  | 如果键存在，则返回当前值。   |
| 返回值        | 返回 | `bool`    | —  | `true` 如果找到了该键。 |

***

#### `更新上下文`

高级直连节点。发送原始 `上下文更新` 并显式指定 `文本`, `模式`，以及 `ShouldRespond`。暂存的状态/事件刷新在 `FlushDynamicContext()` 中使用相同的传输消息类型，而不会通过此节点更新跟踪器。 `重置动态上下文` 使用相同的 C++ `UpdateContext` 发送路径来传递重置消息。

**使用场景：** 已跟踪节点家族无法满足你的格式要求。

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

| 参数              | 类型                     | 默认   | 说明                           |
| --------------- | ---------------------- | ---- | ---------------------------- |
| `文本`            | `FString`              | —    | 要应用的上下文文本。当 `模式` 是 `重置`.     |
| `模式`            | `EC_ContextUpdateMode` | `追加` | 上下文的应用方式： `追加`, `替换`，或 `重置`. |
| `ShouldRespond` | `EC_RunLLMOption`      | `自动` | 映射到 `run_llm` 在传输中。          |

使用 `更新上下文` 仅当已跟踪节点家族无法满足你的格式要求时。它不会更新 `FConvaiDynamicContextTracker`结束时变为可用，因此 `获取上下文状态值` 无法读取仅通过此节点发送的值。当 `模式` 是 `重置`；SDK 会省略 `text` 仅用于空 Reset 负载。

### 默认 ShouldRespond 引用

| 函数         | 默认 `ShouldRespond`       | 默认 `发送`       |
| ---------- | ------------------------ | ------------- |
| `设置上下文状态`  | `从不`                     | `正常发送`        |
| `设置上下文状态集` | `从不`                     | `正常发送`        |
| `添加上下文事件`  | `自动`                     | `正常发送`        |
| `移除上下文状态`  | *（无 `ShouldRespond` 参数）* | *（无 `发送` 参数）* |
| `重置动态上下文`  | *（Reset 始终使用 `从不` 在传输中）* | *（无 `发送` 参数）* |
| `更新上下文`    | `自动`                     | *（无 `发送` 参数）* |

### 属性

#### `ContextDebounceWindow`

| 详情面板标签 | Context Debounce Window (秒) |
| ------ | --------------------------- |
| 类型     | `float`                     |
| 默认     | `0.5`                       |
| 限制     | ≥ `0.1`                     |
| 类别     | \`Convai                    |

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

***

#### `ContextMaxDebounceWindow`

| 详情面板标签 | Max Debounce Window (秒) |
| ------ | ----------------------- |
| 类型     | `float`                 |
| 默认     | `3.0`                   |
| 限制     | ≥ `0.1`                 |
| 类别     | \`Convai                |

防抖突发中第一次更新可被延迟的最长上限。必须 ≥ `ContextDebounceWindow`；更小的值会在刷新时被限制。

***

#### `ConversationIdleSettleSeconds`

| 详情面板标签 | 发送前静默时间（秒） |
| ------ | ---------- |
| 类型     | `float`    |
| 默认     | `2.0`      |
| 限制     | ≥ `0.0`    |
| 类别     | \`Convai   |

对话必须持续保持安静多久，才会使其 `发送` 是 `等待直到对话空闲` 被发送。任何对话活动都会重新开始等待——这里刻意不设总等待上限，因此等待中的更新绝不会打断正在进行的交流。设置为 `0` 以便在检测到空闲后立即发送。

***

#### `DynamicEnvironmentInfo`

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

通过 `update-dynamic-info` 发送的自由文本，在参与者连接时，以及该属性在已连接会话中发生变化时。不会被 `FConvaiDynamicContextTracker`跟踪。对于运行时变化的事实，请使用 `设置上下文状态`.

### 枚举

#### `EC_RunLLMOption`

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

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

***

#### `EC_ContextUpdateMode`

控制在调用 `更新上下文` 。

| 枚举项                             | Blueprint 显示名称 | 传输值（`mode`) | 行为                               |
| ------------------------------- | -------------- | ----------- | -------------------------------- |
| `EC_ContextUpdateMode::Append`  | 追加             | `追加`        | 文本会追加到现有上下文。                     |
| `EC_ContextUpdateMode::Replace` | 替换             | `替换`        | 完整上下文会被提供的文本替换。                  |
| `EC_ContextUpdateMode::Reset`   | 重置             | `重置`        | 上下文将被清空。传入空 `文本` 以作为标准 Reset 负载。 |

***

#### `EConvaiContextDelivery`

控制 **当** 一个状态、事件或事实更新到达角色，独立于以下所述的防抖批处理： [同步行为和时序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/sync-behavior-and-timing.md).

| 枚举项                                                   | Blueprint 显示名称 | 行为                                                              |
| ----------------------------------------------------- | -------------- | --------------------------------------------------------------- |
| `EConvaiContextDelivery::SendNormally`                | 正常发送           | 默认。会批量并入下一次计划发送——与该选项存在之前的行为相同。                                 |
| `EConvaiContextDelivery::WaitUntilConversationIsIdle` | 等待直到对话空闲       | 暂缓发送，直到对话已安静持续 `发送前静默时间（秒）`，因此该更新不会让角色打断自己或盖过用户发言。这里刻意不设等待时间上限。 |

仅当 `ShouldRespond` 是 `自动`/`始终` ——一个静默的（`从不`）更新没有可打断的内容，因此无论 `发送`.

### 传输消息

#### `上下文更新`

由以下发送 `UConvaiSubsystem::UpdateContext` 用于已跟踪的动态上下文刷新和直接的 `更新上下文` 调用。

| JSON 字段                    | 说明                                  |
| -------------------------- | ----------------------------------- |
| `mode`                     | `追加`, `替换`，或 `重置`                   |
| `run_llm`                  | 字符串值 `"auto"`, `"true"`，或 `"false"` |
| `text`                     | 组装后的上下文字符串；在空 Reset 时省略             |
| `current_attention_object` | 当注意力被并入刷新时，可选的注意对象名称                |

来自以下的跟踪刷新 `FlushDynamicContext` 始终使用 `模式：替换` 用于暂存的批次内容。

#### `update-dynamic-info`

由以下发送 `UpdateDynamicInfo` 用于 `DynamicEnvironmentInfo` 变化，以及在参与者连接时。

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

### 连接辅助

| 函数            | 类别       | 说明           |
| ------------- | -------- | ------------ |
| `获取聊天机器人连接状态` | \`Convai | Connection\` |

### 下一步

{% 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/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 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.