> 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 架构

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

### 系统图

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

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

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

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

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

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

### 运行时层

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

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

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

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

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

### 房间层

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

它负责：

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

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

### Agent 层

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

#### ConvaiCharacter

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

* 角色 ID——来自你 Convai 仪表板的唯一 ID
* 会话状态—— `已断开`, `连接中`, `已连接`, `重新连接中`, `Disconnecting`, `错误`
* 对话生命周期—— `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 %}

### 模块层

模块是你添加到与 `ConvaiCharacter` （或 `ConvaiRoomManager` （用于视觉）。每个模块彼此独立——只添加项目所需的部分。

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

`ConversationFlow` 在 `ConvaiCharacter` 初始化时会在运行时自动提供。所有其他模块—— `LipSync`, `情绪`, `视觉`, `叙事`, `DialogueAnimation`, `FacialAnimation`, `凝视`, `Attention`，以及 `Embodiment` ——均为按需启用。

### 配置模型

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

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

{% tab title="资源" %}
值来自可复用的 `ConvaiCharacterProfile` 或 `ConvaiRoomManagerProfile` ScriptableObject。当前你希望在多个场景或 prefab 变体之间共享默认值，或者需要在不修改单个 prefab 的情况下切换角色行为时，请使用此模式。
{% 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 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/convai-unity-sdk/overview/convai-unity-sdk-architecture.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.