@agentunion/fastaun-browser 0.5.3 → 0.5.6

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

@@ -217,8 +217,8 @@ 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()
 ```
@@ -329,17 +329,22 @@ headers = client.get_protected_headers()
 | Collab | `client.collab` | `client.collab` | `client.Collab()` | 版本化文档、标签、`gc` / `reflog` / `revert` |
 | Group FS | `client.group.fs` | `client.group.fs` | `client.Group().FS()` | POSIX 风格群文件系统；`ls/find/stat/lstat/mkdir/rm/cp/mv/df/mount/umount`，以及 `set_acl/remove_acl/get_acl/list_acl` 角色 ACL 门面，上传下载数据面由 SDK 编排 |
 
-群文件系统路径统一使用 `group_aid:/...`，成员数据区使用 `group_aid:/memberdata/{member_ref}/...`。SDK 不拼接真实 storage 路径，`memberdata` 到成员 `group_data/{group_aid}` 的映射只在服务端完成。群自有区写入允许当前 `group_aid` 证书签名、默认 `role:owner`、以及 owner 通过 `group.fs.set_acl` 显式授权后的 `role:admin`；撤销使用 `group.fs.remove_acl`，查询使用 `group.fs.get_acl/list_acl`，这些角色 ACL 操作都要求当前 group owner 调用且对外权限位显示为 `rwx`。JS 浏览器版上传中 `string` 默认表示文本内容，Node 本地路径需显式 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀；Python/TS/Go 默认把 `string` 当本地路径。
+群文件系统路径统一使用 `group_aid:/...`，成员数据区使用 `group_aid:/memberdata/{member_ref}/...`。SDK 不拼接真实 storage 路径，`memberdata` 到成员 `group_data/{group_aid}` 的映射只在服务端完成。群自有区写入允许当前 `group_aid` 证书签名；成员角色中 `owner/admin` 默认可写群自有区，`member` 默认不可写。`owner/admin` 可通过 `group.fs.set_acl` 对特定业务目录授予 `role:member` 的 `rw` 权限，用于后续群协作场景；`rw` 只允许创建/写入，不授予删除、移动、重命名权限。`rwd` 是 storage 内部权限位，SDK/RPC 对外按 POSIX 视图显示为 `rwx`，不给删除/移动/重命名权限时只使用 `rw`。`.group/` 是系统控制目录，默认给 `owner/admin` 写权限，用于群公告、群规则、入群要求附件，不能向 `role:member` 授权。老群如果缺少 `.group/` 默认 ACL，group 服务会在该群首次被 RPC 访问时 best-effort 触发 namespace/ACL lazy repair；ACL 同步全部成功后才记录本进程已检查，失败会在后续访问继续重试。JS 浏览器版上传中 `string` 默认表示文本内容，Node 本地路径需显式 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀；Python/TS/Go 默认把 `string` 当本地路径。
 
 ### 消息与群组门面
 
 | 能力 | 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` 提供三个查询方法，适用不同场景：
 
@@ -347,15 +352,20 @@ headers = client.get_protected_headers()
 - `getInfo()` — 查询群组信息（扁平化格式，提升常用字段到顶层），**推荐外部使用**
 - `info()` — 查询群组详细信息（带权限控制，非成员只能看公开群，成员能看 seq/epoch 等运行时状态）
 
