@agentunion/fastaun 0.5.33 → 0.5.34

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

@@ -1,1659 +1,1698 @@
-# 存储 — RPC Manual
-
-## 方法索引
-
-### 控制面方法
-
-| 方法 | 说明 |
-|------|------|
-| [storage.put_object](#storageput_object) | Inline 写入小对象 |
-| [storage.get_object](#storageget_object) | Inline 读取小对象 |
-| [storage.head_object](#storagehead_object) | 查询元数据 |
-| [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.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) | 通过分享短码读取对象 |
-
-### POSIX VFS 方法
-
-> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/lstat/mkdir/touch/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
-
-| 方法 | 说明 |
-|------|------|
-| [storage.fs.list](#storagefslist) | 列目录（ls） |
-| [storage.fs.find](#storagefsfind) | 递归查找（find，支持 name/type/size/mtime 过滤） |
-| [storage.fs.df](#storagefsdf) | 配额/用量报告（df） |
-| [storage.fs.stat](#storagefsstat) | 查节点（stat，跟随末级软链） |
-| [storage.fs.lstat](#storagefslstat) | 查节点（lstat，不跟随软链） |
-| [storage.fs.mkdir](#storagefsmkdir) | 建目录（mkdir） |
-| [storage.fs.touch](#storagefstouch) | 创建空文件或更新时间戳（touch） |
-| [storage.fs.remove](#storagefsremove) | 删除文件/目录/软链（rm） |
-| [storage.fs.rename](#storagefsrename) | 同 owner 内移动/改名（mv） |
-| [storage.fs.copy](#storagefscopy) | 复制对象或软链（cp） |
-| [storage.fs.mount](#storagefsmount) | 挂载卷或他人子树 |
-| [storage.fs.approve](#storagefsapprove) | 源 owner 批准待审挂载 |
-| [storage.fs.reject](#storagefsreject) | 拒绝待审挂载 |
-| [storage.fs.unmount](#storagefsunmount) | 卸载挂载点 |
-| [storage.fs.invalidate_membership](#storagefsinvalidate_membership) | 群成员变更时失效群挂载 |
-
-### 软链方法
-
-| 方法 | 说明 |
-|------|------|
-| [storage.create_symlink](#storagecreate_symlink) | 创建软链 |
-| [storage.readlink](#storagereadlink) | 读软链 target |
-| [storage.atomic_repoint](#storageatomic_repoint) | 原子重指 target（CAS 乐观锁） |
-| [storage.rename_symlink](#storagerename_symlink) | 改软链 key（target 不变） |
-| [storage.delete_symlink](#storagedelete_symlink) | 删软链记录（不动 target） |
-
-### ACL / 权限方法
-
-> 统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。
->
-> `storage.set_acl` 授予路径前缀权限：`w` 写、`x` 删、`r` 读。`r` 用于 authoritative 读取和受信挂载读取；普通个人私有对象下载请使用 `storage.create_share_link`，以 `allowed_aids` 指定接收 AID。群角色 ACL 使用 `group.fs.set_acl/remove_acl`。
-
-| 方法 | 说明 |
-|------|------|
-| [storage.set_acl](#storageset_acl) | 授予路径前缀 ACL |
-| [storage.remove_acl](#storageremove_acl) | 移除 ACL 授权 |
-| [storage.list_acl](#storagelist_acl) | 列出路径 ACL |
-| [storage.set_visibility](#storageset_visibility) | 切换公开/私有 |
-| [storage.check_access](#storagecheck_access) | 非抛错的访问探测 |
-| [storage.issue_token](#storageissue_token) | 签发路径访问 token |
-| [storage.revoke_token](#storagerevoke_token) | 吊销 token |
-| [storage.list_tokens](#storagelist_tokens) | 列出 token |
-
-### 卷方法
-
-| 方法 | 说明 |
-|------|------|
-| [storage.volume.create](#storagevolumecreate) | 创建/upsert 配额卷 |
-| [storage.volume.renew](#storagevolumerenew) | 续期卷 |
-| [storage.volume.expire_due](#storagevolumeexpire_due) | 过期到期卷并失效其挂载 |
-
----
-
-> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
-
-## SDK 封装状态
-
-Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`。Python / Go / TypeScript 的 `download_file` / `downloadFile` 从下载票据及 HTTP GET 路径读取并写入本地文件；JavaScript 的 `downloadFile` 复用字节读取路径并返回正文数据。`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
-
-四个 SDK 的 VFS 会优先按实际字节识别 PNG、JPEG、GIF、BMP、WebP、PDF、gzip、ZIP、MP4、JSON、HTML 和 UTF-8 文本，再回退文件扩展名及 `application/octet-stream`。大文件上传时，`create_upload_session`、HTTP PUT 和 `complete_upload` 使用同一个 `Content-Type`；如果 session 响应额外提供 `headers`，SDK 会保留其它 header 并以实际识别结果替换其中的 Content-Type。OSS 预签名 PUT 会把 Content-Type 纳入签名校验，缺失或不一致时可直接返回 403。
-
-直接调用底层 RPC 的高级客户端必须自行完成相同编排：先确定内容类型，再把同一个值传给 session 和 complete，并在 PUT 请求中发送一致的 `Content-Type`。绕过 VFS 后未遵守该约束属于调用方式错误。
-
-## SDK 默认读缓存
-
-从 0.5.22 起，四个 SDK 的 Storage 和 Group FS 读缓存由客户端默认启用，服务端无需逐个对象显式授权缓存。已接入缓存的元数据查询（如 `head_object`、目录列表、`fs.stat/lstat/find/df`）与完整小正文读取适用下表；不是任意 RPC 或大文件下载都缓存。
-
-| 响应策略 | SDK 行为 |
-|----------|----------|
-| 不返回 `read_cache`，或值为 `null` | 元数据默认 TTL 60 秒；正文实际大小不超过 65,536 字节、SHA-256 合法且校验通过时，默认缓存正文 |
-| `read_cache.reusable: false` | 此响应不进入可复用读缓存，用于显式禁止特定文件缓存 |
-| 显式允许策略 | 元数据须 `reusable: true`，正文还须 `inline: true`；省略 `max_age_ms` 时默认 60 秒，有限正数 TTL 最多使用 60 秒 |
-
-`read_cache` 是读取响应中的策略对象，不是应用写入文件时的通用选项。缺省策略的 64 KiB 上限使用实际正文长度；元数据可独立缓存，不因文件正文较大而自动禁用。显式允许策略省略 TTL 时采用 60 秒；显式 null、非正数或非法 TTL 均不复用，不把空对象或其它显式异常值解释为缺省允许。
-
-应用可为特定读取设置 TypeScript / JavaScript `noCache: true`、Python `no_cache=True` 或 Go 对应 VFS Options 的 `NoCache: true`。TS/JS 的底层 RPC 和 Group FS 也兼容 `no_cache`，TypeScript Storage VFS 的类型化选项使用 `noCache`。SDK 消费该选项并跳过有效缓存命中，仍可发送已有 SHA-256 进行条件校验；它不表示 no-store，新结果仍按响应策略缓存。对于支持 `consistency` 的底层 RPC，`consistency: "authoritative"` 则完全旁路 SDK 读缓存，规则见下节。
-
-正文过期或显式刷新时，SDK 可带 `if_sha256`；服务端返回 `not_modified: true` 时只复用已有且已验证的正文，无本地正文时不能将该响应当作空内容。缓存键隔离调用身份及业务参数；写入和相关变更使缓存失效，重新鉴权仍由联网读取执行。范围读取和直接调用预签 RPC 不使用普通正文缓存；VFS 的完整下载流程可按下文缓存已验证的 inline 大小正文。
-
-下载票据路径也可缓存已下载并校验的 inline 大小正文，TTL 最多 60 秒；Python / Go / TypeScript 的下载入口可复用对应 `get_object` 热缓存，不必先重传正文。过期后可用 SHA-256 向下载票据接口条件校验，摘要未变则直接复用本地正文；正文大于 inline 缓存上限时仍按原下载路径传输。
-
-有限次 token、ACL 和分享授权的 inline 读取只有返回正文才计次；inline 和大对象匹配 SHA 而只返回无正文 `not_modified` 均不计次，额度耗尽后仍可进行该条件验证。SDK 本地缓存命中不请求 Storage，因此不计次；HEAD 等纯元数据查询不计次。限次授权可缓存，TTL 受对象及授权有效期限制；联网验证继续检查撤销、过期、身份和权限。大对象按下载授权计次：非 `not_modified` 请求签发 URL 或授权 302 时计一次，直接复用已签发的正文下载 URL 属于同次授权；再次向 Storage 申请 URL／授权跳转按新授权计次；Storage 不代理外部 OSS 正文，不统计 OSS 实际 GET 次数。范围参数错误、正文读取失败、下载 URL／票据准备失败不扣次；`storage.get_object_url` 仅返回稳定地址，不计次，权限和额度预检保持。响应准备成功后发生网络中断，不承诺退回次数。
-
-普通文件 API 读取 `default/sub_aids/{sub_aid}/owner.md` 同样适用上述默认规则；Ownership 管理、维护和新鲜共识的权威读取继续旁路。`resolve` 的 ownership 展示快照使用自己的 TTL 和刷新选项，不能替代授权时的新鲜共识检查。
-
-### 策略字段与条件读取
-
-| 字段 | 类型 | 含义 |
-| --- | --- | --- |
-| `read_cache` | object / null，可省略 | 响应缓存策略；缺省／null 使用上表默认规则 |
-| `read_cache.reusable` | boolean | `false` 禁止复用该响应，显式允许策略使用 `true` |
-| `read_cache.inline` | boolean | 显式策略是否允许缓存完整正文；`false` 不妨碍符合条件的元数据独立缓存 |
-| `read_cache.max_age_ms` | integer，可省略 | 有效期上限，单位毫秒；显式允许策略省略时默认 60,000；正数最多使用 60,000，并受对象及授权剩余有效期限制；显式 null／非正数／非法值不复用 |
-| `read_cache.max_inline_bytes` | integer | 服务端允许 inline 正文的大小上限（字节）；不表示大对象正文也可缓存 |
-| `if_sha256` | string，可选请求字段 | 本地完整正文的 64 位十六进制 SHA-256，用于条件读取，不用于范围正文 |
-| `not_modified` | boolean，可选响应字段 | 摘要未变化；仍须通过当前访问校验，响应可省略正文或下载票据 |
-
-收到 `not_modified: true` 时，无论当前响应是否允许继续缓存，SDK 都必须校验响应摘要与已有、已验证完整正文的摘要一致；无本地正文须重新请求完整对象，不能返回空内容。它不等于 HTTP 304，也不延长票据期限。`noCache`／`no_cache` 是 SDK 本地选项，不作为服务端 `get_object` 或下载票据的业务参数。四端对齐落点见 [parity 块⑦](../../python/CHANGES_FOR_PARITY.md#块⑦-storage--group-fs-默认读缓存)。
-
-### 持久化与新鲜度
-
-Node.js TypeScript、Python、Go 的索引位于 `{aunPath}/.cache/storage/index.sqlite3`，正文按摘要存于同目录 `blobs/{前2位}/{sha256}`；浏览器使用既有 `aun-keystore` IndexedDB 的 `storage_cache_index`／`storage_cache_blobs`。当前默认内存正文预算 32 MiB、持久正文预算 256 MiB，更多索引容量、淘汰及故障降级要求见 [0.5.22 移植指南](0.5.22-SDK开发与移植指南.md#61-storage--group-fs-默认读缓存)。这不是新增 JSONL 业务记录或公共配置接口。
-
-服务端 `max_age_ms` 扣除本次授权／对象解析所用元数据的已缓存年龄及解析耗时，使服务端元数据可能陈旧时间与 SDK 复用时间之和不超过 60 秒，同时受对象及授权剩余有效期限制。热命中不联网，也不续期 TTL。其它客户端写入或撤销权限可能在剩余 TTL 内仍未被本端观察，默认最多 60 秒；需要立即观察时显式刷新，权威管理／授权仍用权威入口。正文缓存不持久复用下载 URL、临时 token 或签名；票据过期后重新申请。重启恢复、原始 RPC 正文和权限查询白名单的已对齐分支及定向测试范围统一列在上述 parity 节，完整联网矩阵仍须单独验收。
-
-## 权威读取与完整发布
-
-`storage.head_object/get_object` 和 `storage.fs.stat` 的 `consistency: authoritative` 绕过正负缓存，核对当前存在性、规范路径及完整正文摘要。权威结果包含 `consistency`、布尔 `exists`、请求 `owner_aid/bucket/path` 和 Unix 秒 `observed_at`；存在时返回完整对象元数据，仅 `get_object` 另含严格 Base64 的完整 `content`，head/stat 不返回正文。恢复未完成、权限错误、网络或数据库故障不能返回 `exists=false`。私有路径仍检查既有 ACL，匹配的 `r` grant 不授权普通下载票据。
-
-
-
-`default/sub_aids/{sub_aid}/owner.md` 为公开可读的 Ownership 规范路径，仅命名空间 owner 可写删；ACL、token、父目录、移动、重命名、软链、挂载或自动清理均不能给第三方绕过能力。该路径约束先于通用权限放行，关系授权以 [Ownership 2.1](../protocol/Ownership协议定义2.1.md) 的 NS 新鲜事实为准。
-
-## storage.put_object
-
-上传小对象（内容 base64 编码通过 RPC 传输）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `content` | string | 是 | base64 编码内容 |
-| `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `is_private` | boolean | 否 | 是否私有，默认 `true` |
-| `overwrite` | boolean | 否 | 是否覆盖已有对象，默认 `true` |
-| `expected_version` | integer | 否 | 乐观并发控制版本号 |
-| `expire_in_seconds` | integer | 否 | 过期时间（秒），0 表示不过期 |
-| `metadata` | object | 否 | 自定义元数据 |
-
-### 响应
-
-返回写入后的对象元数据。URL 字段收敛为 `url` 和 `logical_url`，供后续 HTTP 读取使用；私有对象仍须通过访问鉴权。SDK 需要 HTTP 下载时，使用 `storage.create_download_ticket` 响应中的地址。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/{object_key}`，经 NameService fallback 302 跳转到 storage 服务 |
-| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
-| `node_type` | string | 固定为 `"object"` |
-| `type` | string | 固定为 `"file"` |
-| `object_id` | string | 对象 ID |
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `parent_folder_id` | string | 父目录 ID |
-| `name` | string | 文件名 |
-| `path` | string | 对象路径，与 `object_key` 相同 |
-| `size_bytes` | integer | 对象大小（字节） |
-| `content_type` | string | MIME 类型 |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `etag` | string | 实体标签 |
-| `is_private` | boolean | 是否私有 |
-| `expire_at` | integer | 过期时间戳（秒），`0` 表示不过期 |
-| `created_at` | integer | 创建时间戳（毫秒） |
-| `updated_at` | integer | 更新时间戳（毫秒） |
-| `status` | string | 对象状态，通常为 `"active"` |
-| `metadata` | object | 自定义元数据，未设置时为 `{}` |
-
-### 示例
-
-```python
-import base64
-
-content = base64.b64encode(b"Hello World").decode()
-result = await client.call("storage.put_object", {
-    "object_key": "notes/hello.txt",
-    "content": content,
-    "content_type": "text/plain",
-})
-```
-
----
-
-## storage.get_object
-
-读取小对象，返回 base64 编码内容。
-
-可传 `consistency: authoritative`，结果及故障分类见 [权威读取与完整发布](#权威读取与完整发布)；权威读取只接受完整对象。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
-| `if_sha256` | string | 否 | 本地完整正文的 64 位十六进制 SHA-256；普通条件读取时使用，权威读取仍返回完整对象 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `content` | string | base64 编码内容；`not_modified: true` 时可省略 |
-| `content_type` | string | MIME 类型 |
-| `size_bytes` | integer | 对象大小（字节） |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `updated_at` | integer | 更新时间戳 |
-
-普通读取还可返回 `read_cache`（object）及 `not_modified`（boolean）；字段和本地正文复用条件见 [策略字段与条件读取](#策略字段与条件读取)。只有提供了匹配 `if_sha256` 的条件读取才可将缺少 `content` 的 `not_modified` 结果与已有正文组合，不能当作空对象。
-
-> **注意**：实现不返回 `etag`（与 put_object/head_object 不同）。
-
-### 示例
-
-```python
-result = await client.call("storage.get_object", {
-    "object_key": "notes/hello.txt",
-})
-content = base64.b64decode(result["content"])
-```
-
----
-
-## storage.head_object
-
-查询对象元数据，不返回内容。
-
-可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回权威对象元数据 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `content_type` | string | MIME 类型 |
-| `size_bytes` | integer | 对象大小（字节） |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `etag` | string | 实体标签 |
-| `is_private` | boolean | 是否私有 |
-| `expire_at` | integer | 过期时间戳（0 表示不过期） |
-| `created_at` | integer | 创建时间戳 |
-| `updated_at` | integer | 更新时间戳 |
-| `read_cache` | object | 可选缓存策略；不返回／null 时采用 SDK 默认元数据策略，见 [策略字段](#策略字段与条件读取) |
-
-HEAD 只查询元数据，不消耗 token、ACL 或分享的正文读取次数。
-
----
-
-## storage.delete_object
-
-删除对象。
-
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `expected_version` | integer | 否 | 非负 JSON 整数；指定时使用版本 CAS 删除 |
-
-省略 `expected_version` 保持既有无条件删除行为。提供 `0` 时仅匹配对象不存在并返回 `deleted: false`；提供正整数时必须存在相同版本的对象才删除。存在性不符、版本不符或检查后对象被替换导致 CAS 失败时返回 `-32009`（Version conflict），不得继续删除新版本。字符串、浮点数、布尔值及负数不是合法版本条件。收到 `-32009` 后，先权威读取当前对象及原件摘要；目标已不是本任务原件时停止删除，不得改用新版本号自动重试。请求结果未知时，先核对目标是否已删除，再决定是否重放原条件请求。
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `deleted` | boolean | 是否成功删除（`false` 表示对象不存在） |
-| `owner_aid` | string | 所有者 AID |
-| `object_key` | string | 对象路径 |
-
----
-
-## storage.list_objects
-
-列出对象。
-
-> 权限：仅允许查询自己的对象（`owner_aid` 默认为当前用户，不可指定他人的 AID）
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `prefix` | string | 否 | 路径前缀过滤 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `page` | integer | 否 | 页码，默认 1 |
-| `size` | integer | 否 | 每页条数，默认 50（最大 200） |
-| `marker` | string | 否 | 深度分页游标；传入时优先按游标分页 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `items` | array | 对象元数据列表 |
-| `total` | integer | 总条数 |
-| `page` | integer | 当前页码 |
-| `size` | integer | 每页条数 |
-| `marker` | string | 当前游标标记 |
-| `next_marker` | string | 下一页游标标记（为空表示无更多数据） |
-
-每个 item 包含：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `object_key` | string | 对象路径 |
-| `size_bytes` | integer | 对象大小（字节） |
-| `content_type` | string | MIME 类型 |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `is_private` | boolean | 是否私有 |
-| `updated_at` | integer | 更新时间戳 |
-
-### 示例
-
-```python
-result = await client.call("storage.list_objects", {
-    "prefix": "notes/",
-    "size": 20,
-})
-for obj in result["items"]:
-    print(f"{obj['object_key']} ({obj['size_bytes']} bytes)")
-```
-
----
-
-## storage.list_prefixes
-
-列出直接子目录（前缀）。
-
-> 权限：仅允许查询自己的对象（`owner_aid` 默认为当前用户，不可指定他人的 AID）
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `prefix` | string | 否 | 路径前缀过滤 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `size` | integer | 否 | 每页条数上限 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `prefixes` | string[] | 直接子目录列表 |
-| `count` | integer | 子目录数量 |
-| `size` | integer | 实际生效的每页上限 |
-
----
-
-## storage.get_quota
-
-查询存储配额。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `owner_aid` | string | 否 | 查询指定 AID 的配额（默认为当前用户，仅允许查询自己的配额） |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `owner_aid` | string | 所有者 AID |
-| `used_bytes` | integer | 已使用空间（字节） |
-| `object_count` | integer | 对象数量 |
-| `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。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `size_bytes` | integer | 否 | 声明的文件大小（字节）。当前实现允许省略，但建议传入用于客户端追踪与最终校验 |
-| `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
-| `expected_version` | integer | 否 | 乐观并发控制版本号 |
-| `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `upload_url` | string | 上传用 presigned URL |
-| `session_id` | string | 规范 agent.md/owner.md 的完整原子发布会话；普通对象不保证返回 |
-| `expire_at` | integer | URL 过期时间戳 |
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `name` | string | 对象名称 |
-| `path` | string | 对象路径 |
-| `path_url` | string | Storage path URL |
-| `url` / `download_url` | string | AID 风格对象 URL |
-| `logical_url` | string | Storage 直链 URL |
-| `content_type` | string | MIME 类型 |
-| `size_bytes` | integer | 声明的文件大小 |
-| `overwrite` | boolean | 是否覆盖已有对象 |
-
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通对象不保证返回 `session_id`；规范 agent.md/owner.md 会话另返回 `session_id`，complete 必须沿用同一会话。
-
-规范 `default/agent.md` 与 `default/sub_aids/{sub_aid}/owner.md` 的上传会话使用独立临时对象，`create_upload_session` 返回 `session_id`；新客户端完成这些规范文件时必须携带同一 `session_id`。服务端核对会话的认证申请者、目标及有效期，验证完整内容后原子发布，失败保留旧完整文件。普通对象保持既有上传流程，不保证返回 `session_id`；该临时会话不记录 Ownership 关系事实或路径历史。
-
-> 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
-
-> 当前实现会在 `create_upload_session` 阶段按声明的 `size_bytes` 校验最大文件限制；实际 blob 大小、SHA-256 和配额在 `storage.complete_upload` 阶段校验。
-
----
-
-## storage.complete_upload
-
-完成上传，提交校验信息。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 条件 | 对象路径；提供 `session_id` 时可省略，若提供则必须与原会话目标一致 |
-| `session_id` | string | 否 | 规范 agent.md/owner.md 新上传必须沿用 create_upload_session 返回的同一会话 |
-| `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`，且当前 owner 已拥有相同内容 |
-| `expected_version` | integer | 否 | 普通模式的乐观并发控制版本号；会话模式沿用 `create_upload_session` 保存的原值（包括未设置），本次传入值不生效 |
-| `expire_in_seconds` | integer | 否 | 过期时间（秒） |
-| `metadata` | object | 否 | 自定义元数据 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/{object_key}`，经 NameService fallback 302 跳转 |
-| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，无跳转 |
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `size_bytes` | integer | 对象大小（字节） |
-| `content_type` | string | MIME 类型 |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `etag` | string | 实体标签 |
-| `updated_at` | integer | 更新时间戳 |
-
----
-
-## storage.create_download_ticket
-
-获取对象下载 URL。私有对象要分享给指定 AID 时，使用 `storage.create_share_link` 并设置 `allowed_aids`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `object_key` | string | 是 | 对象路径 |
-| `bucket` | string | 否 | 存储桶，默认 `"default"` |
-| `owner_aid` | string | 否 | 所有者 AID，默认当前用户（公开对象可指定其他 AID） |
-| `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
-
-支持可选 `if_sha256`（string，64 位十六进制摘要）；摘要匹配时可返回 `not_modified: true`、对象元数据及 `read_cache`，不签发新的 URL／token。调用方须持有匹配且已验证的正文，否则重新请求完整下载票据。权威对象存在性与完整原件校验使用 `storage.head_object/get_object` 或 `storage.fs.stat` 的权威入口。
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `url` | string | **AID 风格 URL（默认/推荐）**：public 文件为 `https://{owner_aid}/{object_key}`，private 文件为 `https://{owner_aid}/{object_key}?t={token}`。经 NameService fallback 302 跳转到 storage 服务，storage 实时鉴权后出文件（302 到 blob 后端，对客户端透明） |
-| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无 NameService 跳转 |
-| `download_url` | string | 同 `url`（兼容旧客户端，格式已统一） |
-| `expire_at` | integer | token 过期时间戳（Unix 秒），public 文件此字段无实际约束 |
-| `token` | string | private 文件的不透明访问 token（10 位 Base62），public 文件无此字段 |
-| `file_name` | string | 文件名（从 object_key 提取） |
-| `size_bytes` | integer | 文件大小（字节） |
-| `content_type` | string | MIME 类型 |
-| `sha256` | string | SHA-256 哈希 |
-| `version` | integer | 版本号 |
-| `etag` | string | 实体标签 |
-
-`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
-
-普通票据响应还可带 `read_cache`。该策略供 SDK 判断下载后正文是否可缓存，票据 URL、token、headers 及 `expire_at` 不因此成为可长期复用的正文缓存；条件未变化响应的处理见 [策略字段与条件读取](#策略字段与条件读取)。
-
-### 数据面 HTTP 下载流程
-
-1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
-2. 优先使用返回的 `url` / `download_url`，完整保留查询参数。URL 已包含 `?t=` 时，该值就是资源域签发的能力凭据，按原样请求即可，不要替换为 AID access token。
-3. 只有目标端点明确要求 `Authorization: Bearer <AID JWT>` 时，才在发起请求前读取当前 token：Python 使用 `get_access_token()`，TypeScript / JavaScript 使用 `getAccessToken()`，Go 使用 `GetAccessToken()`。不得长期保存 `authenticate()` 首次返回的 token，也不得跨多次请求缓存 getter 的返回值。
-4. getter 只读后台刷新任务维护的缓存，不主动刷新。返回空值时先完成身份加载和认证/连接，不发送空 Bearer。跨 issuer 下载必须使用资源所在域签发的 `?t=` 票据，不能把调用方所在域的 AID JWT 发给远端 storage。
-5. Bearer 请求收到 401/403 时，重新读取一次 getter；仅当 token 已变化时最多重试一次。token 未变化时保留真实鉴权/授权错误，不得无限重试。票据过期则重新调用 `create_download_ticket`，不能靠刷新 AID token 延长票据。
-6. 跟随 302 时不得把 AID Bearer 转发到不同 origin 的 blob backend；下载完成后校验 `size_bytes` / `sha256`。
-
-SDK Storage VFS 会编排 ticket、HTTP GET 和完整性校验。应用只有在绕过 VFS、自行执行 HTTP 请求时，才需要直接处理上述凭据生命周期。
-
----
-
-## 事件
-
-### event/storage.object_changed
-
-对象变更时推送。
-
-**Payload**：
-
-```json
-{
-    "module_id": "storage",
-    "action": "put",
-    "owner_aid": "alice.agentid.pub",
-    "object_key": "notes/hello.txt"
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `module_id` | string | 当前模块 ID，通常为 `"storage"` |
-| `action` | string | `"put"` 或 `"delete"` |
-| `owner_aid` | string | 对象所有者 AID |
-| `object_key` | string | 对象路径 |
-
-> 当前实现在 `storage.put_object` 成功后推送 `action="put"`，`storage.delete_object` 返回 `deleted=true` 时推送 `action="delete"`，`storage.complete_upload` 成功后也会推送 `action="put"` 事件。
-
----
-
-## 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
-
-上传预检：一次调用同时回答"文件是否超限"和"当前 owner 是否可秒传"。客户端应在计算完文件 SHA-256 后、实际上传前调用。
-
-> `check_upload` / `complete_upload(skip_blob=true)` 只允许复用当前 owner 已拥有的内容，避免跨 owner 暴露全局 CAS 存在性或跳过上传克隆他人私有内容。不同 owner 上传相同内容时，仍会在完成上传后归一到同一个 CAS blob，由服务端引用计数管理物理去重。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `sha256` | string | 是 | 文件内容的 SHA-256 hex（64 字符） |
-| `size_bytes` | integer | 是 | 文件大小（字节） |
-| `owner_aid` | string | 否 | 检查指定 owner 是否可秒传，默认当前用户；必须等于当前登录 AID |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `within_limit` | boolean | 文件大小是否在限制内 |
-| `exists` | boolean | 当前 owner 是否已拥有相同内容且 CAS blob 可用 |
-| `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"]:
-    # 秒传：当前 owner 已拥有相同内容，跳过上传直接 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),
-    })
-```
-
----
-
-## 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 分享短码 |
-| `url` | string | 默认分享 URL：`https://{owner_aid}/s/{share_id}`，经 NameService 跳转 |
-| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}`，直接访问 Storage 服务 |
-| `expire_at` | integer | 分享链接过期时间戳（Unix 秒），`0` 表示永不过期 |
-| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
-| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
-| `target` | object | 被分享对象的元数据，不包含空 URL 字段；其中 `expire_at` 为对象过期时间 |
-
-> `url` 经 NameService 302 跳转到 `share_url`；两者都通过 `share_id` 定位到同一条分享记录鉴权。
-> 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["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
-```
-
----
-
-## storage.list_share_links
-
-列举分享链接，可按 bucket / object_key 过滤。仅返回当前用户自己创建的链接。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `bucket` | string | 否 | 按存储桶过滤 |
-| `object_key` | string | 否 | 按对象路径过滤 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `links` | array | 分享链接列表 |
-
-每个 link 包含：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `share_id` | string | 分享短码 |
-| `url` | string | 默认分享 URL（隐藏路径）：`https://{owner_aid}/s/{share_id}` |
-| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}` |
-| `object_key` | string | 被分享对象路径 |
-| `target_type` | string | 分享目标类型 |
-| `target_id` | string | 分享目标 ID |
-| `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 | 是 | 分享短码 |
-
-可选 `if_sha256`（string，64 位十六进制摘要）用于已验证完整正文的条件读取。
-
-**响应**：小对象返回 `content`；大对象返回 `download_url`，该响应不能按空 `content` 解码。共同返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256` 和可选 `read_cache`。当前访问校验通过且摘要一致时可返回 `not_modified: true` 并省略正文／URL，复用要求见 [策略字段与条件读取](#策略字段与条件读取)。有限次分享允许 SDK 复用已验证的本地正文；本地缓存命中及无正文的 `not_modified` 不消耗分享次数；inline 返回正文时计次，大对象按下载授权签发／跳转计次，见[默认读缓存](#sdk-默认读缓存)。
-
----
-
-## storage.fs.list
-
-列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 否 | `""` | 目录路径（空=根） |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `page` | integer | 否 | `1` | 页码 |
-| `size` | integer | 否 | `100` | 每页条数（受 `list_max_limit` 上限约束） |
-| `marker` | string | 否 | — | 分页游标 |
-| `token` | string | 否 | — | 访问 token |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `nodes` | array | 节点列表，每项 `{type, node_type, name, path, mode, size, mtime, owner_principal}` |
-| `items` | array | 同 `nodes`（兼容别名） |
-| `total` | integer | 总数 |
-| `page` / `size` | integer | 分页 |
-| `next_marker` | string | 下一页游标 |
-
-`type` 取值：`file` / `dir` / `symlink` / `mount`。
-
----
-
-## storage.fs.find
-
-递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 起始目录 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `name` | string | 否 | — | 名称 glob（如 `*.md`） |
-| `type` | string | 否 | — | 节点类型过滤：`f`/`d`/`l`（SDK 形参 `node_type`） |
-| `size` | string | 否 | — | 大小表达式（如 `+1M`） |
-| `mtime` | string | 否 | — | 修改时间表达式 |
-| `page` | integer | 否 | `1` | 页码 |
-| `page_size` | integer | 否 | `1000` | 每页条数 |
-| `token` | string | 否 | — | 访问 token |
-
-### 响应
-
-同 `storage.fs.list`：`{nodes, items, total, page, size, next_marker}`。
-
----
-
-## storage.fs.df
-
-配额/用量报告（POSIX `df`），含每 owner 卷（过期卷重新计算）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `owner_aid` / `bucket` | string | 所有者 / 桶 |
-| `used_bytes` | integer | 已用字节 |
-| `object_count` | integer | 对象数 |
-| `quota_bytes` | integer | 配额上限 |
-| `avail_bytes` | integer | 剩余可用 |
-| `volumes` | array | 每卷用量明细 |
-
----
-
-## storage.fs.stat
-
-查节点元数据（POSIX `stat`）。`follow_final=true`，解析末级软链 target。
-
-可传 `consistency: authoritative`；此模式使用 [权威对象结果](#权威读取与完整发布)，不是普通 fs 节点视图。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 节点路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `token` | string | 否 | — | 访问 token |
-| `consistency` | string | 否 | — | 传 `authoritative` 时返回权威对象结果 |
-
-### 响应
-
-fs 节点视图：`{type, node_type, name, path, mode, size, mtime, owner_principal, ...}`。
-
----
-
-## storage.fs.lstat
-
-查节点（POSIX `lstat`），**不跟随末级软链**——返回软链本身（携带 `dangling` 悬空标志），不返回 target。
-
-### 参数
-
-同 `storage.fs.stat`。
-
-### 响应
-
-fs 节点视图；若为软链，返回软链节点本身（含 `dangling` 标志）。
-
----
-
-## storage.fs.mkdir
-
-建目录（POSIX `mkdir`）。委托 `create_folder`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 目录路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `parents` | boolean | 否 | `false` | 递归创建父目录（类 `mkdir -p`） |
-
-### 响应
-
-fs 目录节点视图。
-
----
-
-## storage.fs.touch
-
-创建空文件或刷新已有节点的修改时间（POSIX `touch`）。已存在的文件、目录或软链会更新时间戳；不存在时默认创建 0 字节私有文件；`no_create=true` 时不存在不创建并返回 `{touched:false, created:false}`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 目标路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `parents` | boolean | 否 | `false` | 创建文件时是否递归创建父目录 |
-| `no_create` / `noCreate` | boolean | 否 | `false` | 目标不存在时不创建 |
-| `mtime` | integer | 否 | 当前时间 | Unix 秒或毫秒；小于 `10000000000` 按秒解释 |
-| `follow_symlinks` / `followSymlinks` | boolean | 否 | `false` | 目标为软链时是否跟随末级软链 |
-| `content_type` | string | 否 | `"application/octet-stream"` | 新建空文件的 MIME 类型 |
-| `metadata` | object | 否 | `{}` | 新建空文件的元数据 |
-| `expire_in_seconds` | integer | 否 | `0` | 新建空文件的过期秒数 |
-
-### 响应
-
-成功返回 fs 节点视图，并额外包含：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `touched` | boolean | 是否实际更新或创建 |
-| `created` | boolean | 是否新建了空文件 |
-
----
-
-## storage.fs.remove
-
-删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
-
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 节点路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `recursive` | boolean | 否 | `false` | 递归删除目录 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `owner_aid` / `bucket` / `path` | string | 目标 |
-| `removed_count` | integer | 删除节点数 |
-| `deleted` | boolean | 是否删除成功 |
-
----
-
-## storage.fs.rename
-
-同 owner/bucket 内移动或改名（POSIX `mv`）。**跨 owner/bucket 被拒**；按节点类型分派到 move_folder / rename_symlink / move_object。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `src` | string | 是 | — | 源路径 |
-| `dst` | string | 是 | — | 目标路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `overwrite` | boolean | 否 | `false` | 覆盖已存在目标 |
-| `expected_version` | integer | 否 | — | 乐观锁版本号 |
-
-### 响应
-
-被重命名节点的 fs 节点视图。
-
----
-
-## storage.fs.copy
-
-复制对象或软链（POSIX `cp`，目录复制暂不支持）。CAS blob 引用计数复用，支持跨 owner 对象复制。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `src` | string | 是 | — | 源路径 |
-| `dst` | string | 是 | — | 目标路径 |
-| `owner_aid` | string | 否 | 当前用户 | 源所有者 AID |
-| `bucket` | string | 否 | `"default"` | 源存储桶 |
-| `overwrite` | boolean | 否 | `false` | 覆盖已存在目标 |
-| `follow_symlinks` | boolean | 否 | `false` | 复制软链 target 而非软链本身 |
-| `dst_owner_aid` | string | 否 | 同源 | 目标所有者（SDK 形参 `dst_owner`） |
-| `dst_bucket` | string | 否 | 同源 | 目标存储桶 |
-
-### 响应
-
-被复制节点的 fs 节点视图。
-
----
-
-## storage.fs.mount
-
-挂载卷或他人子树进 owner 命名空间。`readonly` 默认 true；`require_approval=true` 时进入 pending 直到源 owner 批准。群成员卷挂载场景下，storage 通过 CA `aid_type=group` 识别群命名空间，命中 `/memberdata/` 时调 `group.check_membership` 实时校验成员身份。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `mount_path` | string | 是 | — | 挂载点路径 |
-| `owner_aid` | string | 否 | 当前用户 | 命名空间所有者 |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `volume_id` | string | 否 | — | 挂载实体卷（与 source_* 互斥） |
-| `source_aid` | string | 否 | — | 虚拟卷源 AID（与 volume_id 互斥） |
-| `source_path` | string | 否 | — | 虚拟卷源路径 |
-| `source_bucket` | string | 否 | — | 虚拟卷源存储桶 |
-| `readonly` | boolean | 否 | `true` | 只读挂载 |
-| `require_approval` | boolean | 否 | `false` | 需源 owner 批准 |
-| `expires_at` | integer | 否 | — | 挂载过期时间 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `mount` | object | 挂载视图 |
-| `status` | string | `active`（直接生效）/ `pending`（待批准） |
-
-> `status` 字段仅在直接调用 lowlevel RPC（`fs_mount`/`FSMount`/`fsMount` 原始返回）时可见。四语言 SDK 的高层 VFS 门面（`vfs.mount()`/`StorageVFS.Mount()`/`vfs.mount()`）会把响应解析为通用 NodeView，该视图不保留顶层 `status` 字段；需要判断是否 `pending` 时请改用 lowlevel 接口读取原始响应，或检查服务端在 `pending` 场景下额外写入的 `request_id`。
-
----
-
-## storage.fs.approve
-
-源 owner 批准 pending 挂载（重新校验源路径存在）。`mount_id` 或 `(owner_aid, bucket, mount_path)` 二选一定位。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `mount_id` | string | 否 | 挂载 ID（或用下方三元组定位） |
-| `owner_aid` | string | 否 | 命名空间所有者 |
-| `bucket` | string | 否 | 存储桶 |
-| `mount_path` | string | 否 | 挂载点路径 |
-
-### 响应
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `approved` | boolean | `true` |
-| `mount` | object | 挂载视图 |
-
----
-
-## storage.fs.reject
-
-源 owner 或挂载 owner 拒绝 pending 挂载。定位方式同 `fs.approve`。
-
-### 响应
-
-`{rejected: boolean, mount}`。
-
----
-
-## storage.fs.unmount
-
-卸载挂载点（仅 owner 可操作）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `mount_path` | string | 是 | — | 挂载点路径 |
-| `owner_aid` | string | 否 | 当前用户 | 命名空间所有者 |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-`{unmounted: boolean, owner_aid, bucket, path, mount_path}`。
-
----
-
-## storage.fs.invalidate_membership
-
-群成员变更/群解散时失效群挂载（仅群 owner 或内部调用者）。SDK 形参不带 owner/bucket。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `group_id` | string | 是 | — | 群组标识兼容字段，值语义为目标态 `group_aid` |
-| `group_owner_aid` | string | 是 | — | 群 owner AID |
-| `member_aid` | string | 否 | — | 成员 AID（不传=全员） |
-| `reason` | string | 否 | `"membership_changed"` | `dissolved` / `membership_changed` |
-| `status` | string | 否 | — | `inactive` / `unavailable` |
-
-### 响应
-
-`{group_id, group_aid, group_owner_aid, member_aid, reason, status, invalidated}`（`invalidated`=失效挂载数）。
-
----
-
-## storage.create_symlink
-
-创建软链。target 受限于 owner 命名空间；拒绝同名 file/dir；父路径不可含软链前缀。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 软链路径 |
-| `target` | string | 是 | — | 指向目标路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `overwrite` | boolean | 否 | `false` | 覆盖已存在软链 |
-
-### 响应
-
-软链视图（含 `dangling` 悬空标志）。
-
----
-
-## storage.readlink
-
-读软链 target（owner 校验）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 软链路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-软链视图 `{symlink, target, version, ...}`。
-
----
-
-## storage.atomic_repoint
-
-原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 软链路径 |
-| `new_target` | string | 是 | — | 新 target |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `expected_version` | integer | 否 | — | CAS 期望版本（null=跳过 CAS） |
-
-### 响应
-
-**成功**：`{ok: true, ...软链视图}`（version+1）。
-**CAS 失败**：`{ok: false, current_version, current_target}`。
-
----
-
-## storage.rename_symlink
-
-改软链 key（同 owner/bucket 内移动/改名），target 不变。跨 owner 被拒。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 原软链路径（SDK 形参 `path`/服务端 `src`） |
-| `new_path` | string | 是 | — | 新软链路径（服务端 `dst`） |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `overwrite` | boolean | 否 | `false` | 覆盖已存在 |
-| `expected_version` | integer | 否 | — | CAS 期望版本 |
-
-### 响应
-
-**成功**：`{ok: true, ...软链视图}`。
-**CAS 失败**：`{ok: false, current_version, current_path, current_target}`。
-
----
-
-## storage.delete_symlink
-
-删软链记录（不动 target 对象）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 软链路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-`{deleted: boolean, owner_aid, bucket, path, symlink_id, target}`。
-
----
-
-## storage.set_acl
-
-授予路径前缀权限，作用于该路径及子路径（最近祖先 ACL 生效）。`w` 写、`x` 删、`r` 读；`r` 可用于 authoritative 读取和受信挂载读取，不能授权普通个人私有对象直接下载。分享私有对象给指定 AID，请使用 `storage.create_share_link` 并设置 `allowed_aids`。
-
-`role:*` 伪主体只允许可信 group 内部门面写入。客户端不能直接对 `group_aid` 空间调用 `storage.set_acl` 设置 `role:admin`；群自有区角色写授权统一使用 `group.fs.set_acl`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aids` | string[] | 二选一 | — | 一个或多个被授权 AID；优先于兼容字段；`role:*` 仅限 group 内部调用 |
-| `grantee_aid` | string | 二选一 | — | 兼容旧调用的单个 AID；未提供 `grantee_aids` 时使用 |
-| `perms` | string | 是 | — | 权限位：`r` 读取、`w` 写入、`x` 删除，可组合 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `expires_at` | integer | 否 | — | 授权过期时间 |
-| `max_uses` | integer | 否 | — | 每个被授权 AID 的最大使用次数，分别计数；0 表示不限次数 |
-
-### 响应
-
-使用 `grantee_aids` 返回 `{acls: [ACL视图, ...]}`，单元素数组也返回此结构；仅使用兼容字段 `grantee_aid` 时仍返回单条 ACL 视图。每个 AID 独立保存 `max_uses` 和 `used_count`。
-
-`grantee_aids` 不能为空数组，元素不能为空；重复 AID 去重并保留首次顺序。先校验整批参数，再逐项写入；存储错误会中断，已完成项保留。
-
----
-
-## storage.remove_acl
-
-移除指定路径和 AID 的 ACL。撤销分享链接使用 `storage.revoke_share_link`；群角色 ACL 使用 `group.fs.remove_acl`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aids` | string[] | 二选一 | — | 一个或多个待撤销 AID；优先于兼容字段 |
-| `grantee_aid` | string | 二选一 | — | 兼容旧调用的单个 AID；未提供 `grantee_aids` 时使用 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-使用 `grantee_aids` 返回 `{results: [{removed: boolean, owner_aid, bucket, path, grantee_aid}, ...]}`；单元素数组也返回此结构。仅使用 `grantee_aid` 时仍返回 `{removed: boolean, owner_aid, bucket, path, grantee_aid}`。
-
-数组校验和去重规则与 `storage.set_acl` 一致；逐项撤销，存储错误会中断并保留已完成项。
-
----
-
-## storage.list_acl
-
-列出路径上的 ACL 授权（owner 校验）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-`{owner_aid, bucket, path, acls}`。
-
----
-
-## storage.set_visibility
-
-切换对象或目录的公开/私有（软链不支持）。`allow_roles` 是低层兼容字段，不能作为群自有区 admin 写授权入口；群自有区角色写授权必须使用 `group.fs.set_acl/remove_acl`。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 路径 |
-| `visibility` | string | 是 | — | `public` / `private` |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `allow_roles` | array | 否 | — | 低层兼容字段，仅表示可见性读角色；不能用于群自有区写授权 |
-
-### 响应
-
-fs 节点视图（含 `allow_roles`）。
-
----
-
-## storage.check_access
-
-非抛错的访问探测——探测某操作在某路径是否放行（内部捕获 NotFound/Dangling/Permission）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 路径（服务端别名 `object_key`） |
-| `operation` | string | 否 | `"read"` | `read` / `write` / `delete`（服务端别名 `op`） |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `token` | string | 否 | — | 访问 token |
-| `follow_symlinks` | boolean | 否 | `true` | 跟随软链 |
-
-### 响应
-
-`{allowed: boolean, reason, message, requester_aid, owner_aid, bucket, path, operation}`。
-
----
-
-## storage.issue_token
-
-签发 hash 化的 bearer 访问 token，scope 到某路径。返回的明文 token 仅此一次可见。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 授权路径（服务端别名 `object_key`） |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `expires_at` | integer | 否 | — | 过期时间 |
-| `max_reads` | integer | 否 | — | 最大读取次数（服务端别名 `max_uses`） |
-
-### 响应
-
-token 视图 + 明文 token（一次性返回）。
-
----
-
-## storage.revoke_token
-
-按明文 token 值吊销（内部 hash 后查找）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 路径（服务端别名 `object_key`） |
-| `token` | string | 是 | — | 要吊销的明文 token |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-`{revoked: boolean, owner_aid, bucket, path}`。
-
----
-
-## storage.list_tokens
-
-列出路径上的 token（owner 校验，不返回明文）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `path` | string | 是 | — | 路径 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-
-### 响应
-
-token 列表（hash 摘要 + 元数据）。
-
----
-
-## storage.volume.create
-
-创建/upsert 配额卷（含 mount_point）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `size_bytes` | integer | 是 | — | 卷容量（>0） |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `volume_id` | string | 否 | 自动 | 卷 ID |
-| `used_bytes` | integer | 否 | — | 已用字节 |
-| `status` | string | 否 | `active` | `active` / `grace` / `expired` |
-| `mount_point` | string | 否 | — | 挂载点 |
-| `expires_at` | integer | 否 | — | 过期时间 |
-
-### 响应
-
-`{volume, ...卷视图}`。
-
----
-
-## storage.volume.renew
-
-续期卷过期时间/状态（owner 校验，owner 不符抛 PermissionError）。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `volume_id` | string | 是 | — | 卷 ID（服务端别名 `id`） |
-| `expires_at` | integer | 是 | — | 新过期时间 |
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `status` | string | 否 | — | 卷状态 |
-
-### 响应
-
-`{volume, ...卷视图}`。
-
----
-
-## storage.volume.expire_due
-
-过期所有到期卷并标记其挂载为 unavailable。
-
-### 参数
-
-| 参数 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
-| `bucket` | string | 否 | `"default"` | 存储桶 |
-| `now` | integer | 否 | 当前时间 | 判定基准时间 |
-
-### 响应
-
-`{owner_aid, bucket, expired, mounts_unavailable, volumes, mounts}`。
-
-## 错误码
-
-| code | 说明 |
-|------|------|
-| -32002 | 服务暂不可用（数据库未连接） |
-| -32004 | 权限拒绝（requester 不是对象 owner，或非公开对象的读权限不足） |
-| -32008 | 对象不存在（`ErrNotFound`） |
-| -32009 | 版本冲突（`ErrVersionConflict`，`expected_version` 与实际版本不匹配） |
-| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |
+# 存储 — RPC Manual
+
+## 方法索引
+
+### 控制面方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.put_object](#storageput_object) | Inline 写入小对象 |
+| [storage.get_object](#storageget_object) | Inline 读取小对象 |
+| [storage.head_object](#storagehead_object) | 查询元数据 |
+| [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.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) | 通过分享短码读取对象 |
+
+### POSIX VFS 方法
+
+> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/lstat/mkdir/touch/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
+
+| 方法 | 说明 |
+|------|------|
+| [storage.fs.list](#storagefslist) | 列目录（ls） |
+| [storage.fs.find](#storagefsfind) | 递归查找（find，支持 name/type/size/mtime 过滤） |
+| [storage.fs.df](#storagefsdf) | 配额/用量报告（df） |
+| [storage.fs.stat](#storagefsstat) | 查节点（stat，跟随末级软链） |
+| [storage.fs.lstat](#storagefslstat) | 查节点（lstat，不跟随软链） |
+| [storage.fs.mkdir](#storagefsmkdir) | 建目录（mkdir） |
+| [storage.fs.touch](#storagefstouch) | 创建空文件或更新时间戳（touch） |
+| [storage.fs.remove](#storagefsremove) | 删除文件/目录/软链（rm） |
+| [storage.fs.rename](#storagefsrename) | 同 owner 内移动/改名（mv） |
+| [storage.fs.copy](#storagefscopy) | 复制对象或软链（cp） |
+| [storage.fs.mount](#storagefsmount) | 挂载卷或他人子树 |
+| [storage.fs.approve](#storagefsapprove) | 源 owner 批准待审挂载 |
+| [storage.fs.reject](#storagefsreject) | 拒绝待审挂载 |
+| [storage.fs.unmount](#storagefsunmount) | 卸载挂载点 |
+| [storage.fs.invalidate_membership](#storagefsinvalidate_membership) | 群成员变更时失效群挂载 |
+
+### 软链方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.create_symlink](#storagecreate_symlink) | 创建软链 |
+| [storage.readlink](#storagereadlink) | 读软链 target |
+| [storage.atomic_repoint](#storageatomic_repoint) | 原子重指 target（CAS 乐观锁） |
+| [storage.rename_symlink](#storagerename_symlink) | 改软链 key（target 不变） |
+| [storage.delete_symlink](#storagedelete_symlink) | 删软链记录（不动 target） |
+
+### ACL / 权限方法
+
+> 统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。
+>
+> `storage.set_acl` 授予路径前缀权限：`w` 写、`x` 删、`r` 读。具体 AID 的 `r` 用于 authoritative 读取和受信挂载读取；`subject` 条件 ACL 还支持匹配者读取普通私有对象。向指定 AID 分享普通私有对象仍使用 `storage.create_share_link` 的 `allowed_aids`。群角色 ACL 使用 `group.fs.set_acl/remove_acl`。
+
+| 方法 | 说明 |
+|------|------|
+| [storage.set_acl](#storageset_acl) | 授予路径前缀 ACL |
+| [storage.remove_acl](#storageremove_acl) | 移除 ACL 授权 |
+| [storage.list_acl](#storagelist_acl) | 列出路径 ACL |
+| [storage.set_visibility](#storageset_visibility) | 切换公开/私有 |
+| [storage.check_access](#storagecheck_access) | 非抛错的访问探测 |
+| [storage.issue_token](#storageissue_token) | 签发路径访问 token |
+| [storage.revoke_token](#storagerevoke_token) | 吊销 token |
+| [storage.list_tokens](#storagelist_tokens) | 列出 token |
+
+### 卷方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.volume.create](#storagevolumecreate) | 创建/upsert 配额卷 |
+| [storage.volume.renew](#storagevolumerenew) | 续期卷 |
+| [storage.volume.expire_due](#storagevolumeexpire_due) | 过期到期卷并失效其挂载 |
+
+---
+
+> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
+
+## SDK 封装状态
+
+Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`。Python / Go / TypeScript 的 `download_file` / `downloadFile` 从下载票据及 HTTP GET 路径读取并写入本地文件；JavaScript 的 `downloadFile` 复用字节读取路径并返回正文数据。`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+
+四个 SDK 的 VFS 会优先按实际字节识别 PNG、JPEG、GIF、BMP、WebP、PDF、gzip、ZIP、MP4、JSON、HTML 和 UTF-8 文本，再回退文件扩展名及 `application/octet-stream`。大文件上传时，`create_upload_session`、HTTP PUT 和 `complete_upload` 使用同一个 `Content-Type`；如果 session 响应额外提供 `headers`，SDK 会保留其它 header 并以实际识别结果替换其中的 Content-Type。OSS 预签名 PUT 会把 Content-Type 纳入签名校验，缺失或不一致时可直接返回 403。
+
+直接调用底层 RPC 的高级客户端必须自行完成相同编排：先确定内容类型，再把同一个值传给 session 和 complete，并在 PUT 请求中发送一致的 `Content-Type`。绕过 VFS 后未遵守该约束属于调用方式错误。
+
+四端 VFS 写入会沿用本端读取的版本或显式 `expected_version`／`expectedVersion`；目标已存在但没有可用版本时返回冲突，显式 `force` 可选择覆盖。low-level 封装会对对象写入和删除执行版本预检；直接 `client.call()` 不具有这层 SDK 编排。RPC 的 `expected_version=0` 表示只允许目标不存在，正整数表示必须匹配当前版本。
+
+## SDK 默认读缓存
+
+从 0.5.22 起，四个 SDK 的 Storage 和 Group FS 读缓存由客户端默认启用，服务端无需逐个对象显式授权缓存。已接入缓存的元数据查询（如 `head_object`、目录列表、`fs.stat/lstat/find/df`）与完整小正文读取适用下表；不是任意 RPC 或大文件下载都缓存。
+
+| 响应策略 | SDK 行为 |
+|----------|----------|
+| 不返回 `read_cache`，或值为 `null` | 元数据默认 TTL 60 秒；正文实际大小不超过 65,536 字节、SHA-256 合法且校验通过时，默认缓存正文 |
+| `read_cache.reusable: false` | 此响应不进入可复用读缓存，用于显式禁止特定文件缓存 |
+| 显式允许策略 | 元数据须 `reusable: true`，正文还须 `inline: true`；省略 `max_age_ms` 时默认 60 秒，有限正数 TTL 最多使用 60 秒 |
+
+`read_cache` 是读取响应中的策略对象，不是应用写入文件时的通用选项。缺省策略的 64 KiB 上限使用实际正文长度；元数据可独立缓存，不因文件正文较大而自动禁用。显式允许策略省略 TTL 时采用 60 秒；显式 null、非正数或非法 TTL 均不复用，不把空对象或其它显式异常值解释为缺省允许。
+
+应用可为特定读取设置 TypeScript / JavaScript `noCache: true`、Python `no_cache=True` 或 Go 对应 VFS Options 的 `NoCache: true`。TS/JS 的底层 RPC 和 Group FS 也兼容 `no_cache`，TypeScript Storage VFS 的类型化选项使用 `noCache`。SDK 消费该选项并跳过有效缓存命中，仍可发送已有 SHA-256 进行条件校验；它不表示 no-store，新结果仍按响应策略缓存。对于支持 `consistency` 的底层 RPC，`consistency: "authoritative"` 则完全旁路 SDK 读缓存，规则见下节。
+
+正文过期或显式刷新时，SDK 可带 `if_sha256`；服务端返回 `not_modified: true` 时只复用已有且已验证的正文，无本地正文时不能将该响应当作空内容。缓存键隔离调用身份及业务参数；写入和相关变更使缓存失效，重新鉴权仍由联网读取执行。范围读取和直接调用预签 RPC 不使用普通正文缓存；VFS 的完整下载流程可按下文缓存已验证的 inline 大小正文。
+
+下载票据路径也可缓存已下载并校验的 inline 大小正文，TTL 最多 60 秒；Python / Go / TypeScript 的下载入口可复用对应 `get_object` 热缓存，不必先重传正文。过期后可用 SHA-256 向下载票据接口条件校验，摘要未变则直接复用本地正文；正文大于 inline 缓存上限时仍按原下载路径传输。
+
+有限次 token、ACL 和分享授权的 inline 读取只有返回正文才计次；inline 和大对象匹配 SHA 而只返回无正文 `not_modified` 均不计次，额度耗尽后仍可进行该条件验证。SDK 本地缓存命中不请求 Storage，因此不计次；HEAD 等纯元数据查询不计次。限次授权可缓存，TTL 受对象及授权有效期限制；联网验证继续检查撤销、过期、身份和权限。大对象按下载授权计次：非 `not_modified` 请求签发 URL 或授权 302 时计一次，直接复用已签发的正文下载 URL 属于同次授权；再次向 Storage 申请 URL／授权跳转按新授权计次；普通下载不代理外部 OSS 正文，不统计 OSS 实际 GET 次数；subject 条件下载由 Storage 流式代理并在每次下载时重新判权。范围参数错误、正文读取失败、下载 URL／票据准备失败不扣次；`storage.get_object_url` 仅返回稳定地址，不计次，权限和额度预检保持。响应准备成功后发生网络中断，不承诺退回次数。
+
+`subject` 条件 ACL 的响应使用 `read_cache.reusable: false`、`max_age_ms: 0`，每次联网读取核对 Owner 当前 `owner.md` 单方声明；只有限定 `card` 时才检查名片，名片使用 Storage 的 60 秒 TTL 缓存。其 `max_uses` 由整条规则共享；下载票据兑换正文时还会核对原规则、权限、当前声明及按相同缓存策略取得的名片。条件下载由 Storage 直接返回或流式代理正文，HTTP 响应使用 `Cache-Control: private, no-store`；撤销规则或声明后，后续联网读取被拒绝；名片改为不匹配最多有 60 秒缓存窗口。
+
+普通文件 API 读取 `default/sub_aids/{sub_aid}/owner.md` 同样适用上述默认规则；Ownership 管理、维护和新鲜共识的权威读取继续旁路。`resolve` 的 ownership 展示快照使用自己的 TTL 和刷新选项，不能替代条件 ACL 对当前 Owner 声明的检查。
+
+### 策略字段与条件读取
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `read_cache` | object / null，可省略 | 响应缓存策略；缺省／null 使用上表默认规则 |
+| `read_cache.reusable` | boolean | `false` 禁止复用该响应，显式允许策略使用 `true` |
+| `read_cache.inline` | boolean | 显式策略是否允许缓存完整正文；`false` 不妨碍符合条件的元数据独立缓存 |
+| `read_cache.max_age_ms` | integer，可省略 | 有效期上限，单位毫秒；显式允许策略省略时默认 60,000；正数最多使用 60,000，并受对象及授权剩余有效期限制；显式 null／非正数／非法值不复用 |
+| `read_cache.max_inline_bytes` | integer | 服务端允许 inline 正文的大小上限（字节）；不表示大对象正文也可缓存 |
+| `if_sha256` | string，可选请求字段 | 本地完整正文的 64 位十六进制 SHA-256，用于条件读取，不用于范围正文 |
+| `not_modified` | boolean，可选响应字段 | 摘要未变化；仍须通过当前访问校验，响应可省略正文或下载票据 |
+
+收到 `not_modified: true` 时，无论当前响应是否允许继续缓存，SDK 都必须校验响应摘要与已有、已验证完整正文的摘要一致；无本地正文须重新请求完整对象，不能返回空内容。它不等于 HTTP 304，也不延长票据期限。`noCache`／`no_cache` 是 SDK 本地选项，不作为服务端 `get_object` 或下载票据的业务参数。四端对齐落点见 [parity 块⑦](../../python/CHANGES_FOR_PARITY.md#块⑦-storage--group-fs-默认读缓存)。
+
+### 持久化与新鲜度
+
+Node.js TypeScript、Python、Go 的索引位于 `{aunPath}/.cache/storage/index.sqlite3`，正文按摘要存于同目录 `blobs/{前2位}/{sha256}`；浏览器使用既有 `aun-keystore` IndexedDB 的 `storage_cache_index`／`storage_cache_blobs`。当前默认内存正文预算 32 MiB、持久正文预算 256 MiB，更多索引容量、淘汰及故障降级要求见 [0.5.22 移植指南](0.5.22-SDK开发与移植指南.md#61-storage--group-fs-默认读缓存)。这不是新增 JSONL 业务记录或公共配置接口。
+
+服务端 `max_age_ms` 扣除本次授权／对象解析所用元数据的已缓存年龄及解析耗时，使服务端元数据可能陈旧时间与 SDK 复用时间之和不超过 60 秒，同时受对象及授权剩余有效期限制。热命中不联网，也不续期 TTL。其它客户端写入或撤销权限可能在剩余 TTL 内仍未被本端观察，默认最多 60 秒；需要立即观察时显式刷新，权威管理／授权仍用权威入口。正文缓存不持久复用下载 URL、临时 token 或签名；票据过期后重新申请。重启恢复、原始 RPC 正文和权限查询白名单的已对齐分支及定向测试范围统一列在上述 parity 节，完整联网矩阵仍须单独验收。
+
+## 权威读取与完整发布
+
+`storage.head_object/get_object` 和 `storage.fs.stat` 的 `consistency: authoritative` 绕过正负缓存，核对当前存在性、规范路径及完整正文摘要。权威结果包含 `consistency`、布尔 `exists`、请求 `owner_aid/bucket/path` 和 Unix 秒 `observed_at`；存在时返回完整对象元数据，仅 `get_object` 另含严格 Base64 的完整 `content`，head/stat 不返回正文。恢复未完成、权限错误、网络或数据库故障不能返回 `exists=false`。私有路径仍检查 ACL；具体 AID 的 `r` grant 不授权普通下载票据，匹配的 `subject` 条件规则可授权该读取流程。
+
+
+
+`default/sub_aids/{sub_aid}/owner.md` 为公开可读的 Ownership 规范路径，仅命名空间 owner 可写删；ACL、token、父目录、移动、重命名、软链、挂载或自动清理均不能给第三方绕过能力。该路径约束先于通用权限放行，关系授权以 [Ownership 2.1](../protocol/Ownership协议定义2.1.md) 的 NS 新鲜事实为准。
+
+## storage.put_object
+
+上传小对象（内容 base64 编码通过 RPC 传输）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `content` | string | 是 | base64 编码内容 |
+| `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `is_private` | boolean | 否 | 是否私有，默认 `true` |
+| `overwrite` | boolean | 否 | 是否覆盖已有对象，默认 `false`；提供匹配的 `expected_version` 时可更新已有对象 |
+| `force` | boolean | 否 | 覆盖开关的兼容别名，默认 `false`；不会绕过已提供的版本条件 |
+| `expected_version` | integer | 否 | 乐观并发控制版本号 |
+| `expire_in_seconds` | integer | 否 | 过期时间（秒），0 表示不过期 |
+| `metadata` | object | 否 | 自定义元数据 |
+
+### 响应
+
+返回写入后的对象元数据。URL 字段收敛为 `url` 和 `logical_url`，供后续 HTTP 读取使用；私有对象仍须通过访问鉴权。SDK 需要 HTTP 下载时，使用 `storage.create_download_ticket` 响应中的地址。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/{object_key}`，经 NameService fallback 302 跳转到 storage 服务 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
+| `node_type` | string | 固定为 `"object"` |
+| `type` | string | 固定为 `"file"` |
+| `object_id` | string | 对象 ID |
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `parent_folder_id` | string | 父目录 ID |
+| `name` | string | 文件名 |
+| `path` | string | 对象路径，与 `object_key` 相同 |
+| `size_bytes` | integer | 对象大小（字节） |
+| `content_type` | string | MIME 类型 |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `etag` | string | 实体标签 |
+| `is_private` | boolean | 是否私有 |
+| `expire_at` | integer | 过期时间戳（秒），`0` 表示不过期 |
+| `created_at` | integer | 创建时间戳（毫秒） |
+| `updated_at` | integer | 更新时间戳（毫秒） |
+| `status` | string | 对象状态，通常为 `"active"` |
+| `metadata` | object | 自定义元数据，未设置时为 `{}` |
+
+### 示例
+
+```python
+import base64
+
+content = base64.b64encode(b"Hello World").decode()
+result = await client.call("storage.put_object", {
+    "object_key": "notes/hello.txt",
+    "content": content,
+    "content_type": "text/plain",
+})
+```
+
+---
+
+## storage.get_object
+
+读取小对象，返回 base64 编码内容。
+
+可传 `consistency: authoritative`，结果及故障分类见 [权威读取与完整发布](#权威读取与完整发布)；权威读取只接受完整对象。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `if_sha256` | string | 否 | 本地完整正文的 64 位十六进制 SHA-256；普通条件读取时使用，权威读取仍返回完整对象 |
+| `token` | string | 否 | 访问 token |
+| `offset` / `limit` | integer | 否 | 字节起点与返回长度；范围读取不使用 `if_sha256`，也不能与权威读取组合 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `content` | string | base64 编码内容；`not_modified: true` 时可省略 |
+| `content_type` | string | MIME 类型 |
+| `size_bytes` | integer | 对象大小（字节） |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `updated_at` | integer | 更新时间戳 |
+
+普通读取还可返回 `read_cache`（object）及 `not_modified`（boolean）；字段和本地正文复用条件见 [策略字段与条件读取](#策略字段与条件读取)。只有提供了匹配 `if_sha256` 的条件读取才可将缺少 `content` 的 `not_modified` 结果与已有正文组合，不能当作空对象。
+
+响应包含对象的 `etag`；范围读取额外返回 `range: {offset, limit, returned_bytes, size_bytes, partial: true}`，其中对象 `size_bytes` 和 `sha256` 仍描述完整对象。
+
+### 示例
+
+```python
+result = await client.call("storage.get_object", {
+    "object_key": "notes/hello.txt",
+})
+content = base64.b64decode(result["content"])
+```
+
+---
+
+## storage.head_object
+
+查询对象元数据，不返回内容。
+
+可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回权威对象元数据 |
+| `token` | string | 否 | 访问 token |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `content_type` | string | MIME 类型 |
+| `size_bytes` | integer | 对象大小（字节） |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `etag` | string | 实体标签 |
+| `is_private` | boolean | 是否私有 |
+| `expire_at` | integer | 过期时间戳（0 表示不过期） |
+| `created_at` | integer | 创建时间戳 |
+| `updated_at` | integer | 更新时间戳 |
+| `read_cache` | object | 可选缓存策略；不返回／null 时采用 SDK 默认元数据策略，见 [策略字段](#策略字段与条件读取) |
+
+HEAD 只查询元数据，不消耗 token、ACL 或分享的正文读取次数。
+
+---
+
+## storage.delete_object
+
+删除对象。
+
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `expected_version` | integer | 否 | 非负 JSON 整数；指定时使用版本 CAS 删除 |
+
+省略 `expected_version` 保持既有无条件删除行为。提供 `0` 时仅匹配对象不存在并返回 `deleted: false`；提供正整数时必须存在相同版本的对象才删除。存在性不符、版本不符或检查后对象被替换导致 CAS 失败时返回 `-32009`（Version conflict），不得继续删除新版本。字符串、浮点数、布尔值及负数不是合法版本条件。收到 `-32009` 后，先权威读取当前对象及原件摘要；目标已不是本任务原件时停止删除，不得改用新版本号自动重试。请求结果未知时，先核对目标是否已删除，再决定是否重放原条件请求。
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `deleted` | boolean | 是否成功删除（`false` 表示对象不存在） |
+| `owner_aid` | string | 所有者 AID |
+| `object_key` | string | 对象路径 |
+
+---
+
+## storage.list_objects
+
+列出对象。
+
+> 权限：仅允许查询自己的对象（`owner_aid` 默认为当前用户，不可指定他人的 AID）
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prefix` | string | 否 | 路径前缀过滤 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `page` | integer | 否 | 页码，默认 1 |
+| `size` | integer | 否 | 每页条数，RPC 默认 50；SDK low-level 默认传 100 |
+| `marker` | string | 否 | 深度分页游标；传入时优先按游标分页 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `items` | array | 对象元数据列表 |
+| `total` | integer | 普通 SDK 调用返回本次可见条数，不是全目录精确总数 |
+| `page` | integer | 当前页码 |
+| `size` | integer | 每页条数 |
+| `marker` | string | 当前游标标记 |
+| `next_marker` | string | 下一页游标标记（为空表示无更多数据） |
+
+每个 item 包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `object_key` | string | 对象路径 |
+| `size_bytes` | integer | 对象大小（字节） |
+| `content_type` | string | MIME 类型 |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `is_private` | boolean | 是否私有 |
+| `updated_at` | integer | 更新时间戳 |
+
+### 示例
+
+```python
+result = await client.call("storage.list_objects", {
+    "prefix": "notes/",
+    "size": 20,
+})
+for obj in result["items"]:
+    print(f"{obj['object_key']} ({obj['size_bytes']} bytes)")
+```
+
+---
+
+## storage.list_prefixes
+
+列出直接子目录（前缀）。
+
+> 权限：仅允许查询自己的对象（`owner_aid` 默认为当前用户，不可指定他人的 AID）
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prefix` | string | 否 | 路径前缀过滤 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `size` | integer | 否 | 每页条数上限 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `prefixes` | string[] | 直接子目录列表 |
+| `count` | integer | 子目录数量 |
+| `size` | integer | 实际生效的每页上限 |
+
+---
+
+## storage.get_quota
+
+查询存储配额。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner_aid` | string | 否 | 查询指定 AID 的配额（默认为当前用户，仅允许查询自己的配额） |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `owner_aid` | string | 所有者 AID |
+| `used_bytes` | integer | 已使用空间（字节） |
+| `object_count` | integer | 对象数量 |
+| `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`），目标目录 `destination_parent_folder_id` 或 `dst_parent_path`（别名 `destination_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。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `size_bytes` | integer | 否 | 声明的文件大小（字节）。当前实现允许省略，但建议传入用于客户端追踪与最终校验 |
+| `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
+| `expected_version` | integer | 否 | 乐观并发控制版本号 |
+| `overwrite` / `force` | boolean | 否 | 默认 `false`；允许覆盖已有目标，提供版本条件时仍须匹配 |
+| `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `upload_url` | string | 上传用 presigned URL |
+| `session_id` | string | 本次上传会话 ID；普通对象与规范文件均返回 |
+| `expire_at` | integer | URL 过期时间戳 |
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `name` | string | 对象名称 |
+| `path` | string | 对象路径 |
+| `path_url` | string | Storage path URL |
+| `url` / `download_url` | string | AID 风格对象 URL |
+| `logical_url` | string | Storage 直链 URL |
+| `content_type` | string | MIME 类型 |
+| `size_bytes` | integer | 声明的文件大小 |
+| `overwrite` | boolean | 是否覆盖已有对象 |
+
+客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据，再把同一 `session_id` 传给 `complete_upload`。会话绑定申请者、目标、声明大小和版本条件，正文先写入独立临时对象。
+
+服务端核对会话申请者、目标及有效期，验证完整内容后发布。兼容调用省略 `session_id` 时，服务端仅在当前申请者和目标存在唯一已上传且未过期的会话时自动匹配；存在多个候选时必须显式提供。规范 `default/agent.md` 与 `default/sub_aids/{sub_aid}/owner.md` 仍执行完整原子发布，失败保留旧完整文件；上传会话不记录 Ownership 关系事实或路径历史。
+
+> 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
+
+> 当前实现会在 `create_upload_session` 阶段按声明的 `size_bytes` 校验最大文件限制；实际 blob 大小、SHA-256 和配额在 `storage.complete_upload` 阶段校验。
+
+---
+
+## storage.complete_upload
+
+完成上传，提交校验信息。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 条件 | 对象路径；提供 `session_id` 时可省略，若提供则必须与原会话目标一致 |
+| `session_id` | string | 否 | 沿用 `create_upload_session` 返回的会话；省略时仅支持上述唯一会话匹配或既有无会话路径 |
+| `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`，且当前 owner 已拥有相同内容 |
+| `expected_version` | integer | 否 | 乐观并发控制版本号；会话保存过版本条件时必须沿用，传入不同值返回冲突；原会话未设置时可在完成请求中提供 |
+| `overwrite` / `force` | boolean | 否 | 默认 `false`；与会话原有覆盖开关合并，不绕过版本条件 |
+| `expire_in_seconds` | integer | 否 | 过期时间（秒） |
+| `metadata` | object | 否 | 自定义元数据 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/{object_key}`，经 NameService fallback 302 跳转 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，无跳转 |
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `size_bytes` | integer | 对象大小（字节） |
+| `content_type` | string | MIME 类型 |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `etag` | string | 实体标签 |
+| `updated_at` | integer | 更新时间戳 |
+
+---
+
+## storage.create_download_ticket
+
+获取对象下载 URL。私有对象要分享给指定 AID 时，使用 `storage.create_share_link` 并设置 `allowed_aids`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 对象路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 所有者 AID，默认当前用户（公开对象可指定其他 AID） |
+| `expire_in_seconds` | integer | 否 | URL 有效期（秒），默认 3600 |
+
+支持可选 `if_sha256`（string，64 位十六进制摘要）；摘要匹配时可返回 `not_modified: true`、对象元数据及 `read_cache`，不签发新的 URL／token。调用方须持有匹配且已验证的正文，否则重新请求完整下载票据。权威对象存在性与完整原件校验使用 `storage.head_object/get_object` 或 `storage.fs.stat` 的权威入口。
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：public 文件为 `https://{owner_aid}/{object_key}`，private 文件为 `https://{owner_aid}/{object_key}?t={token}`。经 NameService fallback 302 跳转到 storage 服务，storage 实时鉴权后出文件（302 到 blob 后端，对客户端透明） |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无 NameService 跳转 |
+| `download_url` | string | 同 `url`（兼容旧客户端，格式已统一） |
+| `expire_at` | integer | token 过期时间戳（Unix 秒），public 文件此字段无实际约束 |
+| `token` | string | private 文件的不透明访问 token（10 位 Base62），public 文件无此字段 |
+| `file_name` | string | 文件名（从 object_key 提取） |
+| `size_bytes` | integer | 文件大小（字节） |
+| `content_type` | string | MIME 类型 |
+| `sha256` | string | SHA-256 哈希 |
+| `version` | integer | 版本号 |
+| `etag` | string | 实体标签 |
+
+`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
+
+普通票据响应还可带 `read_cache`。该策略供 SDK 判断下载后正文是否可缓存，票据 URL、token、headers 及 `expire_at` 不因此成为可长期复用的正文缓存；条件未变化响应的处理见 [策略字段与条件读取](#策略字段与条件读取)。
+
+### 数据面 HTTP 下载流程
+
+1. 通过控制面 RPC `storage.create_download_ticket` 获取短 TTL 的下载票据，不把长期对象 URL 当作最终下载地址。
+2. 优先使用返回的 `url` / `download_url`，完整保留查询参数。URL 已包含 `?t=` 时，该值就是资源域签发的能力凭据，按原样请求即可，不要替换为 AID access token。
+3. 只有目标端点明确要求 `Authorization: Bearer <AID JWT>` 时，才在发起请求前读取当前 token：Python 使用 `get_access_token()`，TypeScript / JavaScript 使用 `getAccessToken()`，Go 使用 `GetAccessToken()`。不得长期保存 `authenticate()` 首次返回的 token，也不得跨多次请求缓存 getter 的返回值。
+4. getter 只读后台刷新任务维护的缓存，不主动刷新。返回空值时先完成身份加载和认证/连接，不发送空 Bearer。跨 issuer 下载必须使用资源所在域签发的 `?t=` 票据，不能把调用方所在域的 AID JWT 发给远端 storage。
+5. Bearer 请求收到 401/403 时，重新读取一次 getter；仅当 token 已变化时最多重试一次。token 未变化时保留真实鉴权/授权错误，不得无限重试。票据过期则重新调用 `create_download_ticket`，不能靠刷新 AID token 延长票据。
+6. 跟随 302 时不得把 AID Bearer 转发到不同 origin 的 blob backend；下载完成后校验 `size_bytes` / `sha256`。
+
+SDK Storage VFS 会编排 ticket、HTTP GET 和完整性校验。应用只有在绕过 VFS、自行执行 HTTP 请求时，才需要直接处理上述凭据生命周期。
+
+---
+
+## 事件
+
+### event/storage.object_changed
+
+对象变更时推送。
+
+**Payload**：
+
+```json
+{
+    "module_id": "storage",
+    "action": "put",
+    "owner_aid": "alice.agentid.pub",
+    "object_key": "notes/hello.txt"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `module_id` | string | 当前模块 ID，通常为 `"storage"` |
+| `action` | string | `"put"` 或 `"delete"` |
+| `owner_aid` | string | 对象所有者 AID |
+| `object_key` | string | 对象路径 |
+
+> 当前实现在 `storage.put_object` 成功后推送 `action="put"`，`storage.delete_object` 返回 `deleted=true` 时推送 `action="delete"`，`storage.complete_upload` 成功后也会推送 `action="put"` 事件。
+
+---
+
+## storage.get_limits
+
+查询当前用户的上传限制和配额使用情况。客户端可在上传前调用此方法，避免超限后浪费流量。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner_aid` | string | 否 | 默认当前用户；仅允许查询自己的限制和配额 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `max_inline_bytes` | integer | `put_object` 内联上限，服务默认 65,536 字节，以响应配置值为准 |
+| `max_file_size_bytes` | integer | 单文件大小上限，服务默认 100 MiB，以响应配置值为准 |
+| `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
+
+上传预检：一次调用同时回答"文件是否超限"和"当前 owner 是否可秒传"。客户端应在计算完文件 SHA-256 后、实际上传前调用。
+
+> `check_upload` / `complete_upload(skip_blob=true)` 只允许复用当前 owner 已拥有的内容，避免跨 owner 暴露全局 CAS 存在性或跳过上传克隆他人私有内容。不同 owner 上传相同内容时，仍会在完成上传后归一到同一个 CAS blob，由服务端引用计数管理物理去重。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sha256` | string | 是 | 文件内容的 SHA-256 hex（64 字符） |
+| `size_bytes` | integer | 是 | 文件大小（字节） |
+| `owner_aid` | string | 否 | 目标 owner，默认当前用户；未提供目标路径时必须等于当前登录 AID |
+| `object_key` | string | 否 | 目标路径；提供时按该目标的写权限和挂载解析进行预检 |
+| `bucket` | string | 否 | 目标存储桶，默认 `"default"` |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `within_limit` | boolean | 文件大小是否在限制内 |
+| `exists` | boolean | 当前 owner 是否已拥有相同内容且 CAS blob 可用 |
+| `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"]:
+    # 秒传：当前 owner 已拥有相同内容，跳过上传直接 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),
+    })
+```
+
+---
+
+## 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 分享短码 |
+| `url` | string | 默认分享 URL：`https://{owner_aid}/s/{share_id}`，经 NameService 跳转 |
+| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}`，直接访问 Storage 服务 |
+| `expire_at` | integer | 分享链接过期时间戳（Unix 秒），`0` 表示永不过期 |
+| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
+| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+| `target` | object | 被分享对象的元数据，不包含空 URL 字段；其中 `expire_at` 为对象过期时间 |
+
+> `url` 经 NameService 302 跳转到 `share_url`；两者都通过 `share_id` 定位到同一条分享记录鉴权。
+> 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["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
+```
+
+---
+
+## storage.list_share_links
+
+列举分享链接，可按 bucket / object_key 过滤。仅返回当前用户自己创建的链接。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bucket` | string | 否 | 按存储桶过滤 |
+| `object_key` | string | 否 | 按对象路径过滤 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `links` | array | 分享链接列表 |
+
+每个 link 包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `share_id` | string | 分享短码 |
+| `url` | string | 默认分享 URL（隐藏路径）：`https://{owner_aid}/s/{share_id}` |
+| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}` |
+| `object_key` | string | 被分享对象路径 |
+| `target_type` | string | 分享目标类型 |
+| `target_id` | string | 分享目标 ID |
+| `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 | 是 | 分享短码 |
+
+可选 `if_sha256`（string，64 位十六进制摘要）用于已验证完整正文的条件读取。
+
+**响应**：小对象返回 `content`；大对象返回 `download_url`，该响应不能按空 `content` 解码。共同返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256` 和可选 `read_cache`。当前访问校验通过且摘要一致时可返回 `not_modified: true` 并省略正文／URL，复用要求见 [策略字段与条件读取](#策略字段与条件读取)。有限次分享允许 SDK 复用已验证的本地正文；本地缓存命中及无正文的 `not_modified` 不消耗分享次数；inline 返回正文时计次，大对象按下载授权签发／跳转计次，见[默认读缓存](#sdk-默认读缓存)。
+
+---
+
+## storage.fs.list
+
+列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 否 | `""` | 目录路径（空=根） |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `page` | integer | 否 | `1` | 页码 |
+| `size` | integer | 否 | `100` | 每页条数（受 `list_max_limit` 上限约束） |
+| `marker` | string | 否 | — | SDK 兼容参数，当前服务不消费该游标 |
+| `token` | string | 否 | — | 访问 token |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `nodes` | array | 节点列表，每项 `{type, node_type, name, path, mode, size, mtime, owner_principal}` |
+| `items` | array | 同 `nodes`（兼容别名） |
+| `total` | integer | 当前可见候选条数；普通调用不保证全目录精确总数 |
+| `page` / `size` | integer | 页码回显与截断上限；当前服务不按 `page` 偏移 |
+| `next_marker` | null | 当前固定为 `null`，不能据此遍历后续页 |
+
+`type` 取值：`file` / `dir` / `symlink` / `mount`。
+
+---
+
+## storage.fs.find
+
+递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 起始目录 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `name` | string | 否 | — | 名称 glob（如 `*.md`） |
+| `type` | string | 否 | — | 节点类型过滤：`f`/`d`/`l`（SDK 形参 `node_type`） |
+| `size` | string | 否 | — | 大小表达式（如 `+1M`） |
+| `mtime` | string | 否 | — | 修改时间表达式 |
+| `page` | integer | 否 | `1` | 页码 |
+| `page_size` | integer | 否 | `1000` | 每页条数，最大 5000 |
+| `token` | string | 否 | — | 访问 token |
+
+### 响应
+
+同 `storage.fs.list`：`{nodes, items, total, page, size, next_marker}`。
+
+---
+
+## storage.fs.df
+
+配额/用量报告（POSIX `df`），含每 owner 卷（过期卷重新计算）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `owner_aid` / `bucket` | string | 所有者 / 桶 |
+| `used_bytes` | integer | 已用字节 |
+| `object_count` | integer | 对象数 |
+| `quota_bytes` | integer | 配额上限 |
+| `avail_bytes` | integer | 剩余可用 |
+| `volumes` | array | 每卷用量明细 |
+
+---
+
+## storage.fs.stat
+
+查节点元数据（POSIX `stat`）。`follow_final=true`，解析末级软链 target。
+
+可传 `consistency: authoritative`；此模式使用 [权威对象结果](#权威读取与完整发布)，不是普通 fs 节点视图。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 节点路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `token` | string | 否 | — | 访问 token |
+| `consistency` | string | 否 | — | 传 `authoritative` 时返回权威对象结果 |
+
+### 响应
+
+fs 节点视图：`{type, node_type, name, path, mode, size, mtime, owner_principal, ...}`。
+
+---
+
+## storage.fs.lstat
+
+查节点（POSIX `lstat`），**不跟随末级软链**——返回软链本身（携带 `dangling` 悬空标志），不返回 target。
+
+### 参数
+
+同 `storage.fs.stat`。
+
+### 响应
+
+fs 节点视图；若为软链，返回软链节点本身（含 `dangling` 标志）。
+
+---
+
+## storage.fs.mkdir
+
+建目录（POSIX `mkdir`）。委托 `create_folder`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 目录路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `parents` | boolean | 否 | `false` | 递归创建父目录（类 `mkdir -p`） |
+
+### 响应
+
+fs 目录节点视图。
+
+---
+
+## storage.fs.touch
+
+创建空文件或刷新已有节点的修改时间（POSIX `touch`）。已存在的文件、目录或软链会更新时间戳；不存在时默认创建 0 字节私有文件；`no_create=true` 时不存在不创建并返回 `{touched:false, created:false}`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `parents` | boolean | 否 | `false` | 创建文件时是否递归创建父目录 |
+| `no_create` / `noCreate` | boolean | 否 | `false` | 目标不存在时不创建 |
+| `mtime` | integer | 否 | 当前时间 | Unix 秒或毫秒；小于 `10000000000` 按秒解释 |
+| `follow_symlinks` / `followSymlinks` | boolean | 否 | `false` | 目标为软链时是否跟随末级软链 |
+| `content_type` | string | 否 | `"application/octet-stream"` | 新建空文件的 MIME 类型 |
+| `metadata` | object | 否 | `{}` | 新建空文件的元数据 |
+| `is_private` | boolean | 否 | `true` | 新建空文件是否私有 |
+| `ttl_seconds` | integer | 否 | `0` | 新建空文件的过期秒数；不是 `expire_in_seconds` |
+
+### 响应
+
+成功返回 fs 节点视图，并额外包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `touched` | boolean | 是否实际更新或创建 |
+| `created` | boolean | 是否新建了空文件 |
+
+---
+
+## storage.fs.remove
+
+删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
+
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 节点路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `recursive` | boolean | 否 | `false` | 递归删除目录 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `owner_aid` / `bucket` / `path` | string | 目标 |
+| `removed_count` | integer | 删除节点数 |
+| `deleted` | boolean | 是否删除成功 |
+
+---
+
+## storage.fs.rename
+
+同 owner/bucket 内移动或改名（POSIX `mv`）。**跨 owner/bucket 被拒**；按节点类型分派到 move_folder / rename_symlink / move_object。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `src` | string | 是 | — | 源路径 |
+| `dst` | string | 是 | — | 目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `overwrite` | boolean | 否 | `false` | 覆盖已存在目标 |
+| `expected_version` | integer | 否 | — | 乐观锁版本号 |
+
+### 响应
+
+被重命名节点的 fs 节点视图。
+
+---
+
+## storage.fs.copy
+
+复制对象、软链或目录（POSIX `cp`，目录必须传 `recursive=true`）。CAS blob 引用计数复用，支持跨 owner 复制，目标仍须具备写权限。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `src` | string | 是 | — | 源路径 |
+| `dst` | string | 是 | — | 目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 源所有者 AID |
+| `bucket` | string | 否 | `"default"` | 源存储桶 |
+| `overwrite` | boolean | 否 | `false` | 覆盖已存在目标 |
+| `follow_symlinks` | boolean | 否 | `false` | 复制软链 target 而非软链本身 |
+| `recursive` | boolean | 否 | `false` | 递归复制目录及其对象、软链 |
+| `dst_owner_aid` | string | 否 | 同源 | 目标所有者（SDK 形参 `dst_owner`） |
+| `dst_bucket` | string | 否 | 同源 | 目标存储桶 |
+
+### 响应
+
+被复制节点的 fs 节点视图；目录额外返回 `copied_folders`、`copied_objects`、`copied_symlinks`。四端 VFS 解析为通用 NodeView 后不保留这些计数字段，需要计数时使用 low-level 原始响应。
+
+---
+
+## storage.fs.mount
+
+挂载卷或他人子树进 owner 命名空间。`readonly` 默认 true；`require_approval=true` 时进入 pending 直到源 owner 批准。群成员卷挂载场景下，storage 通过 CA `aid_type=group` 识别群命名空间，命中 `/memberdata/` 时调 `group.check_membership` 实时校验成员身份。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `mount_path` | string | 是 | — | 挂载点路径 |
+| `owner_aid` | string | 否 | 当前用户 | 命名空间所有者 |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `volume_id` | string | 否 | — | 挂载实体卷（与 source_* 互斥） |
+| `source_aid` | string | 否 | — | 虚拟卷源 AID（与 volume_id 互斥） |
+| `source_path` | string | 否 | — | 虚拟卷源路径 |
+| `source_bucket` | string | 否 | — | 虚拟卷源存储桶 |
+| `readonly` | boolean | 否 | `true` | 只读挂载 |
+| `require_approval` | boolean | 否 | `false` | 需源 owner 批准 |
+| `expires_at` | integer | 否 | — | 挂载过期时间 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `mount` | object | 挂载视图 |
+| `status` | string | `active`（直接生效）/ `pending`（待批准） |
+
+> `status` 字段仅在直接调用 lowlevel RPC（`fs_mount`/`FSMount`/`fsMount` 原始返回）时可见。四语言 SDK 的高层 VFS 门面（`vfs.mount()`/`StorageVFS.Mount()`/`vfs.mount()`）会把响应解析为通用 NodeView，该视图不保留顶层 `status` 字段；需要判断是否 `pending` 时请改用 lowlevel 接口读取原始响应，或检查服务端在 `pending` 场景下额外写入的 `request_id`。
+
+---
+
+## storage.fs.approve
+
+源 owner 批准 pending 挂载（重新校验源路径存在）。`mount_id` 或 `(owner_aid, bucket, mount_path)` 二选一定位。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mount_id` | string | 否 | 挂载 ID（或用下方三元组定位） |
+| `owner_aid` | string | 否 | 命名空间所有者 |
+| `bucket` | string | 否 | 存储桶 |
+| `mount_path` | string | 否 | 挂载点路径 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `approved` | boolean | `true` |
+| `mount` | object | 挂载视图 |
+
+---
+
+## storage.fs.reject
+
+源 owner 或挂载 owner 拒绝 pending 挂载。定位方式同 `fs.approve`。
+
+### 响应
+
+`{rejected: boolean, mount}`。
+
+---
+
+## storage.fs.unmount
+
+卸载挂载点（仅 owner 可操作）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `mount_path` | string | 是 | — | 挂载点路径 |
+| `owner_aid` | string | 否 | 当前用户 | 命名空间所有者 |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+`{unmounted: boolean, owner_aid, bucket, path, mount_path}`。
+
+---
+
+## storage.fs.invalidate_membership
+
+群成员变更/群解散时失效群挂载（仅群 owner 或内部调用者）。SDK 形参不带 owner/bucket。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `group_id` | string | 是 | — | 群组标识兼容字段，值语义为目标态 `group_aid` |
+| `group_owner_aid` | string | 是 | — | 群 owner AID |
+| `member_aid` | string | 否 | — | 成员 AID（不传=全员） |
+| `reason` | string | 否 | `"membership_changed"` | `dissolved` / `membership_changed` |
+| `status` | string | 否 | — | `inactive` / `unavailable` |
+
+### 响应
+
+`{group_id, group_aid, group_owner_aid, member_aid, reason, status, invalidated}`（`invalidated`=失效挂载数）。
+
+---
+
+## storage.create_symlink
+
+创建软链。target 受限于 owner 命名空间；拒绝同名 file/dir；父路径不可含软链前缀。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 软链路径 |
+| `target` | string | 是 | — | 指向目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `overwrite` | boolean | 否 | `false` | 覆盖已存在软链 |
+
+### 响应
+
+软链视图（含 `dangling` 悬空标志）。
+
+---
+
+## storage.readlink
+
+读软链 target（owner 校验）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 软链路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+软链视图 `{symlink, target, version, ...}`。
+
+---
+
+## storage.atomic_repoint
+
+原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 软链路径 |
+| `new_target` | string | 是 | — | 新 target |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `expected_version` | integer | 否 | — | CAS 期望版本（null=跳过 CAS） |
+
+### 响应
+
+**成功**：`{ok: true, ...软链视图}`（version+1）。
+**CAS 失败**：`{ok: false, current_version, current_target}`。
+
+---
+
+## storage.rename_symlink
+
+改软链 key（同 owner/bucket 内移动/改名），target 不变。跨 owner 被拒。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 原软链路径（SDK 形参 `path`/服务端 `src`） |
+| `new_path` | string | 是 | — | 新软链路径（服务端 `dst`） |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `overwrite` | boolean | 否 | `false` | 覆盖已存在 |
+| `expected_version` | integer | 否 | — | CAS 期望版本 |
+
+### 响应
+
+**成功**：`{ok: true, ...软链视图}`。
+**CAS 失败**：`{ok: false, current_version, current_path, current_target}`。
+
+---
+
+## storage.delete_symlink
+
+删软链记录（不动 target 对象）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 软链路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+`{deleted: boolean, owner_aid, bucket, path, symlink_id, target}`。
+
+---
+
+## storage.set_acl
+
+授予路径前缀权限，作用于该路径及子路径（最近祖先 ACL 生效）。`w` 写、`x` 删、`r` 读。具体 AID 的 `r` 用于 authoritative 读取和受信挂载读取；`subject` 条件规则的 `r` 还可授权普通私有对象读取。向指定 AID 分享普通私有对象，使用 `storage.create_share_link` 的 `allowed_aids`。
+
+`role:*` 伪主体只允许可信 group 内部门面写入。客户端不能直接对 `group_aid` 空间调用 `storage.set_acl` 设置 `role:admin`；群自有区角色写授权统一使用 `group.fs.set_acl`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 授权路径前缀 |
+| `subject` | object | 三选一 | — | 按 Ownership 和可信名片匹配的条件规则，结构见下表 |
+| `grantee_aids` | string[] | 三选一 | — | 一个或多个被授权 AID；`role:*` 仅限 group 内部调用 |
+| `grantee_aid` | string | 三选一 | — | 兼容旧调用的单个 AID |
+| `perms` | string | 是 | — | 权限位：`r` 读取、`w` 写入、`x` 删除，可组合 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `expires_at` | integer | 否 | — | 授权过期时间，Unix 秒 |
+| `max_uses` | integer | 否 | — | 具体 AID 分别计数；`subject` 整条规则共享计数；0 表示不限次数 |
+
+`subject`、`grantee_aid`、`grantee_aids` 必须且只能传一种；全部省略、同时传入或显式 `null` 返回 `-32602`。数组允许一个 AID，不能为空，元素不能为空；重复 AID 去重并保留首次顺序。先校验整批参数，再逐项写入；存储错误会中断，已完成项保留。
+
+### subject 结构
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ownership` | object | 是 | 匹配 Owner 当前 `owner.md` 单方声明的 sub，不要求双向共识 |
+| `ownership.owner_aid` | string | 是 | 要求请求者归属的 Owner AID；Owner 自身不计入 sub |
+| `ownership.scope` | string | 否 | 默认 `direct`：直接 sub；`descendants`：沿各级 Owner 声明检查后代，最多 64 跳，遇循环停止 |
+| `card` | object | 否 | 追加请求者的可信 Name Service 名片条件 |
+| `card.type` | string[] | 否 | 允许的 `type`；提供时必须为非空数组 |
+| `card.exttype` | string[] | 否 | 允许的 `exttype`；提供时必须为非空数组 |
+
+Ownership、`type`、`exttype` 之间是 AND；同一属性数组内是 OR。属性值去首尾空白、排序、去重后精确匹配；名片由服务端查询，应用不能随读取请求自报属性。同一路径和归一化 `subject` 对应同一规则，重复授权更新该规则。
+
+Storage 先检查 `owner_aid:/default/sub_aids/{请求者 AID}/owner.md`；`descendants` 逐级检查声明。每次确认当前路径快照，按正文摘要缓存解析结果，声明修改或删除后不复用旧版本。省略 `card` 不查询 NS；配置 `card` 时使用 60 秒 TTL 名片缓存，未命中／过期经内部 svc RPC `nameservice.agent_md_batch` 回源，不匹配时允许提前刷新，相邻刷新至少间隔 5 秒。并发查询按 AID 合并并去重，按需短窗口批查每批最多 64 个，无周期同步任务。远域 Owner 声明由内部 `storage.owner_declared_subjects` 查询；两种内部 RPC 只供受信 Storage 服务使用，SDK Facade 无需新增调用。
+
+```json
+{"path":"reports","subject":{"ownership":{"owner_aid":"owner.aid.example","scope":"direct"},"card":{"type":["agent"],"exttype":["assistant","worker"]}},"perms":"r"}
+```
+
+这条规则允许该 Owner 的直接 sub 中，名片满足 `type=agent` 且 `exttype` 为 `assistant` 或 `worker` 的 AID 读取 `reports` 及子路径。受保护的系统路径仍遵循原有约束。
+
+### 响应
+
+使用 `grantee_aids` 返回 `{acls: [ACL视图, ...]}`，单元素数组也返回此结构；仅使用兼容字段 `grantee_aid` 时仍返回单条 ACL 视图。每个 AID 独立保存 `max_uses` 和 `used_count`。
+
+使用 `subject` 返回单条 ACL 视图，其中用归一化 `subject` 替代 `grantee_aid`；其 `max_uses`、`used_count` 为整条规则的共享计数。视图另含 `acl_id`、`owner_aid`、`bucket`、`path/path_prefix`、`perms`、`expires_at`、`created_at`、`updated_at`。
+
+---
+
+## storage.remove_acl
+
+移除指定路径的具体 AID 或条件 ACL。撤销分享链接使用 `storage.revoke_share_link`；群角色 ACL 使用 `group.fs.remove_acl`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 授权路径前缀 |
+| `subject` | object | 三选一 | — | 原授权条件；按归一化后的同一规则撤销 |
+| `grantee_aids` | string[] | 三选一 | — | 一个或多个待撤销 AID |
+| `grantee_aid` | string | 三选一 | — | 兼容旧调用的单个 AID |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+使用 `grantee_aids` 返回 `{results: [{removed: boolean, owner_aid, bucket, path, grantee_aid}, ...]}`；单元素数组也返回此结构。仅使用 `grantee_aid` 时仍返回 `{removed: boolean, owner_aid, bucket, path, grantee_aid}`。
+
+使用 `subject` 返回 `{removed: boolean, owner_aid, bucket, path, subject}`。三选一、条件归一化、数组校验和去重规则与 `storage.set_acl` 一致；逐项撤销，存储错误会中断并保留已完成项。
+
+---
+
+## storage.list_acl
+
+列出路径上的 ACL 授权（owner 校验）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+`{owner_aid, bucket, path, acls}`。每条具体 AID 规则显示 `grantee_aid`，条件规则显示 `subject`；两类规则可同时存在，条件规则不暴露内部存储主体键。
+
+---
+
+## storage.set_visibility
+
+切换对象或目录的公开/私有（软链不支持）。`allow_roles` 是低层兼容字段，不能作为群自有区 admin 写授权入口；群自有区角色写授权必须使用 `group.fs.set_acl/remove_acl`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 路径 |
+| `visibility` | string | 是 | — | `public` / `private` |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `allow_roles` | array | 否 | — | 低层兼容字段，仅表示可见性读角色；不能用于群自有区写授权 |
+
+### 响应
+
+fs 节点视图（含 `allow_roles`）。
+
+---
+
+## storage.check_access
+
+非抛错的访问探测——探测某操作在某路径是否放行（内部捕获 NotFound/Dangling/Permission）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 路径（服务端别名 `object_key`） |
+| `operation` | string | 否 | `"read"` | `read` / `write` / `delete`（服务端别名 `op`） |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `token` | string | 否 | — | 访问 token |
+| `follow_symlinks` | boolean | 否 | `true` | 跟随软链 |
+
+### 响应
+
+`{allowed: boolean, reason, message, requester_aid, owner_aid, bucket, path, operation}`。
+
+---
+
+## storage.issue_token
+
+签发 hash 化的 bearer 访问 token，scope 到某路径。返回的明文 token 仅此一次可见。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 授权路径（服务端别名 `object_key`） |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `expires_at` | integer | 否 | — | 过期时间 |
+| `max_reads` | integer | 否 | — | 最大读取次数（服务端别名 `max_uses`） |
+
+### 响应
+
+token 视图 + 明文 token（一次性返回）。
+
+---
+
+## storage.revoke_token
+
+按明文 token 值吊销（内部 hash 后查找）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 路径（服务端别名 `object_key`） |
+| `token` | string | 是 | — | 要吊销的明文 token |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+`{revoked: boolean, owner_aid, bucket, path}`。
+
+---
+
+## storage.list_tokens
+
+列出路径上的 token（owner 校验，不返回明文）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+
+### 响应
+
+token 列表（hash 摘要 + 元数据）。
+
+---
+
+## storage.volume.create
+
+创建/upsert 配额卷（含 mount_point）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `size_bytes` | integer | 是 | — | 卷容量（>0） |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `volume_id` | string | 否 | 自动 | 卷 ID |
+| `used_bytes` | integer | 否 | — | 已用字节 |
+| `status` | string | 否 | `active` | `active` / `grace` / `expired` |
+| `mount_point` | string | 否 | — | 挂载点 |
+| `expires_at` | integer | 否 | — | 过期时间 |
+
+### 响应
+
+`{volume, ...卷视图}`。
+
+---
+
+## storage.volume.renew
+
+续期卷过期时间/状态（owner 校验，owner 不符抛 PermissionError）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `volume_id` | string | 是 | — | 卷 ID（服务端别名 `id`） |
+| `expires_at` | integer | 是 | — | 新过期时间 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `status` | string | 否 | — | 卷状态 |
+
+### 响应
+
+`{volume, ...卷视图}`。
+
+---
+
+## storage.volume.expire_due
+
+过期所有到期卷并标记其挂载为 unavailable。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `now` | integer | 否 | 当前时间 | 判定基准时间 |
+
+### 响应
+
+`{owner_aid, bucket, expired, mounts_unavailable, volumes, mounts}`。
+
+## 错误码
+
+| code | 说明 |
+|------|------|
+| -32002 | 服务暂不可用（数据库未连接） |
+| -32004 | 权限拒绝（requester 不是对象 owner，或非公开对象的读权限不足） |
+| -32008 | 对象不存在（`ErrNotFound`） |
+| -32009 | 版本冲突（`ErrVersionConflict`，`expected_version` 与实际版本不匹配） |
+| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |