@agentunion/fastaun-browser 0.3.6 → 0.4.1

package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -1,52 +1,50 @@
-# AUN SDK Python - 错误处理
+# AUN SDK - 错误处理
 
 ---
 
 ## 错误类层级
 
-```
+```text
 AUNError
-├── ConnectionError        # 网络连接失败
-├── TimeoutError           # 操作超时
-├── AuthError              # 认证失败（code: 4001/4010/-32001/-32003）
-│   ├── CertificateRevokedError  # 证书已吊销（code: -32050）
-│   └── IdentityConflictError    # 身份冲突（code: 4090）
-├── PermissionError        # 权限不足（code: 4030/403/-32004）
-├── ValidationError        # 参数校验失败（code: 4000/-32600/-32601/-32602）
-├── NotFoundError          # 资源不存在（code: 4040/404/-32008）
-├── RateLimitError         # 请求限流（code: 4290/429/-32029），retryable=True
-├── VersionConflictError   # 版本冲突（code: -32009）
-├── StateError             # 非法状态操作
-├── SerializationError     # JSON 序列化失败
-├── SessionError           # 会话错误（code: -32010/-32011/-32013）
-├── ClientSignatureError   # 客户端签名验证失败（code: -32051）
+├── ConnectionError
+├── TimeoutError
+├── AuthError
+│   ├── CertificateRevokedError
+│   └── IdentityConflictError
+├── PermissionError
+├── ValidationError
+├── NotFoundError
+├── RateLimitError
+├── VersionConflictError
+├── StateError
+├── SerializationError
+├── SessionError
+├── ClientSignatureError
 ├── GroupError
-│   ├── GroupNotFoundError  # code: -33001
-│   └── GroupStateError     # code: -33002/-33003
 └── E2EEError
-    ├── E2EEDecryptFailedError              # P2P 消息解密失败
-    ├── E2EEDegradedError                   # E2EE 降级为 long_term_key（无 prekey 可用）
-    ├── E2EEGroupSecretMissingError         # code: -32040，缺少群密钥
-    ├── E2EEGroupEpochMismatchError         # code: -32041，epoch 不匹配
-    ├── E2EEGroupCommitmentInvalidError     # code: -32042，成员承诺验证失败
-    ├── E2EEGroupNotMemberError             # code: -32043，请求者非群成员
-    └── E2EEGroupDecryptFailedError         # code: -32044，群消息解密失败
 ```
 
-## 错误属性
+`AIDStore` / `AID` 的可失败方法优先返回 Result 字典；`AUNClient.connect()` / `call()` 等会话方法保留抛异常风格。
+
+Result 格式：
 
 ```python
-from aun_core import AUNError
+loaded = store.load("alice.agentid.pub")
+if not loaded["ok"]:
+    print(loaded["error"]["code"], loaded["error"]["message"])
+```
+
+异常属性：
 
+```python
 try:
-    await client.call("method.name", {...})
+    await client.call("message.send", params)
 except AUNError as e:
