@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/_packed_docs/protocol/index.md

@@ -16,13 +16,14 @@
 | 05 | [05-Relay-子协议.md](05-Relay-子协议.md) | `relay.*` 中继注册转发、透明封装、与 peer.* 关系 |
 | 06 | [06-服务协议.md](06-服务协议.md) | 业务层：message.* / meta.* / search.* / task.* / group.* + 跨域消息路由 |
 | 07 | [07-错误码与状态机.md](07-错误码与状态机.md) | 错误码汇总、各模式状态机、重试分类 |
-| E2EE | [08-AUN-E2EE.md](08-AUN-E2EE.md) | Legacy P2P E2EE 信封说明；当前默认主路径见 SDK V2 多设备 wrap 文档 |
+| E2EE | [08-AUN-E2EE.md](08-AUN-E2EE.md) | Legacy P2P E2EE 信封说明；当前默认主路径见 SDK V2 多设备 wrap 文档 |
 | E2EE-Group | [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE V2：消息级密钥、逐设备密钥包裹、成员状态签名验证 |
 | 09 | [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、升级安全、验签时序 |
 | 10 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、`group.index` 签名索引、邀请码、资源共享、在线状态 |
-| 11 | [11-Storage-子协议.md](11-Storage-子协议.md) | `storage.*` 对象存储、大文件上传下载、预签名 URL |
-| 12 | [12-Stream-子协议.md](12-Stream-子协议.md) | `stream.*` 实时流式传输、WebSocket 推流、HTTP SSE 拉流、跨域拉流 |
-| 15 | [15-离线推送通知协议.md](15-离线推送通知协议.md) | `push.*` 离线推送、push_notify_aid 代理、事件通知 + 背压 ack、白名单与去重 |
+| 11 | [11-Storage-子协议.md](11-Storage-子协议.md) | `storage.*` 对象存储、大文件上传下载、预签名 URL |
+| 12 | [12-Stream-子协议.md](12-Stream-子协议.md) | `stream.*` 实时流式传输、WebSocket 推流、HTTP SSE 拉流、跨域拉流 |
+| 13 | [13-Agent行为规范.md](13-Agent行为规范.md) | Agent 自主模式行为规范、收发方义务、`mention_mode` 与 channel 层过滤边界 |
+| 15 | [15-离线推送通知协议.md](15-离线推送通知协议.md) | `push.register/unregister/ack`、SDK connect 自动登记、installation delivery、持久恢复与安全边界 |
 | 16 | [16-系统目录保护方案.md](16-系统目录保护方案.md) | `memberdata` 与 `group_data` 的系统目录保护、目录树隐藏/读下载/写保护边界、配额归属和访问矩阵 |
 
 **附录**：A-术语表 | B-扩展性 | C-私钥管理 | D-Root CA 治理 | E-Root CA 准入 | F-Issuer CA 申请 | G-孤儿 AID | H-Auth 实现 | I-跨域消息路由 | J-客户端接入 | K-Agent Web | L-E2EE 实现 | M-JWT 实现
@@ -53,11 +54,13 @@
 | 任务协作（task.*） | 06 §6.5 |
 | 跨域消息路由 | 06 §6.7 |
 | E2EE 端到端加密 | AUN-E2EE, 06 §6.6 |
-| 群组管理（group.*） | 10 |
-| 群索引（group.index / _meta.group_indexes / CAS） | 10 §10.13 |
+| 群组管理（group.*） | 10 |
+| 群索引（group.index / _meta.group_indexes / CAS） | 10 §10.13 |
 | 群消息收发（group.send/pull） | 10 §10.6 |
-| 群成员权限（owner/admin/member） | 10 §10.2 |
-| 邀请码（group.create_invite_code） | 10 §10.7 |
+| 群成员权限（owner/admin/member） | 10 §10.2 |
+| 群提及过滤（mention_mode） | 10 §10.2.3, 13 §13.8 |
+| Agent 自主行为与响应义务 | 13 |
+| 邀请码（group.create_invite_code） | 10 §10.7 |
 | 群文件系统（group.fs.*） | 10 §10.9 |
 | 系统目录保护（memberdata / group_data） | 16 |
 | 对象存储（storage.*） | 11 |
@@ -66,11 +69,11 @@
 | 拉流（HTTP SSE） | 12 §12.6 拉流端点 |
 | 跨域拉流 | 12 §12.7 |
 | 离线推送通知 | 15 |
-| push_notify_aid 推送代理 | 15 §2, §10.1 |
-| push_token 鉴权 | 15 §10 |
-| 推送背压与 in-flight | 15 §5 |
-| 推送去重与频控 | 15 §8.2, §8.4 |
-| 跨域推送 | 15 §7 |
+| push_notify_aid 推送代理 | 15 §2-3 |
+| push_token 鉴权 | 15 §3, §7, §10 |
+| 推送 ACK、重试与恢复 | 15 §8-9 |
+| 推送去重与频控 | 15 §7, §9 |
+| federation 与域边界 | 15 §10 |
 | 错误码 | 07 §7.1 |
 | 连接状态机 | 07 §7.3 |
 | 威胁模型与安全 | 09 |
@@ -100,13 +103,13 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 `relay.*` 3 个方法：register、forward、event/relay.message。Relay 职责边界（零信任笨管道）、透明封装规则、与 peer.* 配合完成端到端认证。
 
 ### 06-服务协议（业务层）
-认证后可用的业务方法：auth.*（身份管理）、ca.*（证书管理）、message.*（P2P 消息、E2EE V2 设备密钥/bootstrap、`payload.type` 负载类型）、meta.*（心跳、状态、受信根）、storage.*（文件存储）、group.*（群组）、mail.*（邮件）、stream.*（流式传输）、search.*（Agent 发现）、relay.*（中继）、peer.*（点对点）、task.*（协作任务）。同时列出 `pki.{issuer}` 与 `ct.{issuer}` 等公开 HTTP 端点入口。
+认证后可用的业务方法：auth.*（身份管理）、ca.*（证书管理）、message.*（P2P 消息、E2EE V2 设备密钥/bootstrap、`payload.type` 负载类型）、meta.*（心跳、状态、受信根）、storage.*（文件存储）、group.*（群组）、mail.*（邮件）、stream.*（流式传输）、search.*（Agent 发现）、relay.*（中继）、peer.*（点对点）、task.*（协作任务）。同时列出 `pki.{issuer}` 与 `ct.{issuer}` 等公开 HTTP 端点入口。
 
 ### 07-错误码与状态机
 错误码分层汇总（JSON-RPC 通用 + AUN 协议级 + Peer/Relay/Search/Task/升级扩展码）。三种连接模式状态机。任务状态机。可重试/不可重试分类。
 
 ### AUN-E2EE
-独立安全层，横跨三种连接模式。当前 SDK 主路径为 E2EE V2 多设备 wrap：P2P 使用 `e2ee.p2p_encrypted`，Group 使用 `e2ee.group_encrypted`；正文一消息一密钥，按 recipient 设备生成 `3DH` / `1DH` wrap，并由接收端验证 `sender_signature`、AAD 和 recipient proof / digest。旧 `prekey_ecdh_v2` / `long_term_key` 文档仅作为历史兼容材料保留。
+独立安全层，横跨三种连接模式。当前 SDK 主路径为 E2EE V2 多设备 wrap：P2P 使用 `e2ee.p2p_encrypted`，Group 使用 `e2ee.group_encrypted`；正文一消息一密钥，按 recipient 设备生成 `3DH` / `1DH` wrap，并由接收端验证 `sender_signature`、AAD 和 recipient proof / digest。旧 `prekey_ecdh_v2` / `long_term_key` 文档仅作为历史兼容材料保留。
 
 ### AUN-E2EE-Group
 群组端到端加密规范（V2，当前唯一在用版本）。每条消息使用独立随机密钥，接收方按设备分别持有密钥包裹（wrap），不依赖群级共享对称密钥。成员状态通过签名版本链（state_version/state_chain）记录，接收方可据此检测状态分叉或篡改。群组密文格式、AAD 防篡改、防重放保护。
@@ -116,15 +119,18 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 
 ### 10-Group-子协议
 `group.*` 命名空间完整协议规范。群组生命周期（create/suspend/resume/dissolve）、成员管理（add/kick/set_role/transfer_owner）、群消息（send/pull/ack、`payload.type` 负载类型）、`group.index` 签名索引与 `expected_index_etag` CAS、`_meta.group_indexes` 版本提示、入群申请与邀请码、群规则与公告、资源共享、在线状态、事件推送（group.created/changed/message_created）、错误码（-33001~-33009）。Group Service 作为独立 AID 持有者运行，Gateway/Message 不生成或改写 group index。
-
-### 11-Storage-子协议
+
+### 13-Agent行为规范
+定义 AUN 原生自主模式、收发方无强制响应义务、客户端 UI 约束，以及群 `mention_mode` 在 channel 层过滤消息与 Agent 自主决策之间的边界。
+
+### 11-Storage-子协议
 `storage.*` 命名空间完整协议规范。控制面与数据面分离（小对象内联 RPC，大对象预签名 URL HTTP 传输）、per-AID 隔离、对象键路径化、版本化 CAS 并发控制。方法：put_object / get_object / delete_object / list_objects / create_upload_session / create_download_ticket。
 
 ### 12-Stream-子协议
-`stream.*` 命名空间完整协议规范。控制面通过 JSON-RPC（stream.create / close / get_info / list_active）管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输。当前实现以 push/pull URL 中的 token 作为能力凭证，拉流可跨域使用，并支持 Late Joiner 回放、Last-Event-ID 断线续拉、空闲/离线超时自动关闭。
+`stream.*` 命名空间完整协议规范。控制面通过 JSON-RPC（stream.create / close / get_info / list_active）管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输。当前实现以独立 push/pull token 作为能力凭证，通过 Authorization/X-Stream-Token Header 传递，URL 不含凭据；拉流可跨域使用，并支持 Late Joiner 回放、Last-Event-ID 断线续拉、空闲/离线超时自动关闭。
 
 ### 15-离线推送通知协议
-目标 AID 全部设备离线时的推送机制。push_notify_aid 作为普通客户端 AID 连接 Gateway，通过 `event/push.offline_message` 事件接收推送摘要（仅元数据，不含正文），处理后回 `push.ack` RPC 释放 in-flight 槽位（默认 max_in_flight=1 串行确认，30s 超时不重试）。聚合机制：同一 target_aid 60s 冷却期内合并为一条推送（unread_count++、senders 去重追加）。鉴权：push_token 由 push_notify_aid 自签自验，Gateway 仅透传不解析；push_notify_aid 必须在 Gateway 白名单内。跨域：推送由目标 AID 所属域的 Gateway 触发，push_notify_aid 必须与目标 AID 同域。
+定义独立 Push Service 的外部协议。应用侧 `push_notify_aid` 对应线上 RPC 字段 `push_server_aid`；Python SDK 推荐在 `connect()` 中携带 `push_notify_aid/push_token`，由 SDK 建连后调用 `push.register`，运行期可用 `client.push.register/unregister` 变更。Push Service 按 installation 保存 registration，离线复核后生成稳定 delivery，向确定的 Push Server 长连接定向发送 `push.offline_message`，并用批次级 `push.ack`、持久 timeout、重试和重启恢复闭环。事件不含正文或密文，token 由 Push Server 自签自验；V1 不跨 federation，生产仍受 token 加密门限制。
 
 ### 16-系统目录保护方案
 定义 `memberdata` 与 `group_data` 的分层保护。`memberdata` 不是隐藏目录，但根和成员槽位根不可被普通文件操作破坏，group AID 命名空间下的普通 Storage 写入必须拒绝；`group_data` 是成员个人 Storage 内部真实根，Storage 服务端必须在目录树浏览中隐藏它，读/下载按普通 read 权限处理，写入、删除、重命名、挂载、授权和状态变更必须拒绝。文档同时规定 `group_data` 空间计入真实 owner AID 配额，group.fs 是可信授权写入路径，并给出访问矩阵、生命周期、审计和测试验收要求。

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -55,17 +55,17 @@ sequenceDiagram
         "protocol": { "min": "1.0", "max": "1.0" },
         "device": { "id": "来自 ~/.aun/.device_id", "type": "desktop" },
         "client": { "slot_id": "slot-a" },
-        "delivery_mode": {
-            "mode": "queue",
-            "routing": "sender_affinity",
-            "affinity_ttl_ms": 300000
-        },
-        "options": { "kind": "long" },
-        "extra_info": { "app": "demo" },
-        "capabilities": {
-            "e2ee": true,
-            "group_e2ee": true
-        }
+        "delivery_mode": {
+            "mode": "queue",
+            "routing": "sender_affinity",
+            "affinity_ttl_ms": 300000
+        },
+        "options": { "kind": "long" },
+        "extra_info": { "app": "demo" },
+        "capabilities": {
+            "e2ee": true,
+            "group_e2ee": true
+        }
     }
 }
 ```
@@ -74,12 +74,12 @@ sequenceDiagram
 
 - `protocol.min/max` 在 `auth.connect` 阶段完成 Gateway 会话版本协商；详细规则见协议文档 `03-Gateway-连接模式.md`。
 - `device.id` 是设备级稳定标识，Python SDK 默认从 `~/.aun/.device_id` 读取。
-- `client.slot_id` 由应用层显式传入，用于区分同设备上的多个实例槽位。SDK 允许 `/`、`:`、空格作为隔离键分隔符，例如 `evolclaw cli`、`evolclaw/cli`、`evolclaw:cli` 的隔离键都是 `evolclaw`。
-- `delivery_mode` 决定该 AID 当前连接的投递语义；同一 AID 的所有在线连接必须保持一致。
-- `options.kind` 声明连接类型：`"long"`（默认）= 长连接，承担服务端推送 / 事件订阅；`"short"` = 短连接，仅用于发送 RPC 并等待响应即断开。同 `(aid, device.id, slotIsolationKey(client.slot_id))` 隔离槽下，长连接最多 1 条，短连接最多 10 条；短连接不会顶掉长连接。
-- `options.short_ttl_ms` 仅在 `kind="short"` 时有效，可选；服务端兜底超时后主动关闭短连接，防止占名额。
-- `extra_info` 是应用层自定义连接信息，可用于审计、踢人提示或排障；SDK 会过滤下划线开头的内部键。
-- `capabilities` 是客户端能力声明；`hello-ok.result.capabilities` 是服务端能力公告，不是双方能力交集。
+- `client.slot_id` 由应用层显式传入，用于区分同设备上的多个实例槽位。SDK 允许 `/`、`:`、空格作为隔离键分隔符，例如 `evolclaw cli`、`evolclaw/cli`、`evolclaw:cli` 的隔离键都是 `evolclaw`。
+- `delivery_mode` 决定该 AID 当前连接的投递语义；同一 AID 的所有在线连接必须保持一致。
+- `options.kind` 声明连接类型：`"long"`（默认）= 长连接，承担服务端推送 / 事件订阅；`"short"` = 短连接，仅用于发送 RPC 并等待响应即断开。同 `(aid, device.id, slotIsolationKey(client.slot_id))` 隔离槽下，长连接最多 1 条，短连接最多 10 条；短连接不会顶掉长连接。
+- `options.short_ttl_ms` 仅在 `kind="short"` 时有效，可选；服务端兜底超时后主动关闭短连接，防止占名额。
+- `extra_info` 是应用层自定义连接信息，可用于审计、踢人提示或排障；SDK 会过滤下划线开头的内部键。
+- `capabilities` 是客户端能力声明；`hello-ok.result.capabilities` 是服务端能力公告，不是双方能力交集。
 
 ### (3) hello-ok — 握手完成
 
@@ -111,7 +111,52 @@ sequenceDiagram
 
 ---
 
-## 消息格式
+## Capabilities（能力声明）
+
+### 客户端能力声明
+
+客户端在 `auth.connect` 时通过 `capabilities` 字段声明自身支持的特性。SDK 会自动填充以下能力：
+
+```json
+{
+    "capabilities": {
+        "e2ee": true,
+        "group_e2ee": true,
+        "supported_p2p_e2ee": ["e2ee_v2"],
+        "supported_group_e2ee": ["group_e2ee_v2"],
+        "inline_realtime_payload_v1": true
+    }
+}
+```
+
+| Capability | 说明 |
+|------------|------|
+| `e2ee` | 支持 P2P E2EE V2 加密通信 |
+| `group_e2ee` | 支持群组 E2EE V2 加密通信 |
+| `supported_p2p_e2ee` | 明确支持的 P2P 加密版本列表 |
+| `supported_group_e2ee` | 明确支持的群组加密版本列表 |
+| `inline_realtime_payload_v1` | **支持实时推送内联消息载荷**（0.5.6+ 新增） |
+
+### inline_realtime_payload_v1 详解
+
+**背景**：传统模式下，Gateway 推送 `event/message.received` 或 `event/group.message` 时只包含消息元数据（如 `from`、`seq`、`message_id`），客户端需要调用 `message.pull` 或 `group.pull` 拉取完整载荷。
+
+**优化**：声明 `inline_realtime_payload_v1: true` 后，Gateway 会在事件通知中直接内联完整的 `payload`、`envelope` 等字段，客户端无需额外 RPC 调用即可获取消息内容。
+
+**好处**：
+- **降低延迟**：消息到达即可处理，无需等待 pull RPC 往返
+- **减少请求**：对于实时在线场景，可完全避免 pull 调用
+- **保留回退**：离线消息和历史消息仍通过 pull 机制拉取，确保可靠性
+
+**SDK 行为**：Python/Go/JS/TS SDK 自动声明此能力；应用层无需感知，事件回调中始终能获取完整消息。
+
+### 服务端能力公告
+
+`hello-ok.result.capabilities` 返回服务端支持的特性，客户端可根据此信息调整行为。服务端和客户端的 capabilities **不是交集协商**，而是各自独立声明。
+
+---
+
+## 消息格式
 
 所有消息遵循 JSON-RPC 2.0 格式，通过以下规则区分类型：
 

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -57,6 +57,28 @@ SDK 在 `message.pull` / `message.ack` 中自动注入当前 `device_id` / `slot
 
 ---
 
