@agentunion/fastaun-browser 0.5.19 → 0.5.21

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

@@ -20,12 +20,12 @@
 | `meta.*` | 核心 | 健康检查、状态查询、受信根证书 | meta 服务 | WebSocket |
 | `storage.*` | 扩展 | 对象存储、大文件上传下载（详见 [11-Storage-子协议.md](11-Storage-子协议.md)） | storage 服务 | WebSocket + HTTP |
 | `group.*` | 扩展 | 群组管理、群消息、资源共享（详见 [10-Group-子协议.md](10-Group-子协议.md)） | group 服务 | WebSocket |
-| `mail.*` | 扩展 | 邮件服务 | mail 服务 | WebSocket |
-| `stream.*` | 扩展 | 实时流式传输（详见 [12-Stream-子协议.md](12-Stream-子协议.md)） | stream 服务 | WebSocket + HTTP SSE |
-| `proxy.*` | 扩展 | Service Proxy 服务列表控制面 | Gateway 本地处理 / service_proxy 查询 | WebSocket |
-| `search.*` | 扩展 | Agent 搜索与发现 | search 服务 | WebSocket |
-| `relay.*` | 扩展 | NAT 穿透中继（详见 [05-Relay-子协议.md](05-Relay-子协议.md)） | relay 服务 | WebSocket |
-| `peer.*` | 协议定义 | 点对点直连（详见 [04-Peer-子协议.md](04-Peer-子协议.md)） | 无对应服务 | WebSocket |
+| `mail.*` | 扩展 | 邮件服务 | mail 服务 | WebSocket |
+| `stream.*` | 扩展 | 实时流式传输（详见 [12-Stream-子协议.md](12-Stream-子协议.md)） | stream 服务 | WebSocket + HTTP SSE |
+| `proxy.*` | 扩展 | Service Proxy 服务列表控制面 | Gateway 本地处理 / service_proxy 查询 | WebSocket |
+| `search.*` | 扩展 | Agent 搜索与发现 | search 服务 | WebSocket |
+| `relay.*` | 扩展 | NAT 穿透中继（详见 [05-Relay-子协议.md](05-Relay-子协议.md)） | relay 服务 | WebSocket |
+| `peer.*` | 协议定义 | 点对点直连（详见 [04-Peer-子协议.md](04-Peer-子协议.md)） | 无对应服务 | WebSocket |
 | `task.*` | 协议定义 | Agent 协作与任务执行 | 无对应服务 | WebSocket |
 
 **控制面与数据面分离**：
@@ -36,215 +36,215 @@
 - 大文件、二进制附件、长时流式内容不应直接嵌入 `message.*` 的 `payload`，应先经 `storage.*` 存储，再由 `message.*` 传递对象引用
 - 实现应分别对 `message.*` 的消息体大小和 `storage.*` 的对象大小进行独立限制
 
