@agentunion/fastaun-browser 0.5.4 → 0.5.8

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-下载流程)。
 
 状态值：
 
@@ -217,18 +220,18 @@ retry_backoff / reconnecting / connection_failed / closed
 Python：
 
 ```python
-auth = await client.authenticate()
-await client.connect({"slot_id": "main", "auto_reconnect": True})
+auth = await client.authenticate()
+await client.connect({"auto_reconnect": True})
 await client.disconnect()
 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 媒体类型上的结构化约定。
 
@@ -335,11 +338,16 @@ headers = client.get_protected_headers()
 
 | 能力 | Python | TS/JS | Go | 说明 |
 |------|--------|-------|----|------|
-| Message | `client.message` | `client.message` | `client.Message()` | 消息便利方法：`send()`、`pull()`、`ack()`、`recall()`、`queryOnline()` |
+| Message | `client.message` | `client.message` | `client.Message()` | 消息便利方法：`send()`、`pull()`、`history()`、`ack()`、`recall()`、`queryOnline()` |
 | Message Thought | `client.message.thought` | `client.message.thought` | `client.Message().Thought()` | P2P 思考内容：`put()`、`get()`（不持久化、不分配 seq、强制 E2EE） |
-| Group | `client.group` | `client.group` | `client.Group()` | 群组便利方法：`create()`、`send()`、`pull()`、`ack()`、群管理方法、群查询方法、群设置便利方法 |
-| Group Thought | `client.group.thought` | `client.group.thought` | `client.Group().Thought()` | 群思考内容：`put()`、`get()`（不持久化、不分配 seq、强制 E2EE） |
-| Stream | `client.stream` | `client.stream` | — | 流式数据：`createStream()`、`sendChunk()`、`endStream()`、`subscribeStream()` |
+| Group | `client.group` | `client.group` | `client.Group()` | 群组便利方法：`create()`、`send()`、`pull()`、`history()`、`ack()`、群管理方法、群查询方法、群设置便利方法 |
+| Group Thought | `client.group.thought` | `client.group.thought` | `client.Group().Thought()` | 群思考内容：`put()`、`get()`（不持久化、不分配 seq、强制 E2EE） |
+| Offline Push | `client.push` | — | — | Python SDK：登记/注销当前安装的 `push_notify_aid`，Push Server 处理批次后 ACK |
+| Stream | `client.stream` | `client.stream` | — | 流式数据：`createStream()`、`sendChunk()`、`endStream()`、`subscribeStream()` |
+
+`message.history` 和 `group.history` 使用 `before_seq` 排他上界向左翻页，下一页直接使用响应的 `next_before_seq`。History 只读，不推进实时 A/T/H、不 ACK、不触发实时消息事件。实时 Push 的最新页同步完全由 SDK 内部自动执行，再按 A/T/H 决定是否补一页 Forward；没有需要应用调用的 Tail 方法或参数。
+
+消息回调只提供页级语义：单个 Tail/Forward 响应页内按 seq 升序、同 seq 最多一次；跨 Push/Tail/Forward 页可能重复或乱序。A/T/H 不能用于判断某条消息是否已经回调。全局去重与排序不是 SDK 业务逻辑保证；应用仓库应以 `(namespace, message_id)` 做唯一键，并按 `seq` 排序。SDK 的进程内折叠仅是 best-effort 优化。
 
 **群查询方法**：`GroupFacade` 提供三个查询方法，适用不同场景：
 
@@ -631,8 +639,37 @@ fmt.Printf("推送成功\n")
 5. **附件字段只存引用**：`updateRules` / `updateAnnouncement` / `updateSettingWithIndex` 传入 `content` 和 `attachments` 元数据引用；`updateJoinRequirements` 传入结构化入群字段和 `attachments` 元数据引用。附件实体先上传到群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。群自有区默认允许 `owner/admin` 写入，`member` 默认不可写；`.group/` 不允许授予 `role:member` 写权限。
 
 ---
-
-## ServiceProxyClient
+
+### 离线推送门面（Python）
+
+应用启动时推荐把推送代理和 opaque token 交给 `connect()`：
+
+```python
+await client.connect({
+    "push_notify_aid": "push.example.com",
+    "push_token": token,
+})
+```
+
+SDK 先建立 AUN 会话，再调用 `push.register` 登记当前安装。`push_notify_aid` 是 SDK 公共名称，线上 RPC 字段仍是冻结契约中的 `push_server_aid`；它不会被透传给 `auth.connect`。
+
+运行期间更换 token 或停止推送时使用 facade：
+
+```python
+await client.push.register(push_notify_aid="push.example.com", push_token=new_token)
+await client.push.unregister()
+```
+
+- `register()` 可附带 `provider`、`app_id`；身份范围始终由 Gateway 注入的当前 `aid/device_id/slot_id` 决定，调用方不能伪造。
+- `unregister()` 幂等禁用当前安装，不删除历史 delivery。
+- `ack(batch_id, status)` 只供 Push Server 实现使用；V1 status 仅允许 `accepted`、`retryable_failure`、`permanent_failure`。
+- 本轮只修改 Python SDK；Go、TypeScript、JavaScript 尚无专用 Push facade。
+
+协议与可靠性边界见 `docs/protocol/15-离线推送通知协议.md`。
+
+---
+
+## ServiceProxyClient
 
 Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
 
@@ -701,8 +738,9 @@ sub.unsubscribe()
 | `message.ack` | 消息 ack |
 | `message.undecryptable` | P2P E2EE 解密失败 |
 | `group.changed` | 群组事件 |
-| `group.message_undecryptable` | 群 E2EE 解密失败 |
-| `storage.object_changed` | Storage 对象变更事件透传 |
+| `group.message_undecryptable` | 群 E2EE 解密失败 |
+| `push.offline_message` | Push Server 收到离线唤醒批次；普通终端无需订阅 |
+| `storage.object_changed` | Storage 对象变更事件透传 |
 
 ---
 
@@ -728,13 +766,14 @@ sub.unsubscribe()
 
 | 领域 | 手册 | 关键方法 |
 |------|------|----------|
-| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.ack` / `message.thought.*` |
-| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.v2.*` / `group.fs.*` |
+| 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.history` / `message.ack` / `message.thought.*` |
+| 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.pull` / `group.history` / `group.v2.*` / `group.fs.*` |
 | 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.fs.*` / `storage.volume.*` / ACL / token / share link |
 | 协作 | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) | `collab.ls-files` / `collab.show` / `collab.commit` / `collab.merge` / `collab.log` / `collab.diff` / `collab.clone` / `collab.prune` / `collab.gc` / `collab.reflog` / `collab.revert` / `collab.tag.*` / `collab.ls-remote` / `collab.unregister` |
 | 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |
-| Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
-| Service Proxy | [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` |
+| Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
+| Offline Push | `docs/protocol/15-离线推送通知协议.md` | `push.register` / `push.unregister` / `push.ack` / `push.offline_message` |
+| Service Proxy | [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` |
 
 ---
 

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

@@ -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,16 +92,28 @@ SDK 内部自动管理 RPC 并发，应用层无需配置：
 
 | 机制 | 说明 |
 |------|------|
-| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
-| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
-| Pull Gate | 同一 namespace/group 的 pull 操作自动序列化 |
-| 队列超时 | 排队超过 timeout 抛 `TimeoutError` |
-
-应用层保持普通 `await client.call(...)` 即可。
+| 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 自动折叠 |
+
+Gate 内始终保持单飞；相同 key 的调用共享同一结果，不同 key 按前台优先、队列顺序执行。应用层保持普通 `await client.call(...)` 即可，不应自行实现重复并发控制。
+
+---
+
+## 7. 消息同步与历史读取
+
+- V2 Push 只作为服务端 Head 通知。只要本地 H 落后，就先 Tail；Tail 后仍有未扫描 Gap 才执行一页后台 Forward。
+- 不要把回调成功当作 ACK 条件。SDK 按服务端原始页最大 seq 推进 Forward 水位；坏密文通过 `message.undecryptable` / `group.message_undecryptable` 单独处理。
+- 冷启动缺 sender IK 时允许 SDK 最多同步等待 3 秒 bootstrap；同发送端并发请求自动合并。成功后当前消息立即重试解密，失败或超时才 pending，不要在应用层并发重复拉取 IK。
+- SDK 只保证单个 Tail/Forward 响应页内按 seq 升序、同 seq 最多发布一次；A/T/H 只是扫描水位，不是发布账本。
+- 实时消息可能从 Push、Tail、Forward 重复到达，跨页、跨通道都不保证全局回调顺序。全局去重与排序由应用业务仓库负责，不属于 SDK 业务逻辑保证；业务仓库必须按 `(namespace, message_id)` 幂等，并按 seq 排序展示。SDK 进程内折叠只能作为 best-effort 优化。
+- 用 `message.history(before_seq=..., limit=...)` 或 `group.history(group_id=..., before_seq=..., limit=...)` 向左翻页；下一页直接复用响应的 `next_before_seq`。History 不影响实时游标和 ACK。
+- Forward Piggy ACK 保留：有待提交 ACK 时，非满页仍会再拉一页并携带 ACK，拉到空页后停止。
 
 ---
 
-## 7. Group Index 更新流程
+## 8. Group Index 更新流程
 
 公告、规则、入群要求属于 indexed settings。owner/admin 修改这些内容时，不要直接裸调 `group.set_settings` 写单个 key，应使用 SDK facade 的 `updateGroupIndex` 语义。
 
@@ -113,11 +125,11 @@ SDK 内部自动管理 RPC 并发，应用层无需配置：
 4. 调用 `updateGroupIndex`。SDK 会读取当前服务端 index、生成新签名 index，并带 `expected_index_etag` 调用 `group.set_settings`。
 5. 如果服务端返回 `group.index etag conflict`，说明提交基线已变化；应用层需要重新决定 pull、merge 或保留本地修改后再提交。
 
-`getAnnouncement`、`getRules`、`getJoinRequirements` 只读 SDK 本地缓存；本地没有对应值时才读取相应 settings 初始化缓存，不会因为 etag 不一致自动 pull 远端。`updateAnnouncement`、`updateRules`、`updateJoinRequirements` 已内置 indexed 写入路径。普通不进入 index 的设置，例如 `dispatch_mode`，仍可直接使用 `setSettings` / `set_settings` / `SetSettings`。
+`getAnnouncement`、`getRules`、`getJoinRequirements` 只读 SDK 本地缓存；本地没有对应值时才读取相应 settings 初始化缓存，不会因为 etag 不一致自动 pull 远端。`updateAnnouncement`、`updateRules`、`updateJoinRequirements` 已内置 indexed 写入路径。普通不进入 index 的设置，例如 `mention_mode`，仍可直接使用 `setSettings` / `set_settings` / `SetSettings`。
 
 ---
 
-## 8. 测试数据保护
+## 9. 测试数据保护
 
 - 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
 - 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。