@agentunion/fastaun-browser 0.3.6 → 0.4.0

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

@@ -1,469 +1,242 @@
-# AUN SDK Python - 连接与认证
+# AUN SDK - 连接与认证
 
 ---
 
-## v0.3.4 行为变更
+## 当前公开流程
 
-### 注册与认证分离
+重构后，注册、身份加载、会话连接分离：
 
-v0.3.4 起，`authenticate()` **不再隐式注册**。如果本地无完整身份（缺 keypair 或 cert），`authenticate()` 直接抛 `StateError`。
+```python
+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)
 
-```python
-await client.auth.register_aid({"aid": aid})   # 1. 注册（生成密钥对 + 获取证书）
-auth = await client.auth.authenticate({"aid": aid})  # 2. 认证（获取 token）
-await client.connect(auth, {})                 # 3. 连接
+me = loaded["data"]["aid"]
+client = AUNClient(me, debug=True)
+await client.connect({"slot_id": "main", "auto_reconnect": True})
 ```
 
-**半成品恢复**：如果本地有 keypair 但无 cert（上次注册中断），`register_aid()` 会自动向服务端查询并恢复证书，无需手动清理。
+关键约束：
 
-### 身份查询 API
+- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
+- `AIDStore.load(aid)` 返回 AID 值对象；AID 对象加载后不可变。
+- `AUNClient` 只接收 AID 对象，不接收字符串 AID 或配置字典里的 `aid` 字段。
+- `connect(options)` 内部会按需认证、建立 WebSocket、初始化 E2EE 和后台任务。
 
-v0.3.4 新增两个只读 API，用于检查本地身份状态（无网络请求、无副作用）：
+---
 
-```python
-# 加载身份（不存在时抛 StateError）
-identity = client.auth.load_identity({"aid": aid})
+## AIDStore
 
-# 加载身份（不存在时返回 None）
-identity = client.auth.load_identity_or_none({"aid": aid})
+### 构造
 
-# 获取对端证书 PEM（本地缓存优先，未命中走 PKI）
-cert_pem = await client.auth.fetch_peer_cert({"aid": peer_aid})
+```python
+store = AIDStore(
+    aun_path="~/.aun/myapp",
+    encryption_seed="",
+    device_id=None,
+    slot_id="default",
+    debug=True,
+)
 ```
 
-### 迁移说明
+| 参数 | 说明 |
+|------|------|
+| `aun_path` | 应用级数据目录 |
+| `encryption_seed` | 本地密钥保护种子 |
+| `device_id` | 可选设备 ID；不传时从 `{aun_path}/.device_id` 读取或生成 |
+| `slot_id` | 默认连接槽位 |
+| `debug` | 是否输出 DEBUG 日志和文件日志 |
 
-| 旧 API（v0.3.3-） | 新 API（v0.3.4+） |
-|---|---|
-| `create_aid()` | `register_aid()`（已移除 `create_aid`） |
-| `authenticate()` 自动注册 | 必须先显式调用 `register_aid()` |
+### 常用方法
 
----
+| 方法 | 说明 |
+|------|------|
+| `load(aid)` | 从本地加载 AID，返回 Result |
+| `register(aid)` | 注册新 AID，返回 Result |
+| `list()` | 列出本地身份 |
+| `exists(aid)` | HEAD PKI 端点，判断 AID 是否已注册 |
+| `resolve(aid, opts=None)` | 拉取并缓存对端证书和 agent.md |
+| `fetch_agent_md(aid)` | 下载并验签对端 agent.md |
+| `check_agent_md(aid, ttl_days=1)` | 检查本地缓存与远端 agent.md 状态 |
+| `diagnose(aid)` | 本地和远端一致性诊断 |
+| `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
 
-## 注册 AID 和认证
+Result 使用方式：
 
 ```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