-**应用层扩展服务**本身也是 AID 持有者，通过核心协议（`message.*`）与客户端通信。客户端可以选择使用或不使用这些扩展服务。
-
----
-
-### 6.2 Service Proxy 服务列表控制面 `proxy.*`
-
-`proxy.*` 是 AUN Service Proxy 的控制面命名空间，用于 provider 通过 Gateway 长连接声明自己能够通过 Service Proxy 暴露哪些服务。它不承载 HTTP/WS 数据面流量；真实访问数据面由 `service_proxy` 模块的独立 proxy-server 隧道处理。
-
-#### 控制面与数据面
-
-- **Gateway 控制面**：provider 的 AUN 长连接调用 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`。Gateway 记录每个 provider 长连接声明的服务摘要，供 `service_proxy` 模块判断 provider 是否在线、是否声明目标服务。
-- **proxy-server 数据面**：service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须再次发送隧道消息 `register_services`。proxy-server 只向已在本地数据面连接并注册目标服务的 provider 隧道转发请求。
-- **服务列表生命周期**：Gateway 控制面服务列表绑定 Gateway 长连接；proxy-server 数据面服务列表绑定 proxy-server 隧道连接。连接断开后对应服务列表必须清理。
-- **一致性要求**：同一 provider AID 的多个实例可以同时在线，但它们注册的服务列表必须一致。这里的一致性以清洗后的服务摘要为准，包括 `service_name`、`service_type`、`visibility` 和非敏感 `metadata`。
-- **粘性路由**：同一 provider AID 的多个实例若提供相同服务，proxy-server 必须对同一访问亲和键保持稳定路由；亲和键可由 requester AID、客户端 IP、provider AID 和服务名组合得到。
-
-#### 服务摘要
-
-服务摘要不得包含内网 endpoint、token、cookie、私钥、证书等敏感字段。实现必须在 Gateway 控制面和 proxy-server 数据面分别清洗摘要，不能依赖共享代码。
-
-```json
-{
-  "service_name": "fileshare",
-  "service_type": "http",
-  "visibility": "public",
-  "metadata": {"label": "Files"}
-}
-```
-
-| 字段 | 必需 | 说明 |
-|------|:----:|------|
-| `service_name` | ✅ | 服务名，只允许小写字母、数字、`_`、`-`；不得使用 `api`、`health`、`proxy`、`ws` 等保留名 |
-| `service_type` | ❌ | 服务类型，默认 `http`；可用于提示 `http` / `sse` / `websocket` / `mcp` / `file` 等 |
-| `visibility` | ❌ | 访问策略，默认 `private`；当前实现支持 `public`、`private`、`aun-auth` |
-| `metadata` | ❌ | 非敏感元数据；实现必须过滤 endpoint、url、token、authorization、cookie、secret、private_key、cert 等敏感键 |
-
-#### `proxy.register_services`
-
-注册当前 Gateway 长连接提供的 Service Proxy 服务列表。服务端必须以连接认证得到的 AID 作为 provider AID；客户端传入的 `provider_aid` 只能作为兼容字段或诊断字段，不能覆盖认证身份。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "reg-1",
-  "method": "proxy.register_services",
-  "params": {
-    "provider_aid": "alice.agentid.pub",
-    "services": [{
-      "service_name": "fileshare",
-      "service_type": "http",
-      "visibility": "public",
-      "metadata": {"label": "Files"}
-    }]
-  }
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "reg-1",
-  "result": {
-    "ok": true,
-    "provider_aid": "alice.agentid.pub",
-    "connection_id": "conn-1",
-    "count": 1,
-    "services": [{
-      "service_name": "fileshare",
-      "service_type": "http",
-      "visibility": "public",
-      "metadata": {"label": "Files"}
-    }]
-  }
-}
-```
-
-#### `proxy.unregister_services`
-
-注销当前 Gateway 长连接上的部分或全部 Service Proxy 服务。省略 `service_names` 时注销该连接全部服务。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "unreg-1",
-  "method": "proxy.unregister_services",
-  "params": {"service_names": ["fileshare"]}
-}
-```
-
-响应包含 `removed` 和剩余 `count`。如果同一 provider AID 还有其他连接，部分注销导致服务列表不一致时，服务端应拒绝该操作。
-
-#### `proxy.list_services`
-
-列出当前 Gateway 长连接已注册的服务摘要。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": "list-1",
-  "method": "proxy.list_services",
-  "params": {}
-}
-```
-
-#### 内部查询 `gateway.query_proxy_services`
-
-`gateway.query_proxy_services` 是 service_proxy 模块调用 Gateway 的内部模块 RPC，不是普通客户端公开方法。调用方必须是 `service_proxy` 模块。
-
-请求参数：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `provider_aid` | ✅ | 被访问 provider AID |
-| `service_name` | ❌ | 目标服务名；为空时只查询 provider 在线和服务列表概览 |
-
-响应字段：
-
-| 字段 | 说明 |
-|------|------|
-| `provider_aid_exists` | Gateway 通过 CA 证书查询确认 provider AID 是否存在；查询失败时为 `null` |
-| `provider_online` | provider 是否存在 Gateway 长连接 |
-| `has_registered_services` | 在线连接中是否已有 proxy 服务列表注册 |
-| `service_registered` | 指定 `service_name` 是否已由在线 provider 注册 |
-| `service_names` | 当前 provider 声明的服务名集合 |
-| `connections` | 已注册服务列表的 Gateway 长连接摘要 |
-| `matched_connections` | 注册了指定服务的 Gateway 长连接摘要 |
-
-#### proxy-server well-known 发现
-
-proxy-client 不得由应用外部传入、配置或硬拼 proxy-server 地址。连接 proxy-server 前必须先执行发现：
-
-1. 优先请求 `https://{provider_aid}/.well-known/aun-proxy`。
-2. 请求失败时回退 `https://proxy.{issuer}/.well-known/aun-proxy`。
-3. 发现结果可缓存到 provider AID 本地 SQLite metadata，缓存 TTL 为 1 小时。
-
-响应示例：
-
-```json
-{
-  "issuer": "agentid.pub",
-  "provider_aid": "alice.agentid.pub",
-  "proxy_host": "proxy.agentid.pub",
-  "https_url": "https://proxy.agentid.pub:19890",
-  "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
-  "proxy_servers": [{
-    "https_url": "https://proxy.agentid.pub:19890",
-    "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
-    "priority": 1
-  }]
-}
-```
-
-proxy-client 连接 `ws_url` 时必须带 `Authorization: Bearer <access_token>`。`access_token` 优先复用本地 cached token；缓存缺失或过期时，必须通过 AUNClient 向 Gateway 完成两步登录取得新 token。
-
-#### proxy-server 隧道注册
-
-service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须发送：
-
-```json
-{
-  "type": "register_services",
-  "request_id": "reg-1",
-  "services": [{
-    "service_name": "fileshare",
-    "service_type": "http",
-    "visibility": "public",
-    "metadata": {"label": "Files"}
-  }]
-}
-```
-
-成功响应：
-
-```json
-{"type": "register_services_ack", "request_id": "reg-1", "ok": true, "count": 1}
-```
-
-若同一 provider AID 的另一条 proxy-server 隧道已注册不同服务列表，proxy-server 必须返回：
-
-```json
-{
-  "type": "service_proxy_error",
-  "request_id": "reg-1",
-  "error": {
-    "code": "proxy_services_inconsistent",
-    "message": "provider service list is inconsistent with existing connections"
-  }
-}
-```
-
-#### 路由与 wakeup 策略
-
-proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等价路由时，必须按以下顺序决策：
-
-1. 本地 proxy-server 连接索引中存在 `(provider_aid, service_name)`：直接选择对应数据面连接；多连接时按亲和键稳定选择。
-2. provider 已连接本 proxy-server 且已注册服务列表，但没有目标服务：返回 `service_not_registered`，不得 wakeup。
-3. provider 未连接本 proxy-server 时，查询 Gateway 控制面：
-   - `provider_aid_exists=false`：返回 `provider_aid_not_found`。
-   - `provider_aid_exists=null`：返回 `provider_aid_check_failed`。
-   - `provider_online=false`：返回 `provider_offline`。
-   - `provider_online=true` 且 `service_registered=false`：返回 `service_not_registered`，不得 wakeup。
-   - `provider_online=true` 且 `service_registered=true`：通过 Gateway 向注册了目标服务的 provider 长连接发送 `app.service_proxy.wakeup`。
-4. wakeup 已投递但本 proxy-server 仍未等到目标服务注册时，返回 `provider_wakeup_timeout`。
-
----
-
-### 6.3 点对点消息 `message.*`
+**应用层扩展服务**本身也是 AID 持有者，通过核心协议（`message.*`）与客户端通信。客户端可以选择使用或不使用这些扩展服务。
+
+---
+
+### 6.2 Service Proxy 服务列表控制面 `proxy.*`
+
+`proxy.*` 是 AUN Service Proxy 的控制面命名空间，用于 provider 通过 Gateway 长连接声明自己能够通过 Service Proxy 暴露哪些服务。它不承载 HTTP/WS 数据面流量；真实访问数据面由 `service_proxy` 模块的独立 proxy-server 隧道处理。
+
+#### 控制面与数据面
+
+- **Gateway 控制面**：provider 的 AUN 长连接调用 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`。Gateway 记录每个 provider 长连接声明的服务摘要，供 `service_proxy` 模块判断 provider 是否在线、是否声明目标服务。
+- **proxy-server 数据面**：service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须再次发送隧道消息 `register_services`。proxy-server 只向已在本地数据面连接并注册目标服务的 provider 隧道转发请求。
+- **服务列表生命周期**：Gateway 控制面服务列表绑定 Gateway 长连接；proxy-server 数据面服务列表绑定 proxy-server 隧道连接。连接断开后对应服务列表必须清理。
+- **一致性要求**：同一 provider AID 的多个实例可以同时在线，但它们注册的服务列表必须一致。这里的一致性以清洗后的服务摘要为准，包括 `service_name`、`service_type`、`visibility` 和非敏感 `metadata`。
+- **粘性路由**：同一 provider AID 的多个实例若提供相同服务，proxy-server 必须对同一访问亲和键保持稳定路由；亲和键可由 requester AID、客户端 IP、provider AID 和服务名组合得到。
+
+#### 服务摘要
+
+服务摘要不得包含内网 endpoint、token、cookie、私钥、证书等敏感字段。实现必须在 Gateway 控制面和 proxy-server 数据面分别清洗摘要，不能依赖共享代码。
+
+```json
+{
+  "service_name": "fileshare",
+  "service_type": "http",
+  "visibility": "public",
+  "metadata": {"label": "Files"}
+}
+```
+
+| 字段 | 必需 | 说明 |
+|------|:----:|------|
+| `service_name` | ✅ | 服务名，只允许小写字母、数字、`_`、`-`；不得使用 `api`、`health`、`proxy`、`ws` 等保留名 |
+| `service_type` | ❌ | 服务类型，默认 `http`；可用于提示 `http` / `sse` / `websocket` / `mcp` / `file` 等 |
+| `visibility` | ❌ | 访问策略，默认 `private`；当前实现支持 `public`、`private`、`aun-auth` |
+| `metadata` | ❌ | 非敏感元数据；实现必须过滤 endpoint、url、token、authorization、cookie、secret、private_key、cert 等敏感键 |
+
+#### `proxy.register_services`
+
+注册当前 Gateway 长连接提供的 Service Proxy 服务列表。服务端必须以连接认证得到的 AID 作为 provider AID；客户端传入的 `provider_aid` 只能作为兼容字段或诊断字段，不能覆盖认证身份。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "reg-1",
+  "method": "proxy.register_services",
+  "params": {
+    "provider_aid": "alice.agentid.pub",
+    "services": [{
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }]
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "reg-1",
+  "result": {
+    "ok": true,
+    "provider_aid": "alice.agentid.pub",
+    "connection_id": "conn-1",
+    "count": 1,
+    "services": [{
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }]
+  }
+}
+```
+
+#### `proxy.unregister_services`
+
+注销当前 Gateway 长连接上的部分或全部 Service Proxy 服务。省略 `service_names` 时注销该连接全部服务。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "unreg-1",
+  "method": "proxy.unregister_services",
+  "params": {"service_names": ["fileshare"]}
+}
+```
+
+响应包含 `removed` 和剩余 `count`。如果同一 provider AID 还有其他连接，部分注销导致服务列表不一致时，服务端应拒绝该操作。
+
+#### `proxy.list_services`
+
+列出当前 Gateway 长连接已注册的服务摘要。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "list-1",
+  "method": "proxy.list_services",
+  "params": {}
+}
+```
+
+#### 内部查询 `gateway.query_proxy_services`
+
+`gateway.query_proxy_services` 是 service_proxy 模块调用 Gateway 的内部模块 RPC，不是普通客户端公开方法。调用方必须是 `service_proxy` 模块。
+
+请求参数：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `provider_aid` | ✅ | 被访问 provider AID |
+| `service_name` | ❌ | 目标服务名；为空时只查询 provider 在线和服务列表概览 |
+
+响应字段：
+
+| 字段 | 说明 |
+|------|------|
+| `provider_aid_exists` | Gateway 通过 CA 证书查询确认 provider AID 是否存在；查询失败时为 `null` |
+| `provider_online` | provider 是否存在 Gateway 长连接 |
+| `has_registered_services` | 在线连接中是否已有 proxy 服务列表注册 |
+| `service_registered` | 指定 `service_name` 是否已由在线 provider 注册 |
+| `service_names` | 当前 provider 声明的服务名集合 |
+| `connections` | 已注册服务列表的 Gateway 长连接摘要 |
+| `matched_connections` | 注册了指定服务的 Gateway 长连接摘要 |
+
+#### proxy-server well-known 发现
+
+proxy-client 不得由应用外部传入、配置或硬拼 proxy-server 地址。连接 proxy-server 前必须先执行发现：
+
+1. 优先请求 `https://{provider_aid}/.well-known/aun-proxy`。
+2. 请求失败时回退 `https://proxy.{issuer}/.well-known/aun-proxy`。
+3. 发现结果可缓存到 provider AID 本地 SQLite metadata，缓存 TTL 为 1 小时。
+
+响应示例：
+
+```json
+{
+  "issuer": "agentid.pub",
+  "provider_aid": "alice.agentid.pub",
+  "proxy_host": "proxy.agentid.pub",
+  "https_url": "https://proxy.agentid.pub:19890",
+  "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
+  "proxy_servers": [{
+    "https_url": "https://proxy.agentid.pub:19890",
+    "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
+    "priority": 1
+  }]
+}
+```
+
+proxy-client 连接 `ws_url` 时必须带 `Authorization: Bearer <access_token>`。`access_token` 优先复用本地 cached token；缓存缺失或过期时，必须通过 AUNClient 向 Gateway 完成两步登录取得新 token。
+
+#### proxy-server 隧道注册
+
+service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须发送：
+
+```json
+{
+  "type": "register_services",
+  "request_id": "reg-1",
+  "services": [{
+    "service_name": "fileshare",
+    "service_type": "http",
+    "visibility": "public",
+    "metadata": {"label": "Files"}
+  }]
+}
+```
+
+成功响应：
+
+```json
+{"type": "register_services_ack", "request_id": "reg-1", "ok": true, "count": 1}
+```
+
+若同一 provider AID 的另一条 proxy-server 隧道已注册不同服务列表，proxy-server 必须返回：
+
+```json
+{
+  "type": "service_proxy_error",
+  "request_id": "reg-1",
+  "error": {
+    "code": "proxy_services_inconsistent",
+    "message": "provider service list is inconsistent with existing connections"
+  }
+}
+```
+
+#### 路由与 wakeup 策略
+
+proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等价路由时，必须按以下顺序决策：
+
+1. 本地 proxy-server 连接索引中存在 `(provider_aid, service_name)`：直接选择对应数据面连接；多连接时按亲和键稳定选择。
+2. provider 已连接本 proxy-server 且已注册服务列表，但没有目标服务：返回 `service_not_registered`，不得 wakeup。
+3. provider 未连接本 proxy-server 时，查询 Gateway 控制面：
+   - `provider_aid_exists=false`：返回 `provider_aid_not_found`。
+   - `provider_aid_exists=null`：返回 `provider_aid_check_failed`。
+   - `provider_online=false`：返回 `provider_offline`。
+   - `provider_online=true` 且 `service_registered=false`：返回 `service_not_registered`，不得 wakeup。
+   - `provider_online=true` 且 `service_registered=true`：通过 Gateway 向注册了目标服务的 provider 长连接发送 `app.service_proxy.wakeup`。
+4. wakeup 已投递但本 proxy-server 仍未等到目标服务注册时，返回 `provider_wakeup_timeout`。
+
+---
+
+### 6.3 点对点消息 `message.*`
 
 **设计原则**：
 
