@agentunion/fastaun-browser 0.4.13 → 0.5.0

package/_packed_docs/protocol//351/231/204/345/275/225K-Agent_Web/345/217/221/347/216/260/345/215/217/350/256/256.md

@@ -128,3 +128,5 @@ https://{aid}.{issuer_domain}/{svc}
 - `index.html` 是 Agent 面向人类用户的默认首页
 
 这使 AUN 在保持去中心化身份体系的同时，也为 Agent 的公开发现、说明页、服务页和后续生态扩展提供了统一入口。
+
+

package/_packed_docs/protocol//351/231/204/345/275/225L-E2EE/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -265,3 +265,5 @@ AES-GCM + AAD 验证保证消息完整性。AAD 包含以下字段，按 Canonic
 ## L.7 兼容性说明
 
 - 发送端 **MUST** 使用 `prekey_ecdh_v2`（四路 ECDH）模式发送新消息
+
+

package/_packed_docs/protocol//351/231/204/345/275/225M-JWT/350/256/244/350/257/201/345/256/236/347/216/260/346/214/207/345/215/227.md

@@ -365,3 +365,5 @@ Auth 服务证书轮换直接影响 JWT 验证，需特别处理：
 - 证书被吊销
 
 ---
+
+

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

@@ -255,3 +255,5 @@ if effective != client_mode:
 ## 文档版本
 
 - v1.0 — 2026-05-21 初稿，定义协议字段、链路传播、开关层级、安全约束
+
+

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

@@ -202,3 +202,5 @@ client := aun.NewAUNClient(aid.Data.AID)
 6. 通过 `close()` 释放连接和后台任务。
 
 详细 API 见 [06-API手册.md](06-API手册.md)，RPC 参数见各领域的 `09-*-rpc-manual.md`。
+
+

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

@@ -356,3 +356,5 @@ async def main():
 
 asyncio.run(main())
 ```
+
+

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

@@ -166,3 +166,5 @@ client.on("message.received", lambda e: print(e["payload"]))
 ```
 
 RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-storage-rpc-manual.md` 等专项手册。
+
+

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

@@ -260,3 +260,5 @@ RPC 方法完整参数和响应格式见：
 | 群组 | [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) |
+
+

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -611,3 +611,5 @@ client = AUNClient(aid)
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
 | 默认要求前向保密 | `require_forward_secrecy=true`，无 prekey 时拒绝 long_term_key 降级 |
 | 客户端操作签名 | `group.send`/`group.kick`/`group.add_member`/`group.leave` 等操作自动附加 `client_signature`，服务端强制验签 |
+
+

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

@@ -1,69 +1,69 @@
-# AUN SDK - API 手册
-
----
-
-## 目录
-
-- [AIDStore](#aidstore)
-- [AID](#aid)
+# AUN SDK - API 手册
+
+---
+
+## 目录
+
+- [AIDStore](#aidstore)
+- [AID](#aid)
 - [AUNClient](#aunclient)
 - [事件](#事件)
 - [ServiceProxyClient](#serviceproxyclient)
 - [E2EE 高级 API](#e2ee-高级-api)
 - [RPC 方法参考](#rpc-方法参考)
 - [Stream 使用指南](#stream-使用指南)
-
+
 > **多语言命名约定**：Python 使用 `snake_case`（如 `aun_path`、`download_agent_md`），TS/JS 使用 `camelCase`（如 `aunPath`、`downloadAgentMd`），Go 使用 `PascalCase` 公开方法（如 `Load`、`Register`）。本手册表格中各列对应各语言的实际命名。
-
----
-
-## AIDStore
-
-Python：
-
-```python
-store = AIDStore(
-    aun_path: str,
-    encryption_seed: str,
-    *,
-    device_id=None,
-    slot_id="default",
-    verify_ssl=None,      # None=自动（由 AUN_ENV/KITE_ENV 决定），True/False=强制
-    root_ca_path=None,    # 私有部署时指定自定义根证书路径
-    debug=False,
-)
-```
-
-TypeScript / JavaScript：
-
-```ts
-const store = new AIDStore({
-  aunPath, encryptionSeed,
-  deviceId, slotId,
-  verifySsl,    // 同 Python verify_ssl
-  rootCaPath,   // 同 Python root_ca_path
-  debug,
-});
-```
-
-Go：
-
-```go
-store := aun.NewAIDStore(aunPath, encryptionSeed)
-// 可选配置通过 AIDStoreOptions 传入
-store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
-    VerifySSL:  &[]bool{true}[0],
-    RootCaPath: "/path/to/ca.crt",
-    Debug:      true,
-})
-```
-
-### 方法
-
-| Python | TS/JS | Go | 说明 |
-|--------|-------|----|------|
-| `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
-| `register(aid)` | `register(aid)` | `Register(ctx, aid)` | 注册并落盘证书和私钥 |
+
+---
+
+## AIDStore
+
+Python：
+
+```python
+store = AIDStore(
+    aun_path: str,
+    encryption_seed: str,
+    *,
+    device_id=None,
+    slot_id="default",
+    verify_ssl=None,      # None=自动（由 AUN_ENV/KITE_ENV 决定），True/False=强制
+    root_ca_path=None,    # 私有部署时指定自定义根证书路径
+    debug=False,
+)
+```
+
+TypeScript / JavaScript：
+
+```ts
+const store = new AIDStore({
+  aunPath, encryptionSeed,
+  deviceId, slotId,
+  verifySsl,    // 同 Python verify_ssl
+  rootCaPath,   // 同 Python root_ca_path
+  debug,
+});
+```
+
+Go：
+
+```go
+store := aun.NewAIDStore(aunPath, encryptionSeed)
+// 可选配置通过 AIDStoreOptions 传入
+store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
+    VerifySSL:  &[]bool{true}[0],
+    RootCaPath: "/path/to/ca.crt",
+    Debug:      true,
+})
+```
+
+### 方法
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
+| `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
+| `register(aid)` | `register(aid)` | `Register(ctx, aid)` | 注册并落盘证书和私钥 |
 | `list()` | `list()` | `List()` | 列出本地 AID |
 | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
 | `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 拉证书并缓存；默认下载 agent.md，可用 `skip_agent_md` / `skipAgentMd` 跳过 |
