@agentunion/fastaun 0.5.15 → 0.5.17

package/CHANGELOG.md

@@ -6,292 +6,332 @@
 
 ---
 
-## 0.5.15 — 2026-09-15
-
-### 修复
-
-#### 协议事件与应用事件隔离
-- 协议事件、transport observer 和断线回调使用独立 dispatcher，不再被慢速应用 handler 阻塞。
-- 协议事件转发到应用层时深拷贝 payload，公开错误统一转换为 `{code, message}`，避免暴露内部错误对象。
-
-#### Worker、Pull 与 V2 连接代次
-- Node.js Worker transport 增加连接代次和旧响应保护；Worker 启动、运行中异常或熔断时回退本地 transport，旧连接结果不会污染新连接。
-- Transport、Pull gate、ACK 和后台同步默认超时统一放宽到约 35 秒；Forward gate key 将默认 `limit=50` 纳入归一化，V2 续页使用初始 cursor 构造 gate key。
-
-### 改进
-
-- Transport/RPC 日志补充本端 AID、对端 AID 和入站/出站方向，并为乱序响应保留原请求上下文。
-- 统一公开 RPC 错误信息，移除错误结果中的内部 `cause` 暴露。
-- SDK、锁文件、运行时版本和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.15`。
-
-### 测试
-
-- 增加协议 dispatcher、payload 隔离、错误映射、日志上下文和 transport 超时测试。
-- 扩展 Worker/native transport、Pull gate、V2 cursor、连接代次和 Node.js conformance 测试。
-
-## 0.5.14 — 2026-09-11
-
-### 修复
-
-#### Pull gate watchdog 超时隔离
-- Pull watchdog 超时只使当前 Pull job 失败，不再通过全局失效状态影响 `message.send` 等非 Pull RPC。
-- 保留 background Pull 的全局 single-flight gate；超时但尚未真正结束的旧 Pull 继续占用 gate，后续 Pull 等待其 settle 后再执行。
-
-### 改进
-
-- SDK、锁文件、运行时版本和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.14`。
-
-### 测试
-
-- 增加 Pull 超时隔离、非 Pull RPC 投递和全局 single-flight gate 保持的单元测试。
-
-## 0.5.13 — 2026-09-08
-
-### 修复
-
-#### agent.md description 可选字段
-- `validateAgentMdDocument` 不再要求 frontmatter 必须包含 `description`，缺失或空字符串均可通过校验，与 `description` 的可选字段定义保持一致。
-- `description` 存在时仍必须是字符串，长度上限保持为 100 个 Unicode 码点；`aid`、`name`、`type`、`version` 的必填和格式校验不变。
-
-### 改进
-
-- SDK、锁文件、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.13`。
-
-### 测试
-
-- 新增缺失、空字符串和非字符串 `description` 的 Schema 单元测试，并保留 Unicode 长度边界验证。
-
-## 0.5.12 — 2026-09-05
-
-### 新功能
-
-#### 定向群邀请
-- `GroupFacade` 新增 `inviteMember`、`listMyInvites`、`acceptInvite`、`rejectInvite` 和 `revokeInvite`，统一规范化群 ID、邀请 ID/AID 别名并接入签名 RPC。
-- `create({ members })` 在群创建完成后逐一发出定向邀请，支持 `member_type`，跳过自身和重复 AID；Node.js cross-SDK agent 增加邀请 RPC 与事件观测。
-- 邀请按群和目标 AID 聚合，在线重复、分页恢复和重连恢复只发布一次 `group.invite_received`；状态持久化，部分终态保留剩余 pending 邀请。
-
-### 修复
-
-#### Forward Pull、ACK 与游标
-- Forward 页完成后忽略页内空洞，按页最大序号和服务端 `contiguous_seq` 证明推进 seq-tracker，并在提交成功后 ACK；已观察到的 Push 上界未追平时继续翻页，即使 `has_more=false`。
-- 空页不直接用高位服务端 cursor 覆盖本地连续游标，待恢复 cursor 在下一次成功 Forward 时应用；持久化失败回滚 tracker 并禁止 ACK。
-- inline push 只有在包含非空 inline payload 时才推进连续游标并 ACK；非 inline push 只更新 `maxSeen` 并触发 Forward，不直接推进 A/T/H 或 ACK。Tail 仅维护窗口，History 不推进实时游标。
-
-#### Push、V2 与生命周期
-- P2P、群消息和群事件的 plain/V2 路径统一上述边界；缺少 sender IK/SPK 时保留阻塞页，不错误推进、ACK 或续页，密钥恢复后按 `pending_retry` 投递。
-- 当前设备自发消息在 Pull 中只标记序号，不重复发布；重复/迟到 inline ACK 保留 pending。群 changed、dissolved、自入群等非 inline Push 只记录上界并交由 Forward 处理。
-- Pull gate 识别 inline realtime 竞争任务，避免不必要挂起并继续按 namespace 正确串行化提交。
-
-### 改进
-
-- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.12`。
-
-### 测试
-
-- 新增定向邀请 facade、聚合持久化、重连恢复、部分终态和 Node.js cross-SDK agent 测试。
-- 扩展 Forward 空洞、服务端 contiguous 证明、空页 cursor、持久化回滚、inline/non-inline Push、Tail/History 不推进、self-sync 去重及缺 IK/SPK 阻塞边界测试；跨域 runner 使用 `agentid.cn`/`agentid.pub`。
-
-## 0.5.11 — 2026-09-03
-
-### 新功能
-
-#### 消息来源与同步生命周期
-- P2P 消息、群消息、群事件、撤回和不可解密事件的应用 payload 新增 `source`，统一标识 `push`、`pull`、`inline_push` 或 `pending_retry`；`delivery.changed` 同步增加规范化 `source`。
-- 新增 `sync.started`、`sync.progress`、`sync.stopped` 生命周期事件。首次进入 Pull 时启动同步，每个 P2P/群 Pull page 完成后报告 namespace、页数、原始/已投递条数、`has_more`、`remaining`/估算剩余量，全部 Pull work 排空或中止时结束。
-- 同步事件继续经应用异步 FIFO 分发；并发 namespace 归入同一 run，Pull 失败、断线、关闭或身份代次重置以 `reason: "aborted"` 收口，不再把失败同步报告为正常排空。
-
-#### 连接后身份准入自愈
-- 每次 Gateway 连接成功后异步执行一次身份准入检查：普通 AID 缺少远端 agent.md 时复用本地内容或生成默认内容并补传。
-- 对当前 AID 作为群主的群逐个检查 group AID；缺少本地群证书/私钥时触发绑定并沿用绑定流程上传 group agent.md，已有群身份但远端缺少 group agent.md 时补传。检查失败只记录告警，不阻塞已建立的连接。
-
-### 修复
-
-#### Node.js Network Actor 容错
-- `worker_threads` Network Actor 和短 RPC worker 增加 `ready` 启动握手及约 2 秒超时；worker 不可创建、启动前报错/退出或未及时 ready 时熔断该 worker，并回退主线程本地 transport。
-- Actor 已连接后崩溃会清理 pending、异步发布连接错误和断线事件，后续连接使用本地 transport；无 `worker_threads` 或显式本地模式仍保持应用事件异步 FIFO，避免 handler 阻塞网络处理。
-
-#### V2 消息兼容与来源保持
-- Tail/Forward/History 能识别 V1 wrapper 内的 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` V2 envelope，并进入 V2 解密路径；群撤回在旧格式行中仍优先归一化为撤回事件。
-- ordered queue、sender IK 延迟恢复、inline realtime 和不可解密事件保持原始来源，避免补洞消息被误标为 push；群 Tail 同步进度仅由当前实例拥有的 cursor 产生。
-
-### 改进
-
-- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.11`。
-
-### 测试
-
-- 新增 Network Actor 启动超时、禁用后本地回退、运行中崩溃与异步连接事件测试。
-- 扩展 `source`、`sync.*` 状态机、Pull 中止、分页进度、V1 wrapper 内 V2 envelope、连接后普通/群 agent.md 自愈及版本相关测试。
-
-## 0.5.10 — 2026-09-02
-
-### 新功能
-
-#### `delivery.changed` 投递汇总
-- 新增应用事件 `delivery.changed`，覆盖 `push`、`inline_push` 和全局 Pull 排空（`pull_drained`）三类触发来源；payload 按 namespace 聚合 `deliveredCount`。
-- P2P 统一归入 `p2p` namespace，群消息按 canonical group AID 归一化；多页/并发/重复/空 Pull、ordered queue 和 inline push 均折叠为稳定的单次通知。
-- continuation、sender IK 延迟恢复和 ordered drain 均计入全局 Pull 保留量；全部排空后才发布 `pull_drained`，连接或身份代次切换会隔离旧结果，原消息事件先于汇总事件。
-
-### 修复
-
-#### 事件分发与生命周期
-- 应用事件改由单客户端 FIFO 异步队列分发，handler 不再阻塞网络或内部处理；单个 handler 异常隔离，`close()` 会排空已接受事件。
-- 支持 handler 内重入 RPC、Pull 和 `close()`，避免自等待死锁；trace/meta observer、断线回调及解密/状态事件也经过异步分发边界。
-
-#### WebSocket、Pull 与消息幂等
-- 短 RPC 支持并发调用、`AbortSignal` 取消和超时；连接代次变化会丢弃旧事件并清理 pending，WebSocket 写入统一串行化。
-- 普通 Pull、P2P/群 V2 Pull、inline realtime、续拉和 ACK 提交纳入统一的 Pull 排空生命周期，旧代次不会继续发布、持久化或确认消息。
-- `message.send`/`group.send` preflight 自动生成 `messageId`，显式值保持不变；V2 重试、缓存 envelope 和底层 RPC 继续传递同一 ID，缺失响应 ID 时从请求回填。
-
-#### agent.md 与短 RPC 错误
-- 远端缺失的 agent.md 增加约 60 秒负缓存窗口，避免重复下载；短 RPC 错误保留服务端映射属性，便于调用方识别原始错误。
-
-### 改进
-
-- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.10`。
-
-### 测试
-
-- 新增 `delivery.changed` 单元和单域集成测试，覆盖 namespace 归一化、来源折叠、Pull 排空、ordered queue、inline push 和代次隔离。
-- 扩展异步 dispatcher、短 RPC 并发与取消、Pull 排空生命周期、messageId、agent.md 负缓存、错误映射及 observer/断线回调测试。
-
-## 0.5.9 — 2026-08-31
-
-### 安全性
-
-- agent.md 签名证书强制使用 ECDSA P-256，拒绝其他 EC 曲线，收紧本地校验与协议要求的一致性。
-- 身份切换和 discovery 使用代际检查；旧身份迟到的 discovery 结果不得回写新身份的 Gateway 候选或 token metadata。
-
-### 修复
-
-#### AID 注册、agent.md 与群身份
-- `AIDStore.register()` 在 AID、证书和私钥已成功落盘后，不再因默认 agent.md 上传返回失败而把整个注册报告为失败，避免重试时命中已注册冲突。
-- agent.md 自动恢复优先上传本地自定义内容，不再用默认模板覆盖；恢复后若仍收到同一 `-32003`，按 `0/50/100/200ms` 短退避重试原 RPC。
-- 命名群创建、绑定、续期和群主转移完成分别使用 `create:<group_name>`、`bind:<group_id>`、`renew:<group_id>`、`complete:<group_id>` 暂存待用密钥。RPC 前先落盘，失败重试复用同一密钥，身份导入及 group agent.md 上传完成后再清理；绑定流程兼容旧裸 `group_id` 槽位。
-- 恢复 `groupName` 到 `group_name` 的兼容映射；`GroupFacade` 未提供 `aidStore` 时保留直接 RPC 行为。`group.v2.confirm_state` 同时补传 `group_id`。
-
-#### Pull gate、消息窗口与生命周期
-- Pull 去重键纳入窗口 mode、cursor、force、limit 及外部 group cursor 参数；只有完整请求相同的 Pull 才会合并。
-- watchdog 超时后等待旧 Pull 真正 settle 再放行后续任务；close/disconnect 会失效在途 Pull、停止 watchdog、等待旧任务结束后保存 tracker，旧身份结果不能继续发布、落盘或 ACK。
-- unread hint、Tail 后补洞及实时窗口按目标上界计算 Forward 页数；plain Forward ACK 同时识别标量 `cursor` 和 `cursor.current_seq`。
-- V2 Forward 缺少 sender IK/SPK 时不提交本页最大序号、不发送 ACK，也不继续后续页，保留服务端消息供密钥恢复后重拉。
-- Auth 短 RPC 支持 `AbortSignal`；关闭、断连和身份切换可取消在途 WebSocket、HTTP discovery 与 DNS fallback 请求。
-
-### 改进
-
-- 顶层导出 `CompleteGroupTransferOptions`。
-- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.9`。
-
-### 测试
-
-- 扩展 P-256、注册部分成功、自定义 agent.md 恢复、群身份 pending key、facade 兼容和 `confirm_state` 参数测试。
-- 扩展 Pull 完整键、watchdog settle/失效、生命周期取消、多页 Forward、ACK cursor、缺 IK/SPK 不推进游标及类型导出测试。
-
-## 0.5.8 — 2026-08-30
+## 0.5.17 — 2026-09-19
 
 ### 新功能
 
