@agentunion/fastaun-browser 0.3.6 → 0.4.0

package/_packed_docs/sdk/INDEX.md

@@ -1,6 +1,6 @@
 # AUN SDK 文档索引
 
-> 渐进式三层结构。Layer 1 极简地图，总是加载；Layer 2 概念交叉索引，按主题查找时加载；Layer 3 每篇文档的详细摘要，需要深入时加载。
+> 三层索引：Layer 1 文档地图，Layer 2 主题交叉索引，Layer 3 单篇摘要。
 
 ---
 
@@ -8,129 +8,103 @@
 
 | 文档 | 说明 |
 |------|------|
-| [01-快速开始](01-快速开始.md) | 最小示例 · 安装 · 配置 · 核心流程 |
-| [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · 连接状态机 · 认证流程 · E2EE |
-| [04-连接与认证](04-连接与认证.md) | 创建AID · 连接网关 · 网关发现 · 调用RPC · 事件订阅 |
-| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE加密消息 · ProtectedHeaders · 会话管理 · 自定义密钥存储 |
-| [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 · Mermaid 时序图 |
-| [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态 · 竞态条件 · 补测清单 |
-| [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位 · 成熟方案对比 · 风险边界 · 分阶段改进建议 |
-| [06-API手册](06-API手册.md) | AUNClient · AuthNamespace · MetaNamespace（信任根列表 / issuer root 更新） · E2EEManager · 内置事件 · RPC手册索引 |
-| [07-错误处理](07-错误处理.md) | 错误类层级 · 错误码速查 · 重试策略 |
-| [08-最佳实践](08-最佳实践.md) | 幂等初始化 · 多AID隔离 · 环境变量 · 资源清理 |
-| [10-custody-api-manual](10-custody-api-manual.md) | AID 托管 · 手机号验证码 · 备份恢复 · 跨设备复制 |
-| [多语言SDK使用场景与调用链路对齐审查清单](多语言SDK使用场景与调用链路对齐审查清单.md) | 多语言场景清单 · 调用链路 · 字段对齐 · 竞态与服务端风险 · 旧清单复审 |
-
-### RPC 手册
-
-| 文档 | 说明 |
-|------|------|
-| [09-payload-reference](09-payload-reference.md) | `message.send` / `message.thought.put` / `group.send` / `group.thought.put` 共用业务负载格式 · `payload.type` 类型总览 · 交互卡片/action_card_reply · 任务事件 · 附件引用 |
-| [09-group-rpc-manual](09-group-rpc-manual.md) | Group 服务 RPC 接口 · 群组创建/加入/成员管理/设置与分发/消息收发/思考内容 · `payload.type` 负载类型 |
-| [09-message-rpc-manual](09-message-rpc-manual.md) | Message 服务 RPC 接口 · 点对点消息发送/拉取/确认/P2P 思考内容 · `payload.type` 负载类型 |
-| [09-meta-rpc-manual](09-meta-rpc-manual.md) | Meta 服务 RPC 接口 · ping/status/信任根列表与 PKI 下载端点 |
-| [09-storage-rpc-manual](09-storage-rpc-manual.md) | Storage 服务 RPC 接口 · 文件上传/下载/对象管理 |
-| [09-stream-rpc-manual](09-stream-rpc-manual.md) | Stream 服务 RPC 接口 · 流式数据传输 |
+| [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
+| [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
+| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE |
+| [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 网关发现 · 事件 · agent.md |
+| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 消息 · ProtectedHeaders · 密钥管理 · 高级存储 |
+| [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
+| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 事件 · E2EE 高级 API · RPC 索引 |
+| [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · 测试数据保护 |
+| [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
+| [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
+| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC |
+| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC |
+| [09-meta-rpc-manual](09-meta-rpc-manual.md) | meta RPC 和信任根 |
+| [09-stream-rpc-manual](09-stream-rpc-manual.md) | stream RPC |
+| [09-custody-api-manual](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
 
 ---
 
 ## Layer 2：概念交叉索引
 
 ### 身份与认证
-- **AID 格式与结构** → [03-核心概念](03-核心概念.md)
-- **创建 AID** → [04-连接与认证](04-连接与认证.md) · [06-API手册](06-API手册.md)
-- **认证流程（挑战-应答）** → [03-核心概念](03-核心概念.md)
-- **认证失败处理** → [07-错误处理](07-错误处理.md)
-- **AID 证书与加密私钥托管恢复/跨设备复制** → [10-custody-api-manual](10-custody-api-manual.md)
-
-### 连接与协议
-- **WebSocket 握手协议** → [02-WebSocket协议](02-WebSocket协议.md)
-- **状态机（4 状态）** → [03-核心概念](03-核心概念.md)
-- **连接网关** → [04-连接与认证](04-连接与认证.md)
-- **网关自动发现** → [04-连接与认证](04-连接与认证.md)
-- **连接状态事件** → [06-API手册](06-API手册.md)
-
-### E2EE 端到端加密
-- **E2EE 机制概述** → [03-核心概念](03-核心概念.md)
-- **加密消息收发** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **V2-only P2P/GROUP 明文与加密时序** → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
-- **会话管理** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **GROUP epoch key 轮换竞态/补测清单** → [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md)
-- **GROUP E2EE 现状对比与演进建议** → [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md)
-- **E2EEManager API** → [06-API手册](06-API手册.md)
-- **E2EE 错误类** → [07-错误处理](07-错误处理.md)
-- **E2EE 幂等运行** → [08-最佳实践](08-最佳实践.md)
-
-### RPC 调用与事件
-- **`client.call()` 模式** → [04-连接与认证](04-连接与认证.md)
-- **`client.on()` 事件订阅** → [04-连接与认证](04-连接与认证.md)
-- **裸 WebSocket RPC 调用** → [02-WebSocket协议](02-WebSocket协议.md)
-- **内置事件列表** → [06-API手册](06-API手册.md)
-- **RPC 手册索引** → [06-API手册](06-API手册.md)
-- **多语言 SDK gap、字段、事件、调用链路对齐审查** → [多语言SDK使用场景与调用链路对齐审查清单](多语言SDK使用场景与调用链路对齐审查清单.md)
-- **消息 payload 类型总览与格式约定** → [09-payload-reference](09-payload-reference.md)
-- **Group RPC 与群设置、群消息、群思考内容收发** → [09-group-rpc-manual](09-group-rpc-manual.md)
-- **Message RPC 与 P2P 消息、P2P 思考内容收发** → [09-message-rpc-manual](09-message-rpc-manual.md)
-- **Meta RPC** → [09-meta-rpc-manual](09-meta-rpc-manual.md)
-- **Storage RPC** → [09-storage-rpc-manual](09-storage-rpc-manual.md)
-- **Stream RPC** → [09-stream-rpc-manual](09-stream-rpc-manual.md)
-
-### 配置与存储
-- **构造参数** → [01-快速开始](01-快速开始.md)
-- **数据目录布局** → [01-快速开始](01-快速开始.md)
-- **自定义 KeyStore** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **自定义 SecretStore** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **多 AID 隔离** → [08-最佳实践](08-最佳实践.md)
-- **环境变量配置** → [08-最佳实践](08-最佳实践.md)
-
-### 错误处理
-- **错误类层级** → [07-错误处理](07-错误处理.md)
-- **错误码对照表** → [07-错误处理](07-错误处理.md)
-- **重试策略** → [07-错误处理](07-错误处理.md)
+
+- AID 格式、证书、不可变值对象 → [03-核心概念](03-核心概念.md)
+- `AIDStore.register()` / `load()` / `exists()` / `resolve()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
+- AID 构造约束与多语言入口 → [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md)
+- 认证链路和 token → [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md)
+- AID 托管恢复 / 跨设备复制 → [09-custody-api-manual](09-custody-api-manual.md)
+
+### 连接与状态
+
+- 九态状态机 → [03-核心概念](03-核心概念.md)
+- `connect()` 选项、长短连接、网关发现 → [04-连接与认证](04-连接与认证.md)
+- capability getter、事件、生命周期 API → [06-API手册](06-API手册.md)
+- 裸 WebSocket 握手 → [02-WebSocket协议](02-WebSocket协议.md)
+
+### E2EE
+
+- E2EE 原理和默认行为 → [03-核心概念](03-核心概念.md)
+- ProtectedHeaders、prekey、replay guard → [05-E2EE加密通信](05-E2EE加密通信.md)
+- V2 P2P/GROUP 时序 → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
+- 高级 E2EE API → [06-API手册](06-API手册.md)
+- 解密失败排查 → [07-错误处理](07-错误处理.md)
+
+### RPC 与事件
+
+- `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
+- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
+- Group RPC → [09-group-rpc-manual](09-group-rpc-manual.md)
+- Storage RPC → [09-storage-rpc-manual](09-storage-rpc-manual.md)
+- Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
+- Stream RPC → [09-stream-rpc-manual](09-stream-rpc-manual.md)
+- Payload 格式 → [09-payload-reference](09-payload-reference.md)
+
+### 错误与测试
+
+- Result 与异常层级 → [07-错误处理](07-错误处理.md)
+- 重试策略 → [07-错误处理](07-错误处理.md)
+- 幂等连接、多 AID、资源清理 → [08-最佳实践](08-最佳实践.md)
+- 集成 / E2E 运行顺序 → [../aun测试运行指南.md](../aun测试运行指南.md)
 
 ---
 
-## Layer 3：文档详细摘要
+## Layer 3：文档摘要
 
 ### 01-快速开始
-入门文档。双客户端最小可运行示例（创建 AID → 认证 → 连接 → 消息收发 → 关闭），pip 安装命令，AUNClient 构造参数，数据目录布局。
+
+说明安装、三主体模型、Python 最小消息收发示例、`AIDStore` / `AID` / `AUNClient` 的职责和 TS/JS/Go 构造约束。
 
 ### 02-WebSocket协议
-底层协议细节。连接握手流程（challenge → auth.connect → hello-ok），消息格式（RPC 请求/响应/事件通知），裸 WebSocket 完整示例。适合在其他语言中实现客户端。
+
+说明 Gateway WebSocket 握手、JSON-RPC 请求/响应/通知格式，以及裸 WebSocket 客户端如何借助 SDK 完成 token 获取。
 
 ### 03-核心概念
-SDK 的核心抽象。AID 域名格式身份及本地密钥对管理；连接状态机及自动重连；认证流程（挑战-应答）；E2EE 两级离线加密流程。
 
-### 04-连接与认证
-SDK 高层封装。`register_aid` + `authenticate` 认证流程；`connect` 参数（含自动重连、心跳、令牌刷新）；`client.call()` RPC 调用模式；`client.on()` 事件订阅。
+解释 AID 身份、三主体职责、九态状态机、认证挑战-响应、默认 E2EE 行为和 RPC/事件模型。
 
-### 05-E2EE加密通信
-E2EE 完整收发流程（加密发送 + 监听解密 + 后台消息循环）；`protected_headers` 与可验证 `context` 元数据；密钥管理（prekey 缓存 / replay guard / group epoch）；自定义 `KeyStore` / `SecretStore` Protocol。
+### 04-连接与认证
 
-### E2EE_V2消息通信时序图
-当前 V2-only 实现下的主通信链路图。覆盖 V2 设备密钥注册、P2P 明文、P2P 加密、GROUP 明文、GROUP 加密五条时序；明确 P2P 加密走 `message.send` 承载 `e2ee.p2p_encrypted`，GROUP 加密走 `group.v2.send` 承载 `e2ee.group_encrypted`，接收端统一通过 V2 pull 后由 SDK 解密。
+描述 `AIDStore` 注册加载、`AUNClient` 身份加载、显式认证、连接选项、长短连接共存、网关发现、agent.md 和 RPC 调用。
 
-### GROUP-E2EE轮换竞态清单
-GROUP epoch key 两阶段轮换的状态边界和竞态检查项。覆盖 pending 期间成员变更、leader 竞争、分发/ack/commit 失败、stale pending、key recovery、旧 epoch 保留等场景，用于补充测试和实现审查。
+### 05-E2EE加密通信
 
-### GROUP-E2EE现状对比与改进建议
-当前 GROUP E2EE 实现的架构评估。对比 Signal Private Groups、WhatsApp Sender Key、Matrix Megolm 和 MLS，明确 AUN 当前处于“内容 E2EE + 服务端可见成员关系”的安全层级；列出旧 epoch key 恢复、signed group state commit、manifest hash / epoch chain 绑定、多设备模型和 epoch 内前向安全等改进方向。
+覆盖默认加密发送、接收自动解密、ProtectedHeaders、prekey、群 E2EE、replay guard 和高级存储扩展边界。
 
 ### 06-API手册
-完整 API 文档。AUNClient 构造函数/属性/方法；AuthNamespace 方法；E2EEManager 方法；内置事件列表；RPC 手册索引。
+
+列出 AIDStore、AID、AUNClient、事件、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
 
 ### 07-错误处理
-`AUNError` 基类及子类层级；错误属性；错误码速查表；指数退避重试策略；常见错误场景。
+
+说明 Result 字典、AUNError 异常层级、错误码映射、重试策略和常见错误场景。
 
 ### 08-最佳实践
-幂等连接初始化；安全关闭；E2EE 幂等运行；多 AID 隔离；环境变量驱动配置；资源清理。
 
-### 10-custody-api-manual
-AID 托管 HTTP API。通过手机号验证码上传和下载 AID 证书、客户端加密后的私钥密文；定义 `send-code`、`bind-phone`、`restore-phone` 主流程；补充旧设备 AID token 授权的跨设备复制流程、CT 记录要求及安全边界。
+给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control 和测试数据保护建议。
 
-### 09-payload-reference
-`message.send`、`message.thought.put`、`group.send` 和 `group.thought.put` 共用的业务 payload 约定。包含 `payload.type` 类型总览、信封字段边界、公共辅助字段、提及语义、`thought` 思考内容、群消息 `dispatch_mode`、各类型字段格式、交互卡片及 `action_card_reply`、`status` / `event` 任务生命周期约定、附件引用规范和降级处理建议。
+### 09-*-rpc-manual
 
-### 多语言SDK使用场景与调用链路对齐审查清单
-多语言 SDK 与服务端的总审查文档。覆盖使用场景清单、主调用链路、错误/超时/竞态分支、字段与事件对齐矩阵、高影响问题总表，以及旧清单复审结论。
+各业务服务的 RPC 参数、响应和错误语义。SDK 不为每个 RPC 提供一层业务 wrapper，应用直接通过 `client.call()` 调用。

package/_packed_docs/sdk/README.md

@@ -1,307 +1,126 @@
-# AUN Protocol — Python SDK
+# AUN Protocol - SDK 文档
 
-## 概述
-
-AUN（Agent Union Network）定义 Agent 之间安全通信的标准接口——基于 WebSocket + JSON-RPC 2.0，涵盖身份、认证、消息和 Agent 间自主交互，不绑定单一通信拓扑。
+AUN（Agent Union Network）定义 Agent 之间安全通信的标准接口，基于 WebSocket + JSON-RPC 2.0，涵盖身份、认证、消息、群组、存储、流式传输和端到端加密。
 
 ---
 
 ## 核心要点
 
-**问题**：AI Agent 被困在各自的平台里，无法跨域通信与协作。
-
-**AUN 的答案**：
-
-- **AID 身份**：`{name}.{issuer}` 格式的全局唯一标识（如 `alice.agentid.pub`），基于 X.509 证书链
-- **三种连接模式**：协议层定义 Gateway（标准接入）、Peer（点对点直连）、Relay（中继转发）三种模式；当前各语言 SDK 的连接层稳定支持 Gateway，Peer/Relay 仍处于协议定义状态
-- **Agent 工具使用展示**：原生 `tool_call` / `tool_result` payload 类型，用于在 IM/查看端可视化展示 Agent 的工具使用过程（**不是跨 Agent 能力调用契约**）
-
-```
-                  ┌─ Gateway ──→ 标准接入（浏览器/移动端/服务端）
-Agent A ← WSS → ─┤─ Peer ─────→ 点对点直连（同内网/低延迟）
-                  └─ Relay ────→ 中继转发（NAT 穿透/轻量部署）
-```
-
-**本 SDK** 是 AUN 协议的 Python 客户端实现。`pip install fastaun` 即可使用。
+- **AID 身份**：`{name}.{issuer}` 格式的全局唯一标识，例如 `alice.agentid.pub`，基于 X.509 证书链。
+- **三主体 SDK 模型**：`AIDStore` 管理 keystore，`AID` 是不可变身份值对象，`AUNClient` 管理连接与会话。
+- **Gateway 连接**：当前各语言 SDK 稳定支持 Gateway 接入；Peer / Relay 仍处于协议定义或未实现状态。
+- **默认 E2EE**：P2P 和 Group V2 消息默认加密；普通明文消息需要显式关闭加密。
+- **统一 RPC**：业务方法通过 `client.call(method, params)` 调用，事件通过 `client.on(event, handler)` 订阅。
 
 ---
 
-## 深入了解
-
-### AID 身份体系
-
-AID（Agent Identifier）是 AUN 的核心身份标识，格式为 `{name}.{issuer}`：
+## 快速开始
 
+```bash
+pip install fastaun
 ```
-alice.agentid.pub           ← agentid.pub 签发的 Agent
-weather-bot.aun.pub     ← aun.pub 签发的天气 Agent
-data-agent.corp.io      ← 企业自有域名签发的内部 Agent
-```
-
-任何拥有域名的组织都可以成为 Issuer，签发自己的 AID。AUN 采用标准 X.509 v3 证书和 ECDSA 算法，通过**四级证书链**建立联邦信任机制：
-
-```
-Root CA → Registry CA → Issuer CA → Agent 证书
-```
-
-### 协议分层
 
-```
-Layer 4: 服务层   — auth服务、ca服务、message服务、storage服务、group服务、mail服务、
-                    stream服务、meta服务、search服务、relay服务、泛域名解析服务
-                    （peer.*、task.* 仅有协议定义，无对应服务）
-Layer 3: 协议层   — auth.* / ca.* / message.* / storage.* / group.* / mail.* / stream.* /
-                    meta.* / search.* / task.* / peer.* / relay.*
-Layer 2: 通信层   — WebSocket + JSON-RPC 2.0 / HTTP/HTTPS
-Layer 1: 安全层   — TLS 1.3（传输加密）+ AUN E2EE（端到端加密）
-```
+```python
+import asyncio
+import random
+from aun_core import AIDStore, AUNClient
 
-### 三种连接模式
+DOMAIN = "agentid.pub"
+ALICE = f"alice-{random.randint(1000,9999)}.{DOMAIN}"
+BOB = f"bob-{random.randint(1000,9999)}.{DOMAIN}"
 
-| 模式 | 认证方式 | 适用场景 |
-|------|---------|---------|
-| **Gateway** | `auth.*` JWT 认证 | 浏览器、移动端、标准接入 |
-| **Peer** | `peer.*` 证书互验 | 同内网、已知地址、低延迟 |
-| **Relay** | `relay.*` 穿透中继 | 双方在 NAT 后、轻量中继 |
 
-三种模式共享相同的 AID 身份、X.509 证书信任体系和业务层 API（`message.*`、`meta.*` 等）。
+async def create_client(aid: str) -> AUNClient:
+    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+    loaded = store.load(aid)
+    if not loaded["ok"]:
+        registered = await store.register(aid)
+        if not registered["ok"]:
+            raise RuntimeError(registered["error"]["message"])
+        loaded = store.load(aid)
 
-**当前 SDK 实现状态**：
+    client = AUNClient(loaded["data"]["aid"], debug=True)
+    await client.connect({"slot_id": "main", "auto_reconnect": True})
+    return client
 
-| SDK | Gateway | Peer | Relay |
-|-----|---------|------|-------|
-| Python | 已实现 | `connect(topology={"mode":"peer"})` 明确报未实现 | `connect(topology={"mode":"relay"})` 明确报未实现 |
-| Browser JS | 已实现 | 明确报未实现 | 明确报未实现 |
-| TypeScript | 已实现 | 明确报未实现 | 明确报未实现 |
-| Go | 已实现（当前按 `gateway` URL 建立会话） | 未实现独立 peer 传输 | 未实现独立 relay 传输 |
 
-> `peer.*` / `relay.*` 出现在协议表中，表示协议命名空间已定义，不代表 SDK 的 `connect()` 已支持对应拓扑。
+async def main():
+    alice = await create_client(ALICE)
+    bob = await create_client(BOB)
 
-### 消息类型
+    received = asyncio.Event()
+    bob.on("message.received", lambda e: (print(f"Bob 收到: {e['payload']}"), received.set()))
 
-| type | 说明 | 场景 |
-|------|------|------|
-| `text` | 纯文本消息 | Agent 间自然语言交流 |
-| `json` | 结构化数据消息 | 传递参数、配置、状态 |
-| `tool-call` | **Agent 工具调用过程标注**（请求段） | 由发送方标注自身正在调用的本地工具，供查看端渲染 |
-| `tool-result` | **Agent 工具调用过程标注**（结果段） | 由同一发送方标注本地工具的执行结果，供查看端渲染 |
-| `event` | 事件通知 | 状态变更、异步回调 |
-| `binary-ref` | 文件引用 | 文件分享（图片、视频、文档等，实际数据走 storage，通过 `mime_type` 区分文件类型） |
+    await alice.call("message.send", {
+        "to": BOB,
+        "payload": {"type": "text", "text": "Hello from Alice!"},
+    })
 
-`tool-call` / `tool-result` 由**同一发送方**先后发出，描述自己的工具使用过程；接收方收到后**不需要执行、不需要响应**，仅用于结构化展示（如 IM 的工具气泡、折叠卡片）。它不是跨 Agent 调用契约。
+    await asyncio.wait_for(received.wait(), timeout=5)
+    await alice.close()
+    await bob.close()
 
----
 
-## 协议详解
-
-### 架构总览
-
-```mermaid
-graph TD
-    subgraph Client["客户端 / Agent"]
-        Browser["浏览器"]
-        Mobile["移动端"]
-        Desktop["桌面/服务器 Agent"]
-    end
-
-    subgraph Access["接入模式"]
-        GW["Gateway"]
-        Peer["Peer 直连"]
-        Relay["Relay 中继"]
-    end
-
-    subgraph Infra["基础设施"]
-        Auth["Auth 服务 / Issuer CA"]
-        Roots["Root CA 列表"]
-    end
-
-    subgraph Services["AUN 服务"]
-        direction LR
-        Message["Message"] --- Group["Group"] --- Storage["Storage"] --- Stream["Stream"]
-    end
-
-    Browser --> GW
-    Mobile --> GW
-    Desktop --> GW
-    Desktop -.-> Peer
-    Desktop --> Relay
-
-    GW --> Services
-
-    Browser -.证书/JWT.-> Auth
-    Desktop -.证书/JWT.-> Auth
-    Auth --> Roots
-```
-
-- **Auth 服务 / Issuer CA** 是必须的基础设施（AID 注册、证书签发、JWT 签发）
-- **Gateway** 是最常见的接入方式，但不是协议唯一入口
-- **Peer / Relay** 模式下，身份验证基于证书链，本地即可完成
-
-### 协议层（RPC 方法）
-
-| 命名空间 | 职责 | 关键方法 |
-|----------|------|----------|
-| `auth.*` | 身份认证、JWT 签发与刷新 | register_aid / authenticate / refresh_token |
-| `peer.*` | 对等认证、证书互验 | hello / verify / establish |
-| `relay.*` | 中继注册与转发 | register / forward / unregister |
-| `message.*` | 消息收发、离线队列、P2P 思考内容 | send / pull / ack / recall / thought.put / thought.get |
-| `meta.*` | 元信息查询 | ping / status / trust_roots |
-| `group.*` | 群组生命周期、成员管理、群设置、群消息 | create / invite / set_settings / send / thought.put / thought.get / dissolve |
-| `storage.*` | 文件上传下载、权限管理 | upload / download / share |
-| `stream.*` | 实时流式传输（推流 WS / 拉流 SSE） | create / close / get_info / list_active |
-| `mail.*` | 异步邮件式消息 | send / list / read |
-| `search.*` | Agent 与能力搜索发现 | query / browse |
-| `task.*` | 跨 Agent 任务协作 | create / assign / update / complete |
-
-协议层可由用户自定义扩展命名空间。
-
-> `peer.*` / `relay.*` 目前主要是协议规范与服务侧能力定义；当前 SDK 的连接建立与会话生命周期仍以 Gateway 为主。
-
-### 消息层
-
-AUN 使用 JSON-RPC 2.0 原生三类消息：
-
-| 类型 | 有 `id` | 说明 |
-|------|:-------:|------|
-| **Request** | 是 | 调用方法，期望对端返回 Response |
-| **Response** | 是 | 对 Request 的回复（`result` 或 `error`） |
-| **Notification** | 否 | 单向通知，无需回复 |
-
-命名约定区分用途：
-
-| 前缀 | 示例 | 用途 |
-|------|------|------|
-| `namespace.action` | `message.send` | Request 方法名 |
-| `event/xxx` | `event/message.received` | 业务层事件推送 |
-| `notification/xxx` | `notification/initialized` | 协议级通知 |
-
-### 安全模型
-
-- **四级证书链**：Root CA → Registry CA → Issuer CA → Agent 证书，双向验证
-- **Challenge-Response**：Nonce 防重放 + 时间戳验证
-- **Token 体系**：access_token（短期）+ refresh_token（长期，一次性）
-- **E2EE**：协议层可扩展多种密码学套件，当前 Python SDK 仅实现 P-256 + HKDF-SHA256 + AES-256-GCM。可叠加于任意连接模式
-
-> **⚠️ V2 群 E2EE 安全等级警示**
->
-> V2 群消息加密强度取决于群的 `join_mode`：
->
-> - **end_to_end（真正端到端）**：`approval` / `closed` 群。新成员必须经 owner/admin 签名确认，可防服务端注入幽灵成员窃听
-> - **transport（仅传输加密）**：`open` / `invite_code` / `invite_only` 群。任何人可自由入群，wrap 接收方不绑定到授权成员，**E2EE 等同传输层加密，不提供"仅授权成员可读"保证**
->
-> `group.v2.bootstrap` 响应中的 `e2ee_security_level` 字段标识当前群的安全等级。**UI 应在 transport 等级群中显著提示用户"非端到端加密"**，避免用户对安全保证产生误判。
-
-### Gateway 模式连接流程
-
-```mermaid
-sequenceDiagram
-    participant C as Agent
-    participant G as Gateway
-
-    C->>G: WebSocket 连接
-    G->>C: challenge（nonce, protocol, auth_methods）
-    C->>G: auth.connect（nonce, token, protocol）
-    G->>C: hello-ok（identity, capabilities）
-    Note over C,G: 握手完成，进入双向 RPC / 事件通信
-    C->>G: message.send / group.create / ...
-    G->>C: event/message.received / ...
+asyncio.run(main())
 ```
 
-### Agent 生命周期
-
-```mermaid
-stateDiagram-v2
-    [*] --> 未注册
-    未注册 --> 已注册: register_aid（生成密钥对 + 签发证书）
-    已注册 --> 已认证: authenticate（Challenge-Response）
-    已认证 --> 已连接: connect（WebSocket）
-    已连接 --> 已连接: call / on（业务操作）
-    已连接 --> 断线重连: 网络断开
-    断线重连 --> 已连接: Token 有效
-    断线重连 --> 已注册: Token 过期
-    已连接 --> 已注册: close / logout
-    已注册 --> [*]: deregister
-```
+---
 
-### AUN 协议完整文档
+## 多语言构造约束
 
-协议文档随 SDK 包一起分发，安装后位于 `aun_core/docs/protocol/`：
+| 语言 | options-only | AID + options |
+|------|--------------|---------------|
+| Python | `AUNClient(debug=True)` | `AUNClient(aid, debug=True)` |
+| TypeScript | `new AUNClient({ debug: true })` | `new AUNClient(aid, { debug: true })` |
+| JavaScript | `new AUNClient({ debug: true })` | `new AUNClient(aid, { debug: true })` |
+| Go | `aun.NewAUNClient(aun.AUNClientOptions{Debug: true})` | `aun.NewAUNClient(aid, aun.AUNClientOptions{Debug: true})` |
 
-| 文档 | 内容 |
-|------|------|
-| [00-总览与分层](../src/aun_core/docs/protocol/00-总览与分层.md) | 协议总览、分层架构 |
-| [01-身份与凭证协议](../src/aun_core/docs/protocol/01-身份与凭证协议-auth.md) | auth.* 方法定义 |
-| [02-证书与信任体系](../src/aun_core/docs/protocol/02-证书与信任体系.md) | 四级证书链、信任模型 |
-| [03-Gateway连接模式](../src/aun_core/docs/protocol/03-Gateway-连接模式.md) | Gateway 连接流程 |
-| [04-Peer子协议](../src/aun_core/docs/protocol/04-Peer-子协议.md) | 对等认证 |
-| [05-Relay子协议](../src/aun_core/docs/protocol/05-Relay-子协议.md) | 中继转发 |
-| [06-服务协议](../src/aun_core/docs/protocol/06-服务协议.md) | message/meta/search/task/group/stream |
-| [08-AUN-E2EE](../src/aun_core/docs/protocol/08-AUN-E2EE.md) | 端到端加密 |
-| [10-Group子协议](../src/aun_core/docs/protocol/10-Group-子协议.md) | 群组管理 |
-| [11-Storage子协议](../src/aun_core/docs/protocol/11-Storage-子协议.md) | 对象存储 |
-| [12-Stream子协议](../src/aun_core/docs/protocol/12-Stream-子协议.md) | 实时流式传输 |
+`aid` 必须是 AID 对象，不是字符串。不要把 aid 放进 options，也不要使用旧的 `(config, debug)` 构造形态。
 
 ---
 
-## SDK 快速开始
+## 协议分层
 
-```bash
-pip install fastaun
+```text
+Layer 4: 服务层   auth / ca / message / group / storage / stream / meta / search
+Layer 3: 协议层   JSON-RPC 方法命名空间
+Layer 2: 通信层   WebSocket + JSON-RPC 2.0 / HTTP
+Layer 1: 安全层   TLS + AUN E2EE
 ```
 
-```python
-import asyncio, random
-from aun_core import AUNClient
-
-DOMAIN = "agentid.pub"
-ALICE = f"alice-{random.randint(1000,9999)}.{DOMAIN}"
-BOB   = f"bob-{random.randint(1000,9999)}.{DOMAIN}"
-
-async def create_client(aid: str) -> tuple[AUNClient, dict]:
-    client = AUNClient({"aun_path": f"~/.aun/{aid}"})
-    identity = client._auth.load_identity_or_none(aid)
-    if not identity:
-        await client.auth.register_aid({"aid": aid})
-    auth = await client.auth.authenticate({"aid": aid})
-    return client, auth
-
-async def main():
-    alice, alice_auth = await create_client(ALICE)
-    bob, bob_auth = await create_client(BOB)
-
-    received = asyncio.Event()
-    bob.on("message.received", lambda e: (print(f"Bob 收到: {e['payload']}"), received.set()))
-
-    await alice.connect(alice_auth, {})
-    await bob.connect(bob_auth, {})
-
-    await alice.call("message.send", {
-        "to": BOB,
-        "payload": {"type": "text", "text": "Hello from Alice!"},
-    })
-
-    try:
-        await asyncio.wait_for(received.wait(), timeout=5.0)
-    except asyncio.TimeoutError:
-        pull = await bob.call("message.pull", {"after_seq": 0, "limit": 10})
-        for m in pull.get("messages", []):
-            print(f"Bob 拉取: {m.get('payload')}")
+### 连接模式
 
-    await alice.close()
-    await bob.close()
+| 模式 | 当前 SDK 状态 | 说明 |
+|------|---------------|------|
+| Gateway | 已实现 | 浏览器、移动端、服务端标准接入 |
+| Peer | 未实现或明确报未实现 | 协议命名空间已定义 |
+| Relay | 未实现或明确报未实现 | 协议命名空间已定义 |
 
-asyncio.run(main())
-```
+---
 
-### SDK 文档
+## 文档入口
 
 | 章节 | 说明 |
 |------|------|
-| [01-快速开始](01-快速开始.md) | 安装、配置、双客户端消息收发完整示例 |
+| [01-快速开始](01-快速开始.md) | 安装、三主体模型、最小示例、多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID、连接状态机、认证流程、E2EE |
-| [04-连接与认证](04-连接与认证.md) | 认证封装、call()、on()、网关发现 |
-| [05-E2EE加密通信](05-E2EE加密通信.md) | 端到端加密收发、ProtectedHeaders、密钥管理、自定义存储 |
-| [06-API手册](06-API手册.md) | AUNClient / AuthNamespace / E2EEManager 完整 API |
-| [07-错误处理](07-错误处理.md) | 错误类层级、错误码速查、重试策略 |
-| [08-最佳实践](08-最佳实践.md) | 幂等初始化、多 AID 隔离、资源清理 |
+| [03-核心概念](03-核心概念.md) | AID、AIDStore、AUNClient、九态状态机、E2EE |
+| [04-连接与认证](04-连接与认证.md) | 注册、加载、认证、连接、事件、agent.md |
+| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 收发、ProtectedHeaders、密钥管理 |
+| [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / 事件 / RPC 索引 |
+| [07-错误处理](07-错误处理.md) | Result、异常层级、错误码、重试策略 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接、多 AID、资源清理、测试数据保护 |
+
+RPC 专项手册：
+
+| 手册 | 范围 |
+|------|------|
+| [09-message-rpc-manual.md](09-message-rpc-manual.md) | P2P 消息、ack、thought |
+| [09-group-rpc-manual.md](09-group-rpc-manual.md) | 群组生命周期、成员、群消息、群 thought |
+| [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | 文件和对象存储 |
+| [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | ping / status / trust_roots |
+| [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | 流式数据传输 |
+| [09-payload-reference.md](09-payload-reference.md) | message / group payload 结构 |
+| [09-custody-api-manual.md](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
+
+协议文档随 SDK 包分发，位于 `aun_core/docs/protocol/`。