-    e.code       # int，错误码
-    e.data       # Any，附加数据
-    e.retryable  # bool，是否可重试
-    e.trace_id   # str | None，追踪 ID
+    print(e.code, e.data, e.retryable, e.trace_id)
 ```
 
+---
+
 ## 错误码速查
 
 | 范围 | 含义 | 对应异常 |
@@ -56,24 +54,20 @@ except AUNError as e:
 | 4030 / 403 | 权限不足 | `PermissionError` |
 | 4040 / 404 | 资源不存在 | `NotFoundError` |
 | 4290 / 429 | 请求限流 | `RateLimitError` |
-| -32001 / -32003 | 认证失败（协议级） | `AuthError` |
-| -32004 | 权限不足（协议级） | `PermissionError` |
-| -32008 | 资源不存在（协议级） | `NotFoundError` |
+| -32001 / -32003 | 认证失败 | `AuthError` |
+| -32004 | 权限不足 | `PermissionError` |
+| -32008 | 资源不存在 | `NotFoundError` |
 | -32009 | 版本冲突 | `VersionConflictError` |
 | -32010 / -32011 / -32013 | 会话错误 | `SessionError` |
-| -32029 | 请求限流（协议级） | `RateLimitError` |
+| -32029 | 请求限流 | `RateLimitError` |
 | -32600 / -32601 / -32602 | JSON-RPC 参数错误 | `ValidationError` |
-| -32040 | 缺少群密钥 | `E2EEGroupSecretMissingError` |
-| -32041 | 群 epoch 不匹配 | `E2EEGroupEpochMismatchError` |
-| -32042 | 成员承诺验证失败 | `E2EEGroupCommitmentInvalidError` |
-| -32043 | 密钥请求者非群成员 | `E2EEGroupNotMemberError` |
-| -32044 | 群消息解密失败 | `E2EEGroupDecryptFailedError` |
+| -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
 | 4090 | 身份冲突 | `IdentityConflictError` |
 | -32050 | 证书已吊销 | `CertificateRevokedError` |
 | -32051 | 客户端签名验证失败 | `ClientSignatureError` |
-| -33001 | 群组不存在 | `GroupNotFoundError` |
-| -33002 / -33003 | 群组状态异常 | `GroupStateError` |
-| -33004 ~ -33009 | 群组通用错误 | `GroupError` |
+| -33001 ~ -33009 | 群组错误 | `GroupError` 子类 |
+
+---
 
 ## 重试策略
 
@@ -87,82 +81,68 @@ async def send_with_retry(client, params, max_retries=3):
         except RateLimitError:
             await asyncio.sleep(2 ** i)
         except AuthError:
-            raise  # 认证错误不重试
+            raise
         except AUNError as e:
             if not e.retryable or i == max_retries - 1:
                 raise
             await asyncio.sleep(0.5)
 ```
 
+---
+
 ## 常见错误场景
 
-### 未认证就发消息
+### 未加载身份
 
 ```python
-# ❌ 错误：跳过认证直接操作
 client = AUNClient()
-await client.call("message.send", {...})  # → AuthError
-
-# ✅ 正确：先认证再操作
-auth = await client.auth.authenticate({"aid": MY_AID})
-await client.connect(auth, {})
-await client.call("message.send", {...})
+await client.connect()  # StateError: no_identity
 ```
 
-### E2EE 解密失败
+修复方式：
 
 ```python
-# E2EEDecryptFailedError — prekey 不匹配、AAD 篡改、密文损坏
-# SDK 自动处理：解密失败的消息返回原始密文，不中断其他消息
+loaded = store.load(MY_AID)
+client.load_identity(loaded["data"]["aid"])
+await client.connect({"auto_reconnect": True})
 ```
 
-### 群组 E2EE 错误
+### 传入字符串 AID 构造客户端
 
 ```python
-# E2EEGroupSecretMissingError — 发送加密群消息时本地无群密钥
-# 常见于建群后 create_epoch 尚未完成、或通过邀请码入群后尚未恢复密钥
-# SDK 会抛出此异常，调用方可捕获后等待密钥恢复完成再重试
-# SDK 自动编排：建群后自动 create_epoch；缺密钥时自动发起恢复请求
-
-# E2EEGroupDecryptFailedError — 群消息解密失败（密钥不匹配或密文损坏）
-# 协议层定义的错误语义，当前 Python SDK 的部分路径表现为返回 None、拒绝状态或跳过自动解密，不一定抛出对应异常
-
-# E2EEGroupEpochMismatchError — 收到的密钥分发 epoch 低于当前 epoch
-# 协议层定义的错误语义，当前 Python SDK 的部分路径表现为返回 None、拒绝状态或跳过自动解密，不一定抛出对应异常
+AUNClient("alice.agentid.pub")  # TypeError / ValidationError
+```
 
-# E2EEGroupCommitmentInvalidError — 收到的密钥分发中成员承诺校验失败
-# 协议层定义的错误语义，当前 Python SDK 的部分路径表现为返回 None、拒绝状态或跳过自动解密，不一定抛出对应异常
-# 可能原因：中间人篡改、成员列表不一致
+AID 必须来自 `AIDStore.load()`：
 
-# E2EEGroupNotMemberError — 密钥恢复请求被拒，请求者不在群成员列表中
-# 协议层定义的错误语义，当前 Python SDK 的部分路径表现为返回 None、拒绝状态或跳过自动解密，不一定抛出对应异常
+```python
+me = store.load("alice.agentid.pub")["data"]["aid"]
+client = AUNClient(me)
 ```
 
