AI 助手（TSAIAssistantInterface）

AI 助手包含两类能力：单次流式文本总结，以及由设备麦克风驱动的多轮 AI 语音对话。

前提条件

TSAIContext *context = [TSAIKit sharedInstance].activeContext;
id<TSAIAssistantInterface> assistant = context.assistant;

调用前分别查询 TSAIFeatureAISummary 或 TSAIFeatureAIChat。语音对话还要求设备已连接并支持对应音频场景。

数据模型

文本总结

模型	主要属性	说明
`TSAISummaryPartialResult`	`taskId`、`text`	累积的流式中间文本
`TSAISummaryResult`	`taskId`、`text`、`duration`	最终总结结果

AI 语音对话

模型	主要属性	说明
`TSAIChatConfig`	`audioRouteConfiguration`、`languageHint`、`initialPrompt`、`agentId`、`speakerId`	音频路由、会话语言、角色和提示配置
`TSAIChatConfig`	`enableVoiceOutput`、`allowUserInterrupt`	是否输出语音、是否允许用户打断
`TSAIChatConfig`	`silenceBeforeReplyInterval`、`autoEndSessionTimeout`	VAD 回复等待和会话自动结束时间
`TSAIChatContent`	`contentType`、`roundIndex`、`text`、`isTextFinal`	问题或回答文本及其终态
`TSAIChatContent`	`audioChunk`、`audioFormat`、`isAudioFinal`、`intent`	增量音频、音频格式及业务意图
`TSAIChatIntent`	`type`、`intentId`、`query`、`value`、`valueDictionary`	结构化设备控制或业务意图
`TSAIChatEvent`	`eventType`、`timestamp`	VAD、播放、网络等会话事件
`TSAIChatReport`	`startTime`、`endTime`、`roundCount`、`endReason`	会话最终报告

使用 [TSAIChatConfig defaultConfig] 创建默认配置。

回调类型

回调	说明
`TSAISummaryPartialBlock`	返回累积总结文本，可调用零次或多次
`TSAISummaryCompletionBlock`	总结成功、失败或取消时调用一次
`TSAIChatContentBlock`	高频返回文本、音频或意图内容
`TSAIChatEventBlock`	返回低频会话生命周期事件
`TSAIChatCompletionBlock`	会话结束时返回报告或错误
`TSAIChatStateBlock`	返回面向 App 的会话状态

文本总结

- (NSString *)summarizeText:(NSString *)text
            onPartialResult:(nullable TSAISummaryPartialBlock)onPartialResult
                 completion:(nullable TSAISummaryCompletionBlock)completion;

- (void)cancelSummarizeWithTaskId:(NSString *)taskId;

NSString *taskId = [assistant summarizeText:sourceText
    onPartialResult:^(TSAISummaryPartialResult *partial) {
        TSLog(@"总结中: %@", partial.text);
    }
    completion:^(TSAISummaryResult *result, NSError *error) {
        if (error) {
            TSLog(@"总结失败: %@", error.localizedDescription);
            return;
        }
        TSLog(@"总结完成: %@", result.text);
    }];

// [assistant cancelSummarizeWithTaskId:taskId];

同步返回的 taskId 由客户端生成，会出现在所有中间结果和最终结果中。超过模型上下文长度时返回参数错误，不会自动截断输入。

AI 语音对话

- (NSString *)startChatWithConfig:(TSAIChatConfig *)config
                        onContent:(nullable TSAIChatContentBlock)onContent
                          onEvent:(nullable TSAIChatEventBlock)onEvent
                       completion:(nullable TSAIChatCompletionBlock)completion;

- (void)stopChatWithTaskId:(NSString *)taskId;

TSAIChatConfig *config = [TSAIChatConfig defaultConfig];
config.languageHint = @"zh-CN";
config.enableVoiceOutput = YES;
config.audioRouteConfiguration = [TSAIAudioRouteConfiguration defaultConfiguration];

NSString *chatTaskId = [assistant startChatWithConfig:config
    onContent:^(TSAIChatContent *content) {
        if (content.text.length > 0) {
            TSLog(@"AI 对话内容: %@", content.text);
        }
    }
    onEvent:^(TSAIChatEvent *event) {
        TSLog(@"AI 对话事件: %ld", (long)event.eventType);
    }
    completion:^(TSAIChatReport *report, NSError *error) {
        if (error) {
            TSLog(@"AI 对话结束: %@", error.localizedDescription);
            return;
        }
        TSLog(@"完成 %ld 轮对话", (long)report.roundCount);
    }];

