@agentunion/fastaun-browser 0.3.3 → 0.3.5

package/_packed_docs/protocol//351/231/204/345/275/225N-/345/210/206/345/270/203/345/274/217Trace/345/215/217/350/256/256.md

@@ -0,0 +1,257 @@
+# 附录 N — 分布式 Trace 协议
+
+## 设计目标
+
+为 AUN RPC 调用链路（SDK → Gateway → Service → Gateway → SDK）提供轻量级的分布式追踪能力，
+支持两种使用场景：
+
+1. **日志关联（log 模式）** — 全链路日志通过 `trace_id` 串联，零开销，可在生产环境常开
+2. **诊断回传（diag 模式）** — 各环节追加 span，response 携带完整链路返回调用者，
+   仅用于疑难问题诊断，需通过开关启用
+
+不依赖 OpenTelemetry / Jaeger 等外部体系，自定义 `_trace` 字段即可，跨语言实现成本极低。
+
+---
+
+## 一、协议层
+
+### 1.1 字段位置
+
+`_trace` 字段位于 JSON-RPC `params` 内，沿用 AUN 现有框架字段约定（与 `_caller_id`、`_auth` 同级）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "message.send",
+  "params": {
+    "to": "bob.aid.com",
+    "body": "hello",
+    "_trace": {
+      "trace_id": "a1b2c3d4e5f6...",
+      "mode": "log"
+    }
+  }
+}
+```
+
+### 1.2 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `trace_id` | string | 是 | 32 hex chars（16 bytes 随机），由 SDK 生成，全链路唯一 |
+| `mode` | string | 是 | `"log"` 或 `"diag"`，缺失视为 `"log"` |
+| `spans` | array | 否 | 仅 `diag` 模式存在，各环节追加 |
+
+**说明**：`mode: "off"` 不需要显式表示——不带 `_trace` 字段即为 off 状态。
+
+### 1.3 Span 结构
+
+```json
+{
+  "node": "gateway",
+  "ts": 1716300000156,
+  "action": "relay_in",
+  "ms": 0,
+  "detail": "route→message"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `node` | string | 环节标识：`sdk-{aid}`、`gateway`、`{service_name}` |
+| `ts` | number | Unix 毫秒时间戳（入站时刻） |
+| `action` | string | 动作：`send` / `relay_in` / `process` / `relay_out` / `deliver` |
+| `ms` | number | 本环节处理耗时（出站时填写，入站初始为 0） |
+| `detail` | string | 可选，关键上下文（路由目标、错误码等），最多 256 字符 |
+
+---
+
+## 二、链路传播流程
+
+```
+SDK-A                Gateway              Service             Gateway              SDK-B
+  │                    │                    │                    │                    │
+  │─── params._trace ─▶│                    │                    │                    │
+  │  {trace_id, mode,  │                    │                    │                    │
+  │   spans:[sdk-send]}│                    │                    │                    │
+  │                    │── 追加 gateway ───▶│                    │                    │
+  │                    │   转发到 service   │                    │                    │
+  │                    │                    │── 追加 svc span ──▶│                    │
+  │                    │                    │   返回 response    │                    │
+  │                    │◀── response ───────│                    │                    │
+  │                    │   追加 gateway-out │                    │                    │
+  │◀── response._trace─│                    │                    │                    │
+  │                    │                    │                    │                    │
+  │                    │─── event._trace ──────────────────────▶│── deliver ────────▶│
+```
+
+### 2.1 各环节职责
+
+| 环节 | 入站行为 | 出站行为 |
+|------|----------|----------|
+| SDK 发起 | 生成 trace_id；mode≠off 时构造 `_trace` 注入 params | — |
+| Gateway 入站 | 读取 _trace，应用降级；diag 模式追加 `relay_in` span | — |
+| Service 处理 | 读取 _trace 写入日志（log）或追加 span（diag） | response 透传 _trace |
+| Gateway 出站 | diag 模式追加 `relay_out` span | log 模式剥离 _trace；diag 模式注入 response 顶层 |
+| SDK 接收 | 提取 response._trace 回调 trace observer | — |
+
+---
+
+## 三、Response 回传（仅 diag 模式）
+
+Gateway 在 `deliver_response_to_client` 中将 `_trace` 注入 response 顶层（与 `_meta` 平级）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {"status": "ok", "message_id": "..."},
+  "_meta": {"agent_md_etag": "..."},
+  "_trace": {
+    "trace_id": "a1b2c3...",
+    "mode": "diag",
+    "spans": [
+      {"node": "sdk-alice.aid.com", "ts": 1716300000100, "action": "send"},
+      {"node": "gateway", "ts": 1716300000123, "action": "relay_in", "ms": 2, "detail": "→message"},
+      {"node": "message", "ts": 1716300000125, "action": "process", "ms": 15},
+      {"node": "gateway", "ts": 1716300000142, "action": "relay_out", "ms": 1}
+    ]
+  }
+}
+```
+
+**注意**：log 模式下 response 不带 `_trace`（保持 envelope 干净，零开销）。
+
+---
+
+## 四、开关层级
+
+### 4.1 三态定义
+
+| 值 | 行为 |
+|---|---|
+| `off` | 不生成 `_trace`，零开销（默认） |
+| `log` | 生成 trace_id + 各环节写本地日志，response 不回传 |
+| `diag` | 同 log + spans 追加 + response 回传完整链路 |
+
+### 4.2 控制点
+
+| 层级 | 配置位置 | 默认值 | 作用 |
+|------|----------|--------|------|
+| 服务端上限 | Gateway 环境变量 `AUN_TRACE_MAX_MODE` | `"log"` | 超过此级别自动降级 |
+| SDK 会话级 | `client.set_trace_mode("log")` | `"off"` | 连接内所有请求默认 mode |
+| SDK 调用级 | `client.rpc("method", params, trace="diag")` | 继承会话级 | 单次覆盖，优先级最高 |
+
+### 4.3 优先级规则
+
+```
+最终 mode = min(SDK 调用级 || SDK 会话级, 服务端上限)
+其中 off < log < diag
+```
+
+### 4.4 服务端降级逻辑（Gateway 入站时）
+
+```python
+client_mode = trace.get("mode", "off")
+server_max = config.trace_max_mode  # "off" | "log" | "diag"
+effective = min(client_mode, server_max)
+if effective != client_mode:
+    trace["mode"] = effective
+    if effective != "diag":
+        trace.pop("spans", None)  # 降级到 log/off 时丢弃已有 spans
+```
+
+**生产环境推荐配置**：`AUN_TRACE_MAX_MODE=log`，diag 需运维手动开启。
+
+---
+
+## 五、各组件改动点
+
+### 5.1 SDK 侧
+
+**`transport.py`**：
+- `call()` 方法：会话/调用级 mode 非 off 时，构造 `_trace` 注入 params
+- response 处理：提取 `_trace` 回调 trace observer（与现有 `_meta_observer` 模式一致）
+
+**`client.py`**：
+- 新增 `set_trace_mode(mode: str)`：设置会话级默认 mode
+- `rpc()` 方法新增 `trace` 参数：单次覆盖 mode
+- 暴露 `set_trace_observer(callback)`：接收 diag 模式回传的 spans
+
+### 5.2 Gateway 侧
+
+**`ws_server.py`**：
+- `_resolve_ws_message_trace()` 改造：读取 mode，应用服务端降级
+- 入站时追加 `relay_in` span（diag 模式）
+- `_strip_internal_route()` 保持现状：log 模式仍剥离 `_trace`，diag 模式由 response 路径专门处理
+
+**`relay.py`**：
+- `deliver_response_to_client()`：diag 模式追加 `relay_out` span，将 `_trace` 注入 response 顶层
+
+### 5.3 Service 侧
+
+通用 pattern（适用于 message / group / storage / stream / mail 等所有服务）：
+1. RPC 入口提取 `params._trace`
+2. 处理过程中通过 trace_id 写入日志
+3. diag 模式追加自身 span
+4. response 透传 `_trace` 字段
+
+---
+
+## 六、日志格式（log 模式）
+
+各环节按现有日志规范输出，前缀加 trace_id：
+
+```
+[2026-05-21 10:00:00.123][INFO][gateway] [trace=a1b2c3d4] relay_in method=message.send conn=42
+[2026-05-21 10:00:00.125][INFO][message] [trace=a1b2c3d4] process persist=true target=bob.aid.com
+[2026-05-21 10:00:00.140][INFO][gateway] [trace=a1b2c3d4] relay_out duration_ms=17
+```
+
+排查时 `grep trace=a1b2c3d4` 即可串联全链路。
+
+---
+
+## 七、安全约束
+
+| 约束 | 限制 |
+|------|------|
+| spans 数组最大长度 | 32 条，超出由 Gateway 截断尾部 |
+| 单个 detail 最大长度 | 256 字符 |
+| trace_id 长度 | 严格 32 hex chars，不合规由 Gateway 重新生成 |
+| 敏感信息 | spans 禁止包含消息体、密钥、Token 等，只记录路由/耗时/错误码等元数据 |
+| 生产环境默认 | `AUN_TRACE_MAX_MODE=log`，diag 需运维手动开启 |
+| 跨域传播 | 跨 federation 边界时保留 trace_id，spans 在边界节点视为新链路起点 |
+
+---
+
+## 八、跨语言实现要点
+
+所有 SDK（Python / Go / TypeScript / JavaScript / C++）需保持一致：
+
+1. **trace_id 生成**：16 字节加密随机数，hex 编码
+2. **时间戳**：Unix 毫秒（不使用秒/纳秒），统一单位
+3. **字段顺序**：JSON 字段顺序不影响语义，但建议按 `trace_id, mode, spans` 顺序输出便于阅读
+4. **observer 接口**：各 SDK 提供 `set_trace_observer(callback)` 接口，签名一致
+5. **会话/调用级 API 命名**：
+   - 设置：`set_trace_mode(mode)` / `setTraceMode(mode)`
+   - 单次覆盖：`rpc(method, params, trace=mode)` / `rpc(method, params, {trace: mode})`
+
+---
+
+## 九、未实现 / 后续扩展
+
+以下能力本附录暂不覆盖，留作后续扩展：
+
+- **采样率控制**：当前 SDK 完全控制 mode，未引入概率采样（如 1% diag）
+- **OpenTelemetry 适配**：未来如需对接 Jaeger / Zipkin，可在 Gateway 端增加导出适配层，
+  将 spans 转为 OTLP 格式
+- **跨域链路连续性**：当前跨 federation 边界视为新链路，未实现端到端 trace_id 透传
+- **span 父子关系**：当前 spans 数组仅按时间排序，未引入 parent_span_id（保持极简）
+
+---
+
+## 文档版本
+
+- v1.0 — 2026-05-21 初稿，定义协议字段、链路传播、开关层级、安全约束

package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -30,17 +30,17 @@ BOB = f"bob{random.randint(1000,9999)}.{DOMAIN}"
 
 
 async def create_client(aid: str) -> tuple[AUNClient, dict]:
-    """创建客户端 → 加载或创建 AID → 认证 → 返回 (client, auth)"""
+    """创建客户端 → 注册 AID → 认证 → 返回 (client, auth)"""
     client = AUNClient()  # 默认 aun_path: ~/.aun
 
     # 先检查本地是否已有该 AID 的身份
     known = any(item["aid"] == aid for item in client.list_identities())
     if not known:
-        # 不存在则创建
+        # 不存在则注册
         try:
-            await client.auth.create_aid({"aid": aid})
+            await client.auth.register_aid({"aid": aid})
         except AuthError as e:
-            print(f"[错误] 创建 AID 失败 ({aid}): {e}")
+            print(f"[错误] 注册 AID 失败 ({aid}): {e}")
             raise
         except ConnectionError as e:
             print(f"[错误] 网络连接失败: {e}")
@@ -213,7 +213,7 @@ await client.connect(auth, {
 完整的使用流程见上方"最小示例"，核心步骤：
 
 1. **创建客户端** - `AUNClient(config)`
-2. **加载或创建 AID** - `load_identity_or_none()` → `create_aid()`
+2. **注册 AID** - `check_aid()` → `register_aid()`
 3. **认证** - `authenticate()` 获取令牌
 4. **订阅事件** - `on("message.received", handler)`
 5. **连接** - `connect(auth, options)`

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -210,7 +210,7 @@ async def authenticate(aid: str) -> dict:
     try:
         client = AUNClient({"aun_path": f"~/.aun/{aid}"})
         if not client._auth.load_identity_or_none(aid):
-            await client.auth.create_aid({"aid": aid})
+            await client.auth.register_aid({"aid": aid})
         auth = await client.auth.authenticate({"aid": aid})
         return auth
     except AuthError as e:

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -19,8 +19,8 @@ AID 是 Agent 的全局唯一身份，格式为域名形式：`alice.agentid.pub
 import random
 MY_AID = f"alice-{random.randint(1000,9999)}.agentid.pub"
 