-#### AID 注册与 agent.md
-- `AIDStore.register()` 默认生成符合 schema 的 `agent.md`（`aid`、`type: "agent"` 等字段），使用对应 AID 签名并上传；`uploadAgentMd()` 仍可按需显式替换内容，也支持由另一个本地 uploader AID 认证代传。
-- 增加 agent.md 的严格 frontmatter、UTF-8/Base64、大小、证书有效期、证书指纹、公钥指纹和签名校验；校验失败不会覆盖已有内容或可信缓存。
-- 新版本连接能力声明 `agent_md_validation_v1`；收到缺少 agent.md 的 `-32003` 时自动生成、签名、上传并重试原 RPC。恢复只针对当前 AID，群 agent.md 恢复只由持有 group AID 私钥的群主执行。
-
-#### 群身份与 group agent.md
-- 命名群的 `createGroup()` 在 `group.create` 时携带新生成的 group AID 公钥和曲线，并要求服务端返回匹配的 group AID 证书；匿名群先创建，再按原始 `groupId` 绑定证书并导入本地 group AID。
-- `bindGroupAid()`、`renewGroupAid()` 和群主转移完成流程校验证书、公钥和用途，并自动上传 `type: "group"` 的 group agent.md；内容由 group AID 签名，群主 AID 负责认证上传。
-- group agent.md 可以事后上传，但在上传有效证书和 agent.md 前，群管理、群消息、`group.fs` 等后续群 RPC 继续受 Gateway 限制；历史群缺证书或缺 group agent.md 的自动修复仅允许群主执行。
+#### 非持久消息与设备定向
+- 正 `ttl` 的 V2 加密消息会透传到最终发送 RPC；`storage=volatile` 消息使用独立 volatile cursor 拉取和 ACK，不进入持久 `seq`、seq-tracker 或持久水位。
+- Push、Pull 和 sender IK 延迟恢复共用按消息去重及并发占用状态；纯 volatile 页可独立续页，cursor epoch 不匹配时清空旧 cursor 并重试一次，切换 AID、设备或 slot 时重置本地 volatile 状态。
+- `message.v2.pull` / `message.v2.ack` 接入公开调用管线和实例上下文校验；`message.ack` 支持只提交 `volatile_cursor(s)` / `volatile_ids`。
+- V2 `message.send` 支持 `device_id` / `to_device_id` 定向接收设备，同时保留发送方 self-sync 和 audit recipients；应用消息公开规范化的 `sender_device_id`，不再暴露内部 slot 字段。
 
