Teleop（超视距遥操）API · Android

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

v1.5.0 新增。Android SDK 的 com.agibot.aiem.sdk.teleop.* 与 Java v1.5.0 · Teleop API 完整同源，签名、字段、错误码、事件类型全部一致。本页只列 Android 独有的差异；一般查询请直接看 Java 页。

与 Java v1.5.0 的差异

差异点	Java v1.5.0	Android v1.5.0
`TeleopRequest.appendAudioDelta`	只把 base64 字符串放到 `audio` 字段	额外用 `Base64.getDecoder().decode(...)` 得到字节长度，回填 `audioLen` 字段一起下发
`TeleopRequest.appendAudioDelta` 空字符串处理	直接下发 `audio: ""`	空 / null 直接 `return`（不下发）
`enter` / `exit` 内部追踪	只发消息，dispatcher 通过 `teleopId` 反查 request	发消息前先 `AgentSdkTeleopMgr.trackEvent(eventId, this)`，dispatcher 可按 `eventId` 直接路由
底层 WebSocket	Netty	OkHttp（`com.squareup.okhttp3:okhttp:4.12.0`）
打包形态	JAR	AAR，含 `consumer-rules.pro`；`compileOnly lombok` 不会传递到调用方

其余 API（AgentSdk.registerTeleop / unregisterTeleop / TeleopEnterCallback.onEnterAck / TeleopKeepaliveCallback.onKeepaliveAck / TeleopExitCallback.onExitAck / IdGenerator.generateTeleopId()）与 Java 完全一致，签名与错误码见 Java v1.5.0 · Teleop API。

类图

text

AgentSdk
  ├── registerTeleop(TeleopRequest)
  └── unregisterTeleop(String teleopId)

TeleopRequest
  ├── constructor(AgentSdk, agentId, teleopId)
  ├── enter(AgentParam param, TeleopEnterCallback cb, long timeoutMs) → String eventId
  ├── startAudio(AgentParam param)                                    → String eventId
  ├── appendAudioDelta(String eventId, String audioDeltaBase64)
  ├── appendAudioDelta(String eventId, String audioDeltaBase64, double gain)
  ├── doneAudio(String eventId)
  ├── keepalive(TeleopKeepaliveCallback cb, long timeoutMs)           → String eventId
  └── exit(TeleopExitCallback cb, long timeoutMs)                     → String eventId

TeleopEnterCallback (abstract)
  └── onEnterAck(String teleopId, String eventId, int code, String msg)

TeleopKeepaliveCallback (abstract)
  └── onKeepaliveAck(String teleopId, String eventId, int code, String msg)

TeleopExitCallback (abstract)
  └── onExitAck(String teleopId, String eventId, int code, String msg)

IdGenerator
  └── generateTeleopId()  → "teleop_<21 位随机字符>"

`TeleopRequest.keepalive`

java

public String keepalive(TeleopKeepaliveCallback cb, long timeoutMs)

机器人在线探活。timeoutMs < 50 会被 clamp 到 50（当前仅占位）。返回本次消息 eventId。onKeepaliveAck 中 code == 0 表示机器人在线，code == -1 表示机器人离线。建议每 10 秒定时调用一次。

Android 注意：onKeepaliveAck 不在 UI 线程回调，如需更新界面请 runOnUiThread 或 Handler.post。

`TeleopKeepaliveCallback`

java

public abstract class TeleopKeepaliveCallback {
    public abstract void onKeepaliveAck(String teleopId, String eventId, int code, String msg);
}

通过 Lombok @Getter/@Setter 暴露 agentId、timeout 字段（SDK 内部注入）。

事件类型

Android SDK 的 AgentEventType 枚举与 Java 一致。遥操相关 9 个：

枚举成员	wire 值	说明
`AGENTSDK_TELEOP_ENTER`	`agentsdk.teleop.enter`	进入遥操
`AGENTSDK_TELEOP_ENTER_ACK`	`agentsdk.teleop.enter_ack`	进入回执
`AGENTSDK_TELEOP_AUDIO_START`	`agentsdk.teleop_audio.start`	音频段开始
`AGENTSDK_TELEOP_AUDIO_DELTA`	`agentsdk.teleop_audio.delta`	音频增量
`AGENTSDK_TELEOP_AUDIO_DONE`	`agentsdk.teleop_audio.done`	音频段结束
`AGENTSDK_TELEOP_KEEPALIVE`	`agentsdk.teleop.keepalive`	机器人在线探活
`AGENTSDK_TELEOP_KEEPALIVE_ACK`	`agentsdk.teleop.keepalive_ack`	探活回执
`AGENTSDK_TELEOP_EXIT`	`agentsdk.teleop.exit`	退出遥操
`AGENTSDK_TELEOP_EXIT_ACK`	`agentsdk.teleop.exit_ack`	退出回执

wire 结构

enter / keepalive / exit 的公共信封：

json

{
  "type":      "<event type>",
  "agentId":   "<agentId>",
  "teleopId":  "teleop_xxxxxxxxxxxxxxxxxxxxx",
  "eventId":   "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode": "teleop"
}

AGENTSDK_TELEOP_ENTER 与 AGENTSDK_TELEOP_AUDIO_START 在信封基础上携带 param。注意：param 是 AgentParam.getExtParam() 得到的扁平键值对，不带外层 extParam 包装：

json

{
  "type":      "agentsdk.teleop_audio.start",
  "agentId":   "<agentId>",
  "teleopId":  "teleop_xxxxxxxxxxxxxxxxxxxxx",
  "eventId":   "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode": "teleop",
  "param":     { "role": "male", "threshold": 0 }
}

调用方 API 不变：仍然是 enter(AgentParam, cb, timeout) / startAudio(AgentParam)。上面描述的是 SDK 内部把 AgentParam 序列化到 wire 的形状——直接放入 extParam 这层 Map，因此 param 下是扁平字段（与 iOS param.dictionary 一致）。

AGENTSDK_TELEOP_AUDIO_DELTA 在信封基础上额外携带 audio、audioLen 与 gain：

json

{
  "type":      "agentsdk.teleop_audio.delta",
  "agentId":   "<agentId>",
  "teleopId":  "teleop_xxxxxxxxxxxxxxxxxxxxx",
  "eventId":   "event_xxxxxxxxxxxxxxxxxxxxx",
  "agentMode": "teleop",
  "audio":     "<base64 chunk>",
  "audioLen":  640,
  "gain":      1.0
}

audioLen 是解码后的字节数，供服务端做完整性 / QoS 校验；业务侧无需理会。gain 为音频增益倍数（appendAudioDelta 的可选参数，默认 1.0，范围 (0, 10]，越界归一 / 截断）。