-# 创建（仅首次）
-await client.auth.create_aid({"aid": MY_AID})
+# 注册（仅首次）
+await client.auth.register_aid({"aid": MY_AID})
 
 # 认证
 auth = await client.auth.authenticate({"aid": MY_AID})

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -2,7 +2,47 @@
 
 ---
 
-## 创建 AID 和认证
+## v0.3.4 行为变更
+
+### 注册与认证分离
+
+v0.3.4 起，`authenticate()` **不再隐式注册**。如果本地无完整身份（缺 keypair 或 cert），`authenticate()` 直接抛 `StateError`。
+
+正确流程：
+
+```python
+await client.auth.register_aid({"aid": aid})   # 1. 注册（生成密钥对 + 获取证书）
+auth = await client.auth.authenticate({"aid": aid})  # 2. 认证（获取 token）
+await client.connect(auth, {})                 # 3. 连接
+```
+
+**半成品恢复**：如果本地有 keypair 但无 cert（上次注册中断），`register_aid()` 会自动向服务端查询并恢复证书，无需手动清理。
+
+### 身份查询 API
+
+v0.3.4 新增两个只读 API，用于检查本地身份状态（无网络请求、无副作用）：
+
+```python
+# 加载身份（不存在时抛 StateError）
+identity = client.auth.load_identity({"aid": aid})
+
+# 加载身份（不存在时返回 None）
+identity = client.auth.load_identity_or_none({"aid": aid})
+
+# 获取对端证书 PEM（本地缓存优先，未命中走 PKI）
+cert_pem = await client.auth.fetch_peer_cert({"aid": peer_aid})
+```
+
+### 迁移说明
+
+| 旧 API（v0.3.3-） | 新 API（v0.3.4+） |
+|---|---|
+| `create_aid()` | `register_aid()`（已移除 `create_aid`） |
+| `authenticate()` 自动注册 | 必须先显式调用 `register_aid()` |
+
+---
+
+## 注册 AID 和认证
 
 ```python
 from aun_core import AUNClient
@@ -10,12 +50,12 @@ from aun_core import AUNClient
 async def setup(aid: str):
     client = AUNClient()  # 默认 aun_path: ~/.aun
 
-    # 创建 AID
+    # 注册 AID
     try:
-        result = await client.auth.create_aid({"aid": aid})
+        result = await client.auth.register_aid({"aid": aid})
         # result: {"aid": ..., "cert_pem": ..., "gateway": ...}
     except Exception as e:
-        print(f"创建 AID 失败: {e}")
+        print(f"注册 AID 失败: {e}")
         raise
 
     auth = await client.auth.authenticate({"aid": aid})
@@ -159,7 +199,7 @@ print(client.aid)    # "alice.agentid.pub"
 
 ## 网关自动发现
 
-`create_aid()` / `authenticate()` 内部会自动发现 Gateway。
+`register_aid()` / `authenticate()` 内部会自动发现 Gateway。
 
 - 生产配置（`verify_ssl=true`）下，优先尝试 `https://{aid}/.well-known/aun-gateway`
 - 若失败，则回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
