@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/_packed_docs/message-online-push-alignment.md

@@ -0,0 +1,572 @@
+# Message 在线推送场景对齐分析
+
+**审查日期**: 2026-08-16  
+**审查范围**: Python vs Go message 在线推送机制实现  
+**审查文件**:
+- Python: `D:\modelunion\kite\extensions\services\message\entry.py`
+- Python: `D:\modelunion\kite\extensions\services\message\online_tracker.py`
+- Go: `D:\modelunion\kite\extensions\services\message\go\cmd\message-go\main.go`
+- Go: `D:\modelunion\kite\extensions\services\message\go\internal\online\tracker.go`
+
+---
+
+## 1. 在线状态管理对齐
+
+### Python 实现 (`online_tracker.py`)
+
+**数据结构**:
+```python
+# OnlineTracker 类
+_aid_to_connections: dict[str, set[str]]              # aid → connection_ids
+_aid_device_to_connections: dict[tuple[str, str], set[str]]  # (aid, device_id) → connection_ids
+_connection_to_aid: dict[str, str]                     # connection_id → aid
+_connection_meta: dict[str, dict]                      # connection_id → metadata
+_aid_delivery_mode: dict[str, dict]                    # aid → delivery_mode
+_gateway_snapshot_connection_ids: set[str]             # Gateway 同步的连接集合
+_redis: redis_client                                   # Redis 连接存储
+```
+
+**在线状态更新机制**:
+- `on_client_online(connection_id, aid, device_id, slot_id, delivery_mode)` — 连接上线
+- `on_client_offline(connection_id)` — 连接下线
+- `sync_with_gateway(snapshot)` — 从 Gateway 在线快照同步
+- `is_online_async(aid)` — 支持 Redis 远程查询
+
+**多设备支持**:
+- ✅ 同一 AID 多个 connection_id（`_aid_to_connections` 是 set）
+- ✅ 同一 (aid, device_id) 多个 connection（`_aid_device_to_connections`）
+- ✅ delivery_mode 采用 first-writer-wins 策略（第一个设备的模式生效）
+
+### Go 实现 (`internal/online/tracker.go`)
+
+**数据结构**:
+```go
+// Tracker 结构
+aidToConnections       map[string]map[string]struct{}  // aid → connection_ids
+aidDeviceToConnections map[deviceKey]map[string]struct{} // (aid, device_id) → connection_ids
+connectionToAID        map[string]string                // connection_id → aid
+connectionMeta         map[string]OnlineInstance        // connection_id → metadata
+aidDeliveryMode        map[string]map[string]any        // aid → delivery_mode
+gatewaySnapshotIDs     map[string]struct{}              // Gateway 同步的连接集合
+connectionStore        ConnectionStore                  // Redis 连接存储接口
+```
+
+**在线状态更新机制**:
+- `OnClientOnline(connectionID, aid, ClientOnlineOptions)` — 连接上线
+- `OnClientOffline(connectionID)` — 连接下线
+- `SyncWithGateway(snapshot)` — 从 Gateway 在线快照同步
+- `IsOnlineContext(ctx, aid)` — 支持 ConnectionStore 远程查询
+
+**多设备支持**:
+- ✅ 同一 AID 多个 connection_id（`aidToConnections` 是 map[string]struct{}）
+- ✅ 同一 (aid, device_id) 多个 connection（`aidDeviceToConnections`）
+- ✅ delivery_mode 采用 first-writer-wins 策略（一致）
+
+### 对齐结论
+
+✅ **完全对齐** — 数据结构、多设备支持、delivery_mode 策略完全一致
+
+---
+
+## 2. 推送路径选择对齐
+
+### Python 实现
+
+**推送路径**:
+1. **gateway.dispatch_event** (`_emit_client_event`) — 主路径
+   - 直接调用 Gateway 的 `dispatch_event` RPC
+   - 支持 fire-and-forget 模式（`AUN_DIRECT_EVENT_MESSAGE=true`）
+   - 支持同步模式（等待 Gateway 响应）
+   - 路径: `_emit_client_event` → `_gateway_business_call/notify("gateway.dispatch_event", params)`
+
+2. **kernel.event.publish** (`_publish_kernel_event`) — 弃用路径
+   - 通过 Kernel 发布事件（非客户端事件）
+   - ⚠️ 仅用于非客户端事件（不含 `message.received`/`message.recalled`）
+
+**路径选择逻辑**:
+```python
+async def _publish_event(ws, event: dict):
+    event_name = event.get("event", "")
+    data = event.get("data", {})
+    # 客户端事件走 gateway.dispatch_event
+    if event_name in {"message.received", "message.recalled"} or event_name.startswith("aun.service."):
+        await _emit_client_event(event_name, data)
+        return
+    # 其他事件走 kernel.event.publish
+    await _publish_kernel_event(ws, event_name, data, _next_fast_id("evt"))
+```
+
+**联邦跨域推送**:
+- ✅ 支持 `federation_forward: true` 选项
+- ✅ Gateway 自动转发到远程 issuer
+- 实现: `_emit_client_event` 中设置 `options: {"federation_forward": True}`
+
+### Go 实现
+
+**推送路径**:
+1. **gatewayattach.DispatchEvent** — 唯一路径
+   - 直接调用 Gateway Client 的 `DispatchEvent` 方法
+   - 路径: `gatewayMessageEventSink.EmitMessageReceived` → `client.DispatchEvent(ctx, DispatchEventRequest)`
+
+2. **无 kernel.event.publish 路径**
+   - ✅ Go 版本完全移除了 Kernel event.publish 路径
+
+**路径选择逻辑**:
+```go
+// 所有客户端事件统一走 DispatchEvent
+func (s gatewayMessageEventSink) EmitMessageReceived(ctx context.Context, data map[string]any) error {
+    // ...
+    result, err := s.client.DispatchEvent(ctx, gatewayattach.DispatchEventRequest{
+        EventID: eventIDForMessageReceived(payload),
+        Event:   "message.received",
+        Targets: map[string]any{
+            "aids":           []string{toAID},
+            "connection_ids": sessionGroup.connectionIDs,
+        },
+        Payload: gatewayPayloadWithTrace(ctx, payload),
+    })
+    // ...
+}
+```
+
+**联邦跨域推送**:
+- ✅ 支持通过 `ForwardFederation` 接口转发
+- ⚠️ **但 dispatch_event 本身不携带 federation_forward 选项**
+
+### 对齐结论
+
+| 维度 | Python | Go | 对齐状态 |
+|------|--------|-----|----------|
+| 主推送路径 | gateway.dispatch_event | DispatchEvent | ✅ 对齐 |
+| kernel.event.publish | 存在（非客户端事件） | 不存在 | ⚠️ Go 更纯净 |
+| federation_forward 选项 | ✅ 显式传递 | ❌ 缺失 | ⚠️ **P1 缺口** |
+
+---
+
+## 3. 推送逻辑对齐
+
+### Python 实现
+
+**推送事件格式**:
+```python
+params = {
+    "event_id": event_id,
+    "event": "message.received",  # 或 "peer.v2.message_received"
+    "source_module": "message",
+    "targets": {
+        "aids": [to_aid],
+        "connection_ids": [...]  # 可选
+    },
+    "payload": {
+        "to": to_aid,
+        "message_id": message_id,
+        "seq": seq,
+        "device_id": device_id,
+        "_route": {"aids": [...], "connection_ids": [...]},
+        "_trace": {"trace_id": "...", "mode": "..."}
+    },
+    "options": {"federation_forward": True}
+}
+```
+
+**推送参数构造**:
+- `targets` — 由 `_targets_for_message_event` 自动计算
+  - 从 `data._route` 提取 aids/connection_ids
+  - 兜底从 `data.to` 提取目标 AID
+- `payload` — 包含完整消息体 + `_route` + `_trace`
+- `options.federation_forward` — 启用跨域转发
+
+**推送失败降级**:
+```python
+if _gateway_event_fire_and_forget_enabled(event_name):
+    await _gateway_business_notify("gateway.dispatch_event", params)
+    return {}  # 不等待响应
+else:
+    result = await _gateway_business_call("gateway.dispatch_event", params)
+    _enqueue_message_offline_push_delivery_evidence(event_name, data, result)
+    return result  # 记录离线推送证据
+```
+- fire-and-forget: 静默失败（不影响 send 返回）
+- 同步模式: 记录 `delivered_devices` 用于离线推送决策
+
+**推送性能追踪**:
+- ❌ Python 无显式性能追踪（仅依赖 `_trace` 传递）
+
+**批量推送 vs 逐个推送**:
+- Python 逐个设备推送（每个 device_id 单独调用 `_emit_client_event`）
+
+### Go 实现
+
+**推送事件格式**:
+```go
+gatewayattach.DispatchEventRequest{
+    EventID: eventIDForMessageReceived(payload),
+    Event:   "message.received",  // 或 "peer.v2.message_received"
+    Targets: map[string]any{
+        "aids":           []string{toAID},
+        "connection_ids": sessionGroup.connectionIDs,
+    },
+    Payload: gatewayPayloadWithTrace(ctx, payload),
+}
+```
+
+**推送参数构造**:
+- `Targets` — 显式构造
+  - 查询 Gateway sessions: `client.QuerySessions(ctx, QuerySessionsRequest{AID: toAID, DeviceID: deviceID})`
+  - 按 slot_id 分组: `groupGatewaySessionConnectionsBySlot(sessions)`
+  - 每个 slot 单独推送
+- `Payload` — 包含 `_route` + trace 上下文
+- ⚠️ **无 federation_forward 选项**
+
+**推送失败降级**:
+```go
+delivered := false
+for _, sessionGroup := range sessionGroups {
+    result, err := s.client.DispatchEvent(ctx, DispatchEventRequest{...})
+    if err != nil {
+        dispatchErr = errors.Join(dispatchErr, fmt.Errorf("dispatch failed: %w", err))
+        continue  // 继续尝试其他 slot
+    }
+    if !gatewayDispatchSucceeded(result) {
+        dispatchErr = errors.Join(dispatchErr, fmt.Errorf("Gateway rejected: result=%v", result))
+        continue
+    }
+    delivered = true
+}
+if !delivered {
+    return dispatchErr  // 返回失败（影响 send 结果）
+}
+```
+- **同步模式** — 所有 slot 失败才返回错误
+- 记录 `delivered_devices` 到 `offlinePushCandidates`
+
+**推送性能追踪**:
+- ✅ `LogPerf(ctx, "msg_v2_source_self_sync_done", map[string]any{"push_scheduled": 0})`
+- ✅ 详细日志: `servicelog.Warningf("V2 push dispatch failed aid=%s device=%s seq=%d error=%v", ...)`
+
+**批量推送 vs 逐个推送**:
+- Go 按 slot 分组批量推送（同一 slot 的多个 connection 一次推送）
+
+### 对齐结论
+
+| 维度 | Python | Go | 对齐状态 |
+|------|--------|-----|----------|
+| 事件格式 | ✅ 标准 | ✅ 标准 | ✅ 对齐 |
+| targets 计算 | 自动提取 | QuerySessions + 分组 | ⚠️ Go 更精确 |
+| federation_forward | ✅ 显式传递 | ❌ 缺失 | ⚠️ **P1 缺口** |
+| 失败降级 | fire-and-forget / 同步 | 同步 + 多 slot 重试 | ⚠️ Go 更健壮 |
+| 性能追踪 | ❌ 无 | ✅ 有 | ⚠️ Go 更好 |
+| 推送模式 | 逐设备 | 按 slot 批量 | ⚠️ Go 更高效 |
+
+---
+
+## 4. 推送时机对齐
+
+### Python 实现
+
+**send 成功后立即推送**:
+```python
+# legacy send (entry.py:8700+)
+async def _rpc_send(params: dict):
+    # 1. 落库持久化
+    await _store_message(...)
+    # 2. 立即推送（不影响 send 返回）
+    _publish_event(_ws_global, {"event": "message.received", "data": evt_data})
+    # 3. 返回 send 结果
+    return {"message_id": message_id, "timestamp": timestamp, "seq": seq}
+```
+
+**V2 send 推送**:
+```python
+# v2 send (entry.py:11100+)
+# 1. 落库
+result = await _v2_store_message_with_recipients(...)
+# 2. 异步推送（后台 task）
+for row in recipients:
+    try:
+        await _emit_client_event("peer.v2.message_received", push_event_data)
+    except Exception as e:
+        print(f"WARNING: V2 push event failed (non-fatal)")  # 静默失败
+# 3. 返回结果
+return result
+```
+
+**推送与持久化顺序**:
+- 持久化 → 推送（先写库，再推送）
+- 推送失败不影响 send 返回（fire-and-forget 或异常捕获）
+
+**推送失败影响**:
+- ❌ 不影响 send 返回（静默失败或后台重试）
+
+### Go 实现
+
+**send 成功后立即推送**:
+```go
+// legacy send (main.go:8620+)
+func (s gatewayMessageEventSink) EmitMessageReceived(ctx context.Context, data map[string]any) error {
+    // 1. 查询 Gateway sessions
+    sessions, err := s.client.QuerySessions(ctx, QuerySessionsRequest{...})
+    // 2. 按 slot 推送
+    for _, sessionGroup := range sessionGroups {
+        result, err := s.client.DispatchEvent(ctx, DispatchEventRequest{...})
+        if err != nil || !gatewayDispatchSucceeded(result) {
+            dispatchErr = errors.Join(dispatchErr, err)
+            continue
+        }
+        delivered = true
+    }
+    // 3. 标记已投递
+    if delivered {
+        s.markDelivered(ctx, toAID, messageID, deviceID)
+    }
+    return dispatchErr  // ⚠️ 返回错误会影响调用方
+}
+```
+
+**V2 send 推送**:
+```go
+// v2 send (main.go:8570+)
+for _, pair := range pairs {
+    err = sink.EmitV2PeerMessageReceived(ctx, event)
+    if err != nil {
+        servicelog.Warningf("message V2 push emit failed: %v", err)  // 记录警告但不中断
+    }
+    scheduled++
+}
+```
+
+**推送与持久化顺序**:
+- 持久化 → 推送（先写库，再推送）
+- 推送失败记录到日志但不影响 send 返回
+
+**推送失败影响**:
+- ⚠️ **潜在问题**: `EmitMessageReceived` 返回错误，但调用方是否捕获？
+  - 需确认 `sink.EmitV2PeerMessageReceived` 调用时是否会传播错误
+
+### 对齐结论
+
+| 维度 | Python | Go | 对齐状态 |
+|------|--------|-----|----------|
+| 推送时机 | 持久化后立即推送 | 持久化后立即推送 | ✅ 对齐 |
+| 持久化顺序 | 先写库，再推送 | 先写库，再推送 | ✅ 对齐 |
+| 推送失败影响 send | ❌ 不影响 | ⚠️ 可能影响 | ⚠️ **P2 不一致** |
+| 失败日志 | WARNING 静默 | Warningf 记录 | ✅ 对齐 |
+
+---
+
+## 5. 修复清单
+
+### P0 缺口（严重，影响核心功能）
+
+**无**
+
+---
+
+### P1 缺口（重要，影响跨域或可靠性）
+
+#### P1-1: Go 缺失 `federation_forward` 选项
+
+**位置**: `main.go:8643` / `8702` / `8887` / `8923` / `8952` / `8978`
+
+**问题**:
+- Go 在调用 `DispatchEvent` 时未传递 `Options: {"federation_forward": true}`
+- 导致跨域推送无法自动转发到远程 issuer
+- Python 版本通过 `options: {"federation_forward": True}` 启用联邦转发
+
+**影响**:
+- 跨 issuer 的在线推送无法送达（仅本地 issuer 生效）
+- 联邦场景下消息只能通过 pull 获取（无实时推送）
+
+**修复**:
+```go
+// 修复前
+result, err := s.client.DispatchEvent(ctx, gatewayattach.DispatchEventRequest{
+    EventID: eventIDForMessageReceived(payload),
+    Event:   "message.received",
+    Targets: map[string]any{
+        "aids":           []string{toAID},
+        "connection_ids": sessionGroup.connectionIDs,
+    },
+    Payload: gatewayPayloadWithTrace(ctx, payload),
+})
+
+// 修复后
+result, err := s.client.DispatchEvent(ctx, gatewayattach.DispatchEventRequest{
+    EventID: eventIDForMessageReceived(payload),
+    Event:   "message.received",
+    Targets: map[string]any{
+        "aids":           []string{toAID},
+        "connection_ids": sessionGroup.connectionIDs,
+    },
+    Payload: gatewayPayloadWithTrace(ctx, payload),
+    Options: map[string]any{"federation_forward": true},  // 新增
+})
+```
+
+**受影响方法**:
+1. `EmitMessageReceived` (main.go:8643, 8702)
+2. `emitV2PeerMessageReceived` (main.go:8887)
+3. `EmitMessageRecalled` (main.go:8923, 8952, 8978)
+4. `EmitMessageAck` (main.go:8997)
+
+**验证方法**:
+1. 启动双域测试环境（issuer-a.test + issuer-b.test）
+2. alice.issuer-a.test 发送消息给 bob.issuer-b.test
+3. 确认 bob 在线时能实时收到推送（不依赖 pull）
+4. 检查 gateway logs 确认 `federation.forward` 被调用
+
+---
+
+### P2 缺口（次要，影响体验或一致性）
+
+#### P2-1: Go 推送失败可能影响 send 返回
+
+**位置**: `main.go:8620` (`EmitMessageReceived` 返回值处理)
+
+**问题**:
+- `EmitMessageReceived` 返回 error 时，调用方是否会传播到 send 响应？
+- Python 版本明确静默失败（`except Exception: print(f"WARNING: ...")`）
+- Go 版本返回 `dispatchErr`，但不确定是否被捕获
+
+**影响**:
+- 如果错误传播，推送失败会导致 send 失败（不符合异步推送语义）
+- 客户端收到 send 错误，但消息已持久化（状态不一致）
+
+**修复**:
+确认调用方是否捕获错误，如果需要保持 Python 行为，修改为：
+```go
+// 修复后
+func (s gatewayMessageEventSink) EmitMessageReceived(ctx context.Context, data map[string]any) error {
+    // ... 推送逻辑
+    if !delivered {
+        servicelog.Warningf("message push failed (non-fatal): %v", dispatchErr)
+        return nil  // 静默失败，不影响 send 返回
+    }
+    return nil
+}
+```
+
+**验证方法**:
+1. 模拟 Gateway 不可用（关闭 gateway 服务）
+2. 发送消息，确认 send 返回成功（不受推送失败影响）
+3. 确认消息已持久化到数据库
+
+---
+
+#### P2-2: Go 缺少 fire-and-forget 配置支持
+
+**位置**: 全局推送逻辑
+
+**问题**:
+- Python 支持 `AUN_DIRECT_EVENT_MESSAGE` / `AUN_MESSAGE_ACK_EVENT_FIRE_AND_FORGET` 环境变量
+- Go 版本所有推送都是同步模式（等待 Gateway 响应）
+- 高吞吐场景下，同步等待会成为瓶颈
+
+**影响**:
+- 推送延迟影响 send 吞吐量
+- 无法通过配置优化性能
+
+**修复**:
+```go
+// 新增配置检查
+func (s gatewayMessageEventSink) shouldFireAndForget(eventName string) bool {
+    if eventName == "message.received" || eventName == "peer.v2.message_received" || eventName == "message.recalled" {
+        return envOrConfigBool("AUN_DIRECT_EVENT_MESSAGE", false)
+    }
+    if eventName == "message.ack" {
+        return envOrConfigBool("AUN_MESSAGE_ACK_EVENT_FIRE_AND_FORGET", false)
+    }
+    return false
+}
+
+// 在推送时应用
+if s.shouldFireAndForget(event) {
+    go func() {
+        _, _ = s.client.DispatchEvent(ctx, req)  // 后台发送，不等待
+    }()
+    return nil
+} else {
+    result, err := s.client.DispatchEvent(ctx, req)
+    // 处理响应
+}
+```
+
+---
+
+#### P2-3: Python 无性能追踪，Go 有
+
+**位置**: Python `_emit_client_event` / Go `LogPerf`
+
+**问题**:
+- Python 版本没有推送性能追踪（仅传递 `_trace`）
+- Go 版本有详细的性能日志（`LogPerf`）
+
+**影响**:
+- Python 环境下难以诊断推送性能问题
+
+**修复**:
+在 Python `_emit_client_event` 中添加性能日志：
+```python
+async def _emit_client_event(event_name: str, data: dict, *, event_id: str | None = None):
+    start = time.perf_counter()
+    try:
+        # ... 推送逻辑
+        result = await _gateway_business_call("gateway.dispatch_event", params)
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        if elapsed_ms > 100:  # 超过 100ms 记录
+            print(f"[message] PERF: push_slow event={event_name} elapsed={elapsed_ms:.1f}ms")
+        return result
+    except Exception as e:
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        print(f"[message] PERF: push_failed event={event_name} elapsed={elapsed_ms:.1f}ms error={e}")
+        raise
+```
+
+---
+
+#### P2-4: Go 按 slot 批量推送更高效
+
+**位置**: Go `groupGatewaySessionConnectionsBySlot` / Python 逐设备推送
+
+**问题**:
+- Python 逐个 device_id 调用 `_emit_client_event`
+- Go 查询 sessions 后按 slot 分组，同一 slot 的多个 connection 一次推送
+
+**影响**:
+- Python 版本在多设备场景下推送次数更多（性能劣势）
+
+**修复**:
+Python 采用 Go 的批量推送策略（需重构 `_emit_client_event` 调用逻辑）
+
+---
+
+## 6. 总结
+
+### 整体对齐度
+
+| 模块 | 对齐度 | 主要差异 |
+|------|--------|----------|
+| 在线状态管理 | ✅ 100% | 数据结构和逻辑完全一致 |
+| 推送路径选择 | ⚠️ 90% | Go 缺失 federation_forward |
+| 推送逻辑 | ⚠️ 85% | Go 更健壮，但缺少配置项 |
+| 推送时机 | ✅ 95% | 基本一致，仅错误处理略有差异 |
+
+### 关键发现
+
+1. **P1 严重缺口**: Go 缺失 `federation_forward` 选项，跨域推送失效
+2. **Go 更健壮**: 多 slot 重试、性能追踪、按 slot 批量推送
+3. **Python 更灵活**: 支持 fire-and-forget 配置
+4. **一致性良好**: 在线状态管理、推送时机、事件格式高度一致
+
+### 修复优先级
+
+1. **立即修复** (P1-1): 添加 `federation_forward` 选项
+2. **近期修复** (P2-1): 确认推送失败不影响 send 返回
+3. **中期优化** (P2-2/3/4): 添加配置支持、性能追踪对齐、批量推送优化
+
+### 验证计划
+
+1. 单元测试: 验证 `federation_forward` 选项传递
+2. 集成测试: 跨域推送端到端验证
+3. 性能测试: 对比 Python vs Go 推送吞吐量
+4. 容错测试: Gateway 不可用时 send 行为一致性

