> 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.md). # 动态上下文 ## 动态上下文动态上下文是你在对话中将实时运行时信息——玩家状态、环境条件、模拟事件——直接输入 Convai 角色感知的机制。没有它，角色只知道配置时写入其系统提示中的内容。有了动态上下文，它就能在周围世界实时变化时加以识别并作出响应。本节涵盖动态上下文的方方面面：如何在不写一行代码的情况下进行设置，如何在游戏逻辑需要时通过脚本驱动它，以及决定更新何时以及如何到达角色的精确规则。 ## 工作原理动态上下文建立在两个概念之上： **状态** 是持久存在的键值事实，用于描述某物的当前状况。状态有名称和值——例如， `“危险等级”` 为 `“高”`，或 `“当前站点”` 为 `“控制室 B”`。当状态变化时，旧值会被替换。角色始终知道每个状态的当前值。 **事件** 是按时间顺序追加的一次性事件——例如， `“学员绕过了紧急锁定”` 或 `“访客询问了反应堆安全壳”`。事件永远不会被替换或去重；它们会作为时间线不断累积，供角色引用。当角色接收上下文时，它会先看到状态（按首次引入的顺序），然后按时间顺序看到事件： ``` 当前站点是控制室 B 危险等级是高学员绕过了紧急锁定访客询问了反应堆安全壳 ``` 这种规范化格式由 SDK 自动组装。你只需提供名称、值和事件文本。 ## 两个入口动态上下文可以通过检查器或 C# 脚本驱动。两条路径都接入同一个底层跟踪器。 ```mermaid flowchart TD A["ConvaiDynamicContextCommand\n(检查器 / UnityEvent)"] B["ConvaiCharacter.DynamicContext\n(脚本 API)"] T["DynamicContext 跟踪器\n保存规范化状态 + 事件"] Q["待处理队列\n（在对话开始时刷新）"] R["RTVI 上下文更新消息"] C["Convai 角色推理"] A -->|执行| T B -->|SetState / AddEvent / ...| T T -->|对话尚未开始| Q T -->|对话中| R Q --> R R --> C ``` 该 **检查器路径** 使用 `ConvaiDynamicContextCommand`，这是一个可添加到任何 GameObject 的无代码组件。你可以直接在检查器中配置命令类型及其参数，然后调用 `Execute()` 从任何 `UnityEvent`、动画时间轴、触发器碰撞体或按钮点击中触发。该 **脚本路径** 访问 `ConvaiCharacter.DynamicContext`，它会返回一个 `IConvaiDynamicContext` 接口，包含七个方法，覆盖从设置单个状态到发送原始类型化更新的所有操作。两条路径共用同一个跟踪器、同一个对话前队列和同一种传输方式。 ## 示例：火灾模拟中途的安全培训上下文为了更具体地说明，以下是一个安全培训角色在火灾应急演练进行到一半时，其上下文可能是什么样子： ``` 站点是灭火区危险等级是极高当前灭火剂是 CO2 学员在电气火灾上启动了水基抑制器学员绕过了手动锁定 ``` 角色可以自然地引用这些内容中的任何一项： *“我能看到你现在在灭火区——在极高危险等级下，绕过手动锁定是一个严重错误。让我们先回顾一下本来应该怎么做。”* ## 关键概念一览

概念	描述
状态	一种带名称、持久存在的键值事实。值发生变化时会就地更新。
事件	一种按时间顺序追加的事件。永不去重。
规范化上下文	完整组装后的上下文字符串：先是状态（插入顺序），然后是事件（时间顺序）。
响应模式	控制上下文更新是否会立即触发角色的 LLM 响应。
对话前队列	在对话开始之前进行的更新会被排队，并在对话开始时自动刷新。
初始上下文	在 `ConvaiCharacter` 中设置的一段固定文本，会在连接时一次性发送，与运行时更新分开。

## 各项放在哪里

入口	位置 / 方式	最适合
`ConvaiDynamicContextCommand`	添加组件在任何 GameObject 上；通过 `Execute()` 从任何 `UnityEvent`	设计师和技术美术；以检查器驱动的工作流、按钮、时间轴、触发器
`ConvaiCharacter.DynamicContext`	在 C# 中访问为 `character.DynamicContext`	程序员；游戏系统、库存管理器、事件总线
初始上下文（`ConvaiCharacter`)	动态信息（连接请求）位于……上的 `ConvaiCharacter` 检查器	在会话开始时、第一轮对话之前一次性发送的固定场景事实

## 本节内容


快速开始	从检查器中配置你的第一条动态上下文更新，将其连接到 UnityEvent，并在对话中观察角色引用实时游戏状态。
命令组件参考	关于所有六种命令类型的逐字段完整参考，位于 `ConvaiDynamicContextCommand`.
连接时的静态上下文	设置一个固定的上下文块，在对话开始时一次性发送，在任何运行时更新之前。
使用示例	覆盖四种模拟场景的真实示例，展示完整的命令功能。
脚本 API 参考	全部七个 `IConvaiDynamicContext` 方法，具有精确的签名和参数语义。
同步行为与时序	更新何时以及如何发送；规范重建；对话前排队；传输细节。
故障排查与诊断	诊断静默更新、意外的角色响应以及对话前时序问题。

## 结论动态上下文让你的 Convai 角色感知模拟中一切重要的信息——从学员当前所在站点到他们刚刚犯下的错误。该 [快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/quick-start.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.md?ask= ``` 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.