> 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/usage-examples.md).

# 使用示例

## 动态上下文实践：演练模拟场景

以下场景演示了动态上下文在学习和训练模拟中的应用。每个示例都是独立的，并展示了不同的上下文操作组合。它们共同覆盖了该功能的全部范围——从简单的状态更新到批量过渡和响应式事件。

## 场景 A — 安全演练：灭火评估

一名安全培训角色引导学习者完成灭火演练。该角色必须知道受训者所在的站点、当前危险级别以及受训者犯下的任何关键错误，以便提供有针对性的即时反馈。

### 初始上下文

在 NPC 的 `ConvaiCharacter` 检查器中，在 **动态信息（连接请求）**，设置：

```
站点是灭火区
危险等级是极高
```

启用 **初始动态信息保留在上下文中** ，以便角色在整个对话过程中始终保留场景框架。

### 区域进入：设置当前设备

当受训者进入 CO2 灭火剂区域时， `ConvaiDynamicContextCommand` 触发器碰撞体上的 `Execute()` ，带有：

* **命令类型：** `SetState`
* **状态名称：** `当前灭火剂`
* **状态值：** `CO2`
* **反应：** `SyncOnly`

无需立即的角色回应——角色会在下一次对话轮次中自然提及该灭火剂。

### 错误：激活了错误的灭火剂

当受训者激活了错误的灭火剂（水用于电气火灾）时，模拟会从脚本中触发一个事件：

```csharp
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

public class SuppressionAssessment : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;

    public void OnWrongSuppressorActivated()
    {
        _character.DynamicContext.AddEvent(
            "受训者在电气火灾上启用了水基灭火剂",
            ConvaiContextReactionMode.ReactImmediately
        );
    }
}
```

`ReactImmediately` 会迫使角色立即回应——例如： *"停下——在电气火灾上使用水极其危险。让我们先讨论为什么这里应该选择 CO2，然后再继续。"*

### 危险已清除：移除状态

当演练结束且危险得到解决时， `ConvaiDynamicContextCommand` 会触发：

* **命令类型：** `RemoveState`
* **状态名称：** `危险级别`

规范化上下文会在不包含危险级别的情况下重建，因此角色不再提及当前紧急情况。

## 场景 B — 入职引导：设备交接

一名入职引导角色带领新员工完成一项流程性设备检查。该角色必须知道受训者已收集了哪些设备以及哪些检查点已清除——并且不应重复解释它已经知道受训者完成过的内容。

### 拾取物品时批量更新状态

当受训者拿起一整套 PPE 套装时，一次更新多个状态：

```csharp
using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

public class EquipmentPickup : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;

        _character.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "设备", "完整的 PPE 套装" },
                { "检查点", "更衣室已清除" }
            },
            ConvaiContextReactionMode.SyncOnly
        );
    }
}
```

将这两个更新批量合并为一次 `SetStates` 调用，可避免两次单独的规范化重建，并向角色发送一次原子更新——比两个顺序的 `SetState` 调用的影响。

### 使用 TryGetStateValue 的条件逻辑

在触发解释 PPE 使用的对话分支之前，检查 SDK 是否已经知道受训者拥有该设备。这样可以防止冗余更新，并避免重复解释角色已经知道的内容：

```csharp
public void OnApproachEquipmentStation()
{
    if (!_character.DynamicContext.TryGetStateValue("Equipment", out string equipment)
        || equipment != "Full PPE kit")
    {
        _character.DynamicContext.SetState(
            "设备", "完整的 PPE 套装",
            ConvaiContextReactionMode.SyncOnly
        );
        TriggerEquipmentExplanationDialogue();
    }
}
```

`TryGetStateValue` 读取本地追踪器——它不会查询服务器——因此可以安全地频繁调用，而不会产生网络开销。

### 在下一个站点重置

当受训者移动到下一个入职站点并开始新的检查清单时，清除会话上下文：

```csharp
public void OnAdvanceToNextStation()
{
    _character.DynamicContext.Reset();
}
```

这会清除所有已跟踪的状态和事件。最初设置的 `ConvaiCharacter` 上下文会被保留——只会擦除运行时跟踪的信息。

## 场景 C — 引导式参观：带有时间线事件的自适应叙述

一名引导式参观角色会随着访客浏览展品而提供自适应解说。两个 `ConvaiDynamicContextCommand` 组件被连接到 Playable Director 时间线信号——一个更新当前展品，另一个记录访客交互。

### 检查器设置

由于 `ConvaiDynamicContextCommand` 为 `[DisallowMultipleComponent]`，请将每个命令放在 NPC 的单独子 GameObject 上。将它们配置如下：

**命令 A — 展品更新** （在子 GameObject `ContextCmd_Exhibit`)

* **命令类型：** `SetState`
* **状态名称：** `展品`
* **状态值：** `反应堆核心模型`
* **反应：** `SyncOnly`

**命令 B — 访客交互** （在子 GameObject `ContextCmd_Interaction`)

* **命令类型：** `AddEvent`
* **事件文本：** `访客询问了遏制协议`
* **反应：** `自动`

在 **目标** 部分中，将 NPC 的 `ConvaiCharacter` 显式地在 **角色** 字段中指定（因为这些命令位于子 GameObject 上，而不是 NPC 根对象上）。

将每个命令的 `Execute()` 连接到 Playable Director 时间线中相应的动画事件信号。

### 使用 OnExecuted 提供 UI 反馈

将 **On Executed** 上的命令 A 连接到一个 UI 组件，该组件会在界面中高亮显示当前展品标签：

```
命令 A → On Executed → ExhibitHighlight.Activate()
```

一次 `Execute()` 调用既更新角色的上下文，又驱动视觉 UI 响应——无需额外脚本。

## 场景 D — 多状态场景过渡与即时反应

一个训练场景从常规检查阶段过渡到应急响应阶段。多个状态值同时变化，而角色应立即确认新情况，而无需等待受训者开口。

### 过渡

```csharp
using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

public class EmergencyTransition : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;

    public void TriggerEmergencyPhase()
    {
        _character.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "Phase", "Emergency Response" },
                { "Alert Level", "Red" },
                { "Time Remaining", "4 minutes" },
                { "Primary Hazard", "Uncontrolled gas release" }
            },
            ConvaiContextReactionMode.ReactImmediately
        );
    }
}
```

`ReactImmediately` 与 `SetStates` 结合后，会使角色在批量更新应用后立即生成响应——例如： *"警报——我们已进入应急响应阶段。检测到失控气体释放，警报级别为红色，你还有四分钟。你的第一步行动是什么？"*

### 为什么使用批量而不是顺序 SetState 调用

四次顺序的 `SetState` 调用会触发多达四次规范化重建和四次潜在的 LLM 重新提示，每次可能得到不同的反应模式结果。一次 `SetStates` 调用会发送一次原子更新——一次 Replace（如果有任何现有状态被触及）加上一次概括所有更改的 Append——并应用 `ReactImmediately` 反应且仅一次。结果是对完整场景变化给出一次干净、权威的角色回应。

## 接下来

* [脚本 API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md) ——每个上面的脚本示例背后的完整方法签名和参数语义。
* [同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/sync-behavior-and-timing.md) ——精确说明每种更新类型何时传输，以及 SDK 如何决定发送 Replace、Append，还是两者都发送。

## 结论

这四个场景覆盖了动态上下文操作的完整范围——从单个由 Inspector 驱动的状态更新，到带即时反应的脚本化批量过渡。有关每个脚本示例背后的方法签名，请参见 [脚本 API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.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 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/unity-plugin-beta-overview/features/dynamic-context/usage-examples.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.