TopStepAIKit

TopStepAIKit 是独立于 TopStepComKit 的 AI 业务 SDK。它通过统一的 Contract 和 Context 屏蔽具体 AI Provider，并通过设备平台提供的 DeviceBridge 使用手表、耳机或眼镜的麦克风与 AI 能力。

架构

App
 └─ TSAIKit
     └─ activeContext（当前仅允许一个）
         ├─ assistant        文本总结、AI 语音对话
         ├─ questionAnswer   单次 AI 问答
         ├─ translate        文本翻译
         ├─ speech           TTS、PCM/文件/设备麦克风 ASR
         ├─ interpreter      同声传译
         ├─ audioRecord      普通录音、AI 录音
         ├─ imageGeneration  图片生成
         └─ audioRouting     音频路由发现与监听

业务代码只访问 TSAIKit.sharedInstance.activeContext 暴露的能力对象，不直接创建 Provider、Adapter 或 DeviceBridge。

系统要求

iOS 13.0+
CocoaPods
一个 AI Provider 产品包；当前正式实现为 AIBuds
至少一个设备平台 AI Bridge：Fit、NewPlatform 或 Persimwear
对应平台设备 SDK 已完成初始化与连接

安装

target 'YourApp' do
  pod 'TopStepAIKit/Providers/AIBuds'

  # 按实际设备平台选择一个；也可以同时集成多个平台
  pod 'TopStepFitKit/AI'
  # pod 'TopStepNewPlatformKit/AI'
  # pod 'TopStepPersimwearKit/AI'

  # 仅在需要 AIBuds LiveStream 时安装，其中包含 FFmpeg
  # pod 'TopStepAIKit/Providers/AIBudsLiveStream'
end

TopStepAIKit/AIBuds 和 TopStepAIKit/AIBudsLiveStream 是兼容旧工程的别名，新工程应使用 Providers/* 路径。

静态 Framework 工程

如果工程使用 use_frameworks! :linkage => :static，AIBuds 运行时依赖的 AFNetworking 和 SocketRocket 仍需保持动态 Framework。不要同时安装其他携带 libav*.xcframework 的视频 SDK 与 AIBudsLiveStream。

初始化 Context

设备平台应先完成初始化和连接，使平台 AI Bridge 完成注册，然后激活 AI Context：

#import <TopStepAIKit/TopStepAIKit.h>

TSAIBudsConfiguration *providerConfig =
    [TSAIBudsConfiguration configurationWithPreferredVendor:TSAIBudsVendorTypeStarBurst];

TSAIContextConfiguration *contextConfig =
    [TSAIContextConfiguration configurationWithPlatformIdentifier:TSAIPlatformIdentifierFit
                                                      providerType:TSAIProviderTypeAIBuds
                                             providerConfiguration:providerConfig];

[[TSAIKit sharedInstance] activateContextWithConfiguration:contextConfig
                                                completion:^(BOOL success, NSError *error) {
    if (!success) {
        TSLog(@"AI Context 激活失败: %@", error.localizedDescription);
        return;
    }

    TSAIContext *context = [TSAIKit sharedInstance].activeContext;
    TSLog(@"AI Context 已激活: %@", context.contextIdentifier);
}];

TSAIContextConfiguration

属性	类型	说明
`platformIdentifier`	`NSString *`	DeviceBridge 平台标识，使用 SDK 提供的常量
`providerType`	`TSAIProviderType`	AI Provider 产品类型
`providerConfiguration`	`id`	Provider 专属配置；AIBuds 使用 `TSAIBudsConfiguration`

TSAIContext 还提供只读的 contextIdentifier、platformIdentifier、state、authorizationState，七个业务能力对象，以及只读的 audioRouting 路由发现接口。Context 同时实现精确启动资格和设备协同会话协议。TSAIBudsConfiguration 包含 preferredVendor、appId、appKey 和 vendorOptions；敏感字段应由宿主 App 在运行时注入。

Provider 与 AIBuds 厂商

枚举	枚举值与数值
`TSAIProviderType`	`Unknown = 0`、`AIBuds = 1`、`AliAI = 2`
`TSAIBudsVendorType`	`None = 0`、`StarBurst = 1 << 0`、`MltCloud = 1 << 1`、`All = StarBurst \| MltCloud`

每个 Context 的 preferredVendor 必须只选择一个实际厂商；All 仅供 SDK Runtime 注册使用。

平台标识

常量	平台
`TSAIPlatformIdentifierFit`	TopStepFitKit
`TSAIPlatformIdentifierNewPlatform`	TopStepNewPlatformKit
`TSAIPlatformIdentifierPersimwear`	TopStepPersimwearKit

Context 状态

枚举值	说明
`TSAIContextStateInactive`	未激活
`TSAIContextStateActivating`	激活中
`TSAIContextStateActive`	已激活，可调用能力接口
`TSAIContextStateDeactivating`	停用中
`TSAIContextStateFailed`	激活失败

可通过 registerStateDidChange: 和 registerAuthorizationStateDidChange: 监听 Context 与 Provider 鉴权状态。

`TSAIAuthorizationState`	数值	说明
`TSAIAuthorizationStateUnknown`	0	尚无明确鉴权状态
`TSAIAuthorizationStateDisconnected`	1	Provider 未连接
`TSAIAuthorizationStateAuthenticating`	2	鉴权中
`TSAIAuthorizationStateAuthenticated`	3	鉴权完成
`TSAIAuthorizationStateFailed`	4	鉴权失败

停用与切换

[[TSAIKit sharedInstance] deactivateActiveContextWithCompletion:^(BOOL success, NSError *error) {
    if (!success) {
        TSLog(@"AI Context 停用失败: %@", error.localizedDescription);
    }
}];

切换设备平台时，应先完成设备 SDK 切换，再激活新 Context。激活新 Context 后，旧 Context 及此前保存的能力对象均失效，继续调用会返回 TSAIErrorCodeContextInactive。

下一步

能力与启动资格 — 区分兼容性发现与真实启动授权
音频路由 — 查询并配置 AI 会话的输入输出通道
AI 助手 — 文本总结与 AI 语音对话
AI 语音 — TTS 与多种 ASR 输入
公共类型与错误处理 — 语言、音频格式和错误码

注意事项

当前进程只允许一个 activeContext，不支持多个 Context 并发。
能力对象必须在 Context 激活成功后从 activeContext 获取，不要长期缓存跨越平台切换。
providerConfiguration 中的 App Key、Token 等敏感信息不得写入日志。
不要直接调用 AIBuds 的全局初始化、厂商切换或鉴权类方法；这些流程由 TopStepAIKit 串行管理。

架构​

系统要求​

安装​

初始化 Context​

TSAIContextConfiguration​

Provider 与 AIBuds 厂商​

平台标识​

Context 状态​

停用与切换​

下一步​

注意事项​

架构