@@ -261,12 +261,16 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | `queue` | 单实例实时消费 | 内存环形缓冲 | 有限时间窗口（默认 5 分钟）+ 有限条数（默认 200 条/AID） | Worker/执行器消费、同一发送者尽量命中同一实例 |
 | `fanout` | 广播到在线实例 | 数据库 + 文件存储 | TTL 过期前持久保存（默认 24 小时） | 离线送达、历史查询、多实例同步接收 |
 
-**序列号机制**：
-
-- `ttl <= 0` 的现有消息在收件人维度分配递增 `seq`
-- `ttl > 0` 的 volatile 消息不分配持久 `seq`，使用独立 opaque `volatile_cursor`
-- 客户端通过 `after_seq` 游标增量拉取，支持多设备各自维护进度
-- `message.pull` 分别读取持久流与 volatile 流，并按服务端创建时间稳定合并
+**序列号机制**：
+
+- `ttl <= 0` 的现有消息在收件人维度分配递增 `seq`
+- `ttl > 0` 的 volatile 消息不分配持久 `seq`，使用独立 opaque `volatile_cursor`
+- 客户端通过 `after_seq` 游标增量拉取，支持多设备各自维护进度
+- `message.pull` 分别读取持久流与 volatile 流，并按服务端创建时间稳定合并
+
+**按对端隔离消费（`p2p_peer_pull_v1`）**：新 SDK 在 `auth.connect.capabilities` 中声明严格布尔值 `p2p_peer_pull_v1: true`。Gateway 将连接能力作为可信认证上下文传给 Message 服务，并在上线、重连后发送待同步提示；能力不由发送消息时的在线状态决定。旧 SDK 继续使用 global Pull/ACK。新 SDK 使用 `cursor_scope="peer"` 与完整 `sender_aid`，按接收方 AID、认证设备、内部消费 slot 和发送方隔离游标；原设备共享 `seq`、消息密文及群组 Pull/ACK 模型保持不变，不分配 `peer_seq`，不逐条回填历史。
+
+首次进入 peer 模式时，服务端原子冻结同设备、同 slot 的旧 `server_acked_seq` 为 `bootstrap_floor_seq`；无旧记录为 0，已有 peer ACK 优先。每个新 peer 从该固定基线初始化，不能用后来变化的旧 global ACK 跳过历史。peer ACK 不推进旧 global ACK；同一设备降级到旧 SDK 可能重拉，应用必须幂等。当前 peer 模式只支持单 Message 服务实例，单实例内可有多个 writer shard；多实例支持留待 AUN 分布式 2.0。
 
 #### `message.send`
 
