版本变更记录 (CHANGELOG)

v1.5.0-SNAPSHOT (当前开发版本)

⚠️ 本版本为开发中(SNAPSHOT)版本，下列 v1.5.0 新增能力（超视距遥操 / 扩展技能 / Function Call 与 Arbiter）尚未正式上线，接口可能调整。

发布日期: 开发中

🆕 新增能力：超视距遥操（Teleop）

v1.5.0 在既有的被动交互 / 主动交互两条路径之外，正式对外开放第三条交互路径 —— 超视距遥操：远端操作员通过 SDK 建立会话，向指定 agentId 的机器人推送人工语音接管指令。

• 新增类：
  • com.agibot.aiem.sdk.teleop.TeleopRequest —— 会话请求实体，方法：enter / startAudio(AgentParam) / appendAudioDelta / doneAudio / keepalive / exit
  • com.agibot.aiem.sdk.teleop.TeleopEnterCallback —— onEnterAck(teleopId, eventId, code, msg)
  • com.agibot.aiem.sdk.teleop.TeleopKeepaliveCallback —— onKeepaliveAck(teleopId, eventId, code, msg)；机器人在线探活，遥操期间建议每 10 秒定时调用一次，code != 0 视为机器人离线
  • com.agibot.aiem.sdk.teleop.TeleopExitCallback —— onExitAck(teleopId, eventId, code, msg)
  • com.agibot.aiem.sdk.mgr.AgentSdkTeleopMgr —— 全局 request 索引，7200s 无活动自动清理
  • com.agibot.aiem.sdk.client.TeleopMsgHandler —— 网关下行消息路由
• 新增 AgentSdk 公开方法：
  • registerTeleop(TeleopRequest)
  • unregisterTeleop(String teleopId)
• 新增策略枚举：AgentPolicy.TELEOP（wire 值 "teleop"）
• 新增事件类型 9 个：
  • agentsdk.teleop.enter / agentsdk.teleop.enter_ack
  • agentsdk.teleop_audio.start / agentsdk.teleop_audio.delta / agentsdk.teleop_audio.done
  • agentsdk.teleop.keepalive / agentsdk.teleop.keepalive_ack
  • agentsdk.teleop.exit / agentsdk.teleop.exit_ack
• 新增 ID 生成器：IdGenerator.generateTeleopId()（前缀 teleop_）
• 新增示例：com.agibot.aiem.teleop.TeleopExample
• 新增文档：超视距遥操指南、Teleop API、Teleop 示例

🆕 新增能力：扩展技能（ExtSkill）

v1.5.0 同步新增扩展技能能力：SDK 通过 query 拉取指定机器人可用的扩展技能清单，通过 invoke 触发执行，执行结果以三段回执（invoke_ack 确认受理 → report_state 上报进度 → invoke_result 返回执行结果）异步返回；invoke_ack 与 invoke_result 各回调一次，执行期间技能侧可通过 agentsdk.ext_skill.report_state 多次上报进度（对应 onState）。与 Teleop 使用 sn+teleopId 标识不同，ExtSkill 使用 agentId+requestId 标识。

• 新增类：
  • com.agibot.aiem.sdk.extskill.ExtSkillRequest —— 请求实体，方法：query / invoke
  • com.agibot.aiem.sdk.extskill.ExtSkillQueryCallback —— onQueryResult(agentId, requestId, eventId, code, msg, result)
  • com.agibot.aiem.sdk.extskill.ExtSkillInvokeCallback —— onInvokeAck(agentId, requestId, eventId, code, msg) + onState(agentId, requestId, eventId, stateName, stateValue) + onInvokeResult(agentId, requestId, eventId, code, msg, param)
  • com.agibot.aiem.sdk.mgr.AgentSdkExtSkillMgr —— 按 requestId 索引，7200s 无活动自动清理
  • com.agibot.aiem.sdk.client.ExtSkillMsgHandler —— 网关下行消息路由
• 新增 AgentSdk 公开方法：
  • registerExtSkill(ExtSkillRequest)
  • unregisterExtSkill(String requestId)
