运行时架构
了解 Convai Unity SDK 的四层运行时——每层负责什么、哪些组件可替换，以及 RuntimeState 转换如何管理。
Convai Unity SDK 采用分层架构。每一层都有明确的职责，并且通信方向向内——外层依赖内层，绝不相反。理解这一结构可以让你知道 SDK 的哪些部分面向开发者、哪些是可替换的，以及哪些是无需触碰的内部实现细节。
系统层
下图展示了四个主要层及其关系。 ConvaiRuntime 在第二层直接包含四个子系统—— IRoomRuntime, IEventHub, IAgentRegistry，以及模块列表。角色和玩家显示在 IRoomRuntime 是位于 IAgentRegistry，且所有模块共享一个公共上下文层。
ConvaiRuntime （顶层） ——拥有所有子系统并协调完整生命周期。通过 ConvaiRuntimeBuilder在整个应用生命周期内仅创建一次。暴露 start、pause、resume 和 stop 操作，并将其传播到所有已注册模块。它持有四个直接子系统：
IRoomRuntime——管理实时会话：连接、断开、音频路由、角色归属和诊断。角色和本地玩家显示在此层之下。IEventHub——SDK 中用于跨系统通信的解耦发布/订阅总线。IAgentRegistry——所有活动ConvaiCharacter是位于ConvaiPlayer实例的注册表。IReadOnlyList<IConvaiModule>——已注册功能模块的集合。
角色 / 玩家层 — ConvaiCharacter 是位于 ConvaiPlayer 向 IAgentRegistry 注册，并通过 IRoomRuntime接收各自的会话上下文。每个角色维护自己的会话状态。
模块上下文层 ——功能模块（IConvaiModule）共享一个 IModuleContext ，它提供对运行时服务的访问。模块彼此隔离：它们不会直接相互调用。
运行时接口清单
IConvaiRuntime 通过属性暴露以下子系统。每个属性都是特定功能领域的入口点。
State
RuntimeState
运行时当前生命周期状态
Room
IRoomRuntime
连接、音频、归属和诊断
事件
IEventHub
解耦的发布/订阅通信
Agents
IAgentRegistry
所有活动角色和玩家的注册表
Modules
IReadOnlyList<IConvaiModule>
所有已注册的功能模块
Transport
ITransportProvider
平台特定的实时传输
Conversation
IConversationProvider
AI 后端通信
Config
ConvaiBootstrapConfigSnapshot
不可变的引导配置
RuntimePreferences
IRuntimePreferences
可变的运行时偏好设置
FeatureVariants
IFeatureVariantProvider
功能变体 / A/B 选择
Persistence
IPersistenceProvider
运行时拥有的数据存储
Telemetry
ITelemetryProvider
可观测性和分析
开发者最常与 Room, Agents，以及 事件 交互。 Transport, Conversation, Persistence, Telemetry，以及 FeatureVariants 可通过 ConvaiRuntimeBuilder.
你可以替换的内容
ConvaiRuntimeBuilder 在运行时启动前用于组合运行时的流式 API。每个方法都会返回 this，因此调用可以链式连接。
下表列出了哪些内容可替换，哪些仅限内部使用。
传输提供程序
UseTransport()
平台默认（WebSocket / LiveKit）
对话提供程序
UseConversation()
Convai RTVI 对话后端
持久化提供程序
UsePersistence()
PlayerPrefs-支持的键值存储
遥测提供程序
UseTelemetry()
无操作遥测
功能变体提供程序
WithFeatureVariants()
静态功能标志
运行时偏好设置
WithRuntimePreferences()
默认值来自 ConvaiSettings
事件总线
UseEventHub()
默认的内存事件总线
代理注册表
UseAgentRegistry()
默认注册表
终端用户身份
WithEndUserIdentityProvider()
设备 ID 提供程序
最终用户元数据
WithEndUserMetadataProvider()
无
Modules
AddModule() / AddModule<T>()
仅限 SDK 功能模块
房间运行时
UseRoomRuntime()
内部的、由 LiveKit 支持的房间
ConvaiRuntime 由 ConvaiManager MonoBehaviour 自动创建。大多数项目从不直接调用 ConvaiRuntimeBuilder 。仅在需要替换默认提供程序或添加自定义模块时使用它。
IRoomRuntime 子结构
IRoomRuntime 子结构房间层本身由四个协调器组成，均可通过 IConvaiRuntime.Room.
连接
IRoomConnectionCoordinator
连接、断开、会话状态
音频
IRoomAudioCoordinator
麦克风采集、远程音频播放
归属
IRoomOwnershipCoordinator
此客户端拥有并聚焦的角色
诊断
IRoomDiagnostics
会话指标、健康监控
连接和音频是最可能在脚本中调用的协调器。当场景中有多个角色时，归属会自动管理。诊断用于性能监控和调试。
模块层
模块是运行在运行时生命周期内的功能扩展。它们接收共享的 IModuleContext ，并可以注册供其他模块或表现层使用的服务。
在调用 Build() 之前通过构建器添加模块：
模块会随着运行时一起启动、暂停、恢复和停止。 IConvaiModule 接口定义了这些生命周期钩子。完整的模块编写参考请参见 扩展 SDK 。
模块不能直接相互依赖。如果两个模块需要共享数据，请使用 IEventHub ，或者使用通过 IModuleContext.
RuntimeState 生命周期
RuntimeState 生命周期运行时从创建到释放会经历以下状态。
已创建
运行时已构建但尚未启动
启动中
StartAsync() 正在进行
运行中
完全运行
暂停中
PauseAsync() 正在进行
已暂停；可恢复
已暂停；可恢复
恢复中
ResumeAsync() 正在进行
停止中
StopAsync() 正在进行
已停止
已关闭；无法重新启动
已释放
DisposeAsync() 已调用；所有资源已释放
所有状态转换都是封装在 IConvaiOperation<Unit>中的异步操作。在返回的操作上检查， Status 以确认转换完成后再继续。
ConvaiManager 在销毁时自动处理。若你使用 DisposeAsync() 直接构建自定义宿主，请调用 ConvaiRuntimeBuilder 以释放所有资源。 DisposeAsync() 在 StopAsync() 来
下一步
你现在已经了解 Convai 运行时的组成方式，以及各层中哪些部分可替换。接下来阅读《会话生命周期》，了解每个角色的会话如何创建、持久化和恢复，然后继续阅读《轮流发言模式》和《事件系统》。
最后更新于
这有帮助吗？