@@ -74,18 +74,18 @@ store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
 | `renew_cert(aid)` / `rekey(aid)` | `renewCert(aid)` / `rekey(aid)` | `RenewCert(ctx, aid)` / `Rekey(ctx, aid)` | 证书运维 |
 | `change_seed(old, new)` | `changeSeed(old, new)` | `ChangeSeed(old, new)` | 本地密钥保护种子迁移 |
 
-Python / TS / JS / Go 的 `AIDStore` 方法都返回 Result 包装；Go 形态为 `Result[T]`，字段为 `Ok` / `Data` / `Error`。
-
-### Result 类型
-
-```python
-# ok=True 时
-{"ok": True, "data": {...}}
-
-# ok=False 时
-{"ok": False, "error": {"code": "ERROR_CODE", "message": "..."}}
-```
-
+Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览器 JS 因 IndexedDB / WebCrypto 约束返回 `Promise<Result>`。联网方法在 TS/JS 中均返回 `Promise<Result>`；Go 形态为 `Result[T]`，字段为 `Ok` / `Data` / `Error`。
+
+### Result 类型
+
+```python
+# ok=True 时
+{"ok": True, "data": {...}}
+
+# ok=False 时
+{"ok": False, "error": {"code": "ERROR_CODE", "message": "..."}}
+```
+
 ### DownloadAgentMdResult
 
 | 字段 | 类型 | 说明 |
@@ -117,128 +117,128 @@ Python / TS / JS / Go 的 `AIDStore` 方法都返回 Result 包装；Go 形态
 | `verify_status` / `verify_error` | str | 最近一次下载验签状态 |
 
 agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