@@ -278,11 +282,11 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
   "jsonrpc": "2.0",
   "id": 10,
   "method": "message.send",
-  "params": {
-    "to": "bob.aid.pub",
-    "device_id": "bob-phone",
-    "ttl": 300,
-    "payload": {"type": "text", "text": "你好"}
+  "params": {
+    "to": "bob.aid.pub",
+    "device_id": "bob-phone",
+    "ttl": 300,
+    "payload": {"type": "text", "text": "你好"}
   }
 }
 ```
@@ -291,14 +295,15 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
-| `to` | ✅ | 接收者 AID |
-| `device_id` | ❌ | 目标接收设备；指定后只投递该设备，不会降级为 AID 全设备投递 |
-| `to_device_id` | ❌ | `device_id` 的兼容别名 |
-| `ttl` | ❌ | 秒；缺省或 `<=0` 持久化，正数钳制到 1–3600 秒并进入 volatile 内存通道 |
-| `payload` | ✅ | 消息载荷，对协议层透明，由应用层定义 |
+| `to` | ✅ | 接收者 AID |
+| `device_id` | ❌ | 目标接收设备；指定后只投递该设备，不会降级为 AID 全设备投递 |
+| `to_device_id` | ❌ | `device_id` 的兼容别名 |
+| `ttl` | ❌ | 秒；缺省或 `<=0` 持久化，正数钳制到 1–3600 秒并进入 volatile 内存通道 |
+| `payload` | ✅ | 消息载荷，对协议层透明，由应用层定义 |
 | `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
 | `encrypted` | ❌ | E2EE 标记（默认 `false`） |