-### 身份冲突（v0.3.4+）
+### 身份冲突
 
 ```python
-from aun_core import IdentityConflictError
-
-try:
-    await client.auth.register_aid({"aid": "alice.agentid.pub"})
-except IdentityConflictError as e:
-    # e.code == 4090
-    # 场景 1：AID 已被他人注册（公钥不匹配）→ 换一个 AID
-    # 场景 2：本地有身份但服务端无记录 → 清理本地目录后重试
-    print(f"身份冲突: {e}")
+registered = await store.register("alice.agentid.pub")
+if not registered["ok"] and registered["error"]["code"] == "IDENTITY_CONFLICT":
+    print("AID 已被其他密钥注册，换名或恢复原私钥")
 ```
 
-跨语言类名统一为 `IdentityConflictError`（Python / Go / TS / JS）。
+不要通过删除本地 `AIDs/` 目录解决冲突；私钥丢失后无法证明原 AID 所有权。
 
 ### 连接状态错误
 
 ```python
-# ❌ 错误：断连后直接调用
-await client.call("message.send", {...})  # → ConnectionError("client is not connected")
-
-# ✅ 正确：重新认证并启用自动重连
-auth = await client.auth.authenticate({"aid": MY_AID})
-await client.connect(auth, {
-    "auto_reconnect": True,
-})
+await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionError / StateError
 ```
+
+发送前检查：
+
+```python
+if not client.can_send:
+    await client.connect({"auto_reconnect": True})
+```
+
+### E2EE 解密失败
+
+P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 `message.undecryptable` / `group.message_undecryptable` 事件，应用可记录并继续处理其他消息。

package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -1,104 +1,117 @@
-# AUN SDK Python - 最佳实践
+# AUN SDK - 最佳实践
 
 ---
 
-## 1. 幂等的连接初始化
+## 1. 幂等加载身份并连接
 
-每次启动时安全地确保已认证并连接，无论是首次还是重复运行：
+```python
+async def ensure_ready(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)
+
+    me = loaded["data"]["aid"]
+    client = AUNClient(me, debug=True)
+    await client.connect({"slot_id": "main", "auto_reconnect": True})
+    return client
+```
+
+要点：
+
+- 先 `load()`，只有本地身份不存在时才 `register()`。
+- 注册后重新 `load()`，不要把字符串 AID 直接传给 `AUNClient`。
+- 连接前先订阅关键事件，避免漏掉首个状态变更或消息推送。
+
+---
+
+## 2. 多 AID 管理
 
 ```python
-async def ensure_connected(client: AUNClient, aid: str) -> str:
-    try:
-        await client.auth.register_aid({"aid": aid})
-    except Exception as e:
-        print(f"注册 AID 失败: {e}")
-        raise
-    auth = await client.auth.authenticate({"aid": aid})
-    await client.connect(auth, {"auto_reconnect": True})
-    return aid
+store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+alice = store.load("alice.agentid.pub")["data"]["aid"]
+bob = store.load("bob.agentid.pub")["data"]["aid"]
+
+alice_client = AUNClient(alice)
+bob_client = AUNClient(bob)
 ```
 
-## 2. 安全关闭多个客户端
+一个 `aun_path` 可管理多个 AID。不要把 `aun_path` 命名为某个 AID，否则会产生冗余嵌套路径。
+
+---
+
+## 3. 安全关闭
 
 ```python
 async def close_all(*clients: AUNClient):
-    for c in clients:
+    for client in clients:
         try:
-            await c.close()
+            await client.close()
         except Exception:
             pass
 ```
 
-## 3. E2EE 幂等运行
+`close()` 后客户端进入 `closed` 状态。若要复用对象，必须重新 `load_identity(AID对象)`。
 
-每次运行前清除旧 prekey 缓存并跳过历史消息，避免计数器冲突：
+---
+
+## 4. E2EE 幂等运行
 
 ```python
-# 清除旧 prekey 缓存
 sender.e2ee.invalidate_prekey_cache(peer_aid=receiver_aid)
 receiver.e2ee.invalidate_prekey_cache(peer_aid=sender_aid)
 
-# 跳过旧消息（获取当前最大 seq 作为 cursor 起点）
-r = await receiver.call("message.pull", {"after_seq": 0, "limit": 1})
-recv_cursor = r.get("latest_seq", 0)
-```
-
-## 4. 多 AID 管理
-
-一个 `aun_path` 可管理多个 AID，每个 AID 数据隔离在 `{aun_path}/AIDs/{aid}/` 下：
-
-```python
-# 推荐：用应用名作为 aun_path，多个 AID 共存于同一目录
-client = AUNClient({"aun_path": "~/.aun/myapp"})
-
-# 注册不同的 AID，各自数据自动隔离
-await client.auth.register_aid({"aid": "alice.agentid.pub"})
-await client.auth.register_aid({"aid": "bob.agentid.pub"})
-# 数据分别在 ~/.aun/myapp/AIDs/alice.agentid.pub/ 和 bob.agentid.pub/ 下
+cursor = await receiver.call("message.pull", {"after_seq": 0, "limit": 1})
+recv_cursor = cursor.get("latest_seq", 0)
 ```
 
