LinkSoul AgentSDK for Python v1.5.0-SNAPSHOT

🆕 v1.5.0 新增：超视距遥操（Teleop）/ Beyond-line-of-sight teleoperation
v1.5.0 在既有的被动交互 / 主动交互两条路径之外新增第三条 —— 超视距遥操（Teleop）：远端操作员通过 SDK 下发 enter → start_audio / append_audio_delta / done_audio* → exit 语音接管指令，目标机器人在线执行。
请求类：linksoul_agentsdk.TeleopRequest（enter / start_audio(param=None) / append_audio_delta / done_audio / exit）
回调基类：TeleopEnterCallback.on_enter_ack(...) / TeleopExitCallback.on_exit_ack(...)（code=0 成功；code=1000 SDK 侧连接已 closed；code=-1 服务端拒绝）
注册：AgentSdk.register_teleop(TeleopRequest) / AgentSdk.unregister_teleop(teleop_id)
事件类型 7 个：agentsdk.teleop.enter / agentsdk.teleop.enter_ack / agentsdk.teleop_audio.start|delta|done / agentsdk.teleop.exit / agentsdk.teleop.exit_ack
策略枚举：AgentPolicy.TELEOP（wire 值 "teleop"）
ID 前缀 teleop_...：IdGenerator.generate_teleop_id()
start_audio(param) 可携带 role（man / woman）、threshold（-14 ~ 14）等音色 / VAD 参数
详见超视距遥操指南（zh） / Teleop guide (en)、Teleop API（zh） / Teleop API (en)、Teleop 示例（zh） / Teleop example (en)。
v1.5.0 introduces a third interaction mode, teleop, on top of passive / active. A remote operator drives the robot via TeleopRequest.enter → start_audio(param) → append_audio_delta* → done_audio → exit; enter/exit legs are ack'd through TeleopEnterCallback / TeleopExitCallback, and audio.* messages are fire-and-forget.

⚠️ 验签方式标准化（不兼容 v1.3.0 及更早版本）/ Breaking auth change
v1.4.0 已遵循灵心开放平台规范，对 SDK 的鉴权（验签）方式做了标准化改造，v1.3.0 及更早版本无法直接平滑升级（v1.5.0 沿用同一套鉴权体系）：
项目 v1.3.0 及更早 v1.4.0
网关 URL wss://agentsdk.agibot.com/v1/agentsdk wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk
凭证来源灵心平台「二开智能体模板」灵心开放平台「应用」（新增 app_key）
创建方法 AgentSdk.create(url, app_id, app_secret) AgentSdk.create(url, app_id, app_key, app_secret)
鉴权机制 JWT（AGIBOT_AUTHORIZATION 请求头） HMAC-SHA256（5 个请求头：X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature）
回调类型 JWT payload 独立请求头 X-Callback-Types（JSON 数组字符串）
升级路径见 zh/CHANGELOG.md / en/CHANGELOG.md。
v1.4.0 standardises the AgentSDK signing scheme to match the LinkSoul open-platform spec and is NOT backward compatible with v1.3.0 or earlier. JWT auth is replaced by HMAC-SHA256 with five signed request headers (X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature); AgentSdk.create() now takes an extra app_key parameter, credentials are issued by an application on the open platform, and the gateway URL has changed. See the CHANGELOGs above for the migration path.

项目	v1.3.0 及更早	v1.4.0
网关 URL	`wss://agentsdk.agibot.com/v1/agentsdk`	`wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk`
凭证来源	灵心平台「二开智能体模板」	灵心开放平台「应用」（新增 `app_key`）
创建方法	`AgentSdk.create(url, app_id, app_secret)`	`AgentSdk.create(url, app_id, app_key, app_secret)`
鉴权机制	JWT（`AGIBOT_AUTHORIZATION` 请求头）	HMAC-SHA256（5 个请求头：`X-App-Id` / `X-App-Key` / `X-Timestamp` / `X-Nonce` / `X-Signature`）
回调类型	JWT payload	独立请求头 `X-Callback-Types`（JSON 数组字符串）

选择语种 / Choose locale

语种 / Locale	入口
简体中文	zh/index.md
English	en/index.md

章节速览 / Section quick-links

Section	中文	English
Home / 首页	zh/index.md	en/index.md
Quick Start / 快速开始	zh/guide/quickstart.md	en/guide/quickstart.md
Architecture / 架构	zh/guide/architecture.md	en/guide/architecture.md
Passive guide / 被动交互	zh/guide/passive_callbacks.md	en/guide/passive_callbacks.md
Active guide / 主动交互	zh/guide/active_operations.md	en/guide/active_operations.md
Teleop guide / 超视距遥操	zh/guide/teleop.md	en/guide/teleop.md
Task-flow payload / 任务流协议	zh/guide/taskflow_payload.md	en/guide/taskflow_payload.md
Semantic skills / 语义技能	zh/guide/skills.md	en/guide/skills.md
AgentSdk API	zh/api/agent_sdk.md	en/api/agent_sdk.md
Passive callbacks API	zh/api/passive_callbacks.md	en/api/passive_callbacks.md
Active requests API	zh/api/active_requests.md	en/api/active_requests.md
Teleop API / 超视距遥操	zh/api/teleop.md	en/api/teleop.md
Enums	zh/api/enums.md	en/api/enums.md
Examples / 示例	zh/examples/	en/examples/
Glossary / 名词解释	zh/glossary.md	en/glossary.md
Changelog	zh/CHANGELOG.md	en/CHANGELOG.md

与 Java SDK 的关系 / Relationship to the Java SDK

同版本的 Java SDK v1.5.0 文档是配套实现， API 面与协议都等价；本套文档仅做以下 Python 化：

模块路径：com.agibot.aiem.sdk.* → linksoul_agentsdk.*
命名：camelCase → snake_case（onRequest → on_request、registerAudio2Llm → register_audio2_llm …）
异步原语：Java 用 Netty，本 SDK 用 websocket-client + threading（同步阻塞）

The Java SDK v1.5.0 docs describe the sibling implementation. The public surface and wire protocol are equivalent; the Python build only differs in naming (camelCase → snake_case) and threading primitives (websocket-client + threading).