-| `message_id` | ❌ | 幂等键（客户端提供或服务端生成 UUID） |
+| `message_id` | ❌ | 持久 P2P 的逻辑消息幂等键；新消息使用新的唯一 ID，重试复用原 ID，sender 隔离不扩大复用范围；客户端提供或服务端生成 UUID。volatile 保留原 sender+ID 隔离 |
+| `need_render` | ❌ | 布尔值，默认 `true`；表示消息是否需要应用渲染，不改变拉取顺序或 ACK 规则 |
 | `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
 
 **响应**：
@@ -313,10 +318,12 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
     "status": "sent",
     "delivery_mode": "queue"
   }
-}
-```
-
-正 TTL 消息不写数据库或 WAL、不分配持久 `seq`，响应包含 `storage="volatile"`、`volatile_cursor`（多设备时可含 `volatile_cursors`）、`created_at`、`expires_at` 和 `status="accepted"`。`delivery_mode` 继续控制在线投递方式，不改变 TTL 存储语义。跨域只传递剩余 TTL，目标域不得重新应用 1 秒下限。
+}
+```
+
+正 TTL 消息不写数据库或 WAL、不分配持久 `seq`，响应包含 `storage="volatile"`、`volatile_cursor`（多设备时可含 `volatile_cursors`）、`created_at`、`expires_at` 和 `status="accepted"`。`delivery_mode` 继续控制在线投递方式，不改变 TTL 存储语义。跨域只传递剩余 TTL，目标域不得重新应用 1 秒下限。
+
+`need_render` 同样适用于 `group.send`。SDK 提取后放入明文信封，接收端同时可读取消息顶层该字段；历史缺字段或数据库 NULL 按 `true`。它不进入 E2EE AAD、`protected_headers`、消息保护签名或元数据 HMAC；RPC `client_signature` 仍按既有业务参数签名规则覆盖该参数，不新增 canonical 排除项。
 
 ##### Payload 参考约定
 
@@ -366,9 +373,27 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 - 旧通道在 `peer.switch` 完成前 **MUST** 保持可用
 - 升级失败或超时时双方 **MUST** 回退到原通道
 
+#### `message.peers`
+
+返回当前认证设备、消费 slot 的消息对端目录，不是联系人服务。要求连接已声明 `p2p_peer_pull_v1: true`。
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `filter` | ❌ | 默认 `pending`；只返回有持久待拉取消息或可用 volatile 消息的对端。`all` 返回仍有消息状态的全部对端 |
+| `limit` | ❌ | 仅 `all` 可用，默认 100，范围 1–200 |
+| `page_token` | ❌ | 仅 `all` 可用，复用响应的 `next_page_token` |
+
+`pending` 一次完整返回，不分页、不截断到 200 个 peer，传入分页参数会拒绝。响应包含 `cursor_scope="peer"`、`receiver_aid`、`device_id`、固定的 `bootstrap_floor_seq`、`catalog_ready`、`catalog_revision` 和 `peers`；`all` 另含 `has_more`、`next_page_token`。`catalog_ready=false` 表示目录尚未覆盖可靠读取边界，不能把其空列表当作已同步完成，SDK 保留后台重试。
+
+每个 peer 包含 `sender_aid`、`head_seq`、`server_ack_seq`、`initial_after_seq`、`initialization_source`、`retention_floor_seq`、`earliest_available_seq` 和 `volatile_has_more`。正常 `pending` 直接从同一游标表的 peer A/H 筛选持久候选：内部 `peer_H>A` 且 `peer_H>R`，再合并可用 volatile sender；不扫描消息积压、不逐 peer seek，也不执行 COUNT/SUM。候选可以保守偏大，完成仍由 Forward 覆盖证明及 ACK 确认；不返回每 peer 或整体的 `pending_count`、`need_render_pending_count`、`non_render_pending_count` 三项精确计数。
+
+`peers[].next_pending_seq` 是可选排序近似；正常 `pending` 的持久候选直接返回该 peer 的 `server_ack_seq`（A），包含 0，`all` 或 volatile-only 允许省略。它不是首条未确认投递的真实 seq，无需额外查询或 SQL 往返；仅用于 SDK 调度，不是覆盖证明、可提交游标或完成依据，不能由它推进 A/H，也不能用 `covered_through_seq+1` 推导下一提示。公共 S 不用于抬高某个 peer 的 Forward 扫描起点，仍按该 peer ACK 与永久保留边界校验。
+
+响应顶层可选 `pending_count_estimate=max(0,H-max(R,S_used))`：H 是当前设备已知可靠 Head，R 是已证明永久不可取得的前缀，S_used 是当前消费 slot 的有效公共安全前缀；S 缺失或 S>H 时按 0 使用，H 未知时省略字段。它是整体持久 seq 跨度上界，可含空号及 S 后已 ACK 的消息，不含 volatile，不是精确条数、未读数或 all 单页数量。SDK 仅透传给应用，不能缺省填 0、对 peer 求和或据此调度/推进游标/判断同步完成。volatile-only peer 在估计为 0 或缺省时仍须返回与同步。
+
 #### `message.pull`
 
-按两个独立游标拉取持久消息和 volatile 消息。volatile 消息不进入持久 `seq` 空间。
+按持久和 volatile 两个独立游标拉取消息。以下请求/响应示例表示旧 global 路径；peer 路径增加 `cursor_scope="peer"`、`sender_aid`，持久页默认及最大 200 条，volatile 游标同样按 peer 隔离。
 
 **请求**：
 ```json
@@ -376,11 +401,11 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
   "jsonrpc": "2.0",
   "id": 11,
   "method": "message.pull",