-> **注意**：不要用 AID 名称作为 `aun_path`（如 `~/.aun/{aid}`），否则会产生冗余嵌套。
-
-## 5. 环境变量驱动配置
+测试和 demo 中建议跳过历史消息，避免旧消息、旧 prekey、旧游标影响当前断言。
 
-```python
-import os
-from pathlib import Path
+---
 
-DATA_ROOT = os.environ.get("AUN_DATA_ROOT", str(Path.home() / ".aun"))
-```
+## 5. protected_headers
 
-## 6. 资源清理
+实例级 `protected_headers` 适合放 SDK 版本、运行环境、调用方链路标识等需要签名保护的元数据：
 
 ```python
-async def main():
-    client = AUNClient()
-    try:
-        await ensure_connected(client, aid)
-        # ... 业务逻辑
-    finally:
-        await client.close()
+client = AUNClient(me, protected_headers={"sdk": "python", "app": "demo"})
+client.set_protected_headers({"sdk": "python", "trace": "abc"})
 ```
 
-## 参考
-
-- 协议文档：`../src/aun_core/docs/protocol/`
-- SDK 架构文档：`../src/aun_core/docs/skill/sdk-core/`
-- RPC 方法手册：`../src/aun_core/docs/skill/rpc-manual/`
-- 可运行示例：`../src/aun_core/docs/skill/examples/`
-- GitHub：https://github.com/ModelUnion/aun-sdk-core
+只对 `message.send`、`group.send`、`message.thought.put`、`group.thought.put` 生效。
 
 ---
 
-## 7. Flow Control（v0.3.4+）
+## 6. Flow Control
 
 SDK 内部自动管理 RPC 并发，应用层无需配置：
 
 | 机制 | 说明 |
 |------|------|
 | RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
-| 后台 RPC 限制 | 后台任务（prekey 上传、token 刷新等）额外限制为 8 个 |
-| Pull Gate | 同一 namespace/group 的 pull 操作自动序列化，防止并发 pull 导致重复消息 |
-| 队列超时 | 排队等待超过 timeout 时抛 `TimeoutError("rpc queue timeout before send: {method}")` |
+| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
+| Pull Gate | 同一 namespace/group 的 pull 操作自动序列化 |
+| 队列超时 | 排队超过 timeout 抛 `TimeoutError` |
+
+应用层保持普通 `await client.call(...)` 即可。
 
-这些限制在高并发场景下保护服务端不被单客户端打满，同时避免 pull 竞态导致的消息乱序。应用层只需正常调用 `client.call()`，SDK 自动排队和限流。
+---
+
+## 7. 测试数据保护
+
+- 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
+- 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。
+- 需要换身份时使用新的 AID 名称，避免制造不可恢复的 key mismatch。
+
+---
+
+## 参考
+
+- 协议文档：`../src/aun_core/docs/protocol/`
+- RPC 方法手册：`09-*-rpc-manual.md`
+- E2EE 说明：[05-E2EE加密通信.md](05-E2EE加密通信.md)
+- API 手册：[06-API手册.md](06-API手册.md)

package/_packed_docs/sdk/09-custody-api-manual.md

@@ -2,7 +2,7 @@
 
 AID Custody 是 AUN AP 可选提供的 AID 备份、恢复与跨设备复制服务，不属于 AUN 核心协议强制能力。当前阶段定义两条主流程：通过手机号和验证码上传、下载 AID 证书以及客户端加密后的私钥文件；以及旧设备通过 AID token 授权，新设备凭一次性复制码领取 OTP 加密材料的跨设备复制流程。
 
