@agentunion/fastaun 0.5.21 → 0.5.22

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

@@ -120,12 +120,54 @@
 
 ## 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` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`；`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+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 不授权普通下载票据。
@@ -198,6 +240,7 @@ result = await client.call("storage.put_object", {
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `consistency` | string | 否 | 传 `authoritative` 时绕过缓存并返回完整权威对象 |
+| `if_sha256` | string | 否 | 本地完整正文的 64 位十六进制 SHA-256；普通条件读取时使用，权威读取仍返回完整对象 |
 
 ### 响应
 
@@ -206,13 +249,15 @@ result = await client.call("storage.put_object", {
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
-| `content` | string | base64 编码内容 |
+| `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 不同）。
 
 ### 示例
@@ -230,7 +275,7 @@ content = base64.b64decode(result["content"])
 
 查询对象元数据，不返回内容。
 
-可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
+可传 `consistency: authoritative`，返回当前存在性与完整对象元数据；完整契约见 [权威读取与完整发布](#权威读取与完整发布)。
 
 ### 参数
 
@@ -257,6 +302,9 @@ content = base64.b64decode(result["content"])
 | `expire_at` | integer | 过期时间戳（0 表示不过期） |
 | `created_at` | integer | 创建时间戳 |
 | `updated_at` | integer | 更新时间戳 |
+| `read_cache` | object | 可选缓存策略；不返回／null 时采用 SDK 默认元数据策略，见 [策略字段](#策略字段与条件读取) |
+
+HEAD 只查询元数据，不消耗 token、ACL 或分享的正文读取次数。
 
 ---
 
@@ -272,6 +320,9 @@ content = base64.b64decode(result["content"])
 | `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` 后，先权威读取当前对象及原件摘要；目标已不是本任务原件时停止删除，不得改用新版本号自动重试。请求结果未知时，先核对目标是否已删除，再决定是否重放原条件请求。
 
 ### 响应
 
@@ -582,7 +633,7 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `upload_url` | string | 上传用 presigned URL |
+| `upload_url` | string | 上传用 presigned URL |
 | `session_id` | string | 规范 agent.md/owner.md 的完整原子发布会话；普通对象不保证返回 |
 | `expire_at` | integer | URL 过期时间戳 |
 | `owner_aid` | string | 所有者 AID |
@@ -597,8 +648,8 @@ for obj in result["items"]:
 | `size_bytes` | integer | 声明的文件大小 |
 | `overwrite` | boolean | 是否覆盖已有对象 |
 
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。普通对象不保证返回 `session_id`；规范 agent.md/owner.md 会话另返回 `session_id`，complete 必须沿用同一会话。
-
+客户端获得 `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`。
@@ -659,6 +710,8 @@ for obj in result["items"]:
 | `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` 的权威入口。
+
 ### 响应
 
 | 字段 | 类型 | 说明 |
@@ -677,6 +730,8 @@ for obj in result["items"]:
 
 `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 当作最终下载地址。
@@ -921,7 +976,9 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 |------|------|------|------|
 | `share_id` | string | 是 | 分享短码 |
 
-**响应**：小对象返回 `content`；大对象返回 `download_url`。同时返回 `object_id`、`object_key`、`path`、`size_bytes`、`content_type`、`sha256`。
+可选 `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-默认读缓存)。
 
 ---
 

package/_packed_docs/sdk/09-/345/207/255/350/257/201/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -58,7 +58,7 @@
 | `org_id`、`registration_request_id` | 条件 | 受限吊销授权要求时绑定组织和原登记操作 |
 | `registration_authorization` | 条件 | 补偿尚未登记的 CID 时提供原 issuer 授权 |
 
-成功返回 `credentialCid`、`status=revoked`、`revokedAt`、`eventSeq` 和 `cascadeCount`。同一 method、request ID 和参数摘要重试返回原结果；同一 request ID 更换摘要返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。
+成功返回 `credentialCid`、`status=revoked`、`revokedAt`、`eventSeq` 和 `cascadeCount`。同一 method、request ID 和参数摘要重试从持久去重记录返回原结果，进程重启后仍有效；同一 request ID 更换摘要返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。持久结果必须匹配原 CID 和 revoked 状态；记录损坏或状态不明返回 `CREDENTIAL_STATUS_UNKNOWN`，不能当作补偿已完成。
 
 ## credential.revocationList
 
@@ -66,6 +66,8 @@
 
 响应包含 `events[]`、`next_cursor`、`as_of`、`expires_at`、`responder`、`request_id`、`nonce`、`target`、`issuer_aid` 和签名。每个事件包含 `event_seq`、`cid`、`reason_code`、`revoked_at`、`revoked_by_aid`，可选 `reason` 和 `cascade_root_cid`。客户端应验证服务签名与证明时间窗，并按序号续查。
 
+SDK 0.5.22 将已验签的 `credential.revoked`／`credential.revocationList` 推送和列表页持久合并，单条事件不推进分页位置，旧分页不能覆盖新撤销证据。后台兜底拉取在连接后一小时首次执行，此后每小时一次；这是 SDK 调度策略，不是 RPC 的限频或服务端分页契约。存储、身份隔离和 proof 要求见 [SDK 移植指南](凭证与组织服务SDK开发与移植指南.md#54-撤销同步与持久快照0522)。
+
 ## 错误
 
 业务错误码位于 JSON-RPC `error.data.error_code`，包括 `CREDENTIAL_INVALID`、`CREDENTIAL_SIGNATURE_INVALID`、`CREDENTIAL_CHAIN_INVALID`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_REVOKED`、`CREDENTIAL_REQUEST_BINDING_INVALID`、`CREDENTIAL_AUTHENTICATION_INVALID`、`CREDENTIAL_IDEMPOTENCY_KEY_REUSE`、`CREDENTIAL_NOT_FOUND` 和 `CREDENTIAL_STATUS_UNKNOWN`。状态未知或服务/数据库不可用不能按有效处理。未注册的方法返回 JSON-RPC `Method not found`。

package/_packed_docs/sdk/09-/347/273/204/347/273/207/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -48,6 +48,8 @@
 
 ## 成员关系
 
+0.5.22 配套服务修复组织创建补偿与转让恢复：创建补偿遇到 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE` 时保存冲突并停止自动补偿；转让开始换钥前复核当前证书／公钥代际，以规范 DER 公钥的 Base64 调用 CA，并将新旧 owner 的成员替换、完整成员包定向通知一起持久化。通知失败保留待办并按组织轮转；应用保留原任务、原请求及原密钥，不用更换 request ID 消除不确定结果。完整恢复要求见 [应用指南](凭证与组织服务SDK应用集成指南.md#6-所有权转让与实体材料)。
+
 | 方法 | 主要业务参数 | 作用与结果 |
 |------|------|------|
 | `org.member.join` | `org_id`、`member_aid`、成员类型/类别、角色、完整条款、双签前 binding、成员签名 | 申请加入；返回待审批请求，不直接建立 active 成员 |

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -1,134 +1,138 @@
-# AUN SDK 文档查阅指南
-
-AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：Layer 1 地图、Layer 2 主题索引、Layer 3 单篇摘要。按需逐层读取，避免一次性加载整套文档。
-
-## SDK 文档定位
-
-当前 SDK 聚焦三主体模型：
-
-- `AIDStore`：注册、加载、列举、解析、证书运维与通用 raw/document 多签。
-- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
-- `AUNClient`：认证、连接、状态机、事件和 RPC。
-- `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
-- `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
-
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`。P2P 共享 seq/peer 游标、pending peers/统计快照、need_render、device 定向发送、TTL volatile 和 ACK 见 `09-message-rpc-manual.md`。当前 Agent.md Schema、签名和上传前校验见 `../protocol/Ownership协议定义2.1.md` 与 `04-连接与认证.md`；`../agent.md/SCHEMA.md` 为 legacy 2.0。当前 Ownership 2.1 应用接入见 `Ownership2.1-SDK应用集成指南.md`，SDK 移植见 `Ownership2.1-SDK开发与移植指南.md`，wire schema 见 `../protocol/Ownership协议定义2.1.md`；旧集成/实现指南与管理专题为 legacy。新服务端为旧 SDK 保留隔离的 owner RPC/Auth JSONL，不参与 2.1 双文件关系判断。Group/Org owner 不走通用流程，名片实体主签、owner token 上传、可选 owner 附签、实体证书代际和原 CAS pending见协议 §1.3/§2.5。peer A/T/H、human Tail 策略、稀疏覆盖、后台续拉和每个 AUNClient 一个网络 Pull Gate（同 namespace 单飞、不同 namespace 最多 4 个并行、相同 key 折叠、可运行项前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual；SDK 50k 内存去重、应用持久幂等及三类 batch 的当前契约见 Message RPC Manual。
-
-Storage 的 SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、direct backend 上传下载和 ticket / AID Bearer 边界见 `09-storage-rpc-manual.md` 与 `AUN Storage架构设计.md`。
-跨设备业务已读的 `read/read_state/read_changed`、单条/显式空值、回执与共享汇总、scope/owner 绑定、设备映射、晚到位置回填、TS/JS 精确整数和 Group canonical/权限版本及混合域提交见 Message/Group RPC Manual；四端门面与本地 `read_state_sync` 完成事件见 `06-API手册.md`、`04-连接与认证.md`。
-Group 的成员 block/status、暂停群权限和两阶段群主转让，以及 Group FS 的 `group.fs.*` RPC、角色 ACL、`parents` 语义和 memberdata 映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
-
-## 渐进式查阅流程
-
-### Step 1：读 Layer 1
-
-查看文档地图，能定位目标就直接读目标文档。
-
-### Step 2：按主题读 Layer 2
-
-常见主题：
-
-- 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
-- Ownership 2.1：关系仅由当前 agent.md/owner.md 确认；release 保持 v，清理后版本投影为 0／重绑默认 1，Header 只投影校验结果；普通 agent 注册 owner 可选；owner 当前完整原文/摘要/存在性再读，object_id/version 不为读取一致性条件；owner.md 通过 create_upload_session→HTTP PUT→complete_upload 的同一会话发布，expected_version 作发布 CAS，不提供全局/ABA保证；新服务端兼容旧 SDK 的注册、绑定、转移、查询和解绑 RPC 及隔离 Auth JSONL，只激活旧 NS ownership_proof，不写 2.1 双文件，不授 2.1 lock/version/consensus，不覆盖已存现代声明；新 SDK 关系操作不兼容旧服务端；当前应用/移植指南、七 Facade 与 Group/Org 专属生命周期、实体主签及原始多签恢复；v1/proof/escrow 文档为 legacy
-- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连 / 当前 access token getter / connect-disconnect-close 并发与取消
-- E2EE：默认加密、ProtectedHeaders、P2P / Group V2
-- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
-- 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
-- 消息同步：共享 seq 下的 peer A/T/H、稀疏覆盖/前驱、human Tail→Forward、50k 内存去重/应用持久幂等、N=4 网络 Gate、后台工作片续调度、`message.peers_snapshot` 的轻量对端水位/可选整体积压估计、目录/Pull逐页next_pending_seq、可靠commit后持续更新与每N次FIFO（无额外SQL、原列表顺序不改）、need_render/页内计数、`source` 和同步生命周期；Group 保持原终态规则
-- P2P TTL 消息：`message.send.ttl` 秒级钳制、按 device 内存收件箱、volatile 双游标、自动 ACK/去重、服务 epoch 与重启语义
-- 跨设备已读：P2P/Group 按话题上报、共享汇总、设备映射、单调事件、本地 `read_state_sync`、精确整数、混合域部分提交及幂等重试
-- Storage：SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC
-- Group RPC：成员 block/status、暂停群权限、两阶段群主转让、`group_aid` / `group_id` 兼容、`group.index` 签名索引与 CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
-- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
-- Credential/Org：服务端实际注册的凭证与组织 RPC、受保护请求、内部接口及未实现占位（见 `09-凭证服务RPC手册.md`、`09-组织服务RPC手册.md`）
-- Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
-- agent.md：Schema/frontmatter、Store.sign/verify 通用多签、显式 file/inPlace、multi-v1 表示协商、4 KiB/总尾区2048 字节限制、`AIDStore.register()` 默认自动上传、上传前完整校验、`agent_md_validation_v1`、`uploader_aid` / `uploaderAid`、`AIDStore.upload_agent_md()` / `download_agent_md()` / `check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
-- 错误处理：Result、Python `ErrorInfo.cause`、异常、错误码、重试
-
-### Step 3：读 Layer 3 摘要
-
-不确定哪篇文档包含细节时，先看单篇摘要，再打开原文目标章节。
-
-## 文档总览
-
-| 编号 | 文档 | 定位 |
-|------|------|------|
-| - | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) | 应用开发者的 TypeScript 接入、消息持久幂等、resolve/owner、凭证组织、诊断与升级 |
-| - | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) | SDK 开发者的 peer/batch 提交、共识缓存、原 CAS/旧任务、checkpoint、语言差异及验收 |
-| - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
-| 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
-| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、严格布尔 peer 能力、各层大小限制、消息格式、裸 WebSocket |
-| 03 | [核心概念](03-核心概念.md) | AID、peer A/T/H、稀疏覆盖、N=4 Gate、50k 内存去重、状态机、E2EE |
-| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、已读状态本地补偿完成事件、agent.md 校验和自动观察、resolve frontmatter 与按需 ownership |
-| - | [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) | 当前双文件关系、版本、签名与授权边界、旧 SDK owner RPC/JSONL 隔离 |
-| - | [Ownership SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md) | 七 Facade、审批、持久任务和恢复 |
-| - | [Ownership 2.1 SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md) | 普通 agent 可选 owner 注册、应用审批、新鲜共识、文件多签与实体上传 |
-| - | [Ownership 2.1 SDK 开发与移植指南](Ownership2.1-SDK开发与移植指南.md) | 统一签验核心、原件复核、owner.md 同会话上传与发布 CAS、NS 原条件与恢复 |
-| - | [Ownership管理专题（legacy）](Ownership管理专题.md) | 四端 P2P owner API、应用层 accept/reject、完整消息 payload、identity escrow、owner 代签 agent.md、metadata 状态和验签边界 |
-| - | [Ownership SDK集成指南（legacy）](Ownership-SDK集成指南.md) | TypeScript 快速接入、应用审批、状态查询及 SDK 编排流程图 |
-| - | [Ownership SDK实现指南（legacy）](Ownership-SDK实现指南.md) | SDK 移植入口、消息拦截、proof/escrow、metadata 和恢复验收 |
-| - | [Ownership协议定义（legacy）](../protocol/Ownership协议定义.md) | P2P/proof/agent.md schema、escrow、owner 授权头与现有 RPC |
-| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | 0.5.19 应用接入、CAP 完整验证、登记回执、成员闭环、代表请求和转让恢复 |
-| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | 0.5.19 四端协议实现、canonical JSON、强状态 proof、请求绑定、facade/RPC 和共同向量 |
-| - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | Credential Service 实际 RPC、参数和签名状态响应 |
-| - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、need_render、agent.md 版本提示、旧 SPK 保留 |
-| - | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API、实例级/单次调用、E2EE V2 HMAC 完整性和接收信任边界 |
-| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / ownership 和 owner.md 缓存 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
-| 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
-| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
-| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界 |
-| - | [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
-| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
-| 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
-| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
-
-## 常见查阅场景
-
-| 场景 | 推荐路径 |
-|------|----------|
-| 接入或升级 0.5.21，查看 TypeScript 应用示例 | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) |
-| 实现、移植或审查 0.5.21 SDK | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) |
-| 首次使用 SDK | [01-快速开始](01-快速开始.md) |
-| 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
-| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 查询 resolve opts、frontmatter 字段及类型、按需 ownership 共识和 owner.md 缓存 | [resolve 输入与输出](06-API手册.md#resolve-输入与输出) |
-| 查旧 SDK owner 注册、绑定、转移、查询及解绑的隔离兼容，或 legacy proof/escrow/代签 | [当前协议兼容边界](../protocol/Ownership协议定义2.1.md) 开篇/§3.2、[详细设计](Ownership2.1详细设计.md) §1 兼容矩阵；历史 wire 见 [Ownership管理专题（legacy）](Ownership管理专题.md)、[legacy 集成指南](Ownership-SDK集成指南.md) |
-| 首次在应用中集成 Ownership 2.1，使用 sign/verify、文件多签与实体上传 | [当前应用集成指南](Ownership2.1-SDK应用集成指南.md)、[API 手册](06-API手册.md#通用-sign--verify)、[编排指南 2.1](Ownership-SDK编排指南2.1.md) |
-| 实现、移植或审查 Ownership 2.1 SDK、统一签验核心与多签 HTTP 兼容 | [当前开发与移植指南](Ownership2.1-SDK开发与移植指南.md) §7 的 owner.md 同会话上传与 expected_version 发布 CAS，object_id/version 非读取条件；[详细设计](Ownership2.1详细设计.md) §1 兼容非回归原则与矩阵；关系有效性只影响依赖 owner 的功能 |
-| Ownership 2.1 当前格式、reset、历史任务及验证边界 | [第二十二节](../audit/Ownership2.1代码审查报告.md#二十二2026-10-18-恢复发布格式与历史兼容更正)：撤销独立资源和新增字段；[编排第 8 节](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)：0.5.20/0.5.19 及更早兼容、原任务恢复、绑定容错与 reset |
-| 当前双文件关系、release/清理/重绑版本、Header 投影及 Group/Org 名片 wire | [协议 2.1](../protocol/Ownership协议定义2.1.md) §3/§4.2/§6、§1.3/§2.5；旧 SDK RPC 隔离兼容见开篇/§3.2，旧 escrow/授权头 wire 查 legacy 协议 |
-| 应用接入 Credential/Org 服务 | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) |
-| 实现或移植 Credential/Org SDK | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) |
-| 查 Credential Service RPC | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) |
-| 查 Org Service RPC | [组织服务 RPC 手册](09-组织服务RPC手册.md) |
-| 自行发起 HTTP 数据面请求并获取当前 access token | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程) |
-| 发布、下载、检查或排查 agent.md（含 Schema/签名/大小限制）及远端 ETag | [当前协议 2.1](../protocol/Ownership协议定义2.1.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
-| 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
-| 查 peer 能力声明、连接上下文、上线恢复与实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers) |
-| 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
-| 查方法签名、群组高层 facade 和 `aid_store` / `aidStore` | [06-API手册](06-API手册.md) |
-| 查消息或群组 RPC、群提及过滤 `mention_mode` | 对应 `09-*-rpc-manual.md`；`mention_mode` 详见 [09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查 `protected_headers` / ProtectedHeaders 用法及四端 E2EE 细节 | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) |
-| 查 P2P pending peers、按对端/全部对端 Pull、peer ACK、历史基线、TTL volatile 或 need_render | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
-| 查跨设备业务已读、单条/显式空值、scope/owner、seq 映射、TS/JS 精确整数或 Group canonical/权限版本及混合域提交 | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查已读状态补偿完成事件 `read_state_sync`、states/errors 和 `background_sync` 边界 | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
-| 查 peer A/T/H、稀疏覆盖/前驱、human Tail、N=4 Gate、page_size×N 共享队列、后台续拉、SDK 50k 内存去重/应用持久幂等的自定义 store/多 client 边界 | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
-| 查 message.peers_snapshot 的对端水位/可选整体积压估计、目录A近似/Pull精确next_pending_seq提示（缺hint安全A、提交ACK后更新、只调度内部副本）、三类batch/完整single fallback、消息 source、同步生命周期和 delivery.changed | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers_snapshot) |
-| 查 History、Forward、Pull Gate、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查成员 block/status、暂停群发言权限或两阶段群主转让 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 架构、SDK VFS、权限模型和 mount/symlink | [AUN Storage架构设计.md](<../aun-fs/AUN Storage架构设计.md>) |
-| 查 Storage MIME 识别、session/PUT/complete Content-Type、OSS 403 或底层 RPC 调用责任 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 数据面 HTTP 下载流程和 ticket / AID Bearer 边界 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
-| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
-| 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
-| 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |
-| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
-| 排查错误或读取 Python 本地原始异常 `cause` | [07-错误处理](07-错误处理.md) |
-| 写测试或 demo | [08-最佳实践](08-最佳实践.md) |
-
-
+# AUN SDK 文档查阅指南
+
+AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：Layer 1 地图、Layer 2 主题索引、Layer 3 单篇摘要。按需逐层读取，避免一次性加载整套文档。
+
+## SDK 文档定位
+
+当前 SDK 聚焦三主体模型：
+
+- `AIDStore`：注册、加载、列举、解析、证书运维与通用 raw/document 多签。
+- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
+- `AUNClient`：认证、连接、状态机、事件和 RPC。
+- `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
+- `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
+
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`。P2P 共享 seq/peer 游标、pending peers/统计快照、need_render、device 定向发送、TTL volatile 和 ACK 见 `09-message-rpc-manual.md`。当前 Agent.md Schema、签名和上传前校验见 `../protocol/Ownership协议定义2.1.md` 与 `04-连接与认证.md`；`../agent.md/SCHEMA.md` 为 legacy 2.0。当前 Ownership 2.1 应用接入见 `Ownership2.1-SDK应用集成指南.md`，SDK 移植见 `Ownership2.1-SDK开发与移植指南.md`，wire schema 见 `../protocol/Ownership协议定义2.1.md`；旧集成/实现指南与管理专题为 legacy。新服务端为旧 SDK 保留隔离的 owner RPC/Auth JSONL，不参与 2.1 双文件关系判断。Group/Org owner 不走通用流程，名片实体主签、owner token 上传、可选 owner 附签、实体证书代际和原 CAS pending见协议 §1.3/§2.5。peer A/T/H、human Tail 策略、稀疏覆盖、后台续拉和每个 AUNClient 一个网络 Pull Gate（同 namespace 单飞、不同 namespace 最多 4 个并行、相同 key 折叠、可运行项前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual；SDK 50k 内存去重、应用持久幂等及三类 batch 的当前契约见 Message RPC Manual。
+
+Storage 的 SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、direct backend 上传下载和 ticket / AID Bearer 边界见 `09-storage-rpc-manual.md` 与 `AUN Storage架构设计.md`；Storage / Group FS 默认读缓存、60 秒总新鲜度、`read_cache`、SHA 条件读取、无正文 not_modified 不计次、持久层/容量与 `noCache` 规则见 [缓存策略](09-storage-rpc-manual.md#sdk-默认读缓存) 和 [API 选项](06-API手册.md#默认读缓存与单次刷新)。
+跨设备业务已读的 `read/read_state/read_changed`、单条/显式空值、回执与共享汇总、scope/owner 绑定、设备映射、晚到位置回填、TS/JS 精确整数和 Group canonical/权限版本及混合域提交见 Message/Group RPC Manual；四端门面与本地 `read_state_sync` 完成事件见 `06-API手册.md`、`04-连接与认证.md`。
+Group 的成员 block/status、暂停群权限和两阶段群主转让，以及 Group FS 的 `group.fs.*` RPC、角色 ACL、`parents` 语义和 memberdata 映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
+
+## 渐进式查阅流程
+
+### Step 1：读 Layer 1
+
+查看文档地图，能定位目标就直接读目标文档。
+
+### Step 2：按主题读 Layer 2
+
+常见主题：
+
+- 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
+- Ownership 2.1：关系仅由当前 agent.md/owner.md 确认；release 保持 v，清理后版本投影为 0／重绑默认 1，Header 只投影校验结果；普通 agent 注册 owner 可选；owner 当前完整原文/摘要/存在性再读，object_id/version 不为读取一致性条件；owner.md 通过 create_upload_session→HTTP PUT→complete_upload 的同一会话发布，expected_version 作发布 CAS，不提供全局/ABA保证；新服务端兼容旧 SDK 的注册、绑定、转移、查询和解绑 RPC 及隔离 Auth JSONL，只激活旧 NS ownership_proof，不写 2.1 双文件，不授 2.1 lock/version/consensus，不覆盖已存现代声明；新 SDK 关系操作不兼容旧服务端；当前应用/移植指南、七 Facade 与 Group/Org 专属生命周期、实体主签及原始多签恢复；v1/proof/escrow 文档为 legacy
+- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连 / 当前 access token getter / connect-disconnect-close 并发与取消
+- E2EE：默认加密、ProtectedHeaders、P2P / Group V2
+- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
+- 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
+- 消息同步：共享 seq 下的 peer A/T/H、稀疏覆盖/前驱、human Tail→Forward、50k 内存去重/应用持久幂等、N=4 网络 Gate、后台工作片续调度、`message.peers_snapshot` 的轻量对端水位/可选整体积压估计、目录/Pull逐页next_pending_seq、可靠commit后持续更新与每N次FIFO（无额外SQL、原列表顺序不改）、need_render/页内计数、`source` 和同步生命周期；Group 保持原终态规则
+- P2P TTL 消息：`message.send.ttl` 秒级钳制、按 device 内存收件箱、volatile 双游标、自动 ACK/去重、服务 epoch 与重启语义
+- 跨设备已读：P2P/Group 按话题上报、共享汇总、设备映射、单调事件、本地 `read_state_sync`、精确整数、混合域部分提交及幂等重试
+- Storage：SDK VFS、实际字节 MIME 识别、session/PUT/complete Content-Type 一致性、OSS 403、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC
+- Group RPC：成员 block/status、暂停群权限、两阶段群主转让、`group_aid` / `group_id` 兼容、`group.index` 签名索引与 CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
+- Credential/Org：服务端实际注册的凭证与组织 RPC、受保护请求、内部接口及未实现占位（见 `09-凭证服务RPC手册.md`、`09-组织服务RPC手册.md`）
+- Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
+- agent.md：Schema/frontmatter、Store.sign/verify 通用多签、显式 file/inPlace、multi-v1 表示协商、4 KiB/总尾区2048 字节限制、`AIDStore.register()` 默认自动上传、上传前完整校验、`agent_md_validation_v1`、`uploader_aid` / `uploaderAid`、`AIDStore.upload_agent_md()` / `download_agent_md()` / `check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
+- 错误处理：Result、Python `ErrorInfo.cause`、异常、错误码、重试
+
+### Step 3：读 Layer 3 摘要
+
+不确定哪篇文档包含细节时，先看单篇摘要，再打开原文目标章节。
+
+## 文档总览
+
+| 编号 | 文档 | 定位 |
+|------|------|------|
+| - | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) | 应用开发者的 TypeScript 接入、消息持久幂等、resolve/owner、凭证组织、诊断与升级 |
+| - | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) | SDK 开发者的 peer/batch 提交、共识缓存、原 CAS/旧任务、checkpoint、语言差异及验收 |
+| - | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) | TypeScript 接线、审批恢复、resolve、缓存及凭证组织 |
+| - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
+| - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
+| 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
+| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、严格布尔 peer 能力、各层大小限制、消息格式、裸 WebSocket |
+| 03 | [核心概念](03-核心概念.md) | AID、peer A/T/H、稀疏覆盖、N=4 Gate、50k 内存去重、状态机、E2EE |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、已读状态本地补偿完成事件、agent.md 校验和自动观察、resolve frontmatter 与按需 ownership |
+| - | [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) | 当前双文件关系、版本、签名与授权边界、旧 SDK owner RPC/JSONL 隔离 |
+| - | [Ownership SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md) | 七 Facade、sub-first Stage／owner-first 直接提交、无锁预检、三类 CAS 冲突及持久恢复 |
+| - | [Ownership 2.1 SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md) | 应用侧 TS 接线与审批；双向绑定、释放、三方转移和重连恢复图，任务与当前共识分开判断 |
+| - | [Ownership 2.1 SDK 开发与移植指南](Ownership2.1-SDK开发与移植指南.md) | SDK 内部 TS 接口；严格签验、NS fresh、Storage 发布、收件持久化和原 CAS 恢复图 |
+| - | [Ownership管理专题（legacy）](Ownership管理专题.md) | 四端 P2P owner API、应用层 accept/reject、完整消息 payload、identity escrow、owner 代签 agent.md、metadata 状态和验签边界 |
+| - | [Ownership SDK集成指南（legacy）](Ownership-SDK集成指南.md) | TypeScript 快速接入、应用审批、状态查询及 SDK 编排流程图 |
+| - | [Ownership SDK实现指南（legacy）](Ownership-SDK实现指南.md) | SDK 移植入口、消息拦截、proof/escrow、metadata 和恢复验收 |
+| - | [Ownership协议定义（legacy）](../protocol/Ownership协议定义.md) | P2P/proof/agent.md schema、escrow、owner 授权头与现有 RPC |
+| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | TS 示例与凭证登记验证、成员申请／邀请、续期、撤销同步和组织转让图 |
+| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | TS 内部示例与 Verify、双层请求摘要、回执、撤销快照和实体 checkpoint 图 |
+| - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | Credential Service 实际 RPC、参数和签名状态响应 |
+| - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、need_render、agent.md 版本提示、旧 SPK 保留 |
+| - | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API、实例级/单次调用、E2EE V2 HMAC 完整性和接收信任边界 |
+| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / ownership 和 owner.md 缓存 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC |
+| 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
+| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界、默认读缓存持久层、条件读取与 noCache |
+| - | [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
+| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
+| 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
+| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
+
+## 常见查阅场景
+
+| 场景 | 推荐路径 |
+|------|----------|
+| 接入或升级 0.5.21，查看 TypeScript 应用示例 | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) |
+| 实现、移植或审查 0.5.21 SDK | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) |
+| 接入或升级 0.5.22，查看 TypeScript 示例、关系审批、默认读缓存及完整成员包 | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) |
+| 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
+| 首次使用 SDK | [01-快速开始](01-快速开始.md) |
+| 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
+| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
+| 查询 resolve opts、frontmatter 字段及类型、按需 ownership 共识和 owner.md 缓存 | [resolve 输入与输出](06-API手册.md#resolve-输入与输出) |
+| 查旧 SDK owner 注册、绑定、转移、查询及解绑的隔离兼容，或 legacy proof/escrow/代签 | [当前协议兼容边界](../protocol/Ownership协议定义2.1.md) 开篇/§3.2、[详细设计](Ownership2.1详细设计.md) §1 兼容矩阵；历史 wire 见 [Ownership管理专题（legacy）](Ownership管理专题.md)、[legacy 集成指南](Ownership-SDK集成指南.md) |
+| Ownership 2.1 应用：绑定／释放／转移、审批及恢复的 TS 示例与图 | [应用集成指南](Ownership2.1-SDK应用集成指南.md) |
+| Ownership 2.1 移植：fresh 共识、发布、收件持久化和 CAS 恢复 | [开发与移植指南](Ownership2.1-SDK开发与移植指南.md) |
+| Ownership 2.1 当前格式、reset、历史任务及验证边界 | [第二十二节](../audit/Ownership2.1代码审查报告.md#二十二2026-10-18-恢复发布格式与历史兼容更正)：撤销独立资源和新增字段；[编排第 8 节](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)：0.5.20/0.5.19 及更早兼容、原任务恢复、绑定容错与 reset |
+| 当前双文件关系、release/清理/重绑版本、Header 投影及 Group/Org 名片 wire | [协议 2.1](../protocol/Ownership协议定义2.1.md) §3/§4.2/§6、§1.3/§2.5；旧 SDK RPC 隔离兼容见开篇/§3.2，旧 escrow/授权头 wire 查 legacy 协议 |
+| Credential/Org 应用：登记验证、入组、续期、撤销和转让图 | [应用集成指南](凭证与组织服务SDK应用集成指南.md) |
+| Credential/Org 移植：签验、双层摘要、快照和实体恢复 | [开发与移植指南](凭证与组织服务SDK开发与移植指南.md) |
+| 查 Credential Service RPC | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) |
+| 查 Org Service RPC | [组织服务 RPC 手册](09-组织服务RPC手册.md) |
+| 自行发起 HTTP 数据面请求并获取当前 access token | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程) |
+| 发布、下载、检查或排查 agent.md（含 Schema/签名/大小限制）及远端 ETag | [当前协议 2.1](../protocol/Ownership协议定义2.1.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
+| 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
+| 查 peer 能力声明、连接上下文、上线恢复与实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers) |
+| 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
+| 查方法签名、群组高层 facade 和 `aid_store` / `aidStore` | [06-API手册](06-API手册.md) |
+| 查消息或群组 RPC、群提及过滤 `mention_mode` | 对应 `09-*-rpc-manual.md`；`mention_mode` 详见 [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 `protected_headers` / ProtectedHeaders 用法及四端 E2EE 细节 | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) |
+| 查 P2P pending peers、按对端/全部对端 Pull、peer ACK、历史基线、TTL volatile 或 need_render | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
+| 查跨设备业务已读、单条/显式空值、scope/owner、seq 映射、TS/JS 精确整数或 Group canonical/权限版本及混合域提交 | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查已读状态补偿完成事件 `read_state_sync`、states/errors 和 `background_sync` 边界 | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
+| 查 peer A/T/H、稀疏覆盖/前驱、human Tail、N=4 Gate、page_size×N 共享队列、后台续拉、SDK 50k 内存去重/应用持久幂等的自定义 store/多 client 边界 | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md) |
+| 查 message.peers_snapshot 的对端水位/可选整体积压估计、目录A近似/Pull精确next_pending_seq提示（缺hint安全A、提交ACK后更新、只调度内部副本）、三类batch/完整single fallback、消息 source、同步生命周期和 delivery.changed | [06-API手册](06-API手册.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md#messagepeers_snapshot) |
+| 查 History、Forward、Pull Gate、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查成员 block/status、暂停群发言权限或两阶段群主转让 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 Storage 架构、SDK VFS、权限模型和 mount/symlink | [AUN Storage架构设计.md](<../aun-fs/AUN Storage架构设计.md>) |
+| 查 Storage MIME 识别、session/PUT/complete Content-Type、OSS 403 或底层 RPC 调用责任 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 Storage / Group FS 默认读缓存、60 秒总新鲜度、SHA 条件读取、无正文条件验证不计次、刷新和缓存专项断点续跑 | [缓存策略](09-storage-rpc-manual.md#sdk-默认读缓存)、[0.5.22 移植指南](0.5.22-SDK开发与移植指南.md#61-storage--group-fs-默认读缓存)、[测试入口](../aun测试运行指南.md#storage--group-fs-读缓存专项) |
+| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
+| 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
+| 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |
+| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
+| 排查错误或读取 Python 本地原始异常 `cause` | [07-错误处理](07-错误处理.md) |
+| 写测试或 demo | [08-最佳实践](08-最佳实践.md) |
+
+