AIMA开放平台文档中心Agent SDK (iOS)

Teleop（超视距遥操）API · iOS

Teleop（超视距遥操）API · iOS

⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。

v1.5.0 新增。类均从 LinksoulAgentSDK 模块导出：import LinksoulAgentSDK 之后即可访问 TeleopRequest / TeleopEnterCallback / TeleopKeepaliveCallback / TeleopExitCallback。使用流程见 Teleop 指南。

类图

text
AgentSdk
  ├── registerTeleop(_ request: TeleopRequest)                     // 关联 LinkskyClient
  └── unregisterTeleop(teleopId: String)

TeleopRequest
  ├── init(agentSdk: AgentSdk, agentId: String, teleopId: String)
  ├── enter(param: AgentParam?, enterCallback: TeleopEnterCallback, timeout: Int64)     → String eventId
  ├── startAudio(param: AgentParam?)                                                    → String eventId
  ├── appendAudioDelta(eventId: String, audioDelta: String, gain: Double = 1.0)
  ├── doneAudio(eventId: String)
  ├── keepalive(keepaliveCallback: TeleopKeepaliveCallback, timeout: Int64)             → String eventId
  └── exit(exitCallback: TeleopExitCallback, timeout: Int64)                            → String eventId

open class TeleopEnterCallback: Timestamped
  └── open func onEnterAck(teleopId: String, eventId: String, code: Int, msg: String?)

open class TeleopKeepaliveCallback: Timestamped
  └── open func onKeepaliveAck(teleopId: String, eventId: String, code: Int, msg: String?)

open class TeleopExitCallback: Timestamped
  └── open func onExitAck(teleopId: String, eventId: String, code: Int, msg: String?)

IdGenerator
  └── static func generateTeleopId() -> String    // "teleop_<21 位随机字符>"

AgentSdk（新增方法）

方法说明
registerTeleop(_ request: TeleopRequest)把 request 与当前 SDK 的 LinkskyClient 绑定，并加入 AgentSdkTeleopMgr.shared。必须在调用 request.enter(...) 之前调用。
unregisterTeleop(teleopId: String)从索引中移除。exit 完成或不再需要该会话时调用，避免依赖 7200s 后台清理。

TeleopRequest

swift
public init(agentSdk: AgentSdk, agentId: String, teleopId: String)
  • agentId：目标机器人的 agentId（由灵心开放平台颁发）；
  • teleopId：会话 ID，用 IdGenerator.generateTeleopId() 生成，同一次遥操期间固定。
方法语义
enter(param:enterCallback:timeout:) -> String进入遥操会话。param 可为 nil；timeout < 50 会被 clamp 到 50（当前仅存储不生效）。返回本次消息 eventId。
startAudio(param:) -> String声明本段音频开始（fire-and-forget）。param 可为 nil；常用键：role（"male" / "female"）、threshold（-14 ~ 14）。返回 eventId；后续 appendAudioDelta / doneAudio 必须使用同一个 eventId。
appendAudioDelta(eventId:audioDelta:gain:)追加音频块。audioDelta 是 base64 字符串。可选 gain 为音频增益倍数，默认 1.0，有效范围 (0, 10]；gain <= 0 归一为 1.0，gain > 10 截断为 10.0，随消息 gain 字段下发。fire-and-forget。
doneAudio(eventId:)声明本段音频结束（fire-and-forget）。可再次 startAudio 开新一段。
keepalive(keepaliveCallback:timeout:) -> String机器人在线探活。通过 onKeepaliveAck 回传结果；code == 0 表示机器人在线，code == -1 表示机器人离线。建议每 10 秒定时调用一次；timeout 处理规则同 enter。返回本次消息 eventId。
exit(exitCallback:timeout:) -> String退出遥操。timeout 处理规则同 enter。
var updateTs: Int64最近一次消息发送时间（毫秒）。7200s 无活动会被后台清理。
var agentId: String / var teleopId: String会话身份
var enterCallback: TeleopEnterCallback? / var keepaliveCallback: TeleopKeepaliveCallback? / var exitCallback: TeleopExitCallback?最近一次绑定的回调

回调错误码

code含义
0成功（网关业务层 ACK）
-1服务端返回失败，msg 携带 errorMsg 详情
1000本地失败：发送时 SDK 侧 LinkskyClient 已 closed；SDK 会同步在原线程回调该 code，业务侧应视为发送失败，避免继续下发音频

TeleopEnterCallback / TeleopKeepaliveCallback / TeleopExitCallback

均为 open class（继承 Timestamped），业务侧继承并 override 对应方法：

swift
final class MyEnter: TeleopEnterCallback {
    override func onEnterAck(teleopId: String, eventId: String, code: Int, msg: String?) {
        // code == 0 成功；-1 服务端拒绝；1000 本地连接关闭
    }
}

final class MyKeepalive: TeleopKeepaliveCallback {
    override func onKeepaliveAck(teleopId: String, eventId: String, code: Int, msg: String?) {
        // code == 0 机器人在线；-1 机器人离线（msg 含 errorMsg）；1000 本地连接关闭
    }
}

基类字段：

  • var agentId: String? —— SDK 内部注入；
  • var timeout: Int64 —— enter / keepalive / exit 传入的 clamp 值；
  • var updateTs: Int64 —— SDK 内部用于超时清理。

IdGenerator.generateTeleopId()

swift
public static func generateTeleopId() -> String

返回形如 teleop_ABCDEFGHIJKLMNOPQRSTU 的会话 ID（前缀 + 21 位随机 [A-Za-z0-9]）。与 flow_ / event_ / item_ / pull_ / signal_ 等其他前缀互不冲突。

事件类型

见 Teleop 指南 · 事件族与协议。iOS 端 AgentEventType 使用 Swift 的 camelCase case 名（.teleopEnter 等），wire 值与 Java 完全一致。