-用户也可以部署自己的 AID 托管服务。只要服务地址发现格式和本手册定义的 HTTP 接口、请求响应语义保持一致，SDK 即可通过 `client.custody.set_url(...)` 或 well-known 自动发现接入自部署服务。
+用户也可以部署自己的 AID 托管服务。只要服务地址发现格式和本手册定义的 HTTP 接口、请求响应语义保持一致，SDK 即可通过 custody 辅助客户端或 well-known 自动发现接入自部署服务。
 
 核心原则：
 
@@ -19,8 +19,9 @@ https://aid_custody.{issuer_domain}:{port}
 SDK 使用约束：
 
 - `custody_url` 不作为 `AUNClient` 构造配置参数传入。
-- 客户端通过 `client.custody.set_url(...)` 显式配置托管服务地址。
-- 也可以通过 `client.custody.discover_url(aid=...)` 从 `https://{aid}/.well-known/aun-custody` 自动发现官方托管服务地址；发现结果会缓存在当前 `client.custody` 实例中。
+- Python SDK 不在 `AUNClient` 上挂载 custody namespace；需要时使用独立 custody 辅助客户端或直接按本手册 HTTP API 调用。
+- TS / JS / Go 仍保留历史 custody namespace 兼容层；新代码应避免把 custody 当作 AUNClient 核心会话能力。
+- 可通过 `https://{aid}/.well-known/aun-custody` 自动发现官方托管服务地址，并缓存发现结果。
 
 ## 手机号验证码备份/恢复时序
 
@@ -94,9 +95,9 @@ SDK 方法：
 
 | 语言 | 发起复制 | 上传复制材料 | 领取复制材料 |
 |------|----------|--------------|--------------|
-| Python | `client.custody.create_device_copy(...)` | `client.custody.upload_device_copy_materials(...)` | `client.custody.claim_device_copy(...)` |
-| JS/TS | `client.custody.createDeviceCopy(...)` | `client.custody.uploadDeviceCopyMaterials(...)` | `client.custody.claimDeviceCopy(...)` |
-| Go | `client.Custody.CreateDeviceCopy(...)` | `client.Custody.UploadDeviceCopyMaterials(...)` | `client.Custody.ClaimDeviceCopy(...)` |
+| Python | 独立 custody 辅助客户端或 HTTP API | 独立 custody 辅助客户端或 HTTP API | 独立 custody 辅助客户端或 HTTP API |
+| JS/TS | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API |
+| Go | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API |
 
 复制请求：
 

package/_packed_docs/sdk/09-meta-rpc-manual.md

@@ -74,7 +74,7 @@ print(f"模式: {status['mode']}")
 
 该 RPC 适合已连接客户端查询。首次信任根更新应优先使用公开 HTTP 端点 `GET https://trust.aun.network/.well-known/aun/trust-roots.json`，不可达时可使用 Issuer PKI 泛域名端点 `GET https://pki.{issuer}/trust-root.json` 或 Gateway 镜像 `GET https://gateway.{issuer}/pki/trust-roots.json`。无论来源是 RPC 还是 HTTP，客户端导入前都必须验证 `authority_signature`。
 
-Issuer PKI 泛域名服务还必须公开 `GET https://pki.{issuer}/root.crt`，用于下载该 issuer 证书链锚定的 Root CA PEM。客户端通过 `client.meta.update_issuer_root_cert(issuer)` 更新指定 issuer 的根证书时，必须先确认该证书指纹存在于已验签的受信根列表中。
+Issuer PKI 泛域名服务还必须公开 `GET https://pki.{issuer}/root.crt`，用于下载该 issuer 证书链锚定的 Root CA PEM。SDK 在 `AIDStore.load()` / `resolve()` 的证书链验证流程中按需更新指定 issuer 的根证书；写入本地信任锚前必须确认该证书指纹存在于已验签的受信根列表中。
 
 ### 参数
 
@@ -120,23 +120,22 @@ Issuer PKI 泛域名服务还必须公开 `GET https://pki.{issuer}/root.crt`，
 ### 示例
 
 ```python
-trust_list = await client.meta.trust_roots()
-client.meta.import_trust_roots(trust_list, authority_cert_pem=authority_cert_pem)
+trust_list = await client.call("meta.trust_roots", {})
+# 信任根验证、导入和 issuer root 更新由 AIDStore 内部证书链验证流程按需处理。
 ```
 
 ---
 
-## Python SDK `MetaNamespace` 辅助方法
+## SDK 信任根辅助能力
 
