> 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/static-context-at-connection-time.md).

# 连接时的静态上下文

有些上下文会在会话开始时发送一次。其他上下文可以在游戏过程中通过单独的更新路径发生变化。本页说明连接时固定的内容，以及可以实时更新的内容。

### 连接时发送的内容

当 `开始会话` 运行时， `UConvaiChatbotComponent` 使用组件中的连接参数和当前环境数据打开一个实时会话。经源码验证的实时连接路径包含以下数据：

| Data   | 来源开启 `UConvaiChatbotComponent`                            | 说明                                                     |
| ------ | --------------------------------------------------------- | ------------------------------------------------------ |
| 角色 ID  | `CharacterID`                                             | 决定 Convai 加载哪个角色配置。                                    |
| 动作配置   | `EnvironmentData` 当 `bEnableActions` 为 `true` 并且至少配置了一个动作 | 序列化为一个 JSON `action_config` 块。动作集、对象列表和角色列表在重新连接前保持固定。 |
| 终端用户身份 | `EndUserID` 是位于 `EndUserMetadata`                         | 用于长期记忆。在会话中途更改它们不会影响当前会话。                              |

这些值用于建立会话。在游戏过程中推送动态上下文时，它们不会改变。

### 哪些内容可实时更新

会话连接后，有六种机制可以向 Convai 传递更新后的上下文：

| 机制      | RTVI 消息                 | 承载内容                                                                                    |
| ------- | ----------------------- | --------------------------------------------------------------------------------------- |
| 动态上下文管道 | `上下文更新`                 | 跟踪的状态和事件，来自 `设置上下文状态`, `设置上下文状态`, `Add Context Event`, `移除上下文状态`，以及 `重置动态上下文`           |
| 直接上下文更新 | `上下文更新`                 | 通过 `更新上下文`，绕过已跟踪的状态/事件辅助 API                                                            |
| 场景元数据管道 | `update-scene-metadata` | 来自……的新建或移除的环境条目 `AddObject`, `RemoveObject`, `AddCharacter`, `RemoveCharacter`以及相关的环境变更 |
| 动态环境信息  | `update-dynamic-info`   | 来自……的自由格式文本 `DynamicEnvironmentInfo`                                                    |
| 叙事模板键   | `update-template-keys`  | 当前 `NarrativeTemplateKeys` 连接后以及通过……更新时的值 `UpdateNarrativeTemplateKeys`                 |
| 注意力折叠   | `上下文更新` （同一条消息）         | 可选 `current_attention_object` 当注意力在上下文刷新时被暂存                                            |

请参见 [动态上下文如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md) 用于跟踪管道，且 [场景元数据如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md) 用于环境更新。

### DynamicEnvironmentInfo

`DynamicEnvironmentInfo` 是一个 `FString` 属性，位于 **Convai** 详细信息面板的……类别中。它承载的是自由格式文本， **不是** 由 `FConvaiDynamicContextTracker`.

插件通过 `update-dynamic-info` 在两种情况下：

1. **在参会者连接时** — `OnAttendeeConnected` 调用 `UpdateDynamicInfo` 使用当前属性值。
2. **连接状态下属性更改时** —— 赋予新值会触发 `UpdateDynamicEnvironmentInfo`，其会调用 `UpdateDynamicInfo` 当会话代理存在时。

线上载荷结构如下：

```json
{
  "dynamic_info": {
    "text": "你的自由格式文本"
  }
}
```

`DynamicEnvironmentInfo` 不会经过防抖批处理。它不使用规范的状态/事件组装。对于在游戏过程中频繁变化的值，请使用 `设置上下文状态` 代替。

| 使用场景            | 推荐路径                            |
| --------------- | ------------------------------- |
| 会话级简报，设置一次或很少更改 | `DynamicEnvironmentInfo`        |
| 游戏过程中变化的运行时事实   | `设置上下文状态` 或 `Add Context Event` |

### 连接数据与实时更新之间的关系

连接数据用于建立实时会话，并在启用动作时建立初始动作配置。实时更新承载的是会话开始后发生变化的信息。

类似这样的动态状态更新 `Health` 为 `50` 会向 Convai 通报当前的运行时事实。它不会编辑 `action_config` 在连接时发送的内容。只推送游戏过程中发生变化的内容，不要通过动态上下文管道重新发送相同的连接数据。

### 重新连接与动态层

在默认的连接代理设置下，调用 `停止会话` 然后调用 `开始会话` 会创建一个新的实时连接。如果启用了连接代理复用，并且正值的 `ConnectionProxyTTL`，同一角色重启可以复用一个孤立连接。新的连接会使用当前的 `CharacterID`、终端用户身份字段以及当时的动作配置。 `FConvaiDynamicContextTracker` 是一个客户端内存中的结构；当会话重启时，它不会自动重置。

调用 `重置动态上下文` 如果你想要一个干净的动态上下文跟踪器，请在重新连接前重置它。

{% hint style="warning" %}
动作配置在 `/connect` 时固定。运行时对 `AddAction` 或 `RemoveAction` 会为 **下一** 个会话，而不是当前会话。要更改实时动作契约，请调用 `停止会话` 然后 `开始会话` ，在修改动作列表之后。
{% endhint %}

### 会话前动态上下文排队

对……的默认防抖调用 `设置上下文状态`, `设置上下文状态`, `Add Context Event`，以及 `移除上下文状态` 在会话连接前发出的调用可免受 `BeginPlay`。 `PendingContextBatch`。当会话建立连接后，插件会在防抖期限已过的第一个 tick 中刷新该批次。

`重置动态上下文` 在连接前不会立即丢弃已暂存的更新——它会标记一个待处理的 `Reset` ，该项会在 **在** 任何已暂存的内容都会在连接后的首次刷新时排空。若要从空的动态上下文开始，请先让重置刷新完成，再暂存新的更新。

### SessionID 和实时会话

`SessionID` 存在于 `UConvaiChatbotComponent`，但经过验证的实时 `/connect` 路径在当前源码中不会将其作为 `FConvaiConnectionParams`。不要依赖此节点返回的 `SessionID` 来控制动态上下文重置行为。请使用 `重置动态上下文` 用于跟踪的动态上下文层。

### 下一步

{% content-ref url="/pages/8ef7dcd046dad07f4afcb544f96d3beda6feb0ad" %}
[动态上下文的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/602e67296ec3ed2b843879adb48efa844ab06ec3" %}
[动态上下文快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-quick-start.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/static-context-at-connection-time.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.