@agentunion/fastaun-browser 0.4.9 → 0.4.11

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

@@ -6,11 +6,12 @@
 
 - [AIDStore](#aidstore)
 - [AID](#aid)
-- [AUNClient](#aunclient)
-- [事件](#事件)
-- [E2EE 高级 API](#e2ee-高级-api)
-- [RPC 方法参考](#rpc-方法参考)
-- [Stream 使用指南](#stream-使用指南)
+- [AUNClient](#aunclient)
+- [事件](#事件)
+- [ServiceProxyClient](#serviceproxyclient)
+- [E2EE 高级 API](#e2ee-高级-api)
+- [RPC 方法参考](#rpc-方法参考)
+- [Stream 使用指南](#stream-使用指南)
 
 > **多语言命名约定**：Python 使用 `snake_case`（如 `aun_path`、`download_agent_md`），TS/JS 使用 `camelCase`（如 `aunPath`、`downloadAgentMd`），Go 使用 `PascalCase` 公开方法（如 `Load`、`Register`）。本手册表格中各列对应各语言的实际命名。
 
@@ -238,16 +239,51 @@ result = await client.call("message.send", {
 })
 ```
 
-常用 meta RPC 直接透传：
-
-```python
-await client.call("meta.ping", {})
-await client.call("meta.status", {})
-await client.call("meta.trust_roots", {})
-```
-
-### protected_headers
-
+常用 meta RPC 直接透传：
+
+```python
+await client.call("meta.ping", {})
+await client.call("meta.status", {})
+await client.call("meta.trust_roots", {})
+```
+
+### Notify
+
+`notify()` 发送轻量在线通知，底层是 JSON-RPC Notification，无 `id`，不进入离线存储、seq、pull 或 ack。
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
+| `notify(method, params=None, *, to=None, group_id=None, device_id=None, slot_id=None, ttl_ms=None)` | `notify(method, params?, options?)` | `Notify(ctx, method, params, NotifyOptions{...})` | 发送在线轻量通知 |
+
+常见用法：
+
+```python
+await client.notify("notification/client.activity", {"state": "idle"})
+await client.notify("event/app.typing", {"thread_id": "t1"}, to="bob.agentid.pub", ttl_ms=5000)
+await client.notify("event/app.presence", {"state": "active"}, group_id="group.agentid.pub/123")
+```
+
+路由选项：
+
+| 选项 | 说明 |
+|------|------|
+| `to` / `To` | 目标 AID；可同域或跨域 |
+| `group_id` / `groupId` / `GroupID` | 目标群；与 `to` 互斥 |
+| `device_id` / `deviceId` / `DeviceID` | 限定目标 AID 的在线设备；必须配合 `to` |
+| `slot_id` / `slotId` / `SlotID` | 限定目标设备的在线 slot；必须配合 `device_id` |
+| `ttl_ms` / `ttlMs` / `TTLMS` | `0..60000`，只控制在线投递过期，不表示离线缓存 |
+
+约束：
+
+- 未指定 `to` / `group_id` 时，`method` 必须以 `notification/` 开头，表示直发 Gateway 的协议级通知。
+- 指定 `to` 或 `group_id` 时，`method` 必须是 `event/app.*`，接收端通过 `client.on("app.xxx", handler)` 订阅。
+- 跨域 AID notify 已支持 federation 在线转发，但仍是 best-effort；目标离线或 federation 不可用时丢弃。
+- 可靠、敏感或需要审计的业务事件应继续使用 `message.send` / `group.send`。
+
+详细语义见 [Notify通知方案.md](Notify通知方案.md)。
+
+### protected_headers
+
 ```python
 client = AUNClient(aid)
 client.set_protected_headers({"sdk": "python", "trace": "abc"})
@@ -275,13 +311,62 @@ headers = client.get_protected_headers()
 - 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
 - SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
 - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
-
----
-
-## 事件
-
-```python
-sub = client.on("message.received", handler)
+
+---
+
+## ServiceProxyClient
+
+Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
+
+```python
+from aun_core.service_proxy import ServiceProxyClient
+
+proxy_client = ServiceProxyClient(
+    provider_aid="alice.agentid.pub",
+    aun_client=client,
+)
+proxy_client.register_service(
+    "fileshare",
+    "http://127.0.0.1:8080",
+    visibility="public",
+)
+await proxy_client.serve_forever()
+```
+
+proxy-server 连接地址不能由应用外部传入或配置。`ServiceProxyClient` 会先读取 provider AID 本地 SQLite metadata 中 1 小时 TTL 的 `service_proxy_discovery` 缓存；缓存缺失或过期时，按协议查询 `https://{provider_aid}/.well-known/aun-proxy`，失败后回退 `https://proxy.{issuer}/.well-known/aun-proxy`，并使用返回的 `ws_url` 建立隧道。
+
+关键 API：
+
+| Python | 说明 |
+|--------|------|
+| `register_service(service_name, endpoint, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
+| `unregister_service(service_name)` | 注销本地服务 |
+| `list_service_summaries()` | 获取可上报到 Gateway 和 proxy-server 的服务摘要 |
+| `register_services_with_gateway()` | 显式调用 Gateway `proxy.register_services` |
+| `unregister_services_from_gateway(service_names=None)` | 显式调用 Gateway `proxy.unregister_services` |
+| `list_gateway_services()` | 显式调用 Gateway `proxy.list_services` |
+| `register_services_with_proxy_server(ws)` | 通过已认证 proxy-server 隧道发送 `register_services` |
+| `discover_proxy_server(force_refresh=False)` | 通过缓存 / well-known 发现 proxy-server |
+| `connect_once()` | 建立一次 proxy-server 隧道并完成认证、数据面注册和可选心跳 |
+| `serve_once()` | 处理有限数量的 proxy-server 转发请求 |
+| `serve_forever(connection_mode="persistent")` | 持续提供 Service Proxy 服务；支持 persistent / on_demand |
+
+自动注册顺序：
+
+- `connect_once()`、`serve_once()`、`serve_forever()` 在存在 `aun_client.call()` 时，会先向 Gateway 调用 `proxy.register_services`。
+- 建立 proxy-server 隧道前，SDK 必须通过缓存 / `/.well-known/aun-proxy` 发现得到 `ws_url`；不得由应用传入或配置 proxy-server 地址。
+- proxy-server 隧道使用 `Authorization: Bearer <access_token>` 鉴权；SDK 优先复用 cached token，缺失或过期时通过 `aun_client.authenticate()` 向 Gateway 完成登录刷新。
+- 每次 proxy-server 隧道认证成功后，都会立即向 proxy-server 发送 `register_services` 隧道消息。
+- 服务列表与连接绑定；断开 Gateway 长连接或 proxy-server 隧道后，相应注册立即失效。
+
+详细控制面 RPC、隧道消息和路由语义见 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md)。
+
+---
+
+## 事件
+
+```python
+sub = client.on("message.received", handler)
 client.off("message.received", handler)
 sub.unsubscribe()
 ```
@@ -324,12 +409,13 @@ 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-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` |
-
----
+| 群组 | [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` |
+
+---
 
 ## Stream 使用指南
 

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

@@ -67,6 +67,7 @@
 | 方法 | 说明 |
 |------|------|
 | [group.send](#groupsend) | 发送群消息 |
+| [group.recall](#grouprecall) | 撤回群消息 |
 | [group.thought.put](#groupthoughtput) | 写入某个群上下文的思考内容 |
 | [group.thought.get](#groupthoughtget) | 获取某个群上下文的思考内容 |
 | [group.pull](#grouppull) | 增量拉取消息 |
@@ -120,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) | 更新资源元数据 |
@@ -1173,6 +1184,59 @@ result = await client.call("group.thought.get", {
 {"cursor": 42}
 ```
 
+### group.recall
+
+撤回群消息。仅**原发送者**可撤回自己的消息，受时间窗口限制（默认 **120 秒**，由群服务配置 `recall_window_seconds` 控制，`0` 表示不限制）。管理员撤回（`group_admin_recall_enabled`）默认关闭，本期不实现。
+
+**双 tombstone 机制**：群消息使用 per-group 全局 `message_seq`（V1/V2 共享同一空间），直接删除原消息会让"还没拉到原消息"的客户端遇到永久 seq 空洞。因此撤回写入两条 tombstone：
+
+- **原 seq 占位 tombstone**：占住被撤消息原来的 seq。V1 把原 `group_messages` 行 `message_type` 改为 `group.message_recalled` 并清空正文；V2 删除 `v2_group_messages` 密文体与所有 `v2_group_wraps`，再在 `group_messages` 插入同 `original_seq` 的明文 tombstone 顶替。服务对象是**还没读到原消息**的客户端——拉到该 seq 看到 tombstone，而非空洞。
+- **新 seq 通知 tombstone**：分配一个新的 `message_seq`，通知**已经读过原消息**（游标已越过 `original_seq`）的客户端"这条消息被撤回了"。
+
+同时写一条 `group_events`（`event_type = group.message_recalled`）用于事件流审计，并在事务提交后推送 `event/group.message_recalled`（见下）。撤回真相记录在 `group_message_recalls` 表，`(group_id, original_message_id)` 与 `(group_id, original_seq)` 双唯一键防止重复撤回。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
+| `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
+
+**响应**：
+
+```json
+{
+    "success": true,
+    "accepted": ["gm-aaa", "gm-bbb"],
+    "recalled": ["gm-aaa"],
+    "errors": [
+        {"message_id": "gm-bbb", "error": "not_sender"}
+    ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | 整体是否受理 |
+| `accepted` | string[] | 通过时间窗口前置过滤、进入撤回事务的消息 ID |
+| `recalled` | string[] | DB 真实撤回成功的消息 ID（避免并发撤回误通知）|
+| `errors` | array | 逐条错误：`{message_id, error}` |
+
+**逐条错误码**：
+
+| error | 说明 |
+|-------|------|
+| `not_found` | 消息不存在 |
+| `not_sender` | 操作者不是原发送者 |
+| `already_recalled` | 消息已被撤回（命中唯一键 / 占位 tombstone 已存在）|
+| `expired` | 超过撤回时间窗口 |
+| `group_inactive` | 群组非 active 状态（suspended / dissolved）|
+
+**SDK 行为**：SDK 把 pull / push 收到的撤回 tombstone（占位与通知）归一化为 `group.message_recalled` 应用事件，**不**作为普通 `group.message_created` 交付；tombstone 仍占 seq，正常推进 SeqTracker 与 ack。SDK 按 `(group_id, message_ids)` 去重，因此即使同时收到在线 push 事件、占位 tombstone、通知 tombstone，应用层也**只回调一次**。去重键**不含 `recalled_at`**：占位 tombstone、通知 tombstone 与在线 push 三条通道对同一次撤回可能携带不同来源的时间戳（push 在事务提交后重取），若纳入 `recalled_at` 会使去重失效、导致重复回调；一条消息只能被撤回一次（服务端 `group_message_recalls` 唯一键保证），`(group_id, message_ids)` 已能唯一标识一次撤回。
+
+> 所有语言 SDK 统一通过 `client.call("group.recall", {...})` 调用，不提供独立的便捷方法名。
+
 ---
 
 ## 公告与规则
@@ -1304,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
 
 查看资源详情。
@@ -1431,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"`）。
 
@@ -1781,7 +1961,8 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 {
     "module_id": "group",
     "action": "member_added",
-    "group_id": "g-abc123.agentid.pub"
+    "group_id": "g-abc123.agentid.pub",
+    "event_seq": 42
 }
 ```
 
@@ -1790,9 +1971,21 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 | `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 | 说明 |
@@ -1874,6 +2067,49 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
 
 SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
 
+### 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",
+    "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 列表** |
+| `target_message_seqs` | integer[] | 被撤回的原消息 seq 列表 |
+| `sender_aid` | string | 原消息发送方 |
+| `recalled_by` | string | 撤回操作者 |
+| `recalled_at` | integer | 撤回时间戳（毫秒）|
+| `reason` | string | 可选撤回理由 |
+
+跨域成员通过 federation forward 转发（`group.message_recalled` 在跨域转发白名单内），路径与 `group.message_created` 一致。
+
+**订阅**：
+
+```python
+client.on("group.message_recalled", lambda ev: print("recalled:", ev["message_ids"]))
+```
+
 ---
 
 ## 错误码