• 新增策略枚举：AgentPolicy.EXT_SKILL（wire 值 "extskill"）
• 新增事件类型 6 个：
  • agentsdk.ext_skill.query / agentsdk.ext_skill.query_result
  • agentsdk.ext_skill.invoke / agentsdk.ext_skill.invoke_ack / agentsdk.ext_skill.report_state / agentsdk.ext_skill.invoke_result
• 新增 ID 生成器：IdGenerator.generateExtSkillRequestId()（前缀 extskill_）
• 新增示例：com.agibot.aiem.extskill.ExtSkillExample
• 新增文档：扩展技能指南、ExtSkill API、ExtSkill 示例

🆕 新增能力：Function Call 开放与 Arbiter 仲裁

v1.5.0 在被动交互链路上开放 Function Call 分发与 Arbiter 仲裁：网关将待处理的 function call 透传给 SDK，二开应用做出仲裁决策后回传，决定该 function call 由智能体默认链路处理还是由应用接管覆盖。

• 新增回调方法（8 种被动回调类均有）：onFunctionCall(String agentId, String eventId, FunctionCallInfo functionCall, <XxxResponse> response)，默认空实现，按需重载
• 新增响应方法（8 种 Response 类均有）：onArbiter(String eventId, String decision, AgentParam arbParam)
• 新增实体类：com.agibot.aiem.sdk.FunctionCallInfo（字段 source / policy / type / value / param）
• 新增枚举：com.agibot.aiem.sdk.enums.ArbiterDecision（DELEGATE = "delegate" / OVERRIDE = "override"）
• 新增消息处理器：com.agibot.aiem.sdk.client.passive.FunctionCallMsgHandler
• 新增事件类型：
  • agentsdk.function_call.expose（网关 → SDK，触发 onFunctionCall）
  • agentsdk.function_call.arbiter（SDK → 网关，由 onArbiter 发出）
• 文档：被动交互指南 · Function Call 开放与 Arbiter 仲裁、被动回调 & 响应 API · Function Call 与 Arbiter
• 说明：当前仅 Java 版开放该接口，其余语言 SDK 暂未实现

⚠️ 破坏性变更：灵心平台「技能调用方式 = Agent 调用」下线（依赖者须升级 v1.5.0）

v1.5.0 引入 Function Call + Arbiter 仲裁器 后，灵心平台二开智能体配置中的「技能调用方式」为 Agent 调用 的转发机制已下线，由仲裁器取代：

• 旧机制（≤ v1.4.0）：二开智能体配置里「技能调用方式」选择 Agent 调用 后，技能被触发时平台会把技能请求转发给二开应用（SDK）自行处理。
• 新机制（v1.5.0）：该平台配置已下线，平台不再自动转发技能，而是把待处理的技能请求以 function call 形式透传给 SDK（onFunctionCall），由二开应用通过 仲裁器接口（response.onArbiter(...)）显式决定委托策略：ArbiterDecision.DELEGATE（委托智元交互云默认链路处理）或 ArbiterDecision.OVERRIDE（二开应用接管覆盖）。

因此，若你的智能体依赖了「技能调用方式 = Agent 调用」的转发能力，必须升级到 v1.5.0，并基于 Function Call 与 Arbiter 接口重写技能委托 / 分流逻辑，否则技能将无法被正确处理。

调用契约

register → enter → (startAudio(param) → appendAudioDelta* → doneAudio)+ → exit → unregister

遥操存续期间可任意频次调用 keepalive（推荐每 10 秒一次）；任何一次 onKeepaliveAck 收到 code != 0 都应视为机器人离线，立即 exit + unregisterTeleop 释放资源。

• enter / keepalive / exit 由 SDK 侧回调收 ACK；code == 0 成功，code == 1000 表示 SDK 本地连接已 closed，code == -1 服务端拒绝；
• startAudio / appendAudioDelta / doneAudio 是 fire-and-forget（无 ACK）；
• startAudio(AgentParam) 支持在每段音频开始时传递 role（"male" / "female"）、threshold（-14 ~ 14）等音色 / VAD 参数；
• timeout 参数当前仅做占位（clamp 到 ≥50ms），暂未真正驱动超时回调，后续版本会补齐。

兼容性