-以下方法属于 SDK 本地辅助能力，不是新的服务端 RPC；底层只在需要时调用 `meta.trust_roots` 或公开 HTTP 端点。
+以下能力属于 SDK 本地证书链验证流程，不是新的服务端 RPC；底层只在需要时调用 `meta.trust_roots` 或公开 HTTP 端点。
 
-| 方法 | 说明 |
+| 能力 | 说明 |
 |------|------|
-| `await client.meta.download_trust_roots(...)` | 从管理局权威端点、`pki.{issuer}` 或 Gateway 镜像下载受信根列表 |
-| `client.meta.verify_trust_roots(...)` | 验证受信根列表结构、签名、证书 CA 约束、有效期和 SHA-256 指纹 |
-| `client.meta.import_trust_roots(...)` | 验证后写入本地 `trust-roots.json` / `trust-roots.pem` 并刷新信任根缓存 |
-| `await client.meta.refresh_trust_roots(...)` | 下载、验证并导入受信根列表 |
-| `await client.meta.download_issuer_root_cert(issuer, ...)` | 从 `https://pki.{issuer}/root.crt` 下载指定 issuer 的 Root CA PEM |
-| `await client.meta.update_issuer_root_cert(issuer, ...)` | 校验证书为自签 Root CA，且指纹存在于已验签受信根列表后导入本地 |
-
-`update_issuer_root_cert()` 不信任下载来源本身；它必须以已验签的受信根列表为准，确认 `root.crt` 的 SHA-256 指纹已列入 `root_cas` 后才能写入本地信任锚。
+| 下载受信根列表 | 从管理局权威端点、`pki.{issuer}` 或 Gateway 镜像下载 |
+| 验证受信根列表 | 校验结构、签名、证书 CA 约束、有效期和 SHA-256 指纹 |
+| 导入受信根列表 | 验证后写入本地 `trust-roots.json` / `trust-roots.pem` 并刷新缓存 |
+| 下载 issuer root | 从 `https://pki.{issuer}/root.crt` 下载指定 issuer 的 Root CA PEM |
+| 更新 issuer root | 校验证书为自签 Root CA，且指纹存在于已验签受信根列表后导入本地 |
+
+更新 issuer root 时不信任下载来源本身；必须以已验签的受信根列表为准，确认 `root.crt` 的 SHA-256 指纹已列入 `root_cas` 后才能写入本地信任锚。

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -1,74 +1,62 @@
-# AUN SDK Python 文档查阅指南
+# AUN SDK 文档查阅指南
 
-AUN SDK 文档在 `docs/sdk/` 下，索引文件 `docs/sdk/INDEX.md` 分三层，**严格按需逐层加载，禁止一次性读取整个索引**。
-
-行区间格式：`L43-49` 表示用 Read 工具读取时读取第 43 行到 49 行。
+AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：Layer 1 地图、Layer 2 主题索引、Layer 3 单篇摘要。按需逐层读取，避免一次性加载整套文档。
 
 ## SDK 文档定位
 
-SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信任根（`client.meta`）** 和 **E2EE（`client.e2ee`）**。AID 托管是可选 HTTP 服务，查 `10-custody-api-manual.md`。
-
-其他业务操作（消息、群组、存储等）通过 `client.call(method, params)` 调用 RPC 方法，参数和响应格式见 `docs/sdk/09-*-rpc-manual.md`；`message.send` / `message.thought.put` / `group.send` / `group.thought.put` 的业务 payload 共用格式见 `docs/sdk/09-payload-reference.md`。
-
-## 渐进式查阅流程
-
-### Step 1：只读 Layer 1（L7-34）
+当前 SDK 聚焦三主体模型：
 
-列出所有文档名和章节行区间。能直接定位目标 → 跳 Step 4。
+- `AIDStore`：注册、加载、列举、解析和证书运维。
+- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
+- `AUNClient`：认证、连接、状态机、事件和 RPC。
 
-### Step 2：按需读 Layer 2 对应小节
+业务操作统一通过 `client.call(method, params)` 调用；消息、群组、存储、meta、stream 的参数见 `09-*-rpc-manual.md`。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。
 
-仅当 Step 1 不够时，按关键词读：
+## 渐进式查阅流程
 
-身份与认证 L40-45 · 连接与状态 L47-52 · E2EE L54-63 · RPC与事件 L65-77 · 配置与存储 L79-85 · 错误处理 L87-90 · AID托管 L45
+### Step 1：读 Layer 1
 
