@agentunion/fastaun-browser 0.3.5 → 0.4.0

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/09-storage-rpc-manual.md

@@ -13,6 +13,8 @@
 | [storage.list_objects](#storagelist_objects) | 列举对象 |
 | [storage.list_prefixes](#storagelist_prefixes) | 列举子目录 |
 | [storage.get_quota](#storageget_quota) | 查询配额 |
+| [storage.get_limits](#storageget_limits) | 查询上传限制 |
+| [storage.check_upload](#storagecheck_upload) | 上传预检（秒传检测 + 超限检测） |
 
 ### 数据面协调方法
 
@@ -397,6 +399,93 @@ for obj in result["items"]:
 
 ---
 
+## storage.get_limits
+
+查询当前用户的上传限制和配额使用情况。客户端可在上传前调用此方法，避免超限后浪费流量。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner_aid` | string | 否 | 查询指定用户的配额，默认当前用户 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `max_inline_bytes` | integer | `put_object` 内联上限（当前 64KB） |
+| `max_file_size_bytes` | integer | 单文件大小上限（当前 10MB） |
+| `quota_total_bytes` | integer | 用户总配额（0 表示无限制） |
+| `quota_used_bytes` | integer | 已用配额 |
+
+### 示例
+
+```python
+limits = await client.call("storage.get_limits", {})
+print(f"单文件上限: {limits['max_file_size_bytes']} bytes")
+print(f"配额: {limits['quota_used_bytes']}/{limits['quota_total_bytes']}")
+```
+
+---
+
+## storage.check_upload
+
+上传预检：一次调用同时回答"文件是否超限"和"是否可秒传"。客户端应在计算完文件 SHA-256 后、实际上传前调用。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sha256` | string | 是 | 文件内容的 SHA-256 hex（64 字符） |
+| `size_bytes` | integer | 是 | 文件大小（字节） |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `within_limit` | boolean | 文件大小是否在限制内 |
+| `exists` | boolean | 服务端是否已有相同内容 |
+| `skip_upload` | boolean | 是否可跳过上传（秒传） |
+
+### 使用场景
+
+```python
+import hashlib
+
+data = open("large_file.bin", "rb").read()
+sha256 = hashlib.sha256(data).hexdigest()
+
+check = await client.call("storage.check_upload", {
+    "sha256": sha256,
+    "size_bytes": len(data),
+})
+
+if not check["within_limit"]:
+    print("文件超限，无法上传")
+elif check["skip_upload"]:
+    # 秒传：服务端已有相同内容，跳过上传直接 complete
+    await client.call("storage.complete_upload", {
+        "object_key": "my/file.bin",
+        "sha256": sha256,
+        "size_bytes": len(data),
+        "skip_blob": True,
+    })
+else:
+    # 正常上传流程
+    session = await client.call("storage.create_upload_session", {
+        "object_key": "my/file.bin",
+        "size_bytes": len(data),
+    })
+    # HTTP PUT ...
+    await client.call("storage.complete_upload", {
+        "object_key": "my/file.bin",
+        "sha256": sha256,
+        "size_bytes": len(data),
+    })
+```
+
+---
+
 ## 错误码
 
 | code | 说明 |