+## 消息实时窗口与历史拉取
+
+P2P Message 和 Group Message 都在原 Forward Cursor 上维护三个本地持久化水位：
+
+| 水位 | 含义 |
+|------|------|
+| `A / ack` | Forward 已扫描到的最大 seq，也是唯一允许提交 ACK 的水位 |
+| `T / tail` | Tail 已扫描实时窗口的左边界 |
+| `H / head` | Tail 已扫描实时窗口的右边界 |
+
+收到 `head_server > H` 的 Push 通知时，SDK 内部自动拉取最新一页。最新页处理后若 `A < T - 1`，再执行一页后台 Forward；当 A 到达 `T - 1` 时自动折叠为 `A=T=H`。服务端原始页中的缺号视为永久空号，Forward 按页内最大 seq 推进 A，不再为页内缺号发起 Gap Fill。应用无需也不应构造内部最新页请求。
+
+Tail 和 Forward 的水位由通过校验的服务端原始页决定。单条解密失败或应用回调失败会产生诊断事件，但不会永久卡住 A/T/H。History 使用独立的 `message.history` / `group.history`，只解密并返回历史页，不修改 A/T/H、不 ACK、也不触发实时消息事件。
+
+冷启动缺少发送方 IK 时，SDK 会将同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；成功后立即重试当前消息解密，失败或超时才转入 pending 后台重试。这个有界阻塞只影响当前加密消息的首次处理，不改变“永久坏密文不阻塞 A/T/H”的规则。
+
+每个 `AUNClient` 只有一个客户端级 Pull Gate。P2P Message、Group Message、Group Event 的 Pull 都进入该 Gate；Gate 始终 single-inflight，相同请求 key 折叠并共享同一结果，不同 key 排队，前台 FIFO 优先于后台 FIFO。Message Tail/History 属于前台，Message Forward/Gap Fill 与 Group Event Pull 属于后台。Group Event 仍使用独立的 Forward Cursor，但不使用独立 Gate；不同 `AUNClient` 实例之间不共享 Gate。应用层直接正常 `await client.call(...)` 即可，无需自行实现重复并发控制。
+
+A/T/H 是服务端消息空间的扫描水位，不是应用层发布账本。SDK 只保证单个通过校验的 Tail/Forward 响应页内按 seq 升序、同 seq 最多发布一次；History 只解密返回，不进入实时发布流。Tail 与 Forward 的窗口可能重叠，因此跨 Push/Tail/Forward 页不保证唯一或有序。全局去重与排序属于应用业务仓库职责，不是 SDK 交付契约；应用必须在 namespace 内按 `message_id` 幂等，并按 `seq` 排序存储或展示。SDK 的进程内去重只能作为 best-effort 重叠折叠，不能替代应用持久化幂等。
+
+---
+
 ## 连接状态机
 
 ```mermaid

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

@@ -16,14 +16,14 @@ if not loaded["ok"]:
         raise RuntimeError(registered["error"]["message"])
     loaded = store.load(aid)
 
-me = loaded["data"]["aid"]
-client = AUNClient(me)
-await client.connect({"slot_id": "main", "auto_reconnect": True})
+me = loaded["data"]["aid"]
+client = AUNClient(me)
+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 和后台任务。
@@ -62,12 +62,12 @@ store = AIDStore(
 | `register(aid)` | 注册新 AID，返回 Result |
 | `list()` | 列出本地身份 |
 | `exists(aid)` | HEAD PKI 端点，判断 AID 是否已注册 |
-| `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()` |
-
+| `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()` |
+
 Result 使用方式：
 
 ```python
