> 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 消息                | 它携带的内容                                                                      |
| ------- | ---------------------- | --------------------------------------------------------------------------- |
| 动态上下文管道 | `上下文更新`                | 来自……的跟踪状态和事件 `设置上下文状态`, `设置上下文状态集`, `添加上下文事件`, `移除上下文状态`，以及 `重置动态上下文`       |
| 直接上下文更新 | `上下文更新`                | 通过……发送的显式文本 `更新上下文`，绕过跟踪状态/事件辅助 API                                         |
| 场景元数据管道 | `更新场景元数据`              | 来自……的新建或移除的环境条目 `添加对象`, `移除对象`, `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** Details 面板中的类别。它承载的是自由格式文本， **包含** 由……跟踪 `FConvaiDynamicContextTracker`.

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

1. **在参与者连接时** — `OnAttendeeConnected` 调用 `UpdateDynamicInfo` 使用当前属性值。
2. **连接时属性更改** — 分配新值会触发 `UpdateDynamicEnvironmentInfo`，它会调用 `UpdateDynamicInfo` 当存在会话代理时。

线上载荷格式为：

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

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

| 使用场景              | 推荐路径                     |
| ----------------- | ------------------------ |
| 会话级简报，仅设置一次或不频繁更改 | `DynamicEnvironmentInfo` |
| 在游戏过程中变化的运行时事实    | `设置上下文状态` 或 `添加上下文事件`    |

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

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

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

### 重新连接与动态层

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

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

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

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

默认防抖调用的 `设置上下文状态`, `设置上下文状态集`, `添加上下文事件`，以及 `移除上下文状态` 在会话连接前进行的……不会受到 `BeginPlay`。每次调用都会累积到 `PendingContextBatch`。会话连接后，插件会在防抖截止时间已过的第一个 tick 中刷新该批次。

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

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