@agentunion/fastaun-browser 0.5.20 → 0.5.21

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

@@ -1,1392 +1,1433 @@
-## 6. 服务协议（业务层）
-
-> 本文描述认证完成后的业务层方法。连接与身份认证见对应子协议文档：
-> - 身份与凭证：[01-身份与凭证协议-auth.md](01-身份与凭证协议-auth.md)
-> - Gateway 连接：[03-Gateway-连接模式.md](03-Gateway-连接模式.md)
-> - Peer 对等认证：[04-Peer-子协议.md](04-Peer-子协议.md)
-> - Relay 中继：[05-Relay-子协议.md](05-Relay-子协议.md)
->
-> 业务层方法与连接拓扑无关。无论使用 gateway、peer 或 relay 模式，认证完成后都可调用以下方法。
-
----
-
-### 6.1 命名空间概览
-
-| 命名空间 | 分类 | 功能 | 对应服务 | 传输方式 |
-|---------|------|------|---------|---------|
-| `auth.*` | 核心 | AID 注册、认证、令牌管理 | auth 服务 | WebSocket |
-| `ca.*` | 核心 | 证书签发、续期、吊销 | ca 服务 | WebSocket / HTTP |
-| `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 |
-| `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 |
-
-**控制面与数据面分离**：
-
-- `message.*` 用于传递消息语义、小型结构化负载和控制信息，不承担大对象传输职责
-- `storage.*` 用于承载大文件、大对象及附件内容的上传、下载与持久保存
-- `stream.*` 用于实时流式传输（LLM 输出、数据推送等），控制面通过 RPC 管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输
-- 大文件、二进制附件、长时流式内容不应直接嵌入 `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.*`
-
-**设计原则**：
-
-- **无会话生命周期**：不需要 create/invite/join/close 流程，直接发送即可
-- **投递语义由 `delivery_mode` 决定**：`fanout` 会进入离线历史并广播到同一 AID 的在线实例；`queue` 只做实时单实例投递，不进入历史存储
-- **控制面与数据面分离**：`message.*` 承载消息语义和小型结构化数据；附件、大对象应通过 `storage.*` 传输，消息中只保留引用
-
-> 本节仅适用于 P2P `message.*`。`group.send` 不支持 `queue`，群消息始终是 fanout 语义。
-
-**消息存储模型**：
-
-| `delivery_mode.mode` | 投递方式 | 存储位置 | 生命周期 | 适用场景 |
-|----------------------|----------|---------|---------|---------|
-| `queue` | 单实例实时消费 | 内存环形缓冲 | 有限时间窗口（默认 5 分钟）+ 有限条数（默认 200 条/AID） | Worker/执行器消费、同一发送者尽量命中同一实例 |
-| `fanout` | 广播到在线实例 | 数据库 + 文件存储 | TTL 过期前持久保存（默认 24 小时） | 离线送达、历史查询、多实例同步接收 |
-
-**序列号机制**：
-
-- `ttl <= 0` 的现有消息在收件人维度分配递增 `seq`
-- `ttl > 0` 的 volatile 消息不分配持久 `seq`，使用独立 opaque `volatile_cursor`
-- 客户端通过 `after_seq` 游标增量拉取，支持多设备各自维护进度
-- `message.pull` 分别读取持久流与 volatile 流，并按服务端创建时间稳定合并
-
-#### `message.send`
-
-发送 P2P 消息。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 10,
-  "method": "message.send",
-  "params": {
-    "to": "bob.aid.pub",
-    "device_id": "bob-phone",
-    "ttl": 300,
-    "payload": {"type": "text", "text": "你好"}
-  }
-}
-```
-
-**参数**：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `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） |
-| `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 10,
-  "result": {
-    "message_id": "550e8400-e29b-41d4-a716-446655440000",
-    "seq": 42,
-    "timestamp": 1709712000,
-    "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 秒下限。
-
-##### Payload 参考约定
-
-`message.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整 P2P 请求仍在 `payload` 同级传入 `to`；业务类型放在 `payload.type`，不要与 `message.send.params.type` 信封/封装类型混用。
-
-协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小限制；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
-
-#### 连接升级控制消息
-
-`peer.offer` / `peer.accept` / `peer.reject` / `peer.switch` 不是独立 JSON-RPC 方法，而是通过普通 `message.send` 发送的**协议控制负载**。三种连接模式在业务层复用统一的 `message.*`。
-
-**用途**：
-
-- `gateway → peer`：通过 Gateway 交换直连地址，尝试升级到 Peer
-- `relay → peer`：已通过 Relay 联通的双方尝试升级到直连
-- 失败时可回退到原有通道，不影响业务层 API
-
-**`peer.offer` 示例**：
-```json
-{
-  "method": "message.send",
-  "params": {
-    "to": "bob.company.com",
-    "payload": {
-      "type": "peer.offer",
-      "session_id": "upgrade-550e8400",
-      "from_mode": "gateway",
-      "preferred_mode": "peer",
-      "endpoints": [{"url": "wss://alice.company.com:9900/acp", "priority": 1}],
-      "expires_in": 30
-    },
-    "delivery_mode": {"mode": "queue"}
-  }
-}
-```
-
-**`peer.accept` 负载**：`{ "type": "peer.accept", "session_id": "...", "selected_endpoint": "wss://..." }`
-
-**`peer.reject` 负载**：`{ "type": "peer.reject", "session_id": "...", "reason": "policy_denied" }`
-
-**`peer.switch` 负载**：`{ "type": "peer.switch", "session_id": "...", "new_mode": "peer", "keep_fallback": true }`
-
-**规范要求**：
-
-- 接收方 **MAY** 接受或拒绝 `peer.offer`
-- 接受后，双方 **MUST** 在新通道上重新执行完整 `initialize(mode=peer)` 与 `peer.*` 认证流程
-- 旧通道在 `peer.switch` 完成前 **MUST** 保持可用
-- 升级失败或超时时双方 **MUST** 回退到原通道
-
-#### `message.pull`
-
-按两个独立游标拉取持久消息和 volatile 消息。volatile 消息不进入持久 `seq` 空间。
-
-**请求**：
-```json
-{
-  "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"
-  }
-}
-```
-
-**参数**：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
-| `after_volatile_cursor` | ❌ | opaque volatile 游标；四个 SDK 自动维护，应用通常无需传入 |
-| `limit` | ❌ | 单次返回上限（默认 50，最大 50） |
-| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
-| `window_mode` | ❌ | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 11,
-  "result": {
-    "messages": [{
-      "message_id": "550e8400-...",
-      "seq": 43,
-      "from": "alice.aid.pub",
-      "to": "bob.aid.pub",
-      "timestamp": 1709712000,
-      "payload": {"type": "text", "text": "你好"},
-      "delivery_mode": "fanout"
-    }],
-    "count": 1,
-    "latest_seq": 43,
-    "ephemeral_earliest_available_seq": 38,
-    "ephemeral_dropped_count": 5
-  }
-}
-```
-
-**响应字段**：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `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 内因过期或容量淘汰而不可读的累计数 |
-| `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 可以单独提交，也可以在同一请求中提交。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 12,
-  "method": "message.ack",
-  "params": {
-    "seq": 43,
-    "volatile_cursors": ["v1:i1:7:21"],
-    "device_id": "device-001"
-  }
-}
-```
-
-**参数**：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `seq` | ❌ | 确认到的持久序列号（含）；未提交 volatile ACK 时必填 |
-| `volatile_cursor` | ❌ | 单个 volatile 游标的兼容形式 |
-| `volatile_cursors` | ❌ | 要确认的 volatile 游标数组 |
-| `volatile_ids` | ❌ | 要按 `message_id` 确认的 volatile 消息数组 |
-| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 12,
-  "result": {"success": true, "ack_seq": 43}
-}
-```
-
-**说明**：`ack_seq` 仅增不减；volatile 结果通过 `volatile_ack` 返回 `accepted`、`expired` 等幂等计数。服务端内部按消费 slot 隔离 lease，但 slot 不属于对外协议对象。
-
-#### `message.recall`
-
-撤回消息。仅发送方可撤回，受时间窗口限制（默认 2 分钟）。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 13,
-  "method": "message.recall",
-  "params": {"message_ids": ["uuid-1", "uuid-2"]}
-}
-```
-
-**参数**：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `message_ids` | ✅ | 要撤回的消息 ID 列表（最多 100 个） |
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 13,
-  "result": {
-    "success": true,
-    "accepted": 2,
-    "recalled": 1,
-    "errors": [{"message_id": "uuid-2", "error": "expired"}]
-  }
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `success` | boolean | 操作是否执行 |
-| `accepted` | integer | 接收的 message_id 数 |
-| `recalled` | integer | 实际撤回数 |
-| `errors` | array\|null | 失败项，错误码：`not_found` / `not_sender` / `already_recalled` / `expired` |
-
-**说明**：撤回成功后向接收方推送 `event/message.recalled` 事件。仅 `delivery_mode.mode = "fanout"` 的消息支持撤回；`queue` 消息不进入历史，无法可靠追溯。
-
-#### `message.query_online`
-
-批量查询 AID 在线状态。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 14,
-  "method": "message.query_online",
-  "params": {"aids": ["alice.aid.pub", "bob.example.com"]}
-}
-```
-
-**参数**：
-
-| 参数 | 必需 | 说明 |
-|------|:----:|------|
-| `aids` | ✅ | 要查询的 AID 列表（最多 100 个） |
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 14,
-  "result": {
-    "online": {
-      "alice.aid.pub": true,
-      "bob.example.com": false
-    }
-  }
-}
-```
-
-**当前实现说明**：
-
-- 本域 AID 直接由 message 服务本地在线跟踪器返回
-- 外域 AID 通过 `gateway.forward_federation` 转发到目标域查询
-- 当前实现中，若某个外域查询失败，该域内 AID 会回落为 `false`
-
-#### `event/message.received`
-
-收到 P2P 消息事件。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "event/message.received",
-  "params": {
-    "from": "bob.aid.pub",
-    "sender_device_id": "bob-phone",
-    "to": "alice.aid.pub",
-    "message_id": "550e8400-...",
-    "seq": 42,
-    "payload": {"type": "text", "text": "你好"},
-    "timestamp": 1709712005,
-    "delivery_mode": "queue",
-    "encrypted": false
-  }
-}
-```
-
-volatile 事件包含 `storage="volatile"`、`volatile_cursor`、`created_at`、`expires_at`，不含持久 `seq` 或内部 slot。`sender_device_id` 始终表示发送方设备，可用于下一次定向发送。
-
-#### `event/message.ack`
-
-消息确认事件（通知发送方消息已被接收方确认）。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "event/message.ack",
-  "params": {
-    "to": "bob.aid.pub",
-    "device_id": "device-001",
-    "ack_seq": 43,
-    "timestamp": 1709712003
-  }
-}
-```
-
-- `to`：确认方 AID
-- `device_id`：触发 ack 的设备标识；legacy 客户端为空字符串
-- `ack_seq`：确认到的序列号（含该 seq 及之前的所有消息）
-
-#### `event/message.recalled`
-
-消息被撤回事件（通知接收方消息已被发送方撤回）。
-
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "event/message.recalled",
-  "params": {
-    "from": "alice.aid.pub",
-    "to": "bob.aid.pub",
-    "message_ids": ["uuid-1"],
-    "timestamp": 1709712000
-  }
-}
-```
-
-- `from`：发送方（撤回者）AID
-- `to`：接收方 AID
-- `message_ids`：被撤回的消息 ID 列表
-- `timestamp`：服务端时间戳（毫秒）
-
----
-
-### 6.4 元协议 `meta.*`
-
-#### `meta.ping`
-
-健康检查。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 30, "method": "meta.ping"}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 30, "result": {"pong": true, "timestamp": 1709712000}}
-```
-
-#### `meta.status`
-
-查询当前连接状态。
-
-**当前实现事实**：
-
-- `meta.status` 由 Gateway 本地处理，不转发到独立 `meta` 服务
-- 当前 Gateway 返回的是简化状态对象，不是完整的 peer / relay 拓扑诊断结构
-- Python SDK 当前也只实现 Gateway 拓扑；`peer` 和 `relay` 拓扑在 Python SDK 中尚未实现
-
-**当前返回字段**：
-
-| 字段 | 说明 |
-|------|------|
-| `mode` | 当前连接模式。现实现固定为 `gateway` |
-| `aid` | 当前会话 AID |
-| `role` | 当前会话角色 |
-| `connected_at` | 会话建立时间戳（毫秒） |
-| `protocol_version` | 协议版本，当前为 `1.0` |
-
-**当前实现示例**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 31,
-  "result": {
-    "mode": "gateway",
-    "aid": "alice.aid.pub",
-    "role": "user",
-    "connected_at": 1709712000000,
-    "protocol_version": "1.0"
-  }
-}
-```
-
-**协议演进约束**：
-
-- 客户端 **MUST** 容忍未知字段，以便未来扩展更完整的连接诊断结构
-- 文档中关于 peer / relay 诊断字段的 richer 结构，目前应视为未来扩展方向，而非当前稳定返回契约
-
-#### `meta.trust_roots`
-
-查询当前 AUN 受信根证书列表。Gateway 内部转发给 CA 模块处理。
-
-该 RPC 适合已连接客户端查询服务端缓存列表。首次信任根更新应优先使用公开 HTTP 端点：
-
-- `GET https://trust.aun.network/.well-known/aun/trust-roots.json`
-- `GET https://pki.{issuer}/trust-root.json`
-- `GET https://gateway.{issuer}/pki/trust-roots.json`
-
-Issuer PKI 泛域名服务还必须提供 `GET https://pki.{issuer}/root.crt`，用于下载该 issuer 证书链锚定的 Root CA PEM。客户端导入前必须验证受信根列表的 `authority_signature`，并确认 `root.crt` 的 SHA-256 指纹存在于已验签列表中。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 32, "method": "meta.trust_roots"}
-```
-
-**参数**：无。
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 32,
-  "result": {
-    "version": 2,
-    "issued_at": "2026-03-15T10:00:00Z",
-    "next_update": "2026-03-16T10:00:00Z",
-    "authority_signature": "MEUCIQDx...",
-    "root_cas": [
-      {
-        "id": "root-ca-001",
-        "name": "AUN Root CA A",
-        "organization": "Organization A",
-        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
-        "fingerprint_sha256": "a1b2c3d4...",
-        "status": "active",
-        "crl_url": "http://crl.rootca-a.example/root.crl",
-        "ocsp_url": "http://ocsp.rootca-a.example"
-      }
-    ]
-  }
-}
-```
-
-**响应字段**：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `version` | integer | 受信根列表版本，单调递增 |
-| `issued_at` | string | 列表签发时间 |
-| `next_update` | string | 建议下次更新时间 |
-| `authority_signature` | string | 管理局对规范化列表内容的签名 |
-| `root_cas` | array | Root CA 列表 |
-| `root_cas[].certificate` | string | PEM 格式 Root CA 证书 |
-| `root_cas[].fingerprint_sha256` | string | Root CA 证书 DER SHA-256 指纹 |
-| `root_cas[].status` | string | `active` / `retired` / `revoked` 等状态 |
-
-> **兼容说明**：早期服务可能仍返回 `roots/count` 简化结构。客户端可以查询该结构，但默认不得将未签名列表导入本地信任根。客户端仍应容忍未知字段。
-
-#### CT 公开 HTTP 端点
-
-Issuer 必须通过 `https://ct.{issuer}` 提供证书透明日志（CT）的公开只读查询入口。该入口不属于 SDK RPC 命名空间，不通过 `AUNClient` 暴露专用方法；审计方和客户端可直接使用 HTTP 查询。
-
-`ct.{issuer}` 是稳定的公开访问面，CA 服务本身不得直接暴露公网 HTTP 端点。服务端对外只能暴露公开只读查询路径，CT 写入接口不得通过 `ct.{issuer}` 暴露。
-
-规范端点：
-
-| 方法 | URL | 说明 |
-|------|-----|------|
-| GET | `https://ct.{issuer}/sth` | 获取最新签名树头（STH） |
-| GET | `https://ct.{issuer}/entries?start=0&limit=100` | 分页查询公开 CT 条目 |
-| GET | `https://ct.{issuer}/entries/{log_id}` | 按日志 ID 查询单条公开 CT 条目 |
-| GET | `https://ct.{issuer}/certs/{serial}` | 按证书序列号查询对应 CT 条目 |
-| GET | `https://ct.{issuer}/proof/{tree_size}/{log_id}` | 获取指定树大小下的 Merkle inclusion proof |
-
-完整日志范围、字段定义、SCT/STH 格式和 Issuer CA 写入要求见 [附录D D.8](附录D-Root_CA_治理机制.md) 与 [附录F](附录F-Issuer_CA_申请流程.md)。
-
----
-
-### 6.5 搜索与发现 `search.*`
-
-`search.*` 定义 AUN 中 Agent 的公开发现机制，围绕 `agent.md` 工作：
-
-- `agent.md` 是 Agent 的标准公开描述文档，对标 A2A 的 Agent Card
-- AP 内部通过 `search.*` 为本 AP 托管或索引的公开 `agent.md` 提供检索服务
-- 整个 AUN 网络可通过公开 AP 之间的同步，聚合形成跨 AP、跨 Issuer 的全网 Agent 搜索与发现能力
-
-#### 6.4.1 `agent.md` 规范
-
-`agent.md` **MUST** 采用 `YAML frontmatter + Markdown 正文` 结构。
-
-**必填字段**：
-
-| 字段 | 说明 |
-|------|------|
-| `aid` | Agent 的唯一身份标识，必须为合法 AID |
-| `name` | Agent 显示名称 |
-| `type` | Agent 类型，如 `human`、`assistant`、`avatar`、`codeagent` |
-| `version` | 该公开描述文档自身的版本号 |
-| `description` | 一句话简介 |
-
-**可选字段**：`tags`、`visibility`（`public`/`unlisted`/`private`）、`updated_at`、`skills`、`input_modes`、`output_modes`、`service_endpoints`、`provider`、`contact`、`license`、`signature`
-
-**最小格式示例**：
-
-```markdown
----
-aid: "agent-name.aid.pub"
-name: "Agent Name"
-type: "assistant"
-version: "1.0.0"
-description: "一句话描述"
-visibility: "public"
-tags:
-  - tag1
----
-
-# Markdown 正文
-详细说明、Skills、使用示���等...
-```
-
-- `visibility=private` 的记录 **MUST NOT** 进入公开索引
-- `agent.md` **MUST NOT** 包含私钥或敏感凭据
-
-#### 6.4.2 发现模型
-
-**AP 内发现**：
-
-- AP **MUST** 能索引其服务范围内公开可见的 `agent.md`
-- `search.query`、`search.get_agent`、`search.suggest` 返回的是该 AP 当前索引视图
-
-**全网发现**：
-
-- 公开 AP **SHOULD** 从其他公开 AP 同步公开的 `agent.md`
-- 同步模型推荐"增量追加日志 + 周期性快照"
-- 客户端 **MUST** 把搜索结果视为"最终一致"，而不是强事务视图
-
-#### `search.ap_info`
-
-查询公开 AP 的同步能力与当前索引状态。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 40, "method": "search.ap_info"}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 40,
-  "result": {
-    "ap_id": "search.aid.pub",
-    "public": true,
-    "capabilities": {"query": true, "suggest": true, "snapshot": true, "changes": true},
-    "current_snapshot_version": "2026-03-21T00:00:00Z",
-    "change_cursor_head": "chg_00000991",
-    "updated_at": "2026-03-21T08:00:00Z"
-  }
-}
-```
-
-#### `search.snapshot`
-
-获取公开 AP 的全量快照，用于冷启动或游标失效后重建。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 41,
-  "method": "search.snapshot",
-  "params": {"version": "2026-03-21T00:00:00Z", "cursor": null, "limit": 500}
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 41,
-  "result": {
-    "snapshot_version": "2026-03-21T00:00:00Z",
-    "items": [{
-      "aid": "reviewer.aid.pub",
-      "agent_md_url": "https://reviewer.aid.pub/agent.md",
-      "agent_md_sha256": "6f4c...9a",
-      "source_ap": "search.aid.pub",
-      "updated_at": "2026-03-20T12:00:00Z"
-    }],
-    "next_cursor": "snap_0002",
-    "has_more": true
-  }
-}
-```
-
-#### `search.changes`
-
-获取某个游标之后的增量变更，用于持续同步。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 42,
-  "method": "search.changes",
-  "params": {"cursor": "chg_00000920", "limit": 200}
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 42,
-  "result": {
-    "from_cursor": "chg_00000920",
-    "next_cursor": "chg_00000991",
-    "changes": [
-      {"sequence": 921, "op": "upsert", "aid": "reviewer.aid.pub", "updated_at": "2026-03-21T07:55:00Z"},
-      {"sequence": 922, "op": "delete", "aid": "oldbot.aid.pub", "updated_at": "2026-03-21T07:56:00Z"}
-    ],
-    "has_more": false
-  }
-}
-```
-
-- `op` 至少支持 `upsert` 与 `delete`
-- 若游标已过期，服务端 **SHOULD** 返回错误，要求下游重新拉取 `search.snapshot`
-
-#### `search.query`
-
-搜索公开 Agent。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 43,
-  "method": "search.query",
-  "params": {"q": "code review assistant", "tags": ["coding"], "limit": 10}
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 43,
-  "result": {
-    "items": [{
-      "aid": "reviewer.aid.pub",
-      "name": "Reviewer",
-      "description": "面向工程团队的代码审查 Agent",
-      "tags": ["coding", "review"],
-      "agent_md_url": "https://reviewer.aid.pub/agent.md"
-    }],
-    "next_cursor": "cur_abc123"
-  }
-}
-```
-
-#### `search.get_agent`
-
-获取单个 Agent 的公开描述。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 44,
-  "method": "search.get_agent",
-  "params": {"aid": "reviewer.aid.pub"}
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 44,
-  "result": {
-    "aid": "reviewer.aid.pub",
-    "agent_md": "---\naid: \"reviewer.aid.pub\"\nname: \"Reviewer\"\n...\n---\n# Reviewer\n",
-    "content_type": "text/markdown",
-    "agent_md_url": "https://reviewer.aid.pub/agent.md",
-    "updated_at": "2026-03-20T12:00:00Z"
-  }
-}
-```
-
-#### `search.suggest`
-
-返回搜索建议、热门标签或前缀匹配结果。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 45, "method": "search.suggest", "params": {"prefix": "code"}}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 45,
-  "result": {
-    "suggestions": [
-      {"type": "query", "value": "code review"},
-      {"type": "tag", "value": "coding"},
-      {"type": "aid", "value": "reviewer.aid.pub"}
-    ]
-  }
-}
-```
-
-#### 错误码
-
-| 错误码 | 名称 | 说明 |
-|-------:|------|------|
-| `-32160` | Search unavailable | 当前 AP 未启用搜索服务 |
-| `-32161` | Agent not found | 指定 AID 的公开 `agent.md` 不存在 |
-| `-32162` | Invalid search query | 查询参数非法 |
-| `-32163` | Snapshot stale | 当前结果基于过期快照 |
-| `-32164` | Change cursor expired | 增量游标已超出保留窗口 |
-
----
-
-### 6.6 Agent 协作与任务 `task.*`
-
-`task.*` 用于表达 Agent 之间的长生命周期协作任务，参考 A2A 的 task 机制，对齐 AUN 特点：
-
-- 任务对象通过 `task.*` 暴露统一的状态、输入、产物和事件
-- 大对象、附件 **SHOULD** 通过 `storage.*` 承载，`task.*` 仅传递元数据与引用
-
-**任务对象核心字段**：
-
-| 字段 | 说明 |
-|------|------|
-| `task_id` | 任务唯一标识 |
-| `status` | 任务状态 |
-| `owner` | 发起方 AID |
-| `assignee` | 执行方 AID |
-| `participants` | 参与方列表 |
-| `visibility` | 任务可见性（`private`/`shared`/`public`） |
-| `parent_task_id` | 父任务标识（如有） |
-| `input` | 初始输入 |
-| `artifacts` | 任务产物 |
-| `messages` | 上下文消息 |
-
-**状态机**：
-
-| 状态 | 说明 |
-|------|------|
-| `submitted` | 已创建，等待接收方受理 |
-| `rejected` | 接收方明确拒绝受理（终态） |
-| `working` | 正在执行 |
-| `input_required` | 需要发起方补充信息 |
-| `completed` | 正常完成（终态） |
-| `failed` | 执行失败（终态） |
-| `canceled` | 被取消（终态） |
-
-终态任务 **MAY** 允许读取历史，但 **MUST NOT** 再接受新的执行输入。
-
-#### `task.create`
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 50,
-  "method": "task.create",
-  "params": {
-    "to": "reviewer.aid.pub",
-    "input": {"type": "text", "content": "请审查这个 PR 的风险点"},
-    "visibility": "private"
-  }
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 50,
-  "result": {
-    "task_id": "task_01HV7J6N8F",
-    "status": "submitted",
-    "owner": "alice.aid.pub",
-    "assignee": "reviewer.aid.pub",
-    "created_at": "2026-03-21T13:00:00Z"
-  }
-}
-```
-
-#### `task.get`
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 51, "method": "task.get", "params": {"task_id": "task_01HV7J6N8F"}}
-```
-
-**响应**：返回完整任务对象（含 `status`、`participants`、`children`、`messages`、`artifacts` 等）。
-
-#### `task.accept`
-
-接收方显式受理任务，把 `submitted` 推进到 `working`。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 52, "method": "task.accept", "params": {"task_id": "task_01HV7J6N8F"}}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 52, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}
-```
-
-#### `task.reject`
-
-接收方显式拒绝受理任务。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 53, "method": "task.reject", "params": {"task_id": "task_01HV7J6N8F", "reason": "unsupported_scope"}}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 53, "result": {"task_id": "task_01HV7J6N8F", "status": "rejected"}}
-```
-
-#### `task.send_input`
-
-向任务追加新的输入，用于继续协作或响应 `input_required`。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 54,
-  "method": "task.send_input",
-  "params": {
-    "task_id": "task_01HV7J6N8F",
-    "input": {"type": "text", "content": "补充说明：重点检查数据库迁移部分"}
-  }
-}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 54, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}
-```
-
-#### `task.delegate`
-
-把当前任务的一个子问题委派给另一个 Agent，创建子任务。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 55,
-  "method": "task.delegate",
-  "params": {
-    "task_id": "task_01HV7J6N8F",
-    "to": "db-reviewer.aid.pub",
-    "input": {"type": "text", "content": "请专门检查数据库迁移风险"}
-  }
-}
-```
-
-**响应**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 55,
-  "result": {
-    "task_id": "task_child_01",
-    "parent_task_id": "task_01HV7J6N8F",
-    "status": "submitted",
-    "assignee": "db-reviewer.aid.pub"
-  }
-}
-```
-
-- 服务端 **SHOULD** 限制递归委派深度和扇出数量，避免任务风暴
-
-#### `task.complete`
-
-将任务标记为完成，附带最终产物。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 56,
-  "method": "task.complete",
-  "params": {
-    "task_id": "task_01HV7J6N8F",
-    "artifacts": [{
-      "id": "artifact-1",
-      "type": "text",
-      "name": "summary",
-      "mime_type": "text/markdown",
-      "content": "数据库迁移存在锁表风险"
-    }]
-  }
-}
-```
-
-#### `task.fail`
-
-将任务标记为失败。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 57, "method": "task.fail", "params": {"task_id": "task_01HV7J6N8F", "reason": "missing_required_context"}}
-```
-
-#### `task.cancel`
-
-取消未完成任务。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 58, "method": "task.cancel", "params": {"task_id": "task_01HV7J6N8F", "reason": "user_abort"}}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 58, "result": {"task_id": "task_01HV7J6N8F", "status": "canceled"}}
-```
-
-#### `task.children`
-
-列出指定任务的子任务摘要。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 59, "method": "task.children", "params": {"task_id": "task_01HV7J6N8F"}}
-```
-
-#### `task.list`
-
-分页列出任务。
-
-**请求**：
-```json
-{"jsonrpc": "2.0", "id": 60, "method": "task.list", "params": {"status": "working", "limit": 20, "cursor": null}}
-```
-
-- 返回结果 **MUST** 受调用方身份约束，**MUST NOT** 泄露无权访问的任务
-
-#### `task.subscribe`
-
-订阅任务后续事件。
-
-**请求**：
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 61,
-  "method": "task.subscribe",
-  "params": {"task_ids": ["task_01HV7J6N8F"], "events": ["updated", "completed", "artifact"]}
-}
-```
-
-**响应**：
-```json
-{"jsonrpc": "2.0", "id": 61, "result": {"subscribed": ["task_01HV7J6N8F"]}}
-```
-
-- 服务端 **MUST NOT** 为无访问权限的任务建立订阅
-- 服务端 **MAY** 在连接断开后丢失订阅状态，客户端应负责重订阅
-
-#### 任务事件
-
-```text
-event/task.updated        # 任务状态更新
-event/task.completed      # 任务完成
-event/task.failed         # 任务失败
-event/task.artifact       # 任务产物可用
-event/task.delegated      # 已创建子任务
-```
-
-**`event/task.updated` 示例**：
-```json
-{
-  "jsonrpc": "2.0",
-  "method": "event/task.updated",
-  "params": {
-    "task_id": "task_01HV7J6N8F",
-    "status": "input_required",
-    "updated_at": "2026-03-21T13:01:00Z",
-    "message": {"type": "text", "content": "请提供 PR 链接"}
-  }
-}
-```
-
-#### 错误码
-
-| 错误码 | 名称 | 说明 |
-|-------:|------|------|
-| `-32170` | Task not found | 指定任务不存在 |
-| `-32171` | Task state invalid | 当前状态不允许该操作 |
-| `-32172` | Task input required | 需要补充输入 |
-| `-32173` | Task canceled | 任务已取消 |
-| `-32174` | Task output too large | 输出过大，应改用 `storage.*` 引用 |
-| `-32175` | Task access denied | 无权访问该任务 |
-| `-32176` | Task already accepted | 不能重复 accept |
-| `-32177` | Task rejected | 任务已被拒绝 |
-| `-32178` | Task delegation denied | 无权创建子任务 |
-| `-32179` | Task child limit exceeded | 子任务数量或深度超限 |
-| `-32185` | Task completion blocked | 存在未完成的必需子任务 |
-| `-32186` | Task failure recorded | 任务已进入失败终态 |
-
----
-
-### 6.7 端到端加密（E2EE）摘要
-
-> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
-
-**核心原则**：
-
-- E2EE 加解密**完全由客户端实现**，无需在线协商
-- 服务端只做消息中转和 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 的互操作必须以 [08-AUN-E2EE.md](08-AUN-E2EE.md) 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。
-
-**错误码**：
-
-| 错误码 | 名称 | 说明 |
-|-------:|------|------|
-| `-32604` | E2EE capability required | 客户端不支持群组 E2EE（无法加入群组） |
-
----
-
-### 6.8 跨域消息路由
-
-**当前实现事实**：
-
-- 跨域消息路由已落地在 Gateway federation 通道上
-- 本域服务通过 `gateway.forward_federation` / `gateway.forward_federation_batch` 发起跨域 RPC 中继
-- Gateway federation client 当前通过 `https://{issuer}/.well-known/aun-gateway` 发现远端 Gateway 地址
-- 远端 Gateway 通过 `federation.hello` 完成双向认证后，接收 `federation.relay` / `federation.relay_batch`
-- `message.send`、`message.query_online`、`storage.*`、`group.*` 等服务当前都已复用该通道进行跨域转发
-
-**当前约束**：
-
-- 这是一条 Gateway 级 federation 中继通道，不是独立的 `message.*` 子协议扩展
-- 跨域转发的具体可用 namespace 受 Gateway 白名单控制
-- 服务端会向被中继的 RPC 注入 `_federation` 上下文，并校验调用方 AID 的 issuer 与来源 issuer 一致
-
-**错误语义**：
-
-- `gateway.forward_federation` 当前在连接失败时返回 `-32010`
-- 超时时返回 `-32011`
-- 运行时拒绝或协议错误返回 `-32012`
+## 6. 服务协议（业务层）
+
+> 本文描述认证完成后的业务层方法。连接与身份认证见对应子协议文档：
+> - 身份与凭证：[01-身份与凭证协议-auth.md](01-身份与凭证协议-auth.md)
+> - Gateway 连接：[03-Gateway-连接模式.md](03-Gateway-连接模式.md)
+> - Peer 对等认证：[04-Peer-子协议.md](04-Peer-子协议.md)
+> - Relay 中继：[05-Relay-子协议.md](05-Relay-子协议.md)
+>
+> 业务层方法与连接拓扑无关。无论使用 gateway、peer 或 relay 模式，认证完成后都可调用以下方法。
+
+---
+
+### 6.1 命名空间概览
+
+| 命名空间 | 分类 | 功能 | 对应服务 | 传输方式 |
+|---------|------|------|---------|---------|
+| `auth.*` | 核心 | AID 注册、认证、令牌管理 | auth 服务 | WebSocket |
+| `ca.*` | 核心 | 证书签发、续期、吊销 | ca 服务 | WebSocket / HTTP |
+| `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 |
+| `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 |
+
+**控制面与数据面分离**：
+
+- `message.*` 用于传递消息语义、小型结构化负载和控制信息，不承担大对象传输职责
+- `storage.*` 用于承载大文件、大对象及附件内容的上传、下载与持久保存
+- `stream.*` 用于实时流式传输（LLM 输出、数据推送等），控制面通过 RPC 管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输
+- 大文件、二进制附件、长时流式内容不应直接嵌入 `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.*`
+
+**设计原则**：
+
+- **无会话生命周期**：不需要 create/invite/join/close 流程，直接发送即可
+- **投递语义由 `delivery_mode` 决定**：`fanout` 会进入离线历史并广播到同一 AID 的在线实例；`queue` 只做实时单实例投递，不进入历史存储
+- **控制面与数据面分离**：`message.*` 承载消息语义和小型结构化数据；附件、大对象应通过 `storage.*` 传输，消息中只保留引用
+
+> 本节仅适用于 P2P `message.*`。`group.send` 不支持 `queue`，群消息始终是 fanout 语义。
+
+**消息存储模型**：
+
+| `delivery_mode.mode` | 投递方式 | 存储位置 | 生命周期 | 适用场景 |
+|----------------------|----------|---------|---------|---------|
+| `queue` | 单实例实时消费 | 内存环形缓冲 | 有限时间窗口（默认 5 分钟）+ 有限条数（默认 200 条/AID） | Worker/执行器消费、同一发送者尽量命中同一实例 |
+| `fanout` | 广播到在线实例 | 数据库 + 文件存储 | TTL 过期前持久保存（默认 24 小时） | 离线送达、历史查询、多实例同步接收 |
+
+**序列号机制**：
+
+- `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`
+
+发送 P2P 消息。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "message.send",
+  "params": {
+    "to": "bob.aid.pub",
+    "device_id": "bob-phone",
+    "ttl": 300,
+    "payload": {"type": "text", "text": "你好"}
+  }
+}
+```
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `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` | ❌ | 持久 P2P 的逻辑消息幂等键；新消息使用新的唯一 ID，重试复用原 ID，sender 隔离不扩大复用范围；客户端提供或服务端生成 UUID。volatile 保留原 sender+ID 隔离 |
+| `need_render` | ❌ | 布尔值，默认 `true`；表示消息是否需要应用渲染，不改变拉取顺序或 ACK 规则 |
+| `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "result": {
+    "message_id": "550e8400-e29b-41d4-a716-446655440000",
+    "seq": 42,
+    "timestamp": 1709712000,
+    "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 秒下限。
+
+`need_render` 同样适用于 `group.send`。SDK 提取后放入明文信封，接收端同时可读取消息顶层该字段；历史缺字段或数据库 NULL 按 `true`。它不进入 E2EE AAD、`protected_headers`、消息保护签名或元数据 HMAC；RPC `client_signature` 仍按既有业务参数签名规则覆盖该参数，不新增 canonical 排除项。
+
+##### Payload 参考约定
+
+`message.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整 P2P 请求仍在 `payload` 同级传入 `to`；业务类型放在 `payload.type`，不要与 `message.send.params.type` 信封/封装类型混用。
+
+协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小限制；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
+
+#### 连接升级控制消息
+
+`peer.offer` / `peer.accept` / `peer.reject` / `peer.switch` 不是独立 JSON-RPC 方法，而是通过普通 `message.send` 发送的**协议控制负载**。三种连接模式在业务层复用统一的 `message.*`。
+
+**用途**：
+
+- `gateway → peer`：通过 Gateway 交换直连地址，尝试升级到 Peer
+- `relay → peer`：已通过 Relay 联通的双方尝试升级到直连
+- 失败时可回退到原有通道，不影响业务层 API
+
+**`peer.offer` 示例**：
+```json
+{
+  "method": "message.send",
+  "params": {
+    "to": "bob.company.com",
+    "payload": {
+      "type": "peer.offer",
+      "session_id": "upgrade-550e8400",
+      "from_mode": "gateway",
+      "preferred_mode": "peer",
+      "endpoints": [{"url": "wss://alice.company.com:9900/acp", "priority": 1}],
+      "expires_in": 30
+    },
+    "delivery_mode": {"mode": "queue"}
+  }
+}
+```
+
+**`peer.accept` 负载**：`{ "type": "peer.accept", "session_id": "...", "selected_endpoint": "wss://..." }`
+
+**`peer.reject` 负载**：`{ "type": "peer.reject", "session_id": "...", "reason": "policy_denied" }`
+
+**`peer.switch` 负载**：`{ "type": "peer.switch", "session_id": "...", "new_mode": "peer", "keep_fallback": true }`
+
+**规范要求**：
+
+- 接收方 **MAY** 接受或拒绝 `peer.offer`
+- 接受后，双方 **MUST** 在新通道上重新执行完整 `initialize(mode=peer)` 与 `peer.*` 认证流程
+- 旧通道在 `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 两个独立游标拉取消息。以下请求/响应示例表示旧 global 路径；peer 路径增加 `cursor_scope="peer"`、`sender_aid`，持久页默认及最大 200 条，volatile 游标同样按 peer 隔离。
+
+**请求**：
+```json
+{
+  "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"
+  }
+}
+```
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `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
+{
+  "jsonrpc": "2.0",
+  "id": 11,
+  "result": {
+    "messages": [{
+      "message_id": "550e8400-...",
+      "seq": 43,
+      "from": "alice.aid.pub",
+      "to": "bob.aid.pub",
+      "timestamp": 1709712000,
+      "payload": {"type": "text", "text": "你好"},
+      "delivery_mode": "fanout"
+    }],
+    "count": 1,
+    "latest_seq": 43,
+    "ephemeral_earliest_available_seq": 38,
+    "ephemeral_dropped_count": 5
+  }
+}
+```
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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 内因过期或容量淘汰而不可读的累计数 |
+| `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`；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"
+  }
+}
+```
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `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
+{
+  "jsonrpc": "2.0",
+  "id": 12,
+  "result": {"success": true, "ack_seq": 43}
+}
+```
+
+**说明**：`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`
+
+撤回消息。仅发送方可撤回，受时间窗口限制（默认 2 分钟）。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 13,
+  "method": "message.recall",
+  "params": {"message_ids": ["uuid-1", "uuid-2"]}
+}
+```
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `message_ids` | ✅ | 要撤回的消息 ID 列表（最多 100 个） |
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 13,
+  "result": {
+    "success": true,
+    "accepted": 2,
+    "recalled": 1,
+    "errors": [{"message_id": "uuid-2", "error": "expired"}]
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | 操作是否执行 |
+| `accepted` | integer | 接收的 message_id 数 |
+| `recalled` | integer | 实际撤回数 |
+| `errors` | array\|null | 失败项，错误码：`not_found` / `not_sender` / `already_recalled` / `expired` |
+
+**说明**：撤回成功后向接收方推送 `event/message.recalled` 事件。仅 `delivery_mode.mode = "fanout"` 的消息支持撤回；`queue` 消息不进入历史，无法可靠追溯。
+
+#### `message.query_online`
+
+批量查询 AID 在线状态。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 14,
+  "method": "message.query_online",
+  "params": {"aids": ["alice.aid.pub", "bob.example.com"]}
+}
+```
+
+**参数**：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `aids` | ✅ | 要查询的 AID 列表（最多 100 个） |
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 14,
+  "result": {
+    "online": {
+      "alice.aid.pub": true,
+      "bob.example.com": false
+    }
+  }
+}
+```
+
+**当前实现说明**：
+
+- 本域 AID 直接由 message 服务本地在线跟踪器返回
+- 外域 AID 通过 `gateway.forward_federation` 转发到目标域查询
+- 当前实现中，若某个外域查询失败，该域内 AID 会回落为 `false`
+
+#### `event/message.received`
+
+收到 P2P 消息事件。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/message.received",
+  "params": {
+    "from": "bob.aid.pub",
+    "sender_device_id": "bob-phone",
+    "to": "alice.aid.pub",
+    "message_id": "550e8400-...",
+    "seq": 42,
+    "payload": {"type": "text", "text": "你好"},
+    "timestamp": 1709712005,
+    "delivery_mode": "queue",
+    "encrypted": false
+  }
+}
+```
+
+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`
+
+消息确认事件（通知发送方消息已被接收方确认）。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/message.ack",
+  "params": {
+    "to": "bob.aid.pub",
+    "device_id": "device-001",
+    "ack_seq": 43,
+    "timestamp": 1709712003
+  }
+}
+```
+
+- `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`
+
+消息被撤回事件（通知接收方消息已被发送方撤回）。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/message.recalled",
+  "params": {
+    "from": "alice.aid.pub",
+    "to": "bob.aid.pub",
+    "message_ids": ["uuid-1"],
+    "timestamp": 1709712000
+  }
+}
+```
+
+- `from`：发送方（撤回者）AID
+- `to`：接收方 AID
+- `message_ids`：被撤回的消息 ID 列表
+- `timestamp`：服务端时间戳（毫秒）
+
+---
+
+### 6.4 元协议 `meta.*`
+
+#### `meta.ping`
+
+健康检查。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 30, "method": "meta.ping"}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 30, "result": {"pong": true, "timestamp": 1709712000}}
+```
+
+#### `meta.status`
+
+查询当前连接状态。
+
+**当前实现事实**：
+
+- `meta.status` 由 Gateway 本地处理，不转发到独立 `meta` 服务
+- 当前 Gateway 返回的是简化状态对象，不是完整的 peer / relay 拓扑诊断结构
+- Python SDK 当前也只实现 Gateway 拓扑；`peer` 和 `relay` 拓扑在 Python SDK 中尚未实现
+
+**当前返回字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `mode` | 当前连接模式。现实现固定为 `gateway` |
+| `aid` | 当前会话 AID |
+| `role` | 当前会话角色 |
+| `connected_at` | 会话建立时间戳（毫秒） |
+| `protocol_version` | 协议版本，当前为 `1.0` |
+
+**当前实现示例**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 31,
+  "result": {
+    "mode": "gateway",
+    "aid": "alice.aid.pub",
+    "role": "user",
+    "connected_at": 1709712000000,
+    "protocol_version": "1.0"
+  }
+}
+```
+
+**协议演进约束**：
+
+- 客户端 **MUST** 容忍未知字段，以便未来扩展更完整的连接诊断结构
+- 文档中关于 peer / relay 诊断字段的 richer 结构，目前应视为未来扩展方向，而非当前稳定返回契约
+
+#### `meta.trust_roots`
+
+查询当前 AUN 受信根证书列表。Gateway 内部转发给 CA 模块处理。
+
+该 RPC 适合已连接客户端查询服务端缓存列表。首次信任根更新应优先使用公开 HTTP 端点：
+
+- `GET https://trust.aun.network/.well-known/aun/trust-roots.json`
+- `GET https://pki.{issuer}/trust-root.json`
+- `GET https://gateway.{issuer}/pki/trust-roots.json`
+
+Issuer PKI 泛域名服务还必须提供 `GET https://pki.{issuer}/root.crt`，用于下载该 issuer 证书链锚定的 Root CA PEM。客户端导入前必须验证受信根列表的 `authority_signature`，并确认 `root.crt` 的 SHA-256 指纹存在于已验签列表中。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 32, "method": "meta.trust_roots"}
+```
+
+**参数**：无。
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 32,
+  "result": {
+    "version": 2,
+    "issued_at": "2026-03-15T10:00:00Z",
+    "next_update": "2026-03-16T10:00:00Z",
+    "authority_signature": "MEUCIQDx...",
+    "root_cas": [
+      {
+        "id": "root-ca-001",
+        "name": "AUN Root CA A",
+        "organization": "Organization A",
+        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
+        "fingerprint_sha256": "a1b2c3d4...",
+        "status": "active",
+        "crl_url": "http://crl.rootca-a.example/root.crl",
+        "ocsp_url": "http://ocsp.rootca-a.example"
+      }
+    ]
+  }
+}
+```
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `version` | integer | 受信根列表版本，单调递增 |
+| `issued_at` | string | 列表签发时间 |
+| `next_update` | string | 建议下次更新时间 |
+| `authority_signature` | string | 管理局对规范化列表内容的签名 |
+| `root_cas` | array | Root CA 列表 |
+| `root_cas[].certificate` | string | PEM 格式 Root CA 证书 |
+| `root_cas[].fingerprint_sha256` | string | Root CA 证书 DER SHA-256 指纹 |
+| `root_cas[].status` | string | `active` / `retired` / `revoked` 等状态 |
+
+> **兼容说明**：早期服务可能仍返回 `roots/count` 简化结构。客户端可以查询该结构，但默认不得将未签名列表导入本地信任根。客户端仍应容忍未知字段。
+
+#### CT 公开 HTTP 端点
+
+Issuer 必须通过 `https://ct.{issuer}` 提供证书透明日志（CT）的公开只读查询入口。该入口不属于 SDK RPC 命名空间，不通过 `AUNClient` 暴露专用方法；审计方和客户端可直接使用 HTTP 查询。
+
+`ct.{issuer}` 是稳定的公开访问面，CA 服务本身不得直接暴露公网 HTTP 端点。服务端对外只能暴露公开只读查询路径，CT 写入接口不得通过 `ct.{issuer}` 暴露。
+
+规范端点：
+
+| 方法 | URL | 说明 |
+|------|-----|------|
+| GET | `https://ct.{issuer}/sth` | 获取最新签名树头（STH） |
+| GET | `https://ct.{issuer}/entries?start=0&limit=100` | 分页查询公开 CT 条目 |
+| GET | `https://ct.{issuer}/entries/{log_id}` | 按日志 ID 查询单条公开 CT 条目 |
+| GET | `https://ct.{issuer}/certs/{serial}` | 按证书序列号查询对应 CT 条目 |
+| GET | `https://ct.{issuer}/proof/{tree_size}/{log_id}` | 获取指定树大小下的 Merkle inclusion proof |
+
+完整日志范围、字段定义、SCT/STH 格式和 Issuer CA 写入要求见 [附录D D.8](附录D-Root_CA_治理机制.md) 与 [附录F](附录F-Issuer_CA_申请流程.md)。
+
+---
+
+### 6.5 搜索与发现 `search.*`
+
+`search.*` 定义 AUN 中 Agent 的公开发现机制，围绕 `agent.md` 工作：
+
+- `agent.md` 是 Agent 的标准公开描述文档，对标 A2A 的 Agent Card
+- AP 内部通过 `search.*` 为本 AP 托管或索引的公开 `agent.md` 提供检索服务
+- 整个 AUN 网络可通过公开 AP 之间的同步，聚合形成跨 AP、跨 Issuer 的全网 Agent 搜索与发现能力
+
+#### 6.4.1 `agent.md` 规范
+
+`agent.md` **MUST** 采用 `YAML frontmatter + Markdown 正文` 结构。
+
+**必填字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | Agent 的唯一身份标识，必须为合法 AID |
+| `name` | Agent 显示名称 |
+| `type` | Agent 类型，如 `human`、`assistant`、`avatar`、`codeagent` |
+| `version` | 该公开描述文档自身的版本号 |
+| `description` | 一句话简介 |
+
+**可选字段**：`tags`、`visibility`（`public`/`unlisted`/`private`）、`updated_at`、`skills`、`input_modes`、`output_modes`、`service_endpoints`、`provider`、`contact`、`license`、`signature`
+
+**最小格式示例**：
+
+```markdown
+---
+aid: "agent-name.aid.pub"
+name: "Agent Name"
+type: "assistant"
+version: "1.0.0"
+description: "一句话描述"
+visibility: "public"
+tags:
+  - tag1
+---
+
+# Markdown 正文
+详细说明、Skills、使用示���等...
+```
+
+- `visibility=private` 的记录 **MUST NOT** 进入公开索引
+- `agent.md` **MUST NOT** 包含私钥或敏感凭据
+
+#### 6.4.2 发现模型
+
+**AP 内发现**：
+
+- AP **MUST** 能索引其服务范围内公开可见的 `agent.md`
+- `search.query`、`search.get_agent`、`search.suggest` 返回的是该 AP 当前索引视图
+
+**全网发现**：
+
+- 公开 AP **SHOULD** 从其他公开 AP 同步公开的 `agent.md`
+- 同步模型推荐"增量追加日志 + 周期性快照"
+- 客户端 **MUST** 把搜索结果视为"最终一致"，而不是强事务视图
+
+#### `search.ap_info`
+
+查询公开 AP 的同步能力与当前索引状态。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 40, "method": "search.ap_info"}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 40,
+  "result": {
+    "ap_id": "search.aid.pub",
+    "public": true,
+    "capabilities": {"query": true, "suggest": true, "snapshot": true, "changes": true},
+    "current_snapshot_version": "2026-03-21T00:00:00Z",
+    "change_cursor_head": "chg_00000991",
+    "updated_at": "2026-03-21T08:00:00Z"
+  }
+}
+```
+
+#### `search.snapshot`
+
+获取公开 AP 的全量快照，用于冷启动或游标失效后重建。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 41,
+  "method": "search.snapshot",
+  "params": {"version": "2026-03-21T00:00:00Z", "cursor": null, "limit": 500}
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 41,
+  "result": {
+    "snapshot_version": "2026-03-21T00:00:00Z",
+    "items": [{
+      "aid": "reviewer.aid.pub",
+      "agent_md_url": "https://reviewer.aid.pub/agent.md",
+      "agent_md_sha256": "6f4c...9a",
+      "source_ap": "search.aid.pub",
+      "updated_at": "2026-03-20T12:00:00Z"
+    }],
+    "next_cursor": "snap_0002",
+    "has_more": true
+  }
+}
+```
+
+#### `search.changes`
+
+获取某个游标之后的增量变更，用于持续同步。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 42,
+  "method": "search.changes",
+  "params": {"cursor": "chg_00000920", "limit": 200}
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 42,
+  "result": {
+    "from_cursor": "chg_00000920",
+    "next_cursor": "chg_00000991",
+    "changes": [
+      {"sequence": 921, "op": "upsert", "aid": "reviewer.aid.pub", "updated_at": "2026-03-21T07:55:00Z"},
+      {"sequence": 922, "op": "delete", "aid": "oldbot.aid.pub", "updated_at": "2026-03-21T07:56:00Z"}
+    ],
+    "has_more": false
+  }
+}
+```
+
+- `op` 至少支持 `upsert` 与 `delete`
+- 若游标已过期，服务端 **SHOULD** 返回错误，要求下游重新拉取 `search.snapshot`
+
+#### `search.query`
+
+搜索公开 Agent。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 43,
+  "method": "search.query",
+  "params": {"q": "code review assistant", "tags": ["coding"], "limit": 10}
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 43,
+  "result": {
+    "items": [{
+      "aid": "reviewer.aid.pub",
+      "name": "Reviewer",
+      "description": "面向工程团队的代码审查 Agent",
+      "tags": ["coding", "review"],
+      "agent_md_url": "https://reviewer.aid.pub/agent.md"
+    }],
+    "next_cursor": "cur_abc123"
+  }
+}
+```
+
+#### `search.get_agent`
+
+获取单个 Agent 的公开描述。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 44,
+  "method": "search.get_agent",
+  "params": {"aid": "reviewer.aid.pub"}
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 44,
+  "result": {
+    "aid": "reviewer.aid.pub",
+    "agent_md": "---\naid: \"reviewer.aid.pub\"\nname: \"Reviewer\"\n...\n---\n# Reviewer\n",
+    "content_type": "text/markdown",
+    "agent_md_url": "https://reviewer.aid.pub/agent.md",
+    "updated_at": "2026-03-20T12:00:00Z"
+  }
+}
+```
+
+#### `search.suggest`
+
+返回搜索建议、热门标签或前缀匹配结果。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 45, "method": "search.suggest", "params": {"prefix": "code"}}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 45,
+  "result": {
+    "suggestions": [
+      {"type": "query", "value": "code review"},
+      {"type": "tag", "value": "coding"},
+      {"type": "aid", "value": "reviewer.aid.pub"}
+    ]
+  }
+}
+```
+
+#### 错误码
+
+| 错误码 | 名称 | 说明 |
+|-------:|------|------|
+| `-32160` | Search unavailable | 当前 AP 未启用搜索服务 |
+| `-32161` | Agent not found | 指定 AID 的公开 `agent.md` 不存在 |
+| `-32162` | Invalid search query | 查询参数非法 |
+| `-32163` | Snapshot stale | 当前结果基于过期快照 |
+| `-32164` | Change cursor expired | 增量游标已超出保留窗口 |
+
+---
+
+### 6.6 Agent 协作与任务 `task.*`
+
+`task.*` 用于表达 Agent 之间的长生命周期协作任务，参考 A2A 的 task 机制，对齐 AUN 特点：
+
+- 任务对象通过 `task.*` 暴露统一的状态、输入、产物和事件
+- 大对象、附件 **SHOULD** 通过 `storage.*` 承载，`task.*` 仅传递元数据与引用
+
+**任务对象核心字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `task_id` | 任务唯一标识 |
+| `status` | 任务状态 |
+| `owner` | 发起方 AID |
+| `assignee` | 执行方 AID |
+| `participants` | 参与方列表 |
+| `visibility` | 任务可见性（`private`/`shared`/`public`） |
+| `parent_task_id` | 父任务标识（如有） |
+| `input` | 初始输入 |
+| `artifacts` | 任务产物 |
+| `messages` | 上下文消息 |
+
+**状态机**：
+
+| 状态 | 说明 |
+|------|------|
+| `submitted` | 已创建，等待接收方受理 |
+| `rejected` | 接收方明确拒绝受理（终态） |
+| `working` | 正在执行 |
+| `input_required` | 需要发起方补充信息 |
+| `completed` | 正常完成（终态） |
+| `failed` | 执行失败（终态） |
+| `canceled` | 被取消（终态） |
+
+终态任务 **MAY** 允许读取历史，但 **MUST NOT** 再接受新的执行输入。
+
+#### `task.create`
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 50,
+  "method": "task.create",
+  "params": {
+    "to": "reviewer.aid.pub",
+    "input": {"type": "text", "content": "请审查这个 PR 的风险点"},
+    "visibility": "private"
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 50,
+  "result": {
+    "task_id": "task_01HV7J6N8F",
+    "status": "submitted",
+    "owner": "alice.aid.pub",
+    "assignee": "reviewer.aid.pub",
+    "created_at": "2026-03-21T13:00:00Z"
+  }
+}
+```
+
+#### `task.get`
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 51, "method": "task.get", "params": {"task_id": "task_01HV7J6N8F"}}
+```
+
+**响应**：返回完整任务对象（含 `status`、`participants`、`children`、`messages`、`artifacts` 等）。
+
+#### `task.accept`
+
+接收方显式受理任务，把 `submitted` 推进到 `working`。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 52, "method": "task.accept", "params": {"task_id": "task_01HV7J6N8F"}}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 52, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}
+```
+
+#### `task.reject`
+
+接收方显式拒绝受理任务。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 53, "method": "task.reject", "params": {"task_id": "task_01HV7J6N8F", "reason": "unsupported_scope"}}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 53, "result": {"task_id": "task_01HV7J6N8F", "status": "rejected"}}
+```
+
+#### `task.send_input`
+
+向任务追加新的输入，用于继续协作或响应 `input_required`。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 54,
+  "method": "task.send_input",
+  "params": {
+    "task_id": "task_01HV7J6N8F",
+    "input": {"type": "text", "content": "补充说明：重点检查数据库迁移部分"}
+  }
+}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 54, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}
+```
+
+#### `task.delegate`
+
+把当前任务的一个子问题委派给另一个 Agent，创建子任务。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 55,
+  "method": "task.delegate",
+  "params": {
+    "task_id": "task_01HV7J6N8F",
+    "to": "db-reviewer.aid.pub",
+    "input": {"type": "text", "content": "请专门检查数据库迁移风险"}
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 55,
+  "result": {
+    "task_id": "task_child_01",
+    "parent_task_id": "task_01HV7J6N8F",
+    "status": "submitted",
+    "assignee": "db-reviewer.aid.pub"
+  }
+}
+```
+
+- 服务端 **SHOULD** 限制递归委派深度和扇出数量，避免任务风暴
+
+#### `task.complete`
+
+将任务标记为完成，附带最终产物。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 56,
+  "method": "task.complete",
+  "params": {
+    "task_id": "task_01HV7J6N8F",
+    "artifacts": [{
+      "id": "artifact-1",
+      "type": "text",
+      "name": "summary",
+      "mime_type": "text/markdown",
+      "content": "数据库迁移存在锁表风险"
+    }]
+  }
+}
+```
+
+#### `task.fail`
+
+将任务标记为失败。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 57, "method": "task.fail", "params": {"task_id": "task_01HV7J6N8F", "reason": "missing_required_context"}}
+```
+
+#### `task.cancel`
+
+取消未完成任务。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 58, "method": "task.cancel", "params": {"task_id": "task_01HV7J6N8F", "reason": "user_abort"}}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 58, "result": {"task_id": "task_01HV7J6N8F", "status": "canceled"}}
+```
+
+#### `task.children`
+
+列出指定任务的子任务摘要。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 59, "method": "task.children", "params": {"task_id": "task_01HV7J6N8F"}}
+```
+
+#### `task.list`
+
+分页列出任务。
+
+**请求**：
+```json
+{"jsonrpc": "2.0", "id": 60, "method": "task.list", "params": {"status": "working", "limit": 20, "cursor": null}}
+```
+
+- 返回结果 **MUST** 受调用方身份约束，**MUST NOT** 泄露无权访问的任务
+
+#### `task.subscribe`
+
+订阅任务后续事件。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 61,
+  "method": "task.subscribe",
+  "params": {"task_ids": ["task_01HV7J6N8F"], "events": ["updated", "completed", "artifact"]}
+}
+```
+
+**响应**：
+```json
+{"jsonrpc": "2.0", "id": 61, "result": {"subscribed": ["task_01HV7J6N8F"]}}
+```
+
+- 服务端 **MUST NOT** 为无访问权限的任务建立订阅
+- 服务端 **MAY** 在连接断开后丢失订阅状态，客户端应负责重订阅
+
+#### 任务事件
+
+```text
+event/task.updated        # 任务状态更新
+event/task.completed      # 任务完成
+event/task.failed         # 任务失败
+event/task.artifact       # 任务产物可用
+event/task.delegated      # 已创建子任务
+```
+
+**`event/task.updated` 示例**：
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/task.updated",
+  "params": {
+    "task_id": "task_01HV7J6N8F",
+    "status": "input_required",
+    "updated_at": "2026-03-21T13:01:00Z",
+    "message": {"type": "text", "content": "请提供 PR 链接"}
+  }
+}
+```
+
+#### 错误码
+
+| 错误码 | 名称 | 说明 |
+|-------:|------|------|
+| `-32170` | Task not found | 指定任务不存在 |
+| `-32171` | Task state invalid | 当前状态不允许该操作 |
+| `-32172` | Task input required | 需要补充输入 |
+| `-32173` | Task canceled | 任务已取消 |
+| `-32174` | Task output too large | 输出过大，应改用 `storage.*` 引用 |
+| `-32175` | Task access denied | 无权访问该任务 |
+| `-32176` | Task already accepted | 不能重复 accept |
+| `-32177` | Task rejected | 任务已被拒绝 |
+| `-32178` | Task delegation denied | 无权创建子任务 |
+| `-32179` | Task child limit exceeded | 子任务数量或深度超限 |
+| `-32185` | Task completion blocked | 存在未完成的必需子任务 |
+| `-32186` | Task failure recorded | 任务已进入失败终态 |
+
+---
+
+### 6.7 端到端加密（E2EE）摘要
+
+> 当前 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 存储，对加密内容完全透明
+- 当前 P2P 使用 `message.send` 承载 `e2ee.p2p_encrypted` 信封，群组使用 `group.v2.send` 承载 `e2ee.group_encrypted` 信封
+- 当前默认每消息独立密钥，按设备使用 `3DH` / `1DH` wrap；`prekey_ecdh_v2` / `long_term_key` 仅用于 Legacy 兼容
+
+**服务端兼容性要求**：
+
+- 接受并转发当前 V2 加密信封及 Legacy `encrypted: true` 消息
+- 在离线队列和历史消息中存储密文 payload
+- 不对密文 payload 施加额外的语义解析要求
+- 当前 P2P 设备 SPK 使用 `message.v2.put_peer_pk` / `message.v2.bootstrap`；`message.e2ee.put_prekey` / `message.e2ee.get_prekey` 仅为 Legacy 兼容
+
+**互操作要求**：
+
+跨语言、跨平台 SDK 必须按当前 V2 路径保持算法、信封、AAD 与 recipient proof 一致；旧格式才适用 [Legacy E2EE 规范](08-AUN-E2EE.md)，不得用旧信封替代默认 V2 发送格式。
+
+**错误码**：
+
+| 错误码 | 名称 | 说明 |
+|-------:|------|------|
+| `-32604` | E2EE capability required | 客户端不支持群组 E2EE（无法加入群组） |
+
+---
+
+### 6.8 跨域消息路由
+
+**当前实现事实**：
+
+- 跨域消息路由已落地在 Gateway federation 通道上
+- 本域服务通过 `gateway.forward_federation` / `gateway.forward_federation_batch` 发起跨域 RPC 中继
+- Gateway federation client 当前通过 `https://{issuer}/.well-known/aun-gateway` 发现远端 Gateway 地址
+- 远端 Gateway 通过 `federation.hello` 完成双向认证后，接收 `federation.relay` / `federation.relay_batch`
+- `message.send`、`message.query_online`、`storage.*`、`group.*` 等服务当前都已复用该通道进行跨域转发
+
+**当前约束**：
+
+- 这是一条 Gateway 级 federation 中继通道，不是独立的 `message.*` 子协议扩展
+- 跨域转发的具体可用 namespace 受 Gateway 白名单控制
+- 服务端会向被中继的 RPC 注入 `_federation` 上下文，并校验调用方 AID 的 issuer 与来源 issuer 一致
+
+**错误语义**：
+
+- `gateway.forward_federation` 当前在连接失败时返回 `-32010`
+- 超时时返回 `-32011`
+- 运行时拒绝或协议错误返回 `-32012`