package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md

@@ -16,7 +16,7 @@
 |---------|------|------|---------|---------|
 | `auth.*` | 核心 | AID 注册、认证、令牌管理 | auth 服务 | WebSocket |
 | `ca.*` | 核心 | 证书签发、续期、吊销 | ca 服务 | WebSocket / HTTP |
-| `message.*` | 核心 | 点对点消息路由、E2EE V2 设备密钥/bootstrap | message 服务 | WebSocket |
+| `message.*` | 核心 | 点对点消息路由、E2EE prekey 管理 | message 服务 | WebSocket |
 | `meta.*` | 核心 | 健康检查、状态查询、受信根证书 | meta 服务 | WebSocket |
 | `storage.*` | 扩展 | 对象存储、大文件上传下载（详见 [11-Storage-子协议.md](11-Storage-子协议.md)） | storage 服务 | WebSocket + HTTP |
 | `group.*` | 扩展 | 群组管理、群消息、资源共享（详见 [10-Group-子协议.md](10-Group-子协议.md)） | group 服务 | WebSocket |
@@ -290,7 +290,7 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 |------|:----:|------|
 | `to` | ✅ | 接收者 AID |
 | `payload` | ✅ | 消息载荷，对协议层透明，由应用层定义 |
-| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
+| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
 | `encrypted` | ❌ | E2EE 标记（默认 `false`） |
 | `message_id` | ❌ | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
