版本变更记录 (CHANGELOG)

v1.4.0 (alpha)

发布日期: 开发中

v1.4.0 已遵循灵心开放平台规范，对 AgentSDK 的鉴权（验签）方式做了标准化改造。Python SDK 与 Java SDK 同步升级，v1.3.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（HS256 签名 + `AGIBOT_AUTHORIZATION` 请求头）	HMAC-SHA256(`"GET\n{path}\n{timestamp}\n{nonce}"`)，签名经五个请求头下发
鉴权请求头	1 个：`AGIBOT_AUTHORIZATION`	5 个：`X-App-Id` / `X-App-Key` / `X-Timestamp` / `X-Nonce` / `X-Signature`
`callback_types` 传递方式	JWT payload 字段	独立请求头 `X-Callback-Types`（JSON 数组字符串）
实现影响	`LinkskyClient` 依赖 `jwt_util.py`	`LinkskyClient` 改用 `hmac` + `hashlib`；`AgentSdk` 不再对外暴露 `app_secret`

升级步骤：

在灵心开放平台「应用」页面重新申领 app_id / app_key / app_secret（旧凭证不可继续使用）。
将 WebSocket 网关 URL 切换为 wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk。
调用方升级 AgentSdk.create(url, app_id, app_secret) → AgentSdk.create(url, app_id, app_key, app_secret)。
若有自定义代理 / 网关在转发 SDK 请求，须解析并透传新的 5 个鉴权头 + X-Callback-Types，并停用旧 AGIBOT_AUTHORIZATION。
确认调用方未再读取 AgentSdk.app_secret（属性已下线）。

与 Java SDK v1.4.0 等价，参考 Java CHANGELOG 获取完整变更点。本节仅列出 Python 端的差异点。

包名：linksoul_agentsdk（PEP 8 蛇形命名），与 Java 包路径 com.agibot.aiem.sdk.* 一一对应
公开模块：linksoul_agentsdk.passive / linksoul_agentsdk.active / linksoul_agentsdk.client / linksoul_agentsdk.mgr
WebSocket 客户端：基于 websocket-client>=1.7，同步阻塞模式，在独立 daemon 线程跑 run_forever
心跳：由 websocket-client 内置（ping_interval=10s, ping_timeout=5s）
重连：连接断开自动通过 threading.Timer 延迟 3 秒重连
线程模型：AgentThreadMgr 用一组单线程 ThreadPoolExecutor，每个 agent_id 绑定一个串行 worker（与 Java AgentThreadMgr 等价）
鉴权：基于 hmac + hashlib（HMAC-SHA256），与 Java LinkskyClient.hmacSha256 对齐，签名字段经 X-App-Id / X-App-Key / X-Timestamp / X-Nonce / X-Signature 五个请求头下发；回调类型集合经 X-Callback-Types 请求头下发

Java SDK 的 camelCase 全部转为 Python 的 snake_case，并加上类型注解：

Java	Python
`AgentSdk.create(url, appId, appKey, appSecret)`	`AgentSdk.create(url, app_id, app_key, app_secret)`
`registerAuth(AgentAuthCallback)`	`register_auth(AgentAuthCallback)`
`registerAsr2Llm(Asr2LlmCallback)`	`register_asr2_llm(Asr2LlmCallback)`
`onRequest(agentId, eventId, ...)`	`on_request(agent_id, event_id, ...)`
`response.onLlmItemDelta(...)`	`response.on_llm_item_delta(...)`
`response.onInterrupt(...)`	`response.on_interrupt(...)`
`response.onSkill(...)`	`response.on_skill(...)`
`IdGenerator.generateEventId()`	`IdGenerator.generate_event_id()`
`AgentParam.create().setString(k, v)`	`AgentParam.create().set_string(k, v)`

依赖	版本
Python	3.9+
websocket-client	≥ 1.7.0

Java/Python 始终保持版本号对齐——历史版本（v1.0.0 / v1.1.0 / v1.3.0）的协议层变更详见 Java SDK v1.4.0 CHANGELOG。