-
-> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
-
----
-
-## AID
-
-AID 由 `AIDStore.load()` 返回，应用层不直接构造。
-
-### 只读属性
-
-| Python | TS/JS | Go | 说明 |
-|--------|-------|----|------|
-| `aid` | `aid` | `AID()` | AID 字符串 |
-| `cert_pem` | `certPem` | `CertPEM()` | 证书 PEM |
-| `public_key` | `publicKey` | `PublicKey()` | 公钥 |
-| `cert_fingerprint` | `certFingerprint` | `CertFingerprint()` | 证书指纹 |
-| `aun_path` | `aunPath` | `AUNPath()` | 所属数据目录 |
-| `device_id` | `deviceId` | `DeviceID` | 设备 ID |
+
+> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
+
+---
+
+## AID
+
+AID 由 `AIDStore.load()` 返回，应用层不直接构造。
+
+### 只读属性
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
+| `aid` | `aid` | `AID()` | AID 字符串 |
+| `cert_pem` | `certPem` | `CertPEM()` | 证书 PEM |
+| `public_key` | `publicKey` | `PublicKey()` | 公钥 |
+| `cert_fingerprint` | `certFingerprint` | `CertFingerprint()` | 证书指纹 |
+| `aun_path` | `aunPath` | `AUNPath()` | 所属数据目录 |
+| `device_id` | `deviceId` | `DeviceID` | 设备 ID |
 | `slot_id` | `slotId` | `SlotID` | 实例槽位 ID；允许 `/`、`:`、空格作为共享隔离键分隔符 |
-| `verify_ssl` | `verifySsl` | `VerifySSL` | 是否校验 TLS 证书 |
-| `root_ca_path` | `rootCaPath` | `RootCaPath` | 自定义根证书路径 |
-| `debug` | `debug` | `Debug` | 是否开启调试日志 |
-| `private_key_pem` | `privateKeyPem` | `PrivateKeyPem` | 明文私钥 PEM（由 `AIDStore.load()` 注入，空字符串表示无私钥）|
-
-### 方法
-
-| Python | TS/JS | Go | 说明 |
-|--------|-------|----|------|
-| `is_cert_valid()` | `isCertValid()` | `IsCertValid()` | 证书是否有效 |
-| `is_private_key_valid()` | `isPrivateKeyValid()` | `IsPrivateKeyValid()` | 私钥是否可用 |
-| `sign(data)` | `sign(data)` | `Sign(data)` | 签名 bytes |
-| `verify(data, signature)` | `verify(data, signature)` | `Verify(data, signature)` | 验签 |
-| `sign_agent_md(content)` | `signAgentMd(content)` | `SignAgentMd(content)` | agent.md 签名 |
-| `verify_agent_md(content)` | `verifyAgentMd(content)` | `VerifyAgentMd(content)` | agent.md 验签 |
-
----
-
-## AUNClient
-
-### 构造
-
-Python：
-
-```python
-client = AUNClient()
-client = AUNClient(aid)
-```
-
-TS/JS：
-
-```ts
-const client = new AUNClient();
-const client = new AUNClient(aid);
-```
-
-Go：
-
-```go
-client := aun.NewAUNClientEmpty()
-client := aun.NewAUNClient(aid)
-```
-
-构造约束：
-
-- `aid` 必须是 AID 对象（由 `AIDStore.load()` 返回）。
-- 不接受字符串 AID。
-- 不接受把 aid 放进 options。
-- 不接受旧的 `(config, debug)` 或 `(config, true)` 形态。
-
-### 身份与状态
-
-| Python | TS/JS | Go | 说明 |
-|--------|-------|----|------|
+| `verify_ssl` | `verifySsl` | `VerifySSL` | 是否校验 TLS 证书 |
+| `root_ca_path` | `rootCaPath` | `RootCaPath` | 自定义根证书路径 |
+| `debug` | `debug` | `Debug` | 是否开启调试日志 |
+| `private_key_pem` | `privateKeyPem` | `PrivateKeyPem` | 明文私钥 PEM（由 `AIDStore.load()` 注入，空字符串表示无私钥）|
+
+### 方法
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
+| `is_cert_valid()` | `isCertValid()` | `IsCertValid()` | 证书是否有效 |
+| `is_private_key_valid()` | `isPrivateKeyValid()` | `IsPrivateKeyValid()` | 私钥是否可用 |
+| `sign(data)` | `sign(data)` | `Sign(data)` | 签名 bytes |
+| `verify(data, signature)` | `verify(data, signature)` | `Verify(data, signature)` | 验签 |
+| `sign_agent_md(content)` | `signAgentMd(content)` | `SignAgentMd(content)` | agent.md 签名 |
+| `verify_agent_md(content)` | `verifyAgentMd(content)` | `VerifyAgentMd(content)` | agent.md 验签 |
+
+---
+
+## AUNClient
+
+### 构造
+
+Python：
+
+```python
+client = AUNClient()
+client = AUNClient(aid)
+```
+
+TS/JS：
+
+```ts
+const client = new AUNClient();
+const client = new AUNClient(aid);
+```
+
+Go：
+
+```go
+client := aun.NewAUNClientEmpty()
+client := aun.NewAUNClient(aid)
+```
+
+构造约束：
+
+- `aid` 必须是 AID 对象（由 `AIDStore.load()` 返回）。
+- 不接受字符串 AID。
+- 不接受把 aid 放进 options。
+- 不接受旧的 `(config, debug)` 或 `(config, true)` 形态。
+
+### 身份与状态
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
 | `load_identity(aid)` | `loadIdentity(aid)` | `LoadIdentity(aid)` | 在 `no_identity` / `closed` 状态加载身份 |