@@ -204,7 +244,7 @@ Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
 
 ### 推荐主 API（自 v0.x 起）
 
-SDK 在 `AUNClient` 上提供三个一站式主方法，分别封装"发布"、"下载"、"一致性检查"三条主线。文件统一存放在 `{aun_path}/AgentMDs/{aid}/agent.md`，由 SDK 管理；元数据持久化到 `agent_md_cache` 表 / `list.json`。
+SDK 在 `AUNClient` 上提供三个一站式主方法，分别封装"发布"、"下载"、"一致性检查"三条主线。文件统一存放在 `{aun_path}/AgentMDs/{aid}/agent.md`，由 SDK 管理；元数据持久化到 `agent_md_cache` 表 / `agentmd.json`。
 
 ```python
 # 发布自己的 agent.md（读 SDK 管理的本地文件 → 签名 → 上传 → 刷新内部 etag）

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -23,9 +23,11 @@
 - [check_gateway_health()](#await-check_gateway_healthgateway_url-str-timeout-float--50---bool) - 检查网关可用性
 
 ### [AUNClient.Auth](#authnamespace-clientauth)
-- [create_aid()](#await-create_aidparams-dict---dict) - 注册新 AID
+- [register_aid()](#await-register_aidparams-dict---dict) - 注册新 AID
 - [check_aid()](#await-check_aidparams-dict---dict) - 检查 AID 状态（本地完整性 + 远程注册）
 - [authenticate()](#await-authenticateparams-dict--none---dict) - 认证获取令牌
+- [load_identity()](#load_identityparams-dict--none--none---dict) - 只读加载本地身份
+- [fetch_peer_cert()](#await-fetch_peer_certparams-dict---str) - 获取对端证书
 - [sign_agent_md()](#await-sign_agent_mdcontent-str-aid-str--none---str) - 为 agent.md 生成尾部签名 **（已 deprecated，建议改用 `client.publish_agent_md`）**
 - [verify_agent_md()](#await-verify_agent_mdcontent-str-aid-str--none-cert_pem-str--none---dict) - 验证 agent.md 尾部签名 **（已 deprecated，建议改用 `client.fetch_agent_md`）**
 - [upload_agent_md()](#await-upload_agent_mdcontent-str---dict) - 上传自己的 agent.md **（已 deprecated，建议改用 `client.publish_agent_md`）**
@@ -405,7 +407,7 @@ for item in identities:
 - 传入非空路径：切换到指定目录
 - 传入空字符串或 `None`：恢复默认目录 `{aun_path}/AgentMDs`
 - 目录不存在时自动创建
-- 切换后清空内存中的 agent.md 缓存（下次操作会重新从磁盘/list.json 加载）
+- 切换后清空内存中的 agent.md 缓存（下次操作会重新从磁盘/agentmd.json 加载）
 
 **API 跨语言对齐：**
 
@@ -423,11 +425,12 @@ for item in identities:
 
 ```
 {agent_md_path}/
