@agentunion/fastaun-browser 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -6,6 +6,56 @@
 
 ---
 
+## 0.4.12 — 2026-06-08
+
+### 新功能
+- **应用层事件信封（envelope）**：`message.*` 与 `group.changed` 事件发布给应用层时注入 `envelope` 字段，聚合 `message_id`/`seq`/`from`/`to`/`group_id`/`action` 等元数据；顶层别名字段在兼容期保留，计划于 `0.5.*` 移除，请改用 `envelope.*` 访问（四语言对齐）
+- **撤回事件携带 message_id 与自身信封**：`message.recalled` / `group.message_recalled` 通知补全 `message_id` 字段并继承原消息的信封键（四语言对齐）
+
+### 修复
+- **入群首个事件被旧序号阻塞**：`isSelfJoinGroupChanged` 识别自己入群后，将本地 `group_event` seq 基线对齐到 `eventSeq-1`，避免被入群前不可见事件挡住（四语言对齐）
+- **过期 token 重连死循环**：重连前同步 `_identity` 中的 token 状态到 `_sessionParams`，过期或缺失则清空以触发两阶段重新登录，避免反复用旧 token 触发 4001（四语言对齐）
+- **Service Proxy 持久隧道重连**：新增指数退避（上限 60s，成功后重置）；`AuthError` 触发 `_authenticateForAccessToken` 重新登录后再重连（四语言对齐）
+- **protected_headers 参数兼容**：`mergeInstanceProtectedHeaders` 同时识别 `protected_headers` 与 `headers` 别名
+
+### 测试
+- `自己入群首个 event_seq>1 不应被入群前不可见事件阻塞`
+- `pull 缺失中间 event_seq 时视为永久空洞，不阻塞已拿到的群事件发布`
+- `publishAppEvent 为群事件注入 envelope 并保留顶层兼容字段`
+- `撤回事件发布给应用层时带撤回通知自身 envelope`
+
+---
+
+## 0.4.11 — 2026-06-08
+
+### 新功能
+- **Storage 目录树与扩展操作**：`storage.*` 新增 15 个存储操作方法（含 `create_folder`/`rename_folder`/`move_object`/`batch_delete` 等），加入签名集合和非幂等集合（四语言+服务端对齐）
+- **group.resources 树形资源系统**：新增 11 个资源管理方法，加入签名和非幂等集合；支持跨域访问票据（四语言+服务端对齐）
+- **group.changed 事件保序去重**：新增 `handleGroupChangedEventSeq` 支持 event_seq 追踪和有序消息队列，空洞先到时缓存补洞；新增 `_isEventSignatureVerified()` 区分 pending 不标记已验签（四语言对齐）
+- **V2 E2EE 注册并发保护**：SPK 注册改用 `_registeringPromise` 缓存并发请求，多并发调用时等待同一 Promise（四语言对齐）
+
+### 修复
+- **IndexedDB 事务原子性**：`addSPK` 改用单事务处理原始记录和别名，避免独立事务导致一致性问题
+- **SPK 销毁顺序**：`_doAutoDestroy` 中先删设备级密钥再删存储级密钥
+- **sdk_version 拼写**：`sdk_vesion` → `sdk_version`
+- **V2 并发冲突检测**：检查对端操作的 `inflightSet`，防止 SPK 注册与轮换并发冲突
+- **storage/group.resources 签名和幂等性补全**：补全写操作方法进入签名集合与非幂等集合（四语言对齐）
+
+### 优化
+- **群事件处理流程重构**：`group.changed` 事件分发逻辑从 `client.ts` 迁移到 `delivery.ts`，支持按 event_seq 保序发布；新增 `publishOrderedQueueItem()` / `publishOrderedGroupChanged()`
+- **群组解散清理**：解散事件处理改为异步 `drainOrderedMessages`，保证 seq 追踪一致性
+- **群事件自动 ack**：`handleGroupChangedEventSeq` 无需补洞时直接 ack event cursor
+- **错误日志补充**：V2Session SPK 销毁异常捕获并输出日志
+
+### 测试
+- 新增事件验签状态单元测试（pending 状态不标记已验签）
+- 新增消息乱序补洞保序测试（高序号 push 先到时 SDK 内部消费和应用层发布的保序去重）
+- 新增签名方法覆盖测试（storage 写操作和有副作用读操作进入非幂等集合）
+- 新增 RPC 管道非幂等超时测试（storage/resources 方法按非幂等长超时 35s 发送）
+- 修复 `handleGroupChangedEventSeq` 单元测试 async/await 标记和 ack cursor 验证
+
+---
+
 ## 0.4.10 — 2026-06-06
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,56 @@
 
 ---
 
