@agentunion/fastaun-browser 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -6,6 +6,36 @@
 
 ---
 
+## 0.4.11 — 2026-06-08
+
+### 新功能
+- **Storage 目录树与扩展操作**：`storage.*` 新增 15 个存储操作方法（含 `create_folder`/`rename_folder`/`move_object`/`batch_delete` 等），加入签名集合和非幂等集合（四语言+服务端对齐）
+- **group.resources 树形资源系统**：新增 11 个资源管理方法，加入签名和非幂等集合；支持跨域访问票据（四语言+服务端对齐）
+- **group.changed 事件保序去重**：新增 `handleGroupChangedEventSeq` 支持 event_seq 追踪和有序消息队列，空洞先到时缓存补洞；新增 `_isEventSignatureVerified()` 区分 pending 不标记已验签（四语言对齐）
+- **V2 E2EE 注册并发保护**：SPK 注册改用 `_registeringPromise` 缓存并发请求，多并发调用时等待同一 Promise（四语言对齐）
+
+### 修复
+- **IndexedDB 事务原子性**：`addSPK` 改用单事务处理原始记录和别名，避免独立事务导致一致性问题
+- **SPK 销毁顺序**：`_doAutoDestroy` 中先删设备级密钥再删存储级密钥
+- **sdk_version 拼写**：`sdk_vesion` → `sdk_version`
+- **V2 并发冲突检测**：检查对端操作的 `inflightSet`，防止 SPK 注册与轮换并发冲突
+- **storage/group.resources 签名和幂等性补全**：补全写操作方法进入签名集合与非幂等集合（四语言对齐）
+
+### 优化
+- **群事件处理流程重构**：`group.changed` 事件分发逻辑从 `client.ts` 迁移到 `delivery.ts`，支持按 event_seq 保序发布；新增 `publishOrderedQueueItem()` / `publishOrderedGroupChanged()`
+- **群组解散清理**：解散事件处理改为异步 `drainOrderedMessages`，保证 seq 追踪一致性
+- **群事件自动 ack**：`handleGroupChangedEventSeq` 无需补洞时直接 ack event cursor
+- **错误日志补充**：V2Session SPK 销毁异常捕获并输出日志
+
+### 测试
+- 新增事件验签状态单元测试（pending 状态不标记已验签）
+- 新增消息乱序补洞保序测试（高序号 push 先到时 SDK 内部消费和应用层发布的保序去重）
+- 新增签名方法覆盖测试（storage 写操作和有副作用读操作进入非幂等集合）
+- 新增 RPC 管道非幂等超时测试（storage/resources 方法按非幂等长超时 35s 发送）
+- 修复 `handleGroupChangedEventSeq` 单元测试 async/await 标记和 ack cursor 验证
+
+---
+
 ## 0.4.10 — 2026-06-06
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,36 @@
 
 ---
 
+## 0.4.11 — 2026-06-08
+
+### 新功能
+- **Storage 目录树与扩展操作**：`storage.*` 新增 15 个存储操作方法（含 `create_folder`/`rename_folder`/`move_object`/`batch_delete` 等），加入签名集合和非幂等集合（四语言+服务端对齐）
+- **group.resources 树形资源系统**：新增 11 个资源管理方法，加入签名和非幂等集合；支持跨域访问票据（四语言+服务端对齐）
+- **group.changed 事件保序去重**：新增 `handleGroupChangedEventSeq` 支持 event_seq 追踪和有序消息队列，空洞先到时缓存补洞；新增 `_isEventSignatureVerified()` 区分 pending 不标记已验签（四语言对齐）
+- **V2 E2EE 注册并发保护**：SPK 注册改用 `_registeringPromise` 缓存并发请求，多并发调用时等待同一 Promise（四语言对齐）
+
+### 修复
+- **IndexedDB 事务原子性**：`addSPK` 改用单事务处理原始记录和别名，避免独立事务导致一致性问题
+- **SPK 销毁顺序**：`_doAutoDestroy` 中先删设备级密钥再删存储级密钥
+- **sdk_version 拼写**：`sdk_vesion` → `sdk_version`
+- **V2 并发冲突检测**：检查对端操作的 `inflightSet`，防止 SPK 注册与轮换并发冲突
+- **storage/group.resources 签名和幂等性补全**：补全写操作方法进入签名集合与非幂等集合（四语言对齐）
+
+### 优化
+- **群事件处理流程重构**：`group.changed` 事件分发逻辑从 `client.ts` 迁移到 `delivery.ts`，支持按 event_seq 保序发布；新增 `publishOrderedQueueItem()` / `publishOrderedGroupChanged()`
+- **群组解散清理**：解散事件处理改为异步 `drainOrderedMessages`，保证 seq 追踪一致性
+- **群事件自动 ack**：`handleGroupChangedEventSeq` 无需补洞时直接 ack event cursor
+- **错误日志补充**：V2Session SPK 销毁异常捕获并输出日志
+
+### 测试
+- 新增事件验签状态单元测试（pending 状态不标记已验签）
+- 新增消息乱序补洞保序测试（高序号 push 先到时 SDK 内部消费和应用层发布的保序去重）
+- 新增签名方法覆盖测试（storage 写操作和有副作用读操作进入非幂等集合）
+- 新增 RPC 管道非幂等超时测试（storage/resources 方法按非幂等长超时 35s 发送）
+- 修复 `handleGroupChangedEventSeq` 单元测试 async/await 标记和 ack cursor 验证
+
+---
+
 ## 0.4.10 — 2026-06-06
 
 ### 新功能

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