-├── list.json                    # 所有 AID 的元数据索引
 ├── {aid_1}/
-│   └── agent.md                 # aid_1 的 agent.md 正文
+│   ├── agent.md                 # aid_1 的 agent.md 正文
+│   └── agentmd.json             # aid_1 的元数据（etag、时间戳等）
 ├── {aid_2}/
-│   └── agent.md
+│   ├── agent.md
+│   └── agentmd.json
 └── ...
 ```
 
@@ -448,7 +451,7 @@ client.set_agent_md_path()  # 回到 {aun_path}/AgentMDs
 
 ### `await publish_agent_md() -> dict` — agent.md 发布主 API
 
-读取 SDK 管理的本地 `agent.md`（路径：`{aun_path}/AgentMDs/{self_aid}/agent.md`）→ 调用 `auth.sign_agent_md` 在尾部追加 `<!-- AUN-SIGNATURE -->` 块 → 调用 `auth.upload_agent_md` 上传到服务端 → 以**上传字节的 sha256**计算 quoted etag 写入内部 `_local_agent_md_etag` 与持久化缓存（`agent_md_cache` 表 / `list.json`），使后续应用事件 payload 中的 `_agent_md.local_etag` 字段反映服务端实际生效的版本。
+读取 SDK 管理的本地 `agent.md`（路径：`{aun_path}/AgentMDs/{self_aid}/agent.md`）→ 调用 `auth.sign_agent_md` 在尾部追加 `<!-- AUN-SIGNATURE -->` 块 → 调用 `auth.upload_agent_md` 上传到服务端 → 以**上传字节的 sha256**计算 quoted etag 写入内部 `_local_agent_md_etag` 与持久化缓存（`agent_md_cache` 表 / `agentmd.json`），使后续应用事件 payload 中的 `_agent_md.local_etag` 字段反映服务端实际生效的版本。
 
 **API 跨语言对齐：**
 
@@ -484,7 +487,7 @@ print(result["agent_md_url"], result["etag"])
 
 ### `await fetch_agent_md(aid: str | None = None) -> dict` — agent.md 下载主 API
 
-下载指定 AID 的 `agent.md`，自动调用 `auth.verify_agent_md` 验签；`aid` 缺省取本地身份；下载结果**固定保存**到 `{aun_path}/AgentMDs/{aid}/agent.md`，并同步更新持久化缓存（`agent_md_cache` 表 / `list.json`）。若目标 aid 是自己则刷新内部 `_local_agent_md_etag` 并计算 `in_sync`。
+下载指定 AID 的 `agent.md`，自动调用 `auth.verify_agent_md` 验签；`aid` 缺省取本地身份；下载结果**固定保存**到 `{aun_path}/AgentMDs/{aid}/agent.md`，并同步更新持久化缓存（`agent_md_cache` 表 / `agentmd.json`）。若目标 aid 是自己则刷新内部 `_local_agent_md_etag` 并计算 `in_sync`。
 
 **API 跨语言对齐：**
 
@@ -681,9 +684,9 @@ SDK 在 publish `message.received` / `group.message_created` 等应用事件时
 
 ---
 
-### `await create_aid(params: dict) -> dict`
+### `await register_aid(params: dict) -> dict`
 
-注册新 AID，本地生成 ECDSA 密钥对并向 Gateway 申请 X.509 证书。
+注册新 AID，本地生成 ECDSA 密钥对并向 Gateway 申请 X.509 证书。该方法严格执行注册语义：若 AID 已在本地存在或已在远程注册，将返回错误而非静默复用。调用前应先通过 `check_aid()` 确认 AID 可注册。
 
 **参数**
 
@@ -701,10 +704,21 @@ SDK 在 publish `message.received` / `group.message_created` 等应用事件时
 
 ```python
 MY_AID = f"alice-{random.randint(1000,9999)}.agentid.pub"
