架构

AIBuds SDK iOS 由一系列模块化组件构成，每个组件都有明确的责任边界。理解这些模块如何协同工作，有助于您按需安装并用自定义插件扩展 SDK。

架构总览

SDK 按层次组织 —— 上层依赖下层，设备侧（左）与 AI 侧（右）在大多数层级镜像对称。

系统架构图

AIBuds SDK iOS 架构图

您的 App

您的用于连接 AIBuds 设备的 iOS 应用

AIBudsAllInOne可选

便捷封装

功能模块

Audio · VoiceAssistant · LiveStream · CrashReporter · AIBudsAIDashboard

AIBudsSDK

设备通信核心 SDK

AIBudsAISDK

AI 功能核心 SDK

ABMateSDK(BLE)

设备蓝牙通信核心协议层

StarBurst / MagicHelper

第三方 AI 服务封装层

星芒 AI (字节跳动)
骆方案 AI (美乐创)

AIBudsFoundation

设备通信基础数据模型以及数据类型定义

AIBudsAIFoundation

AI 功能基础数据模型以及数据类型定义

AIBudsLog

全局日志模块

AIBudsXLFacility可选

可选日志插件

理解 AIBuds SDK iOS 的架构

自上而下依次为：您的应用 → 便捷封装 → 功能模块 → 核心 SDK（设备侧 + AI 侧）→ 协议插件 → 基础数据模型 → 贯穿全局的日志。

设备模型

SDK 接触的每台设备都由一个协议表示 —— DeviceConvertible（Objective-C 中为 AIBudsDeviceConvertible）。它是您的 App 读取设备身份与状态、执行生命周期操作（connect、disconnect、unpair、save）的唯一句柄。操作直接在设备实例上调用，而非通过 Manager 单例。DeviceConvertible 遵循 NSSecureCoding，可跨 App 启动归档与恢复。

另一个协议 FoundDeviceConvertible（AIBudsFoundDeviceConvertible）描述的是刚通过扫描发现的设备 —— 它包裹了 Core Bluetooth 三元组（central + peripheral + advertisementData + RSSI），但尚不可持久化。通过 AIBudsSDK.makeStorableDeviceFromDiscovered(_:) 转换为可持久化的 DeviceConvertible。

设备生命周期

从设备扫描到就绪的整个生命周期

扫描扫描发现设备

附近

被发现

扫描到一个正在广播的设备

AIBudsSDK.makeStorableDeviceFromDiscovered(_:)将扫描到的设备转换为可持久化的设备模型

本地

可存储

将设备持久化到本地存储

StoredDevicesMgr.addDevice

已保存

已持久化

将设备保存到本地存储

device.connect(ConnectParams)

进行中

连接中

进行设备连接

deviceDidReady回调设备就绪

在线

已就绪

设备现在可以接收指令了

已就绪设备已连接并就绪

设备依次经历五个状态：扫描发现 → 转换为可存储设备 → 持久化到存储 → 连接中 → 已连接并就绪。

StoredDevicesMgr（AIBudsStoredDevicesMgr）负责管理已持久化的设备列表 —— addDevice、removeDevice、allDevices、findDevice(byMacAddr:)、findDevice(byPeripheral:)。在 App 启动时调用 loadDevicesInBackground 可恢复之前保存的设备（包括自动重连候选设备）。

能力协议

并非每台设备都支持所有功能，因此能力被建模为独立协议，而非一个庞大的设备接口。它们都遵循公共标记协议 DeviceAPI（AIBudsDeviceAPI）：

协议	能力
`DeviceInfoAPI`	电量、设备能力、硬件配置、语言、存储、媒体数量以及同步/设置时间
`DeviceCommonAPI`	恢复出厂设置、关机
`DeviceFindAPI`	查找设备、停止查找
`DeviceWorkModeAPI` / `DeviceWorkStateAPI`	工作模式、工作状态
`DeviceVolumeControlAPI`	获取、设置音量
`DeviceEqualizerAPI`	均衡器设置
`DeviceANCAPI`	ANC 模式、增益、通透和渐变
`DeviceWearDetectionAPI`	佩戴检测能力与状态
`DeviceTWSAPI`	TWS 连接状态
`DeviceMusicControlAPI`	播放、暂停、上一首、下一首和音量
`DeviceAudioRecordingAPI`	普通录音、AI 录音和最大录制时长
`DeviceCameraAPI`	拍照、录像和相机固件
`DeviceRemoteShutterAPI`	遥控快门同步
`DeviceFileImportAPI`	获取、导入和删除媒体文件
`DeviceOtaAPI` / `DeviceCameraOtaAPI`	固件更新
`DeviceAppsAPI`	启动、停止设备应用
`DeviceServiceAuthAPI`	重试服务鉴权和上报结果
`DevicePhysicalOperationsAPI`	按键与触控操作映射
`LiveStreamingAPI`	RTSP / JPEG 直播
`OnDeviceVoiceAssistantAPI`	离线语音助手

