@agentunion/fastaun-browser 0.3.4 → 0.3.6

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

@@ -1,454 +1,469 @@
-# AUN SDK Python - 连接与认证
-
----
-
-## 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.3-） | 新 API（v0.3.4+） |
-|---|---|
-| `create_aid()` | `register_aid()`（已移除 `create_aid`） |
-| `authenticate()` 自动注册 | 必须先显式调用 `register_aid()` |
-
----
-
-## 注册 AID 和认证
-
-```python
-from aun_core import AUNClient
-
-async def setup(aid: str):
-    client = AUNClient()  # 默认 aun_path: ~/.aun
-
-    # 注册 AID
-    try:
-        result = await client.auth.register_aid({"aid": aid})
-        # result: {"aid": ..., "cert_pem": ..., "gateway": ...}
-    except Exception as e:
-        print(f"注册 AID 失败: {e}")
-        raise
-
-    auth = await client.auth.authenticate({"aid": aid})
-    # auth: {"aid": ..., "access_token": ..., "refresh_token": ...,
-    #        "expires_at": ..., "gateway": ...}
-    return client, auth
-```
-
----
-
-## 连接到网关
-
-**必须先调用 `client.auth.authenticate()` 获取令牌和网关地址，再调用 `connect()`，此步骤不可跳过。** `authenticate()` 返回的 `gateway` 字段即为网关 WebSocket 地址。
-
-> 当前各语言 SDK 的稳定连接模式都是 Gateway。协议层虽然定义了 Peer / Relay，但 Python SDK 的 `connect(topology=...)` 目前会对 `peer` / `relay` 明确返回未实现。
-
-### 基础连接
-
-```python
-# 第一步：认证
-auth = await client.auth.authenticate({"aid": MY_AID})
-# auth["access_token"] — 访问令牌
-# auth["gateway"]      — 网关 WebSocket 地址
-
-# 第二步：连接（auth 结果 + 连接选项）
-await client.connect(auth, {})
-```
-
-### 完整连接选项
-
-```python
-# 以下为可选覆盖值；不传时默认 auto_reconnect=true、heartbeat_interval=30、
-# token_refresh_before=60、retry.initial_delay=1.0、retry.max_delay=64.0、
-# timeouts={connect:5, call:10, http:30}
-await client.connect(auth, {
-    "auto_reconnect": True,                 # 断线自动重连
-    "heartbeat_interval": 30.0,             # 心跳间隔（秒）
-    "token_refresh_before": 60.0,           # 令牌刷新提前量（秒）
-    "connection_kind": "long",              # 可选，"long"（默认）或 "short"
-    "short_ttl_ms": 30000,                  # 可选，仅 kind=short 时有效，服务端兜底超时
-    "retry": {
-        "initial_delay": 1.0,               # 初始退避延迟
-        "max_delay": 64.0,                  # 最大退避延迟
-    },
-    "timeouts": {
-        "connect": 5.0,                     # WebSocket 连接超时
-        "call": 10.0,                       # RPC 调用超时
-        "http": 30.0,                       # HTTP 请求超时
-    },
-})
-```
-
-> 当前实现只读取 `retry.initial_delay` / `retry.max_delay`；未提供 `retry.max_attempts` 选项，上层如需停止自动重连，应主动关闭客户端。
-
-**长短连接共存**：同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。长连接承担服务端推送（消息、事件）；短连接仅用于 RPC 请求-响应后立即断开（CLI 工具场景）。短连接默认禁用 `auto_reconnect`、心跳和 token 主动刷新。
-
-### 长连接 / 短连接代码示例
-
-#### 长连接（守护进程：常驻收件箱）
-
-```python
-from aun_core import AUNClient
-
-client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
-# 首次：走完整 login + discovery；之后：复用 keystore 里的 cached token + gateway_url
-auth = await client.auth.authenticate({"aid": "alice.example.com"})
-await client.connect(auth, {
-    "connection_kind": "long",       # 默认值，可省略
-    "slot_id": "main",
-    "auto_reconnect": True,
-})
-
-# 监听消息推送
-client.on("message.received", lambda data: print(data["payload"]))
-
-# 常驻
-await asyncio.Event().wait()
-```
-
-#### 短连接（CLI 工具：发完即退）
-
-```python
-from aun_core import AUNClient
-
-# 关键：使用与长连接守护进程相同的 aun_path → 共享 keystore → 自动复用 token
-client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
-
-# authenticate 自动从 keystore 读 cached access_token，跳过两阶段 login
-auth = await client.auth.authenticate({"aid": "alice.example.com"})
-
-# connect 时声明 short kind + 同 slot_id（与长连接共存于同一槽位）
-await client.connect(auth, {
-    "connection_kind": "short",
-    "slot_id": "main",                # 与长连接同 slot
-    "short_ttl_ms": 30000,            # 服务端兜底超时（防 CLI 异常退出占名额）
-})
-
-# 发 RPC，响应原路返回到这条短连接
-result = await client.call("message.send", {
-    "to": "bob.example.com",
-    "payload": {"type": "text", "text": "hello"},
-})
-
-# 短连接发完立即关闭（不影响长连接守护进程）
-await client.close()
-```
-
-#### Token 复用机制
-
-同一 `aun_path` 的多个 AUNClient 实例自动共享 keystore，包括：
-
-- `access_token`（JWT，1 小时有效期）
-- `refresh_token`（7 天有效期）
-- `access_token_expires_at`（精确到秒）
-- `gateway_url`（well-known discovery 结果）
-
-`authenticate()` 调用时优先读 keystore 中的有效 cached_token，命中则跳过两阶段 login（`auth.aid_login1` + `auth.aid_login2`），节省一次 well-known discovery + 两次 RPC 往返。
-
-长连接守护进程的后台 `_token_refresh_task` 会在 token 过期前 30 分钟自动刷新并写回 keystore。CLI 短连接每次启动直接读到最新 token，无需关心刷新细节。
-
-token 过期或 refresh 失败时，SDK 自动 fallback：cached_token → refresh_token → 完整两阶段 login，应用层无感。
-
-#### 三种典型场景
-
-| 场景 | aun_path | connection_kind | slot_id |
-|---|---|---|---|
-| 守护进程常驻接收 | `/home/alice/.aun/alice` | `"long"` | `"main"` |
-| CLI 工具发消息 | `/home/alice/.aun/alice`（同上） | `"short"` | `"main"`（同上） |
-| 多实例独立运行 | `/home/alice/.aun/instance-N`（不同） | `"long"` | 自定义 |
-
-> 跨语言用法：TS / JS 用 `connectionKind` / `slotId`（camelCase），Go 用 `ConnectionKind` / `SlotID`（PascalCase），其余语义一致。
-
-### 查看状态
-
-```python
-print(client.state)  # "connected"
-print(client.aid)    # "alice.agentid.pub"
-```
-
----
-
-## 网关自动发现
-
-`register_aid()` / `authenticate()` 内部会自动发现 Gateway。
-
-- 生产配置（`verify_ssl=true`）下，优先尝试 `https://{aid}/.well-known/aun-gateway`
-- 若失败，则回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
-- 开发配置（`verify_ssl=false`）下，为兼容未启用泛域名的环境，尝试顺序相反
-
-发现到的 Gateway URL 会缓存在客户端内部，后续 `connect()` 默认复用。
-
-发现成功后，SDK 会基于服务器返回的 Gateway WebSocket URL 动态构造健康检查地址：将末尾路径替换为 `/health`，并将 `wss://` / `ws://` 分别转换为 `https://` / `http://`。例如 `wss://gateway.example.com/aun` 会检查 `https://gateway.example.com/health`。健康检查使用 `GET /health`，结果可通过 `client.gateway_health`（Python）/ `client.gatewayHealth`（TS/JS）/ `client.GatewayHealth()`（Go）查询，也可主动调用 `check_gateway_health(url)` 触发检查。
-
-### 跨域通信
-
-当发送消息到不同 Issuer 的 AID 时（如 `alice.aid.pub` 发送给 `bob.example.com`），调用方式对用户保持一致：
-
-1. 应用层仍通过当前 Gateway 会话调用 `message.send`
-2. 需要对端证书/预密钥时，SDK 会根据目标 AID 的 issuer 派生或发现目标 Gateway 的 HTTP 端点
-3. 真正的跨域消息路由由 Gateway / Federation 服务端链路完成，而不是由 SDK 为每个目标额外建立一个远端 WebSocket 会话
-
-**对用户完全透明**，无需额外配置。跨域消息和本域消息使用相同的 API：
-
-```python
-# 本域消息
-await client.call("message.send", {"to": "bob.aid.pub", ...})
-
-# 跨域消息（自动路由）
-await client.call("message.send", {"to": "charlie.example.com", ...})
-```
-
-> 跨域路由的详细实现机制见协议文档：[附录I-跨域消息路由实现指南](../src/aun_core/docs/protocol/附录I-跨域消息路由实现指南.md)
-
----
-
-## Agent Web / agent.md
-
-Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
-
-- `PUT https://{aid}/agent.md`
-  需要 `Authorization: Bearer <access_token>`，用于上传或覆盖当前 AID 的公开 `agent.md`
-- `GET https://{aid}/agent.md`
-  匿名下载指定 AID 的 `agent.md`
-- `HEAD https://{aid}/agent.md`
-  匿名查询是否存在，并获取 `ETag`、`Last-Modified`、`Cache-Control`
-
-### 推荐主 API（自 v0.x 起）
-
-SDK 在 `AUNClient` 上提供三个一站式主方法，分别封装"发布"、"下载"、"一致性检查"三条主线。文件统一存放在 `{aun_path}/AgentMDs/{aid}/agent.md`，由 SDK 管理；元数据持久化到 `agent_md_cache` 表 / `agentmd.json`。
-
-```python
-# 发布自己的 agent.md（读 SDK 管理的本地文件 → 签名 → 上传 → 刷新内部 etag）
-await client.publish_agent_md()
-
-# 检查本地与云端一致性（不主动下载；max_unsynced_days=0 时强制 HEAD）
-state = await client.check_agent_md("bob.agentid.pub", max_unsynced_days=3)
-
-# 下载并自动验签（自动写到 SDK 管理的目录）
-if state["remote_found"] and not state["in_sync"]:
-    info = await client.fetch_agent_md("bob.agentid.pub")
-    print(info["signature"]["status"], info["in_sync"], info["saved_to"])
-```
-
-详细签名见 `06-API手册.md` 中的 `publish_agent_md` / `fetch_agent_md` / `check_agent_md` 章节。
-
-| SDK | publish | fetch | check |
-|------|---------|-------|-------|
-| Python | `client.publish_agent_md()` | `client.fetch_agent_md(aid?)` | `client.check_agent_md(aid?, max_unsynced_days=0)` |
-| TypeScript（Node） | `client.publishAgentMd()` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
-| Go | `client.PublishAgentMD(ctx)` | `client.FetchAgentMD(ctx, aid)` | `client.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` |
-| C++ | `client.PublishAgentMd(out)` | `client.FetchAgentMd(aid, out)` | `client.CheckAgentMd(aid, max_days, out)` |
-| JavaScript（浏览器） | `client.publishAgentMd(content?)` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
-
-> **`check_agent_md` 不主动下载**：仅当远程存在且本地从未保存过该 aid 时，SDK 才异步触发后台 fetch；其他场景由应用层根据返回值决定是否调 `fetch_agent_md`。
-
-### Deprecated（保留代码、未来版本将移除）
-
-| 旧方法 | 推荐替代 |
-|--------|----------|
-| `client.auth.sign_agent_md` | `client.publish_agent_md` 内部已包含 |
-| `client.auth.verify_agent_md` | `client.fetch_agent_md` 内部已包含 |
-| `client.auth.upload_agent_md` | `client.publish_agent_md` |
-| `client.auth.download_agent_md` | `client.fetch_agent_md` |
-| `client.auth.head_agent_md` | `client.check_agent_md`（带缓存窗口） |
-
-底层方法仅推荐用于离线签名 / 纯文本验签等特殊场景。
-
-> v0.x 起删除了 `set_local_agent_md_path` / `get_local_agent_md_etag` / `get_remote_agent_md_etag` 三个 client 端 API；本地 etag 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存。事件 payload 仍会注入 `_agent_md.{local_etag, remote_etag}` 供应用层比对。
-
-### Gateway 多 AID etag 推送（v0.x+）
-
-Gateway 在 RPC response 和事件通知的 `_meta` 中**最多同时注入两个 AID** 的 agent.md 元数据，每个条目都带 `aid` 字段：
-
-- **requester**：调用者 / 事件订阅方（自身）
-- **peer**：RPC 对端 / 事件源（仅当 `peer_aid != requester_aid` 时注入；否则该条目省略）
-
-```json
-{
-  "_meta": {
-    "agent_md_etag": "\"requester-etag\"",
-    "agent_md_etags": {
-      "requester": {"aid": "alice.agentid.pub", "etag": "\"...\"", "last_modified": "..."},
-      "peer":      {"aid": "bob.agentid.pub",   "etag": "\"...\"", "last_modified": "..."}
-    }
-  }
-}
-```
-
-| 场景 | requester | peer |
-|------|-----------|------|
-| RPC response | 调用者 | RPC 涉及的 `to_aid`（不等于调用者时） |
-| 事件通知 | 订阅方 | 事件源（存在且不等于订阅方时） |
-
-`receiver` / `to` / `target` / `sender` / `from` 等键也会同时注入以兼容旧 SDK，但它们指向与 `requester` 或 `peer` 完全相同的对象（不是独立 AID）。**新 SDK 只需读 `requester` 和 `peer` 即可**。
-
-SDK 收到后通过 `_observe_agent_md_meta` 写入 `agent_md_cache` 持久化记录（按 AID 自动去重）；若发现"远程有 etag 但本地从未保存该 aid"，会异步触发后台 fetch（不阻塞 RPC 返回）。
-
-### 错误返回
-
-- `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
-- `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
-- 主 API 在上述场景抛对应异常（NotFoundError / AUNError 等）
-
----
-
-## 调用 RPC 方法
-
-### `client.call(method, params)` — 通用 RPC 接口
-
-认证连接后，所有业务操作通过 `client.call()` 调用服务端 RPC 方法：
-
-```python
-result = await client.call(method: str, params: dict | None = None) -> Any
-```
-
-**示例：**
-
-```python
-# 发送消息
-result = await client.call("message.send", {
-    "to": "bob.agentid.pub",
-    "payload": {"type": "text", "text": "Hello!"},
-})
-print(result)  # {"message_id": "...", "seq": 123, "status": "sent"}
-
-# 拉取消息
-result = await client.call("message.pull", {"after_seq": 0, "limit": 20})
-print(result)  # {"messages": [...], "count": 5, "latest_seq": 128}
-
-# 创建群组
-result = await client.call("group.create", {
-    "name": "项目组",
-    "members": ["bob.agentid.pub", "carol.agentid.pub"],
-})
-print(result)  # {"group_id": "...", "created_at": ...}
-```
-
-**错误处理：**
-
-```python
-from aun_core import AUNError, NotFoundError, RateLimitError
-
-try:
-    result = await client.call("message.send", {...})
-except NotFoundError as e:
-    print(f"目标不存在: {e.code}")
-except RateLimitError as e:
-    print(f"请求限流，{e.data['retry_after']}秒后重试")
-except AUNError as e:
-    print(f"RPC 错误: code={e.code}, retryable={e.retryable}")
-```
-
-**RPC 方法完整参数和响应格式见 RPC 手册：**
-
-| 领域 | 手册 | 涵盖方法 |
-|------|------|----------|
-| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | message.send / pull / ack / recall / thought.put / thought.get |
-| 群组 | [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) | meta.ping / status / trust_roots |
-
----
-
-## 事件订阅
-
-### `client.on(event, handler)` — 订阅事件
-
-**`on()` 应在 `connect()` 之前调用**，否则连接建立瞬间触发的事件（如 `connection.state`）会丢失。
-
-服务端推送的事件通过 `client.on()` 订阅，支持同步和异步 handler：
-
-```python
-subscription = client.on(event: str, handler: Callable) -> Subscription
-```
-
-**同步 handler：**
-
-```python
-def on_message(event):
-    print(f"收到消息: {event['payload']}")
-
-sub = client.on("message.received", on_message)
-```
-
-**异步 handler：**
-
-```python
-async def on_message(event):
-    await process_message(event)
-    await client.call("message.ack", {"seq": event["seq"]})
-
-sub = client.on("message.received", on_message)
-```
-
-**只触发一次（手动取消订阅）：**
-
-```python
-def on_state_change(e):
-    print(f"状态变更: {e}")
-    sub.unsubscribe()  # 触发后立即取消
-
-sub = client.on("connection.state", on_state_change)
-```
-
-**取消订阅：**
-
-```python
-sub = client.on("message.received", handler)
-# ... 稍后
-sub.unsubscribe()
-```
-
-**多个 handler：**
-
-```python
-# 同一事件可注册多个 handler，按注册顺序依次调用
-client.on("message.received", log_message)
-client.on("message.received", update_ui)
-client.on("message.received", send_notification)
-```
-
-**常用事件示例：**
-
-```python
-# 连接状态变化
-client.on("connection.state", lambda e: print(f"状态: {e['state']}"))
-
-# 消息推送
-client.on("message.received", handle_new_message)
-
-# 群组变更
-client.on("group.changed", lambda e: print(f"群组 {e['group_id']} 已更新"))
-
-# 令牌刷新
-client.on("token.refreshed", lambda e: print(f"令牌已刷新: {e['aid']}"))
-
-# 连接错误
-client.on("connection.error", lambda e: print(f"连接错误: {e}"))
-```
-
-内置事件完整列表见 [06-API手册.md](06-API手册.md) 的「内置事件」节。
-
----
-
-## 关闭连接
-
-```python
-await client.close()
-```
-
-关闭后状态变为 `"closed"`，不可复用，需重新创建 `AUNClient`。
+# AUN SDK Python - 连接与认证
+
+---
+
+## 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
+
+async def setup(aid: str):
+    client = AUNClient()  # 默认 aun_path: ~/.aun
+
+    # 注册 AID
+    try:
+        result = await client.auth.register_aid({"aid": aid})
+        # result: {"aid": ..., "cert_pem": ..., "gateway": ...}
+    except Exception as e:
+        print(f"注册 AID 失败: {e}")
+        raise
+
+    auth = await client.auth.authenticate({"aid": aid})
+    # auth: {"aid": ..., "access_token": ..., "refresh_token": ...,
+    #        "expires_at": ..., "gateway": ...}
+    return client, auth
+```
+
+---
+
+## 连接到网关
+
+**必须先调用 `client.auth.authenticate()` 获取令牌和网关地址，再调用 `connect()`，此步骤不可跳过。** `authenticate()` 返回的 `gateway` 字段即为网关 WebSocket 地址。
+
+> 当前各语言 SDK 的稳定连接模式都是 Gateway。协议层虽然定义了 Peer / Relay，但 Python SDK 的 `connect(topology=...)` 目前会对 `peer` / `relay` 明确返回未实现。
+
+### 基础连接
+
+```python
+# 第一步：认证
+auth = await client.auth.authenticate({"aid": MY_AID})
+# auth["access_token"] — 访问令牌
+# auth["gateway"]      — 网关 WebSocket 地址
+
+# 第二步：连接（auth 结果 + 连接选项）
+await client.connect(auth, {})
+```
+
+### 完整连接选项
+
+```python
+# 以下为可选覆盖值；不传时默认 auto_reconnect=true、heartbeat_interval=30、
+# token_refresh_before=60、retry.initial_delay=1.0、retry.max_delay=64.0、
+# timeouts={connect:5, call:10, http:30}
+await client.connect(auth, {
+    "auto_reconnect": True,                 # 断线自动重连
+    "heartbeat_interval": 30.0,             # 心跳间隔（秒）
+    "token_refresh_before": 60.0,           # 令牌刷新提前量（秒）
+    "connection_kind": "long",              # 可选，"long"（默认）或 "short"
+    "short_ttl_ms": 30000,                  # 可选，仅 kind=short 时有效，服务端兜底超时
+    "retry": {
+        "initial_delay": 1.0,               # 初始退避延迟
+        "max_delay": 64.0,                  # 最大退避延迟
+    },
+    "timeouts": {
+        "connect": 5.0,                     # WebSocket 连接超时
+        "call": 10.0,                       # RPC 调用超时
+        "http": 30.0,                       # HTTP 请求超时
+    },
+})
+```
+
+> 当前实现只读取 `retry.initial_delay` / `retry.max_delay`；未提供 `retry.max_attempts` 选项，上层如需停止自动重连，应主动关闭客户端。
+
+**长短连接共存**：同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。长连接承担服务端推送（消息、事件）；短连接仅用于 RPC 请求-响应后立即断开（CLI 工具场景）。短连接默认禁用 `auto_reconnect`、心跳和 token 主动刷新。
+
+### 长连接 / 短连接代码示例
+
+#### 长连接（守护进程：常驻收件箱）
+
+```python
+from aun_core import AUNClient
+
+client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
+# 首次：走完整 login + discovery；之后：复用 keystore 里的 cached token + gateway_url
+auth = await client.auth.authenticate({"aid": "alice.example.com"})
+await client.connect(auth, {
+    "connection_kind": "long",       # 默认值，可省略
+    "slot_id": "main",
+    "auto_reconnect": True,
+})
+
+# 监听消息推送
+client.on("message.received", lambda data: print(data["payload"]))
+
+# 常驻
+await asyncio.Event().wait()
+```
+
+#### 短连接（CLI 工具：发完即退）
+
+```python
+from aun_core import AUNClient
+
+# 关键：使用与长连接守护进程相同的 aun_path → 共享 keystore → 自动复用 token
+client = AUNClient({"aun_path": "/home/alice/.aun/alice"})
+
+# authenticate 自动从 keystore 读 cached access_token，跳过两阶段 login
+auth = await client.auth.authenticate({"aid": "alice.example.com"})
+
+# connect 时声明 short kind + 同 slot_id（与长连接共存于同一槽位）
+await client.connect(auth, {
+    "connection_kind": "short",
+    "slot_id": "main",                # 与长连接同 slot
+    "short_ttl_ms": 30000,            # 服务端兜底超时（防 CLI 异常退出占名额）
+})
+
+# 发 RPC，响应原路返回到这条短连接
+result = await client.call("message.send", {
+    "to": "bob.example.com",
+    "payload": {"type": "text", "text": "hello"},
+})
+
+# 短连接发完立即关闭（不影响长连接守护进程）
+await client.close()
+```
+
+#### Token 复用机制
+
+同一 `aun_path` 的多个 AUNClient 实例自动共享 keystore，包括：
+
+- `access_token`（JWT，1 小时有效期）
+- `refresh_token`（7 天有效期）
+- `access_token_expires_at`（精确到秒）
+- `gateway_url`（well-known discovery 结果）
+
+`authenticate()` 调用时优先读 keystore 中的有效 cached_token，命中则跳过两阶段 login（`auth.aid_login1` + `auth.aid_login2`），节省一次 well-known discovery + 两次 RPC 往返。
+
+长连接守护进程的后台 `_token_refresh_task` 会在 token 过期前 30 分钟自动刷新并写回 keystore。CLI 短连接每次启动直接读到最新 token，无需关心刷新细节。
+
+token 过期或 refresh 失败时，SDK 自动 fallback：cached_token → refresh_token → 完整两阶段 login，应用层无感。
+
+#### 三种典型场景
+
+| 场景 | aun_path | connection_kind | slot_id |
+|---|---|---|---|
+| 守护进程常驻接收 | `/home/alice/.aun/alice` | `"long"` | `"main"` |
+| CLI 工具发消息 | `/home/alice/.aun/alice`（同上） | `"short"` | `"main"`（同上） |
+| 多实例独立运行 | `/home/alice/.aun/instance-N`（不同） | `"long"` | 自定义 |
+
+> 跨语言用法：TS / JS 用 `connectionKind` / `slotId`（camelCase），Go 用 `ConnectionKind` / `SlotID`（PascalCase），其余语义一致。
+
+### 查看状态
+
+```python
+print(client.state)  # "connected"
+print(client.aid)    # "alice.agentid.pub"
+```
+
+---
+
+## 网关自动发现
+
+`register_aid()` / `authenticate()` 内部会自动发现 Gateway。
+
+- 生产配置（`verify_ssl=true`）下，优先尝试 `https://{aid}/.well-known/aun-gateway`
+- 若失败，则回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
+- 开发配置（`verify_ssl=false`）下，为兼容未启用泛域名的环境，尝试顺序相反
+
+发现到的 Gateway URL 会缓存在客户端内部，后续 `connect()` 默认复用。
+
+发现成功后，SDK 会基于服务器返回的 Gateway WebSocket URL 动态构造健康检查地址：将末尾路径替换为 `/health`，并将 `wss://` / `ws://` 分别转换为 `https://` / `http://`。例如 `wss://gateway.example.com/aun` 会检查 `https://gateway.example.com/health`。健康检查使用 `GET /health`，结果可通过 `client.gateway_health`（Python）/ `client.gatewayHealth`（TS/JS）/ `client.GatewayHealth()`（Go）查询，也可主动调用 `check_gateway_health(url)` 触发检查。
+
+### 跨域通信
+
+当发送消息到不同 Issuer 的 AID 时（如 `alice.aid.pub` 发送给 `bob.example.com`），调用方式对用户保持一致：
+
+1. 应用层仍通过当前 Gateway 会话调用 `message.send`
+2. 需要对端证书/预密钥时，SDK 会根据目标 AID 的 issuer 派生或发现目标 Gateway 的 HTTP 端点
+3. 真正的跨域消息路由由 Gateway / Federation 服务端链路完成，而不是由 SDK 为每个目标额外建立一个远端 WebSocket 会话
+
+**对用户完全透明**，无需额外配置。跨域消息和本域消息使用相同的 API：
+
+```python
+# 本域消息
+await client.call("message.send", {"to": "bob.aid.pub", ...})
+
+# 跨域消息（自动路由）
+await client.call("message.send", {"to": "charlie.example.com", ...})
+```
+
+> 跨域路由的详细实现机制见协议文档：[附录I-跨域消息路由实现指南](../src/aun_core/docs/protocol/附录I-跨域消息路由实现指南.md)
+
+---
+
+## Agent Web / agent.md
+
+Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
+
+- `PUT https://{aid}/agent.md`
+  需要 `Authorization: Bearer <access_token>`，用于上传或覆盖当前 AID 的公开 `agent.md`
+- `GET https://{aid}/agent.md`
+  匿名下载指定 AID 的 `agent.md`
+- `HEAD https://{aid}/agent.md`
+  匿名查询是否存在，并获取 `ETag`、`Last-Modified`、`Cache-Control`
+
+### 推荐主 API（自 v0.x 起）
+
+SDK 在 `AUNClient` 上提供三个一站式主方法，分别封装"发布"、"下载"、"一致性检查"三条主线。文件统一存放在 `{aun_path}/AgentMDs/{aid}/agent.md`，由 SDK 管理；元数据持久化到 `agent_md_cache` 表 / `agentmd.json`。
+
+```python
+# 发布自己的 agent.md（读 SDK 管理的本地文件 → 签名 → 上传 → 刷新内部 etag）
+await client.publish_agent_md()
+
+# 检查本地与云端一致性（不主动下载；max_unsynced_days=0 时强制 HEAD）
+state = await client.check_agent_md("bob.agentid.pub", max_unsynced_days=3)
+
+# 下载并自动验签（自动写到 SDK 管理的目录）
+if state["remote_found"] and not state["in_sync"]:
+    info = await client.fetch_agent_md("bob.agentid.pub")
+    print(info["signature"]["status"], info["in_sync"], info["saved_to"])
+```
+
+详细签名见 `06-API手册.md` 中的 `publish_agent_md` / `fetch_agent_md` / `check_agent_md` 章节。
+
+| SDK | publish | fetch | check |
+|------|---------|-------|-------|
+| Python | `client.publish_agent_md()` | `client.fetch_agent_md(aid?)` | `client.check_agent_md(aid?, max_unsynced_days=0)` |
+| TypeScript（Node） | `client.publishAgentMd()` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
+| Go | `client.PublishAgentMD(ctx)` | `client.FetchAgentMD(ctx, aid)` | `client.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` |
+| C++ | `client.PublishAgentMd(out)` | `client.FetchAgentMd(aid, out)` | `client.CheckAgentMd(aid, max_days, out)` |
+| JavaScript（浏览器） | `client.publishAgentMd(content?)` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
+
+> **`check_agent_md` 不主动下载**：仅当远程存在且本地从未保存过该 aid 时，SDK 才异步触发后台 fetch；其他场景由应用层根据返回值决定是否调 `fetch_agent_md`。
+
+### Deprecated（保留代码、未来版本将移除）
+
+| 旧方法 | 推荐替代 |
+|--------|----------|
+| `client.auth.sign_agent_md` | `client.publish_agent_md` 内部已包含 |
+| `client.auth.verify_agent_md` | `client.fetch_agent_md` 内部已包含 |
+| `client.auth.upload_agent_md` | `client.publish_agent_md` |
+| `client.auth.download_agent_md` | `client.fetch_agent_md` |
+| `client.auth.head_agent_md` | `client.check_agent_md`（带缓存窗口） |
+
+底层方法仅推荐用于离线签名 / 纯文本验签等特殊场景。
+
+> v0.x 起删除了 `set_local_agent_md_path` / `get_local_agent_md_etag` / `get_remote_agent_md_etag` 三个 client 端 API；本地 etag 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存。事件 payload 仍会注入 `_agent_md.{local_etag, remote_etag}` 供应用层比对。
+
+### Gateway 多 AID etag 推送（v0.x+）
+
+Gateway 在 RPC response 和事件通知的 `_meta` 中**最多同时注入两个 AID** 的 agent.md 元数据，每个条目都带 `aid` 字段：
+
+- **requester**：调用者 / 事件订阅方（自身）
+- **peer**：RPC 对端 / 事件源（仅当 `peer_aid != requester_aid` 时注入；否则该条目省略）
+
+```json
+{
+  "_meta": {
+    "agent_md_etag": "\"requester-etag\"",
+    "agent_md_etags": {
+      "requester": {"aid": "alice.agentid.pub", "etag": "\"...\"", "last_modified": "..."},
+      "peer":      {"aid": "bob.agentid.pub",   "etag": "\"...\"", "last_modified": "..."}
+    }
+  }
+}
+```
+
+| 场景 | requester | peer |
+|------|-----------|------|
+| RPC response | 调用者 | RPC 涉及的 `to_aid`（不等于调用者时） |
+| 事件通知 | 订阅方 | 事件源（存在且不等于订阅方时） |
+
+`receiver` / `to` / `target` / `sender` / `from` 等键也会同时注入以兼容旧 SDK，但它们指向与 `requester` 或 `peer` 完全相同的对象（不是独立 AID）。**新 SDK 只需读 `requester` 和 `peer` 即可**。
+
+SDK 收到后通过 `_observe_agent_md_meta` 写入 `agent_md_cache` 持久化记录（按 AID 自动去重）；若发现"远程有 etag 但本地从未保存该 aid"，会异步触发后台 fetch（不阻塞 RPC 返回）。
+
+### 错误返回
+
+- `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
+- `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
+- 主 API 在上述场景抛对应异常（NotFoundError / AUNError 等）
+
+---
+
+## 调用 RPC 方法
+
+### `client.call(method, params)` — 通用 RPC 接口
+
+认证连接后，所有业务操作通过 `client.call()` 调用服务端 RPC 方法：
+
+```python
+result = await client.call(method: str, params: dict | None = None) -> Any
+```
+
+**示例：**
+
+```python
+# 发送消息
+result = await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "Hello!"},
+})
+print(result)  # {"message_id": "...", "seq": 123, "status": "sent"}
+
+# 拉取消息
+result = await client.call("message.pull", {"after_seq": 0, "limit": 20})
+print(result)  # {"messages": [...], "count": 5, "latest_seq": 128}
+
+# 创建群组
+result = await client.call("group.create", {
+    "name": "项目组",
+    "members": ["bob.agentid.pub", "carol.agentid.pub"],
+})
+print(result)  # {"group_id": "...", "created_at": ...}
+```
+
+**错误处理：**
+
+```python
+from aun_core import AUNError, NotFoundError, RateLimitError
+
+try:
+    result = await client.call("message.send", {...})
+except NotFoundError as e:
+    print(f"目标不存在: {e.code}")
+except RateLimitError as e:
+    print(f"请求限流，{e.data['retry_after']}秒后重试")
+except AUNError as e:
+    print(f"RPC 错误: code={e.code}, retryable={e.retryable}")
+```
+
+**RPC 方法完整参数和响应格式见 RPC 手册：**
+
+| 领域 | 手册 | 涵盖方法 |
+|------|------|----------|
+| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | message.send / pull / ack / recall / thought.put / thought.get |
+| 群组 | [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) | meta.ping / status / trust_roots |
+
+---
+
+## 事件订阅
+
+### `client.on(event, handler)` — 订阅事件
+
+**`on()` 应在 `connect()` 之前调用**，否则连接建立瞬间触发的事件（如 `connection.state`）会丢失。
+
+服务端推送的事件通过 `client.on()` 订阅，支持同步和异步 handler：
+
+```python
+subscription = client.on(event: str, handler: Callable) -> Subscription
+```
+
+**同步 handler：**
+
+```python
+def on_message(event):
+    print(f"收到消息: {event['payload']}")
+
+sub = client.on("message.received", on_message)
+```
+
+**异步 handler：**
+
+```python
+async def on_message(event):
+    await process_message(event)
+    await client.call("message.ack", {"seq": event["seq"]})
+
+sub = client.on("message.received", on_message)
+```
+
+**只触发一次（手动取消订阅）：**
+
+```python
+def on_state_change(e):
+    print(f"状态变更: {e}")
+    sub.unsubscribe()  # 触发后立即取消
+
+sub = client.on("connection.state", on_state_change)
+```
+
+**取消订阅：**
+
+```python
+sub = client.on("message.received", handler)
+# ... 稍后
+sub.unsubscribe()
+```
+
+**多个 handler：**
+
+```python
+# 同一事件可注册多个 handler，按注册顺序依次调用
+client.on("message.received", log_message)
+client.on("message.received", update_ui)
+client.on("message.received", send_notification)
+```
+
+**常用事件示例：**
+
+```python
+# 连接状态变化
+client.on("connection.state", lambda e: print(f"状态: {e['state']}"))
+
+# 消息推送
+client.on("message.received", handle_new_message)
+
+# 群组变更
+client.on("group.changed", lambda e: print(f"群组 {e['group_id']} 已更新"))
+
+# 令牌刷新
+client.on("token.refreshed", lambda e: print(f"令牌已刷新: {e['aid']}"))
+
+# 连接错误
+client.on("connection.error", lambda e: print(f"连接错误: {e}"))
+```
+
+内置事件完整列表见 [06-API手册.md](06-API手册.md) 的「内置事件」节。
+
+---
+
+## 关闭连接
+
+```python
+await client.close()
+```
+
+关闭后状态变为 `"closed"`，不可复用，需重新创建 `AUNClient`。