-result = await client.auth.create_aid({"aid": MY_AID})
+result = await client.auth.register_aid({"aid": MY_AID})
 # {"aid": "alice-XXXX.agentid.pub", "cert_pem": "-----BEGIN...", "gateway": "ws://..."}
 ```
 
+**跨语言**
+
+| 语言 | 调用方式 |
+|------|----------|
+| Python | `await client.auth.register_aid({"aid": "..."})` |
+| TypeScript | `await client.auth.registerAid({ aid: '...' })` |
+| Go | `client.Auth.RegisterAID(ctx, map[string]any{"aid": "..."})` |
+| JavaScript（浏览器） | `await client.auth.registerAid({ aid: '...' })` |
+
+> 服务端 RPC 方法名为 `auth.create_aid`，SDK 对外暴露为 `register_aid` / `RegisterAID` / `registerAid` 以明确注册语义。
+
 ---
 
 ### `await check_aid(params: dict) -> dict`
@@ -732,8 +746,8 @@ if result["status"] == "local_ready":
     # 可以直接连接
     pass
 elif result["can_register"]:
-    # AID 可用，创建新身份
-    await client.auth.create_aid({"aid": "alice.agentid.pub"})
+    # AID 可用，注册新身份
+    await client.auth.register_aid({"aid": "alice.agentid.pub"})
 ```
 
 **跨语言**