-  "params": {
-    "after_seq": 0,
-    "after_volatile_cursor": "v1:i1:7:20",
-    "limit": 50,
-    "device_id": "device-001"
+  "params": {
+    "after_seq": 0,
+    "after_volatile_cursor": "v1:i1:7:20",
+    "limit": 50,
+    "device_id": "device-001"
   }
 }
 ```
@@ -389,11 +414,19 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
-| `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
-| `after_volatile_cursor` | ❌ | opaque volatile 游标；四个 SDK 自动维护，应用通常无需传入 |
-| `limit` | ❌ | 单次返回上限（默认 50，最大 50） |
-| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
-| `window_mode` | ❌ | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
+| `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
+| `after_volatile_cursor` | ❌ | opaque volatile 游标；四个 SDK 自动维护，应用通常无需传入 |
+| `limit` | ❌ | 单次返回上限（默认 50，最大 50） |
+| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
+| `window_mode` | ❌ | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
+| `cursor_scope` | ❌ | 旧请求缺省 `global`；新 SDK 使用 `peer`，须有连接能力声明 |
+| `sender_aid` | peer 必需 | 完整发送方 AID，只返回该对端消息；global 请求不得携带此字段 |
+
+peer Forward 响应另含 `cursor_scope`、`sender_aid`、`scan_after_seq`、`covered_through_seq`、`next_after_seq`、`head_seq`、`server_ack_seq`、`persistent_has_more`、`volatile_has_more`、`has_more`、可选 `next_pending_seq`、`page_need_render_count` 和 `page_non_render_count`。固定可靠 Head 后，扫描 `(scan_after_seq, covered_through_seq]`，下一页使用 `next_after_seq=covered_through_seq`；原 seq 在不同 sender 之间共享，peer 页可稀疏，不能由相邻数字或返回条数推断缺消息。三个 `has_more` 必须为布尔值，且 `has_more = persistent_has_more OR volatile_has_more`。`count` 与两类页内数量按最终返回消息在内存计算，包含本页 volatile，不扫描全部积压；计数不改变扫描范围，不优先过滤可渲染消息。
+
+`next_pending_seq` 是 peer Forward（含 force）的可选调度提示：`persistent_has_more=true` 时，返回本页最终边界之后首条未返回持久投递的原 seq，满足 `covered_through_seq < seq <= head_seq`；无持久更多时省略，only-volatile 仍按 `volatile_has_more` 继续。它直接复用原 `limit+1` 查询和去重合并结果：200 条页取第 201 条，字节截断取第一条未返回持久消息，volatile 混排挤掉持久消息时修正为最终第一条未返回持久 seq，不新增 SQL。Tail/History/旧 global 不增加此字段。正常 Forward 在消息页可靠 commit 后即可将页提示用于排序，不等待 ACK；仅收到响应或 commit 失败不能采用，ACK 未完成或失败保留独立确认责任，拒绝旧/迟到页回退；Tail/force/History 不更新正常调度。非法或缺失的可选提示不使合法消息页失败，不能用 `covered_through_seq+1` 推导，也不参与覆盖、ACK 或完成判断。
+
+`server_ack_seq` 只可用于首次 peer 初始化，运行中的 SDK 不得据此跳过本地未交付区间；合法 `retention_floor_seq` 才能解释已经永久不可取得的前缀。peer 内解密或应用交付未完成时，不得仅凭扫描覆盖证明推进 A/ACK。
 
 **响应**：
 ```json
@@ -424,69 +457,70 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 |------|------|------|
 | `messages` | array | 消息列表（临时 + 持久化合并，按 `seq` 排序） |
 | `count` | integer | 本次返回的消息条数 |
-| `latest_seq` | integer | 本次返回的最大 `seq` |
-| `latest_volatile_cursor` | string\|null | 本页最后一个 volatile 游标；不改变 `latest_seq` |
-| `volatile_has_more` | boolean | 是否仍有未返回的 volatile 消息；SDK 在 volatile 游标前进时据此继续分页 |
-| `volatile_earliest_cursor` | string\|null | 当前 boot epoch 内仍可读取的最早 volatile 游标 |
-| `volatile_dropped_count` | integer | 当前 boot epoch 内因过期或容量淘汰而不可读的累计数 |
+| `latest_seq` | integer | 本次返回的最大 `seq` |
+| `latest_volatile_cursor` | string\|null | 本页最后一个 volatile 游标；不改变 `latest_seq` |
+| `volatile_has_more` | boolean | 是否仍有未返回的 volatile 消息；SDK 在 volatile 游标前进时据此继续分页 |
+| `volatile_earliest_cursor` | string\|null | 当前 boot epoch 内仍可读取的最早 volatile 游标 |
+| `volatile_dropped_count` | integer | 当前 boot epoch 内因过期或容量淘汰而不可读的累计数 |
 | `ephemeral_earliest_available_seq` | integer\|null | 当前临时缓冲中最早可用的 `seq`，`null` 表示无临时消息 |
 | `ephemeral_dropped_count` | integer | 因缓冲淘汰而丢弃的临时消息计数 |
 
-> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
-
-**说明**：持久游标与 volatile 游标独立推进。SDK 只把含正 `seq` 的消息送入持久 tracker；volatile push/pull 按发送方和 `message_id` 去重，交付成功后自动 ACK。SDK 在传输层注入内部 slot，应用不得传入或读取，任何消息、响应和事件都不得包含该字段。epoch 不匹配时 SDK 清空 volatile 游标并重试一次。`message.history` 不返回 volatile 消息。
-
-**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 与 volatile ACK 可以单独提交，也可以在同一请求中提交。
+> 客户端可通过 `ephemeral_earliest_available_seq` 判断是否有临时消息丢失：若 `after_seq < ephemeral_earliest_available_seq`，说明存在已被淘汰的消息。
+
+**说明**：持久游标与 volatile 游标独立推进。SDK 只把含正 `seq` 的消息送入持久 tracker；volatile push/pull 按发送方和 `message_id` 去重，交付成功后自动 ACK。SDK 在传输层注入内部 slot，应用不得传入或读取，任何消息、响应和事件都不得包含该字段。epoch 不匹配时 SDK 清空 volatile 游标并重试一次。`message.history` 不返回 volatile 消息。
+
+**Tail 模式**：`window_mode="tail"` 时，服务端固定安全 `head_seq`；global 返回跨度不超过 `limit` 的最新 seq band，peer 按该 sender 最新消息条数取页，seq 跨度可大于 `limit`。额外返回：
+
+| 字段 | 说明 |
+|------|------|
+| `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`。Tail 使用窗口证明，不要求 Forward 的三个 `has_more` 字段。global seq band 内未返回的序号视为服务端永久空号；peer 仅按服务端覆盖证明合并窗口，不能套用 dense seq 校验。新 SDK 仅在已验证自身 `agent.md.type=human` 时自动优先 Tail 再 Forward；其他或未知类型直接 Forward。无 `window_mode` 的旧 global 请求保持原副作用语义。
+
+#### `message.history`
+
+按 `before_seq` 排他上界向前只读翻页，不修改 ACK、cursor、floor 或 Pull activity。
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `before_seq` | ✅ | 正整数排他上界，只返回 `seq < before_seq` 的消息 |
+| `limit` | ❌ | 单页上限（默认 50，最大 50） |
+| `cursor_scope` / `sender_aid` | peer 必需 | 与 Pull 相同；peer 页默认及最大 200 条，隔离读取该 sender 历史 |
+
+**响应字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `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。
+
+**客户端发布语义**：peer 页内按 seq 升序处理；SDK 在当前运行实例内协调并发交付，并以最多 50,000 条的内存成功绑定去重，按接收 AID、设备、消费 slot、事件类别和原正 delivery seq 识别投递，校验 sender 与 `message_id`，不因 namespace 或 Push/Pull/Tail 来源另造身份。消息热路径不逐条读写耐久 receipt，自定义 store 不要求提供 receipt 能力。应用 handler 成功后才完成内存标记，peer 持久消息 Forward 页依据有效 proof 提交页 A/T/H 后发送本页新增累计 ACK；使用持久化 store 时保存页状态。内存淘汰、重建 client、崩溃或版本切换后允许重放，应用须在业务事务中按消息身份持久幂等；多个 client/进程不提供跨实例首次回调原子 claim。跨 peer 不承诺全局回调顺序，显式 History/force/Tail 列表不因内存去重删行；History 不进入实时发布流。
+
+#### `message.ack`
+
+确认已收到消息。持久 ACK 与 volatile ACK 可以单独提交，也可以在同一请求中提交。
 
 **请求**：
 ```json
 {
   "jsonrpc": "2.0",
   "id": 12,
-  "method": "message.ack",
-  "params": {
-    "seq": 43,
-    "volatile_cursors": ["v1:i1:7:21"],
-    "device_id": "device-001"
+  "method": "message.ack",
+  "params": {
+    "seq": 43,
+    "volatile_cursors": ["v1:i1:7:21"],
+    "device_id": "device-001"
   }
 }
 ```
@@ -495,11 +529,12 @@ History 不触发实时消息事件。客户端解密 History 结果时不得修
 
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
-| `seq` | ❌ | 确认到的持久序列号（含）；未提交 volatile ACK 时必填 |
-| `volatile_cursor` | ❌ | 单个 volatile 游标的兼容形式 |
-| `volatile_cursors` | ❌ | 要确认的 volatile 游标数组 |
-| `volatile_ids` | ❌ | 要按 `message_id` 确认的 volatile 消息数组 |
-| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
+| `seq` | ❌ | 确认到的持久序列号（含）；未提交 volatile ACK 时必填 |
+| `volatile_cursor` | ❌ | 单个 volatile 游标的兼容形式 |
+| `volatile_cursors` | ❌ | 要确认的 volatile 游标数组 |
+| `volatile_ids` | ❌ | 要按 `message_id` 确认的 volatile 消息数组 |
+| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
+| `cursor_scope` / `sender_aid` | peer 必需 | 按 peer 确认；持久水位使用 `up_to_seq`，兼容 `seq` / `ack_seq` |
 
 **响应**：
 ```json
@@ -510,7 +545,9 @@ History 不触发实时消息事件。客户端解密 History 结果时不得修
 }
 ```
 
-**说明**：`ack_seq` 仅增不减；volatile 结果通过 `volatile_ack` 返回 `accepted`、`expired` 等幂等计数。服务端内部按消费 slot 隔离 lease，但 slot 不属于对外协议对象。
+**说明**：`ack_seq` 仅增不减；volatile 结果通过 `volatile_ack` 返回 `accepted`、`expired` 等幂等计数。服务端内部按消费 slot 隔离 lease，但 slot 不属于对外协议对象。
+
+peer 响应以 `peer_ack_seq` / `effective_ack_seq` 表示该 sender 的确认水位，不能把 `ack_seq` 当作 peer ACK。可选 `legacy_safe_ack_seq` 与 `previous_legacy_safe_ack_seq` 表示当前消费 slot 的公共安全前缀 S 及原值，不写回旧 global ACK。服务端在同一 `message_peer_slot_cursor` 表以真实 sender 行保存 peer ACK Ap、内部 `sender_aid='*'` 行保存同 owner/device/slot 的 S，与 ACK 同 RR 事务原子持久，单调且不得超过可靠 H；`*` 不对外接受或枚举。bootstrap G 独立冻结，不用 S 替代；来源或潜在 legacy 低位迁入不明时不提高 S。本期不新增设备级聚合游标行；缺完整持久设备 slot 名册时 `device_safe_ack_seq` 可省略，SDK 不得由单 peer 或单 slot 的水位推断设备全部旧密钥可销毁。
 
 #### `message.recall`
 
@@ -603,9 +640,9 @@ History 不触发实时消息事件。客户端解密 History 结果时不得修
 {
   "jsonrpc": "2.0",
   "method": "event/message.received",
-  "params": {
-    "from": "bob.aid.pub",
-    "sender_device_id": "bob-phone",
+  "params": {
+    "from": "bob.aid.pub",
+    "sender_device_id": "bob-phone",
     "to": "alice.aid.pub",
     "message_id": "550e8400-...",
     "seq": 42,
@@ -614,10 +651,12 @@ History 不触发实时消息事件。客户端解密 History 结果时不得修
     "delivery_mode": "queue",
     "encrypted": false
   }
-}
-```
-
-volatile 事件包含 `storage="volatile"`、`volatile_cursor`、`created_at`、`expires_at`，不含持久 `seq` 或内部 slot。`sender_device_id` 始终表示发送方设备，可用于下一次定向发送。
+}
+```
+
+volatile 事件包含 `storage="volatile"`、`volatile_cursor`、`created_at`、`expires_at`，不含持久 `seq` 或内部 slot。`sender_device_id` 始终表示发送方设备，可用于下一次定向发送。
+
+peer 连接按接收 AID、设备及 sender 折叠待拉取通知；上线恢复可以只发 `cursor_scope="peer"` 的同步提示，由 SDK 调用完整 pending `message.peers` 后并行拉取，不能把提示的 0 seq 当作消息水位。可信消息元数据可携带 `prev_peer_seq`，表示同接收设备、同 sender 的前一条原 seq；未知时省略，只有可证明为首条才返回 0。若本地 A=103 收到 seq=105，前驱为103时可确认相接，前驱大于103则需要补拉；缺前驱时保守交由 peer Forward 覆盖证明判断，不能仅由105−103认定 Gap。
 
 #### `event/message.ack`
 
@@ -628,17 +667,19 @@ volatile 事件包含 `storage="volatile"`、`volatile_cursor`、`created_at`、
   "jsonrpc": "2.0",
   "method": "event/message.ack",
   "params": {
-    "to": "bob.aid.pub",
-    "device_id": "device-001",
-    "ack_seq": 43,
+    "to": "bob.aid.pub",
+    "device_id": "device-001",
+    "ack_seq": 43,
     "timestamp": 1709712003
   }
 }
 ```
 
