> 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/overview/convai-unity-sdk-architecture.md).

# Convai Unity SDK 架构

了解 Convai Unity SDK 的四层架构——运行时、房间、代理和模块——以及每一层的职责。

SDK 组织为四个层级：Runtime、Room、Agent 和 Module。作为开发者，你主要与 Agent 层（角色和玩家组件）以及 Module 层（按需启用的功能模块）交互。Runtime 和 Room 层负责连接和服务引导，所需配置很少。

### 系统图

```mermaid
graph TD
    subgraph RT["运行时层"]
        CM["ConvaiManager\n（组合根，服务中心）"]
        CS["ConvaiSDK\n（版本元数据）"]
    end

    subgraph RM_TIER["Room 层"]
        RM["ConvaiRoomManager\n（连接 · 音频 · 轮流发言）"]
    end

    subgraph AG["Agent 层"]
        CC["ConvaiCharacter × N\n（会话 · 转录 · 事件）"]
        CP["ConvaiPlayer\n（身份 · 文本输入）"]
    end

    subgraph ML["Module 层（每个角色按需启用）"]
        direction LR
        LS[唇形同步]
        EM[情绪]
        VI[视觉]
        NA[叙事]
        DA[对话动画]
        FA[面部动画]
        GA[凝视]
        AT[注意力]
        CF[对话流程]
        EB[具身化]
    end

    CM --> RM
    RM --> CC
    RM --> CP
    CC -.->|模块附加到| ML
```

从 `ConvaiCharacter` 到 Module 层的虚线表示模块是可选组件，你将它们添加到与角色相同的 GameObject 上——基础对话并不需要。

### 运行时层

运行时层会在场景加载时启动，并为其下方的一切提供服务。

`ConvaiSDK` 是一个静态类，用于公开 SDK 版本（`ConvaiSDK.Version`）。你很少直接引用它。

`ConvaiManager` 是组合根。它是一个单例（`ConvaiManager.ActiveManager`）并标记为 `[DefaultExecutionOrder(-1100)]` ，因此它会在其他场景对象之前初始化。它拥有：

* **服务访问器** — `TryGet` 方法，覆盖所有内部服务（麦克风、音频、Agent 注册表、通知、设置面板等）
* **高级门面** — `ConvaiManager.Audio`, `ConvaiManager.Transcripts`, `ConvaiManager.Events` 用于最常见的脚本任务
* **连接控制** — `ConnectAsync()`, `DisconnectAsync()`, `SetConversationInputModeAsync()`
* **Agent 引用** — `角色`, `Player`, `ActiveConversationCharacter`

{% hint style="info" %}
大多数集成代码只需要 `ConvaiManager.ActiveManager` 以及角色自身的事件。 `TryGet` 服务访问器适用于你要替换或扩展内部服务的高级场景。
{% endhint %}

### Room 层

`ConvaiRoomManager` 负责与 Convai 的实时连接。每个场景一个，由 `ConvaiRoomManager` 管理 `ConvaiManager`.

它负责：

* **Room 连接生命周期** ——连接、断开连接、重新连接
* **麦克风捕获** ——启动和停止音频输入，静音控制
* **轮流发言模式** ——免提（`ConversationInputMode.HandsFree`）或按住说话（`ConversationInputMode.PushToTalk`)
* **动态上下文传输** ——在运行时向 Convai 发送状态更新和事件
* **音频播放协调** ——启用远程角色音频、WebGL 用户手势处理

`ConvaiRoomManager` 为诊断、音频、所有权和连接管理提供协调器。这些可通过 `ConvaiManager.ActiveManager.TryGetRoomConnectionService()` 用于高级脚本编写。

### Agent 层

Agent 层包含你放置在场景 GameObject 上的组件。

#### ConvaiCharacter

添加 `ConvaiCharacter` 添加到每个 NPC 或 agent GameObject 上。每个角色一个组件。它拥有：