+## 0.4.12 — 2026-06-08
+
+### 新功能
+- **应用层事件信封（envelope）**：`message.*` 与 `group.changed` 事件发布给应用层时注入 `envelope` 字段，聚合 `message_id`/`seq`/`from`/`to`/`group_id`/`action` 等元数据；顶层别名字段在兼容期保留，计划于 `0.5.*` 移除，请改用 `envelope.*` 访问（四语言对齐）
+- **撤回事件携带 message_id 与自身信封**：`message.recalled` / `group.message_recalled` 通知补全 `message_id` 字段并继承原消息的信封键（四语言对齐）
+
+### 修复
+- **入群首个事件被旧序号阻塞**：`isSelfJoinGroupChanged` 识别自己入群后，将本地 `group_event` seq 基线对齐到 `eventSeq-1`，避免被入群前不可见事件挡住（四语言对齐）
+- **过期 token 重连死循环**：重连前同步 `_identity` 中的 token 状态到 `_sessionParams`，过期或缺失则清空以触发两阶段重新登录，避免反复用旧 token 触发 4001（四语言对齐）
+- **Service Proxy 持久隧道重连**：新增指数退避（上限 60s，成功后重置）；`AuthError` 触发 `_authenticateForAccessToken` 重新登录后再重连（四语言对齐）
+- **protected_headers 参数兼容**：`mergeInstanceProtectedHeaders` 同时识别 `protected_headers` 与 `headers` 别名
+
+### 测试
+- `自己入群首个 event_seq>1 不应被入群前不可见事件阻塞`
+- `pull 缺失中间 event_seq 时视为永久空洞，不阻塞已拿到的群事件发布`
+- `publishAppEvent 为群事件注入 envelope 并保留顶层兼容字段`
+- `撤回事件发布给应用层时带撤回通知自身 envelope`
+
+---
+
+## 0.4.11 — 2026-06-08
+
+### 新功能
+- **Storage 目录树与扩展操作**：`storage.*` 新增 15 个存储操作方法（含 `create_folder`/`rename_folder`/`move_object`/`batch_delete` 等），加入签名集合和非幂等集合（四语言+服务端对齐）
+- **group.resources 树形资源系统**：新增 11 个资源管理方法，加入签名和非幂等集合；支持跨域访问票据（四语言+服务端对齐）
+- **group.changed 事件保序去重**：新增 `handleGroupChangedEventSeq` 支持 event_seq 追踪和有序消息队列，空洞先到时缓存补洞；新增 `_isEventSignatureVerified()` 区分 pending 不标记已验签（四语言对齐）
+- **V2 E2EE 注册并发保护**：SPK 注册改用 `_registeringPromise` 缓存并发请求，多并发调用时等待同一 Promise（四语言对齐）
+
+### 修复
+- **IndexedDB 事务原子性**：`addSPK` 改用单事务处理原始记录和别名，避免独立事务导致一致性问题
+- **SPK 销毁顺序**：`_doAutoDestroy` 中先删设备级密钥再删存储级密钥
+- **sdk_version 拼写**：`sdk_vesion` → `sdk_version`
+- **V2 并发冲突检测**：检查对端操作的 `inflightSet`，防止 SPK 注册与轮换并发冲突
+- **storage/group.resources 签名和幂等性补全**：补全写操作方法进入签名集合与非幂等集合（四语言对齐）
+
+### 优化
+- **群事件处理流程重构**：`group.changed` 事件分发逻辑从 `client.ts` 迁移到 `delivery.ts`，支持按 event_seq 保序发布；新增 `publishOrderedQueueItem()` / `publishOrderedGroupChanged()`
+- **群组解散清理**：解散事件处理改为异步 `drainOrderedMessages`，保证 seq 追踪一致性
+- **群事件自动 ack**：`handleGroupChangedEventSeq` 无需补洞时直接 ack event cursor
+- **错误日志补充**：V2Session SPK 销毁异常捕获并输出日志
+
+### 测试
+- 新增事件验签状态单元测试（pending 状态不标记已验签）
+- 新增消息乱序补洞保序测试（高序号 push 先到时 SDK 内部消费和应用层发布的保序去重）
+- 新增签名方法覆盖测试（storage 写操作和有副作用读操作进入非幂等集合）
+- 新增 RPC 管道非幂等超时测试（storage/resources 方法按非幂等长超时 35s 发送）
+- 修复 `handleGroupChangedEventSeq` 单元测试 async/await 标记和 ack cursor 验证
+
+---
+
 ## 0.4.10 — 2026-06-06
 
 ### 新功能

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -56,14 +56,16 @@ SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
 
 `protected_headers` 会随 E2EE 信封发送，接收端可以读取，因此它提供完整性保护，不提供机密性保护。不要把访问令牌、私钥、隐私正文或其他只允许端到端可见的内容放入 `protected_headers`；这类内容应放进加密的 `payload`。
 