-- `to`：确认方 AID
-- `device_id`：触发 ack 的设备标识；legacy 客户端为空字符串
-- `ack_seq`：确认到的序列号（含该 seq 及之前的所有消息）
+- `to`：确认方 AID
+- `device_id`：触发 ack 的设备标识；legacy 客户端为空字符串
+- `ack_seq`：确认到的序列号（含该 seq 及之前的所有消息）
+
+peer 能力连接收到的 peer ACK 通知使用 `cursor_scope="peer"`、`sender_aid` 和 `peer_ack_seq`，不得用它推进旧 global 游标或其他 peer。旧 ACK 通知不能替代新 SDK 的本地交付证明；投递 ACK 不表示应用业务已读。
 
 #### `event/message.recalled`
 
@@ -664,7 +705,7 @@ volatile 事件包含 `storage="volatile"`、`volatile_cursor`、`created_at`、
 
 ---
 
-### 6.4 元协议 `meta.*`
+### 6.4 元协议 `meta.*`
 
 #### `meta.ping`
 
@@ -800,7 +841,7 @@ Issuer 必须通过 `https://ct.{issuer}` 提供证书透明日志（CT）的公
 
 ---
 
-### 6.5 搜索与发现 `search.*`
+### 6.5 搜索与发现 `search.*`
 
 `search.*` 定义 AUN 中 Agent 的公开发现机制，围绕 `agent.md` 工作：
 
@@ -1048,7 +1089,7 @@ tags:
 
 ---
 
-### 6.6 Agent 协作与任务 `task.*`
+### 6.6 Agent 协作与任务 `task.*`
 
 `task.*` 用于表达 Agent 之间的长生命周期协作任务，参考 A2A 的 task 机制，对齐 AUN 特点：
 
@@ -1339,27 +1380,27 @@ event/task.delegated      # 已创建子任务
 
 ---
 
-### 6.7 端到端加密（E2EE）摘要
+### 6.7 端到端加密（E2EE）摘要
 
-> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
+> 当前 V2 主路径见 [E2EE V2 消息通信时序图](../sdk/E2EE_V2消息通信时序图.md)；群组规范见 [08-AUN-E2EE-Group](08-AUN-E2EE-Group.md)。[08-AUN-E2EE](08-AUN-E2EE.md) 仅说明 Legacy 信封。
 
 **核心原则**：
 
 - E2EE 加解密**完全由客户端实现**，无需在线协商
 - 服务端只做消息中转和 prekey 存储，对加密内容完全透明
-- 加密消息通过 `message.send` 的 `encrypted: true` 标志标识
-- 两级降级：prekey_ecdh_v2（优先，四路 ECDH）→ long_term_key（降级）
+- 当前 P2P 使用 `message.send` 承载 `e2ee.p2p_encrypted` 信封，群组使用 `group.v2.send` 承载 `e2ee.group_encrypted` 信封
+- 当前默认每消息独立密钥，按设备使用 `3DH` / `1DH` wrap；`prekey_ecdh_v2` / `long_term_key` 仅用于 Legacy 兼容
 
 **服务端兼容性要求**：
 
-- 接受并转发 `encrypted: true` 的消息
+- 接受并转发当前 V2 加密信封及 Legacy `encrypted: true` 消息
 - 在离线队列和历史消息中存储密文 payload
 - 不对密文 payload 施加额外的语义解析要求
-- 提供 `message.e2ee.put_prekey` / `message.e2ee.get_prekey` RPC
+- 当前 P2P 设备 SPK 使用 `message.v2.put_peer_pk` / `message.v2.bootstrap`；`message.e2ee.put_prekey` / `message.e2ee.get_prekey` 仅为 Legacy 兼容
 
 **互操作要求**：
 
-跨语言、跨平台 SDK 的互操作必须以 [08-AUN-E2EE.md](08-AUN-E2EE.md) 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。
+跨语言、跨平台 SDK 必须按当前 V2 路径保持算法、信封、AAD 与 recipient proof 一致；旧格式才适用 [Legacy E2EE 规范](08-AUN-E2EE.md)，不得用旧信封替代默认 V2 发送格式。
 
 **错误码**：
 
@@ -1369,7 +1410,7 @@ event/task.delegated      # 已创建子任务
 
 ---
 
-### 6.8 跨域消息路由
+### 6.8 跨域消息路由
 
 **当前实现事实**：