脚本 API 参考

动态上下文脚本接口上每个方法、参数和返回值的完整参考——供从游戏代码驱动角色感知的开发者使用。

脚本 API 参考：IConvaiDynamicContext

IConvaiDynamicContext 是 Dynamic Context 的 C# 脚本接口。它作为 ConvaiCharacter 上的一个属性暴露，并提供七个方法，覆盖所有上下文操作——从设置单个跟踪状态到发送原始类型化更新。本页是面向开发者的权威参考，适用于从游戏系统、物品管理器、事件总线或任何其他运行时逻辑中驱动 Dynamic Context。

访问接口

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

void SetState(string name, string value, 
ConvaiContextReactionMode reaction = ConvaiContextReactionMode.SyncOnly)

在角色上设置一个跟踪状态。

参数	类型	默认值	描述
name	字符串	—	状态名称。必须非 null 且不能只包含空白字符。
value	字符串	—	状态值。必须非 null。空字符串是有效值。
reaction	ConvaiContextReactionMode	SyncOnly	控制角色在更新后是否立即生成响应。

行为：

• 如果状态不存在，则会创建它，并发送一条 Append 消息（"Name is Value"）。
• 如果状态已存在，但值 不同， 则先发送一条 Replace 消息（完整规范上下文），然后再发送一条 Append 消息（"Name changed from OldValue to NewValue").
• 如果状态已存在且值 相同， 则不发送任何消息——该操作是幂等的，不会产生网络流量，也不会重新提示 LLM。

验证： 如果 name 为 null 或只包含空白字符，或者如果 value 为 null，则记录警告并直接返回，不发送。

---

SetStates

void SetStates(IReadOnlyDictionary<string, string> states, 
ConvaiContextReactionMode reaction = ConvaiContextReactionMode.SyncOnly)

在一次原子操作中更新多个跟踪状态。当多个值同时变化时，优先使用它而不是多个顺序 SetState 调用。

参数	类型	默认值	描述
states	IReadOnlyDictionary<string, string>	—	状态名称到值的字典。必须非 null 且非空。
reaction	ConvaiContextReactionMode	SyncOnly	应用于整个批次。

行为：

• 如果 任何 如果字典中的某个状态在跟踪器中已存在（无论什么值），则先发送一条 Replace 消息（包含所有已更新值的完整规范上下文），然后发送一条汇总所有更改的单条 Append 消息。
• 如果 所有 如果字典中的状态全部都是新的，则会为它们发送一条单独的 Append 消息。
• 键为 null 或只包含空白字符的字典项会被静默跳过。

验证： 如果 states 为 null 或空，则记录警告并返回。

---

AddEvent

void AddEvent(string text, 
ConvaiContextReactionMode reaction = ConvaiContextReactionMode.Auto)

向角色的上下文附加一个按时间顺序排列的事件。

参数	类型	默认值	描述
text	字符串	—	要附加的事件文本。必须非 null 且不能只包含空白字符。
reaction	ConvaiContextReactionMode	自动	控制该事件是否立即触发一次 LLM 回合。注意：这里的默认值是 自动，不同于 SetState 和 SetStates ，后者默认是 SyncOnly.

行为： 事件会在规范上下文中所有跟踪状态之后按时间顺序累积。使用 AddEvent 以相同文本调用两次会附加两次——事件绝不会去重。

验证： 如果 text 为 null 或只包含空白字符。

---

RemoveState

void RemoveState(string name)

按名称移除一个跟踪状态。不暴露 reaction 参数。

参数	类型	描述
name	字符串	要移除的状态名称。区分大小写。

行为： 在从本地跟踪器中移除该状态后，会发送一条包含剩余规范上下文的 Replace 消息。移除操作总是产生 Replace（而不是 Append），因为角色必须接收权威的已更新状态集合。如果 name 与任何跟踪状态都不匹配，则该调用无操作。

---

Reset

void Reset()

清除所有跟踪状态和事件，并通知角色。

行为： 本地跟踪器会被完全清空。会向角色发送一条 Reset 模式消息——不包含文本。配置在 ConvaiCharacter 为 上的初始动态信息文本 不会

在……之后 重新发送；只会清除运行时跟踪的状态和事件。在调用 Reset() 后，角色的动态上下文为空。后续 SetState 或 AddEvent 调用会从头构建新上下文。

---

TryGetStateValue

bool TryGetStateValue(string name, out string value)

从本地跟踪器读取某个状态当前跟踪的值。

