@agentunion/fastaun-browser 0.4.9 → 0.4.11

package/_packed_docs/sdk/09-proxy-rpc-manual.md

@@ -0,0 +1,231 @@
+# Service Proxy — RPC Manual
+
+## 方法索引
+
+### Gateway 控制面方法
+
+| 方法 | 说明 |
+|------|------|
+| [proxy.register_services](#proxyregister_services) | 注册当前 Gateway 长连接可提供的 Service Proxy 服务列表 |
+| [proxy.unregister_services](#proxyunregister_services) | 注销当前 Gateway 长连接上的部分或全部服务列表 |
+| [proxy.list_services](#proxylist_services) | 查询当前 Gateway 长连接已注册的服务列表 |
+
+### proxy-server 数据面隧道消息
+
+| 消息 | 方向 | 说明 |
+|------|------|------|
+| [register_services](#register_services-隧道消息) | proxy-client → proxy-server | proxy-server 隧道认证后注册本连接的数据面服务列表 |
+| `register_services_ack` | proxy-server → proxy-client | 数据面服务注册成功确认 |
+
+---
+
+## 控制面与数据面
+
+Service Proxy 有两层注册，二者都必须存在：
+
+- **Gateway 控制面**：provider 的 AUN 长连接调用 `proxy.register_services`，Gateway 记录该 provider 在线且声明了哪些服务。proxy-server 用它判断 provider 是否在线、目标服务是否声明、是否应该 wakeup。
+- **proxy-server 数据面**：proxy-client 连接 proxy-server 的 `/ws/client` 并完成认证后，必须再发送 `register_services` 隧道消息。proxy-server 只会向本地已注册目标服务的数据面连接转发请求。
+
+服务列表与连接绑定。Gateway 长连接断开后，Gateway 上的服务列表立即失效；proxy-server 隧道断开后，proxy-server 上的服务列表立即失效。
+
+同一个 provider AID 可以有多个实例连接，但所有实例注册的服务摘要必须一致。若同一 provider AID 的第二条连接注册了不同服务列表，服务端应拒绝该次注册并返回 `proxy_services_inconsistent`。
+
+---
+
+## 服务摘要
+
+服务摘要只描述可公开发现的服务能力，不包含本地 endpoint。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `service_name` | string | 是 | 服务名，建议使用 `[a-z0-9_-]+` |
+| `service_type` | string | 否 | 服务类型，默认 `http`；常见值为 `http` / `websocket` / `sse` / `mcp` |
+| `visibility` | string | 否 | 可见性，默认 `private` |
+| `metadata` | object | 否 | 非敏感描述信息。服务端会移除 token、secret、endpoint、url、cookie、key、cert 等敏感字段 |
+
+Python `ServiceProxyClient.register_service()` 会保存本地 endpoint，但 `list_service_summaries()`、Gateway 注册和 proxy-server 注册只发送摘要。
+
+---
+
+## proxy.register_services
+
+注册当前 Gateway 长连接提供的 Service Proxy 服务列表。服务端必须以连接认证得到的 AID 作为 provider AID，不能信任客户端传入的 `provider_aid` 覆盖认证身份。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `provider_aid` | string | 否 | 兼容字段或诊断字段；服务端以认证身份为准 |
+| `services` | array | 是 | 服务摘要列表 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | boolean | 固定为 `true` |
+| `provider_aid` | string | 认证后的 provider AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `count` | integer | 已注册服务数量 |
+| `services` | array | 服务端清洗后的服务摘要列表 |
+
+### 示例
+
+```python
+result = await client.call("proxy.register_services", {
+    "services": [
+        {
+            "service_name": "fileshare",
+            "service_type": "http",
+            "visibility": "public",
+            "metadata": {"label": "Files"},
+        }
+    ],
+})
+```
+
+### 错误
+
+| JSON-RPC code | message | 原因 |
+|---------------|---------|------|
+| -32602 | `proxy service registration requires a long connection` | 短连接不能注册 Service Proxy 服务 |
+| -32020 | `proxy_services_inconsistent` | 同一 provider AID 的已有连接注册了不一致的服务列表 |
+
+---
+
+## proxy.unregister_services
+
+注销当前 Gateway 长连接上的部分或全部服务。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `service_names` | array | 否 | 要注销的服务名列表；省略时注销当前连接上的全部服务 |
+| `service_name` | string | 否 | 单服务兼容字段 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | boolean | 固定为 `true` |
+| `provider_aid` | string | 认证后的 provider AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `removed` | array | 实际移除的服务名 |
+| `count` | integer | 剩余服务数量；全部注销时可省略 |
+
+### 示例
+
+```python
+await client.call("proxy.unregister_services", {
+    "service_names": ["fileshare"],
+})
+```
+
+---
+
+## proxy.list_services
+
+查询当前 Gateway 长连接已注册的 Service Proxy 服务列表。
+
+### 参数
+
+无有效参数。`provider_aid` 若存在，也只能作为兼容字段；服务端以当前连接身份为准。
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `provider_aid` | string | 当前连接认证后的 AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `services` | array | 当前连接已注册的服务摘要列表 |
+
+### 示例
+
+```python
+current = await client.call("proxy.list_services", {})
+```
+
+---
+
+## register_services 隧道消息
+
+proxy-client 连接 proxy-server `/ws/client` 并收到 `service_proxy_auth_response.ok=true` 后，必须立即发送 `register_services` 隧道消息。proxy-server 只根据这个数据面注册表选择实际转发连接。
+
+### 请求
+
+```json
+{
+  "type": "register_services",
+  "request_id": "register-services",
+  "services": [
+    {
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }
+  ]
+}
+```
+
+### 成功响应
+
+```json
+{"type": "register_services_ack", "request_id": "register-services", "ok": true, "count": 1}
+```
+
+### 失败响应
+
+```json
+{
+  "type": "service_proxy_error",
+  "request_id": "register-services",
+  "error": {
+    "code": "proxy_services_inconsistent",
+    "message": "provider service list is inconsistent with existing connections"
+  }
+}
+```
+
+---
+
+## Python ServiceProxyClient
+
+Python SDK 的 `ServiceProxyClient` 已封装双注册流程：
+
+1. `connect_once()` / `serve_once()` / `serve_forever()` 建立 proxy-server 隧道前，会在存在 `aun_client.call()` 时自动调用 `proxy.register_services`。
+2. proxy-server 连接地址必须通过 `/.well-known/aun-proxy` 发现：先读 provider AID SQLite metadata 中 1 小时 TTL 的 `service_proxy_discovery` 缓存；缓存缺失或过期时查询 `https://{provider_aid}/.well-known/aun-proxy`，失败后回退 `https://proxy.{issuer}/.well-known/aun-proxy`。应用不得传入、配置或硬拼 proxy-server URL。
+3. proxy-server 隧道使用 AUN auth token 鉴权：优先复用 cached access token；缓存缺失或过期时，必须通过 `aun_client.authenticate()` 经 Gateway 两步登录刷新 token。
+4. proxy-server 隧道认证成功后，会自动发送 `register_services` 隧道消息。
+5. persistent 和 on-demand 重连时，每条新连接都会重新执行以上流程。
+
+常用入口：
+
+| 方法 | 说明 |
+|------|------|
+| `register_service(name, endpoint, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
+| `unregister_service(name)` | 移除本地 endpoint |
+| `list_service_summaries()` | 返回可上报的服务摘要 |
+| `register_services_with_gateway()` | 显式向 Gateway 注册控制面服务列表 |
+| `unregister_services_from_gateway(names=None)` | 显式从 Gateway 注销控制面服务 |
+| `list_gateway_services()` | 查询 Gateway 当前连接服务列表 |
+| `register_services_with_proxy_server(ws)` | 通过已认证 proxy-server 隧道注册数据面服务列表 |
+| `discover_proxy_server(force_refresh=False)` | 通过缓存 / well-known 发现 proxy-server |
+| `serve_once()` / `serve_forever()` | 连接 proxy-server 并处理转发请求 |
+
+---
+
+## 路由与 wakeup 语义
+
+proxy-server 收到 `https://proxy.{issuer}/{user_name}/{svc_name}` 或对应 WebSocket 请求时，应按以下顺序处理：
+
+1. 本 proxy-server 已有 `(provider_aid, service_name)` 数据面连接：直接转发，并按 visitor/provider/service 维持稳定粘性。
+2. provider 已连接本 proxy-server 且已注册服务列表，但没有目标服务：返回 `service_not_registered`，不 wakeup。
+3. provider 未连接本 proxy-server：查询 Gateway 控制面。
+4. Gateway 检查 provider AID 证书不存在：返回 `provider_aid_not_found`；证书查询失败：返回 `provider_aid_check_failed`。
+5. Gateway 显示 provider 没有在线长连接：返回 `provider_offline`。
+6. Gateway 显示 provider 在线但未声明目标服务：返回 `service_not_registered`，不 wakeup。
+7. Gateway 显示 provider 在线且声明目标服务：仅向注册了该服务的 provider 连接发送 wakeup。
+8. wakeup 已投递但本 proxy-server 等不到目标数据面隧道注册时，返回 `provider_wakeup_timeout`。
+
+因此，只向 Gateway 注册不足以承载请求；只有 proxy-server 数据面也注册了目标服务，访问才会真正转发。

package/_packed_docs/sdk/09-storage-rpc-manual.md

@@ -12,18 +12,51 @@
 | [storage.delete_object](#storagedelete_object) | 删除对象 |
 | [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) | 上传预检（秒传检测 + 超限检测） |
-
-### 数据面协调方法
-
-| 方法 | 说明 |
+| [storage.get_quota](#storageget_quota) | 查询配额 |
+| [storage.get_limits](#storageget_limits) | 查询上传限制 |
+| [storage.check_upload](#storagecheck_upload) | 上传预检（秒传检测 + 超限检测） |
+
+### 目录树方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.create_folder](#storagecreate_folder) | 创建目录 |
+| [storage.get_folder](#storageget_folder) | 查询目录 |
+| [storage.list_children](#storagelist_children) | 列出目录子节点 |
+| [storage.rename_folder](#storagerename_folder) | 重命名目录 |
+| [storage.move_folder](#storagemove_folder) | 移动目录 |
+| [storage.delete_folder](#storagedelete_folder) | 删除目录 |
+| [storage.resolve_path](#storageresolve_path) | 按路径解析节点 |
+
+### 对象管理方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.move_object](#storagemove_object) | 移动或重命名对象 |
+| [storage.copy_object](#storagecopy_object) | 复制对象 |
+| [storage.batch_delete](#storagebatch_delete) | 批量删除对象/目录 |
+| [storage.batch_head_object](#storagebatch_head_object) | 批量查询对象元数据 |
+| [storage.set_object_meta](#storageset_object_meta) | 更新对象元数据 |
+| [storage.get_object_url](#storageget_object_url) | 获取稳定对象 URL |
+| [storage.append_object](#storageappend_object) | 追加写对象 |
+
+### 数据面协调方法
+
+| 方法 | 说明 |
 |------|------|
 | [storage.create_upload_session](#storagecreate_upload_session) | 申请上传 URL |
 | [storage.complete_upload](#storagecomplete_upload) | 确认上传完成 |
 | [storage.create_download_ticket](#storagecreate_download_ticket) | 申请下载 URL |
 
+### 分享方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.create_share_link](#storagecreate_share_link) | 创建分享链接 |
+| [storage.list_share_links](#storagelist_share_links) | 列举分享链接 |
+| [storage.revoke_share_link](#storagerevoke_share_link) | 撤销分享链接 |
+| [storage.get_by_share](#storageget_by_share) | 通过分享短码读取对象 |
+
 ---
 
 > `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
@@ -51,6 +84,8 @@
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转到直链 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
@@ -246,9 +281,9 @@ for obj in result["items"]:
 
 ---
 
-## storage.get_quota
-
-查询存储配额。
+## storage.get_quota
+
+查询存储配额。
 
 ### 参数
 
@@ -263,13 +298,193 @@ for obj in result["items"]:
 | `owner_aid` | string | 所有者 AID |
 | `used_bytes` | integer | 已使用空间（字节） |
 | `object_count` | integer | 对象数量 |
-| `quota_bytes` | integer | 配额上限（字节），0 表示无限制 |
-
----
-
-## storage.create_upload_session
-
-获取上传用 presigned URL。
+| `quota_bytes` | integer | 配额上限（字节），0 表示无限制 |
+
+---
+
+## storage.create_folder
+
+创建目录节点。目录和对象共用同一个 `bucket`，默认 bucket 为 `"default"`。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | string | 否 | 完整目录路径；提供时优先使用 |
+| `name` | string | 否 | 目录名；未提供 `path` 时必填 |
+| `parent_folder_id` | string | 否 | 父目录 ID |
+| `parent_path` | string | 否 | 父目录路径，默认根目录 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `mkdirs` | boolean | 否 | 是否递归创建父目录 |
+| `metadata` | object | 否 | 目录元数据 |
+| `conflict_policy` | string | 否 | `"reject"` / `"return_existing"` |
+
+**响应**：返回 `folder`，同时在顶层展开 `folder_id`、`path`、`name`、`parent_folder_id`、`version` 等字段。
+
+---
+
+## storage.get_folder
+
+查询目录节点。
+
+**参数**：`folder_id` 或 `path` 至少提供一个；可选 `bucket`、`owner_aid`。
+
+**响应**：同 `storage.create_folder` 的 `folder` 视图。
+
+---
+
+## storage.list_children
+
+列出目录下的直接子目录和对象。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `folder_id` / `path` | string | 否 | 目标目录；都不传表示根目录 |
+| `type` | string | 否 | `"all"` / `"folder"` / `"object"`，默认 `"all"` |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `page` | integer | 否 | 页码，默认 1 |
+| `size` | integer | 否 | 每页数量，最大受服务配置限制 |
+| `order_by` | string | 否 | `"name"` / `"updated_at"` / `"size_bytes"` |
+| `order` | string | 否 | `"asc"` / `"desc"` |
+| `include_metadata` | boolean | 否 | 是否返回元数据，默认 `true` |
+| `include_urls` | boolean | 否 | 是否返回 URL 字段，默认 `true` |
+
+**响应**：`folder`、`items`、`total`、`page`、`size`、`next_marker`。`items[].node_type` 区分 `folder` / `object`。
+
+---
+
+## storage.rename_folder
+
+重命名目录。根目录不可改名。
+
+**参数**：`folder_id` 或 `path`，`new_name` 必填；可选 `bucket`、`owner_aid`、`expected_version`。
+
+**响应**：更新后的 `folder` 视图。
+
+---
+
+## storage.move_folder
+
+移动目录。不能移动到自身或自身子目录。
+
+**参数**：`folder_id` 或 `path`，目标目录通过 `dst_parent_folder_id` 或 `dst_parent_path` 指定；可选 `new_name`、`bucket`、`owner_aid`、`expected_version`。
+
+**响应**：更新后的 `folder` 视图。
+
+---
+
+## storage.delete_folder
+
+删除目录。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `folder_id` / `path` | string | 是 | 待删除目录 |
+| `recursive` | boolean | 否 | 非空目录必须传 `true` |
+| `dry_run` | boolean | 否 | 只预览将删除的目录/对象 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+
+**响应**：`deleted_folders`、`deleted_objects`、`deleted_object_items`、`errors`；`dry_run=true` 时返回预览列表。
+
+---
+
+## storage.resolve_path
+
+按路径解析目录或对象。
+
+**参数**：`path` 必填；可选 `expected_type`（`"any"` / `"object"` / `"folder"`）、`bucket`、`owner_aid`。
+
+**响应**：`type`、`folder_id` 或 `object_id`、`path`、`status`。
+
+---
+
+## storage.move_object
+
+移动或重命名对象。
+
+**参数**：对象选择器（`object_id` / `object_key` / `path`），目标目录 `dst_parent_folder_id` 或 `dst_parent_path`；可选 `new_name`、`conflict_policy`（`"reject"` / `"replace"` / `"keep_both"`）、`expected_version`。
+
+**响应**：返回 `object`，同时在顶层展开对象视图字段。
+
+---
+
+## storage.copy_object
+
+复制对象，底层内容按 CAS 引用计数复用。
+
+**参数**：源对象选择器（`object_id` / `object_key` / `path`，也接受 `src_object_key` / `src_path`），目标 `dst_object_key` / `dst_path` 或目标父目录 + `new_name`；可选 `conflict_policy`、`copy_metadata`。
+
+**响应**：新对象视图。
+
+---
+
+## storage.batch_delete
+
+批量删除对象或目录。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | array | 否 | 每项含 `type`、`object_id` / `object_key` / `path` / `folder_id` |
+| `object_keys` | string[] | 否 | 兼容简写，转为对象删除 |
+| `recursive` | boolean | 否 | 删除目录时是否递归 |
+| `dry_run` | boolean | 否 | 只预览 |
+
+**响应**：`deleted`、`errors`、`deleted_count`、`summary`。
+
+---
+
+## storage.batch_head_object
+
+批量查询对象元数据。
+
+**参数**：`object_ids`、`paths` 至少提供一类；可选 `owner_aid`、`bucket`、`include_missing`、`include_metadata`、`include_urls`。
+
+**响应**：`items` 和 `errors`。
+
+---
+
+## storage.set_object_meta
+
+更新对象元数据和可选 MIME 类型。
+
+**参数**：对象选择器，`metadata`；可选 `merge`（默认 `true`）、`content_type`、`expected_version`。
+
+**响应**：更新后的对象视图。
+
+---
+
+## storage.get_object_url
+
+获取稳定对象 URL。
+
+**参数**：对象选择器；可选 `include_path_url`。
+
+**响应**：`object_id`、`object_url`、`path_url`、`stable`。
+
+---
+
+## storage.append_object
+
+向对象尾部追加 base64 内容；对象不存在时创建。
+
+**参数**：与 `storage.put_object` 类似，`content` 必填；可选 `object_key` / `path` / `name`、`bucket`、`owner_aid`、`content_type`、`metadata`、`expected_version`、`is_private`。
+
+**响应**：对象视图。
+
+---
+
+## storage.create_upload_session
+
+获取上传用 presigned URL。
 
 ### 参数
 
@@ -313,12 +528,13 @@ for obj in result["items"]:
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `object_key` | string | 是 | 对象路径 |
-| `sha256` | string | 是 | 文件 SHA-256 哈希 |
+| `sha256` | string | 否 | 文件 SHA-256 哈希；提供则校验完整性，`skip_blob=true` 时必填 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
 | `is_private` | boolean | 否 | 是否私有，默认 `true` |
 | `size_bytes` | integer | 否 | 预期文件大小（用于校验） |
+| `skip_blob` | boolean | 否 | 秒传模式，默认 `false`；为 `true` 时跳过 blob 上传，必须提供 `sha256` 且服务端已存在对应内容 |
 | `expected_version` | integer | 否 | 乐观并发控制版本号 |
 | `expire_in_seconds` | integer | 否 | 过期时间（秒） |
 | `metadata` | object | 否 | 自定义元数据 |
@@ -327,6 +543,8 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，无跳转 |
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
@@ -356,8 +574,10 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `download_url` | string | 下载用 presigned URL |
-| `expire_at` | integer | URL 过期时间戳 |
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
+| `download_url` | string | 预签名下载 URL（有时效，签名形式由 BlobStore 后端决定） |
+| `expire_at` | integer | `download_url` 的过期时间戳（Unix 秒） |
 | `file_name` | string | 文件名（从 object_key 提取） |
 | `size_bytes` | integer | 文件大小（字节） |
 | `content_type` | string | MIME 类型 |
@@ -365,7 +585,7 @@ for obj in result["items"]:
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
 
-客户端获得 `download_url` 后，通过 HTTP GET 下载文件。
+客户端获得 `download_url` 后，通过 HTTP GET 下载文件。`url` 为永久可分享的 AID 风格链接，`logical_url` 为无跳转直链。
 
 > 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
 
@@ -486,7 +706,119 @@ else:
 
 ---
 
-## 错误码
+## storage.create_share_link
+
+创建分享链接。生成一个短码（share_id），通过短码可访问对象，支持授权 AID 白名单、有效期、使用次数限制。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 被分享对象的路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 对象所有者 AID，默认当前用户（仅可分享自己的对象） |
+| `allowed_aids` | string[] | 否 | 授权访问的 AID 列表，默认 `["*"]`（任意 AID 可访问）；含 `"*"` 即视为公开 |
+| `expire_in_seconds` | integer | 否 | 有效期（秒），默认 86400（1 天），`0` 表示永不过期 |
+| `max_uses` | integer | 否 | 最大使用次数，默认 `0`（无限制） |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `share_id` | string | 10 位 Base62 分享短码 |
+| `aid_share_url` | string | **AID 风格分享 URL（默认/推荐）**：`https://{owner_aid}/storage/{share_id}`，体现分享者身份 |
+| `share_url` | string | 直链分享 URL：`{base_url}/s/{share_id}`，兼容字段 |
+| `expire_at` | integer | 过期时间戳（Unix 秒），`0` 表示永不过期 |
+| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
+| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+
+> 访问 `aid_share_url` 时经 NameService 302 跳转到 `share_url`。share_id 是 10 位无斜杠 Base62，与 object_key 路径天然区分（object_key 含 `/` 或非 10 位）。
+> share_id 指向 `(owner_aid, bucket, object_key)` 逻辑引用，非内容快照：对象改名/移动后原 share_id 失效，内容覆盖后下载到新内容。
+
+### 示例
+
+```python
+result = await client.call("storage.create_share_link", {
+    "object_key": "docs/report.pdf",
+    "allowed_aids": ["alice.agentid.pub"],
+    "expire_in_seconds": 3600,
+    "max_uses": 5,
+})
+share_url = result["aid_share_url"]
+```
+
+---
+
+## storage.list_share_links
+
+列举分享链接，可按 bucket / object_key 过滤。仅返回当前用户自己创建的链接。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bucket` | string | 否 | 按存储桶过滤 |
+| `object_key` | string | 否 | 按对象路径过滤 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `links` | array | 分享链接列表 |
+
+每个 link 包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `share_id` | string | 分享短码 |
+| `aid_share_url` | string | AID 风格分享 URL（主字段） |
+| `share_url` | string | 直链分享 URL（兼容） |
+| `object_key` | string | 被分享对象路径 |
+| `bucket` | string | 存储桶 |
+| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+| `expire_at` | integer | 过期时间戳（秒），`0` 表示永不过期 |
+| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
+| `used_count` | integer | 已使用次数 |
+| `created_at` | integer | 创建时间戳（毫秒） |
+
+---
+
+## storage.revoke_share_link
+
+撤销分享链接。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `share_id` | string | 是 | 待撤销的分享短码 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `revoked` | boolean | 是否成功撤销 |
+| `share_id` | string | 被撤销的分享短码 |
+
+> 链接不存在或已撤销时返回通用错误（`-32000`）。
+
+---
+
+## storage.get_by_share
+
+通过分享短码读取对象。公开分享无需额外授权；私有白名单分享需要请求者 AID 在 `allowed_aids` 内。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `share_id` | string | 是 | 分享短码 |
+
+**响应**：小对象返回 `content`；大对象返回 `download_url`。同时返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256`。
+
+---
+
+## 错误码
 
 | code | 说明 |
 |------|------|