> 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).

# 连接时的静态上下文

了解哪些已验证的连接数据在会话开始时是固定的，以及实时上下文更新如何使用单独的运行时消息。

某些上下文会在会话启动时发送一次。其他上下文则可在游戏过程中通过单独的更新路径进行更改。本页将说明哪些内容在连接时固定，以及哪些内容可以实时更新。

### 连接时发送的内容

当 `Start Session` 运行时， `UConvaiChatbotComponent` 会使用组件中的连接参数和当前环境数据建立实时会话。经源代码验证的实时连接路径包含以下数据：

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

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

### 实时更新的内容

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

| 机制      | RTVI 消息                  | 承载内容                                                                                                                            |
| ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| 动态上下文管线 | `context-update`         | 来自以下接口的跟踪状态和事件： `Set Context State`, `Set Context States`, `Add Context Event`, `Remove Context State`和 `Reset Dynamic Context` |
| 直接上下文更新 | `context-update`         | 通过以下接口发送的显式文本： `Update Context`，绕过跟踪状态/事件辅助 API                                                                                 |
| 场景元数据管线 | `update-scene-metadata`  | 来自以下接口的新增或移除环境条目： `AddObject`, `RemoveObject`, `AddCharacter`, `RemoveCharacter`以及相关的环境变更                                       |
| 动态环境信息  | `update-dynamic-info`    | 来自 `DynamicEnvironmentInfo`                                                                                                     |
| 叙事模板键   | `update-template-keys`   | 当前 `NarrativeTemplateKeys` 连接后以及通过 `UpdateNarrativeTemplateKeys`                                                                |
| 注意力折叠   | `context-update` （同一条消息） | 可选 `current_attention_object` 在通过上下文刷新暂存注意力时                                                                                    |

请参阅 [动态上下文的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md) 了解受跟踪的流程，并参阅 [场景元数据的工作原理](https://docs.convai.com/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` 不会经过防抖批处理，也不会使用规范化的状态/事件组装。对于游戏过程中频繁变化的值，请改用 `Set Context State` 。

| 适用场景             | 推荐方式                                      |
| ---------------- | ----------------------------------------- |
| 仅设置一次或很少更改的会话级简介 | `DynamicEnvironmentInfo`                  |
| 游戏过程中会变化的运行时事实   | `Set Context State` 或 `Add Context Event` |

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

连接数据用于建立实时会话，并在启用操作时设置初始操作配置。实时更新则传递会话开始后发生变化的信息。

像 `Health` 这样的动态状态更新 `50` 会向 Convai 提供当前运行时事实，但不会修改连接时发送的 `action_config` 。只推送游戏过程中发生变化的内容，不要通过动态上下文管线重复发送相同的连接数据。

### 重连与动态层

使用默认的连接代理设置时，调用 `Stop Session` 后再调用 `Start Session` 会创建新的实时连接。如果启用了连接代理复用，且 `ConnectionProxyTTL`为正值，则使用同一角色重启时可以复用孤立的连接。新连接会使用此时的 `CharacterID`、最终用户身份字段和操作配置。 `FConvaiDynamicContextTracker` 是客户端的内存中结构；会话重启时不会自动重置。

如果希望动态上下文跟踪器保持干净，请在重连前调用 `Reset Dynamic Context` 。

{% hint style="warning" %}
操作配置在 `/connect` 时确定。运行时调用 `AddAction` 或 `RemoveAction` 会为 **下一个** 会话准备操作集合，而不会影响当前会话。若要更改当前会话的操作约定，请修改操作列表后调用 `Stop Session` ，然后调用 `Start Session` 。
{% endhint %}

### 会话开始前的动态上下文排队

默认情况下，防抖调用 `Set Context State`, `Set Context States`, `Add Context Event`以及 `Remove Context State` 在会话连接前发起是安全的，不会受到 `BeginPlay`的影响。每次调用都会累积到 `PendingContextBatch`中。会话连接后，插件会在防抖截止时间已到后的第一个帧刷新该批次。

`Reset Dynamic Context` 在连接前调用不会立即丢弃暂存的更新，而是标记一个待处理的 `Reset` ，该操作会在 **之后触发：所有暂存内容会在连接后的首次刷新时排空。若要从空的动态上下文开始，请先等待重置刷新完成，再暂存新的更新。** 会话 ID 与实时会话

### 会话 ID 与实时会话

`SessionID` 存在于 `UConvaiChatbotComponent`中，但在当前源代码中，已验证的实时 `/connect` 路径不会将其作为 `FConvaiConnectionParams`的一部分发送。不要依赖 `SessionID` 来控制动态上下文重置行为。请对受跟踪的动态上下文层使用 `Reset Dynamic Context` 。

### 后续步骤

{% content-ref url="/pages/8ef7dcd046dad07f4afcb544f96d3beda6feb0ad" %}
[动态上下文的工作原理](https://docs.convai.com/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" %}
[动态上下文快速开始](https://docs.convai.com/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.