@@ -382,9 +382,10 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
 | `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
-| `limit` | ❌ | 单次返回上限（默认 50，最大 50；`pull_max_limit` 配置只能进一步收紧） |
+| `limit` | ❌ | 单次返回上限（默认 50，最大 50） |
 | `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
 | `slot_id` | ❌ | 同一设备下的消费槽位；空字符串表示设备单实例模式 |
+| `window_mode` | ❌ | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
 
 **响应**：
 ```json
@@ -419,11 +420,48 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | `ephemeral_earliest_available_seq` | integer\|null | 当前临时缓冲中最早可用的 `seq`，`null` 表示无临时消息 |
 | `ephemeral_dropped_count` | integer | 因缓冲淘汰而丢弃的临时消息计数 |
 
-> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
-
-**说明**：不修改消息状态，多设备安全（各 `(aid, device_id, slot_id)` 维护各自的 `after_seq`），同一 `after_seq` 多次调用返回相同结果（幂等）。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。
-
-#### `message.ack`
+> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
+
+**说明**：不修改消息状态，多设备安全（各 `(aid, device_id, slot_id)` 维护各自的 `after_seq`），同一 `after_seq` 多次调用返回相同结果（幂等）。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。
+
+**Tail 模式**：`window_mode="tail"` 时，服务端固定安全 `head_seq`，返回跨度不超过 `limit` 的最新 seq band，并额外返回：
+
+| 字段 | 说明 |
+|------|------|
+| `window_mode` | 固定为 `tail` |
+| `window_start_seq` | 已扫描窗口的包含式左边界 |
+| `head_seq` | 本次请求固定的安全 Head |
+| `covered_through_seq` | 覆盖终点，正常等于 `head_seq` |
+
+Tail 不推进 ACK、retention/visibility floor、Pull activity 或 catch-up 状态，不接受 `ack_up_to_seq` 或 `force=true`。seq band 内未返回的序号视为服务端永久空号，客户端不得为页内缺号创建 Gap。无 `window_mode` 的旧请求必须保持原请求、响应和副作用语义，以兼容旧 SDK。
+
+#### `message.history`
+
+按 `before_seq` 排他上界向前只读翻页，不修改 ACK、cursor、floor 或 Pull activity。
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `before_seq` | ✅ | 正整数排他上界，只返回 `seq < before_seq` 的消息 |
+| `limit` | ❌ | 单页上限（默认 50，最大 50） |
+
+**响应字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `messages` | 页内按 seq 升序 |
+| `window_start_seq` | 本页最小边界；空页为 `null` |
+| `next_before_seq` | 下一页直接使用的排他上界；无更早消息为 `null` |
+| `has_older` | 是否仍有更早的可见消息 |
+| `retention_floor_seq` | 已实际删除、不可恢复的 seq 下界 |
+| `earliest_available_seq` | 当前最早可拉取边界 |
+
+History 不触发实时消息事件。客户端解密 History 结果时不得修改实时 A/T/H 或发送 ACK。
+
+**客户端发布语义**：单个通过校验的 Tail/Forward 响应页内必须按 seq 升序处理，并折叠页内重复 seq。A/T/H 只描述扫描进度，不是应用发布账本；Tail 与 Forward 窗口可重叠，因此跨 Push/Tail/Forward 页不承诺唯一或有序。全局去重与排序属于应用层业务仓库职责，不是 SDK 交付契约；应用层必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序。SDK 进程内折叠只能作为 best-effort 优化。History 不进入实时发布流。
+
+#### `message.ack`
 
 确认已收到消息，推进服务端 ack 游标。
 
@@ -1288,25 +1326,25 @@ event/task.delegated      # 已创建子任务
 
 ### 6.7 端到端加密（E2EE）摘要
 
-> 当前 V2 主路径见 [E2EE_V2消息通信时序图](../sdk/E2EE_V2消息通信时序图.md)、[05-E2EE加密通信](../sdk/05-E2EE加密通信.md) 和 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。[08-AUN-E2EE.md](08-AUN-E2EE.md) 仅保留 legacy P2P 信封说明。本节仅保留摘要。
+> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
 
 **核心原则**：
 
 - E2EE 加解密**完全由客户端实现**，无需在线协商
-- 服务端只做认证、路由、设备密钥/群状态查询、密文存储和事件通知，对明文内容完全透明
-- P2P 加密消息通过 `message.send` 承载 V2 `e2ee.p2p_encrypted` envelope；群加密消息通过 `group.v2.send` 承载 V2 `e2ee.group_encrypted` envelope
-- 当前主路径为 V2 多设备 wrap：每条消息一把 `master_key`，按 recipient 设备分别生成 `3DH` / `1DH` wrap，并由接收端验证 `sender_signature`、AAD 和 recipient proof / digest
-
-**服务端兼容性要求**：
-
-- 接受并转发 V2 E2EE envelope；兼容旧 `encrypted: true` 标志
-- 在离线队列和历史消息中存储密文 payload
-- 不对密文 payload 施加额外的语义解析要求
-- 提供 `message.v2.put_peer_pk`、`message.v2.bootstrap`、`group.v2.put_group_pk`、`group.v2.bootstrap` 等 V2 设备密钥和 bootstrap RPC
+- 服务端只做消息中转和 prekey 存储，对加密内容完全透明
+- 加密消息通过 `message.send` 的 `encrypted: true` 标志标识
+- 两级降级：prekey_ecdh_v2（优先，四路 ECDH）→ long_term_key（降级）
+
+**服务端兼容性要求**：
+
+- 接受并转发 `encrypted: true` 的消息
+- 在离线队列和历史消息中存储密文 payload
+- 不对密文 payload 施加额外的语义解析要求
+- 提供 `message.e2ee.put_prekey` / `message.e2ee.get_prekey` RPC
 
 **互操作要求**：
 
-跨语言、跨平台 SDK 的当前互操作以 E2EE V2 多设备 wrap 为准：P2P 参见 SDK V2 时序和各语言 `v2/e2ee` 实现，群组参见 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。旧 `e2ee.encrypted` 信封互操作才查 [08-AUN-E2EE.md](08-AUN-E2EE.md)。
+跨语言、跨平台 SDK 的互操作必须以 [08-AUN-E2EE.md](08-AUN-E2EE.md) 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。
 
 **错误码**：