-发送方可以在以下 SDK 调用中传入 `protected_headers`，各 SDK 也兼容别名 `headers`：
+推荐通过 SDK 实例级 setter 设置稳定元数据，例如 `client.set_protected_headers(...)` / `client.setProtectedHeaders(...)` / `client.SetProtectedHeaders(...)`。发送方也可以在以下 SDK 调用中传入顶层 `protected_headers` 作为单次发送的高级覆盖；`headers` 仅作为兼容旧调用的别名，不推荐新代码使用：
 
 - `message.send`
 - `message.thought.put`
 - `group.send`
 - `group.thought.put`
 
-`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
+`payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
+
+`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
 
 示例：
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -409,8 +409,8 @@ sub.unsubscribe()
 | 领域 | 手册 | 关键方法 |
 |------|------|----------|
 | 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.ack` / `message.thought.*` |
-| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.invite` / `group.send` / `group.v2.*` |
-| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.upload` / `storage.download` / `storage.share` |
+| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.v2.*` / `group.resources.*` |
+| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.create_upload_session` / `storage.create_folder` / `storage.create_share_link` |
 | 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |
 | Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
 | Service Proxy | [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` |

package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -13,13 +13,13 @@ AUNError
 │   └── IdentityConflictError
 ├── PermissionError
 ├── ValidationError
+│   └── ClientSignatureError
 ├── NotFoundError
 ├── RateLimitError
 ├── VersionConflictError
 ├── StateError
 ├── SerializationError
 ├── SessionError
-├── ClientSignatureError
 ├── GroupError
 └── E2EEError
 ```
@@ -55,17 +55,20 @@ except AUNError as e:
 | 4040 / 404 | 资源不存在 | `NotFoundError` |
 | 4290 / 429 | 请求限流 | `RateLimitError` |
 | -32001 / -32003 | 认证失败 | `AuthError` |
-| -32004 | 权限不足 | `PermissionError` |
+| -32004 | RPC handler 超时（消息以 `"rpc handler timeout"` 开头） | `TimeoutError` |
+| -32004 | 权限不足（其他情况） | `PermissionError` |
 | -32008 | 资源不存在 | `NotFoundError` |
 | -32009 | 版本冲突 | `VersionConflictError` |
 | -32010 / -32011 / -32013 | 会话错误 | `SessionError` |
+| -32051 | 客户端签名验证失败 | `ClientSignatureError`（继承自 `ValidationError`） |
 | -32029 | 请求限流 | `RateLimitError` |
 | -32600 / -32601 / -32602 | JSON-RPC 参数错误 | `ValidationError` |
 | -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
 | 4090 | 身份冲突 | `IdentityConflictError` |
 | -32050 | 证书已吊销 | `CertificateRevokedError` |
-| -32051 | 客户端签名验证失败 | `ClientSignatureError` |
-| -33001 ~ -33009 | 群组错误 | `GroupError` 子类 |
+| -33001 | 群组不存在 | `GroupNotFoundError` |
+| -33002 / -33003 | 群组状态错误 | `GroupStateError` |
+| -33004 ~ -33009 | 其他群组错误 | `GroupError` 子类 |
 
 ---
 

package/_packed_docs/sdk/09-group-rpc-manual.md

@@ -121,6 +121,16 @@
 | 方法 | 说明 |
 |------|------|
 | [group.resources.put](#groupresourcesput) | 分享资源 |
+| [group.resources.create_folder](#groupresourcescreate_folder) | 创建资源目录 |
+| [group.resources.list_children](#groupresourceslist_children) | 列出目录子节点 |
+| [group.resources.rename](#groupresourcesrename) | 重命名资源节点 |
+| [group.resources.move](#groupresourcesmove) | 移动资源节点 |
+| [group.resources.mount_object](#groupresourcesmount_object) | 挂载 storage 对象为资源 |
+| [group.resources.request_mount_object](#groupresourcesrequest_mount_object) | 申请挂载 storage 对象 |
+| [group.resources.unmount](#groupresourcesunmount) | 取消挂载资源 |
+| [group.resources.resolve_path](#groupresourcesresolve_path) | 按路径解析资源 |
+| [group.resources.list_refs_by_storage](#groupresourceslist_refs_by_storage) | 按 storage 引用反查资源 |
+| [group.resources.cleanup_by_storage_ref](#groupresourcescleanup_by_storage_ref) | 清理失效 storage 引用 |
 | [group.resources.get](#groupresourcesget) | 查看资源 |
 | [group.resources.list](#groupresourceslist) | 列出资源 |
 | [group.resources.update](#groupresourcesupdate) | 更新资源元数据 |
@@ -979,7 +989,7 @@ await client.call("group.set_settings", {
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 
 ### Payload 参考约定
 
@@ -1039,7 +1049,7 @@ SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加
 | `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
 | `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `gt-*` |
 | `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；`context` 会被 SDK 复制进信封并单独验 `_auth` |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
 
 **SDK 调用示例**：
 
@@ -1358,6 +1368,122 @@ result = await client.call("group.thought.get", {
 
 > `created` 为 `true` 表示新建，`false` 表示更新已有资源。
 
+### group.resources.create_folder
+
+创建群资源目录。需要 **member 及以上**权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `path` / `resource_path` | string | 否 | 完整目录路径 |
+| `name` | string | 否 | 目录名；未提供完整路径时使用 |
+| `parent_resource_id` / `parent_path` | string | 否 | 父目录 |
+| `title` | string | 否 | 显示标题，默认目录名 |
+| `metadata` | object | 否 | 自定义元数据 |
+| `visibility` | string | 否 | `"members_only"` / `"public"` |
+| `tags` | array | 否 | 标签 |
+| `mkdirs` | boolean | 否 | 是否递归创建父目录 |
+| `sort_order` | integer | 否 | 排序值 |
+
+**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
+
+### group.resources.list_children
+
+列出某个资源目录下的直接子节点。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `resource_id` / `path` / `resource_path` | string | 否 | 父目录；不传表示根目录 |
+| `type` / `resource_type` | string | 否 | `"folder"` / `"file"` / `"link"` |
+| `include_status` | boolean | 否 | 是否附带 storage 状态 |
+| `page` / `offset` | integer | 否 | 分页位置 |
+| `size` / `limit` | integer | 否 | 每页数量 |
+| `sort_by` | string | 否 | 排序字段，默认 `sort_order` |
+| `order` | string | 否 | `"asc"` / `"desc"` |
+
+**响应**：`group_id`、`resource_id`、`path`、`items`、`total`、`count`、`page`、`size`、`offset`。
+
+### group.resources.rename
+
+重命名资源节点。需要资源创建者、storage owner、owner 或 admin 权限。
+
+**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`），`new_name`；可选 `title`、`expected_version`。
+
+**响应**：更新后的 `resource`。
+
+### group.resources.move
+
+移动资源节点。目录不能移动到自身或自身子目录。
+
+**参数**：`group_id`，资源选择器，目标父目录（`dst_parent_resource_id` / `dst_parent_path`），可选 `new_name` / `dst_name`、`expected_version`。
+
+**响应**：更新后的 `resource`。
+
+### group.resources.mount_object
+
+将 `storage.*` 对象挂载为群资源。需要 **owner/admin** 权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `storage_ref` | object | 是 | storage 引用，通常包含 `owner_aid`、`bucket`、`object_id` 或 `object_key` |
+| `path` / `resource_path` | string | 否 | 资源路径；不传时用 storage 文件名 |
+| `title` | string | 否 | 显示标题 |
+| `metadata` | object | 否 | 自定义元数据 |
+| `visibility` | string | 否 | `"members_only"` / `"public"` |
+| `tags` | array | 否 | 标签 |
+| `mkdirs` | boolean | 否 | 是否递归创建父目录，默认 `true` |
+| `conflict_policy` | string | 否 | `"reject"` / `"replace"` / `"keep_both"` |
+
+**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
+
+### group.resources.request_mount_object
+
+成员申请挂载自己的 storage 对象，进入待审批队列。语义等同 `group.resources.request_add`，但输入按挂载对象组织。
+
+**参数**：同 `group.resources.mount_object`，但不需要 owner/admin 权限。
+
+**响应**：`{ "group_id": "...", "request": { ... } }`。
+
+### group.resources.unmount
+
+取消挂载资源，等价于非递归 `group.resources.delete`。
+
+**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`）。
+
+**响应**：删除结果。
+
+### group.resources.resolve_path
+
+按路径解析资源节点。
+
+**参数**：`group_id`、`path` / `resource_path`；可选 `expected_type`。
+
+**响应**：`resource_id`、`resource_type`、`resource_path`、`path`、`status`、`resource`。
+
+### group.resources.list_refs_by_storage
+
+按 storage 引用反查群资源。传 `group_id` 时要求调用者是该群成员；不传 `group_id` 时要求调用者是 `owner_aid`。
+
+**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`include_missing`、`offset`、`limit` / `size`。
+
+**响应**：`items`、`total`、`count`、`limit`、`offset`，并回显 storage 选择器字段。
+
+### group.resources.cleanup_by_storage_ref
+
+清理指向已删除或失效 storage 对象的资源引用。传 `group_id` 时要求 owner/admin 或 storage owner；不传 `group_id` 时要求 storage owner。
+
+**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`mode`。
+
+**响应**：`affected_count` 和被影响的资源 `items`。
+
 ### group.resources.get
 
 查看资源详情。
@@ -1485,7 +1611,7 @@ result = await client.call("group.thought.get", {
 
 ### group.resources.direct_add
 
-Owner 直接添加资源（无需审批）。需要 **owner** 权限。
+Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限。
 
 **参数**：同 `group.resources.put`（`resource_type` 不能是 `"folder"`）。
 
@@ -1831,22 +1957,44 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 
 **Payload**：
 
-```json
-{
-    "module_id": "group",
-    "action": "member_added",
-    "group_id": "g-abc123.agentid.pub"
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `module_id` | string | 固定 `"group"` |
-| `action` | string | 变更类型（见下表） |
-| `group_id` | string | 群组 ID |
+```json
+{
+    "envelope": {
+        "module_id": "group",
+        "action": "member_added",
+        "group_id": "g-abc123.agentid.pub",
+        "event_seq": 42
+    },
+    "module_id": "group",
+    "action": "member_added",
+    "group_id": "g-abc123.agentid.pub",
+    "event_seq": 42
+}
+```
+
+SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `ev["envelope"]["action"]` 等路径访问。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 群事件信封，包含 `module_id`、`action`、`group_id`、`event_seq`、`event_type`、`actor_aid`、`created_at`、`device_id`、`slot_id` 等存在的字段 |
+| `module_id` | string | 固定 `"group"` |
+| `action` | string | 变更类型（见下表） |
+| `group_id` | string | 群组 ID |
+| `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
 | `request_id` | string | 可选，仅资源审批相关 action |
 | `resource_path` | string | 可选，仅资源相关 action |
 
+**保序去重（SDK 内部行为）**：
+
+服务端为每条 `group.changed` 事件分配 `event_seq`（按群 `group_event:{group_id}` 命名空间单调递增）。SDK 收到事件后：
+
+1. **去重**：`event_seq` ≤ 已连续消费序号，或已处理过该序号，则丢弃
+2. **保序**：事件入有序队列，按序号连续后才发布给应用层
+3. **补洞**：检测到序号空洞时，自动调用 `group.pull_events` 拉取缺失事件补齐
+4. **ack**：连续段推进后自动发送 `group.ack_events`（namespace `group_event:{group_id}`）
+
+不携带 `event_seq` 的旧格式事件直接发布，不参与保序（兼容旧服务端）。
+
 **action 取值**：
 
 | action | 说明 |
@@ -1926,37 +2074,73 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
 }
 ```
 
-SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
-
-### event/group.message_recalled
+SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
+
+**SDK 应用层回调形态**：
+
+```json
+{
+    "envelope": {
+        "group_id": "g-abc123.agentid.pub",
+        "seq": 42,
+        "message_id": "uuid",
+        "sender_aid": "alice.agentid.pub",
+        "message_type": "group.message",
+        "dispatch_mode": "broadcast"
+    },
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 42,
+    "message_id": "uuid",
+    "sender_aid": "alice.agentid.pub",
+    "message_type": "group.message",
+    "dispatch_mode": "broadcast",
+    "payload": {"type": "text", "text": "Hello"}
+}
+```
+
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `msg["envelope"]["message_id"]` 等路径访问。
+
+### event/group.message_recalled
 
 群消息撤回后推送给所有在线成员（与 pull 双 tombstone 兜底互补）。在线 push 是实时通道，双 tombstone 是离线 / 未读 / push 丢失时的可靠性兜底；两者最终一致，SDK 去重保证应用层只感知一次。
 
 **Payload**：
 
-```json
-{
-    "module_id": "group",
-    "group_id": "g-abc123.agentid.pub",
-    "seq": 43,
-    "message_id": "grm-uuid",
-    "message_ids": ["gm-aaa"],
-    "target_message_seqs": [42],
-    "sender_aid": "alice.agentid.pub",
+```json
+{
+    "envelope": {
+        "module_id": "group",
+        "group_id": "g-abc123.agentid.pub",
+        "seq": 43,
+        "message_id": "grm-uuid",
+        "sender_aid": "alice.agentid.pub"
+    },
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 43,
+    "message_id": "grm-uuid",
+    "tombstone_message_id": "grm-uuid",
+    "message_ids": ["gm-aaa"],
+    "target_message_seqs": [42],
+    "sender_aid": "alice.agentid.pub",
     "recalled_by": "alice.agentid.pub",
     "recalled_at": 1234567890000,
     "reason": "",
     "member_aids": ["bob.agentid.pub"]
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `module_id` | string | 固定 `"group"` |
-| `group_id` | string | 群组 ID |
-| `seq` | integer | 撤回通知 tombstone 的**新群消息 seq** |
-| `message_id` | string | 撤回通知 tombstone 自己的 message_id |
-| `message_ids` | string[] | 被撤回的**原消息 ID 列表** |
+}
+```
+
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `module_id`、`group_id`、`seq`、`message_id`、`sender_aid`、`device_id`、`slot_id` 等存在的字段 |
+| `module_id` | string | 固定 `"group"` |
+| `group_id` | string | 群组 ID |
+| `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
+| `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
+| `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
+| `message_ids` | string[] | 被撤回的**原消息 ID 列表** |
 | `target_message_seqs` | integer[] | 被撤回的原消息 seq 列表 |
 | `sender_aid` | string | 原消息发送方 |
 | `recalled_by` | string | 撤回操作者 |

package/_packed_docs/sdk/09-message-rpc-manual.md

@@ -78,7 +78,7 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
 | `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
-| `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
+| `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 
 > 连接级 `delivery_mode` 在 `auth.connect` 阶段声明，结构见 `02-WebSocket协议.md`。Python SDK 的 P2P 消息发送会沿用当前连接的 `delivery_mode`，应用层发送时无需重复指定。
 > `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
@@ -156,7 +156,7 @@ SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加
 | `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
 | `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `mt-*` |
 | `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；`context` 会被 SDK 复制进信封并单独验 `_auth` |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
 
 ### SDK 调用示例
 
@@ -510,20 +510,30 @@ result = await client.call("message.ack", {"seq": 150})
 
 ### Payload
 
-```json
-{
-    "message_id": "uuid-1",
-    "from": "alice.agentid.pub",
-    "to": "bob.agentid.pub",
+```json
+{
+    "envelope": {
+        "message_id": "uuid-1",
+        "from": "alice.agentid.pub",
+        "to": "bob.agentid.pub",
+        "seq": 42,
+        "timestamp": 1234567890000,
+        "encrypted": false
+    },
+    "message_id": "uuid-1",
+    "from": "alice.agentid.pub",
+    "to": "bob.agentid.pub",
     "seq": 42,
     "timestamp": 1234567890000,
     "payload": {"type": "text", "text": "Hello!"},
     "delivery_mode": "queue",
     "encrypted": false
-}
-```
-
-### 订阅
+}
+```
+
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `msg["envelope"]["seq"]` 等路径访问。
+
+### 订阅
 
 ```python
 client.on("message.received", lambda msg: print(msg["payload"]))
@@ -537,21 +547,35 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 
 ### Payload
 
-```json
-{
-    "from": "alice.agentid.pub",
-    "to": "bob.agentid.pub",
-    "message_ids": ["uuid-1", "uuid-2"],
-    "timestamp": 1234567890000
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `from` | string | 发送方（撤回者）AID |
-| `to` | string | 接收方 AID |
-| `message_ids` | array | 被撤回的消息 ID 列表 |
-| `timestamp` | integer | 服务端时间戳（毫秒） |
+```json
+{
+    "envelope": {
+        "message_id": "recall-uuid",
+        "from": "alice.agentid.pub",
+        "to": "bob.agentid.pub",
+        "seq": 43,
+        "timestamp": 1234567890000
+    },
+    "message_id": "recall-uuid",
+    "tombstone_message_id": "recall-uuid",
+    "from": "alice.agentid.pub",
+    "to": "bob.agentid.pub",
+    "message_ids": ["uuid-1", "uuid-2"],
+    "timestamp": 1234567890000
+}
+```
+
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示撤回 tombstone / 通知自身的信封，不是被撤回原消息的信封；被撤回的原消息继续通过 `message_ids` 表达。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `message_id`、`from`、`to`、`seq`、`timestamp`、`device_id`、`slot_id` 等存在的字段 |
+| `message_id` | string | 撤回 tombstone / 通知自身的 message_id |
+| `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
+| `from` | string | 发送方（撤回者）AID |
+| `to` | string | 接收方 AID |
+| `message_ids` | array | 被撤回的消息 ID 列表 |
+| `timestamp` | integer | 服务端时间戳（毫秒） |
 
 ### 订阅
 

package/_packed_docs/sdk/09-payload-reference.md

@@ -40,7 +40,7 @@
 | `to` | `message.send.params` | P2P 接收方 AID |
 | `group_id` | `group.send.params` 和群消息信封 | 群组 ID |
 | `context.type + context.id` | `message.thought.put/get.params` 和 `group.thought.put/get.params` | 思考内容 selector；必填，不要只放在 payload 内 |
-| `protected_headers` / `headers` | `message.send` / `message.thought.put` / `group.send` / `group.thought.put` 参数 | E2EE 信封元数据，类似 HTTP headers；SDK 验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
+| `protected_headers` / `headers` | `message.send` / `message.thought.put` / `group.send` / `group.thought.put` 参数 | E2EE 信封元数据，类似 HTTP headers；推荐 `protected_headers`，`headers` 仅为兼容别名；SDK 验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 | `from` / `sender_aid` | 服务端生成的消息信封 | 发送方身份 |
 | `message_id` / `seq` / `timestamp` / `created_at` | 服务端生成或发送参数 | 当前消息 ID、序号和服务端时间 |
 | `encrypted` / `delivery_mode` | 发送参数或连接上下文 | 加密和 P2P 投递语义 |