-| `state` | `state` | `ConnectionState()` | 九态公开状态 |
-| `gateway_url` | `gatewayUrl` | `GetGatewayURL()` | 当前连接的 Gateway URL（只读，自动发现，连接前为空） |
-| `current_aid` | `currentAid` | `CurrentAID()` | 当前 AID 对象 |
-| `aid` | `aid` | `AID()` | 当前 AID 字符串 |
-| `has_identity` | `hasIdentity` | `HasIdentity()` | 是否已加载身份 |
-| `can_sign` | `canSign` | `CanSign()` | 是否可签名 |
-| `can_connect` | `canConnect` | `CanConnect()` | 是否可连接 |
-| `can_send` / `is_ready` | `canSend` / `isReady` | `CanSend()` / `IsReady()` | 是否可发送 |
-| `is_online` | `isOnline` | `IsOnline()` | 是否处于在线或重连相关状态 |
-| `is_closed` | `isClosed` | `IsClosed()` | 是否已关闭 |
-
-状态值：
-
-```text
-no_identity / standby / authenticated / connecting / ready /
-retry_backoff / reconnecting / connection_failed / closed
-```
-
-### 生命周期
-
-Python：
-
-```python
-auth = await client.authenticate()
-await client.connect({"slot_id": "main", "auto_reconnect": True})
-await client.disconnect()
-await client.close()
-```
-
-说明：
-
-- `authenticate()` 只取 token，不建立业务会话。
-- `connect()` 可从 `standby` 自动认证并进入 `ready`。
-- `disconnect()` 断开当前传输连接，对象仍可重新连接。
-- `close()` 关闭连接和后台任务；之后只能重新加载身份再复用。
-
+| `state` | `state` | `ConnectionState()` | 九态公开状态 |
+| `gateway_url` | `gatewayUrl` | `GetGatewayURL()` | 当前连接的 Gateway URL（只读，自动发现，连接前为空） |
+| `current_aid` | `currentAid` | `CurrentAID()` | 当前 AID 对象 |
+| `aid` | `aid` | `AID()` | 当前 AID 字符串 |
+| `has_identity` | `hasIdentity` | `HasIdentity()` | 是否已加载身份 |
+| `can_sign` | `canSign` | `CanSign()` | 是否可签名 |
+| `can_connect` | `canConnect` | `CanConnect()` | 是否可连接 |
+| `can_send` / `is_ready` | `canSend` / `isReady` | `CanSend()` / `IsReady()` | 是否可发送 |
+| `is_online` | `isOnline` | `IsOnline()` | 是否处于在线或重连相关状态 |
+| `is_closed` | `isClosed` | `IsClosed()` | 是否已关闭 |
+
+状态值：
+
+```text
+no_identity / standby / authenticated / connecting / ready /
+retry_backoff / reconnecting / connection_failed / closed
+```
+
+### 生命周期
+
+Python：
+
+```python
+auth = await client.authenticate()
+await client.connect({"slot_id": "main", "auto_reconnect": True})
+await client.disconnect()
+await client.close()
+```
+
+说明：
+
+- `authenticate()` 只取 token，不建立业务会话。
+- `connect()` 可从 `standby` 自动认证并进入 `ready`。
+- `disconnect()` 断开当前传输连接，对象仍可重新连接。
+- `close()` 关闭连接和后台任务；之后只能重新加载身份再复用。
+
 四个 SDK 的公开构造入口均已对齐为“无参或 AID 对象”。调试、TLS、根证书、device_id、slot_id 等配置由 `AIDStore` 传递到 AID，再由 `AUNClient` 继承；连接级选项只传给 `connect()`。
