SDK 变更日志

@hasheeai/agent-sdk-ts 遵循 Semantic Versioning：

主版本号 (X.0.0)：不兼容的 API 变更
次版本号 (0.X.0)：向后兼容的新功能
修订号 (0.0.X)：向后兼容的 bug 修复

格式遵循 Keep a Changelog 约定。真源：packages/public/agent-sdk-ts/CHANGELOG.md。

[0.2.0] — 2026-04-24

V1 内测期首次公开发布。Phase D1 + D2 交付。

Added

createWebhookDispatcher — 无状态 webhook Agent 调度器（Cloudflare Workers / Vercel Edge / AWS Lambda / Node.js Express）
Layer 1-3 E2EE envelope 处理 — content + sign + wrap
HMAC-SHA256 webhook 签名验证 — ±5 分钟 timestamp 窗口 + 10 分钟 delivery-id 去重
双 secret 宽限期支持 —— /webhook/rotate-secret 旋转后 1 小时内新旧 secret 同时验证通过
createEncryptedSender —— 完整 encrypt-then-send 链路，必须传 aadContext（D2-1 zero-downgrade，不允许 silent epoch=0 fallback）
PeerKeyLoader interface + PeerKeyNotFoundError — zero-downgrade 保证
AadContextRequiredError — 漏传 aadContext 时抛错，与 mobile send-pipeline 硬错合约对齐
parseInboundMessage — 解码 + 验签 + 解密入站 wire envelope；surface aad_epoch 给 caller 做 AAD 串联
HasheeAgent 类 — 自动 E2EE / 传输（WebSocket + REST fallback）/ X25519 + Ed25519 密钥对生命周期
Artifact 发送 + 更新 — sendArtifact() / updateArtifact()
流式 delta 输出 — createStreamSession()
Conversation epoch 注册 — setConversationEpoch，v1.1 AAD 绑定 hardening 必需
Group 加密原语 — 从 @hasheeai/protocol 重导出 hashee-group-v1.2 wire 格式
Webhook 辅助 — verifyWebhookSignature, parseWebhookPayload
幂等 key 生成 — crypto.randomUUID（无 Math.random fallback）

Notes

V1 目标 runtime：TypeScript 5.7+ / Node 22+ / Cloudflare Workers / 现代浏览器 / Electron 28+
Tree-shakeable ESM-first；CJS 消费者通过 require("@hasheeai/agent-sdk-ts") 也支持（package.json exports map）
License：UNLICENSED（pre-public-license 窗口；源码 license 决策待定）

未来路线

版本	计划	主要工作
0.3.0	V1.1 内	Stateful Ratchet 落地（Layer 4 + Layer 5 完整）/ 持久化 ratchet state / Capability Manifest update API
0.4.0	V2 准备	Python SDK 对齐 / Bun runtime 支持 / WebSocket auto-reconnect 完善
1.0.0	V2 上市	API 稳定承诺 / SemVer 担保 / breaking change 政策正式化

详见 Agent 开发者平台规范的 V1 / V2 路线图。

升级指南

从 0.1.x → 0.2.x

0.1.x 是内部预览版，未对外发布。0.2.0 是首个对外版本，无升级路径。

未来 SDK 升级建议

# 查看当前版本
npm list @hasheeai/agent-sdk-ts

# 升级到最新 minor / patch
npm install @hasheeai/agent-sdk-ts@^0.2

# 大版本升级（务必先看本页 Breaking 变更）
npm install @hasheeai/agent-sdk-ts@latest

任何 breaking 变更会在本页 Breaking 子段单独列出。

报告 SDK 问题

联系 Hashee 开发者支持
加入 Hashee 开发者社区（V1 内测期 invite-only）