* 角色 ID——来自你的 Convai 仪表板的唯一 ID
* 会话状态—— `Disconnected`, `连接中`, `已连接`, `重新连接`, `断开连接`, `Error`
* 会话生命周期—— `StartConversationAsync()`, `StopConversationAsync()`, `ToggleSpeech()`
* 转录和事件回调—— `OnTranscriptReceived`, `OnEmotionChanged`, `OnActionsReceived`, `OnSpeechStarted`, `OnSpeechStopped`, `OnCharacterReady`
* 动作配置——通过 `ConvaiActionConfigSource` 组件

`ConvaiCharacter` 可以在 Inspector 中内联配置，也可以通过可复用的 `ConvaiCharacterProfile` ScriptableObject 资源。

#### ConvaiPlayer

添加 `ConvaiPlayer` 添加到你的玩家 GameObject 上。每个场景一个是标准做法。它拥有：

* 用于转录归属的玩家显示名称和姓名标签颜色
* 文本消息发送—— `SendTextMessage(string message)`
* 运行时身份覆盖—— `SetRuntimeDisplayName(string displayName)`

{% hint style="warning" %}
`ConvaiPlayer.PlayerId` 是用于转录 UI 归属的本地显示标识符。它不是用于长期记忆跟踪的服务器生成说话人 ID。
{% endhint %}

### Module 层

模块是你添加到与 `ConvaiCharacter` （或 `ConvaiRoomManager` 相同 GameObject 上的可选 Unity 组件（用于 Vision）。每个模块彼此独立——只添加项目所需的部分。

| 模块               | 它的作用                                                             |
| ---------------- | ---------------------------------------------------------------- |
| 唇形同步             | 由音频播放驱动的实时 blend shape 口型动画；支持 ARKit、MetaHuman 和 CC4 Extended 映射 |
| 情绪               | 接收 Convai 情绪信号，对其进行平滑处理，并分派到 blend shape 或 Animator 参数绑定         |
| 视觉               | 将摄像头、网络摄像头或 Meta Quest 透视画面发布给 Convai，以实现多模态感知                   |
| 叙事               | 通过与对话流程相关联的触发事件来管理故事段落推进                                         |
| 对话动画             | 在对话期间驱动四层 Animator 堆栈（基础待机、遮罩覆盖、身体说话、头部说话）                       |
| 面部动画             | 在运行时播放面部动画剪辑，并与口型同步和情绪输出进行合成                                     |
| 凝视               | 将眼睛和头部驱动器朝向对话伙伴和注意力目标                                            |
| 注意力              | 解析加权焦点目标，为 Gaze 模块提供凝视方向                                         |
| ConversationFlow | 将对话事件流桥接到逐帧对话状态（空闲、说话、反应等）                                       |
| 具身               | 实体存在和行为模块的基础行为配置文件与生命周期管理                                        |

`ConversationFlow` 会在运行时自动提供，当一个 `ConvaiCharacter` 初始化时。所有其他模块—— `唇形同步`, `情绪`, `视觉`, `叙事`, `对话动画`, `面部动画`, `凝视`, `注意力`，以及 `具身` ——都是按需启用的。

### 配置模型

每个主要组件都支持两种配置模式，可在 Inspector 中选择。

{% tabs %}
{% tab title="内联" %}
值直接在 Inspector 中设置到组件上。这是默认模式，适用于大多数场景——无需额外资源。
{% endtab %}

{% tab title="资源" %}
值来自一个可复用的 `ConvaiCharacterProfile` 或 `ConvaiRoomManagerProfile` ScriptableObject。当你希望在多个场景或预制体变体之间共享默认值，或者需要在不修改单个预制体的情况下切换角色行为时，请使用此模式。
{% endtab %}
{% endtabs %}

### 下一步

{% content-ref url="/pages/c8899f56d4e857b17f25df9ab7da1ed0213d1d5f" %}
[功能地图](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/overview/feature-map.md)
{% endcontent-ref %}

{% content-ref url="/pages/5ea68df21c8a54f95779af92056a9ab831531be5" %}
[快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started.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/overview/convai-unity-sdk-architecture.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.