版本变更记录 (CHANGELOG · JS / 浏览器)

JS SDK 与 Java SDK 共享 wire 协议与版本主线。本 CHANGELOG 只记录 JS 独有的变更；跨语言共享的核心变化（例如 v1.4.0 的鉴权标准化）请参阅 Java v1.5.0 CHANGELOG。

v1.5.0-SNAPSHOT（当前开发版本）

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

包版本: linksoul-agentsdk@1.5.0（首个对外版本） 发布日期: 开发中

🆕 新增能力：浏览器端超视距遥操（Teleop）

JS SDK 首个对外版本，面向浏览器（TypeScript / ESM），与 Java v1.5.0 共享同一套遥操 wire 协议。

• 入口：createAgentSdk(appId, options) → AgentSdk（按 appId 单例）
• 会话类 TeleopSession：enter() / startAudio(param?) / sendAudio(base64, eventId?) / finishAudio(eventId?) / keepAlive() / exit()
• 连接层 AgentConnection + KeepAliveController：connect() / close() / on(event, listener)；自动重连（默认固定 3s）；应用层 keep-alive（空闲 20s → 探测 3 次 → 超时关闭触发重连）
• 事件常量 AgentEventType（含 9 个遥操事件 + sdk_meta.report + error）、策略 AgentPolicy
• meta 上报 sendSdkMetaReport / systemInfoSnapshot / systemInfoDescription：每次 connected 自动上报 sdkLanguage: "js"

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

通过 ExtSkillSession 查询机器人可用的扩展技能清单并按需触发执行。

• 入口：sdk.createExtSkillSession({ agentId, requestId? }) → ExtSkillSession
• 方法：query() 查询技能清单 / invoke(extSkillId, input) 触发指定技能
• 事件常量 AgentEventType.ExtSkillQuery / ExtSkillQueryResult / ExtSkillInvoke / ExtSkillInvokeAck / ExtSkillInvokeResult
• 策略常量 AgentPolicy.ExtSkill（值 "extskill"）
• 顶层导出 ExtSkillSession 与类型 ExtSkillOptions / ExtSkillQueryResult / ExtSkillInvokeAck
• 回执经 sdk.on('message') 按 type 判读（SDK 不内置分发，与 Teleop 一致）
• 新增文档：扩展技能指南、ExtSkill API、ExtSkill 示例

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

createAgentSdk → connect → createTeleopSession → enter
   → (startAudio(param) → sendAudio* → finishAudio)+ → exit
   keepAlive 可在 enter 之后任意时刻调用（建议每 10 秒一次）

• enter / keepAlive / exit 返回 eventId；ACK 从 sdk.on('message') 里按 type === "*_ack" 判读，code === 0 成功、-1 服务端拒绝 / 机器人离线；
• startAudio / sendAudio / finishAudio 是 fire-and-forget（无 ACK）；
• startAudio(param?) 支持每段音频传 role（"male" / "female"）、threshold（-14 ~ 14）；
• sendAudio 会就地解码 base64 计算 audioLen（解码字节数）一并下发。

浏览器特有约束（与原生 SDK 的结构性差异）

• 鉴权走服务端代理：浏览器 WebSocket 不能设自定义头，authProvider 回调向同源服务端换取已签名的代理 URL；appSecret 绝不下发前端；
• 心跳经代理转换：SDK 发 JSON {type:"ping"}，由服务端代理转协议级 Ping；
• 无回调类：不提供 TeleopEnterCallback 等类，所有下行经 message 事件；
• 无真实 MAC / 用户名：macAddress 用 localStorage 持久化的 client_<hex>，username 恒为空；
• 需安全上下文：麦克风、crypto.randomUUID 仅在 https / localhost 可用（已内置回退）。

兼容性

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

依赖 / 构建