@agentunion/fastaun-browser 0.2.20 → 0.3.1

package/_packed_docs/protocol/15-/347/246/273/347/272/277/346/216/250/351/200/201/351/200/232/347/237/245/345/215/217/350/256/256.md

@@ -0,0 +1,419 @@
+# 15 - 离线推送通知协议 (Push Notification)
+
+## 1. 概述
+
+当目标 AID 的所有设备均离线时，AUN Gateway 通过事件通知将推送摘要发送给 `push_notify_aid`（推送代理 AID），由其完成最终的平台推送（APNs / FCM / WebPush 等）。
+
+**设计原则：**
+
+- push_notify_aid 是普通客户端 AID，不是 AUN 内部服务
+- 通过事件通知（非 P2P 消息）下发推送摘要——轻量、实时、不持久化
+- push_token 对 Gateway 完全不透明（opaque），push_notify_aid 自签自验
+- 任意一台设备在线即不触发推送
+- 推送内容仅含元数据，不含消息正文（E2EE 安全保证）
+- 背压控制：串行确认，Gateway 等 push_notify_aid ack 后再发下一批
+- 跨域推送：推送由**目标 AID 所属域**的 Gateway 触发，发送方域不参与
+
+---
+
+## 2. 架构
+
+```mermaid
+graph TB
+    Sender[发送方 AID] -->|message.send| GW[Gateway]
+    GW -->|目标全部离线| PA[PushAggregator]
+    PA -->|event/push.offline_message| GW
+    GW -->|事件通知| PNA[push_notify_aid<br/>推送代理客户端]
+    PNA -->|push.ack| GW
+    PNA -->|平台推送| PLATFORM[APNs / FCM / WebPush]
+    PLATFORM -->|通知| Target[目标终端]
+
+    PNA -.->|connect 到 Gateway 保持在线| GW
+```
+
+**关键约束：**
+
+- push_notify_aid 作为普通客户端 AID 连接到 Gateway，通过事件通知接收推送摘要
+- push_notify_aid 离线时事件丢弃——推送是 best-effort，消息可靠性由 message.pull 保证
+- 目标 AID 有任意一台设备在线时，不触发推送
+
+---
+
+## 3. 推送注册流程
+
+### 3.1 应用层：客户端向推送代理注册
+
+```mermaid
+sequenceDiagram
+    participant App as 应用客户端
+    participant PNA as push_notify_aid
+
+    Note over App,PNA: 应用层行为，AUN 协议不规定细节
+    App->>PNA: 注册推送(aid, device_id, platform, device_token)
+    PNA->>PNA: 生成 push_token（格式自定）
+    PNA-->>App: push_token
+```
+
+push_token 的格式、签名算法、有效期完全由 push_notify_aid 自行决定。AUN 协议不做任何约束。
+
+### 3.2 协议层：connect 时携带推送配置
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant GW as Gateway
+
+    C->>GW: connect(aid, token, push_notify_aid, push_token)
+    GW->>GW: 认证 AID 身份 ✓
+    GW->>GW: 持久化 push_config
+    GW-->>C: connected
+```
+
+---
+
+## 4. 离线推送时序
+
+```mermaid
+sequenceDiagram
+    participant A as Sender AID
+    participant GW as Gateway
+    participant PA as PushAggregator
+    participant PNA as push_notify_aid
+
+    A->>GW: message.send(to=B, payload=...)
+    GW->>GW: 持久化消息 + 查询 B 在线状态
+
+    alt B 有任意设备在线
+        GW->>GW: 投递到 B 的在线 session
+        Note over GW: 不触发推送
+    else B 全部设备离线
+        GW->>PA: enqueue(target=B, from=A, msg_id, ts)
+        PA->>PA: 聚合窗口 + 频控 + 背压检查
+
+        alt 触发推送 且 in_flight < max
+            PA->>GW: event/push.offline_message
+            GW->>PNA: 事件通知(batch_id, summary, push_token)
+            PA->>PA: in_flight++, 启动 ack_timeout
+            PNA->>PNA: 验证 push_token ✓ → 发送平台推送
+            PNA->>GW: push.ack(batch_id)
+            GW->>PA: release(batch_id)
+            PA->>PA: in_flight--
+        else in_flight = max（背压）
+            PA->>PA: 排队等待槽位释放
+        else 频控抑制
+            PA->>PA: 延迟到下一窗口
+        end
+    end
+
+    GW-->>A: ack(msg_id, seq)
+```
+
+---
+
+## 5. 背压与 in-flight 控制
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle: 初始状态
+    Idle --> Sending: 有待推送 & in_flight < max
+    Sending --> WaitAck: 事件已发出, in_flight++
+    WaitAck --> Idle: 收到 push.ack, in_flight--
+    WaitAck --> Idle: ack_timeout 超时, in_flight--
+    WaitAck --> Queued: 新推送到达但 in_flight = max
+    Queued --> Sending: 槽位释放
+```
+
+### 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| max_in_flight | 1 | 同一 push_notify_aid 未确认批次上限（串行） |
+| ack_timeout | 30s | 超时未 ack 自动释放槽位 |
+| batch_size | 50 | 每批最多聚合多少个 target_aid 的通知 |
+
+### 行为规则
+
+- in_flight < max → 发送事件，in_flight++
+- in_flight = max → 排队等待
+- 收到 `push.ack(batch_id)` → in_flight--，触发队列中下一批
+- 超时 → in_flight--，**不重试**（推送是 best-effort，过时推送是噪音）
+- push_notify_aid 离线 → 事件丢弃，in_flight 不增加
+
+---
+
+## 6. 在线判断规则
+
+```mermaid
+flowchart TD
+    A[消息到达，目标 AID = B] --> B{B 的在线设备数 > 0?}
+    B -->|≥ 1 台在线| C[投递到在线 session，不推送]
+    B -->|0 台在线| D{push_config 存在?}
+    D -->|是| F[进入 PushAggregator]
+    D -->|否| G[仅持久化，等对方上线 pull]
+    F --> H[聚合 + 频控 + 背压 → 推送]
+```
+
+**边界情况：**
+
+- 目标 AID 上线瞬间：清空该 AID 的聚合桶，取消待发推送
+- 最后一台设备断连：不立即触发推送，只有后续新消息到达时发现全离线才走推送路径
+
+---
+
+## 7. 跨域推送
+
+**核心原则：推送由目标 AID 所属域的 Gateway 触发。**
+
+发送方域不感知目标域的 push_config 和白名单，也不需要任何跨域配置同步。
+
+```mermaid
+sequenceDiagram
+    participant A as alice.domain-a.com
+    participant GW_A as Gateway A
+    participant GW_B as Gateway B
+    participant PA_B as PushAggregator B
+    participant PNA as push.domain-b.com<br/>(连在 GW_B)
+
+    A->>GW_A: message.send(to=bob.domain-b.com)
+    GW_A->>GW_A: 持久化消息
+    GW_A->>GW_B: 跨域 relay 消息
+    GW_B->>GW_B: 查询 bob 本地在线状态
+
+    alt bob 在本域有设备在线
+        GW_B->>GW_B: 投递到 bob 的在线 session
+    else bob 本域全部离线
+        GW_B->>PA_B: enqueue(target=bob, from=alice.domain-a.com)
+        PA_B->>GW_B: event/push.offline_message
+        GW_B->>PNA: 事件通知
+        PNA->>GW_B: push.ack
+    end
+
+    GW_B-->>GW_A: relay ack
+    GW_A-->>A: ack
+```
+
+**规则：**
+
+| 关注点 | 行为 |
+|--------|------|
+| 推送配置存储 | 仅存于目标 AID 所属域，不跨域同步 |
+| 白名单管理 | 各域独立配置 `allowed_notify_aids`，互不影响 |
+| push_notify_aid 必须连接位置 | 目标 AID 所属域的 Gateway |
+| push_notify_aid 跨域时 | 不支持。push_notify_aid 必须与其服务的 AID 同域 |
+| summary.senders 中的跨域 AID | 保留完整 AID（含域名），如 `alice.domain-a.com` |
+
+**约束：** push_notify_aid 必须与其服务的目标 AID 处于同一域。如果应用希望在多个域提供推送服务，需要在每个域部署独立的 push_notify_aid 并分别加入白名单。
+
+---
+
+## 8. 聚合与频控
+
+### 8.1 PushAggregator 数据结构
+
+每个离线目标 AID 一个聚合桶：
+
+```
+bucket[target_aid] = {
+    push_notify_aid: "push.myapp.com",
+    push_token: "eyJhb...",
+    pending: [{from, msg_id, ts}, ...],
+    first_enqueue_ts: timestamp,
+    last_push_ts: timestamp,
+}
+```
+
+### 8.2 去重规则
+
+同一 target_aid 在频控窗口内只产生一次推送通知。具体行为：
+
+- 首条消息触发推送后，该 target_aid 进入频控冷却期（默认 60s）
+- 冷却期内新消息只更新聚合桶的 summary（unread_count++、senders 去重追加），不产生新推送
+- 冷却期结束时，若桶内有新增未推送内容，合并为一条推送发出
+
+效果：无论短时间内收到多少条消息，target_aid 最多每 60s 收到一次推送通知，且 summary 是累积聚合的。
+
+### 8.3 触发规则
+
+| 规则 | 说明 | 默认值 |
+|------|------|--------|
+| 首条即推 | 桶为空且不在冷却期时，第一条消息立即触发 | 开启 |
+| 窗口聚合 | 首条之后的消息等待窗口合并 | 5 秒 |
+| 数量上限 | 桶内积累 N 条立即触发（不等窗口） | 20 条 |
+
+### 8.4 频控规则
+
+| 维度 | 限制 | 说明 |
+|------|------|------|
+| 同一 target_aid | 60 秒内最多 1 次推送 | 避免终端刷屏 |
+| 同一 push_notify_aid | 1000 次/分钟 | 保护推送代理服务 |
+| 全局 | 5000 次/分钟 | 系统保护 |
+
+频控被触发时消息不丢弃，等窗口过后下一次聚合时一并推送。
+
+---
+
+## 9. 协议字段
+
+### 9.1 connect 扩展字段
+
+```json
+{
+  "method": "auth.login",
+  "params": {
+    "aid": "bob.example.com",
+    "challenge_response": "...",
+    "push_notify_aid": "push.myapp.com",
+    "push_token": "eyJhbGciOiJIUzI1NiJ9..."
+  }
+}
+```
+
+- `push_notify_aid` 和 `push_token` 均为可选字段
+- 两者必须同时提供或同时不提供
+- 不提供 = 不需要离线推送
+- 每次 connect 覆盖写（最新连接为准）
+
+### 9.2 事件通知格式
+
+Gateway 向 push_notify_aid 下发的事件通知：
+
+```json
+{
+  "method": "event/push.offline_message",
+  "params": {
+    "batch_id": "uuid-xxx",
+    "items": [
+      {
+        "target_aid": "bob.example.com",
+        "push_token": "eyJhbGciOiJIUzI1NiJ9...",
+        "summary": {
+          "unread_count": 3,
+          "senders": ["alice.example.com", "charlie.example.com"],
+          "latest_ts": 1716100005,
+          "group_ids": ["group-uuid-1"]
+        }
+      }
+    ]
+  }
+}
+```
+
+**安全约束：** 不包含消息正文。E2EE 场景下 Gateway 无法解密，推送代理只需知道"有 N 条未读来自谁"即可构造推送文案。
+
+### 9.3 push.ack RPC
+
+push_notify_aid 处理完一批推送后回调确认：
+
+```json
+{
+  "method": "push.ack",
+  "params": {
+    "batch_id": "uuid-xxx"
+  }
+}
+```
+
+Gateway 收到后释放 in-flight 槽位，触发下一批。
+
+### 9.4 push.update_config RPC（可选）
+
+允许客户端在不重连的情况下更新推送配置：
+
+```json
+{
+  "method": "push.update_config",
+  "params": {
+    "push_notify_aid": "push.myapp.com",
+    "push_token": "new-token..."
+  }
+}
+```
+
+---
+
+## 10. push_token 鉴权模型
+
+### 10.1 push_notify_aid 白名单
+
+Gateway 配置允许的 push_notify_aid 白名单，只有白名单内的 AID 才能被设置为推送代理：
+
+- 客户端 connect 时携带的 `push_notify_aid` 不在白名单内 → 忽略该字段，不报错，不存储
+- 白名单为空 → 禁用推送功能
+- 白名单配置在 Gateway 启动配置中，运行时不可动态修改
+
+```json
+{
+  "push": {
+    "allowed_notify_aids": [
+      "push.myapp.com",
+      "push.partner.com"
+    ]
+  }
+}
+```
+
+### 10.2 token 透传模型
+
+```mermaid
+sequenceDiagram
+    participant PNA as push_notify_aid
+    participant GW as Gateway
+
+    Note over PNA,GW: push_token 生命周期
+    PNA->>PNA: 签发 push_token（格式/算法自定）
+    Note over GW: Gateway 存储 push_token（opaque bytes）
+    Note over GW: 不验签、不解析、不判断过期
+    GW->>PNA: event/push.offline_message(..., push_token="xxx")
+    PNA->>PNA: 自己验签 push_token
+    alt token 有效
+        PNA->>PNA: 执行推送
+        PNA->>GW: push.ack(batch_id)
+    else token 无效/过期
+        PNA->>PNA: 丢弃
+        PNA->>GW: push.ack(batch_id)
+        Note over PNA: 客户端下次 connect 带新 token
+    end
+```
+
+**职责划分：**
+
+| 角色 | 职责 |
+|------|------|
+| push_notify_aid | 签发 token、验证 token、决定格式和有效期、处理后 ack |
+| Gateway | 存储 token、透传 token、不解析不验证、管理 in-flight |
+| Client | 向 push_notify_aid 申请 token、connect 时携带 |
+
+---
+
+## 11. 持久化
+
+### push_config 表
+
+```sql
+CREATE TABLE push_config (
+    aid VARCHAR(255) PRIMARY KEY,
+    push_notify_aid VARCHAR(255) NOT NULL,
+    push_token TEXT NOT NULL,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+- 随 connect 写入/更新（UPSERT）
+- 可加内存缓存（TTL 5 分钟）
+
+---
+
+## 12. 边界情况
+
+| 场景 | 处理 |
+|------|------|
+| push_notify_aid 离线 | 事件丢弃，不持久化。推送是 best-effort，消息可靠性由 pull 保证 |
+| 目标 AID 未配置推送 | 不推送，消息正常持久化等对方上线 pull |
+| 目标 AID 上线瞬间 | 清空聚合桶，取消待发推送 |
+| E2EE 消息 | 推送内容只含元数据（发送者、数量），不含密文 |
+| 群组消息 | 群内每个离线成员独立聚合，summary 含 group_ids |
+| push_token 过期 | push_notify_aid 丢弃但仍 ack，客户端下次 connect 刷新 token |
+| ack 超时 | 释放槽位，不重试。后续新消息触发新批次时会包含累积通知 |
+| 同一 AID 多设备不同推送配置 | 以最后一次 connect 为准（单条记录覆盖） |
+| 跨域消息推送 | 由目标 AID 所属域的 Gateway 触发，发送方域不参与 |
+| push_notify_aid 跨域 | 不支持，必须与目标 AID 同域 |

package/_packed_docs/protocol/index.md

@@ -11,7 +11,7 @@
 | 00 | [00-总览与分层.md](00-总览与分层.md) | 协议目标、核心原则、四层架构、三种连接模式、文档导航 |
 | 01 | [01-身份与凭证协议-auth.md](01-身份与凭证协议-auth.md) | `auth.*` 方法定义、AID/证书/私钥/token 关系、JWT 机制 |
 | 02 | [02-证书与信任体系.md](02-证书与信任体系.md) | AID 体系、四级证书链、信任模型、吊销机制 |
-| 03 | [03-Gateway-连接模式.md](03-Gateway-连接模式.md) | Gateway 模式定位、auth.connect 握手、心跳重连 |
+| 03 | [03-Gateway-连接模式.md](03-Gateway-连接模式.md) | Gateway 模式定位、auth.connect 握手、心跳重连 |
 | 04 | [04-Peer-子协议.md](04-Peer-子协议.md) | `peer.*` 对等认证四步握手、nonce 签名、状态机 |
 | 05 | [05-Relay-子协议.md](05-Relay-子协议.md) | `relay.*` 中继注册转发、透明封装、与 peer.* 关系 |
 | 06 | [06-服务协议.md](06-服务协议.md) | 业务层：message.* / meta.* / search.* / task.* / group.* + 跨域消息路由 |
@@ -22,6 +22,7 @@
 | 10 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、邀请码、资源共享、在线状态 |
 | 11 | [11-Storage-子协议.md](11-Storage-子协议.md) | `storage.*` 对象存储、大文件上传下载、预签名 URL |
 | 12 | [12-Stream-子协议.md](12-Stream-子协议.md) | `stream.*` 实时流式传输、WebSocket 推流、HTTP SSE 拉流、跨域拉流 |
+| 15 | [15-离线推送通知协议.md](15-离线推送通知协议.md) | `push.*` 离线推送、push_notify_aid 代理、事件通知 + 背压 ack、白名单与去重 |
 
 **附录**：A-术语表 | B-扩展性 | C-私钥管理 | D-Root CA 治理 | E-Root CA 准入 | F-Issuer CA 申请 | G-孤儿 AID | H-Auth 实现 | I-跨域消息路由 | J-客户端接入 | K-Agent Web | L-E2EE 实现 | M-JWT 实现
 
@@ -41,7 +42,7 @@
 | JWT Token 机制 | 01 §1.7 |
 | 证书续期与轮转（renew/rekey） | 01 §1.6 |
 | Gateway 连接模式 | 03 |
-| auth.connect 握手 | 03 §3.5 |
+| auth.connect 握手 | 03 §3.5 |
 | Peer 对等认证 | 04 |
 | Relay 中继传输 | 05 |
 | 消息收发（message.*） | 06 §6.2 |
@@ -61,6 +62,12 @@
 | 推流（WebSocket） | 12 §12.6 推流端点 |
 | 拉流（HTTP SSE） | 12 §12.6 拉流端点 |
 | 跨域拉流 | 12 §12.7 |
+| 离线推送通知 | 15 |
+| push_notify_aid 推送代理 | 15 §2, §10.1 |
+| push_token 鉴权 | 15 §10 |
+| 推送背压与 in-flight | 15 §5 |
+| 推送去重与频控 | 15 §8.2, §8.4 |
+| 跨域推送 | 15 §7 |
 | 错误码 | 07 §7.1 |
 | 连接状态机 | 07 §7.3 |
 | 威胁模型与安全 | 09 |
@@ -81,7 +88,7 @@
 AID 格式与命名规则、AUN 网络与根证书管理局、四级证书链（Root CA → Registry CA → Issuer CA → Agent）、终端证书生命周期状态、信任模型与共识场景、CRL/OCSP 吊销机制、CT 公开查询入口概述。
 
 ### 03-Gateway-连接模式
-Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* → auth.connect → READY）、auth.connect 请求/响应格式、心跳与重连策略。
+Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* → auth.connect → READY）、auth.connect 请求/响应格式、心跳与重连策略。
 
 ### 04-Peer-子协议
 `peer.*` 4 个方法：hello、hello_reply、confirm、confirmed。对称 challenge-response 双向认证，不依赖 JWT。状态机、证书链验证规则、nonce 签名规则、Peer 地址发现。
@@ -112,3 +119,6 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 
 ### 12-Stream-子协议
 `stream.*` 命名空间完整协议规范。控制面通过 JSON-RPC（stream.create / close / get_info / list_active）管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输。当前实现以 push/pull URL 中的 token 作为能力凭证，拉流可跨域使用，并支持 Late Joiner 回放、Last-Event-ID 断线续拉、空闲/离线超时自动关闭。
+
+### 15-离线推送通知协议
+目标 AID 全部设备离线时的推送机制。push_notify_aid 作为普通客户端 AID 连接 Gateway，通过 `event/push.offline_message` 事件接收推送摘要（仅元数据，不含正文），处理后回 `push.ack` RPC 释放 in-flight 槽位（默认 max_in_flight=1 串行确认，30s 超时不重试）。聚合机制：同一 target_aid 60s 冷却期内合并为一条推送（unread_count++、senders 去重追加）。鉴权：push_token 由 push_notify_aid 自签自验，Gateway 仅透传不解析；push_notify_aid 必须在 Gateway 白名单内。跨域：推送由目标 AID 所属域的 Gateway 触发，push_notify_aid 必须与目标 AID 同域。

package/_packed_docs/python-sdk-v2-only-changelog.md

@@ -0,0 +1,189 @@
+# Python SDK V2-Only 改动清单
+
+基线：`d8b79f44` (v0.2.20 之后，master_1.0.0 分支)
+日期：2026-05-20
+
+## 一、源码改动（`python/src/aun_core/`）
+
+### 1. client.py：8588 行 → 4502 行（净删 4086 行）
+
+#### 删除的 V1 E2EE 代码（共 ~95 个方法）
+
+**V1 P2P 加密：**
+- `_send_encrypted`, `_build_self_sync_copies`, `_build_recipient_device_copies`
+- `_encrypt_copy_payload`, `_ensure_encrypt_result`, `_resolve_self_copy_peer_cert`
+- `_log_e2ee_error`
+
+**V1 群组加密：**
+- `_send_group_encrypted`, `_put_group_thought_encrypted`, `_put_message_thought_encrypted`
+- `_call_group_encrypted_rpc`, `_prepare_group_encrypted_rpc_params`
+
+**V1 Epoch 管理：**
+- `_recover_group_epoch_key`, `_do_recover_group_epoch_key`, `_try_recover_epoch_key_from_server`
+- `_recover_initial_group_epoch_if_needed`, `_request_group_key_from_candidates`
+- `_request_group_key_from_online`, `_request_group_key_from`
+- `_group_epoch_secret_ready_for_recovery`, `_pending_group_secret_still_current`
+- `_ensure_group_epoch_ready`, `_wait_for_group_membership_epoch_floor`
+- `_committed_group_epoch`, `_committed_group_epoch_state`
+- `_ensure_committed_group_secret_for_send`, `_committed_rotation_membership_gap`
+
+**V1 密钥控制面：**
+- `_try_handle_group_key_message`, `_verify_active_group_rotation_distribution`
+- `_verify_group_key_response_epoch`, `_discard_group_distribution_if_stale`
+- `_ack_group_rotation_key`
+
+**V1 Epoch 轮换：**
+- `_build_rotation_signature`, `_attach_rotation_id`, `_build_epoch_encrypted_keys`
+- `_distribute_group_epoch_key`, `_heartbeat_group_rotation`, `_abort_group_rotation`
+- `_schedule_group_rotation_retry`, `_sync_epoch_to_server`
+- `_maybe_lead_rotate_group_epoch`, `_ranked_group_rotation_candidates`, `_rotate_group_epoch`
+- `_delayed_rotate_after_join`, `_maybe_backfill_key_to_joined_member`
+- `_distribute_key_to_new_member`, `_start_group_epoch_tasks`
+- `_is_rotation_leader`, `_group_epoch_rotate_loop`, `_group_epoch_cleanup_loop`
+
+**V1 解密：**
+- `_decrypt_messages`, `_decrypt_single_message`
+- `_decrypt_group_message`, `_decrypt_group_messages`
+- `_decrypt_group_thoughts`, `_decrypt_message_thoughts`
+
+**V1 Pending queue：**
+- `_enqueue_pending_decrypt`, `_schedule_retry_pending_decrypt_msgs`
+- `_retry_pending_decrypt_msgs`, `_schedule_recovery_timeout`, `_cleanup_group_state`
+
+**V1 Prekey：**
+- `_upload_prekey`, `_prekey_refresh_loop`, `_start_prekey_refresh_task`
+- `_schedule_prekey_replenish_if_consumed`, `_invalidate_peer_prekey_cache`
+- `_fetch_peer_prekeys`, `_fetch_peer_prekey`, `_normalize_peer_prekeys`
+- `_refresh_peer_prekeys`, `_clear_peer_cert_cache`
+
+**V1 错误辅助：**
+- `_is_group_epoch_too_old_error`, `_is_group_epoch_rotation_pending_error`
+- `_is_group_epoch_changed_during_send_error`, `_is_recoverable_group_epoch_error`
+- `_is_expected_group_rotation_skip_error`
+
+**V1 成员轮换辅助：**
+- `_membership_rotation_trigger_id`, `_membership_rotation_changed`
+- `_membership_rotation_expected_epoch`, `_extract_group_id_from_result`
+- `_get_group_member_aids`, `_local_group_members_match`, `_extract_group_join_mode`
+- `_group_allows_member_epoch_rotation`, `_group_key_recovery_candidates`
+- `_joined_member_aids_from_payload`
+
+**V1 群组推送处理：**
+- `_process_and_publish_group_message`, `_auto_pull_group_messages`, `_fill_group_gap`
+
+**V1 公开 API：**
+- `e2ee` property, `group_e2ee` property
+- `send_v2`, `pull_v2`, `ack_v2`, `send_group_v2`, `pull_group_v2`, `ack_group_v2`
+  （独立方法合并进 `call()` 路由）
+
+#### 删除的 V1 实例变量
+
+- `self._e2ee` (E2EEManager)
+- `self._group_e2ee` (GroupE2EEManager)
+- `self._pending_decrypt_msgs`
+- `self._recovery_timeout_scheduled`
+- `self._group_epoch_rotation_inflight`
+- `self._group_epoch_rotation_retry_tasks`
+- `self._group_epoch_recovery_inflight`
+- `self._group_membership_rotation_done`
+- `self._group_member_key_backfill_done`
+
+#### 新增/修改的逻辑
+
+- `_on_raw_group_message_created`：简化为明文消息透传 + seq 跟踪（不再做 V1 解密）
+- `_process_and_publish_message`：移除 V1 解密调用，明文直接透传
+- `_on_raw_group_changed`：移除 V1 epoch 轮换编排，保留 V2 `_v2_auto_propose_state` + event gap 检测
+- `call()` 中 `message.pull` / `group.pull` 后处理：移除 V1 解密，保留 seq 跟踪 + auto-ack
+- `_stop_background_tasks`：移除 V1 epoch 任务清理
+- `_start_background_tasks`：移除 `_start_group_epoch_tasks()` 调用
+- V2 解密元数据：`e2ee` 字段增加 `encryption_mode` 和 `forward_secrecy`
+- V2 group pull：移除返回值去重（pull 始终返回所有解密成功的消息）
+
+### 2. seq_tracker.py：+14 行
+
+- `on_pull_result` 新增 `after_seq` 参数
+- gap fill 场景（`after_seq == contiguous_seq`）：直接把 pull 到的最大 seq 作为新 `contiguous_seq`，跳过服务端永久空洞
+
+### 3. `__init__.py`：无变化（`ProtectedHeaders` 保留）
+
+### 4. `e2ee.py`：不动（3544 行保留作为参考）
+
+### 5. 保留的 e2ee.py 引用（非 E2EE 加解密）
+
+- `from .e2ee import ProtectedHeaders` — 纯数据类，V2 也用
+- `from .e2ee import compute_state_hash` (2处) — 群组 state hash 验证工具函数
+
+## 二、测试改动（`python/tests/`）
+
+### 删除的测试文件（纯 V1 E2EE）
+
+- `e2e_test_epoch_key_server.py` — V1 epoch key 服务端托管
+- `integration_test_e2ee.py` — V1 P2P E2EE 集成
+- `integration_test_multi_device_e2ee.py` — V1 多设备 E2EE
+- `unit/test_client_group_e2ee.py` — V1 群组 E2EE 单元测试（93 个用例）
+
+### 删除的测试用例（从现有文件中移除）
+
+- `test_client.py`：24 个 V1 测试（prekey、send_encrypted V1、decrypt_group 等）
+- `test_py_issues.py`：`TestPY004PrekeyRefreshLoop`
+- `test_py_issues_batch2.py`：`TestPY001DecryptFailStillAutoAck`、`TestPY002KeyRecoveryRetry`、`TestPY003DissolveCleanup`、`TestPY005RotateLoopLeaderElection`
+- `test_py_issues_batch3.py`：`TestPY002PushedSeqsLimit`、`TestPY005EpochWait`
+
+### 修改的测试
+
+- `test_client.py`：`test_e2ee_property` 改为断言 `e2ee` 属性不存在
+- `integration_test_storage.py`：自定义 redirect handler 支持 PUT 302 重定向
+
+## 三、服务端改动（`extensions/services/`）
+
+| 文件 | 改动 |
+|------|------|
+| `gateway/entry.py` | kernel event 订阅补全 V2 事件（fallback）；`_handle_event_notification` 路由补全 V2 事件 |
+| `gateway/ws_server.py` | `_dispatch_event_from_service` 白名单补全 `group.state_committed` |
+| `gateway/relay.py` | `_should_forward_event` 补全 `group.state_committed`；`_V2_ONLY_GROUP_METHODS` 补全 `propose_state/confirm_state/get_proposal` |
+| `message/entry.py` | `AUN_DIRECT_EVENT_MESSAGE` 默认改为 True；V2 send 返回 status 对齐 V1 语义（`delivered`/`sent`） |
+| `group/entry.py` | `AUN_DIRECT_EVENT_GROUP` 默认改为 True；`_targets_for_group_event` / `is_client_event` 补全 `group.state_committed`；`_rpc_v2_pull` / `_rpc_v2_ack` 补全成员权限检查 |
+
+## 四、Bug 修复（需要其它 SDK 对齐）
+
+### BUG-1: gap fill 时 contiguous_seq 卡死
+
+**根因：** `on_pull_result` 从 `contiguous_seq` 开始 pull，如果服务端返回的消息跳过了某些 seq（永久空洞：竞态跳跃/未持久化/过期清理），`_try_advance` 逐个检查时会卡在第一个缺失的 seq 上，永远无法推进。新消息被阻塞在 SDK 内部有序队列中，上层收不到。
+
+**修复：** `on_pull_result` 新增 `after_seq` 参数。当 `after_seq == contiguous_seq`（gap fill 场景）时，直接把 pull 到的最大 seq 作为新的 `contiguous_seq`。
+
+**影响范围：** P2P pull、group pull、event pull 三条路径。
+
+### BUG-2: V2 group pull 返回值去重导致手动 pull 拿不到已 push 的消息
+
+**根因：** `_pull_group_v2_internal` 中 `_is_published_seq` 去重导致已通过 push 自动 pull 消费的消息在手动 pull 时被跳过，返回空列表。
+
+**修复：** pull 返回值不再做 `_is_published_seq` 去重。`_publish_ordered_message` 内部仍做事件投递去重（防止重复触发应用层回调），但 pull 的返回值始终包含所有解密成功的消息。
+
+### BUG-3: V2 message.send 返回 status 不对齐 V1 语义
+
+**根因：** V2 send 返回 `"status": "accepted"`，但 SDK 和应用层已按 V1 语义（`sent`/`delivered`）实现。
+
+**修复：** 服务端 `delivered_count > 0` 时返回 `delivered`，否则返回 `sent`。
+
+### BUG-4: V2 解密元数据缺少 encryption_mode
+
+**根因：** V2 解密后 `e2ee` 字段只有 `version` + `suite`，缺少 `encryption_mode` 和 `forward_secrecy`，导致依赖这些字段的测试/应用层判断失败。
+
+**修复：** 补全 `encryption_mode: "v2_{suite}"` 和 `forward_secrecy: True`。
+
+## 五、验证结果
+
+| 测试 | 结果 |
+|------|------|
+| 单元测试 | 501 passed |
+| V2 P2P E2EE | 12/12 |
+| V2 Group E2EE | 8/8 |
+| V2 Multi-device | 6/6 |
+| Echo | 5/5 |
+| Message Ack | 4/4 |
+| Storage | 4/4 |
+| 双域明文 | PASS |
+| 双域加密 | PASS |
+| 双域离线 | PASS |
+| 双域群组 | 2/2 |