常见问题排除手册 & QA (iOS v1.5.0-SNAPSHOT)
常见问题排除手册 & QA (iOS v1.5.0-SNAPSHOT)
本文档持续补充中。分为两部分：① 常见问题排除手册（现象 → 排查 → 处理）；② 常见问题 QA（问 → 答）。
一、常见问题排除手册
1. WebSocket 连接立即被服务端关闭
- 现象：
AgentSdk.create(...)之后连接建立瞬间断开，无法收到任何回调。 - 可能原因：沿用了旧网关或旧的三参
create(url:appId:appSecret:)（缺appKey）。 - 处理：网关切到
wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk；调用改为AgentSdk.create(url:appId:appKey:appSecret:)。
2. 鉴权失败 / 握手 401 或 403
- 现象：WebSocket 握手阶段返回 401 / 403，或签名不通过。
- 可能原因：
appId/appKey/appSecret不属于同一应用；本机时钟偏差过大；代理没透传 v1.4.0 的 5 个鉴权头（X-App-Id/X-App-Key/X-Timestamp/X-Nonce/X-Signature）。 - 处理：重新申领凭证、对齐时钟、修复代理头的透传。
3. X-Callback-Types 请求头无效导致回调不下发
- 现象：握手成功，但订阅的被动回调（如
Audio2Llm）没触发。 - 可能原因：
X-Callback-Types头缺失或格式非法（需 JSON 数组字符串，如["audio2Llm"]）。 - 处理：抓包确认头存在且格式合法；回调类型枚举以 枚举参考 为准。
4. AgentSdk.registerXxx(...) 找不到符号
- 现象：编译报错找不到
registerStateListen/registerPushListen/querySkill/queryState/registerPullStream等。 - 处理：状态监听改由所有
PassiveCallback子类共享的onState(...)接收；主动交互仅保留任务流registerTaskFlow/unregisterTaskFlow。详见 CHANGELOG 与 主动交互指南。
更多错误码与重连策略请参考 错误处理。
二、常见问题 QA
Q1. v1.4.0/1.5.0 能否与旧版本的凭证/网关兼容？
A：不能。v1.4.0 起已切到灵心开放平台「应用」的凭证与 HMAC-SHA256 五元组请求头。iOS SDK 从初版起即采用该鉴权体系，v1.5.0 保持不变。详见 Java v1.4.0 CHANGELOG。
Q2. appId / appKey / appSecret 从哪里获取？
A：登录灵心开放平台，在「应用」页面创建应用后即可获得，三者属于同一组凭证，不要拆分使用。
Q3. 是否需要自己实现 HMAC-SHA256 签名？
A：不需要。AgentSdk.create(url:appId:appKey:appSecret:) 会在内部完成签名与请求头构造。
Q4. 一个 SDK 实例可以订阅多种被动回调类型吗？
A：可以。v1.4.0 把公开被动回调收敛为 8 种（Audio2Llm / Audio2Tts / Asr2Llm / Asr2Tts / AsrVideo2Vlm / AsrVideo2Tts / AudioVideo2Vlm / AudioVideo2Tts），可按需注册多个。类型定义见 枚举参考。
Q5. 为什么交互链路的结果都是流式返回？
A：AgentSDK 的端侧交互链路是全链路流式的——ASR 音频帧流式上行，ASR/LLM/TTS 结果以 onXxxDelta + onXxxDone 增量下发。好处是"边产出边消费"，端到端等待显著降低。
Q6. 二开系列 AgentSDK 与传统 HTTP API 有什么区别？
A：定位不同。传统 API 是"一次连接、一问一答的无状态调用"；AgentSDK 面向机器人端侧的多模态实时交互，是长连接（WebSocket 全双工）+ 全链路时序的模型，支持双向触发、异步应答、一等公民的打断语义。整体线程模型与重连见 架构概述。