最佳实践

AIBuds 功能涵盖蓝牙指令、设备 Wi-Fi 热点流程、AI 服务、媒体处理和可选诊断模块。可靠的集成应明确这些边界，而不是把每次 SDK 调用都视为孤立请求。

明确模块边界

• AIBudsFoundation 包含共享模型、能力和值类型。
• AIBuds 负责设备发现、连接以及面向设备的功能协议。
• AI 模块负责 AI 服务商配置和 AI 会话生命周期。
• Logging、AI 服务分析仪表盘、Live Streaming、App 闪退收集器 和 视频防抖处理 是可选的运维或媒体模块。
• 产品明确采用完整套件时适合使用 AIBudsAllInOne；模块化产品应只集成实际使用的组件。

将产品策略放在 SDK 层之外。UI Controller 应由协调对象执行工作，该对象在流程结束前持有活动设备、回调、播放器、导入器或 AI 会话。

建立唯一的 SDK 持有者

在 App 生命周期内只初始化一次所选模块，并集中管理配置、Delegate、AI 服务商选择和可选插件注册。以配置页面为统一初始化入口，避免各功能页面形成不同的初始化方式。

检查就绪状态与能力

已连接的设备不一定实现所有功能。执行操作前：

1. 确认目标设备仍处于活动和就绪状态。
2. 检查设备是否符合对应功能协议，例如 DeviceInfoAPI 或 LiveStreamingAPI。
3. 如果功能提供能力属性，请检查该属性。
4. 直接显示不可用状态，不要依靠指令失败来探测能力。

设备重新连接或切换后应重新检查这些条件。不要把设备能力缓存为账号级产品配置。

区分请求已启动与流程已完成

许多回调只表示较大流程中的一个阶段。启动 OTA、进入设备模式、收到 RTSP 地址和完成媒体下载是不同的里程碑。

TEXT

idle -> preparing -> active/progress -> finishing -> completed | failed | cancelled

只有文档明确标注的最终回调才能确定流程结果。启动回调成功、进度达到 100% 或取得中间 URL，都不代表整个流程已经成功。OTA、Camera OTA、Media File Import、Live Streaming、AI 录音、同声传译以及需要明确启停的功能尤其需要注意这一点。

保证清理操作幂等

为每个长时间运行的流程指定唯一持有者和唯一清理路径，并确保在成功、失败、取消、离开页面、断开连接或进入后台后都能安全执行。清理通常包括：

• 在支持时停止面向设备的会话；
• 停止并释放本地播放器、推流器、录音器或处理器；
• 取消订阅并移除观察者；
• 使尚未执行的 UI 工作失效；
• 清理回调和临时文件；
• 根据最终结果恢复 UI。

不要把视图消失等同于中间件或设备任务已经停止。

不要假定回调队列

除非 API 明确保证回调队列，否则应将 UIKit 更新派发到主队列，并把解码、文件 I/O、解析等耗时操作移出主队列。切勿在 SDK 回调中同步等待另一个 SDK 回调。

为网络切换设计

Media File Import、Camera OTA 和 RTSP Live Streaming 可能连接设备热点。iPhone 的互联网路由可能改变，热点丢失也与蓝牙状态相互独立。请显示当前阶段、保留第一个可处理错误，并且只从文档明确的安全边界重新开始。

谨慎处理敏感数据

AI 转写、录音、翻译、报告、日志、崩溃报告、媒体和 Dashboard 页面都可能包含用户数据。

• 定义数据保留和删除策略。
• 将诊断工具限制在指定构建和网络中。
• 从日志中移除凭据和标识符。
• 只请求已启用功能所需的权限。
• 在产品隐私设计中明确说明上传和外部 AI 处理。
• 不要意外地将 SDK 临时输出保存为长期数据。

保存最终输出和回退结果

流程同时产生原始输出和处理后输出时，应保留原始文件直到衍生结果验证完成。例如，视频防抖处理失败并不一定使已下载的源文件失效。

应以公开结果模型和最终回调判断状态。Demo 标签、推测的状态码和 UI 进度只用于展示，不能替代 SDK 公开契约。

集成检查清单

• 初始化和可选插件注册由一个对象统一负责。
• 每项功能都检查设备就绪状态、协议支持情况和具体能力。
• 中间回调与最终结果保持区分。
• UIKit 修改在主队列执行。
• 长时间运行的流程具有幂等清理。
• UX 能反映热点和互联网路由变化。
• 可选处理失败后仍保留原始媒体。
• 诊断数据遵守产品隐私策略。
• 真机测试覆盖中断、断开连接、重试和离开页面。
• 每次 SDK 更新后重新检查 API Reference 和功能指南。