// 用户结束时执行优雅停止，已缓冲音频仍会完成处理
// [assistant stopChatWithTaskId:chatTaskId];

对话内部完成设备 AI 激活、麦克风音频接入以及 ASR → LLM → TTS 管线。会话由 VAD 自动分轮，没有自然结束点，必须主动停止或等待 autoEndSessionTimeout。

设备事件与状态监听

- (void)registerOnAIChatDeviceEvent:(nullable void (^)(TSAIChatDeviceEvent event))deviceEventBlock;
- (void)registerAIChatStateDidChanged:(nullable TSAIChatStateBlock)stateBlock;

[assistant registerOnAIChatDeviceEvent:^(TSAIChatDeviceEvent event) {
    if (event == TSAIChatDeviceEventRequestStart) {
        TSLog(@"设备请求进入 AI 对话");
    }
}];

设备事件只是请求信号，不代表 SDK 会话已自动启动或停止。收到 RequestStart 后调用 startChatWithConfig: 准备会话，但不要立即打开页面；只有 onEvent 收到 TSAIChatEventTypeSessionStarted、确认设备同步成功后才能打开。RequestEnd 对应 stopChatWithTaskId:。

关键枚举

TSAIChatContentType

枚举值	数值	说明
`TSAIChatContentTypeUnknown`	-1	未知内容
`TSAIChatContentTypeQuestion`	1	用户问题文本
`TSAIChatContentTypeAnswer`	2	AI 回答文本
`TSAIChatContentTypeAudioChunk`	3	AI 回答的增量音频
`TSAIChatContentTypeIntent`	4	设备控制或业务意图

TSAIChatEventType

枚举值	数值	说明
`TSAIChatEventTypeUnknown`	-1	未知事件
`TSAIChatEventTypeSessionStarted`	1	会话已启动
`TSAIChatEventTypeUserSpeechStarted`	2	用户开始说话
`TSAIChatEventTypeUserSpeechEnded`	3	用户结束说话
`TSAIChatEventTypeAIPlaybackStarted`	4	AI 语音开始播放
`TSAIChatEventTypeAIPlaybackEnded`	5	AI 语音播放结束
`TSAIChatEventTypeAIPlaybackInterrupted`	6	AI 语音播放被打断
`TSAIChatEventTypeNetworkError`	7	网络异常
`TSAIChatEventTypeBleDisconnected`	8	BLE 设备断连
`TSAIChatEventTypeAutoEnding`	9	会话即将自动结束

设备事件、会话状态与结束原因

枚举	枚举值与数值
`TSAIChatDeviceEvent`	`RequestStart = 0`、`RequestEnd = 1`、`Interrupted = 2`
`TSAIChatState`	`DeviceClosed = 0`、`DeviceOpened = 1`、`Started = 2`、`Ended = 3`、`Interrupted = 255`
`TSAIChatEndReason`	`Unknown = -1`、`UserStop = 1`、`Timeout = 2`、`Cancelled = 3`、`Error = 4`

表格中省略前缀的值应分别加上对应枚举名，例如 TSAIChatStateStarted。

注意事项

completion 是任务结束的权威信号，流式回调不替代终态回调。
stopChatWithTaskId: 是优雅停止；未知或已结束的 taskId 调用无副作用。
页面销毁时注销设备事件和状态监听，避免旧页面继续接收事件。
音频回调频率较高，不要在回调中执行阻塞 I/O。

前提条件​

数据模型​

文本总结​

AI 语音对话​

回调类型​

文本总结​

AI 语音对话​

设备事件与状态监听​

关键枚举​

TSAIChatContentType​

TSAIChatEventType​

设备事件、会话状态与结束原因​

注意事项​

前提条件

数据模型

文本总结

AI 语音对话

回调类型

文本总结

AI 语音对话

设备事件与状态监听

关键枚举

TSAIChatContentType

TSAIChatEventType

设备事件、会话状态与结束原因

注意事项