> 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-unity-sdk/features/dynamic-context/dynamic-context-quick-start.md).

# 动态上下文快速开始

向 NPC 添加 Dynamic Context Relay 组件，从 UI 按钮发送一次被跟踪的更新，并确认角色引用了它。

本指南添加了一个 `ConvaiDynamicContextRelay` 组件到 NPC，配置一个 UI 按钮以发送已跟踪的上下文更新，并确认角色在对话中会引用该更新。请在以下情况之后使用它：一个 `ConvaiCharacter` 已经在 Play 模式下连接并响应语音。

### 前置条件

开始之前，请确认：

* [ ] 一个 `ConvaiCharacter` 已在场景中并在 Play 模式下响应语音

### 为角色添加动态上下文

{% stepper %}
{% step %}

#### 添加中继组件

在 Hierarchy 中选择 NPC 的 GameObject。在 Inspector 中，点击 **添加组件** 中搜索 **Convai Dynamic Context Relay**，或者导航到 **Convai → Dynamic Context → Convai Dynamic Context Relay**.

该组件会添加三个部分： **目标** （它驱动的是哪个角色）， **默认值** （应用于每次调用的响应模式和刷新行为），以及 **事件** （用于排队和跳过调用的回调）。
{% endstep %}

{% step %}

#### 验证角色解析

在 **目标** 部分，确认 **Auto Resolve Character** 已启用（默认）。中继会查找一个 `ConvaiCharacter` 在调用时位于同一 GameObject 上。

如果 `ConvaiCharacter` 位于不同的 GameObject 上，请禁用 **Auto Resolve Character** 并拖入正确的 `ConvaiCharacter` 到 **Character** 字段。已分配的 **Character** 始终优先于自动解析。
{% endstep %}

{% step %}

#### 配置默认值

在 **默认值** 部分：

* 保持 **Reaction Mode** 在 **Silent** （默认）。使用 **Silent**，更新会被吸收进角色的认知中，但不会让它立即开口——角色会在下一次回复中将其纳入。
* 保持 **Flush Immediately** 已禁用（默认）。角色会将中继更新批量处理约半秒后再发送；仅当某次调用必须在不等待批处理窗口的情况下到达 Convai 时，才启用此字段。
  {% endstep %}

{% step %}

#### 连接触发器

向场景中添加一个 UI Button（临时按钮也可以）。在其 **按钮** 组件中，打开 **On Click ()**.

点击 **+** 以添加监听器，将 NPC 的 GameObject 拖到对象字段中，然后选择 **ConvaiDynamicContextRelay → AddEvent** 从函数下拉菜单中选择。下拉菜单下方会出现一个文本字段——在那里输入事件文本，因为 `Button.onClick` 本身不携带任何数据：

```
玩家进入了消防出口走廊。
```

{% endstep %}

{% step %}

#### 在 Play 模式下测试

进入 Play 模式并与角色开始对话。点击上一步中连接的按钮，然后问角色类似“这里发生了什么？”的问题。

角色应该会引用该事件——例如： *“你刚才进入了消防出口走廊。继续往前之前，先记住疏散程序。”*

如果角色没有引用该事件，请打开 Unity Console 并检查来自以下项的警告： `ConvaiDynamicContextRelay` 或 `ConvaiCharacter`。请参阅 [排查动态上下文问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/troubleshoot-dynamic-context.md) 以获取完整的诊断清单。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
你的角色现在已具备上下文感知能力。你发送的事件会记录在角色的 `DynamicContext` 并在批处理窗口关闭后发送到 Convai（或者如果 **Flush Immediately** 已启用，则会立即发送）。任何后续的 `AddEvent`, `SetState`，或通过中继进行的关注对象调用，都会以相同方式传递。
{% endhint %}

### 无需自定义代码进行测试

导入 **LipSync 示例** 从 Package Manager 并打开其场景。该示例包含一个 **示例调试中心** 并传入一个 **上下文** 抽屉，可将状态、事件和注意对象更新发送到场景的 `ConvaiCharacter` 无需连接你自己的 UI 即可使用。如果角色通过 Debug Hub 能正常响应，但通过你自己的中继设置却不能，那么问题出在你的 Inspector 配置上——而不是 Dynamic Context 本身。

### 下一步

{% content-ref url="/pages/743bcc7de155496cbbf02a52a5577aee99f28aab" %}
[中继组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/relay-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/5c3f9bcc544ac6f441fe54139ac1c670eeb5c958" %}
[动态上下文脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/493c8451db0d99cc31b81e26c17158c645622f0e" %}
[动态上下文使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/bb1aef3496a2be08987c770aa7b8072e7d8c5cd6" %}
[同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.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-unity-sdk/features/dynamic-context/dynamic-context-quick-start.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.