-**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法：
-
-- `getAnnouncement()` / `updateAnnouncement()` — 群公告
-- `getRules()` / `updateRules()` — 群规则
-- `getJoinRequirements()` / `updateJoinRequirements()` — 入群要求
-
-读取方法优先返回 SDK 本地缓存；本地没有对应值时才读取相应 settings 做初始化。便利读取从服务端拿到 canonical `group_aid` 后，会同时以 canonical `group_aid` 和本次入参 `group_id` 写入 settings cache，避免 legacy/base `group_id` 下一次读取直接 cache miss。即使 `checkGroupIndex` 观察到远端 etag 与本地 etag 不一致，`getAnnouncement()` / `getRules()` / `getJoinRequirements()` 也不会自动拉取远端版本覆盖本地缓存。`updateAnnouncement()` / `updateRules()` / `updateJoinRequirements()` 属于 indexed 写入，内部会调用 `updateGroupIndex` 生成签名 `group.index` 并带 `expected_index_etag` CAS 提交。
-
-**Group Index 高级同步方法**：`group.index` 是 SDK 内部签名 manifest，用于记录群公告、群规则、入群要求及附件稳定引用的版本。SDK 观察 `_meta.group_indexes` 后只记录远端 etag；etag 不一致只表示本地与观察到的远端版本不同，可能是远端更新，也可能是本地有未提交修改。应用层需要显式选择 pull 远端或 push 本地。
+**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法：
+
+- `getAnnouncement()` / `updateAnnouncement()` — 群公告
+- `getRules()` / `updateRules()` — 群规则
+- `getJoinRequirements()` / `updateJoinRequirements()` — 入群要求
+- `getSettingWithIndex()` / `updateSettingWithIndex()` — 通用文档型 indexed setting（Python 为 `get_setting_with_index()` / `update_setting_with_index()`，Go 为 `GetSettingWithIndex()` / `UpdateSettingWithIndex()`）
+
+读取方法优先返回 SDK 本地缓存；本地没有对应值时才读取相应 settings 做初始化。便利读取从服务端拿到 canonical `group_aid` 后，会同时以 canonical `group_aid` 和本次入参 `group_id` 写入 settings cache，避免 legacy/base `group_id` 下一次读取直接 cache miss。即使 `checkGroupIndex` 观察到远端 etag 与本地 etag 不一致，`getAnnouncement()` / `getRules()` / `getJoinRequirements()` / `getSettingWithIndex()` 也不会自动拉取远端版本覆盖本地缓存。`updateAnnouncement()` / `updateRules()` / `updateJoinRequirements()` / `updateSettingWithIndex()` 属于 indexed 写入，内部会调用 `updateGroupIndex` 生成签名 `group.index` 并带 `expected_index_etag` CAS 提交。
+
+`getSettingWithIndex()` / `updateSettingWithIndex()` 比三对预定义方法多一个 `keyName`（Python 可传 `key_name`，Go 同时接受 `keyName` / `key_name`）。SDK 会生成 `{keyName}.content` 和 `{keyName}.attachments` 两个 settings key；`keyName` 只能是受控文档名（`^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀）。`getRules()` / `updateRules()` 与 `getAnnouncement()` / `updateAnnouncement()` 是该通用方法在 `rules`、`announcement` 上的薄封装；`getJoinRequirements()` / `updateJoinRequirements()` 保持结构化 schema，不改成 `join.content`。
+
+这些 `update*` 便利方法只更新群设置元数据：`updateRules()` / `updateAnnouncement()` / `updateSettingWithIndex()` 写入 `*.content` 与 `*.attachments`，`updateJoinRequirements()` 写入 `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` / `join.attachments`。`attachments` 只保存稳定引用，附件实体应先上传到 group.fs 群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。
+
+**Group Index 高级同步方法**：`group.index` 是 SDK 内部签名 manifest，用于记录群公告、群规则、入群要求及附件稳定引用的版本。SDK 观察 `_meta.group_indexes` 后只记录远端 etag；etag 不一致只表示本地与观察到的远端版本不同，可能是远端更新，也可能是本地有未提交修改。应用层需要显式选择 pull 远端或 push 本地。
 
 | 语义 | Python | TS/JS | Go | 说明 |
 |------|--------|-------|----|------|
@@ -525,13 +535,14 @@ fmt.Printf("拉取成功，etag: %s\n", result["meta"].(map[string]any)["etag"])
 | `last_modified` | int | ❌ | 时间戳毫秒（默认 `Date.now()` / `time.time()*1000`） |
 | `max_attempts` | int | ❌ | CAS 冲突最大重试次数（默认 2） |
 
-**支持的 indexed settings keys**：
-
-- `rules.content` / `rules.attachments` — 群规则及附件
-- `announcement.content` / `announcement.attachments` — 群公告及附件
-- `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` — 入群要求
-
-**返回值**：
+**支持的 indexed settings keys**：
+
+- `rules.content` / `rules.attachments` — 群规则及附件
+- `announcement.content` / `announcement.attachments` — 群公告及附件
+- `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` / `join.attachments` — 入群要求及附件
+- `{keyName}.content` / `{keyName}.attachments` — 通用文档型 indexed setting；`keyName` 需满足 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀
+
+**返回值**：
 
 ```python
 {
@@ -600,13 +611,16 @@ console.log(`推送成功，新 etag: ${result._meta.group_indexes['g-team.agent
 
 ```go
 // Go - 更新入群要求
-result, err := client.Group().UpdateGroupIndex(ctx, map[string]any{
-    "group_id": "g-team.agentid.pub",
-    "settings": map[string]any{
-        "join.mode": "approval",
-        "join.question": "你是如何知道本群的？",
-    },
-})
+result, err := client.Group().UpdateGroupIndex(ctx, map[string]any{
+    "group_id": "g-team.agentid.pub",
+    "settings": map[string]any{
+        "join.mode": "approval",
+        "join.question": "你是如何知道本群的？",
+        "join.attachments": []any{
+            map[string]any{"type": "group.fs", "path": "/.group/attachments/join/guide.pdf"},
+        },
+    },
+})
 if err != nil {
     log.Fatal(err)
 }
@@ -618,11 +632,41 @@ fmt.Printf("推送成功\n")
 1. **权限要求**：写入 indexed settings 需要 admin 及以上权限
 2. **签名算法限制**：当前版本仅支持 ECDSA-P256-SHA256，使用其他算法的 AID 无法签名
 3. **CAS 冲突策略**：默认重试 2 次，高并发场景建议增加 `max_attempts`
-4. **`signer` 必须是当前连接身份**：服务端强制校验 `signed_by == actor_aid`，传入其他 AID 会被拒绝
-
----
-
-## ServiceProxyClient
+4. **`signer` 必须是当前连接身份**：服务端强制校验 `signed_by == actor_aid`，传入其他 AID 会被拒绝
+5. **附件字段只存引用**：`updateRules` / `updateAnnouncement` / `updateSettingWithIndex` 传入 `content` 和 `attachments` 元数据引用；`updateJoinRequirements` 传入结构化入群字段和 `attachments` 元数据引用。附件实体先上传到群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。群自有区默认允许 `owner/admin` 写入，`member` 默认不可写；`.group/` 不允许授予 `role:member` 写权限。
+
+---
+
+### 离线推送门面（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) 直接实现同等控制面和隧道消息。
 
@@ -691,8 +735,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 对象变更事件透传 |
 
 ---
 
@@ -718,13 +763,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/08-/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -94,14 +94,27 @@ SDK 内部自动管理 RPC 并发，应用层无需配置：
 |------|------|
 | RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
 | 后台 RPC 限制 | 后台任务额外限制为 8 个 |
-| Pull Gate | 同一 namespace/group 的 pull 操作自动序列化 |
-| 队列超时 | 排队超过 timeout 抛 `TimeoutError` |
+| Pull Gate | P2P Message、Group Message、Group Event 各一个 Gate；每个 Gate single-inflight |
+| 队列优先级 | Tail/History 前台 FIFO 优先于 Forward/Gap Fill 后台 FIFO；Group Event Pull 为后台；同 key 自动折叠 |
+| 队列超时 | 排队或等待折叠结果超过 3 秒时旁路 Gate 执行，不取消原请求 |
 
 应用层保持普通 `await client.call(...)` 即可。
 
 ---
 
-## 7. Group Index 更新流程
+## 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，拉到空页后停止。
+
+---
+
+## 8. Group Index 更新流程
 
 公告、规则、入群要求属于 indexed settings。owner/admin 修改这些内容时，不要直接裸调 `group.set_settings` 写单个 key，应使用 SDK facade 的 `updateGroupIndex` 语义。
 
@@ -113,11 +126,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 / 跨域测试。