-### Step 3：按需读 Layer 3 单篇摘要
+查看文档地图，能定位目标就直接读目标文档。
 
-仅当需要某篇详情但不确定读哪个章节时：
+### Step 2：按主题读 Layer 2
 
-快速开始 L96-97 · WebSocket协议 L99-100 · 核心概念 L102-103 · 连接与认证 L105-106 · E2EE加密通信 L108-109 · E2EE_V2消息通信时序图 L111-112 · GROUP-E2EE轮换竞态清单 L114-115 · GROUP-E2EE现状对比与改进建议 L117-118 · API参考 L120-121 · 错误处理 L123-124 · 最佳实践 L126-127 · AID托管 L129-130 · 消息Payload L132-133 · 多语言SDK对齐审查 L135-136
+常见主题：
 
-大多数问题在摘要层就能解答。
+- 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
+- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
+- E2EE：默认加密、ProtectedHeaders、P2P / Group V2
+- RPC 与事件：`client.call()`、`client.on()`、RPC 手册
+- 错误处理：Result、异常、错误码、重试
 
-### Step 4：读原文目标章节
+### Step 3：读 Layer 3 摘要
 
-根据前面获得的文档路径和行区间，精确读取对应章节。**只有需要完整分析时才读整篇原文。**
+不确定哪篇文档包含细节时，先看单篇摘要，再打开原文目标章节。
 
 ## 文档总览
 
 | 编号 | 文档 | 定位 |
 |------|------|------|
-| 01 | [快速开始](01-快速开始.md) | 安装、配置、最小示例 |
-| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket 示例 |
+| 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
+| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket |
 | 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
-| 04 | [连接与认证](04-连接与认证.md) | 认证封装、call()、on()、连接 |
-| 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 |
-| 07 | [错误处理](07-错误处理.md) | 错误类层级、错误码、重试 |
-| 08 | [最佳实践](08-最佳实践.md) | 幂等、隔离、资源清理 |
-| 10 | [AID托管API手册](10-custody-api-manual.md) | 手机号验证码、证书与加密私钥备份恢复、跨设备复制 |
-| - | [09-payload-reference](09-payload-reference.md) | `message.send` / `message.thought.put` / `group.send` / `group.thought.put` 共用业务负载格式、类型总览、思考内容、交互卡片/action_card_reply、任务事件、附件引用 |
-| - | [多语言SDK使用场景与调用链路对齐审查清单](多语言SDK使用场景与调用链路对齐审查清单.md) | 多语言场景、调用链路、字段对齐、竞态和服务端风险总表 |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件 |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE、ProtectedHeaders、密钥管理 |
+| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / 事件 / RPC |
+| 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、多 AID、资源清理、测试数据 |
+| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
+| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
 
 ## 常见查阅场景
 
 | 场景 | 推荐路径 |
 |------|----------|
-| 首次使用 SDK | 01-快速开始 全文 |
-| 裸 WebSocket 或其他语言实现 | 02-WebSocket协议 |
-| 理解 AID / E2EE 原理 | 03-核心概念 对应章节 |
-| 认证 + 连接 + call/on 用法 | 04-连接与认证 |
-| 需要加密通信 | 05-E2EE加密通信 |
-| 需要查看 E2EE V2 消息主链路时序 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) |
-| GROUP E2EE 轮换竞态/测试设计 | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) |
-| GROUP E2EE 架构评估/演进路线 | [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) |
-| 查消息或思考内容 payload 类型和格式 | [09-payload-reference](09-payload-reference.md) |
-| 查某个方法的签名 | 06-API手册 |
-| 遇到报错需排查 | 07-错误处理 |
-| 部署前检查 | 08-最佳实践 |
-| AID 证书和加密私钥托管恢复/跨设备复制 | 10-custody-api-manual |
-| 查 RPC 方法参数 | `docs/sdk/*-rpc-manual.md` |
-| 多语言 SDK 功能 gap / 字段和事件对齐 / 失败分支审查 | [多语言SDK使用场景与调用链路对齐审查清单](多语言SDK使用场景与调用链路对齐审查清单.md) |
+| 首次使用 SDK | [01-快速开始](01-快速开始.md) |
+| 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
+| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
+| 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
+| 查方法签名 | [06-API手册](06-API手册.md) |
+| 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
+| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
+| 排查错误 | [07-错误处理](07-错误处理.md) |
+| 写测试或 demo | [08-最佳实践](08-最佳实践.md) |