-
-### RPC
-
-```python
-result = await client.call("message.send", {
-    "to": "bob.agentid.pub",
-    "payload": {"type": "text", "text": "hello"},
-})
-```
-
+
+### RPC
+
+```python
+result = await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "payload": {"type": "text", "text": "hello"},
+})
+```
+
 常用 meta RPC 直接透传：
 
 ```python
@@ -289,16 +289,16 @@ client = AUNClient(aid)
 client.set_protected_headers({"sdk": "python", "trace": "abc"})
 headers = client.get_protected_headers()
 ```
-
-只合并到以下 RPC：
-
-- `message.send`
-- `group.send`
-- `message.thought.put`
-- `group.thought.put`
-
-### agent.md
-
+
+只合并到以下 RPC：
+
+- `message.send`
+- `group.send`
+- `message.thought.put`
+- `group.thought.put`
+
+### agent.md
+
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
 | `AIDStore.upload_agent_md(aid, content=None)` | `store.uploadAgentMd(aid, content?)` | `store.UploadAgentMD(ctx, aid, content...)` | 发布指定本地 AID 的 agent.md |
@@ -314,6 +314,20 @@ headers = client.get_protected_headers()
 
 ---
 
+## 业务门面
+
+除 `client.call(method, params)` 外，四语言 SDK 对 storage、collab 和 group.fs 群文件系统提供高层门面。普通应用优先用门面，只有需要精确控制底层参数时再直调 RPC。
+
+| 能力 | Python | TS/JS | Go | 说明 |
+|------|--------|-------|----|------|
+| Storage VFS | `client.storage` | `client.storage` | `client.Storage()` | 类 POSIX 文件操作；上传自动选择 inline / session / 秒传，下载自动选择 inline / ticket |
+| Collab | `client.collab` | `client.collab` | `client.Collab()` | 版本化文档、标签、`gc` / `reflog` / `revert` |
+| Group FS | `client.group.fs` | `client.group.fs` | `client.Group().FS()` | POSIX 风格群文件系统；`ls/find/stat/lstat/mkdir/rm/cp/mv/df/mount/umount`，上传下载数据面由 SDK 编排 |
+
+群文件系统路径统一使用 `group_aid:/...`，成员数据区使用 `group_aid:/memberdata/{member_ref}/...`。SDK 不拼接真实 storage 路径，`memberdata` 到成员 `groupdata/{group_id}` 的映射只在服务端完成。群自有区写入必须使用群主持有的 `group_aid` 身份并通过当前 group_identity 签名；admin/member 个人 AID 不直接拥有写权限。JS 浏览器版上传中 `string` 默认表示文本内容，Node 本地路径需显式 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀；Python/TS/Go 默认把 `string` 当本地路径。
+
+---
+
 ## ServiceProxyClient
 
 Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
@@ -367,75 +381,77 @@ proxy-server 连接地址不能由应用外部传入或配置。`ServiceProxyCli
 
 ```python
 sub = client.on("message.received", handler)