调用某个能力时，将设备转换为对应协议并检查是否遵循 —— 缺少硬件的设备会直接转换失败：

Swift
Objective-C

if let info = device as? DeviceInfoAPI {
    info.setDeviceTime(Date()) { success, statusCode, error in
        // ...
    }
}

if let anc = device as? DeviceANCAPI {
    anc.setAncMode(.ancOn) { _ in }
}

if ([device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)device;
    [info setDeviceTime:[NSDate date]
             completion:^(BOOL success, NSNumber *statusCode, NSError *error){
                 // ...
             }];
}

代理

SDK 有两层代理 —— 按您需要的事件范围选择合适的一层。

DeviceDelegate（AIBudsDeviceDelegate）—— 设备级。通过 device.delegate = self 设置，接收该特定设备的连接生命周期事件（didStartConnectingDevice、didConnectedToDevice、didFailToConnectDevice、device:didDisconnectWithError:、deviceDidReady）以及状态变更事件（电量、工作模式、ANC、EQ、佩戴状态、TWS、音量、存储、媒体数量等）。所有方法均为 @objc optional —— 只实现您需要的回调即可。
SDKDelegate（AIBudsSDKDelegate）—— 全局。在 AIBudsSDK.initialize(...delegate:) 时传入，跨所有设备镜像连接事件，并上报扫描状态（onScanningStatusChanged:）。

常见做法是用 SDKDelegate 处理 App 级关注点（扫描、全局连接 UI），用 DeviceDelegate 处理特定设备所在页面。

核心单例

单例	作用域	主要入口
`AIBudsSDK`	设备侧	`initialize(bleSDKs:configuration:delegate:)`、`startScanning`、`stopScanning`、`isScanning()`、`makeStorableDeviceFromDiscovered(_:)`、AI/语音插件设置方法
`AIBudsAISDK`	AI 侧	`initialize(aiSDKs:)`、`setAIServiceVendor(_:)`、`startAIChat`、`startAIAudioRecording`、`startSimultaneousInterpretation`、`translateText`、`summary`、`recognizeVoice`、`synthesizeText`

设备操作（连接、断开、发送命令）不在这些单例上 —— 它们直接在 DeviceConvertible 实例上调用。

AI 服务商

AI 能力由可插拔的服务商 SDK 提供。当前 AI 服务商由 AIServiceVendor（AIBudsAIServiceVendor）枚举表示：

枚举值	AI 服务商
`.none`	未选择服务商
`.starBurst`	星芒 AI（字节跳动）
`.mltcloud`	骆方案 AI（美乐创）

枚举 case 的大小写严格遵循公开 Swift API：.starBurst 中的 B 为大写，.mltcloud 则全部小写。

运行期间可通过 AIBudsAISDK.setAIServiceVendor(_:) 切换 AI 服务商。请在调用任何 AI 服务之前完成选择。

连接参数

ConnectParams（AIBudsConnectParams）包含 device.connect(_:) 所需的参数，其中 AI 鉴权参数用于让 SDK 在连接握手期间完成 AI 服务商鉴权：

userId —— AI 服务商用于识别终端用户的 ID。
aiAuthParams（AIAuthParams / AIBudsAIAuthParams）—— 保存各 AI 服务商所需的鉴权参数：
- starburst（StarBurstAIAuthParams）：productId，可选 ppeEnv
- mltcloud（MltCloudAIAuthParams）：channelId

Swift
Objective-C

let params = ConnectParams()
let auth = AIAuthParams()

let starBurst = StarBurstAIAuthParams()
starBurst.productId = configs["STARBURST_PRODUCTID"]
auth.starburst = starBurst

let mltCloud = MltCloudAIAuthParams()
mltCloud.channelId = configs["MLTCLOUD_CHANNELID"]
auth.mltcloud = mltCloud

params.aiAuthParams = auth
params.userId = "199"

device.connect(params)

AIBudsConnectParams *params = [AIBudsConnectParams new];
AIBudsAIAuthParams *auth = [AIBudsAIAuthParams new];

AIBudsStarBurstAIAuthParams *starBurst = [AIBudsStarBurstAIAuthParams new];
starBurst.productId = configs[@"STARBURST_PRODUCTID"];
auth.starburst = starBurst;

AIBudsMltCloudAIAuthParams *mltCloud = [AIBudsMltCloudAIAuthParams new];
mltCloud.channelId = configs[@"MLTCLOUD_CHANNELID"];
auth.mltcloud = mltCloud;

params.aiAuthParams = auth;
params.userId = @"199";

[device connectWithParams:params];

模块参考

基础层

AIBudsLog

贯穿整个 AIBuds SDK 的日志核心模块。所有其他模块都通过它记录日志。LogService 是所有日志功能实现所遵循的协议，因此如果您不想使用默认的日志服务，可以自定义实现自己的 LogService。

默认日志服务已支持四种输出目标 —— console、oslogger、file 和 xlfacility（后者需要额外的插件）。

AIBudsXLFacility