@@ -773,6 +787,69 @@ auth = await client.auth.authenticate({"aid": MY_AID})
 
 ---
 
+### `load_identity(params: dict | None = None) -> dict`
+
+只读加载本地已注册身份（密钥对 + 证书 + 实例状态）。纯本地操作，无网络请求，无副作用。
+
+**参数**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `aid` | `str` | 否 | 指定 AID；不传则使用当前 AID |
+
+**返回值**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aid` | `str` | AID 标识 |
+| `private_key_pem` | `str` | 私钥 PEM |
+| `public_key_der_b64` | `str` | 公钥 DER Base64 |
+| `cert` | `str` | 证书 PEM（如已签发） |
+| `access_token` | `str` | 缓存的 access_token（如有） |
+
+**异常**：本地无完整身份时抛 `StateError`。
+
+```python
+identity = client.auth.load_identity({"aid": "alice.example.com"})
+```
+
+**OrNone 变体**：`load_identity_or_none(params)` — 不存在时返回 `None` 而非抛异常。
+
+| 语言 | 方法名 |
+|------|--------|
+| Python | `client.auth.load_identity()` / `client.auth.load_identity_or_none()` |
+| TypeScript | `client.auth.loadIdentity()` / `client.auth.loadIdentityOrNull()` |
+| JavaScript | `await client.auth.loadIdentity()` / `await client.auth.loadIdentityOrNull()` |
+| Go | `client.Auth.LoadIdentity(aid)` / `client.Auth.LoadIdentityOrNil(aid)` |
+
+---
+
+### `await fetch_peer_cert(params: dict) -> str`
+
+获取对端 AID 的证书 PEM。优先走本地 `public/certs/` 缓存，未命中时通过 PKI HTTP 端点下载并做完整链验证后落缓存。
+
+**参数**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `aid` | `str` | 是 | 对端 AID |
+| `cert_fingerprint` | `str` | 否 | 指定证书指纹（用于精确匹配特定版本） |
+
+**返回值**：证书 PEM 字符串。
+
+```python
+cert_pem = await client.auth.fetch_peer_cert({"aid": "bob.example.com"})
+```
+
+| 语言 | 方法名 |
+|------|--------|
+| Python | `await client.auth.fetch_peer_cert(params)` |
+| TypeScript | `await client.auth.fetchPeerCert(params)` |
+| JavaScript | `await client.auth.fetchPeerCert(params)` |
+| Go | `client.Auth.FetchPeerCert(ctx, aid, certFingerprint)` |
+
+---
+
 ### `await sign_agent_md(content: str, aid: str | None = None) -> str`
 
 > **⚠️ Deprecated。** 主要场景请改用 `client.publish_agent_md(path)`，它内部已包含读文件 + 签名 + 上传一整套流程。`sign_agent_md` 仅作为离线签名（先签名后异步发布、给非 SDK 渠道发送等）的底层工具继续保留，未来版本将移除。

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

@@ -9,7 +9,8 @@ AUNError
 ├── ConnectionError        # 网络连接失败
 ├── TimeoutError           # 操作超时
 ├── AuthError              # 认证失败（code: 4001/4010/-32001/-32003）
-│   └── CertificateRevokedError  # 证书已吊销（code: -32050）
+│   ├── CertificateRevokedError  # 证书已吊销（code: -32050）
+│   └── IdentityConflictError    # 身份冲突（code: 4090）
 ├── PermissionError        # 权限不足（code: 4030/403/-32004）
 ├── ValidationError        # 参数校验失败（code: 4000/-32600/-32601/-32602）
 ├── NotFoundError          # 资源不存在（code: 4040/404/-32008）
@@ -67,6 +68,7 @@ except AUNError as e:
 | -32042 | 成员承诺验证失败 | `E2EEGroupCommitmentInvalidError` |
 | -32043 | 密钥请求者非群成员 | `E2EEGroupNotMemberError` |
 | -32044 | 群消息解密失败 | `E2EEGroupDecryptFailedError` |
+| 4090 | 身份冲突 | `IdentityConflictError` |
 | -32050 | 证书已吊销 | `CertificateRevokedError` |
 | -32051 | 客户端签名验证失败 | `ClientSignatureError` |
 | -33001 | 群组不存在 | `GroupNotFoundError` |
@@ -136,6 +138,22 @@ await client.call("message.send", {...})
 # 协议层定义的错误语义，当前 Python SDK 的部分路径表现为返回 None、拒绝状态或跳过自动解密，不一定抛出对应异常
 ```
 
