运行时模块系统

了解 Convai 运行时模块系统，包括何时使用自定义模块、模块生命周期状态，以及哪些 SDK 扩展点是安全可用的。

Convai Unity SDK 基于一个模块系统构建，该系统为可选功能——口型同步、情绪、视觉、叙事设计——在运行时生命周期中提供了明确的位置。你可以使用同一系统添加自己的模块：它们会接收相同的启动序列，访问相同的服务，并且可以与其他模块共享接口。

你需要自定义模块吗？

当你需要以下行为时，自定义模块是合适的工具：

• 参与 SDK 运行时生命周期 ——与 SDK 一起启动和停止，而不是独立运行
• 与其他 SDK 模块共享服务 ——例如，提供一个 IAudioAnalysisService ，由情绪模块或你自己的代码使用
• 响应 SDK 域事件 ——角色语音状态、情绪变化、动作触发
• 集成硬件或平台系统 ——触觉设备、生物识别传感器、计分引擎

以下情况不需要自定义模块：

• 在 MonoBehaviour 中响应 SDK 事件——直接通过 context.Events 从一个 IInjectable 组件中订阅，或者使用 ConvaiCharacter
• 对角色的简单自定义行为——向角色的 GameObject 添加一个 MonoBehaviour
• 从你自己的脚本调用 Convai REST API——使用 ConvaiManager.ActiveManager 直接

如果不确定，先从 MonoBehaviour 开始，仅在需要生命周期集成时再升级到 IConvaiModule 。

什么是模块

模块是一个实现了 IConvaiModule的类。它：

• 具有一个稳定的 ModuleId 字符串（按约定是唯一、小写、以连字符分隔——例如， "my-company.haptic-feedback").
• 通过 RequiredModules 声明对其他模块的依赖，并通过 RequiredServices.
• 声明对运行时服务的依赖 参与运行时生命周期：.
• 可通过 IModuleContext.ProvideModuleService<T>().

向其他模块暴露类型化服务。模块系统会自动处理启动顺序——模块会按照依赖顺序启动，并按相反顺序停止。

模块生命周期

生命周期包含五种状态。 RegisterAsync 会在任何 StartAsync 调用之前对所有模块运行，使每个模块在任何模块开始主动处理之前都有一个保证的时间窗口来注册服务。

有关完整的生命周期方法契约和实现示例，请参见 实现自定义模块.

安全扩展点和内部 API

仅使用下面列出的公共扩展点。内部类型和平台特定层可能会在不通知的情况下更改。

安全扩展点

内容	方式
自定义模块行为	实现 IConvaiModule 并通过 RegisterModule() 或 AddModule()
模块间服务	ProvideModuleService<T>() / TryGetModuleService<T>()
自定义凭据	重写 CreateRuntimeBuilder() 并调用 builder.UseConfig()
自定义身份	SetEndUserIdentityProvider() / SetEndUserMetadataProvider()，或构建器
自定义持久化	重写 CreateRuntimeBuilder() 并调用 builder.UsePersistence()
角色级组件集成	实现 IInjectable<IConvaiCharacterDependencies> 在角色层级中的 MonoBehaviour 上
事件订阅	IEventHub.Subscribe<T>() / Unsubscribe<T>()
日志路由	ConvaiLogger.RegisterSink(ILogSink)

内部 API——不要覆盖

区域	原因
ConvaiRuntime 内部	按设计为私有；可能在不通知的情况下更改
传输层（ITransportProvider 实现）	特定于平台；覆盖会破坏平台支持
RTVI 协议处理器（RTVIHandler)	序列化格式与 Convai 的后端绑定——任何覆盖都会导致协议不同步
ConvaiRoomManager 内部	房间协调器内部不是扩展点
超出 RequiredModules	拓扑排序是自动的；不要依赖注册顺序

不要通过反射访问内部类型，也不要绕过构建器注入依赖。SDK 内部会在不同版本之间变化——绕过公共 API 的代码在升级时会无预警地失效。

下一步

实现自定义模块事件系统