-### 安全性
-
-- Gateway 在 client-vs-gateway RPC 入口校验客户端 agent.md、普通 AID 证书、group AID 证书及 group agent.md；`group.create`、`group.bindGroupAid`、`group.renewGroupAid` 等建群/绑定例外保留必要的恢复路径。
-- 上述准入只对 connect 协商声明 `agent_md_validation_v1` 的新 SDK 生效，未声明能力的旧 SDK 保持原有行为；Gateway 同时收紧 AID type、group namespace、RPC 目标和路由边界校验。
-- agent.md、证书和身份解析采用带 TTL 的正/负缓存，支持并发请求合并、容量上限及 CA 写入、agent.md 上传和相关事件触发的失效；代际校验防止过期查询回写缓存。
+#### 群管理与 agent.md 事件
+- `GroupFacade` 新增 `block`、`unblock`、`getBlocklist`、`reportStatus` 和 `getMemberStatuses`；屏蔽、禁言和成员状态可通过高层 SDK 直接调用。
+- 远端 agent.md 已有版本的 ETag 或 Last-Modified 变化时，通过应用事件管线发布 `agentmd.changed`。
 
 ### 修复
 
-#### Pull gate 与未读提示
-- `AUNClient` 统一使用一个 pull gate 和队列，前台 pull 优先于后台 pull，二者共享 namespace 去重；P2P 作为一个 namespace，每个 group 独立 namespace，后台请求不旁路也不丢弃。
-- pull 生命周期纳入 `idle`、`pulling`、`processing` 等状态和专用 watchdog；从拉取开始计时，约 3 秒超时即复位并继续队列，应用触发和新 push 会主动唤醒状态机。续拉在响应处理完成后重新入队并置于队尾。
-- `client.online` 时服务端为 P2P 及存在未读消息或事件的群发送 unread hint；SDK 每条 hint 转换为一次 background forward pull，按 namespace 去重。
-
-#### V2 消息窗口与游标
-- Forward 页忽略页内空洞并推进到 pulled page 最大 seq；先完成解密/发布，再一次性提交本页连续游标并发送 ACK 或 piggyback ACK。缺少 SPK/IK 时异步 bootstrap，不阻塞页处理；有密钥但解密失败时发布结构化失败事件后再推进游标。
-- 修正 P2P/群 V2 的 1DH/3DH、IK/SPK bootstrap、self-sync、forward cursor/ACK、重叠页去重及跨页有序投递；服务端 ACK 水位不足时保留待确认状态并在后续 pull 重试。
-- Message/Group thought 存储与响应结构统一，并增加响应预算/大小限制；Go `CollabActionResult` 兼容 `removed` 布尔值和整数格式。
+#### Storage / Group FS 上传 Content-Type
+- `writeBytes`、`uploadFile` 和 Group FS 上传在未显式指定类型时按实际字节识别 MIME，并以路径后缀作为回退。
+- 上传会话、HTTP PUT 和 `completeUpload` 使用同一 Content-Type；保留 session 的其它 header 并替换冲突的 Content-Type，修复 OSS 预签名校验不一致导致的 403。
 