@@ -409,8 +409,8 @@ sub.unsubscribe()
 | 领域 | 手册 | 关键方法 |
 |------|------|----------|
 | 消息 | [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.invite` / `group.send` / `group.v2.*` |
-| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.upload` / `storage.download` / `storage.share` |
+| 群组 | [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` |
 | 元信息 | [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` |

package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -13,13 +13,13 @@ AUNError
 │   └── IdentityConflictError
 ├── PermissionError
 ├── ValidationError
+│   └── ClientSignatureError
 ├── NotFoundError
 ├── RateLimitError
 ├── VersionConflictError
 ├── StateError
 ├── SerializationError
 ├── SessionError
-├── ClientSignatureError
 ├── GroupError
 └── E2EEError
 ```
@@ -55,17 +55,20 @@ except AUNError as e:
 | 4040 / 404 | 资源不存在 | `NotFoundError` |
 | 4290 / 429 | 请求限流 | `RateLimitError` |
 | -32001 / -32003 | 认证失败 | `AuthError` |
-| -32004 | 权限不足 | `PermissionError` |
+| -32004 | RPC handler 超时（消息以 `"rpc handler timeout"` 开头） | `TimeoutError` |
+| -32004 | 权限不足（其他情况） | `PermissionError` |
 | -32008 | 资源不存在 | `NotFoundError` |
 | -32009 | 版本冲突 | `VersionConflictError` |
 | -32010 / -32011 / -32013 | 会话错误 | `SessionError` |
+| -32051 | 客户端签名验证失败 | `ClientSignatureError`（继承自 `ValidationError`） |
 | -32029 | 请求限流 | `RateLimitError` |
 | -32600 / -32601 / -32602 | JSON-RPC 参数错误 | `ValidationError` |
 | -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
 | 4090 | 身份冲突 | `IdentityConflictError` |
 | -32050 | 证书已吊销 | `CertificateRevokedError` |
-| -32051 | 客户端签名验证失败 | `ClientSignatureError` |
-| -33001 ~ -33009 | 群组错误 | `GroupError` 子类 |
+| -33001 | 群组不存在 | `GroupNotFoundError` |
+| -33002 / -33003 | 群组状态错误 | `GroupStateError` |
+| -33004 ~ -33009 | 其他群组错误 | `GroupError` 子类 |
 
 ---
 

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

@@ -121,6 +121,16 @@
 | 方法 | 说明 |
 |------|------|
 | [group.resources.put](#groupresourcesput) | 分享资源 |
+| [group.resources.create_folder](#groupresourcescreate_folder) | 创建资源目录 |
+| [group.resources.list_children](#groupresourceslist_children) | 列出目录子节点 |
+| [group.resources.rename](#groupresourcesrename) | 重命名资源节点 |
+| [group.resources.move](#groupresourcesmove) | 移动资源节点 |
+| [group.resources.mount_object](#groupresourcesmount_object) | 挂载 storage 对象为资源 |
+| [group.resources.request_mount_object](#groupresourcesrequest_mount_object) | 申请挂载 storage 对象 |
+| [group.resources.unmount](#groupresourcesunmount) | 取消挂载资源 |
+| [group.resources.resolve_path](#groupresourcesresolve_path) | 按路径解析资源 |
+| [group.resources.list_refs_by_storage](#groupresourceslist_refs_by_storage) | 按 storage 引用反查资源 |
+| [group.resources.cleanup_by_storage_ref](#groupresourcescleanup_by_storage_ref) | 清理失效 storage 引用 |
 | [group.resources.get](#groupresourcesget) | 查看资源 |
 | [group.resources.list](#groupresourceslist) | 列出资源 |
 | [group.resources.update](#groupresourcesupdate) | 更新资源元数据 |
@@ -1358,6 +1368,122 @@ result = await client.call("group.thought.get", {
 
 > `created` 为 `true` 表示新建，`false` 表示更新已有资源。
 
+### group.resources.create_folder
+
+创建群资源目录。需要 **member 及以上**权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `path` / `resource_path` | string | 否 | 完整目录路径 |
+| `name` | string | 否 | 目录名；未提供完整路径时使用 |
+| `parent_resource_id` / `parent_path` | string | 否 | 父目录 |
+| `title` | string | 否 | 显示标题，默认目录名 |
+| `metadata` | object | 否 | 自定义元数据 |
+| `visibility` | string | 否 | `"members_only"` / `"public"` |
+| `tags` | array | 否 | 标签 |
+| `mkdirs` | boolean | 否 | 是否递归创建父目录 |
+| `sort_order` | integer | 否 | 排序值 |
+
+**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
+
+### group.resources.list_children
+
+列出某个资源目录下的直接子节点。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `resource_id` / `path` / `resource_path` | string | 否 | 父目录；不传表示根目录 |
+| `type` / `resource_type` | string | 否 | `"folder"` / `"file"` / `"link"` |
+| `include_status` | boolean | 否 | 是否附带 storage 状态 |
+| `page` / `offset` | integer | 否 | 分页位置 |
+| `size` / `limit` | integer | 否 | 每页数量 |
+| `sort_by` | string | 否 | 排序字段，默认 `sort_order` |
+| `order` | string | 否 | `"asc"` / `"desc"` |
+
+**响应**：`group_id`、`resource_id`、`path`、`items`、`total`、`count`、`page`、`size`、`offset`。
+
+### group.resources.rename
+
+重命名资源节点。需要资源创建者、storage owner、owner 或 admin 权限。
+
+**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`），`new_name`；可选 `title`、`expected_version`。
+
+**响应**：更新后的 `resource`。
+
+### group.resources.move
+
+移动资源节点。目录不能移动到自身或自身子目录。
+
+**参数**：`group_id`，资源选择器，目标父目录（`dst_parent_resource_id` / `dst_parent_path`），可选 `new_name` / `dst_name`、`expected_version`。
+
+**响应**：更新后的 `resource`。
+
+### group.resources.mount_object
+
+将 `storage.*` 对象挂载为群资源。需要 **owner/admin** 权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `storage_ref` | object | 是 | storage 引用，通常包含 `owner_aid`、`bucket`、`object_id` 或 `object_key` |
+| `path` / `resource_path` | string | 否 | 资源路径；不传时用 storage 文件名 |
+| `title` | string | 否 | 显示标题 |
+| `metadata` | object | 否 | 自定义元数据 |
+| `visibility` | string | 否 | `"members_only"` / `"public"` |
+| `tags` | array | 否 | 标签 |
+| `mkdirs` | boolean | 否 | 是否递归创建父目录，默认 `true` |
+| `conflict_policy` | string | 否 | `"reject"` / `"replace"` / `"keep_both"` |
+
+**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
+
+### group.resources.request_mount_object
+
+成员申请挂载自己的 storage 对象，进入待审批队列。语义等同 `group.resources.request_add`，但输入按挂载对象组织。
+
+**参数**：同 `group.resources.mount_object`，但不需要 owner/admin 权限。
+
+**响应**：`{ "group_id": "...", "request": { ... } }`。
+
+### group.resources.unmount
+
+取消挂载资源，等价于非递归 `group.resources.delete`。
+
+**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`）。
+
+**响应**：删除结果。
+
+### group.resources.resolve_path
+
+按路径解析资源节点。
+
+**参数**：`group_id`、`path` / `resource_path`；可选 `expected_type`。
+
+**响应**：`resource_id`、`resource_type`、`resource_path`、`path`、`status`、`resource`。
+
+### group.resources.list_refs_by_storage
+
+按 storage 引用反查群资源。传 `group_id` 时要求调用者是该群成员；不传 `group_id` 时要求调用者是 `owner_aid`。
+
+**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`include_missing`、`offset`、`limit` / `size`。
+
+**响应**：`items`、`total`、`count`、`limit`、`offset`，并回显 storage 选择器字段。
+
+### group.resources.cleanup_by_storage_ref
+
+清理指向已删除或失效 storage 对象的资源引用。传 `group_id` 时要求 owner/admin 或 storage owner；不传 `group_id` 时要求 storage owner。
+
+**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`mode`。
+
+**响应**：`affected_count` 和被影响的资源 `items`。
+
 ### group.resources.get
 
 查看资源详情。
@@ -1485,7 +1611,7 @@ result = await client.call("group.thought.get", {
 
 ### group.resources.direct_add
 
-Owner 直接添加资源（无需审批）。需要 **owner** 权限。
+Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限。
 
 **参数**：同 `group.resources.put`（`resource_type` 不能是 `"folder"`）。
 
@@ -1835,7 +1961,8 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 {
     "module_id": "group",
     "action": "member_added",
-    "group_id": "g-abc123.agentid.pub"
+    "group_id": "g-abc123.agentid.pub",
+    "event_seq": 42
 }
 ```
 
@@ -1844,9 +1971,21 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 | `module_id` | string | 固定 `"group"` |
 | `action` | string | 变更类型（见下表） |
 | `group_id` | string | 群组 ID |
+| `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
 | `request_id` | string | 可选，仅资源审批相关 action |
 | `resource_path` | string | 可选，仅资源相关 action |
 
+**保序去重（SDK 内部行为）**：
+
+服务端为每条 `group.changed` 事件分配 `event_seq`（按群 `group_event:{group_id}` 命名空间单调递增）。SDK 收到事件后：
+
+1. **去重**：`event_seq` ≤ 已连续消费序号，或已处理过该序号，则丢弃
+2. **保序**：事件入有序队列，按序号连续后才发布给应用层
+3. **补洞**：检测到序号空洞时，自动调用 `group.pull_events` 拉取缺失事件补齐
+4. **ack**：连续段推进后自动发送 `group.ack_events`（namespace `group_event:{group_id}`）
+
+不携带 `event_seq` 的旧格式事件直接发布，不参与保序（兼容旧服务端）。
+
 **action 取值**：
 
 | action | 说明 |

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

@@ -12,13 +12,37 @@
 | [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) | 确认上传完成 |
@@ -28,9 +52,10 @@
 
 | 方法 | 说明 |
 |------|------|
-| [storage.create_share_link](#storagecreate_share_link) | 创建分享链接 |
-| [storage.list_share_links](#storagelist_share_links) | 列举分享链接 |
-| [storage.revoke_share_link](#storagerevoke_share_link) | 撤销分享链接 |
+| [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) | 通过分享短码读取对象 |
 
 ---
 
@@ -256,9 +281,9 @@ for obj in result["items"]:
 
 ---
 
-## storage.get_quota
-
-查询存储配额。
+## storage.get_quota
+
+查询存储配额。
 
 ### 参数
 
@@ -273,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。
 
 ### 参数
 
@@ -578,9 +783,9 @@ share_url = result["aid_share_url"]
 
 ---
 
-## storage.revoke_share_link
-
-撤销分享链接。
+## storage.revoke_share_link
+
+撤销分享链接。
 
 ### 参数
 
@@ -595,11 +800,25 @@ share_url = result["aid_share_url"]
 | `revoked` | boolean | 是否成功撤销 |
 | `share_id` | string | 被撤销的分享短码 |
 
-> 链接不存在或已撤销时返回通用错误（`-32000`）。
-
----
-
-## 错误码
+> 链接不存在或已撤销时返回通用错误（`-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 | 说明 |
 |------|------|