参数	类型	描述
name	字符串	要查找的状态名称。
value	字符串 （out）	如果找到该状态，则接收当前值。
返回	bool	true 如果该状态存在于本地跟踪器中； false 否则为 false。

重要： 此方法只从 本地跟踪器读取。它不会查询 Convai 服务器。本地跟踪器反映所有通过 SetState, SetStates，以及 RemoveState 调用所做的 IConvaiDynamicContext。它不会反映任何通过 Apply().

使用 TryGetStateValue 发送的内容，可用于条件逻辑——例如，当从游戏视角看值没有变化时跳过一次 SetState 调用，或在触发对话分支之前检查装备状态。

---

Apply

void Apply(ConvaiDynamicContextUpdate update)

直接将原始类型化更新发送到传输层，完全绕过本地状态跟踪器。

参数	类型	描述
update	ConvaiDynamicContextUpdate	要发送的类型化更新。

行为：

• 如果角色正处于活动对话中，则立即发送更新。
• 不会在对话前排队。 如果角色不在对话中， Apply() 则为静默无操作。与 SetState 和 AddEvent不同，此方法不会把其效果排队等待稍后刷新。
• 不会更新本地跟踪器。 TryGetStateValue 结果不受 Apply() 调用的影响。

何时使用： 使用 Apply() 当你需要发送 Reset 模式更新时，或者当外部系统自己构建上下文文本且不需要 SDK 的状态跟踪时。对于所有标准状态管理，请优先使用 SetState, SetStates, AddEvent，以及 RemoveState.

ConvaiDynamicContextUpdate

ConvaiDynamicContextUpdate 是 Apply()的类型化参数。它将文本字符串、更新模式和反应模式打包为一个值。

var update = new ConvaiDynamicContextUpdate(
    text: "Trainee score is 72",
    mode: ConvaiContextUpdateMode.Append,
    reaction: ConvaiContextReactionMode.SyncOnly
);
_character.DynamicContext.Apply(update);

参数	类型	默认值	描述
text	字符串	—	要发送的上下文文本。当 mode 为 Reset.
mode	ConvaiContextUpdateMode	Append	文本在后端的应用方式。
reaction	ConvaiContextReactionMode	自动	角色是否立即响应。

对话前排队

所有跟踪方法—— SetState, SetStates, AddEvent, RemoveState，以及 Reset ——当角色尚未处于活动对话中时，会自动将其效果排队。当对话开始时，所有待处理更新会作为一次单一的规范同步刷新，或者在如果 重新发送；只会清除运行时跟踪的状态和事件。 是上一次调用时，作为 Reset 刷新。

这意味着你可以安全地从 Awake(), Start()或任何在角色连接之前运行的初始化代码中调用这些方法——更新不会丢失。

Apply() 不会 上的初始动态信息文本 排队。如果在对话开始前调用，它会被静默丢弃，不会给出警告。调用 Apply()之前，请务必确保角色处于活动对话中，或者使用会自动排队的跟踪方法。

枚举参考

ConvaiContextReactionMode

控制上下文更新是否会触发角色立即生成 LLM 响应。

值	数值	行为
自动	0	由服务器决定该更新是否值得立即进行一次 LLM 回合。建议在大多数情况下作为默认值——当更新足够重要时角色会做出反应，而不会被强制每次都响应。
ReactImmediately	1	在更新应用后始终立即触发一次 LLM 回合。即使在对话进行中，角色也会生成对新上下文的响应。适用于需要立即确认的高影响事件。
SyncOnly	2	在不提示 LLM 的情况下存储上下文。角色保持沉默，并在下一次自然响应中纳入新信息。适用于不需要确认的后台状态更新。

ConvaiContextUpdateMode

控制上下文文本在后端的应用方式。在使用 Apply() 或 RawUpdate 命令类型时相关。跟踪方法（SetState, SetStates, AddEvent, RemoveState）会自动管理这一点，不会直接暴露它。

值	数值	行为
Append	0	将文本添加到现有的临时上下文中。角色的上下文会增长。
Replace	1	用新文本替换整个临时上下文。之前累积的所有内容都会被丢弃。
Reset	2	清除所有临时上下文。使用该模式时会忽略 text 字段。

接下来

• 同步行为与时序 ——每种更新类型何时以及如何传输，包括双消息 Replace+Append 模式以及对话前队列刷新的机制。

结论

IConvaiDynamicContext 为每个 Dynamic Context 操作提供了精确且类型安全的接口。跟踪方法会在对话开始前自动排队； Apply() 则不会——请据此选择。有关每种更新类型何时以及如何传输的完整说明，请参阅 同步行为与时序.