LinkSoul 智能体二开 SDK (iOS)

🆕 v1.5.0 新增：超视距遥操（Teleop）
⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。
iOS SDK v1.5.0 与 Java v1.5.0 同步开放第三条交互路径 —— 超视距遥操：远端操作员在线接管机器人交互。Swift 端 API 与 Java 一一对应，示例见 agentsdk_for_ios/Examples/TeleopExample/main.swift。详见超视距遥操指南。

🆕 v1.5.0 新增：扩展技能（ExtSkill）
⚠️ 尚未上线：本能力为 v1.5.0-SNAPSHOT 开发中特性，接口与协议可能调整，正式发布前请勿用于生产环境。
iOS SDK v1.5.0 同步开放扩展技能：通过 ExtSkillRequest(agentSdk, agentId, requestId) 构造请求，调用 query(...) 拉取技能清单、invoke(extSkillId:input:...) 触发技能执行。回调通过 onQueryResult 获取清单结果，onInvokeAck + onState + onInvokeResult 接收三段式执行回执。详见扩展技能指南。

⚠️ v1.4.0 验签方式标准化（不兼容 v1.3.0 及更早版本）
iOS SDK 从初版起就直接采用 v1.4.0 的鉴权体系（HMAC-SHA256 五头签名，AgentSdk.create(url:appId:appKey:appSecret:)），v1.5.0 保持不变。完整迁移要点见 Java v1.4.0 CHANGELOG。

连接信息

项目	值
WebSocket 地址	`wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk`
appId / appKey / appSecret	通过灵心开放平台创建应用获取
Swift 版本	5.7+
最低平台	iOS 13 / macOS 10.15 / tvOS 13 / watchOS 6

swift

let agentSdk = AgentSdk.create(url: url, appId: appId, appKey: appKey, appSecret: appSecret)

快速导航

文档	说明
快速开始	Swift Package Manager 引入 + Info.plist 权限 + 完整 Swift 接入代码
超视距遥操指南	v1.5.0 新增：远端操作员通过 SDK 接管机器人的语音交互
超视距遥操 API	v1.5.0 新增：`TeleopRequest` / `TeleopEnterCallback` / `TeleopExitCallback` Swift 签名
超视距遥操示例	v1.5.0 新增：`TeleopExample` 完整流程
扩展技能指南	v1.5.0 新增：查询与调用机器人扩展技能
扩展技能 API	v1.5.0 新增：`ExtSkillRequest` / `ExtSkillQueryCallback` / `ExtSkillInvokeCallback` Swift 签名
扩展技能示例	v1.5.0 新增：ExtSkill query + invoke 完整流程
CHANGELOG	iOS 版 SDK 版本变更记录

指南（Guide）

文档	说明
架构概述	线程模型、重连机制、鉴权（HMAC-SHA256 五头签名）
被动交互指南	8 种被动回调详解 + Function Call 开放与 Arbiter 仲裁（v1.5.0 新增）+ 对话历史（v1.5.0 新增）
主动交互指南	任务流生命周期（start / task / end / interrupt）
任务流 payload 协议	`action_group` / `action_type` 详解
语义技能参考	技能全集
机器人端侧状态参考	22 个 `stateName` 模块
错误处理	错误码、鉴权回调、重连策略

API 参考

文档	说明
AgentSdk API	SDK 主入口类 Swift 签名
被动回调 & 响应 API	8 组回调 / 响应对照表 + FunctionCall / History
主动请求 API	`TaskFlowRequest` / `AgentParam` / `AgentMeta` / `IdGenerator`
枚举参考	`AgentCallbackType` / `AgentEventType` / `ArbiterDecision` 等

示例（Examples）

文档	说明
被动交互示例	8 个 `register*` 示例 + FunctionCall 示例 + `onHistories` 示例
主动交互示例	`TaskFlowExample`（start / task / end / interrupt）

其他

文档	说明
常见问题排除手册 & QA	现象 → 排查 → 处理 + QA
名词解释	业务概念 / SDK 术语 / 模型与音视频 / 拒识 / JSON 协议字段

四种交互模式

text

┌──────────────────────────────────────────────────────────────┐
│                       灵心平台                                 │
├──────────────────────────────────────────────────────────────┤
│  机器人 ──音频/视频/文本──→ LinkskyGateway ──→ SDK回调        │  被动交互
│  机器人 ←──ASR/LLM/TTS──── LinkskyGateway ←── SDK响应         │
│                                                              │
│  SDK主动请求 ──→ LinkskyGateway ──→ 机器人                    │  主动交互
│  SDK接收结果 ←── LinkskyGateway ←── 机器人                    │
│                                                              │
│  操作员音频 ──→ LinkskyGateway ──→ 机器人执行                  │  超视距遥操（v1.5.0 新增）
│  操作员 ←──enter/exit ack── LinkskyGateway ←── 机器人         │
│                                                              │
│  SDK query ──→ LinkskyGateway ──→ 机器人(技能清单)            │  扩展技能（v1.5.0 新增）
│  SDK invoke ──→ LinkskyGateway ──→ 机器人(执行) ──→ ack+result│
└──────────────────────────────────────────────────────────────┘

被动交互：机器人上行音频/视频/文本 → SDK 回调 → SDK 返回 ASR/LLM/VLM/TTS 响应；
主动交互：SDK 主动发起 —— v1.5.0 公开入口收敛到任务流（TaskFlowRequest）；
超视距遥操（v1.5.0 新增）：Swift 端调用 TeleopRequest.enter → startAudio(param:) → appendAudioDelta → doneAudio → exit；enter/exit 由 TeleopEnterCallback / TeleopExitCallback 收 ACK，音频事件为 fire-and-forget；
扩展技能（v1.5.0 新增）：Swift 端调用 ExtSkillRequest.query(...) 拉取技能清单，invoke(extSkillId:input:...) 触发执行；回调 onQueryResult 返回清单，onInvokeAck + onState + onInvokeResult 提供三段式执行回执。

集成方式

Swift Package Manager 引入（推荐）：

swift

// Package.swift
dependencies: [
    .package(url: "https://<your-git-host>/linksoul-agentsdk.git",
             from: "1.5.0")
]

targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "LinksoulAgentSDK", package: "linksoul-agentsdk"),
    ])
]

Xcode GUI：File > Add Package Dependencies… → 填仓库地址 → 选择 LinksoulAgentSDK product。

完整的接入模板、Info.plist 权限声明见快速开始。