-#### Gateway 与服务连接可靠性
-- 加固 service attach、连接替换、关闭码、协议错误预算、超时以及 reader/close 竞态；Python/Go 服务端行为和合同测试保持一致。
-- nameservice agent.md upsert、上传验证及数据库/快照兼容性同步修正；SDK 测试器使用阿里云 PyPI 镜像缓解下载超时。
+#### 群身份恢复
+- 匿名群创建在 RPC 前持久化群密钥并复用稳定的 `_create_request_id`，响应丢失后的重试不会重复创建群；命名群恢复可复用已保存身份。
+- 新群主收到 `owner_transfer_rekey_pending` 后只自动完成一次转让；重连时即使服务端角色仍为 member，也会按本地 pending 状态续跑 `complete_transfer`。
 
 ### 改进
 
-- SDK 包版本、锁文件版本、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 更新为 `0.5.8`。
-- 低层 agent.md 上传能力继续由 `AIDStore` 提供，`AUNClient` 通过高层注册、建群和恢复流程编排；agent.md 替换仍保留为可选、按需操作。
+- Message、SendResult、PullResult 和 AckResult 类型补充 volatile 元数据、cursor、ACK 结果及 `sender_device_id`；`status` 接受 `accepted`。
+- SDK、锁文件、运行时版本和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.17`。
 
 ### 测试
 
-- 新增 AID 类型和 Gateway 路由准入的单元、集成、E2E 及跨 SDK 测试，覆盖新旧能力声明、证书/agent.md 缺失恢复、群主权限和缓存失效。
-- 扩展 agent.md、群身份绑定/续期、group.fs、V2 E2EE、pull gate 状态机、unread hint、游标/ACK、thought 响应预算和服务连接合同测试。
-
-## 0.5.7 — 2026-08-20
-
-### 新功能
-
-#### 首次连接自动重试
-- `connect()` 在首次 discovery、认证或 Gateway WebSocket 建连遇到可重试的瞬时错误时，进入与断线重连一致的指数退避生命周期；每轮重新执行完整 discovery/认证并使用最新凭据。
-- 认证、权限、参数和状态类永久错误仍立即返回，不创建后台重连任务。
+- 增加 volatile Push/Pull/ACK、纯 volatile 分页、cursor 恢复、并发去重、定向设备和公开字段边界测试。
+- 增加群屏蔽/禁言/成员状态、匿名创建幂等、群主转让自动完成与恢复测试。
+- 增加 Storage/Group FS MIME 与 Content-Type 一致性测试，并扩展单域、跨 SDK 和 8 MiB 会话上传 E2E 覆盖。
 
-#### Mail facade 与当前令牌 API
-- 新增 `client.mail` / `MailFacade`，提供 `send()`、`get()`、`list()`、`delete()`、`move()`、`mark()`、`search()`、`getAttachment()`、`getQuota()`、`health()` 和 `status()`；`mail.send` 按非幂等 RPC 使用 35 秒超时。
-- 新增 `getAccessToken()`，同步读取后台刷新任务维护的最新 access token，供应用在每次外部 HTTP 数据面请求前取用；getter 本身不发起认证、刷新或网络请求。
-
-### 修复
-
-- 引入重连代际所有权；显式 `connect()` / `disconnect()` / `close()` 可终止旧重连代，旧任务不能清理或覆盖新连接，事件回调内触发生命周期操作也不会自锁。
-- 收口群 ID 语义：`g-` 不再具有特殊含义，所有群 base 统一按 4–64 字符规则校验；移除 `base@issuer` 兼容输入，仅保留 `group.{issuer}/{base}`、`base.issuer` 和本域短格式。
-- `stream/created` 和 `stream/closed` 内部事件重新发布给公共订阅者。
-- Group tail/history 遇到缺失 payload 的不完整 V1 行时采用有界跳过或失败语义，避免阻断后续同步。
-
-### 改进
-
-- SDK 包版本、锁文件版本和运行时 `VERSION` 更新为 `0.5.7`。
-
-### 测试
-
-- 新增首连认证/建连失败、永久错误、重连代际取消、事件回调重入、最新 token getter 和 Mail facade 单元测试。
-- 扩展群 ID 校验、跨域 Group FS、群消息窗口、V2 E2EE 和 replay guard 集成测试。
-
-## 0.5.6 — 2026-08-13
-
-### 新功能
-
-#### V2 消息窗口与实时推送
-- 完成 `tail` / `forward` / `history` 消息窗口处理、seq 状态持久化和 pull gate 调度，统一 P2P 与群消息的补洞、确认和有序投递行为。
-- 连接认证时声明 `inline_realtime_payload_v1`；实时事件优先使用内联消息载荷，离线或不完整事件继续通过 pull 回退，保留可靠性。
-- 对齐 Message/Group self-sync 与 bootstrap 契约，补齐多设备同步和前向保密状态处理。
-
-#### 群消息提及过滤
-- 新增 `mention_mode` 归一化与投递过滤，兼容 `disabled`、`mention-only` 及历史 `mention_only` 表示。
-
-### 安全性
-
-- `lookupPeer()` 在内存 peer cache 未命中或指纹不匹配时自动回源获取证书；支持按签名指纹加载历史证书，并在写入 peer cache 前完成证书链/身份校验。
-- `group.index` 和 `agent.md` 在下载或更新提交缓存前验签；rules、announcement、join requirements 等索引化 settings 逐项校验已签名索引中的 ETag。签名者权限、摘要或内容校验失败时不落盘，也不参与业务读取；已验证缓存的普通读取不重复验签。
-- 修复跨域 Storage 下载携带错误 bearer、Gateway 候选故障转移及连接/重连竞态问题。
-
-### 改进
-
-- 收口短 RPC、challenge/response、前置帧及 transport 运行时可靠性；后台补洞/ack 不再挤占前台 RPC。
-- 扩展跨 SDK agent、runner 与 trace 诊断，覆盖消息窗口和 inline realtime 场景；Node.js SDK 本版本未新增离线 Push facade。
-- 文件型 keystore 删除 `.seed` 自动迁移和 `.seed.migrated.*` 自动回退；保留显式 `changeSeed(oldSeed, newSeed)`，显式迁移成功后才归档旧 `.seed`。
-- SDK 包版本和运行时 `VERSION` 更新为 `0.5.6`。
-
-### 测试
-
-- 新增消息窗口、inline realtime push、mention mode、self-sync/bootstrap、transport/connect race、peer identity、group index 和 `agent.md` 单元/集成测试。
-- 扩展 cross-SDK contract vectors 与 runner，覆盖签名验签、缓存提交边界、inline pull 回退和窗口状态一致性。
-
-## 0.5.5 — 2026-07-14
+## 0.5.16 — 2026-09-16
+
+### 修复
+
+#### agent.md avatar 字段
+- agent.md frontmatter 新增可选 `avatar` 字符串字段，按 Unicode 码点限制最长 256 个字符；普通和 group agent.md 生成器、Schema 验证器保持一致。
+- 群创建、绑定和恢复流程透传 avatar；无值时不生成空字段，Name Service 与 Gateway 对类型和长度执行相同校验。
+
+#### 协议事件与应用事件隔离
+- 协议事件、transport observer 和断线回调使用独立 dispatcher，不再被慢速应用 handler 阻塞。
+- 协议事件转发到应用层时深拷贝 payload，公开错误统一转换为 `{code, message}`，避免暴露内部错误对象。
+
+#### Worker、Pull 与 V2 连接代次
+- Node.js Worker transport 增加连接代次和旧响应保护；Worker 启动、运行中异常或熔断时回退本地 transport，旧连接结果不会污染新连接。
+- Transport、Pull gate、ACK 和后台同步默认超时统一放宽到约 35 秒；Forward gate key 将默认 `limit=50` 纳入归一化，V2 续页使用初始 cursor 构造 gate key。
+
+### 改进
+
+- Transport/RPC 日志补充本端 AID、对端 AID 和入站/出站方向，并为乱序响应保留原请求上下文。
+- 统一公开 RPC 错误信息，移除错误结果中的内部 `cause` 暴露。
+- SDK、锁文件、运行时版本和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.16`。
+
+### 测试
+
+- 增加协议 dispatcher、payload 隔离、错误映射、日志上下文和 transport 超时测试。
+- 扩展 Worker/native transport、Pull gate、V2 cursor、连接代次和 Node.js conformance 测试。
+- 增加 avatar 类型、Unicode 长度、默认生成及群 agent.md 透传测试。
+
+## 0.5.14 — 2026-09-11
+
+### 修复
+
+#### Pull gate watchdog 超时隔离
+- Pull watchdog 超时只使当前 Pull job 失败，不再通过全局失效状态影响 `message.send` 等非 Pull RPC。
+- 保留 background Pull 的全局 single-flight gate；超时但尚未真正结束的旧 Pull 继续占用 gate，后续 Pull 等待其 settle 后再执行。
+
+### 改进
+
+- SDK、锁文件、运行时版本和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.14`。
+
+### 测试
+
+- 增加 Pull 超时隔离、非 Pull RPC 投递和全局 single-flight gate 保持的单元测试。
+
+## 0.5.13 — 2026-09-08
+
+### 修复
+
+#### agent.md description 可选字段
+- `validateAgentMdDocument` 不再要求 frontmatter 必须包含 `description`，缺失或空字符串均可通过校验，与 `description` 的可选字段定义保持一致。
+- `description` 存在时仍必须是字符串，长度上限保持为 100 个 Unicode 码点；`aid`、`name`、`type`、`version` 的必填和格式校验不变。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 统一更新为 `0.5.13`。
+
+### 测试
+
+- 新增缺失、空字符串和非字符串 `description` 的 Schema 单元测试，并保留 Unicode 长度边界验证。
+
+## 0.5.12 — 2026-09-05
+
+### 新功能
+
+#### 定向群邀请
+- `GroupFacade` 新增 `inviteMember`、`listMyInvites`、`acceptInvite`、`rejectInvite` 和 `revokeInvite`，统一规范化群 ID、邀请 ID/AID 别名并接入签名 RPC。
+- `create({ members })` 在群创建完成后逐一发出定向邀请，支持 `member_type`，跳过自身和重复 AID；Node.js cross-SDK agent 增加邀请 RPC 与事件观测。
+- 邀请按群和目标 AID 聚合，在线重复、分页恢复和重连恢复只发布一次 `group.invite_received`；状态持久化，部分终态保留剩余 pending 邀请。
+
+### 修复
+
+#### Forward Pull、ACK 与游标
+- Forward 页完成后忽略页内空洞，按页最大序号和服务端 `contiguous_seq` 证明推进 seq-tracker，并在提交成功后 ACK；已观察到的 Push 上界未追平时继续翻页，即使 `has_more=false`。
+- 空页不直接用高位服务端 cursor 覆盖本地连续游标，待恢复 cursor 在下一次成功 Forward 时应用；持久化失败回滚 tracker 并禁止 ACK。
+- inline push 只有在包含非空 inline payload 时才推进连续游标并 ACK；非 inline push 只更新 `maxSeen` 并触发 Forward，不直接推进 A/T/H 或 ACK。Tail 仅维护窗口，History 不推进实时游标。
+
+#### Push、V2 与生命周期
+- P2P、群消息和群事件的 plain/V2 路径统一上述边界；缺少 sender IK/SPK 时保留阻塞页，不错误推进、ACK 或续页，密钥恢复后按 `pending_retry` 投递。
+- 当前设备自发消息在 Pull 中只标记序号，不重复发布；重复/迟到 inline ACK 保留 pending。群 changed、dissolved、自入群等非 inline Push 只记录上界并交由 Forward 处理。
+- Pull gate 识别 inline realtime 竞争任务，避免不必要挂起并继续按 namespace 正确串行化提交。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.12`。
+
+### 测试
+
+- 新增定向邀请 facade、聚合持久化、重连恢复、部分终态和 Node.js cross-SDK agent 测试。
+- 扩展 Forward 空洞、服务端 contiguous 证明、空页 cursor、持久化回滚、inline/non-inline Push、Tail/History 不推进、self-sync 去重及缺 IK/SPK 阻塞边界测试；跨域 runner 使用 `agentid.cn`/`agentid.pub`。
+
+## 0.5.11 — 2026-09-03
+
+### 新功能
+
+#### 消息来源与同步生命周期
+- P2P 消息、群消息、群事件、撤回和不可解密事件的应用 payload 新增 `source`，统一标识 `push`、`pull`、`inline_push` 或 `pending_retry`；`delivery.changed` 同步增加规范化 `source`。
+- 新增 `sync.started`、`sync.progress`、`sync.stopped` 生命周期事件。首次进入 Pull 时启动同步，每个 P2P/群 Pull page 完成后报告 namespace、页数、原始/已投递条数、`has_more`、`remaining`/估算剩余量，全部 Pull work 排空或中止时结束。
+- 同步事件继续经应用异步 FIFO 分发；并发 namespace 归入同一 run，Pull 失败、断线、关闭或身份代次重置以 `reason: "aborted"` 收口，不再把失败同步报告为正常排空。
+
+#### 连接后身份准入自愈
+- 每次 Gateway 连接成功后异步执行一次身份准入检查：普通 AID 缺少远端 agent.md 时复用本地内容或生成默认内容并补传。
+- 对当前 AID 作为群主的群逐个检查 group AID；缺少本地群证书/私钥时触发绑定并沿用绑定流程上传 group agent.md，已有群身份但远端缺少 group agent.md 时补传。检查失败只记录告警，不阻塞已建立的连接。
+
+### 修复
+
+#### Node.js Network Actor 容错
+- `worker_threads` Network Actor 和短 RPC worker 增加 `ready` 启动握手及约 2 秒超时；worker 不可创建、启动前报错/退出或未及时 ready 时熔断该 worker，并回退主线程本地 transport。
+- Actor 已连接后崩溃会清理 pending、异步发布连接错误和断线事件，后续连接使用本地 transport；无 `worker_threads` 或显式本地模式仍保持应用事件异步 FIFO，避免 handler 阻塞网络处理。
+
+#### V2 消息兼容与来源保持
+- Tail/Forward/History 能识别 V1 wrapper 内的 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` V2 envelope，并进入 V2 解密路径；群撤回在旧格式行中仍优先归一化为撤回事件。
+- ordered queue、sender IK 延迟恢复、inline realtime 和不可解密事件保持原始来源，避免补洞消息被误标为 push；群 Tail 同步进度仅由当前实例拥有的 cursor 产生。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.11`。
+
+### 测试
+
+- 新增 Network Actor 启动超时、禁用后本地回退、运行中崩溃与异步连接事件测试。
+- 扩展 `source`、`sync.*` 状态机、Pull 中止、分页进度、V1 wrapper 内 V2 envelope、连接后普通/群 agent.md 自愈及版本相关测试。
+
+## 0.5.10 — 2026-09-02
+
+### 新功能
+
+#### `delivery.changed` 投递汇总
+- 新增应用事件 `delivery.changed`，覆盖 `push`、`inline_push` 和全局 Pull 排空（`pull_drained`）三类触发来源；payload 按 namespace 聚合 `deliveredCount`。
+- P2P 统一归入 `p2p` namespace，群消息按 canonical group AID 归一化；多页/并发/重复/空 Pull、ordered queue 和 inline push 均折叠为稳定的单次通知。
+- continuation、sender IK 延迟恢复和 ordered drain 均计入全局 Pull 保留量；全部排空后才发布 `pull_drained`，连接或身份代次切换会隔离旧结果，原消息事件先于汇总事件。
+
+### 修复
+
+#### 事件分发与生命周期
+- 应用事件改由单客户端 FIFO 异步队列分发，handler 不再阻塞网络或内部处理；单个 handler 异常隔离，`close()` 会排空已接受事件。
+- 支持 handler 内重入 RPC、Pull 和 `close()`，避免自等待死锁；trace/meta observer、断线回调及解密/状态事件也经过异步分发边界。
+
+#### WebSocket、Pull 与消息幂等
+- 短 RPC 支持并发调用、`AbortSignal` 取消和超时；连接代次变化会丢弃旧事件并清理 pending，WebSocket 写入统一串行化。
+- 普通 Pull、P2P/群 V2 Pull、inline realtime、续拉和 ACK 提交纳入统一的 Pull 排空生命周期，旧代次不会继续发布、持久化或确认消息。
+- `message.send`/`group.send` preflight 自动生成 `messageId`，显式值保持不变；V2 重试、缓存 envelope 和底层 RPC 继续传递同一 ID，缺失响应 ID 时从请求回填。
+
+#### agent.md 与短 RPC 错误
+- 远端缺失的 agent.md 增加约 60 秒负缓存窗口，避免重复下载；短 RPC 错误保留服务端映射属性，便于调用方识别原始错误。
+
+### 改进
+
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.10`。
+
+### 测试
+
+- 新增 `delivery.changed` 单元和单域集成测试，覆盖 namespace 归一化、来源折叠、Pull 排空、ordered queue、inline push 和代次隔离。
+- 扩展异步 dispatcher、短 RPC 并发与取消、Pull 排空生命周期、messageId、agent.md 负缓存、错误映射及 observer/断线回调测试。
+
+## 0.5.9 — 2026-08-31
+
+### 安全性
+
+- agent.md 签名证书强制使用 ECDSA P-256，拒绝其他 EC 曲线，收紧本地校验与协议要求的一致性。
+- 身份切换和 discovery 使用代际检查；旧身份迟到的 discovery 结果不得回写新身份的 Gateway 候选或 token metadata。
+
+### 修复
+
+#### AID 注册、agent.md 与群身份
+- `AIDStore.register()` 在 AID、证书和私钥已成功落盘后，不再因默认 agent.md 上传返回失败而把整个注册报告为失败，避免重试时命中已注册冲突。
+- agent.md 自动恢复优先上传本地自定义内容，不再用默认模板覆盖；恢复后若仍收到同一 `-32003`，按 `0/50/100/200ms` 短退避重试原 RPC。
+- 命名群创建、绑定、续期和群主转移完成分别使用 `create:<group_name>`、`bind:<group_id>`、`renew:<group_id>`、`complete:<group_id>` 暂存待用密钥。RPC 前先落盘，失败重试复用同一密钥，身份导入及 group agent.md 上传完成后再清理；绑定流程兼容旧裸 `group_id` 槽位。
+- 恢复 `groupName` 到 `group_name` 的兼容映射；`GroupFacade` 未提供 `aidStore` 时保留直接 RPC 行为。`group.v2.confirm_state` 同时补传 `group_id`。
+
+#### Pull gate、消息窗口与生命周期
+- Pull 去重键纳入窗口 mode、cursor、force、limit 及外部 group cursor 参数；只有完整请求相同的 Pull 才会合并。
+- watchdog 超时后等待旧 Pull 真正 settle 再放行后续任务；close/disconnect 会失效在途 Pull、停止 watchdog、等待旧任务结束后保存 tracker，旧身份结果不能继续发布、落盘或 ACK。
+- unread hint、Tail 后补洞及实时窗口按目标上界计算 Forward 页数；plain Forward ACK 同时识别标量 `cursor` 和 `cursor.current_seq`。
+- V2 Forward 缺少 sender IK/SPK 时不提交本页最大序号、不发送 ACK，也不继续后续页，保留服务端消息供密钥恢复后重拉。
+- Auth 短 RPC 支持 `AbortSignal`；关闭、断连和身份切换可取消在途 WebSocket、HTTP discovery 与 DNS fallback 请求。
+
+### 改进
+
+- 顶层导出 `CompleteGroupTransferOptions`。
+- SDK 包、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 及相关测试期望统一更新为 `0.5.9`。
+
+### 测试
+
+- 扩展 P-256、注册部分成功、自定义 agent.md 恢复、群身份 pending key、facade 兼容和 `confirm_state` 参数测试。
+- 扩展 Pull 完整键、watchdog settle/失效、生命周期取消、多页 Forward、ACK cursor、缺 IK/SPK 不推进游标及类型导出测试。
+
+## 0.5.8 — 2026-08-30
+
+### 新功能
+
+#### AID 注册与 agent.md
+- `AIDStore.register()` 默认生成符合 schema 的 `agent.md`（`aid`、`type: "agent"` 等字段），使用对应 AID 签名并上传；`uploadAgentMd()` 仍可按需显式替换内容，也支持由另一个本地 uploader AID 认证代传。
+- 增加 agent.md 的严格 frontmatter、UTF-8/Base64、大小、证书有效期、证书指纹、公钥指纹和签名校验；校验失败不会覆盖已有内容或可信缓存。
+- 新版本连接能力声明 `agent_md_validation_v1`；收到缺少 agent.md 的 `-32003` 时自动生成、签名、上传并重试原 RPC。恢复只针对当前 AID，群 agent.md 恢复只由持有 group AID 私钥的群主执行。
+
+#### 群身份与 group agent.md
+- 命名群的 `createGroup()` 在 `group.create` 时携带新生成的 group AID 公钥和曲线，并要求服务端返回匹配的 group AID 证书；匿名群先创建，再按原始 `groupId` 绑定证书并导入本地 group AID。
+- `bindGroupAid()`、`renewGroupAid()` 和群主转移完成流程校验证书、公钥和用途，并自动上传 `type: "group"` 的 group agent.md；内容由 group AID 签名，群主 AID 负责认证上传。
+- group agent.md 可以事后上传，但在上传有效证书和 agent.md 前，群管理、群消息、`group.fs` 等后续群 RPC 继续受 Gateway 限制；历史群缺证书或缺 group agent.md 的自动修复仅允许群主执行。
+
+### 安全性
+
+- Gateway 在 client-vs-gateway RPC 入口校验客户端 agent.md、普通 AID 证书、group AID 证书及 group agent.md；`group.create`、`group.bindGroupAid`、`group.renewGroupAid` 等建群/绑定例外保留必要的恢复路径。
+- 上述准入只对 connect 协商声明 `agent_md_validation_v1` 的新 SDK 生效，未声明能力的旧 SDK 保持原有行为；Gateway 同时收紧 AID type、group namespace、RPC 目标和路由边界校验。
+- agent.md、证书和身份解析采用带 TTL 的正/负缓存，支持并发请求合并、容量上限及 CA 写入、agent.md 上传和相关事件触发的失效；代际校验防止过期查询回写缓存。
+
+### 修复
+
+#### Pull gate 与未读提示
+- `AUNClient` 统一使用一个 pull gate 和队列，前台 pull 优先于后台 pull，二者共享 namespace 去重；P2P 作为一个 namespace，每个 group 独立 namespace，后台请求不旁路也不丢弃。
+- pull 生命周期纳入 `idle`、`pulling`、`processing` 等状态和专用 watchdog；从拉取开始计时，约 3 秒超时即复位并继续队列，应用触发和新 push 会主动唤醒状态机。续拉在响应处理完成后重新入队并置于队尾。
+- `client.online` 时服务端为 P2P 及存在未读消息或事件的群发送 unread hint；SDK 每条 hint 转换为一次 background forward pull，按 namespace 去重。
+
+#### V2 消息窗口与游标
+- Forward 页忽略页内空洞并推进到 pulled page 最大 seq；先完成解密/发布，再一次性提交本页连续游标并发送 ACK 或 piggyback ACK。缺少 SPK/IK 时异步 bootstrap，不阻塞页处理；有密钥但解密失败时发布结构化失败事件后再推进游标。
+- 修正 P2P/群 V2 的 1DH/3DH、IK/SPK bootstrap、self-sync、forward cursor/ACK、重叠页去重及跨页有序投递；服务端 ACK 水位不足时保留待确认状态并在后续 pull 重试。
+- Message/Group thought 存储与响应结构统一，并增加响应预算/大小限制；Go `CollabActionResult` 兼容 `removed` 布尔值和整数格式。
+
+#### Gateway 与服务连接可靠性
+- 加固 service attach、连接替换、关闭码、协议错误预算、超时以及 reader/close 竞态；Python/Go 服务端行为和合同测试保持一致。
+- nameservice agent.md upsert、上传验证及数据库/快照兼容性同步修正；SDK 测试器使用阿里云 PyPI 镜像缓解下载超时。
+
+### 改进
+
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 更新为 `0.5.8`。
+- 低层 agent.md 上传能力继续由 `AIDStore` 提供，`AUNClient` 通过高层注册、建群和恢复流程编排；agent.md 替换仍保留为可选、按需操作。
+
+### 测试
+
+- 新增 AID 类型和 Gateway 路由准入的单元、集成、E2E 及跨 SDK 测试，覆盖新旧能力声明、证书/agent.md 缺失恢复、群主权限和缓存失效。
+- 扩展 agent.md、群身份绑定/续期、group.fs、V2 E2EE、pull gate 状态机、unread hint、游标/ACK、thought 响应预算和服务连接合同测试。
+
+## 0.5.7 — 2026-08-20
+
+### 新功能
+
+#### 首次连接自动重试
+- `connect()` 在首次 discovery、认证或 Gateway WebSocket 建连遇到可重试的瞬时错误时，进入与断线重连一致的指数退避生命周期；每轮重新执行完整 discovery/认证并使用最新凭据。
+- 认证、权限、参数和状态类永久错误仍立即返回，不创建后台重连任务。
+
+#### Mail facade 与当前令牌 API
+- 新增 `client.mail` / `MailFacade`，提供 `send()`、`get()`、`list()`、`delete()`、`move()`、`mark()`、`search()`、`getAttachment()`、`getQuota()`、`health()` 和 `status()`；`mail.send` 按非幂等 RPC 使用 35 秒超时。
+- 新增 `getAccessToken()`，同步读取后台刷新任务维护的最新 access token，供应用在每次外部 HTTP 数据面请求前取用；getter 本身不发起认证、刷新或网络请求。
+
+### 修复
+
+- 引入重连代际所有权；显式 `connect()` / `disconnect()` / `close()` 可终止旧重连代，旧任务不能清理或覆盖新连接，事件回调内触发生命周期操作也不会自锁。
+- 收口群 ID 语义：`g-` 不再具有特殊含义，所有群 base 统一按 4–64 字符规则校验；移除 `base@issuer` 兼容输入，仅保留 `group.{issuer}/{base}`、`base.issuer` 和本域短格式。
+- `stream/created` 和 `stream/closed` 内部事件重新发布给公共订阅者。
+- Group tail/history 遇到缺失 payload 的不完整 V1 行时采用有界跳过或失败语义，避免阻断后续同步。
+
+### 改进
+
+- SDK 包版本、锁文件版本和运行时 `VERSION` 更新为 `0.5.7`。
+
+### 测试
+
+- 新增首连认证/建连失败、永久错误、重连代际取消、事件回调重入、最新 token getter 和 Mail facade 单元测试。
+- 扩展群 ID 校验、跨域 Group FS、群消息窗口、V2 E2EE 和 replay guard 集成测试。
+
+## 0.5.6 — 2026-08-13
+
+### 新功能
+
+#### V2 消息窗口与实时推送
+- 完成 `tail` / `forward` / `history` 消息窗口处理、seq 状态持久化和 pull gate 调度，统一 P2P 与群消息的补洞、确认和有序投递行为。
+- 连接认证时声明 `inline_realtime_payload_v1`；实时事件优先使用内联消息载荷，离线或不完整事件继续通过 pull 回退，保留可靠性。
+- 对齐 Message/Group self-sync 与 bootstrap 契约，补齐多设备同步和前向保密状态处理。
+
+#### 群消息提及过滤
+- 新增 `mention_mode` 归一化与投递过滤，兼容 `disabled`、`mention-only` 及历史 `mention_only` 表示。
+
+### 安全性
+
+- `lookupPeer()` 在内存 peer cache 未命中或指纹不匹配时自动回源获取证书；支持按签名指纹加载历史证书，并在写入 peer cache 前完成证书链/身份校验。
+- `group.index` 和 `agent.md` 在下载或更新提交缓存前验签；rules、announcement、join requirements 等索引化 settings 逐项校验已签名索引中的 ETag。签名者权限、摘要或内容校验失败时不落盘，也不参与业务读取；已验证缓存的普通读取不重复验签。
+- 修复跨域 Storage 下载携带错误 bearer、Gateway 候选故障转移及连接/重连竞态问题。
+
+### 改进
+
+- 收口短 RPC、challenge/response、前置帧及 transport 运行时可靠性；后台补洞/ack 不再挤占前台 RPC。
+- 扩展跨 SDK agent、runner 与 trace 诊断，覆盖消息窗口和 inline realtime 场景；Node.js SDK 本版本未新增离线 Push facade。
+- 文件型 keystore 删除 `.seed` 自动迁移和 `.seed.migrated.*` 自动回退；保留显式 `changeSeed(oldSeed, newSeed)`，显式迁移成功后才归档旧 `.seed`。
+- SDK 包版本和运行时 `VERSION` 更新为 `0.5.6`。
+
+### 测试
+
+- 新增消息窗口、inline realtime push、mention mode、self-sync/bootstrap、transport/connect race、peer identity、group index 和 `agent.md` 单元/集成测试。
+- 扩展 cross-SDK contract vectors 与 runner，覆盖签名验签、缓存提交边界、inline pull 回退和窗口状态一致性。
+
+## 0.5.5 — 2026-07-14
 
 ### 维护