可选的日志插件，通过 XLFacility 路由日志输出。与普通文件输出相比，XLFacility 让日志的导出、查询和过期清理更便捷 —— 这是生产环境推荐的日志输出目标。

AIBudsFoundation

与设备通信相关的数据模型、类型定义和辅助数据结构。可以理解为设备 SDK 与您的 App 共同依赖的"共享词汇表"。

AIBudsAIFoundation

与 AIBudsFoundation 类似，但专注于 AI 业务，定义各 AI 服务商共用的基础数据模型和类型。

核心 SDK 层

AIBudsSDK

设备通信核心 SDK。大部分设备相关功能 —— 扫描、连接、发送命令、接收事件 —— 都通过此模块调用。

ABMateSDK

AIBudsSDK 当前使用的 BLE 通信协议插件。由于协议以插件方式加载，您在需要 BLE 通信时安装 ABMateSDK。未来若支持其他协议，您可以选择与设备匹配的协议插件加载。

AIBudsAISDK

AI 功能的核心 SDK。它通过插件系统接入多个 AI 服务商，并将调用转发给当前选择的服务商实现。

AI 服务商插件

AIBudsStarBurst

**星芒 AI（字节跳动）**的中间件插件，通过 AIBudsAISDK 提供对应 AI 能力。

AIBudsMagicHelper

**骆方案 AI（美乐创）**的中间件插件，通过 AIBudsAISDK 提供对应 AI 能力。

功能模块

AIBudsAudio

音频相关功能：录音、播放与语音活动检测（VAD）。

AIBudsVoiceAssistant

离线语音鉴权插件。为设备上的唤醒词和语音命令识别提供鉴权协调。需要服务商授权时，由该中间件完成协调。

AIBudsLiveStream

设备直播 SDK。从设备拉取 RTSP 流，提供对应的视频播放器，并将流推送到 RTMP 端点进行广播。

AIBudsCrashReporter

崩溃日志采集 SDK。捕获 App 崩溃，保存到本地目录，并通过回调返回崩溃文件路径，方便您的 App 上传至服务器或自行处理。

AIBudsAIDashboard

AI 服务诊断面板。可通过局域网访问，让您检查 AI 相关记录 —— AI 录音、同声传译会话、AI 对话等。每条记录都可查看关联的设备信息、启动参数、传输中的音频数据、会话事件和关键错误，便于分析异常。

便捷封装

AIBudsAllInOne

由于模块化架构使 SDK 初始化配置较为繁琐，AIBudsAllInOne 打包了一套合理的默认配置，让您一次调用即可完成初始化 —— 适合不需要自定义安装的场景。

插件模型

SDK 通过四类插件扩展能力。每类插件都有明确协议，因此可以开发自定义 BLE 协议插件或自有 AI 服务插件，与内置实现并存或替换内置实现：

插件类型	协议	加载方式	示例
BLE 协议	`BleConnectSDK`	`AIBudsSDK.initialize(bleSDKs:...)`	`ABMateSDK`
AI 服务商	`AIConnectSDK`	`AIBudsAISDK.initialize(aiSDKs:...)`	`StarBurstSDK`、`MagicHelperSDK`
AI / 语音桥接	`StarBurstBridgePlugin`、`MltCloudBridgePlugin`、`OnDeviceVoiceAssistantBridgePlugin`	`AIBudsSDK.setStarBurstAIPlugin(...)` / `setMltCloudAIPlugin(...)` / `setOnDeviceVoiceAssistantPlugin(...)`	宿主实现的鉴权插件
日志后端	`LogService`	`AIBudsLogSDK.setXLFacilityPlugin(...)`	`AIBudsXLFacility`

架构总览​

AIBuds SDK iOS 架构图

设备模型​

设备生命周期​

被发现

可存储

已持久化

连接中

已就绪

能力协议​

代理​

核心单例​

AI 服务商​

连接参数​

模块参考​

基础层​

AIBudsLog​

AIBudsXLFacility​

AIBudsFoundation​

AIBudsAIFoundation​

核心 SDK 层​

AIBudsSDK​

ABMateSDK​

AIBudsAISDK​

AI 服务商插件​

AIBudsStarBurst​

AIBudsMagicHelper​

功能模块​

AIBudsAudio​

AIBudsVoiceAssistant​

AIBudsLiveStream​

AIBudsCrashReporter​

AIBudsAIDashboard​

便捷封装​

AIBudsAllInOne​

插件模型​

架构总览

设备模型

设备生命周期

能力协议

代理

核心单例

AI 服务商

连接参数

模块参考

基础层

AIBudsLog

AIBudsXLFacility

AIBudsFoundation

AIBudsAIFoundation

核心 SDK 层

AIBudsSDK

ABMateSDK

AIBudsAISDK

AI 服务商插件

AIBudsStarBurst

AIBudsMagicHelper

功能模块

AIBudsAudio

AIBudsVoiceAssistant

AIBudsLiveStream

AIBudsCrashReporter

AIBudsAIDashboard

便捷封装

AIBudsAllInOne

插件模型