> 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/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md). # 脚本 API 参考 Dynamic Context 脚本接口上每个方法、参数和返回值的完整参考——供通过游戏代码驱动角色感知的开发者使用。 ## 脚本 API 参考：IConvaiDynamicContext `IConvaiDynamicContext` 是 Dynamic Context 的 C# 脚本接口。它作为一个属性暴露在 `ConvaiCharacter` 上，并提供七个方法，涵盖所有上下文操作——从设置单个跟踪状态到发送原始类型化更新。本文档是面向开发者的权威参考，适用于从游戏系统、物品栏管理器、事件总线或任何其他运行时逻辑驱动 Dynamic Context。 ## 访问该接口 ```csharp using Convai.Runtime.Components; using Convai.Runtime.DynamicContext; using UnityEngine; public class MyContextController : MonoBehaviour { [SerializeField] private ConvaiCharacter _character; private void Start() { IConvaiDynamicContext context = _character.DynamicContext; // 安全缓存——懒加载初始化，ConvaiCharacter 构造后永不为 null。 } } ``` `ConvaiCharacter.DynamicContext` 是一个懒加载初始化的属性，返回一个 `IConvaiDynamicContext` 门面。返回的引用可安全缓存。它在 `ConvaiCharacter` 组件构造后永不为 null。 ## 方法 ### SetState ```csharp void SetState(string name, string value, ConvaiContextReactionMode reaction = ConvaiContextReactionMode.SyncOnly) ``` 在角色上设置一个单独的跟踪状态。
参数类型默认值说明
名称string—状态名称。必须非 null 且不能全为空白。
值string—状态值。必须非 null。空字符串是有效值。
反应ConvaiContextReactionMode仅同步控制角色在更新后是否立即生成响应。
**行为：** * 如果状态不存在，则创建它并发送一条 Append 消息（`"名称是值"`）。 * 如果状态已经存在且 **不同的** 值，则先发送一条 Replace 消息（完整规范上下文），随后发送一条 Append 消息（`"名称从旧值更改为新值"`). * 如果状态已经存在且 **相同** 值，则不会发送任何消息——该操作是幂等的，不会产生网络流量，也不会重新提示 LLM。 **验证：** 如果 `名称` 为空或全为空白，或者如果 `值` 为 null，则记录警告并返回，不发送。 *** ### SetStates ```csharp void SetStates(IReadOnlyDictionary states, ConvaiContextReactionMode reaction = ConvaiContextReactionMode.SyncOnly) ``` 以单个原子操作更新多个跟踪状态。当多个值同时变化时，优先使用它而不是多个顺序 `SetState` 调用。 | 参数 | 类型 | 默认值 | 说明 | | ---- | ------------------------------------- | ----- | ---------------------- | | `状态` | `IReadOnlyDictionary` | — | 状态名到值的字典。必须非 null 且非空。 | | `反应` | `ConvaiContextReactionMode` | `仅同步` | 应用于整个批次。 | **行为：** * 如果 **任何** 字典中的状态已经存在于跟踪器中（无论其值为何），则先发送一条 Replace 消息（包含所有更新值的完整规范上下文），然后再发送一条概括所有更改的 Append 消息。 * 如果 **全部** 如果字典中的状态是新状态，则为所有状态发送一条 Append 消息。 * 键为空或全为空白的字典项会被静默跳过。 **验证：** 如果 `状态` 为空或为空集，则记录警告并返回。 *** ### AddEvent ```csharp void AddEvent(string text, ConvaiContextReactionMode reaction = ConvaiContextReactionMode.Auto) ``` 将一个按时间顺序排列的事件追加到角色的上下文中。 | 参数 | 类型 | 默认值 | 说明 | | ------ | --------------------------- | ---- | ------------------------------------------------------------------------------- | | `text` | `string` | — | 要追加的事件文本。必须非 null 且不能全为空白。 | | `反应` | `ConvaiContextReactionMode` | `自动` | 控制事件是否立即触发一次 LLM 回合。注意：这里的默认值是 `自动`，不同于 `SetState` 和 `SetStates` ，后者默认值为 `仅同步`. | **行为：** 在规范上下文中，事件会在所有跟踪状态之后按时间顺序累积。以相同文本调用 `AddEvent` 两次会追加两次——事件永远不会去重。 **验证：** 如果 `text` 为空或全为空白。 *** ### RemoveState ```csharp void RemoveState(string name) ``` 按名称移除一个跟踪状态。不暴露 `反应` 参数。 | 参数 | 类型 | 说明 | | ---- | -------- | --------------- | | `名称` | `string` | 要移除的状态名称。区分大小写。 | **行为：** 从本地跟踪器中移除该状态后，会发送一条 Replace 消息，并带上剩余的规范上下文。删除始终产生 Replace（而不是 Append），因为角色必须收到权威的更新状态集合。如果 `名称` 与任何跟踪状态都不匹配，则该调用无操作。 *** ### Reset ```csharp void Reset() ``` 清除所有跟踪状态和事件，并通知角色。 **行为：** 本地跟踪器将被完全清空。会向角色发送一条 Reset 模式消息——不包含文本。配置在 `ConvaiCharacter` 是 **不是** 上的初始动态信息文本不会被重新发送；只会擦除运行时跟踪的状态和事件。 在……之后 `Reset()`后，角色的动态上下文为空。后续的 `SetState` 或 `AddEvent` 调用会从零开始构建新的上下文。 *** ### TryGetStateValue ```csharp bool TryGetStateValue(string name, out string value) ``` 从本地跟踪器中读取某个状态的当前跟踪值。 | 参数 | 类型 | 说明 | | ------ | -------------- | ---------------------------------- | | `名称` | `string` | 要查找的状态名称。 | | `值` | `string` (out) | 如果找到该状态，则接收当前值。 | | **返回** | `bool` | `true` 如果该状态存在于本地跟踪器中； `false` 否则。 | **重要：** 此方法仅从 **本地跟踪器**读取。它不会查询 Convai 服务器。本地跟踪器反映通过 `SetState`, `SetStates`，以及 `RemoveState` 进行的所有 `IConvaiDynamicContext`调用。它不反映通过 `Apply()`. 使用 `TryGetStateValue` 发送的任何内容，用于条件逻辑——例如，当从游戏视角看值未变化时跳过一次 `SetState` 调用，或在触发对话分支前检查装备状态。 *** ### 应用 ```csharp void Apply(ConvaiDynamicContextUpdate update) ``` 直接将一个原始类型化更新发送到传输层，完全绕过本地状态跟踪器。 | 参数 | 类型 | 说明 | | ---- | ---------------------------- | ---------- | | `更新` | `ConvaiDynamicContextUpdate` | 要发送的类型化更新。 | **行为：** * 如果角色正处于活动对话中，则立即发送该更新。 * **不会在对话前排队。** 如果角色不在对话中， `Apply()` 则是静默无操作。不同于 `SetState` 和 `AddEvent`，此方法不会将其效果排队以供稍后刷新。 * 不会更新本地跟踪器。 `TryGetStateValue` 结果不受 `Apply()` 调用。 **何时使用：** 使用 `Apply()` 当你需要发送一个 `Reset` 模式更新，或者外部系统构建了自己的上下文文本且不需要 SDK 的状态跟踪时。对于所有标准状态管理，优先使用 `SetState`, `SetStates`, `AddEvent`，以及 `RemoveState`. ## ConvaiDynamicContextUpdate `ConvaiDynamicContextUpdate` 是用于 `Apply()`的类型化参数。它将一个文本字符串、一个更新模式和一个反应模式打包为一个值。 ```csharp var update = new ConvaiDynamicContextUpdate( text: "Trainee score is 72", mode: ConvaiContextUpdateMode.Append, reaction: ConvaiContextReactionMode.SyncOnly ); _character.DynamicContext.Apply(update); ``` | 参数 | 类型 | 默认值 | 说明 | | ------ | --------------------------- | ---- | ---------------------------------- | | `text` | `string` | — | 要发送的上下文文本。当使用时忽略 `mode` 是 `Reset`. | | `mode` | `ConvaiContextUpdateMode` | `附加` | 文本在后端如何应用。 | | `反应` | `ConvaiContextReactionMode` | `自动` | 角色是否立即响应。 | ## 对话前排队 所有已跟踪的方法—— `SetState`, `SetStates`, `AddEvent`, `RemoveState`，以及 `Reset` ——当角色尚未处于活动对话中时，会自动排队其效果。对话开始后，所有待处理更新会作为一次规范同步统一刷新，或者如果 `Reset()` 是最后一次调用，则作为 Reset 刷新。 这意味着可以安全地从 `Awake()`, `Start()`，或任何在角色连接之前运行的初始化代码中调用这些方法——更新不会丢失。 {% hint style="warning" %} `Apply()` 不会 **不是** 排队。如果在对话开始前调用，它会被静默丢弃，不会发出警告。调用 `Apply()`之前，请始终确保角色处于活动对话中，或者使用会自动排队的已跟踪方法。 {% endhint %} ## 枚举参考 ### ConvaiContextReactionMode 控制上下文更新是否会触发角色立即进行一次 LLM 响应。
值数值行为
自动0由服务器决定该更新是否值得立即进行一次 LLM 回合。建议作为大多数情况的默认值——当更新具有重要性时角色会作出反应，而不必每次都被强制响应。
立即响应1更新应用后总是立即触发一次 LLM 回合。即使在对话中途，角色也会生成对新上下文作出反应的回复。适用于需要立即确认的高影响事件。
仅同步2在不提示 LLM 的情况下存储上下文。角色保持沉默，并将新信息纳入其下一次自然回复中。适用于不需要确认的后台状态更新。
### ConvaiContextUpdateMode 控制上下文文本在后端的应用方式。与使用 `Apply()` 或 `原始更新` 命令类型时相关。已跟踪的方法（`SetState`, `SetStates`, `AddEvent`, `RemoveState`）会自动管理这一点，不会直接暴露它。
值数值行为
附加0将文本添加到现有的临时上下文中。角色的上下文会增长。
替换1用新文本替换整个临时上下文。之前累积的一切都会被丢弃。
Reset2清除所有临时上下文。使用此模式时， text 字段将被忽略。
## 接下来 * [同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/sync-behavior-and-timing.md) ——包括两消息 Replace+Append 模式以及对话前队列刷新机制，说明每种更新类型何时以及如何传输。 ## 结论 `IConvaiDynamicContext` 为每个 Dynamic Context 操作提供了精确、类型安全的接口；跟踪方法会在对话开始前自动排队； `Apply()` 则不会——请据此选择。要全面了解每种更新类型何时以及如何传输，请参阅 [同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/sync-behavior-and-timing.md). --- # 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/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md?ask=&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.