@agentunion/fastaun-browser 0.5.6 → 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

@@ -459,7 +459,7 @@ Tail 不推进 ACK、retention/visibility floor、Pull activity 或 catch-up 状
 
 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 不进入实时发布流。
+**客户端发布语义**：单个通过校验的 Tail/Forward 响应页内必须按 seq 升序处理，并折叠页内重复 seq。A/T/H 只描述扫描进度，不是应用发布账本；Tail 与 Forward 窗口可重叠，因此跨 Push/Tail/Forward 页不承诺唯一或有序。全局去重与排序属于应用层业务仓库职责，不是 SDK 交付契约；应用层必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序。SDK 进程内折叠只能作为 best-effort 优化。History 不进入实时发布流。
 
 #### `message.ack`
 

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -122,9 +122,9 @@ sequenceDiagram
     "capabilities": {
         "e2ee": true,
         "group_e2ee": true,
-        "supported_p2p_e2ee": ["e2ee_v2"],
-        "supported_group_e2ee": ["group_e2ee_v2"],
-        "inline_realtime_payload_v1": true
+        "supported_p2p_e2ee": ["e2ee_v2"],
+        "supported_group_e2ee": ["group_e2ee_v2"],
+        "inline_realtime_payload_v1": true
     }
 }
 ```
@@ -134,8 +134,8 @@ sequenceDiagram
 | `e2ee` | 支持 P2P E2EE V2 加密通信 |
 | `group_e2ee` | 支持群组 E2EE V2 加密通信 |
 | `supported_p2p_e2ee` | 明确支持的 P2P 加密版本列表 |
-| `supported_group_e2ee` | 明确支持的群组加密版本列表 |
-| `inline_realtime_payload_v1` | **支持实时推送内联消息载荷**（0.5.6+ 新增） |
+| `supported_group_e2ee` | 明确支持的群组加密版本列表 |
+| `inline_realtime_payload_v1` | **支持实时推送内联消息载荷**（0.5.6+ 新增） |
 
 ### inline_realtime_payload_v1 详解
 
@@ -152,11 +152,11 @@ sequenceDiagram
 
 ### 服务端能力公告
 
-`hello-ok.result.capabilities` 返回服务端支持的特性，客户端可根据此信息调整行为。服务端和客户端的 capabilities **不是交集协商**，而是各自独立声明。
-
----
-
-## 消息格式
+`hello-ok.result.capabilities` 返回服务端支持的特性，客户端可根据此信息调整行为。服务端和客户端的 capabilities **不是交集协商**，而是各自独立声明。
+
+---
+
+## 消息格式
 
 所有消息遵循 JSON-RPC 2.0 格式，通过以下规则区分类型：
 

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -73,9 +73,9 @@ Tail 和 Forward 的水位由通过校验的服务端原始页决定。单条解
 
 冷启动缺少发送方 IK 时，SDK 会将同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；成功后立即重试当前消息解密，失败或超时才转入 pending 后台重试。这个有界阻塞只影响当前加密消息的首次处理，不改变“永久坏密文不阻塞 A/T/H”的规则。
 
-SDK 有三个 Pull Gate：P2P Message 共用一个，所有 Group Message 共用一个，所有 Group Event 共用一个。每个 Gate 单飞；相同请求 key 折叠，不同 key 排队。Message Tail/History 进入前台 FIFO，Message Forward/Gap Fill 与 Group Event Pull 进入后台 FIFO；排队超过 3 秒时请求旁路对应 Gate 执行。Group Event 保持独立的 Forward Cursor，不进入 A/T/H 模型，也不与 Group Message 竞争同一 Gate。
+每个 `AUNClient` 只有一个客户端级 Pull Gate。P2P Message、Group Message、Group Event 的 Pull 都进入该 Gate；Gate 始终 single-inflight，相同请求 key 折叠并共享同一结果，不同 key 排队，前台 FIFO 优先于后台 FIFO。Message Tail/History 属于前台，Message Forward/Gap Fill 与 Group Event Pull 属于后台。Group Event 仍使用独立的 Forward Cursor，但不使用独立 Gate；不同 `AUNClient` 实例之间不共享 Gate。应用层直接正常 `await client.call(...)` 即可，无需自行实现重复并发控制。
 
-A/T/H 是服务端消息空间的扫描水位，不是应用层发布账本。SDK 只保证单个通过校验的 Tail/Forward 响应页内按 seq 升序、同 seq 最多发布一次；History 只解密返回，不进入实时发布流。Tail 与 Forward 的窗口可能重叠，Pull Gate 超时旁路也允许多个响应并发完成，因此跨 Push/Tail/Forward 页不保证唯一或有序。全局去重与排序属于应用业务仓库职责，不是 SDK 交付契约；应用必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序存储或展示。SDK 的进程内去重只能作为 best-effort 重叠折叠，不能替代应用持久化幂等。
+A/T/H 是服务端消息空间的扫描水位，不是应用层发布账本。SDK 只保证单个通过校验的 Tail/Forward 响应页内按 seq 升序、同 seq 最多发布一次；History 只解密返回，不进入实时发布流。Tail 与 Forward 的窗口可能重叠，因此跨 Push/Tail/Forward 页不保证唯一或有序。全局去重与排序属于应用业务仓库职责，不是 SDK 交付契约；应用必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序存储或展示。SDK 的进程内去重只能作为 best-effort 重叠折叠，不能替代应用持久化幂等。
 
 ---