@@ -89,46 +89,52 @@ 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-下载流程)。
 
 ### 连接
 
 ```python
 await client.connect({
-    "slot_id": "main",
     "connection_kind": "long",
-    "delivery_mode": {"mode": "fanout"},
-    "background_sync": True,
-    "extra_info": {"app": "demo"},
     "auto_reconnect": True,
-    "heartbeat_interval": 30.0,
-    "token_refresh_before": 60.0,
-    "retry": {
-        "initial_delay": 1.0,
-        "max_delay": 64.0,
-    },
-    "timeouts": {
-        "connect": 5.0,
-        "call": 10.0,
-        "http": 30.0,
-    },
-})
+    "push_notify_aid": "push.example.com",
+    "push_token": "opaque-token",
+})
 ```
 
 | 选项 | 说明 |
 |------|------|
-| `slot_id` | 同一设备内的实例槽位；允许 `/`、`:`、空格作为共享隔离键分隔符 |
 | `connection_kind` | `"long"` 或 `"short"` |
 | `short_ttl_ms` | 短连接服务端兜底超时 |
 | `delivery_mode` | 连接级投递语义 |
@@ -136,9 +142,12 @@ await client.connect({
 | `background_sync` | 连接成功后是否执行 SDK 后台补洞 / 未读同步，默认开启 |
 | `auto_reconnect` | 断线后是否自动重连 |
 | `heartbeat_interval` | 心跳间隔，秒 |
-| `token_refresh_before` | token 过期前刷新提前量，秒 |
-| `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
-| `timeouts.connect/call/http` | 连接、RPC、HTTP 超时 |
+| `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
+| `connect_timeout` / `call_timeout` | 连接和 RPC 超时，秒 |
+| `push_notify_aid` / `push_token` | Python SDK 推荐的离线推送登记入口；必须同时提供 |
+| `push_provider` / `push_app_id` | Python SDK 可选诊断字段 |
+
+`slot_id` 来自已加载的 AID，不是 `connect()` 选项。Python SDK 在 AUN 会话建立后把 `push_notify_aid` 映射为冻结 RPC 字段 `push_server_aid`，调用 `push.register` 登记当前 `(aid, device_id, slot_id)`；这些字段不会进入 `auth.connect`。登记失败时本次连接回滚并向调用方抛错。Go、TypeScript、JavaScript SDK 本轮未增加该便利入口。
 
 当前稳定实现为 Gateway 模式；Peer / Relay 仍是协议能力定义，SDK 连接层会明确返回未实现。
 
@@ -146,21 +155,21 @@ await client.connect({
 
 ## 长短连接共存
 
-同一 `(aid, device_id, slotIsolationKey(slot_id))` 隔离槽下允许 1 条长连接 + 最多 10 条短连接。`slot_id` 的第一个 `/`、`:` 或空格之前的部分是共享隔离键，因此 `evolclaw daemon`、`evolclaw cli`、`evolclaw/netcheck` 会共享 `evolclaw` 隔离槽。
+同一 `(aid, device_id, slotIsolationKey(slot_id))` 隔离槽下允许 1 条长连接 + 最多 10 条短连接。`slot_id` 的第一个 `/`、`:` 或空格之前的部分是共享隔离键，因此 `evolclaw daemon`、`evolclaw cli`、`evolclaw/netcheck` 会共享 `evolclaw` 隔离槽。
 
 长连接：
 
 ```python
-daemon = AUNClient(me)
-await daemon.connect({"connection_kind": "long", "slot_id": "main"})
+daemon = AUNClient(me)
+await daemon.connect({"connection_kind": "long"})
 daemon.on("message.received", lambda e: print(e["payload"]))
 ```
 
 短连接：
 
 ```python
-cli = AUNClient(me)
-await cli.connect({"connection_kind": "short", "slot_id": "main", "short_ttl_ms": 30000})
+cli = AUNClient(me)
+await cli.connect({"connection_kind": "short", "short_ttl_ms": 30000})
 await cli.call("message.send", {"to": peer, "payload": {"type": "text", "text": "hello"}})
 await cli.close()
 ```
@@ -173,8 +182,8 @@ await cli.close()
 
 注册、解析和认证会根据 AID 的 issuer 自动发现 Gateway：
 
-- 生产模式：优先 `https://{aid}/.well-known/aun-gateway`，失败后回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
-- 开发模式：优先 `gateway.{issuer}`，兼容没有泛域名的本地环境
+- 所有环境：优先 `https://{aid}/.well-known/aun-gateway`，让 AID URL 命中 nameservice；失败后才回退到 `https://gateway.{issuer}/.well-known/aun-gateway`
+- 开发模式只放宽本地 TLS 校验，不改变发现优先级
 
 `verify_ssl` 由 `AUN_ENV` / `KITE_ENV` 控制。`development`、`dev`、`local` 会关闭校验，其余情况开启。
 
@@ -193,11 +202,11 @@ print(client.can_connect, client.can_send, client.is_online)
 
 | 事件 | 说明 |
 |------|------|
-| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
-| `connection.error` | 连接、认证、重连错误 |
-| `token.refreshed` | token 自动刷新完成 |
-| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
-| `message.received` | 收到消息 |
+| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
+| `connection.error` | 连接、认证、重连错误 |
+| `token.refreshed` | token 自动刷新完成 |
+| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
+| `message.received` | 收到消息 |
 | `group.changed` | 群组事件 |
 | `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 
@@ -205,49 +214,49 @@ print(client.can_connect, client.can_send, client.is_online)
 
 ---
 
-## Agent Web / agent.md
-
-发布自己的 agent.md：
-
-```python
-uploaded = await store.upload_agent_md("alice.agentid.pub", content)
-```
-
+## Agent Web / agent.md
+
+发布自己的 agent.md：
+
+```python
+uploaded = await store.upload_agent_md("alice.agentid.pub", content)
+```
+
 `aid` 必须是本地 AID。上传由 `AIDStore` 读取本地私钥签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
 
-解析对端并验签 agent.md：
+解析对端并验签 agent.md：
 
 ```python
 resolved = await store.resolve("bob.agentid.pub")
-if resolved["ok"]:
-    print(resolved["data"]["agent_md"]["verification"]["status"])
-```
-
-只下载对端 agent.md：
-
-```python
-downloaded = await store.download_agent_md("bob.agentid.pub")
-```
-
-只检查本地缓存与远端状态：
-
-```python
-state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
-```
-
-当前公开入口分工固定：
-
-| 主体 | 公开能力 |
-|------|----------|
-| `AIDStore` | `upload_agent_md(aid, content=None)`、`download_agent_md(aid)`、`check_agent_md(aid, ttl_days=1)`、`resolve(aid, opts)` |
-| `AID` | `sign_agent_md(content)`、`verify_agent_md(content)` 低层签验能力 |
-| `AUNClient` | 连接、事件和 RPC 调用；不再暴露 agent.md 上传入口 |
-
-本地落盘位置由 SDK 管理。Python / TypeScript / Go 写入 `{aun_path}/AIDs/{aid}/agent.md` 和同目录 `agentmd.json`；浏览器 JavaScript 写入 IndexedDB 的等价 logical key，存储不可用时退化为内存缓存。agent.md 不写入 SQLite，也不再使用旧 `{aun_path}/AgentMDs` 目录。
-
-连接后的 RPC 响应、事件推送和消息信封会被 SDK 自动观察：Gateway `_meta.agent_md_etags` 中的 `requester`、`peer`、`group` 以及兼容别名 `receiver`、`target`、`to`、`sender`、`from` 会更新对应 AID 的 `remote_etag` / `last_modified`；V2 信封中的 `agent_md.sender` 和 `agent_md.group` 也会写入同一份本地记录。`group` 表示群自身 `group_aid` / `group_id` 的 agent.md，缺少 `aid` 时 SDK 会从信封顶层或 AAD 的 `group_aid` / `group_id` 兜底。
-
----
+if resolved["ok"]:
+    print(resolved["data"]["agent_md"]["verification"]["status"])
+```
+
+只下载对端 agent.md：
+
+```python
+downloaded = await store.download_agent_md("bob.agentid.pub")
+```
+
+只检查本地缓存与远端状态：
+
+```python
+state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
+```
+
+当前公开入口分工固定：
+
+| 主体 | 公开能力 |
+|------|----------|
+| `AIDStore` | `upload_agent_md(aid, content=None)`、`download_agent_md(aid)`、`check_agent_md(aid, ttl_days=1)`、`resolve(aid, opts)` |
+| `AID` | `sign_agent_md(content)`、`verify_agent_md(content)` 低层签验能力 |
+| `AUNClient` | 连接、事件和 RPC 调用；不再暴露 agent.md 上传入口 |
+
+本地落盘位置由 SDK 管理。Python / TypeScript / Go 写入 `{aun_path}/AIDs/{aid}/agent.md` 和同目录 `agentmd.json`；浏览器 JavaScript 写入 IndexedDB 的等价 logical key，存储不可用时退化为内存缓存。agent.md 不写入 SQLite，也不再使用旧 `{aun_path}/AgentMDs` 目录。
+
+连接后的 RPC 响应、事件推送和消息信封会被 SDK 自动观察：Gateway `_meta.agent_md_etags` 中的 `requester`、`peer`、`group` 以及兼容别名 `receiver`、`target`、`to`、`sender`、`from` 会更新对应 AID 的 `remote_etag` / `last_modified`；V2 信封中的 `agent_md.sender` 和 `agent_md.group` 也会写入同一份本地记录。`group` 表示群自身 `group_aid` / `group_id` 的 agent.md，缺少 `aid` 时 SDK 会从信封顶层或 AAD 的 `group_aid` / `group_id` 兜底。
+
+---
 
 ## RPC 调用
 

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -49,8 +49,12 @@ await client.call("message.send", {
 4. E2EE 信封包含 `sender_signature`、AAD、`recipients_digest` / Merkle proof，接收端必须验签、验 AAD、验 recipient proof 后再解密。
 
 每条消息独立密钥；V2 当前主路径不再使用旧 `prekey_ecdh_v2` / `long_term_key` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
-
-## ProtectedHeaders 与可验证上下文
+
+接收端校验签名需要发送方 IK。若本地 session 和 PKI 证书都没有目标 sender/device 的 IK，Python、TypeScript、Go、JavaScript SDK 会先给当前消息一次有界同步补救机会：同一发送端的并发请求通过 single-flight 合并，最多阻塞 3 秒调用 `message.v2.bootstrap`；群消息仍未命中时再调用 `group.v2.bootstrap`。获取成功后立即重试当前消息解密；获取失败或超时才进入原有 pending 后台重试，History 则返回结构化解密失败项而不进入实时 pending。该补救会增加少量首条消息延迟，但避免冷启动时“消息已 ACK、IK 稍后才到、当前消息无回调”。
+
+同步获取失败意味着当前时点仍不具备验签和解密条件，SDK 不伪造明文，也不因永久坏密文阻塞 Forward/Tail 水位。实时消息通过 `message.undecryptable` / `group.message_undecryptable` 暴露诊断；应用仍需按 `message_id` 幂等处理后续 pending 重试可能产生的补交付。
+
+## ProtectedHeaders 与可验证上下文
 
 `protected_headers` 是 E2EE 信封里的可选元数据字典，语义接近 HTTP headers：适合放 `device_id`、`slot_id`、`device_name`、`os`、`sdk_version`、`app_name` 等需要被接收端识别、且需要防篡改的非业务内容。`payload` 仍然类似 HTTP body，业务内容应放在 `payload` 内。