常见问题排除手册 & QA (Java v1.4.0)

← 返回本语种主页
本文档持续补充中。发现新的踩坑点或高频问题，欢迎在此追加。文档分为两部分：
常见问题排除手册：按「现象 → 排查 → 处理」组织，用于定位并解决具体故障。
常见问题 QA：按「问 → 答」组织，用于回答概念、使用与边界类问题。

一、常见问题排除手册

补充新条目时，请遵循「现象 / 可能原因 / 排查 / 处理」四段式，便于快速定位。

1. WebSocket 连接立即被服务端关闭

现象：AgentSdk.create(...) 之后连接建立瞬间断开，无法收到任何回调。
可能原因：
- 沿用了 v1.3.0 及更早的旧网关 wss://agentsdk.agibot.com/v1/agentsdk，v1.4.0 已经不再受理。
- 沿用了旧的 AgentSdk.create(url, appId, appSecret) 三参重载，缺少 appKey。
排查：确认 url 与 create() 参数是否切到 v1.4.0 版本。
处理：
- 网关切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk。
- 调用改为 AgentSdk.create(url, appId, appKey, appSecret)。
- 完整迁移要点见 CHANGELOG。

2. 鉴权失败 / 握手 401 或 403

现象：WebSocket 握手阶段返回 401 / 403，或日志中出现签名不通过。
可能原因：
- appId / appKey / appSecret 不属于同一应用（例如混用了旧「二开智能体模板」的凭证）。
- 客户端本机时钟与服务端偏差过大，导致 X-Timestamp 校验失败。
- 自定义代理层或网关层没有透传 v1.4.0 的 5 个鉴权头（X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature）。
排查：
- 到灵心开放平台「应用」页面核对凭证是否为同一应用颁发。
- 用 date -u 检查本机 UTC 时间是否与网络时间对齐。
- 抓包确认 5 个 X-* 头都有下发。
处理：重新申领凭证、对齐时钟、修复代理层的头透传。

3. `X-Callback-Types` 请求头无效导致回调不下发

现象：连接握手成功，但订阅的被动回调（如 Audio2Llm）没有触发。
可能原因：
- v1.4.0 把 callbackTypes 从 JWT payload 迁到了独立请求头 X-Callback-Types，需要是 JSON 数组字符串（例如 ["AUDIO_2_LLM"]）。
- 自定义代理层没有透传该请求头。
排查：抓包确认 X-Callback-Types 存在且格式合法。
处理：修正头格式或代理透传逻辑，回调类型枚举以枚举参考为准。

4. `AgentSdk.registerXxx(...)` 找不到符号

现象：编译报错找不到 registerStateListen / registerPushListen / querySkill / queryState / registerPullStream 等方法。
可能原因：这些方法在 v1.4.0 已经移除或收敛。
处理：
- 状态监听改由所有 PassiveCallback 子类共享的 onState(...) 接收，无需单独注册。
- 主动交互仅保留任务流 registerTaskFlow / unregisterTaskFlow。
- 详见 CHANGELOG 与主动交互指南。

更多错误码与重连策略请参考错误处理。

二、常见问题 QA

补充新条目时，请以 Q / A 开头，一段结论 + 必要时给出跳转链接，避免 QA 越写越像指南。

Q1. v1.4.0 能否与 v1.3.0 或更早版本的凭证/网关兼容？

A：不能。v1.4.0 已切到灵心开放平台「应用」的凭证与新的网关地址，鉴权算法也由 JWT 改为 HMAC-SHA256 五元组请求头，无法平滑升级。需要重新申领凭证、切换网关、更新 create() 调用与请求头处理逻辑。完整清单见 CHANGELOG。

Q2. `appId` / `appKey` / `appSecret` 从哪里获取？

A：登录灵心开放平台，在「应用」页面创建应用后即可获得，三者属于同一组凭证，不要拆分使用。旧「二开智能体模板」颁发的凭证在 v1.4.0 已不再受理。

Q3. 是否需要自己实现 HMAC-SHA256 签名？

A：不需要。AgentSdk.create(url, appId, appKey, appSecret) 会在内部完成签名与请求头构造。只有在自定义代理层需要重放签名时才涉及到手写签名，签名协议见 CHANGELOG 的破坏性变更表。

Q4. 一个 SDK 实例可以订阅多种被动回调类型吗？

A：可以。v1.4.0 把公开被动回调收敛为 8 种（Audio2Llm / Audio2Tts / Asr2Llm / Asr2Tts / AsrVideo2Vlm / AsrVideo2Tts / AudioVideo2Vlm / AudioVideo2Tts），可按需注册多个。类型定义见枚举参考，用法示例见被动示例。

Q5. 为什么交互链路的结果都是流式返回？流式与非流式有什么区别？

A：AgentSDK 的端侧交互链路是全链路流式的——

ASR 的音频输入以帧为单位流式上行给 SDK；
ASR / LLM / TTS 的结果都以 onXxxDelta（增量帧） + onXxxDone（结束标记）的方式增量下发，而不是等整段结果凑齐再一次性返回。

好处是"边产出边消费"：机器人可以在识别、生成、合成整体完成之前就开始播报或衔接下一步动作，端到端等待时长明显降低，响应速度与交互体验都会显著提升；非流式方案要等整段结果凑齐再一次性回吐，可感知的等待时间会明显变长。

Q6. 二开系列 AgentSDK 与传统 HTTP API 有什么区别？

A：定位不同 —— 传统 API（如 HTTP REST）是一次连接、一问一答的无状态调用：请求单帧、应答单帧、同步串行、上下文自带自灭。AgentSDK 面向机器人端侧的多模态实时交互，是长连接（WebSocket 全双工）+ 全链路时序的模型，核心差异有四点：

形状不同：一次交互不是"一个请求换一个响应"，而是两段时序——上行是音频帧序列（ASR 的音频输入本身就是流），下行是 ASR / LLM / VLM / TTS 结果和机器人状态推送的增量事件序列（onXxxDelta + onXxxDone）。
时序关系不同：请求与应答完全异步。同一 eventId 内的应答帧保序（由 SDK 内部的 per-agent 线程池保证）；上游阶段之间有先后——ASR done 之后 LLM 才开始产出 delta，但一旦 LLM 输出首段文字，TTS 就会拿这段文字异步合成并下发音频帧，与 LLM 后续 delta 并行推进。
触发方向不同：双向。机器人可主动上报（8 种被动回调：ASR / LLM / VLM / TTS 结果、机器人状态、人脸/声纹、打招呼等），SDK 也可主动下发（任务流）；不再是单向 client → server。
控制能力不同：有一等公民的打断语义（response.onInterrupt(eventId, interruptType, interruptTips)），可以在流未 done 时切换或终止当前应答，这在传统同步 API 中没有对应物。

一句话概括：传统 API 是"点对点的一次性问答"，AgentSDK 是"双向、异步、按 eventId 组织的时序对话"。接入侧的心智模型也随之变化——从"拼请求 / 解响应"变成"订阅回调 / 拼时序 / 决定何时打断或衔接下一步"。整体线程模型与重连见架构概述，两种交互模式详解见被动交互指南与主动交互指南。