@agentunion/fastaun-browser 0.5.6 → 0.5.9

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -23,7 +23,7 @@ await client.connect({"slot_id": "main", "auto_reconnect": True})
 
 关键约束：
 
-- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
+- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
 - `AIDStore.load(aid)` 返回 AID 值对象；AID 对象加载后不可变。
 - `AUNClient` 只接收 AID 对象，不接收字符串 AID 或配置字典里的 `aid` 字段。
 - `connect(options)` 内部会按需认证、建立 WebSocket、初始化 E2EE 和后台任务。
@@ -65,9 +65,9 @@ store = AIDStore(
 | `resolve(aid, opts=None)` | 拉取并缓存对端证书；默认同时下载并验签 agent.md，可传 `skip_agent_md=True` 跳过 |
 | `download_agent_md(aid)` | 下载并验签对端 agent.md |
 | `check_agent_md(aid, ttl_days=1)` | 检查本地缓存与远端 agent.md 状态 |
-| `diagnose(aid)` | 本地和远端一致性诊断 |
-| `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
-
+| `diagnose(aid)` | 本地和远端一致性诊断 |
+| `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
+
 Result 使用方式：
 
 ```python
@@ -89,18 +89,38 @@ client.load_identity(me)   # standby
 client = AUNClient(me)     # standby
 ```
 
-`load_identity()` 只允许在 `no_identity` 或 `closed` 状态调用；传入对象必须是私钥有效的 AID。
-
+`load_identity()` 只允许在 `no_identity` 或 `closed` 状态调用；传入对象必须是私钥有效的 AID。
+
 ### 显式认证
 
-通常不需要单独调用认证，`connect()` 会自动完成。需要提前获取 token 或检查认证链路时可调用：
+通常不需要单独调用认证，`connect()` 会自动完成。需要提前完成认证或检查认证链路时可调用：
 
 ```python
 auth = await client.authenticate()
 print(auth["access_token"], auth["gateway"])
 ```
 
-认证成功后状态进入 `authenticated`，随后调用 `connect()` 建立会话。
+认证成功后状态进入 `authenticated`，随后调用 `connect()` 建立会话。
+
+`authenticate()` 返回的 `access_token` 只是认证完成时的快照。后台刷新会更新 SDK 内部身份状态，但无法更新应用已经保存的字符串，因此不得把首次返回值长期用于 HTTP 请求。
+
+### 读取当前 access token
+
+应用绕过 SDK 门面、自行访问要求 AID Bearer 的 HTTP 数据面时，应在每次请求前同步读取当前缓存：
+
+```python
+token = client.get_access_token()       # str | None
+```
+
+```typescript
+const token = client.getAccessToken();  // string | null
+```
+
+```go
+token := client.GetAccessToken()        // 缺失时为空字符串
+```
+
+这些 getter 只读取后台刷新任务维护的最新缓存，不发起认证、刷新或网络请求，也不独立检查 token 是否临近过期；其有效性依赖客户端连接生命周期和后台刷新任务正常运行。返回空值时应先完成身份加载和认证/连接，不得发送空 Bearer。应用不得跨请求长期保存 getter 的返回值；具体的数据面票据、跨域凭据和重试规则见 [Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程)。
 
 ### 连接
 
@@ -202,8 +222,8 @@ print(client.can_connect, client.can_send, client.is_online)
 uploaded = await store.upload_agent_md("alice.agentid.pub", content)
 ```
 
-`aid` 必须是本地 AID。上传由 `AIDStore` 读取本地私钥签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-
+`aid` 必须是本地 AID。上传由 `AIDStore` 读取本地私钥签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
+
 解析对端并验签 agent.md：
 
 ```python

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

@@ -152,8 +152,8 @@ AID 由 `AIDStore.load()` 返回，应用层不直接构造。
 | `is_private_key_valid()` | `isPrivateKeyValid()` | `IsPrivateKeyValid()` | 私钥是否可用 |
 | `sign(data)` | `sign(data)` | `Sign(data)` | 签名 bytes |
 | `verify(data, signature)` | `verify(data, signature)` | `Verify(data, signature)` | 验签 |
-| `sign_agent_md(content)` | `signAgentMd(content)` | `SignAgentMd(content)` | agent.md 签名 |
-| `verify_agent_md(content)` | `verifyAgentMd(content)` | `VerifyAgentMd(content)` | agent.md 验签 |
+| `sign_agent_md(content)` | `signAgentMd(content)` | `SignAgentMd(content)` | agent.md 签名 |
+| `verify_agent_md(content)` | `verifyAgentMd(content)` | `VerifyAgentMd(content)` | agent.md 验签 |
 
 ---
 
@@ -193,17 +193,20 @@ client := aun.NewAUNClient(aid)
 
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
-| `load_identity(aid)` | `loadIdentity(aid)` | `LoadIdentity(aid)` | 在 `no_identity` / `closed` 状态加载身份 |
-| `state` | `state` | `ConnectionState()` | 九态公开状态 |
-| `gateway_url` | `gatewayUrl` | `GetGatewayURL()` | 当前连接的 Gateway URL（只读，自动发现，连接前为空） |
-| `current_aid` | `currentAid` | `CurrentAID()` | 当前 AID 对象 |
+| `load_identity(aid)` | `loadIdentity(aid)` | `LoadIdentity(aid)` | 在 `no_identity` / `closed` 状态加载身份 |
+| `state` | `state` | `ConnectionState()` | 九态公开状态 |
+| `gateway_url` | `gatewayUrl` | `GetGatewayURL()` | 当前连接的 Gateway URL（只读，自动发现，连接前为空） |
+| `get_access_token()` | `getAccessToken()` | `GetAccessToken()` | 同步读取后台刷新任务维护的当前 access token；不发起认证、刷新或网络请求；无 token 时分别返回 `None` / `null` / 空字符串 |
+| `current_aid` | `currentAid` | `CurrentAID()` | 当前 AID 对象 |
 | `aid` | `aid` | `AID()` | 当前 AID 字符串 |
 | `has_identity` | `hasIdentity` | `HasIdentity()` | 是否已加载身份 |
 | `can_sign` | `canSign` | `CanSign()` | 是否可签名 |
 | `can_connect` | `canConnect` | `CanConnect()` | 是否可连接 |
 | `can_send` / `is_ready` | `canSend` / `isReady` | `CanSend()` / `IsReady()` | 是否可发送 |
-| `is_online` | `isOnline` | `IsOnline()` | 是否处于在线或重连相关状态 |
-| `is_closed` | `isClosed` | `IsClosed()` | 是否已关闭 |
+| `is_online` | `isOnline` | `IsOnline()` | 是否处于在线或重连相关状态 |
+| `is_closed` | `isClosed` | `IsClosed()` | 是否已关闭 |
+
+`get_access_token()` / `getAccessToken()` / `GetAccessToken()` 面向需要自行发起 HTTP 数据面请求的应用。返回值是调用时刻的缓存快照，不是可长期持有的凭据：应在每次需要 AID Bearer 的请求前重新读取，不能持续复用 `authenticate()` 首次返回的字符串。getter 本身不会主动刷新，也不独立检查 token 是否临近过期；其有效性依赖客户端后台刷新任务正常运行。返回空值时应先完成身份加载和认证/连接，且不得发送空的 `Authorization` 头。Storage VFS 和 Group FS 等 SDK 门面会自行编排其数据面请求，普通应用优先使用门面。Bearer、资源域 ticket、跨 issuer 下载和 401/403 重试边界见 [Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程)。
 
 状态值：
 
@@ -225,10 +228,10 @@ await client.close()
 
 说明：
 
-- `authenticate()` 只取 token，不建立业务会话。
-- `connect()` 可从 `standby` 自动认证并进入 `ready`。
-- `disconnect()` 断开当前传输连接，对象仍可重新连接。
-- `close()` 关闭连接和后台任务；之后只能重新加载身份再复用。
+- `authenticate()` 只取 token，不建立业务会话。
+- `connect()` 可从 `standby` 自动认证并进入 `ready`。
+- `disconnect()` 断开当前传输连接，对象仍可重新连接。
+- `close()` 关闭连接和后台任务；之后只能重新加载身份再复用。
 
 四个 SDK 的公开构造入口均已对齐为“无参或 AID 对象”。调试、TLS、根证书、device_id、slot_id 等配置由 `AIDStore` 传递到 AID，再由 `AUNClient` 继承；连接级选项只传给 `connect()`。
 
@@ -304,14 +307,14 @@ headers = client.get_protected_headers()
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
 | `AIDStore.upload_agent_md(aid, content=None)` | `store.uploadAgentMd(aid, content?)` | `store.UploadAgentMD(ctx, aid, content...)` | 发布指定本地 AID 的 agent.md |
-| `AIDStore.download_agent_md(aid)` | `store.downloadAgentMd(aid)` | `store.DownloadAgentMD(ctx, aid)` | 下载并验签 |
-| `AIDStore.check_agent_md(aid)` | `store.checkAgentMd(aid)` | `store.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 检查一致性 |
-
-说明：
-
-- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
-- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+| `AIDStore.download_agent_md(aid)` | `store.downloadAgentMd(aid)` | `store.DownloadAgentMD(ctx, aid)` | 下载并验签 |
+| `AIDStore.check_agent_md(aid)` | `store.checkAgentMd(aid)` | `store.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 检查一致性 |
+
+说明：
+
+- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
+- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
+- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
 - SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
 - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
 

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

@@ -68,7 +68,7 @@ except AUNError as e:
 | -32602 且消息包含 `group.index` 签名/schema/hash/etag 错误 | group.index 校验失败 | 检查 signer、canonical JSONL、`body_hash`、`etag` 和 `signature` |
 | -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
 | 4090 | 身份冲突 | `IdentityConflictError` |
-| -32050 | 证书已吊销 | `CertificateRevokedError` |
+| -32050 | 证书已吊销 | `CertificateRevokedError` |
 | -33001 | 群组不存在 | `GroupNotFoundError` |
 | -33002 / -33003 | 群组状态错误 | `GroupStateError` |
 | -33004 ~ -33009 | 其他群组错误 | `GroupError` 子类 |
@@ -136,7 +136,7 @@ if not registered["ok"] and registered["error"]["code"] == "IDENTITY_CONFLICT":
 
 不要通过删除本地 `AIDs/` 目录解决冲突；私钥丢失后无法证明原 AID 所有权。
 
-### 连接状态错误
+### 连接状态错误
 
 ```python
 await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionError / StateError
@@ -144,7 +144,7 @@ await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionEr
 
 发送前检查：
 
-```python
+```python
 if not client.can_send:
     await client.connect({"auto_reconnect": True})
 ```

package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -92,13 +92,12 @@ SDK 内部自动管理 RPC 并发，应用层无需配置：
 
 | 机制 | 说明 |
 |------|------|
-| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
-| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
-| Pull Gate | P2P Message、Group Message、Group Event 各一个 Gate；每个 Gate single-inflight |
+| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
+| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
+| Pull Gate | 每个 `AUNClient` 一个客户端级 Gate；P2P Message、Group Message、Group Event Pull 共享该 Gate，始终 single-inflight |
 | 队列优先级 | Tail/History 前台 FIFO 优先于 Forward/Gap Fill 后台 FIFO；Group Event Pull 为后台；同 key 自动折叠 |
-| 队列超时 | 排队或等待折叠结果超过 3 秒时旁路 Gate 执行，不取消原请求 |
-
-应用层保持普通 `await client.call(...)` 即可。
+
+Gate 内始终保持单飞；相同 key 的调用共享同一结果，不同 key 按前台优先、队列顺序执行。应用层保持普通 `await client.call(...)` 即可，不应自行实现重复并发控制。
 
 ---
 

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

@@ -1310,9 +1310,11 @@ result = await client.call("group.thought.get", {
 
 `group.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。普通 Forward 中，`retention_floor_message_seq` 只表示已提交物理 GC；`earliest_available_message_seq-1` 表示服务端综合 retention、入群点和 epoch 后的当前成员可见性排他下界。SDK 以 `max(retention_floor_message_seq, cursor.join_seq, earliest_available_message_seq-1)` 推进 A；History 不修改 A/T/H。
 
-Forward 原始页校验通过后按页内最大 seq 推进 A，单条解密失败通过 `group.message_undecryptable` 报告而不阻塞水位。Piggy ACK 保留：有待提交 ACK 时，非满页会继续拉一页并携带 ACK，空页后停止。
-
-解密当前群消息时若缺少 sender IK，SDK 先执行同发送端 single-flight 的有界同步 bootstrap，最多等待 3 秒；P2P bootstrap 未命中时可继续读取 Group bootstrap。成功后立即重试当前消息，失败或超时才 pending，且不阻塞实时扫描水位。
+Forward 原始页校验通过后按页内最大 seq 推进 A，单条解密失败通过 `group.message_undecryptable` 报告而不阻塞水位。Piggy ACK 保留：有待提交 ACK 时，非满页会继续拉一页并携带 ACK，空页后停止。
+
+`group.pull` 与 `group.history` 进入当前 `AUNClient` 的客户端级 Pull Gate。该 Gate 与 P2P Message、Group Event Pull 共享，始终 single-inflight；相同请求 key 折叠并共享结果，不同 key 按前台 FIFO（Tail/History）优先于后台 FIFO（Forward/Gap Fill/Group Event）排队。不同 `AUNClient` 实例之间不共享 Gate，应用层无需自行实现并发控制。
+
+解密当前群消息时若缺少 sender IK，SDK 先执行同发送端 single-flight 的有界同步 bootstrap，最多等待 3 秒；P2P bootstrap 未命中时可继续读取 Group bootstrap。成功后立即重试当前消息，失败或超时才 pending，且不阻塞实时扫描水位。
 
 SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布一次。A/T/H 是扫描水位，不记录应用是否已经收到回调；跨 Push、SDK 自动最新页同步和 Forward 页允许重复和乱序。全局去重与排序由应用业务仓库负责，不是 SDK 交付契约；应用必须在群 namespace 内按 `message_id` 幂等并按 `seq` 排序。SDK 进程内折叠仅作 best-effort 优化。History 只返回结果，不参与实时发布。
 
@@ -1445,9 +1447,11 @@ SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布
 
 查看群文件系统用量。参数可传 `path` 或 `group_id`。
 
-### group.fs.create_download_ticket
-
-创建下载票据。参数：`path` 必填。响应包含 `download_url`、可选 `sha256`、`content_type`、`file_name`。SDK 下载数据面使用该票据执行 HTTP GET 并校验 sha256。
+### group.fs.create_download_ticket
+
+创建下载票据。参数：`path` 必填。响应包含 `url` / `download_url`、`expire_at`，以及可选的 `token`、`sha256`、`content_type`、`file_name`。私有文件和跨 issuer 文件由资源所在域签发短 TTL 的 `?t=` 能力凭据；Group 只返回票据，不代理文件字节。
+
+SDK Group FS 门面使用票据执行 HTTP GET 并校验 sha256。应用自行下载时遵守与 `storage.create_download_ticket` 相同的数据面规则：完整保留 URL 中的 `?t=`；只有端点明确要求 AID Bearer 时，才在每次请求前调用 Python `get_access_token()`、TypeScript / JavaScript `getAccessToken()` 或 Go `GetAccessToken()`；不得长期复用 `authenticate()` 首次返回的 token，也不得把当前域的 AID JWT 发送给另一 issuer 的 storage。401/403 仅在重新读取到不同 token 时重试一次；票据过期应重新申请。完整流程见 [Storage RPC 手册](09-storage-rpc-manual.md#数据面-http-下载流程)。
 
 ### group.fs.set_acl
 
@@ -1546,7 +1550,7 @@ SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布
 
 ### group.pull_events
 
-增量拉取群事件，支持多设备独立游标。SDK 将其作为后台 Pull 放入独立的 Group Event Gate；该 Gate 内单飞、同请求 key 折叠、不同 key FIFO，排队超过 3 秒时旁路执行。它不与 Group Message Gate 共用，也不修改消息 A/T/H。
+增量拉取群事件，支持多设备独立游标。SDK 将其作为后台 Pull 放入当前 `AUNClient` 的客户端级 Pull Gate；该 Gate 与 P2P Message、Group Message Pull 共享，始终 single-inflight，相同请求 key 折叠并共享结果，不同 key 按后台 FIFO 排队。Group Event 使用独立的 Forward Cursor，不修改消息 A/T/H；不同 `AUNClient` 实例之间不共享 Gate。应用层无需自行实现并发控制。
 
 **参数**：
 

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

@@ -344,9 +344,11 @@ result = await client.call("message.thought.get", {
 | `ephemeral_earliest_available_seq` | integer\|null | 临时缓冲中可用的最小 seq |
 | `ephemeral_dropped_count` | integer | 已被淘汰的临时消息数 |
 
-`message.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。Forward 页通过结构校验后，本地 A 按原始页最大 seq 推进。页内缺号视为服务端永久空号；单条解密失败通过 `message.undecryptable` 报告，不阻塞后续水位。Forward 仍支持 Piggy ACK：存在待提交 ACK 时，即使当前页非满页也会再拉一页并携带 ACK，空页后停止。
-
-解密当前消息时若缺少 sender IK，SDK 会把同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；获取成功立即重试当前消息，失败或超时才进入 pending。该补救不改变 Forward 按原始页推进 A 的规则。
+`message.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。Forward 页通过结构校验后，本地 A 按原始页最大 seq 推进。页内缺号视为服务端永久空号；单条解密失败通过 `message.undecryptable` 报告，不阻塞后续水位。Forward 仍支持 Piggy ACK：存在待提交 ACK 时，即使当前页非满页也会再拉一页并携带 ACK，空页后停止。
+
+`message.pull` 与 `message.history` 进入当前 `AUNClient` 的客户端级 Pull Gate。该 Gate 与 Group Message、Group Event Pull 共享，始终 single-inflight；相同请求 key 折叠并共享结果，不同 key 按前台 FIFO（Tail/History）优先于后台 FIFO（Forward/Gap Fill/Group Event）排队。不同 `AUNClient` 实例之间不共享 Gate，应用层无需自行实现并发控制。
+
+解密当前消息时若缺少 sender IK，SDK 会把同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；获取成功立即重试当前消息，失败或超时才进入 pending。该补救不改变 Forward 按原始页推进 A 的规则。
 
 SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布一次。A/T/H 是扫描水位，不记录应用是否已经收到回调；跨 Push、SDK 自动最新页同步和 Forward 页允许重复和乱序。全局去重与排序由应用业务仓库负责，不是 SDK 交付契约；应用必须按 `(namespace, message_id)` 幂等并按 `seq` 排序。SDK 进程内折叠仅作 best-effort 优化。History 只返回结果，不参与实时发布。
 

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

@@ -647,9 +647,20 @@ for obj in result["items"]:
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
 
-`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
-
----
+`url` 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 `?t=` token 或 `Authorization: Bearer <AID JWT>` 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。
+
+### 数据面 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 请求时，才需要直接处理上述凭据生命周期。
+
+---
 
 ## 事件
 

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -12,9 +12,9 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `PushFacade`：Python SDK 的当前安装推送登记、注销和 Push Server 批次 ACK。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`。A/T/H、SDK 内部自动最新页同步、Forward 调度和三 Pull Gate 见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual。Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`。Agent.md Schema、签名和上传前校验见 `../agent.md/SCHEMA.md` 与 `04-连接与认证.md`。A/T/H、SDK 内部自动最新页同步、Forward 调度和每个 AUNClient 一个 Pull Gate（始终 single-inflight、相同 key 折叠、不同 key 排队、前台 FIFO 优先）见 `03-核心概念.md`；`message.history` / `group.history` 与 Piggy ACK 见 Message/Group RPC Manual。Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。
 
-Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
+Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
 Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
 
 ## 渐进式查阅流程
@@ -28,17 +28,17 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 常见主题：
 
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
-- 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
+- 连接与状态：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
-- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、P2P Message/Group Message/Group Event 三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
-- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
+- 消息同步：A/T/H、Tail、Forward、History、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（P2P Message/Group Message/Group Event Pull 共享，始终单飞、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进
+- Storage：SDK VFS、direct backend 数据面、下载 ticket / AID Bearer 边界、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
 - Group RPC：群提及过滤 `mention_mode`、`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` 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`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
-- agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
+- agent.md：Schema/frontmatter、尾部签名、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、异常、错误码、重试
 
 ### Step 3：读 Layer 3 摘要
@@ -51,13 +51,14 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 |------|------|------|
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
-| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、Capabilities 能力声明、消息格式、裸 WebSocket |
+| 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、Capabilities 能力声明、各层大小限制、消息格式、裸 WebSocket |
 | 03 | [核心概念](03-核心概念.md) | AID、A/T/H、Pull Gate、状态机、E2EE |
-| 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件、agent.md 自动观察 |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、默认 agent.md 自动上传、连接生命周期并发/取消、当前 access token getter、网关发现、事件、agent.md 校验和自动观察 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
-| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / History 门面 / 事件 / RPC |
+| 06 | [API手册](06-API手册.md) | AIDStore / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 门面 / 事件 / RPC |
 | 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
-| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、Pull Gate、测试数据 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（始终单飞）、测试数据 |
+| - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、数据面 HTTP 下载流程、ticket / AID Bearer 边界、跨 issuer 下载 |
 | - | [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 数据面注册 |
@@ -70,20 +71,21 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 了解最新版本特性和改进 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
 | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
-| 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 发布、下载、检查或排查 agent.md 远端 ETag | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
+| 注册或加载 AID | [04-连接与认证](04-连接与认证.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 | [../agent.md/SCHEMA.md](../agent.md/SCHEMA.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) |
 | 查 Capabilities 能力声明、实时推送优化 | [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) |
 | 登记、更新或注销 `push_notify_aid` | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md` |
-| 查方法签名 | [06-API手册](06-API手册.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) |
-| 查 A/T/H、SDK 自动最新页同步与 Pull Gate | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md) |
-| 查 History、Forward、Group 成员可见性 floor 与 Piggy ACK | [09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 A/T/H、SDK 自动最新页同步与 AUNClient 级 Pull Gate | [03-核心概念.md](03-核心概念.md)、[08-最佳实践.md](08-最佳实践.md)、[09-message-rpc-manual.md](09-message-rpc-manual.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查 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) |
 | 查 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 RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 查 Storage 架构、SDK VFS、权限模型和 mount/symlink | [AUN Storage架构设计.md](<../aun-fs/AUN Storage架构设计.md>) |
+| 查 Storage RPC 参数、数据面 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) |

package/_packed_docs/sdk/CHANGELOG-0.5.6.md

@@ -0,0 +1,73 @@
+# AUN SDK 0.5.6 更新日志
+
+> 发布日期：2026-08-13；对比基线：0.5.5（`ce56814a`）
+
+本页汇总 TypeScript、浏览器 JavaScript、Python 和 Go 四个 SDK 的 0.5.6 变更。各语言的发布条目以对应目录下的 `CHANGELOG.md` 为准。
+
+---
+
+## 安全性
+
+### 首次签名者身份发现
+
+- `lookupPeer` / `lookup_peer` / `LookupPeer` 在内存 peer cache 未命中时会从服务端获取证书，而不是直接终止验签。
+- 签名携带证书指纹时，可精确获取对应历史证书；返回前仍会校验证书链、身份、有效期和指纹。
+- 按历史指纹获取的证书不会覆盖当前活动 peer cache，避免旧证书污染后续普通查找。
+
+### group.index 与索引项
+
+- `group.index` 在下载或更新准备写入可信缓存时验签，并校验 `group_aid`、body hash、index ETag、签名者身份以及签名者当前 owner/admin 权限。
+- rules、announcement、join requirements 和其他 indexed settings 不各自维护独立签名；SDK 逐项核对实际内容 ETag 与已验签 `group.index` 中的 entry ETag。
+- 任一签名、摘要、权限、证书或内容 ETag 校验失败，都不会提交新的索引或 settings 缓存。
+- 已以当前验证版本落盘的可信快照在普通读取时不重复验签。远端 ETag 变化会把旧快照标记为 stale，但不会把未经验证的新内容写入缓存；实际刷新时重新执行完整校验。
+
+### agent.md
+
+- 远端 `agent.md` 下载后先解析签名信息，并通过当前或指定指纹的历史证书验签，再决定是否保存。
+- 签名状态为 `invalid` 时返回错误，不覆盖本地正文或缓存记录。
+
+### 其他安全修复
+
+- 修复 Storage 跨域下载时的 bearer 隔离，避免把本域凭据发送给非受信目标。
+- 加固 Gateway 候选故障转移、连接/重连竞态、短 RPC challenge/response 和前置帧处理。
+
+---
+
+## 消息与同步
+
+- 完成 P2P 与群消息 `tail` / `forward` / `history` 窗口处理、seq 状态持久化、pull gate、补洞、确认和有序投递。
+- 连接认证声明 `inline_realtime_payload_v1`；完整的实时内联载荷仍经过 E2EE、签名、序列连续性和状态提交检查，不完整或不支持时回退 pull。
+- 对齐 Message/Group self-sync 与 bootstrap 契约，修复多设备和前向保密状态边界。
+- 新增 `mention_mode` 归一化和投递过滤，支持 `disabled`、`mention-only`，并兼容历史输入 `mention_only`。
+- 后台补洞和 ack 调度不再挤占前台 RPC。
+
+---
+
+## 各语言能力边界
+
+| 能力 | TypeScript / Node.js | JavaScript / Browser | Python | Go |
+|------|----------------------|----------------------|--------|----|
+| peer cache miss 自动回源及历史指纹证书 | 支持 | 支持 | 支持 | 支持 |
+| group.index / indexed settings / agent.md 提交前校验 | 支持 | 支持 | 支持 | 支持 |
+| 消息窗口、inline realtime、mention mode | 支持 | 支持 | 支持 | 支持 |
+| 公开离线 Push facade | 本版本未新增 | 本版本未新增 | `PushFacade`、连接期登记、注销和 ACK | 本版本未新增；覆盖共享合同向量和状态机 |
+| 文件型 `change-seed` | 支持公开 API | 不适用 IndexedDB 后端 | 支持公开 API、CLI 和迁移脚本 | 支持公开 API |
+
+---
+
+## `.seed` 与显式 change-seed
+
+- TypeScript、Python 和 Go 删除构造或启动阶段的 `.seed` 自动迁移，以及运行时对 `.seed.migrated.*` 的自动回退。
+- 显式 `change-seed` 保留。只有调用者明确把旧 seed 指定为 `.seed` 时才读取该文件；迁移全部成功后才将其归档为 `.seed.migrated.<timestamp>`。
+- 普通身份加载和密钥解密不会扫描 `.seed` 或 `.seed.migrated.*`。
+- 浏览器 JavaScript 使用 IndexedDB，不新增文件型迁移接口。
+
+---
+
+## 版本与测试
+
+- 四个 SDK 的源代码版本、CLI（适用语言）、项目配置、锁文件和测试期望统一为 `0.5.6`。
+- 增加 peer 身份回源、历史证书、group.index、索引项 ETag、agent.md 无效签名不落盘、消息窗口、inline pull 回退、mention mode、self-sync/bootstrap、transport 竞态和显式 change-seed 测试。
+- Python 覆盖完整 Push facade 和 Mock Push；Go 使用共享 Push 合同向量与状态机测试；TypeScript 和浏览器 JavaScript 不声明本版本没有提供的 Push facade。
+
+相关实现级对齐说明见 [Python SDK 变更清单](../../python/CHANGES_FOR_PARITY.md)。

package/_packed_docs/sdk/INDEX.md

@@ -10,18 +10,18 @@
 |------|------|
 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源 · 下载提交前验签 · 消息窗口 · 显式 change-seed · 语言能力边界 |
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
-| [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · Capabilities 能力声明 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · A/T/H 消息窗口 · 三 Pull Gate · 九态状态机 · E2EE |
-| [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · Python Push 自动登记 · 网关发现 · 事件 · agent.md 自动观察 |
+| [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · Capabilities 能力声明 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
+| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · A/T/H 消息窗口 · 每个 AUNClient 一个 Pull Gate · 九态状态机 · E2EE |
+| [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 当前 access token getter · Python Push 自动登记 · 网关发现 · 事件 · agent.md 自动观察 |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE V2 消息 · ProtectedHeaders · agent.md 版本提示 · recipient wrap |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
-| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · Python PushFacade · Message/Group History 门面 · 事件 · E2EE 高级 API · RPC 索引 |
+| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 四 SDK access token getter · Python PushFacade · Message/Group History 门面 · 事件 · E2EE 高级 API · RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
-| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 消息同步/History · Pull Gate · group.index · 测试数据保护 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 消息同步/History · AUNClient 级 Pull Gate（始终单飞）· group.index · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC（含 Forward Pull、`message.history`、Piggy ACK、实时推送内联载荷） |
 | [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 Group Forward 成员可见性 floor、`group.history`、`mention_mode`、`group.index`、`group.fs.*` 和角色 ACL） |
-| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
+| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token）· 数据面 HTTP 下载与 Bearer/ticket 边界 |
 | [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
 | [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区角色 ACL、`parents` 和 JS string 语义 |
 | [group.fs POSIX 化分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md) | group.fs 重构的 IPO、Step-by-step、用例集、Checklist、验收和回滚 |
@@ -40,17 +40,17 @@
 
 - AID 格式、证书、不可变值对象 → [03-核心概念](03-核心概念.md)
 - `AIDStore.register()` / `load()` / `exists()` / `resolve()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
-- agent.md 上传/下载/检查、`remote_etag` / `last_modified` 自动观察、`requester` / `peer` / `group` 角色 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[远程 agent.md 缓存与 ETag 透传方案](../agent.md/远程agent.md缓存与etag透传方案.md)
+- agent.md 上传/下载/检查、`remote_etag` / `last_modified` 自动观察、`requester` / `peer` / `group` 角色 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[远程 agent.md 缓存与 ETag 透传方案](../agent.md/远程agent.md缓存与etag透传方案.md)
 - AID 构造约束与多语言入口 → [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md)
-- 认证链路和 token → [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md)
+- 认证链路、后台刷新和当前 token getter（`get_access_token()` / `getAccessToken()` / `GetAccessToken()`）→ [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - AID 托管恢复 / 跨设备复制 → [09-custody-api-manual](09-custody-api-manual.md)
 
 ### 连接与状态
 
 - 九态状态机、device_id / slot_id 隔离键 → [03-核心概念](03-核心概念.md)
 - `connect()` 选项、长短连接、网关发现 → [04-连接与认证](04-连接与认证.md)
-- capability getter、事件、生命周期 API → [06-API手册](06-API手册.md)
-- Capabilities 能力声明、`inline_realtime_payload_v1` 实时推送优化 → [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md)
+- capability getter、事件、生命周期 API → [06-API手册](06-API手册.md)
+- Capabilities 能力声明、`inline_realtime_payload_v1` 实时推送优化 → [02-WebSocket协议](02-WebSocket协议.md)、[CHANGELOG-0.5.6](CHANGELOG-0.5.6.md)
 - 裸 WebSocket 握手 → [02-WebSocket协议](02-WebSocket协议.md)
 
 ### E2EE
@@ -66,11 +66,11 @@
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - Python `connect()` 携带 `push_notify_aid/push_token` 自动登记，以及 `client.push.register/unregister` 运行期变更 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、`docs/protocol/15-离线推送通知协议.md`
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
-- A/T/H 实时窗口、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进 → [03-核心概念](03-核心概念.md)、[05-E2EE加密通信](05-E2EE加密通信.md)、[08-最佳实践](08-最佳实践.md)
+- A/T/H 实时窗口、页内唯一有序发布、应用层跨页幂等排序、每个 AUNClient 一个 Pull Gate（始终 single-inflight、相同 key 折叠、不同 key 排队、前台 FIFO 优先）、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进 → [03-核心概念](03-核心概念.md)、[05-E2EE加密通信](05-E2EE加密通信.md)、[08-最佳实践](08-最佳实践.md)
 - Message Forward/History/Piggy ACK → [09-message-rpc-manual](09-message-rpc-manual.md)
-- Group Forward/History、群提及过滤 `mention_mode`、`group.index`、群文件系统 `group.fs.*` 和角色 ACL → [09-group-rpc-manual](09-group-rpc-manual.md)
+- Group Forward/History、群提及过滤 `mention_mode`、`group.index`、群文件系统 `group.fs.*` 和角色 ACL → [09-group-rpc-manual](09-group-rpc-manual.md)
 - 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
-- Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>)
+- Storage 架构、SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<../aun-fs/AUN Storage架构设计.md>)
 - Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / `storage.fs.touch` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
 - Collab RPC（`collab.*` 版本化文档、乐观锁、标签、GC、reflog、revert）→ [09-collab-rpc-manual](09-collab-rpc-manual.md)
 - Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
@@ -82,7 +82,7 @@
 
 - Result 与异常层级 → [07-错误处理](07-错误处理.md)
 - 重试策略 → [07-错误处理](07-错误处理.md)
-- 幂等连接、多 AID、资源清理 → [08-最佳实践](08-最佳实践.md)
+- 幂等连接、多 AID、资源清理 → [08-最佳实践](08-最佳实践.md)
 - 集成 / E2E 运行顺序 → [../aun测试运行指南.md](../aun测试运行指南.md)；分布式 worktree 测试 → [../aun分布式测试运行指南.md](../aun分布式测试运行指南.md)
 
 ---
@@ -99,15 +99,15 @@
 
 ### 02-WebSocket协议
 
-说明 Gateway WebSocket 握手、Capabilities 能力声明（含 `inline_realtime_payload_v1` 实时推送优化）、JSON-RPC 请求/响应/通知格式，以及裸 WebSocket 客户端如何借助 SDK 完成 token 获取。
+说明 Gateway WebSocket 握手、Capabilities 能力声明（含 `inline_realtime_payload_v1` 实时推送优化）、JSON-RPC 请求/响应/通知格式，以及裸 WebSocket 客户端如何借助 SDK 完成 token 获取。
 
 ### 03-核心概念
 
-解释 AID 身份、三主体职责、device_id / slot_id 隔离键、A/T/H 实时消息窗口、三 Pull Gate、九态状态机、默认 E2EE 行为和 RPC/事件模型。
+解释 AID 身份、三主体职责、device_id / slot_id 隔离键、A/T/H 实时消息窗口、每个 AUNClient 一个 Pull Gate、九态状态机、默认 E2EE 行为和 RPC/事件模型。
 
 ### 04-连接与认证
 
-描述 `AIDStore` 注册加载、`AUNClient` 身份加载、显式认证、连接选项、Python `connect()` 的 Push 自动登记、长短连接共存、网关发现、agent.md 上传/下载/检查，以及连接后从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 自动观察远端版本。
+描述 `AIDStore` 注册加载、`AUNClient` 身份加载、显式认证、当前 access token getter、连接选项、Python `connect()` 的 Push 自动登记、长短连接共存、网关发现、agent.md 上传/下载/检查，以及连接后从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 自动观察远端版本。
 
 ### 05-E2EE加密通信
 
@@ -115,23 +115,23 @@
 
 ### 06-API手册
 
-列出 AIDStore、AID、AUNClient、Python PushFacade、Message/Group History 门面、事件、agent.md、ServiceProxyClient、E2EE 高级 API、Group Index facade 和 RPC 手册索引。
+列出 AIDStore、AID、AUNClient（含四 SDK 当前 access token getter）、Python PushFacade、Message/Group History 门面、事件、agent.md、ServiceProxyClient、E2EE 高级 API、Group Index facade 和 RPC 手册索引。
 
 ### 07-错误处理
 
-说明 Result 字典、AUNError 异常层级、错误码映射、重试策略、`group.index etag conflict` CAS 冲突处理和常见错误场景。
+说明 Result 字典、AUNError 异常层级、错误码映射、重试策略、`group.index etag conflict` CAS 冲突处理和常见错误场景。
 
 ### 08-最佳实践
 
-给出幂等加载身份、连接、关闭、多 AID 管理、Flow Control、A/T/H 实时同步、History 翻页、Piggy ACK、Group Index 更新和测试数据保护建议。
+给出幂等加载身份、连接、关闭、多 AID 管理、Flow Control、A/T/H 实时同步、History 翻页、Piggy ACK、Group Index 更新和测试数据保护建议；每个 AUNClient 的 Pull Gate 始终单飞。
 
 ### 09-*-rpc-manual
 
-各业务服务的 RPC 参数、响应和错误语义。Message/Group RPC 覆盖 History、Forward/Piggy ACK 和 Group Event 独立游标；SDK 自动最新页同步属于核心概念，不作为应用可调用 RPC 参数；其他手册覆盖 Storage、Collab、Group FS、Service Proxy 等领域。
+各业务服务的 RPC 参数、响应和错误语义。Message/Group RPC 覆盖 History、Forward/Piggy ACK 和 Group Event 独立游标；SDK 自动最新页同步属于核心概念，不作为应用可调用 RPC 参数；其他手册覆盖 Storage、Collab、Group FS、Service Proxy 等领域。
 
 ### AUN Storage架构设计
 
-定义 AUN Storage 的 SDK VFS、low-level storage client、Storage Service、Storage Core、Metadata Engine 和 Blob Backend 分层。文档明确主数据流量直连 backend、控制面走 `storage.*` RPC，底层 session/ticket/complete RPC 继续保留，但普通应用通过 SDK VFS 获得类 POSIX 文件操作语义；同时定义类 Linux mode/ACL、目录 `x` 位、mount/unmount、symlink/readlink/lstat、share link 与 direct backend ticket 的授权边界，并给出上传、下载、rename/move、delete/GC、路径解析和鉴权的 Mermaid 时序图。
+定义 AUN Storage 的 SDK VFS、low-level storage client、Storage Service、Storage Core、Metadata Engine 和 Blob Backend 分层。文档明确主数据流量直连 backend、控制面走 `storage.*` RPC，底层 session/ticket/complete RPC 继续保留，但普通应用通过 SDK VFS 获得类 POSIX 文件操作语义；同时定义下载 ticket 与 AID Bearer 的凭据边界、跨 issuer 下载和当前 token getter 用法、类 Linux mode/ACL、目录 `x` 位、mount/unmount、symlink/readlink/lstat、share link 与 direct backend ticket 的授权边界，并给出上传、下载、rename/move、delete/GC、路径解析和鉴权的 Mermaid 时序图。
 
 ### 09-collab-rpc-manual