+result = await store.exists("alice.agentid.pub")
+if result["ok"] and not result["data"]["exists"]:
+    await store.register("alice.agentid.pub")
 ```
 
 ---
 
-## 连接到网关
-
-**必须先调用 `client.auth.authenticate()` 获取令牌和网关地址，再调用 `connect()`，此步骤不可跳过。** `authenticate()` 返回的 `gateway` 字段即为网关 WebSocket 地址。
-
-> 当前各语言 SDK 的稳定连接模式都是 Gateway。协议层虽然定义了 Peer / Relay，但 Python SDK 的 `connect(topology=...)` 目前会对 `peer` / `relay` 明确返回未实现。
+## AUNClient
 
-### 基础连接
+### 构造与身份加载
 
 ```python
-# 第一步：认证
-auth = await client.auth.authenticate({"aid": MY_AID})
-# auth["access_token"] — 访问令牌
-# auth["gateway"]      — 网关 WebSocket 地址
+client = AUNClient()       # no_identity
+client.load_identity(me)   # standby
 
-# 第二步：连接（auth 结果 + 连接选项）
-await client.connect(auth, {})
+client = AUNClient(me)     # standby
 ```
 
-### 完整连接选项
+`load_identity()` 只允许在 `no_identity` 或 `closed` 状态调用；传入对象必须是私钥有效的 AID。
 
-```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` 选项，上层如需停止自动重连，应主动关闭客户端。
+通常不需要单独调用认证，`connect()` 会自动完成。需要提前获取 token 或检查认证链路时可调用：
 
-**长短连接共存**：同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。长连接承担服务端推送（消息、事件）；短连接仅用于 RPC 请求-响应后立即断开（CLI 工具场景）。短连接默认禁用 `auto_reconnect`、心跳和 token 主动刷新。
+```python
+auth = await client.authenticate()
+print(auth["access_token"], auth["gateway"])
+```
 
-### 长连接 / 短连接代码示例
+认证成功后状态进入 `authenticated`，随后调用 `connect()` 建立会话。
 
-#### 长连接（守护进程：常驻收件箱）
+### 连接
 
 ```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",       # 默认值，可省略
+await client.connect({
     "slot_id": "main",
+    "connection_kind": "long",
     "auto_reconnect": True,
+    "heartbeat_interval": 30.0,
+    "token_refresh_before": 60.0,
+    "retry": {
+        "initial_delay": 1.0,
+        "max_delay": 64.0,
+    },
+    "timeouts": {
+        "connect": 5.0,
+        "call": 10.0,
+        "http": 30.0,
+    },
 })
-
-# 监听消息推送
-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 往返。
+| 选项 | 说明 |
+|------|------|
+| `slot_id` | 同一设备内的实例槽位 |
+| `connection_kind` | `"long"` 或 `"short"` |
+| `short_ttl_ms` | 短连接服务端兜底超时 |
+| `delivery_mode` | 连接级投递语义 |
+| `auto_reconnect` | 断线后是否自动重连 |
+| `heartbeat_interval` | 心跳间隔，秒 |
+| `token_refresh_before` | token 过期前刷新提前量，秒 |
+| `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
+| `timeouts.connect/call/http` | 连接、RPC、HTTP 超时 |
 
-长连接守护进程的后台 `_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"
-```
+当前稳定实现为 Gateway 模式；Peer / Relay 仍是协议能力定义，SDK 连接层会明确返回未实现。
 
 ---
 
-## 网关自动发现
-
-`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)` 触发检查。
+同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。
 
-### 跨域通信
-
-当发送消息到不同 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", ...})
+daemon = AUNClient(me)
+await daemon.connect({"connection_kind": "long", "slot_id": "main"})
+daemon.on("message.received", lambda e: print(e["payload"]))
 ```
 