• 接口层面完全向后兼容 v1.4.0：现有 registerAuth / 被动回调 / 任务流接口均无变更；升级方式为 pom.xml 版本号从 1.4.0-SNAPSHOT → 1.5.0-SNAPSHOT。
• 若未使用 Teleop / Function Call，运行时行为与 v1.4.0 一致。
• 但有一处破坏性变更：依赖灵心平台「技能调用方式 = Agent 调用」转发的智能体，须按上文「破坏性变更」章节改造为 Function Call + Arbiter。

依赖

同 v1.4.0（未升级第三方依赖）。

v1.4.0-SNAPSHOT

发布日期: 开发中

⚠️ 破坏性变更 — 验签方式标准化（不兼容 v1.3.0 及更早版本）

v1.4.0 已遵循灵心开放平台规范，对 AgentSDK 的鉴权（验签）方式做了标准化改造。该改动同时影响网关、凭证、AgentSdk.create() 签名与协议头，v1.3.0 及更早版本无法平滑升级，需按以下要点同步替换：

升级步骤：

1. 在灵心开放平台「应用」页面重新申领 appId / appKey / appSecret（注意这是一组新凭证，旧凭证不可继续使用）。
2. 将 WebSocket 网关 URL 切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk。
3. 调用方升级 AgentSdk.create(url, appId, appSecret) → AgentSdk.create(url, appId, appKey, appSecret)。
4. 若有自定义代理层 / 网关层在转发 SDK 请求，须解析并透传新的 5 个鉴权头 + X-Callback-Types，并移除对旧 AGIBOT_AUTHORIZATION 头的依赖。
5. 确认调用方未再读取 AgentSdk 的 appSecret（已移除 Getter）。

新增

• 主动打招呼三合一：被动回调基类 PassiveCallback 新增 onGreetSignal(agentId, eventId, param, GreetResponse)， 通过 GreetResponse.onGreetVlmDelta/Done（VLM 流式文本）与 onGreetTtsDelta/Done （TTS 音频字节的 base64 字符串流）两路输出打招呼内容
• 新增协议事件 agentsdk.greet_response.tts.delta / agentsdk.greet_response.tts.done （配合既有的 agentsdk.greet_response.vlm.delta/done）
• UID（人脸 / 声纹）开放：被动回调基类新增 onFaceInfo(agentId, eventId, param) 和 onVideoFrame(agentId, eventId, flag, buf, isKeyFrame, localTs, param)
• 状态推送统一并入被动回调：PassiveCallback.onState(agentId, eventId, stateName, stateValue)
• 新增协议事件 agentsdk.state_request.meta（机器人状态推送）

变更

• 打招呼能力收敛：删除独立的 Greet2VlmCallback、Greet2VlmResponse， 打招呼信令统一通过 PassiveCallback.onGreetSignal 接收，VLM/TTS 两路应答合并到 GreetResponse； 并且不再使用独立的 AgentCallbackType，由任意已注册的被动回调接收
• 状态监听能力收敛：删除独立的 StateListenCallback 和 AgentSdk.registerStateListen(...)， 状态变化推送改由所有 PassiveCallback 子类共享的 onState(...) 接收
• 修复 GreetResponse.onGreetTtsDelta/Done 误用 VLM 事件类型的 Bug

移除

• Greet2VlmCallback / Greet2VlmResponse / StateListenCallback（合并到 PassiveCallback 基类）
• AgentSdk.registerStateListen(...)（功能合并到被动回调注册流程）
• 删除以下被动回调类（含对应 Response）： Audio2Asr / Audio2Audio / AudioVideo2Audio / Text2Tts
• 删除以下 AgentSdk 公开方法（底层 Callback/Request 类暂保留）：
  • 被动回调注册：registerPushListen
  • 主动接口：querySkill、queryState、registerPullStream / unregisterPullStream