-client.off("message.received", handler)
-sub.unsubscribe()
-```
-
-常用内置事件：
-
-| 事件 | 说明 |
-|------|------|
-| `state_change` | 状态变化，`state` 为九态公开值 |
-| `connection.error` | 连接或重连错误 |
-| `token.refreshed` | token 刷新完成 |
-| `message.received` | 收到 P2P 消息 |
-| `message.ack` | 消息 ack |
-| `message.undecryptable` | P2P E2EE 解密失败 |
-| `group.changed` | 群组事件 |
-| `group.message_undecryptable` | 群 E2EE 解密失败 |
-
----
-
-## E2EE 高级 API
-
-普通业务无需直接操作 E2EE manager；`message.send` / `group.send` 默认加密并自动解密收到的消息。
-
-高级场景可使用：
-
-| API | 说明 |
-|-----|------|
-| `client.e2ee.encrypt_message(...)` | 裸 WebSocket 或特殊集成中的 P2P 加密 |
-| `client.e2ee.decrypt_message(...)` | 裸消息解密 |
-| `client.e2ee.generate_prekey()` | 生成 prekey |
-| `client.e2ee.invalidate_prekey_cache(peer_aid)` | 清理对端 prekey 缓存 |
-| `client.group_e2ee.encrypt(...)` | 群消息加密 |
-| `client.group_e2ee.decrypt(...)` | 群消息解密 |
-| `client.group_e2ee.current_epoch(group_id)` | 查询当前群 epoch |
-
----
-
-## RPC 方法参考
-
-| 领域 | 手册 | 关键方法 |
-|------|------|----------|
-| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.ack` / `message.thought.*` |
-| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.v2.*` / `group.resources.*` |
-| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.create_upload_session` / `storage.create_folder` / `storage.create_share_link` |
+client.off("message.received", handler)
+sub.unsubscribe()
+```
+
+常用内置事件：
+
+| 事件 | 说明 |
+|------|------|
+| `state_change` | 状态变化，`state` 为九态公开值 |
+| `connection.error` | 连接或重连错误 |
+| `token.refreshed` | token 刷新完成 |
+| `message.received` | 收到 P2P 消息 |
+| `message.ack` | 消息 ack |
+| `message.undecryptable` | P2P E2EE 解密失败 |
+| `group.changed` | 群组事件 |
+| `group.message_undecryptable` | 群 E2EE 解密失败 |
+
+---
+
+## E2EE 高级 API
+
+普通业务无需直接操作 E2EE manager；`message.send` / `group.send` 默认加密并自动解密收到的消息。
+
+高级场景可使用：
+
+| API | 说明 |
+|-----|------|
+| `client.e2ee.encrypt_message(...)` | 裸 WebSocket 或特殊集成中的 P2P 加密 |
+| `client.e2ee.decrypt_message(...)` | 裸消息解密 |
+| `client.e2ee.generate_prekey()` | 生成 prekey |
+| `client.e2ee.invalidate_prekey_cache(peer_aid)` | 清理对端 prekey 缓存 |
+| `client.group_e2ee.encrypt(...)` | 群消息加密 |
+| `client.group_e2ee.decrypt(...)` | 群消息解密 |
+| `client.group_e2ee.current_epoch(group_id)` | 查询当前群 epoch |
+
+---
+
+## RPC 方法参考
+
+| 领域 | 手册 | 关键方法 |
+|------|------|----------|
+| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.ack` / `message.thought.*` |
+| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.v2.*` / `group.fs.*` |
+| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.fs.*` / `storage.volume.*` / ACL / token / share link |
+| 协作 | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) | `collab.ls-files` / `collab.show` / `collab.commit` / `collab.merge` / `collab.log` / `collab.diff` / `collab.clone` / `collab.prune` / `collab.gc` / `collab.reflog` / `collab.revert` / `collab.tag.*` / `collab.ls-remote` / `collab.unregister` |
 | 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |
 | Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
 | Service Proxy | [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` |
 
 ---
-
-## Stream 使用指南
-
-创建流：
-
-```python
-stream = await client.call("stream.create", {
-    "kind": "audio",
-    "metadata": {"sample_rate": 16000},
-})
-```
-
-查询流：
-
-```python
-info = await client.call("stream.get_info", {"stream_id": stream["stream_id"]})
-```
-
-关闭流：
-
-```python
-await client.call("stream.close", {"stream_id": stream["stream_id"]})
-```
+
+## Stream 使用指南
+
+创建流：
+
+```python
+stream = await client.call("stream.create", {
+    "kind": "audio",
+    "metadata": {"sample_rate": 16000},
+})
+```
+
+查询流：
+
+```python
+info = await client.call("stream.get_info", {"stream_id": stream["stream_id"]})
+```
+
+关闭流：
+
+```python
+await client.call("stream.close", {"stream_id": stream["stream_id"]})
+```
+