-> 跨域路由的详细实现机制见协议文档：[附录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"])
+cli = AUNClient(me)
+await cli.connect({"connection_kind": "short", "slot_id": "main", "short_ttl_ms": 30000})
+await cli.call("message.send", {"to": peer, "payload": {"type": "text", "text": "hello"}})
+await cli.close()
 ```
 
-详细签名见 `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`（带缓存窗口） |
-
-底层方法仅推荐用于离线签名 / 纯文本验签等特殊场景。
+同一个 `AIDStore` / `aun_path` 下的 token、gateway、证书和 E2EE 材料会被复用。
 
-> 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` 即可**。
+注册、解析和认证会根据 AID 的 issuer 自动发现 Gateway：
 
-SDK 收到后通过 `_observe_agent_md_meta` 写入 `agent_md_cache` 持久化记录（按 AID 自动去重）；若发现"远程有 etag 但本地从未保存该 aid"，会异步触发后台 fetch（不阻塞 RPC 返回）。
+- 生产模式：优先 `https://{aid}/.well-known/aun-gateway`，失败后回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
+- 开发模式：优先 `gateway.{issuer}`，兼容没有泛域名的本地环境
 
-### 错误返回
+`verify_ssl` 由 `AUN_ENV` / `KITE_ENV` 控制。`development`、`dev`、`local` 会关闭校验，其余情况开启。
 
-- `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
-- `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
-- 主 API 在上述场景抛对应异常（NotFoundError / AUNError 等）
+发现成功后，SDK 会基于 WebSocket URL 推导 `/health` 地址，并通过 `gateway_health` 读取最近健康检查结果。
 
 ---
 
-## 调用 RPC 方法
-
-### `client.call(method, params)` — 通用 RPC 接口
-
-认证连接后，所有业务操作通过 `client.call()` 调用服务端 RPC 方法：
+## 状态与事件
 
 ```python
-result = await client.call(method: str, params: dict | None = None) -> Any
+print(client.state)
+print(client.can_connect, client.can_send, client.is_online)
 ```
 
-**示例：**
+常用事件：
 
-```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}
+| 事件 | 说明 |
+|------|------|
+| `connection.state` | 状态变化，payload 中的 `state` 是九态公开值 |
+| `connection.error` | 连接、认证、重连错误 |
+| `token.refreshed` | token 自动刷新完成 |
+| `message.received` | 收到消息 |
+| `group.changed` | 群组事件 |
+| `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 
-# 创建群组
-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 |
+建议在 `connect()` 前注册事件处理器。
 
 ---
 
-## 事件订阅
-
-### `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)
-```
+## Agent Web / agent.md
 
-**异步 handler：**
+发布自己的 agent.md：
 
 ```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)
+await client.publish_agent_md(content)
 ```
 
-**只触发一次（手动取消订阅）：**
+解析对端并验签 agent.md：
 
 ```python
-def on_state_change(e):
-    print(f"状态变更: {e}")
-    sub.unsubscribe()  # 触发后立即取消
-
-sub = client.on("connection.state", on_state_change)
+resolved = await store.resolve("bob.agentid.pub")
+if resolved["ok"]:
+    print(resolved["data"]["agent_md"]["signature"]["status"])
 ```
 
-**取消订阅：**
+只检查远端是否存在：
 
 ```python
-sub = client.on("message.received", handler)
-# ... 稍后
-sub.unsubscribe()
+head = await store.head_agent_md("bob.agentid.pub")
 ```
 
-**多个 handler：**
+---
 
-```python
-# 同一事件可注册多个 handler，按注册顺序依次调用
-client.on("message.received", log_message)
-client.on("message.received", update_ui)
-client.on("message.received", send_notification)
-```
+## RPC 调用
 
-**常用事件示例：**
+认证连接后，所有业务操作通过 `client.call()`：
 
 ```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}"))
+result = await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "Hello!"},
+})
 ```
 
-内置事件完整列表见 [06-API手册.md](06-API手册.md) 的「内置事件」节。
-
----
-
-## 关闭连接
-
-```python
-await client.close()
-```
+RPC 方法完整参数和响应格式见：
 
-关闭后状态变为 `"closed"`，不可复用，需重新创建 `AUNClient`。
+| 领域 | 手册 |
+|------|------|
+| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) |
+| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) |