> 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 参考

大多数动态上下文函数都暴露在 `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/`，以及 `Source/Convai/Private/ConvaiSubsystem.cpp`.

### 函数

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

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

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

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

| 参数                  | 类型                | 默认值     | 说明                                    |
| ------------------- | ----------------- | ------- | ------------------------------------- |
| `名称`                | `FString`         | —       | 用于标识此状态属性的键。区分大小写。                    |
| `值`                 | `FString`         | —       | 该状态属性的当前值。                            |
| `ShouldRespond`     | `EC_RunLLMOption` | `从不`    | 会贡献到批量聚合 `run_llm`.                   |
| `bFlushImmediately` | `bool`            | `false` | **高级。** 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。 |

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

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

***

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

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

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

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

| 参数                  | 类型                       | 默认值     | 说明                                    |
| ------------------- | ------------------------ | ------- | ------------------------------------- |
| `状态`                | `TMap<FString, FString>` | —       | 要设置或更新的键值状态属性映射。                      |
| `ShouldRespond`     | `EC_RunLLMOption`        | `从不`    | 会贡献到批量聚合 `run_llm` 适用于所有提供的键。         |
| `bFlushImmediately` | `bool`                   | `false` | **高级。** 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。 |

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

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

***

#### `Add Context Event`

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

**适用于：** 某事只发生一次——警报、里程碑、叙事节点。

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

| 参数                  | 类型                | 默认值     | 说明                                    |
| ------------------- | ----------------- | ------- | ------------------------------------- |
| `文本`                | `FString`         | —       | 要追加的事件描述。                             |
| `ShouldRespond`     | `EC_RunLLMOption` | `Auto`  | 会贡献到批量聚合 `run_llm`.                   |
| `bFlushImmediately` | `bool`            | `false` | **高级。** 绕过防抖并在当前帧执行刷新路径。连接后用于必须传递的数据。 |

**行为：** 相同 `文本` 在同一防抖窗口内多次暂存的相同值会去重。刷新时，事件会提交到跟踪器并包含在规范中。普通上下文事件不会重复到单独的增量行中。

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

***

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

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

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

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

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

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

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

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

***

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

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

**适用于：** 仿真重新启动，或者你需要丢弃之前的所有运行时上下文。

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

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

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

***

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

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

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

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

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

***

#### `更新上下文`

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

**适用于：** 已跟踪节点家族不满足你的格式要求。

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

| 参数              | 类型                     | 默认值      | 说明                                      |
| --------------- | ---------------------- | -------- | --------------------------------------- |
| `文本`            | `FString`              | —        | 要应用的上下文文本。以下情况可选： `模式` 为 `Reset`.       |
| `模式`            | `EC_ContextUpdateMode` | `Append` | 上下文应用方式： `Append`, `Replace`，或 `Reset`. |
| `ShouldRespond` | `EC_RunLLMOption`      | `Auto`   | 映射到 `run_llm` 在线路上传输。                   |

使用 `更新上下文` 仅当已跟踪节点家族不满足你的格式要求时。它不会更新 `FConvaiDynamicContextTracker`，因此 `获取上下文状态值` 当传入空字符串时 `模式` 为 `Reset`；SDK 会省略 `text` 仅在空 Reset 有效负载时。

### 默认 ShouldRespond 引用

| 函数                  | 默认值 `ShouldRespond`      |
| ------------------- | ------------------------ |
| `设置上下文状态`           | `从不`                     |
| `设置上下文状态`           | `从不`                     |
| `Add Context Event` | `Auto`                   |
| `移除上下文状态`           | *（无 `ShouldRespond` 参数）* |
| `重置动态上下文`           | *（Reset 始终使用 `从不` 在传输中）* |
| `更新上下文`             | `Auto`                   |

### 属性

#### `ContextDebounceWindow`

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

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

***

#### `ContextMaxDebounceWindow`

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

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

***

#### `DynamicEnvironmentInfo`

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

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

### 枚举

#### `EC_RunLLMOption`

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

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

***

#### `EC_ContextUpdateMode`

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

| 枚举值                             | Blueprint 显示名称 | 线路值（`模式`) | 行为                                |
| ------------------------------- | -------------- | --------- | --------------------------------- |
| `EC_ContextUpdateMode::Append`  | Append         | `追加`      | 文本会追加到现有上下文。                      |
| `EC_ContextUpdateMode::Replace` | Replace        | `替换`      | 完整上下文会被提供的文本替换。                   |
| `EC_ContextUpdateMode::Reset`   | Reset          | `重置`      | 上下文会被清空。传入空 `文本` 用于标准 Reset 有效负载。 |

### 传输消息

#### `上下文更新`

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

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

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

#### `update-dynamic-info`

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

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

### 连接辅助

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

### 下一步

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