版本变更记录 (CHANGELOG · iOS)

iOS SDK 与 Java SDK 保持同版本号发布。本 CHANGELOG 只记录 iOS 独有的变更；跨语言共享的核心变化（例如 v1.4.0 的鉴权标准化）请参阅 Java v1.5.0 CHANGELOG。

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

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

发布日期: 开发中

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

iOS SDK 首个正式对外的 v1.5.0 版本，与 Java v1.5.0 完全对齐；在既有的被动交互 / 主动交互两条路径之外，正式对外开放第三条交互路径 —— 超视距遥操。

• 新增 Swift 类（Sources/LinksoulAgentSDK/Teleop）：
  • TeleopRequest —— 请求实体，方法：enter(param:enterCallback:timeout:) / startAudio(param:) / appendAudioDelta(eventId:audioDelta:) / doneAudio(eventId:) / keepalive(keepaliveCallback:timeout:) / exit(exitCallback:timeout:)
  • open class TeleopEnterCallback —— open func onEnterAck(teleopId:eventId:code:msg:)
  • open class TeleopKeepaliveCallback —— open func onKeepaliveAck(teleopId:eventId:code:msg:)
  • open class TeleopExitCallback —— open func onExitAck(teleopId:eventId:code:msg:)
• 新增 AgentSdk 公开方法：registerTeleop(_:) / unregisterTeleop(teleopId:)
• 新增 AgentSdkTeleopMgr.shared 单例（全局 request 索引）
• 新增 Client/TeleopMsgHandler.swift（网关下行消息路由）
• 新增 AgentPolicy.teleop（wire 值 "teleop"）
• 新增 9 个 AgentEventType：.teleopEnter / .teleopEnterAck / .teleopAudioStart / .teleopAudioDelta / .teleopAudioDone / .teleopKeepalive / .teleopKeepaliveAck / .teleopExit / .teleopExitAck
• 新增 IdGenerator.generateTeleopId()（前缀 teleop_）
• 新增示例 target：
  • Examples/TeleopExample/main.swift —— 最小 enter→...→exit 流程
  • Examples/TeleopSimulator/main.swift —— 长压测样例

调用契约（与 Java v1.5.0 一致）

register → enter → (startAudio(param:) → appendAudioDelta* → doneAudio)+ → exit → unregister
                    keepalive 可在 enter 之后任意时刻调用（建议每 10 秒一次）

• enter / keepalive / exit 由 SDK 侧回调收 ACK；code == 0 成功、code == 1000 表示 SDK 本地连接已 closed、code == -1 服务端拒绝；
• startAudio / appendAudioDelta / doneAudio 是 fire-and-forget（无 ACK）；
• startAudio(param:) 支持在每段音频开始时传递 role（"male" / "female"）、threshold（-14 ~ 14）等音色 / VAD 参数；
• keepalive(keepaliveCallback:timeout:) 发送一次在线探活；onKeepaliveAck 中 code == 0 表示机器人在线，code == -1 表示离线；业务侧应定时调用（建议每 10 秒），掉线后主动 exit + unregisterTeleop；
• timeout 参数当前仅做占位（clamp 到 ≥50ms）。

iOS 侧实现要点

• TeleopEnterCallback / TeleopExitCallback 采用 open class（非 protocol），便于共享 timeout / agentId / updateTs 等基类字段；
• TeleopRequest.linkskyClient 用 weak var，避免与 AgentSdk 之间的循环强引用；
• TeleopRequest.updateTs 由 NSLock 保护，兼容多线程发送。

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

iOS SDK v1.5.0 同步开放扩展技能交互路径：应用通过 SDK 查询机器人上注册的扩展技能列表，并按需触发执行，获取三段式回执（ack + state + result）。

• 新增 Swift 类（Sources/LinksoulAgentSDK/ExtSkill）：
  • ExtSkillRequest —— 请求实体，方法：query(queryCallback:timeout:) / invoke(extSkillId:input:invokeCallback:timeout:)
  • open class ExtSkillQueryCallback —— open func onQueryResult(agentId:requestId:eventId:code:msg:result:)
  • open class ExtSkillInvokeCallback —— open func onInvokeAck(agentId:requestId:eventId:code:msg:) + open func onState(agentId:requestId:eventId:stateName:stateValue:) + open func onInvokeResult(agentId:requestId:eventId:code:msg:param:)
• 新增 AgentSdk 公开方法：registerExtSkill(_:) / unregisterExtSkill(requestId:)
• 新增 AgentPolicy.extSkill（wire 值 "extskill"）
• 新增 6 个 AgentEventType：.extSkillQuery / .extSkillQueryResult / .extSkillInvoke / .extSkillInvokeAck / .extSkillReportState / .extSkillInvokeResult
• 新增 IdGenerator.generateExtSkillRequestId()（前缀 extskill_）
• 新增文档：
  • 扩展技能指南
  • ExtSkill API
  • ExtSkill 示例

ExtSkill 调用契约

register → query → (invoke → ack → state* → result)* → unregister

• agentId + requestId 标识一个 ExtSkill 会话；
• query 拉取技能清单，onQueryResult 回调返回 code == 0 成功；
• invoke 触发技能执行，三段回执：onInvokeAck（服务端已受理）→ onState（执行期间技能侧通过 agentsdk.ext_skill.report_state 多次上报进度，可选）→ onInvokeResult（执行完成，param 携带结果）；
• timeout 参数当前仅做占位（clamp 到 ≥50ms）。

iOS 侧 ExtSkill 实现要点

• ExtSkillQueryCallback / ExtSkillInvokeCallback 采用 open class（非 protocol），与 Teleop 回调风格一致；
• ExtSkillRequest.linkskyClient 用 weak var，避免循环强引用。

兼容性

• iOS SDK 从 v1.5.0 起对外发布；此前无正式版本对外供开发者引用。

依赖版本