+### 身份冲突（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}")
+```
+
+跨语言类名统一为 `IdentityConflictError`（Python / Go / TS / JS）。
+
 ### 连接状态错误
 
 ```python

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

@@ -9,9 +9,9 @@
 ```python
 async def ensure_connected(client: AUNClient, aid: str) -> str:
     try:
-        await client.auth.create_aid({"aid": aid})
+        await client.auth.register_aid({"aid": aid})
     except Exception as e:
-        print(f"创建 AID 失败: {e}")
+        print(f"注册 AID 失败: {e}")
         raise
     auth = await client.auth.authenticate({"aid": aid})
     await client.connect(auth, {"auto_reconnect": True})
@@ -51,9 +51,9 @@ recv_cursor = r.get("latest_seq", 0)
 # 推荐：用应用名作为 aun_path，多个 AID 共存于同一目录
 client = AUNClient({"aun_path": "~/.aun/myapp"})
 
-# 创建不同的 AID，各自数据自动隔离
-await client.auth.create_aid({"aid": "alice.agentid.pub"})
-await client.auth.create_aid({"aid": "bob.agentid.pub"})
+# 注册不同的 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/ 下
 ```
 
@@ -87,3 +87,18 @@ async def main():
 - RPC 方法手册：`../src/aun_core/docs/skill/rpc-manual/`
 - 可运行示例：`../src/aun_core/docs/skill/examples/`
 - GitHub：https://github.com/ModelUnion/aun-sdk-core
+
+---
+
+## 7. Flow Control（v0.3.4+）
+
+SDK 内部自动管理 RPC 并发，应用层无需配置：
+
+| 机制 | 说明 |
+|------|------|
+| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
+| 后台 RPC 限制 | 后台任务（prekey 上传、token 刷新等）额外限制为 8 个 |
+| Pull Gate | 同一 namespace/group 的 pull 操作自动序列化，防止并发 pull 导致重复消息 |
+| 队列超时 | 排队等待超过 timeout 时抛 `TimeoutError("rpc queue timeout before send: {method}")` |
+
+这些限制在高并发场景下保护服务端不被单客户端打满，同时避免 pull 竞态导致的消息乱序。应用层只需正常调用 `client.call()`，SDK 自动排队和限流。