• AgentCallbackType 枚举同步删除 AUDIO_2_ASR、AUDIO_2_AUDIO、AUDIO_VIDEO_2_AUDIO、TEXT_2_TTS、STATE_LISTEN、GEET_2_VLM、GEET_2_TTS（PUSH_LISTEN 仍保留但未对外开放）
• 公开被动回调收敛为 8 种：Audio2Llm / Audio2Tts / Asr2Llm / Asr2Tts / AsrVideo2Vlm / AsrVideo2Tts / AudioVideo2Vlm / AudioVideo2Tts
• 公开主动接口收敛为 registerTaskFlow / unregisterTaskFlow

v1.3.0

新增

• 里程碑版本，功能全量开放
• 主动交互：技能查询 (querySkill) — 查询机器人支持的技能及参数
• 主动交互：状态查询 (queryState) — 查询机器人当前状态
• 主动交互：任务流 (TaskFlowRequest) — 编排多步骤任务（startRequest/taskRequest/endRequest/interruptRequest）
• 主动交互：拉流 (PullStreamRequest) — startRequest/keepaliveRequest/endRequest
• 主动交互：推流监听 (PushListenCallback) — 接收机器人推送的视频流
• 主动交互：状态监听 (StateListenCallback) — 实时接收状态变化
• 被动交互支持技能返回：response.onSkill(eventId, itemId, skillType, skillName, skillParam)
• 被动交互支持打断接口：response.onInterrupt(eventId, interruptType, interruptTips)
• AgentParam 支持泛型参数（getObject/setObject、getList/setList）
• 被动交互回调增加 AgentParam param 扩展参数
• 协议新增 policy 字段标识交互模式
• 响应中返回 eventId 字段，方便调用方追踪会话
• FlowStartCallback/FlowTaskCallback 区分 RequestAck 与 ExecuteAck 两阶段确认
• 接口超时自动清理机制
• AgentThreadPool 线程池管理（per-agent 线程绑定，保证消息顺序）
• AgentDelayedPool 延迟任务框架（心跳超时检测）
• 主动交互示例程序
• 打断及技能返回示例程序

变更

• 网关地址变更 (2026-06-25)：WebSocket 地址从 wss://agentsdk.agibot.com/v1/agentsdk 切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk；凭证来源也从"灵心平台二开智能体模版"调整为灵心开放平台创建的应用（appId / appKey / appSecret 一并由应用页面获取）
• 认证方式升级 (2026-06-24)：AgentSdk.create() 新增 appKey 参数，签名从 JWT 改为 HMAC-SHA256 网关鉴权
  • 旧签名：AgentSdk.create(url, appId, appSecret) — 生成 JWT token 并写入 AGIBOT_AUTHORIZATION 请求头
  • 新签名：AgentSdk.create(url, appId, appKey, appSecret) — 通过 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature 五个请求头完成鉴权，签名算法为 HMAC-SHA256("GET\n{path}\n{timestamp}\n{nonce}")
  • LinkskyClient 移除对 JwtUtil 的依赖，内置 hmacSha256 工具方法
  • AgentSdk 移除 appSecret 字段的 Getter，认证参数由 LinkskyClient 内部持有
  • callbackTypes 从 JWT payload 字段迁移为独立请求头 X-Callback-Types（JSON 数组字符串）
• timeout 参数类型从 int 升级为 long，支持更大超时范围
• 所有 onRequest 回调方法签名新增 AgentParam param 参数
• 日志输出优化，减少冗余日志

v1.1.0

新增

• 多模态被动回调: AsrVideo2Vlm、AsrVideo2Tts、AudioVideo2Vlm、AudioVideo2Tts、AudioVideo2Audio
• AgentMeta 封装替代原始 JSONObject
• 视频流透传支持（H264 + Image）
• 图片帧大小限制

变更

• 重构项目结构，独立迁移为独立仓库
• 配置化自定义智能体的 appId 及 appSecret

v1.0.0

发布日期: 2025-02-27

初始版本

• SDK 核心框架：AgentSdk 单例工厂模式
• WebSocket 客户端：LinkskyClient（Netty, 自动重连, JWT认证）
• 基础被动回调：Audio2Asr、Audio2Llm、Audio2Tts、Asr2Llm、Asr2Tts、Audio2Audio、Text2Tts
• AgentParam 类型安全参数包装
• IdGenerator 唯一ID生成
• JwtUtil JWT签名工具
• 示例程序

依赖版本