@agentunion/fastaun-browser 0.5.4 → 0.5.8

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

@@ -23,21 +23,22 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | [message.thought.put](#messagethoughtput) | 写入某个 P2P 上下文的思考内容 |
 | [message.thought.get](#messagethoughtget) | 读取某个 P2P 上下文的思考内容 |
 | [message.pull](#messagepull) | 增量拉取消息 |
+| [message.history](#messagehistory) | 向前只读翻页历史消息 |
 | [message.ack](#messageack) | 确认送达 |
 | [message.recall](#messagerecall) | 撤回消息 |
 | [message.query_online](#messagequery_online) | 批量查询在线状态 |
 
-### E2EE V2 辅助方法（SDK 内部使用）
-
-> 以下方法由 SDK E2EE 层自动调用，应用层通常无需直接使用。
-
-| 方法 | 说明 |
-|------|------|
-| message.v2.put_peer_pk | 注册/更新当前设备的 P2P SPK（`peer_device_prekey`） |
-| message.v2.bootstrap | 拉取对端活跃设备、设备 IK/SPK、audit recipients 与 wrap 策略 |
-| message.v2.group_bootstrap | Group 服务内部批量拉取成员设备 V2 公钥 |
-
-> 旧 `message.e2ee.*` prekey/replay guard RPC 只属于 legacy E2EE 信封兼容路径；当前 SDK 主路径不再直接使用它们。新实现应使用 V2 多设备 wrap，详见 [05-E2EE加密通信](05-E2EE加密通信.md) 和 [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)。
+### E2EE V2 辅助方法（SDK 内部使用）
+
+> 以下方法由 SDK E2EE 层自动调用，应用层通常无需直接使用。
+
+| 方法 | 说明 |
+|------|------|
+| message.v2.put_peer_pk | 注册/更新当前设备的 P2P SPK（`peer_device_prekey`） |
+| message.v2.bootstrap | 拉取对端活跃设备、设备 IK/SPK、audit recipients 与 wrap 策略 |
+| message.v2.group_bootstrap | Group 服务内部批量拉取成员设备 V2 公钥 |
+
+> 旧 `message.e2ee.*` prekey/replay guard RPC 只属于 legacy E2EE 信封兼容路径；当前 SDK 主路径不再直接使用它们。新实现应使用 V2 多设备 wrap，详见 [05-E2EE加密通信](05-E2EE加密通信.md) 和 [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)。
 
 ## 事件索引
 
@@ -75,11 +76,11 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 |------|------|------|--------|------|
 | `to` | string | 是 | — | 接收方 AID |
 | `payload` | object | 是 | — | 消息内容（任意 JSON 对象） |
-| `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
+| `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
 | `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
 | `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
-| `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`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-与可验证上下文) 的格式和校验规则。
@@ -97,17 +98,17 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
         "message_id": "550e8400-e29b-41d4-a716-446655440000",
         "seq": 42,
         "timestamp": 1234567890000,
-        "status": "delivered",
-        "delivery_mode": "fanout",
-        "envelope": {
-            "from": "alice.agentid.pub",
-            "to": "bob.agentid.pub",
-            "type": "text",
-            "timestamp": 1234567890000,
-            "encrypted": false,
-            "payload_type": "text"
-        },
-        "payload": {"type": "text", "text": "Hello!"}
+        "status": "delivered",
+        "delivery_mode": "fanout",
+        "envelope": {
+            "from": "alice.agentid.pub",
+            "to": "bob.agentid.pub",
+            "type": "text",
+            "timestamp": 1234567890000,
+            "encrypted": false,
+            "payload_type": "text"
+        },
+        "payload": {"type": "text", "text": "Hello!"}
     },
     "id": 1
 }
@@ -118,11 +119,11 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | `message_id` | string | 消息 ID |
 | `seq` | integer | 接收方收件箱序号 |
 | `timestamp` | integer | 服务端时间戳（毫秒） |
-| `status` | string | `"sent"` / `"delivered"` / `"duplicate"` |
-| `delivery_mode` | string | 最终生效的连接级投递语义：`fanout` 或 `queue` |
-| `envelope` | object | SDK 回填的发送结果信封，包含发送方、接收方、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
-| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
-| `cross_domain` | boolean | 仅跨域投递时出现，当前值为 `true` |
+| `status` | string | `"sent"` / `"delivered"` / `"duplicate"` |
+| `delivery_mode` | string | 最终生效的连接级投递语义：`fanout` 或 `queue` |
+| `envelope` | object | SDK 回填的发送结果信封，包含发送方、接收方、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
+| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
+| `cross_domain` | boolean | 仅跨域投递时出现，当前值为 `true` |
 | `target_issuer` | string | 仅跨域投递时出现，表示目标 issuer |
 
 > **duplicate 响应**：当 `message_id` 重复时，若服务端仍缓存首次结果，返回完整首次响应并附加 `"status": "duplicate"`；若缓存已过期，仅返回 `message_id`、`timestamp`、`status`，**不含** `seq` 和 `delivery_mode`。客户端收到 `"duplicate"` 状态时应视为幂等成功，无需重试。
@@ -153,22 +154,22 @@ result = await client.call("message.send", {
 
 写入当前发送者针对一个上下文的思考内容。它不是普通消息：不广播、不进 `message.pull`、不占用收件箱 `seq`，只通过 `message.thought.get` 主动读取。
 
-SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.p2p_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature` 和 AAD 生成；`client_signature` 按 Gateway 连接级身份语义携带。
+SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.p2p_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature` 和 AAD 生成；`client_signature` 按 Gateway 连接级身份语义携带。
 
-存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
+存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
 
 ### 参数
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `to` | string | 是 | P2P 会话另一方 AID，不能是群 `group_aid` |
+| `to` | string | 是 | P2P 会话另一方 AID，不能是群 `group_aid` |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
 | `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
 | `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
 | `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `mt-*` |
 | `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
 
 ### SDK 调用示例
 
@@ -187,9 +188,9 @@ await client.call("message.thought.put", {
     "to": "bob.agentid.pub",
     "context": {"type": "run", "id": "run-xxx"},
     "thought_id": "mt-...",
-    "type": "e2ee.p2p_encrypted",
-    "encrypted": true,
-    "payload": {"type": "e2ee.p2p_encrypted", "version": "v2", "...": "..."},
+    "type": "e2ee.p2p_encrypted",
+    "encrypted": true,
+    "payload": {"type": "e2ee.p2p_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -263,7 +264,7 @@ result = await client.call("message.thought.get", {
             "to": "alice.agentid.pub",
             "payload": {"type": "thought", "text": "需要补一个边界条件"},
             "created_at": 1234567890000,
-            "e2ee": {"version": "v2", "wrap_protocol": "3DH"}
+            "e2ee": {"version": "v2", "wrap_protocol": "3DH"}
         }
     ],
     "updated_at": 1234567890000
@@ -299,11 +300,11 @@ result = await client.call("message.thought.get", {
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | `after_seq` | integer | 否 | 0 | 拉取 seq > after_seq 的消息 |
-| `limit` | integer | 否 | 50 | 单次返回上限（最大 50；`pull_max_limit` 配置只能在 1-50 内进一步收紧） |
+| `limit` | integer | 否 | 50 | 单次返回上限（最大 50；`pull_max_limit` 配置只能在 1-50 内进一步收紧） |
 | `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
-| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
-
-> 四个 SDK 都会自动为 `message.pull` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
+| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
+
+> 四个 SDK 都会自动为 `message.pull` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
 
 ### 响应
 
@@ -343,6 +344,14 @@ result = await client.call("message.thought.get", {
 | `ephemeral_earliest_available_seq` | integer\|null | 临时缓冲中可用的最小 seq |
 | `ephemeral_dropped_count` | integer | 已被淘汰的临时消息数 |
 
+`message.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。Forward 页通过结构校验后，本地 A 按原始页最大 seq 推进。页内缺号视为服务端永久空号；单条解密失败通过 `message.undecryptable` 报告，不阻塞后续水位。Forward 仍支持 Piggy ACK：存在待提交 ACK 时，即使当前页非满页也会再拉一页并携带 ACK，空页后停止。
+
+`message.pull` 与 `message.history` 进入当前 `AUNClient` 的客户端级 Pull Gate。该 Gate 与 Group Message、Group Event Pull 共享，始终 single-inflight；相同请求 key 折叠并共享结果，不同 key 按前台 FIFO（Tail/History）优先于后台 FIFO（Forward/Gap Fill/Group Event）排队。不同 `AUNClient` 实例之间不共享 Gate，应用层无需自行实现并发控制。
+
+解密当前消息时若缺少 sender IK，SDK 会把同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；获取成功立即重试当前消息，失败或超时才进入 pending。该补救不改变 Forward 按原始页推进 A 的规则。
+
+SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布一次。A/T/H 是扫描水位，不记录应用是否已经收到回调；跨 Push、SDK 自动最新页同步和 Forward 页允许重复和乱序。全局去重与排序由应用业务仓库负责，不是 SDK 交付契约；应用必须按 `(namespace, message_id)` 幂等并按 `seq` 排序。SDK 进程内折叠仅作 best-effort 优化。History 只返回结果，不参与实时发布。
+
 ### 示例
 
 ```python
@@ -353,6 +362,36 @@ for msg in result["messages"]:
 
 ---
 
+## message.history
+
+向 seq 更小的方向只读翻页。History 不读取或修改实时 A/T/H，不推进 ACK，也不触发 `message.received`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `before_seq` | integer | 是 | — | 排他上界，只返回 `seq < before_seq` 的消息 |
+| `limit` | integer | 否 | 50 | 单页上限，最大 50 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `messages` | array | 页内按 seq 升序；解密失败项以结构化错误返回 |
+| `window_start_seq` | integer\|null | 本页最小边界；空页为 `null` |
+| `next_before_seq` | integer\|null | 下一页直接使用的排他上界 |
+| `has_older` | boolean | 是否仍有更早的可见消息 |
+| `retention_floor_seq` | integer | 已实际删除、不可恢复的 seq 下界 |
+| `earliest_available_seq` | integer\|null | 当前最早可拉取边界 |
+
+```python
+page = await client.message.history(before_seq=101, limit=50)
+while page.get("has_older"):
+    page = await client.message.history(before_seq=page["next_before_seq"], limit=50)
+```
+
+---
+
 ## message.ack
 
 确认已收到消息。推进接收方的 ack_seq 游标。
@@ -378,9 +417,9 @@ for msg in result["messages"]:
 |------|------|------|--------|------|
 | `seq` | integer | 是 | — | 确认 seq ≤ 此值的所有消息 |
 | `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
-| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
-
-> 四个 SDK 都会自动为 `message.ack` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
+| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
+
+> 四个 SDK 都会自动为 `message.ack` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
 
 ### 响应
 
@@ -520,41 +559,43 @@ result = await client.call("message.ack", {"seq": 150})
 
 收到新消息时推送。
 
+**实时推送优化**（0.5.6+）：当客户端在 `auth.connect` 时声明 `inline_realtime_payload_v1: true` 能力后，Gateway 会在事件中直接内联完整的消息载荷（`payload`、`envelope` 等），无需额外调用 `message.pull`。SDK 自动声明此能力，应用层无需关注。对于离线消息和历史消息，仍需通过 `message.pull` 拉取。
+
 ### Payload
 
-```json
-{
-    "envelope": {
-        "from": "alice.agentid.pub",
-        "to": "bob.agentid.pub",
-        "type": "text",
-        "timestamp": 1234567890000,
-        "encrypted": false
-    },
-    "message_id": "uuid-1",
-    "from": "alice.agentid.pub",
-    "to": "bob.agentid.pub",
+```json
+{
+    "envelope": {
+        "from": "alice.agentid.pub",
+        "to": "bob.agentid.pub",
+        "type": "text",
+        "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,
-    "proximity": {
-        "same_device": false,
-        "same_egress_ip": true,
-        "same_network": true,
-        "basis": "egress_ip",
-        "asserted_by": "gateway"
-    },
-    "same_device": false,
-    "same_egress_ip": true,
-    "same_network": true
-}
-```
-
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。`envelope.agent_md.sender` / `envelope.agent_md.group` 是 agent.md 云端版本提示，SDK 会自动观察并写入本地 `remote_etag`。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
-
-### 订阅
+    "delivery_mode": "queue",
+    "encrypted": false,
+    "proximity": {
+        "same_device": false,
+        "same_egress_ip": true,
+        "same_network": true,
+        "basis": "egress_ip",
+        "asserted_by": "gateway"
+    },
+    "same_device": false,
+    "same_egress_ip": true,
+    "same_network": true
+}
+```
+
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。`envelope.agent_md.sender` / `envelope.agent_md.group` 是 agent.md 云端版本提示，SDK 会自动观察并写入本地 `remote_etag`。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
+
+### 订阅
 
 ```python
 client.on("message.received", lambda msg: print(msg["payload"]))
@@ -568,35 +609,35 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 
 ### Payload
 
-```json
-{
-    "envelope": {
-        "from": "alice.agentid.pub",
-        "to": "bob.agentid.pub",
-        "type": "message.recalled",
-        "kind": "message.recalled",
-        "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` 表达。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先读取 `envelope` 和 `message_ids`。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `from`、`to`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
-| `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 | 服务端时间戳（毫秒） |
+```json
+{
+    "envelope": {
+        "from": "alice.agentid.pub",
+        "to": "bob.agentid.pub",
+        "type": "message.recalled",
+        "kind": "message.recalled",
+        "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` 表达。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先读取 `envelope` 和 `message_ids`。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `from`、`to`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
+| `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

@@ -44,7 +44,7 @@
 | `from` / `sender_aid` | 服务端生成的消息信封 | 发送方身份 |
 | `message_id` / `seq` / `timestamp` / `created_at` | 服务端生成或发送参数 | 当前消息 ID、序号和服务端时间 |
 | `encrypted` / `delivery_mode` | 发送参数或连接上下文 | 加密和 P2P 投递语义 |
-| `dispatch_mode` | 群消息信封和 SDK 注入的群消息 payload | 群消息应用层分发模式标签：`broadcast` / `mention`；由群设置决定，不作为 `group.send` 单次入参 |
+| `mention_mode` | 群消息信封和 SDK 注入的群消息 payload | 群消息应用层提及过滤模式标签：`disabled` / `mention-only`；由群设置决定，不作为 `group.send` 单次入参。SDK 从服务端消息元数据复制到对象 payload |
 | `type` / `message_type` | 发送参数或消息信封 | 信封/封装类型，如 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` |
 | `dispatch` / `duty_state` / `message_dispatch` | `group.send` 响应和群消息事件 | 群消息运行时分发状态和值班分发结果 |
 

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

@@ -647,9 +647,20 @@ for obj in result["items"]:
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
 
-`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
-
----
+`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
+
+### 数据面 HTTP 下载流程
+
+1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
+2. 优先使用返回的 `url` / `download_url`，完整保留查询参数。URL 已包含 `?t=` 时，该值就是资源域签发的能力凭据，按原样请求即可，不要替换为 AID access token。
+3. 只有目标端点明确要求 `Authorization: Bearer <AID JWT>` 时，才在发起请求前读取当前 token：Python 使用 `get_access_token()`，TypeScript / JavaScript 使用 `getAccessToken()`，Go 使用 `GetAccessToken()`。不得长期保存 `authenticate()` 首次返回的 token，也不得跨多次请求缓存 getter 的返回值。
+4. getter 只读后台刷新任务维护的缓存，不主动刷新。返回空值时先完成身份加载和认证/连接，不发送空 Bearer。跨 issuer 下载必须使用资源所在域签发的 `?t=` 票据，不能把调用方所在域的 AID JWT 发给远端 storage。
+5. Bearer 请求收到 401/403 时，重新读取一次 getter；仅当 token 已变化时最多重试一次。token 未变化时保留真实鉴权/授权错误，不得无限重试。票据过期则重新调用 `create_download_ticket`，不能靠刷新 AID token 延长票据。
+6. 跟随 302 时不得把 AID Bearer 转发到不同 origin 的 blob backend；下载完成后校验 `size_bytes` / `sha256`。
+
+SDK Storage VFS 会编排 ticket、HTTP GET 和完整性校验。应用只有在绕过 VFS、自行执行 HTTP 请求时，才需要直接处理上述凭据生命周期。
+
+---
 
 ## 事件
 

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

@@ -15,7 +15,7 @@
 
 | 端点 | 协议 | 说明 |
 |------|------|------|
-| `/push/{stream_id}` | WebSocket | 推流。推荐使用 `Authorization: Bearer {push_token}`，query token 仅为兼容旧客户端 |
+| `/push/{stream_id}` | WebSocket | 推流。使用 `Authorization: Bearer {push_token}` 或 `X-Stream-Token`；不接受 query token |
 | `/pull/{stream_id}` | HTTP SSE | 拉流。推荐使用 `Authorization: Bearer {pull_token}`，可跨域 |
 | `/health` | HTTP GET | 健康检查 |
 
@@ -38,8 +38,8 @@
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `stream_id` | string | 流唯一 ID（16 位 hex） |
-| `push_url` | string | 推流 WebSocket URL（含 push_token） |
-| `pull_url` | string | 拉流 HTTP SSE URL（含 pull_token） |
+| `push_url` | string | 推流 WebSocket URL（不含凭据） |
+| `pull_url` | string | 拉流 HTTP SSE URL（不含凭据） |
 | `push_token` | string | 推流凭证 |
 | `pull_token` | string | 拉流凭证，便于通过 message.send 单独传递 |
 | `push_headers` | object | 推流 Authorization header（`{"Authorization": "Bearer {push_token}"}`) |
@@ -54,8 +54,8 @@ result = await client.call("stream.create", {
 })
 # result = {
 #   "stream_id": "4d5067f203cf42ba",
-#   "push_url": "wss://stream.aid.com:9490/push/4d5067f203cf42ba?token=ec80...",
-#   "pull_url": "https://stream.aid.com:9490/pull/4d5067f203cf42ba?token=c438...",
+#   "push_url": "wss://stream.aid.com:9490/push/4d5067f203cf42ba",
+#   "pull_url": "https://stream.aid.com:9490/pull/4d5067f203cf42ba",
 #   "push_token": "ec80...",
 #   "pull_token": "c438953be0ca887b...",
 #   "push_headers": {"Authorization": "Bearer ec80..."},
@@ -63,7 +63,7 @@ result = await client.call("stream.create", {
 # }
 ```
 
-> 当前实现中，`push_url` / `pull_url` 仍会附带 query token 以兼容旧客户端；新客户端优先使用返回的 `push_headers` / `pull_headers`。
+> `push_url` / `pull_url` 不携带凭据。客户端必须使用返回的 `push_headers` / `pull_headers`，或把对应 token 放入 `Authorization: Bearer ...` / `X-Stream-Token` Header。
 
 ### 错误
 
@@ -169,7 +169,7 @@ for s in result["streams"]:
 
 ## 数据面：推流 WebSocket
 
-连接 `stream.create` 返回的 `push_url`，通过 WebSocket 发送 JSON 帧。当前实现优先从 `Authorization: Bearer` 读取 token，query string 仅作兼容回退。
+连接 `stream.create` 返回的 `push_url`，通过 WebSocket 发送 JSON 帧。使用 `Authorization: Bearer` 或 `X-Stream-Token` 请求头传递 token；query string 不接受凭据。
 
 ### 帧格式
 
@@ -210,7 +210,7 @@ WebSocket 断开后，服务端保留流状态最多 120 秒。重连后继续
 
 连接 `stream.create` 返回的 `pull_url`，接收标准 SSE 流。
 
-当前实现优先从 `Authorization: Bearer` 读取 pull token；若提供拉流方 AID，优先使用 `X-Stream-AID` 请求头，query 参数仅作兼容回退。
+使用 `Authorization: Bearer` 或 `X-Stream-Token` 请求头传递 pull token；若提供拉流方 AID，使用 `X-Stream-AID` 请求头；query 参数不接受凭据或身份。
 
 ### SSE 格式
 

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -9,11 +9,12 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `AIDStore`：注册、加载、列举、解析和证书运维。
 - `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
 - `AUNClient`：认证、连接、状态机、事件和 RPC。
+- `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名；`group.index` 的签名索引、`_meta.group_indexes` 观察和 `expected_index_etag` CAS 详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`。Agent.md Schema、签名和上传前校验见 `../agent.md/SCHEMA.md` 与 `04-连接与认证.md`。A/T/H、SDK 内部自动最新页同步、Forward 调度和每个 AUNClient 一个 Pull Gate（始终 single-inflight、相同 key 折叠、不同 key 排队、前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual。Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。
 
-Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
+Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
 Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
 
 ## 渐进式查阅流程
@@ -27,15 +28,17 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 常见主题：
 
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
-- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
+- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连 / 当前 access token getter / connect-disconnect-close 并发与取消
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
-- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
-- Group RPC：`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
+- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（P2P Message/Group Message/Group Event Pull 共享，始终单飞、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
+- Storage：SDK VFS、direct backend 数据面、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
+- Group RPC：群提及过滤 `mention_mode`、`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
 - 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
-- agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
+- agent.md：Schema/frontmatter、尾部签名、4 KiB/2048 字节限制、`AIDStore.register()` 默认自动上传、上传前完整校验、`agent_md_validation_v1`、`uploader_aid` / `uploaderAid`、`AIDStore.upload_agent_md()` / `download_agent_md()` / `check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
 - 错误处理：Result、异常、错误码、重试
 
 ### Step 3：读 Layer 3 摘要
@@ -46,15 +49,17 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 
 | 编号 | 文档 | 定位 |
 |------|------|------|
+| - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
-| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket |
-| 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE、Group Index 观察模型 |
-| 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件、agent.md 自动观察 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
-| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / agent.md / ServiceProxyClient / 事件 / RPC |
+| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、Capabilities 能力声明、各层大小限制、消息格式、裸 WebSocket |
+| 03 | [核心概念](03-核心概念.md) | AID、A/T/H、Pull Gate、状态机、E2EE |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、agent.md 校验和自动观察 |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
+| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 门面 / 事件 / RPC |
 | 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
-| 08 | [最佳实践](08-最佳实践.md) | 幂等、多 AID、资源清理、测试数据 |
-| - | [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（始终单飞）、测试数据 |
+| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、数据面 HTTP 下载流程、ticket / AID Bearer 边界、跨 issuer 下载 |
+| - | [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
 | 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
 | 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
 | 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
@@ -63,18 +68,24 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 
 | 场景 | 推荐路径 |
 |------|----------|
+| 了解最新版本特性和改进 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
 | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
-| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 发布、下载、检查或排查 agent.md 远端 ETag | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
+| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
+| 自行发起 HTTP 数据面请求并获取当前 access token | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程) |
+| 发布、下载、检查或排查 agent.md（含 Schema/签名/大小限制）及远端 ETag | [../agent.md/SCHEMA.md](../agent.md/SCHEMA.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
-| 查方法签名 | [06-API手册](06-API手册.md) |
-| 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
-| 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
-| 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 查 Capabilities 能力声明、实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
+| 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
+| 查方法签名、群组高层 facade 和 `aid_store` / `aidStore` | [06-API手册](06-API手册.md) |
+| 查消息或群组 RPC、群提及过滤 `mention_mode` | 对应 `09-*-rpc-manual.md`；`mention_mode` 详见 [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 A/T/H、SDK 自动最新页同步与 AUNClient 级 Pull Gate | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 History、Forward、Pull Gate、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 Storage 架构、SDK VFS、权限模型和 mount/symlink | [AUN Storage架构设计.md](<../aun-fs/AUN Storage架构设计.md>) |
+| 查 Storage RPC 参数、数据面 HTTP 下载流程和 ticket / AID Bearer 边界 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
 | 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
 | 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
 | 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |