@agentunion/fastaun 0.5.33 → 0.5.34

package/CHANGELOG.md

@@ -6,9 +6,37 @@
 
 ---
 
-## 0.5.33 — 未发布
+## 0.5.34 — 未发布
 
-按当前工作区未提交变更整理；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
+相对已发布的 `0.5.33` 整理当前工作区增量；四端接口、实现差异和服务依赖见 [Python parity 文档](../python/CHANGES_FOR_PARITY.md#v0534)。
+
+### EventService 多角色与持久化
+
+- 同一 AID 在同一 Bus 上可同时承担 `bus`、`pub`、`sub`；角色分别授权，Bus 自发自订仍需对应权限。
+- Bus 目录、白名单、有效授权和订阅，以及客户端目录、订阅意图和待发布记录使用 SQLite（浏览器端为 IndexedDB）持久化；重启加载后与后续注册、订阅配置合并。
+- 发布消息先持久化再入队；按 `none` 或 `accepted` 成功阶段确认后删除本地正文，关闭、未知结果或发送失败时保留；恢复沿用原 `event_id` 和 TTL，过期记录 `EXPIRED`。
+- 新增 `publications` / `subscriptions` 查询，按事件名汇总发布次数与时间，或返回当前有效的设备/slot 订阅关系；分页 token 绑定运行实例和查询范围。
+
+### 消息同步与连接
+
+- 增加历史补拉弹性辅助连接、同步策略通知、主/辅连接回退和持久/volatile 独立读取范围；同一 namespace 保持串行，不同 namespace 按共享预算并行。
+- 完善消息与群消息交付队列的容量、背压、游标、ACK、重复折叠及连接代际隔离；超页、限流和辅助连接回收按策略停止或回退，不丢失待拉责任。
+- 补充 `need_render`、设备/slot 定向投递和控制信封字段在发送、加密、解密及恢复路径中的一致传递。
+
+### E2EE、Storage 与工具
+
+- 对齐 P2P/群组 V2 E2EE 的发送、解密、控制类别和降级路径，完善低层加解密入口及跨 SDK 工具参数。
+- Storage VFS 补充条件读取、上传会话字段、实际 MIME/Content-Type 处理及读缓存边界；ACL 支持 `subject.ownership.owner_aid`／`scope` 与 `subject.card.type`／`exttype` 条件，并保留 `grantee_aids`／兼容 `grantee_aid`，写入和 ACL 变更精确失效相关缓存。
+- 更新 Service Proxy、AID/Ownership 辅助接口及错误映射的类型和 RPC 白名单覆盖。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时版本及测试引用统一为 `0.5.34`。
+- 增补 EventService 持久化、消息恢复、同步策略、Storage 缓存和 E2EE 回归测试；本条目不宣称已完成真实 Gateway 或跨域 E2E 验收。
+
+## 0.5.33 — 已发布
+
+本节记录 0.5.33 发布前相对 0.5.32 的增量；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
 
 ### 控制消息兼容与降级
 

package/README.md

@@ -1,5 +1,7 @@
 # AUN Protocol — Node.js SDK
 
+Version: **0.5.34** · Node.js **>= 22.16.0**. This README describes the current source; package publication and service deployment are separate.
+
 ## Overview
 
 AUN (Agent Union Network) defines a standard interface for secure communication between Agents — based on WebSocket + JSON-RPC 2.0, covering identity, authentication, messaging, and autonomous Agent interaction, without being tied to a single communication topology.
@@ -13,15 +15,9 @@ AUN (Agent Union Network) defines a standard interface for secure communication
 **AUN's Answer**:
 
 - **AID Identity**: Globally unique identifier in `{name}.{issuer}` format (e.g., `alice.agentid.pub`), based on X.509 certificate chain
-- **Three Connection Modes**: Gateway (standard access), Peer (point-to-point direct), Relay (relay forwarding), with consistent application-layer API
+- **Gateway Access**: The current SDK connects through Gateway. Peer and Relay are protocol topology definitions; selecting either mode returns a not-implemented error.
 - **Tool-use Visualization**: Native `tool_call` / `tool_result` payload types for visualizing an Agent's local tool-use process in IM/viewer clients (**not a cross-Agent capability invocation contract**)
 
-```
-                  ┌─ Gateway ──→ Standard access (browser/mobile/server)
-Agent A ← WSS → ─┤─ Peer ─────→ Point-to-point direct (same network/low latency)
-                  └─ Relay ────→ Relay forwarding (NAT traversal/lightweight deployment)
-```
-
 **This SDK** is the Node.js/TypeScript client implementation of the AUN protocol. Install with `npm install @agentunion/fastaun`.
 
 ---
@@ -34,31 +30,32 @@ npm install @agentunion/fastaun
 
 ## Quick Start
 
-```typescript
-import { AunClient } from '@agentunion/fastaun';
+Load an identity already registered in the application's local store. Identity registration and configuration are covered in the [API manual](../docs/sdk/06-API手册.md#aidstore).
 
-// Create client
-const client = new AunClient({
-  aid: 'alice.agentid.pub',
-  gatewayUrl: 'wss://gateway.agentid.pub',
-  dataDir: './data'
-});
+```typescript
+import { AIDStore, AUNClient } from '@agentunion/fastaun';
+
+const store = new AIDStore({ aunPath: './data', encryptionSeed: '' });
+const loaded = store.load('alice.agentid.pub');
+if (!loaded.ok) throw new Error(loaded.error.message);
+const client = new AUNClient(loaded.data.aid);
+client.on('message.received', (event) => console.log(event));
+await client.connect({ auto_reconnect: true });
+```
 
-// Connect
-await client.connect();
+Send business RPCs after connection; message encryption is handled by the SDK.
 
-// Send message
-await client.sendMessage({
+```typescript
+await client.call('message.send', {
   to: 'bob.agentid.pub',
-  content: 'Hello from Alice!'
-});
-
-// Receive messages
-client.on('message', (msg) => {
-  console.log('Received:', msg);
+  payload: { type: 'text', text: 'Hello from Alice!' },
 });
 ```
 
+Call `await client.close()` when the application finishes. Storage, TLS and slot configuration belong to `AIDStore`; `AUNClient` accepts an AID object or no argument, and `connect(options)` authenticates as needed.
+
+Event publishing and subscriptions use `client.EventService`; Bus starts locally and Pub/Sub authorize independently. See the [EventService integration guide](../docs/sdk/AUN事件发布订阅应用集成指南.md) for role coexistence and SQLite recovery.
+
 ## Features
 
 - ✅ AID-based identity authentication
@@ -71,7 +68,12 @@ client.on('message', (msg) => {
 
 ## Documentation
 
-For detailed documentation, visit: https://github.com/agentunion/aun-sdk-core
+- [Quick start and identity model](../docs/sdk/01-快速开始.md)
+- [Connection and authentication](../docs/sdk/04-连接与认证.md)
+- [Public API manual](../docs/sdk/06-API手册.md)
+- [P2P message RPC](../docs/sdk/09-message-rpc-manual.md)
+- [EventService integration and SQLite persistence](../docs/sdk/AUN事件发布订阅应用集成指南.md)
+- [Documentation index](../docs/sdk/INDEX.md)
 
 ## License
 

package/_packed_docs/CHANGELOG.md

@@ -6,9 +6,37 @@
 
 ---
 
-## 0.5.33 — 未发布
+## 0.5.34 — 未发布
 
-按当前工作区未提交变更整理；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
+相对已发布的 `0.5.33` 整理当前工作区增量；四端接口、实现差异和服务依赖见 [Python parity 文档](../python/CHANGES_FOR_PARITY.md#v0534)。
+
+### EventService 多角色与持久化
+
+- 同一 AID 在同一 Bus 上可同时承担 `bus`、`pub`、`sub`；角色分别授权，Bus 自发自订仍需对应权限。
+- Bus 目录、白名单、有效授权和订阅，以及客户端目录、订阅意图和待发布记录使用 SQLite（浏览器端为 IndexedDB）持久化；重启加载后与后续注册、订阅配置合并。
+- 发布消息先持久化再入队；按 `none` 或 `accepted` 成功阶段确认后删除本地正文，关闭、未知结果或发送失败时保留；恢复沿用原 `event_id` 和 TTL，过期记录 `EXPIRED`。
+- 新增 `publications` / `subscriptions` 查询，按事件名汇总发布次数与时间，或返回当前有效的设备/slot 订阅关系；分页 token 绑定运行实例和查询范围。
+
+### 消息同步与连接
+
+- 增加历史补拉弹性辅助连接、同步策略通知、主/辅连接回退和持久/volatile 独立读取范围；同一 namespace 保持串行，不同 namespace 按共享预算并行。
+- 完善消息与群消息交付队列的容量、背压、游标、ACK、重复折叠及连接代际隔离；超页、限流和辅助连接回收按策略停止或回退，不丢失待拉责任。
+- 补充 `need_render`、设备/slot 定向投递和控制信封字段在发送、加密、解密及恢复路径中的一致传递。
+
+### E2EE、Storage 与工具
+
+- 对齐 P2P/群组 V2 E2EE 的发送、解密、控制类别和降级路径，完善低层加解密入口及跨 SDK 工具参数。
+- Storage VFS 补充条件读取、上传会话字段、实际 MIME/Content-Type 处理及读缓存边界；ACL 支持 `subject.ownership.owner_aid`／`scope` 与 `subject.card.type`／`exttype` 条件，并保留 `grantee_aids`／兼容 `grantee_aid`，写入和 ACL 变更精确失效相关缓存。
+- 更新 Service Proxy、AID/Ownership 辅助接口及错误映射的类型和 RPC 白名单覆盖。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时版本及测试引用统一为 `0.5.34`。
+- 增补 EventService 持久化、消息恢复、同步策略、Storage 缓存和 E2EE 回归测试；本条目不宣称已完成真实 Gateway 或跨域 E2E 验收。
+
+## 0.5.33 — 已发布
+
+本节记录 0.5.33 发布前相对 0.5.32 的增量；四端接口、实现差异和服务依赖见 [parity 0.5.33](../python/CHANGES_FOR_PARITY.md#v0533)。
 
 ### 控制消息兼容与降级
 

package/_packed_docs/INDEX.md

@@ -1,6 +1,6 @@
 # AUN SDK Core 文档索引
 
-> 根级文档索引采用三层结构。Layer 1 用于快速定位，Layer 2 按主题交叉查找，Layer 3 给出重点文档摘要。SDK API 细节继续查看 `docs/sdk/INDEX.md`；P2P 保留共享 seq、按 sender 隔离游标，网络 Pull Gate 同 namespace 单飞、每客户端最多4个并行，末页独立 ACK。
+> 当前四 SDK 源码版本为 **0.5.34**，现行接口见 [SDK 索引](sdk/INDEX.md)、[API 手册](sdk/06-API手册.md)及各 RPC 手册；版本专题和 CHANGELOG 保留原版本。根级索引采用三层结构：Layer 1 快速定位，Layer 2 按主题查找，Layer 3 重点文档摘要。P2P 保留共享 seq、按 sender 隔离游标，网络 Pull Gate 同 namespace 单飞、每客户端最多4个并行，末页独立 ACK。
 
 ---
 
@@ -21,7 +21,9 @@
 | [AUN 服务 Go 化重构精细化源码审查](audit/AUN服务Go化重构精细化源码审查-20260718.md) | 10 个 AUN 服务的 Go/Python 调用链、字段、并发、安全与性能修复终审；开放 P0/P1/P2 已归零，并附 Claude 60+76 条复审映射、跨实例/资源边界修复和 Docker/Linux 2344 条 Python 回归证据 |
 | [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md) | Python / Go / TS / JS SDK AUNClient 内部拆分边界、执行步骤和验收矩阵 |
 | [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md) | AUNClient 完全门面化、ClientRuntime 单一状态源和四端分批迁移步骤 |
-| [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md) | Forward A/T/H 窗口、Group 成员可见性下界、Tail/History RPC、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和跨 SDK 验收门禁 |
+| [0.5.34 SDK 应用集成指南](sdk/0.5.34-SDK应用集成指南.md) / [开发与移植指南](sdk/0.5.34-SDK开发与移植指南.md) | 对照已发布 0.5.33：EventService 多角色、目录与发布队列持久化、实时目录、Storage 条件 ACL、Group FS、Service Proxy 及弹性补拉 |
+| [0.5.33 SDK 应用集成指南](sdk/0.5.33-SDK应用集成指南.md) / [开发与移植指南](sdk/0.5.33-SDK开发与移植指南.md) | 弹性补拉：应用面板配置/流程/故障边界 L404-464；四端用途认证、策略准入、共享预算与断线退主 L413-499；保留本版控制消息、Ownership和ACL专题 |
+| [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md) / [消息弹性补拉通道方案](消息弹性补拉通道方案.md) / [消息弹性补拉通道实施计划](消息弹性补拉通道实施计划.md) | Forward A/T/H 窗口、Group 可见性、Tail/History RPC、页内有序发布、跨页幂等排序、三 Pull Gate、缺 sender IK bootstrap及坏密文推进；弹性通道契约：本轮Gateway同AID＋设备最多授权1条、SDK按策略支持0..N（协议测试到2）、同namespace串行/跨namespace并行、history_sync、面板持久开关、断线退主、独立volatile与共享预算；实施计划L338-375为原额度历史证据（不证明新规则通过），新Gateway上限、四端策略行为和Ubuntu验收待完成 |
 | [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md) | `message.send` 秒级 TTL 钳制、持久/volatile 双游标、按 device 收件箱、隐藏 slot lease/ACK、文件 epoch、消息调试计数器与 payload type 分类、多实例/跨域和四 SDK 测试矩阵 |
 | [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md) | 待实施：三类消息、固定优先级、Gateway 设备能力权威与 TTL 回源缓存、独立 SEQ / cursor、旧 SDK 降级及 Owner 名片感知 |
 | [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) | 待实施：服务端强制限制、SDK 能力与柔性响应、旧端断连暂封、版本化恢复、控制台解封及验收 |
@@ -114,7 +116,7 @@
 - 分布式节点角色、节点启动、服务启动/停止、注册发现、配置恢复和重启后状态恢复 → [分布式 AUN 节点与服务启动流程](../../extensions/services/docs/分布式AUN节点与服务启动流程.md)
 - AUNClient 巨类拆分、内部组件边界、逐步迁移和验收矩阵 → [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md)
 - AUNClient 完全门面化、Runtime 状态归属、状态写入收口和四端分批实施 → [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md)
-- P2P/Group Message 的 A/T/H、Tail/History、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和分布式验收门禁 → [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md)
+- P2P/Group Message 的 A/T/H、Tail/History、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和分布式验收门禁 → [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md)；Gateway动态授权、主辅补拉、共享预算与通知回收 → [消息弹性补拉通道方案](消息弹性补拉通道方案.md)；双能力/history_sync、断线退主、面板持久化、Group分页补丁及S06/S08/S22、S07/S11/S16夹具、S13隔离定向测试、S15 cold SPK和S26本机准备状态、基础64/64已有通过attempt；后续resume2最终增量已保留身份更新Python/Go四桥、TS/JS四桥未变，707节点分段通过且两首败保留；缺省启用/显式关闭保留的Linux定向证据已补，完整E2E未签收，S05已运行未签收，S17反向8项P2P通过、Group首败仍核查，完整场景仍待验收 → [消息弹性补拉通道实施计划](消息弹性补拉通道实施计划.md)
 - P2P `message.send` TTL 内存缓存、持久/volatile 游标、device 收件箱、隐藏 slot lease/ACK、服务 epoch、消息调试计数器与 payload type 分类、跨 SDK/双域验收 → [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md)
 - 三类控制消息、设备能力持久化 / TTL 回源、SEQ / cursor 隔离、旧 SDK 投影及 agent.md Owner 感知 → [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md)
 - Gateway 陌生人 P2P 限额、双向互通状态、拒绝/屏蔽、Inbox 手动回填和 Console AID 对状态查询 → [陌生人拒绝协议详细设计](陌生人拒绝协议详细设计.md)、[TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md)
@@ -516,3 +518,15 @@ L5-121定义TS运行器、profile、三种凭证模式及23命令；L124-298说
 ### TS 注册自动绑定 Owner 的 E2E 验证代码
 
 [代码与运行方式](TS注册自动绑定Owner的E2E验证代码.md)：TS SDK 编译产物的 Node.js ESM 用例，覆盖注册意图、connect 自动发起 bind.request、owner 审批、双端锁定共识、NS/Storage 正文及 SHA；包含 agentid.cn 实测结果和私有探针/transport 范围。
+
+### 消息弹性补拉通道方案
+
+[方案正文](消息弹性补拉通道方案.md)（持续验收）：本轮Gateway同AID＋设备最多授权1条，SDK按策略支持0..N（协议测试到2），同namespace串行、跨namespace按授权/预算并行 L9-24；架构与认证 L40-101；Gateway策略/回收 L102-201；公平与顺序 L202-263；流程与兼容 L264-345；阶段状态 L357-400；面板开关 L420-440、双能力 L442-446、断线退主 L448-454；积压门槛、数量下界、短连接无unread hint及统计 L456-485。旧额度测试保留为历史，不证明新规则通过。
+
+### 消息弹性补拉通道实施计划
+
+[实施计划](消息弹性补拉通道实施计划.md)：交付/阶段 L6-159；四端验收 L212-235；旧额度验证证据 L338-375（不证明新规则）；本轮Gateway单辅助上限、SDK 0..N策略支持、namespace并发、积压门槛、短连接与统计验收 L377-399。新Gateway cap、四SDK新规则与Ubuntu Docker验收尚待完成。
+
+### 0.5.33 弹性补拉接入与移植
+
+[应用指南](sdk/0.5.33-SDK应用集成指南.md) L404-464：面板持久开关、无需新Client的补拉流程、暂停与断线退主、同版禁开及应用幂等；[移植指南](sdk/0.5.33-SDK开发与移植指南.md) L413-499：双能力/history_sync、发送前复核、消费预留、volatile主路径、真实辅助计数与回收；[连接协议](protocol/03-Gateway-连接模式.md)弹性专节及[Message](sdk/09-message-rpc-manual.md)/[Group](sdk/09-group-rpc-manual.md)分页段定义wire字段。

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -92,10 +92,10 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | TypeScript 接入跨设备已读未读、单调事件、`read_state_sync`、精确整数、映射状态和错误处理 | `docs/跨设备已读未读SDK集成指南.md` L1-207 |
 | 四端及其它语言 SDK 实现/移植、迁移重试、请求级批写、身份隔离、精确整数、本地完成事件和测试验收 | `docs/跨设备已读未读SDK实现移植指南.md` L1-331 |
 | 跨设备已读未读问题修复闭环、文档与四端 SDK 对齐、本轮隔离回归及历史 Docker 验证边界 | `docs/跨设备已读未读代码审查报告.md` L1-252 |
-| P2P peer 能力、完整轻量 pending peers/可选整体估计快照、目录/Pull逐页next_pending_seq/可靠commit后更新与每N次FIFO、peer ACK/slot 公共 S、need_render/页内计数、device 定向发送及 TTL volatile | `docs/sdk/02-WebSocket协议.md` L116-142；`docs/sdk/09-message-rpc-manual.md` L340-581、L738-751；`docs/sdk/06-API手册.md` |
+| P2P peer 能力、完整轻量 pending peers/可选整体估计快照、目录/Pull逐页next_pending_seq/可靠commit后更新与每N次FIFO、peer ACK/slot 公共 S、need_render/页内计数、device 定向发送及 TTL volatile | `docs/sdk/02-WebSocket协议.md` L116-142；`docs/sdk/09-message-rpc-manual.md` L340-583、L740-753；`docs/sdk/06-API手册.md` |
 | 当前实现的代码审查结论、P0/P1/P2 问题与跨语言差异 | `docs/消息同步与历史拉取代码审查问题清单.md` L3-207 |
 | 消息同步问题修复顺序与已排除误报 | `docs/消息同步与历史拉取代码审查问题清单.md` L208-229 |
-| SDK peer A/T/H、稀疏覆盖/前驱、human Tail、N=4 Gate、后台续拉、50k 内存去重/应用持久幂等与 History/ACK | `docs/sdk/03-核心概念.md` L60-80；`docs/sdk/05-E2EE加密通信.md` L33-59、L294-316；`docs/sdk/08-最佳实践.md` L89-116；`docs/sdk/09-message-rpc-manual.md` L340-581；`docs/sdk/09-group-rpc-manual.md` L1434-1508、L1717-1784 |
+| SDK peer A/T/H、稀疏覆盖/前驱、human Tail、N=4 Gate、后台续拉、50k 内存去重/应用持久幂等与 History/ACK | `docs/sdk/03-核心概念.md` L60-80；`docs/sdk/05-E2EE加密通信.md` L33-59、L294-316；`docs/sdk/08-最佳实践.md` L89-116；`docs/sdk/09-message-rpc-manual.md` L340-583；`docs/sdk/09-group-rpc-manual.md` L1434-1510、L1719-1786 |
 | 测试环境数据保护规则 | `docs/aun测试运行指南.md` L166-182 |
 | 默认单实例 Docker 服务端、Tester 和常规测试命令 | `docs/aun测试运行指南.md` L183-369、L586-1074 |
 | 断网依赖准备、Go 1.24 和 Tester 复用纪律 | `docs/aun测试运行指南.md` L124-165、L183-369、`docs/aun分布式测试运行指南.md` L335-503 |
@@ -156,8 +156,9 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 本轮 owner 关系实施及本地 Docker、单域、cross-SDK、双域 federation 回归中发现的非任务失败、根因、修复与验证 | `docs/agent.md/working/本地Docker测试Bug清单.md` |
 | SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
 | 四 SDK resolve opts、frontmatter 字段／类型；当前 ownership 输出与无 TTL 缓存 | 基础解析见 `docs/sdk/06-API手册.md` L86-203、`docs/sdk/04-连接与认证.md` L233-243；当前共识变更见 `python/CHANGES_FOR_PARITY.md` L19-47 |
-| 四 SDK Storage / Group FS 默认读缓存、省略策略或 TTL 默认 60 秒、显式限制、SHA 无正文免计次与 owner.md 普通/权威读取 | `docs/sdk/09-storage-rpc-manual.md` L129-170；`docs/sdk/06-API手册.md` L497-510；`docs/sdk/09-group-rpc-manual.md` L1586-1620 |
-| 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L96-125、`docs/sdk/06-API手册.md` L327-346、`docs/sdk/09-storage-rpc-manual.md` L690-734、`docs/sdk/09-group-rpc-manual.md` L1612-1618、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
+| 四 SDK Storage / Group FS 默认读缓存、省略策略或 TTL 默认 60 秒、显式限制、SHA 无正文免计次与 owner.md 普通/权威读取 | `docs/sdk/09-storage-rpc-manual.md` L129-170；`docs/sdk/06-API手册.md` L497-510；`docs/sdk/09-group-rpc-manual.md` L1588-1622 |
+| 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L96-125、`docs/sdk/06-API手册.md` L327-346、`docs/sdk/09-storage-rpc-manual.md` L690-734、`docs/sdk/09-group-rpc-manual.md` L1614-1620、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
+| 四 SDK 0.5.34 应用集成与开发移植专题、EventService 多角色和持久化、Storage 条件 ACL、Group FS、Service Proxy 及弹性补拉 | `docs/sdk/0.5.34-SDK应用集成指南.md`、`docs/sdk/0.5.34-SDK开发与移植指南.md`、`../python/CHANGES_FOR_PARITY.md#v0534` |
 | 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
 | 四 SDK 0.5.29 应用接入、共识输入输出、resolve、上传锁与恢复、四端移植 | [应用指南](sdk/0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；parity 当前 L15-87 |
 | 历史 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控 | `docs/sdk/0.5.28-SDK应用集成指南.md`：接入／消息 L5-95、凭证／组织 L96-137、Storage／Ownership L138-186、通知 L187-201、风控／升级 L202-228；`docs/sdk/0.5.28-SDK开发与移植指南.md`：校验 L7-36、共识 L37-62、wire L63-108、outbox L109-121、风控 L122-134、移植 L135-146；parity 历史 L88-172，公共共识规则以 0.5.29 为准 |
@@ -180,4 +181,9 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | collab Plan 2 Python SDK/CLI 与单域 E2E | `docs/aun-fs/collab/2026-06-12-collab协作层-plan2.md` L1-132 |
 | collab Plan 3 Go/TS/JS 与跨语言 E2E | `docs/aun-fs/collab/2026-06-12-collab协作层-plan3.md` L1-154 |
 | Notify 在线轻量通知 / 跨域 federation 方案 | `docs/sdk/Notify通知方案.md` |
+| 离线消息弹性补拉：Gateway当前0/1、SDK按策略0..N、namespace并发和共享预算 | [方案正文](消息弹性补拉通道方案.md)：当前Gateway同AID＋设备最多授权1条，SDK现有协议测试到2；同namespace串行、不同namespace按授权/预算并行 L9-24；认证 L40-101；策略与回收 L102-201；公平/顺序/背压 L202-263；面板开关 L420-440；断线退主 L448-454；积压门槛、无新增读取下界、短连接无unread hint及统计 L456-485。旧额度结果不证明本轮规则通过。 |
+| 弹性补拉实施与验收 | [实施计划](消息弹性补拉通道实施计划.md)：交付/阶段 L6-159；四端验收 L212-235；旧额度验证证据 L338-375（不证明新规则）；本轮Gateway单辅助上限、SDK 0..N策略支持、namespace并发、积压门槛、短连接与统计验收 L377-399。新Gateway cap、四SDK新规则与Ubuntu Docker验收尚待完成。 |
 
+0.5.34 SDK 专题：应用接入见 [0.5.34 应用指南](sdk/0.5.34-SDK应用集成指南.md)，四端共同契约见 [0.5.34 开发与移植指南](sdk/0.5.34-SDK开发与移植指南.md)，实现级差异见 [parity 0.5.34](../python/CHANGES_FOR_PARITY.md#v0534)。文档覆盖 EventService 多角色、SQLite/IndexedDB 持久化、durable outbox、实时目录、Storage 条件 ACL、Group FS、Service Proxy 和弹性补拉。
+
+0.5.33 弹性补拉专题：应用配置与流程见 [应用指南 L404-464](sdk/0.5.33-SDK应用集成指南.md)；四端共同实现见 [开发与移植指南 L413-499](sdk/0.5.33-SDK开发与移植指南.md)。索引三层入口见 [INDEX.md 的弹性补拉与0.5.33条目](INDEX.md)；连接认证/回收和Message/Group存储范围及页字节字段已同步到各手册。

package/_packed_docs/protocol/03-Gateway-/350/277/236/346/216/245/346/250/241/345/274/217.md

@@ -64,7 +64,7 @@ WebSocket 连接建立
   ← challenge（服务端推送 nonce）
   → auth.aid_login1 (可选，已有 token 时跳过)
   → auth.aid_login2 (可选)
-  → auth.connect(nonce, auth, protocol, device, client, delivery_mode, options, extra_info, capabilities)
+  → auth.connect(nonce, auth, protocol, device, client, delivery_mode, options, extra_info, capabilities)
   ← {status: "ok", protocol, identity, ...}
   → READY，进入 Gateway 业务态
 ```
@@ -93,13 +93,13 @@ WebSocket 连接建立
 | device.id | string | 推荐 | 设备唯一标识。SDK 默认从 `~/.aun/.device_id` 稳定读取 |
 | device.type | string | 推荐 | 设备类型（desktop/mobile/browser） |
 | client.slot_id | string | 否 | 同一 `device.id` 下的实例槽位。仅在 `device.id` 存在时可用 |
-| delivery_mode.mode | string | 否 | 连接级投递模式：`fanout` 或 `queue` |
-| delivery_mode.routing | string | 否 | 仅 `queue` 时有效：`round_robin` 或 `sender_affinity` |
-| delivery_mode.affinity_ttl_ms | integer | 否 | 仅 `queue + sender_affinity` 时有效，表示发送者粘性保持时长 |
-| options.kind | string | 否 | 连接类型：`long`（默认）或 `short` |
-| options.short_ttl_ms | integer | 否 | 短连接服务端兜底超时，仅 `kind="short"` 时有效 |
-| extra_info | object | 否 | 应用层自定义连接信息；SDK 会过滤下划线开头的内部键 |
-| capabilities | object | 否 | 客户端能力声明 |
+| delivery_mode.mode | string | 否 | 连接级投递模式：`fanout` 或 `queue` |
+| delivery_mode.routing | string | 否 | 仅 `queue` 时有效：`round_robin` 或 `sender_affinity` |
+| delivery_mode.affinity_ttl_ms | integer | 否 | 仅 `queue + sender_affinity` 时有效，表示发送者粘性保持时长 |
+| options.kind | string | 否 | 连接类型：`long`（默认）或 `short` |
+| options.short_ttl_ms | integer | 否 | 短连接服务端兜底超时，仅 `kind="short"` 时有效 |
+| extra_info | object | 否 | 应用层自定义连接信息；SDK 会过滤下划线开头的内部键 |
+| capabilities | object | 否 | 客户端能力声明 |
 | client | object | 否 | 客户端信息（名称、版本等） |
 
 **当前实现补充**：
@@ -264,4 +264,54 @@ WebSocket 连接建立后 **30 秒**内未完成 `auth.connect`，服务端关
 - 远端 Gateway 验证请求后转发到本域服务
 - **auth 管凭证，auth.connect 管连接**——两者职责不同
 
+## 弹性辅助连接与历史补拉
 
+主连接承接实时消息、控制通知及普通 RPC；SDK 可按需建立历史补拉辅助连接。辅助连接共享主 Client 的身份、解密、游标和应用分发状态，不再创建完整 Client。
+
+| 契约 | 要求 |
+| --- | --- |
+| `capabilities.elastic_connections_v1` | 通用弹性辅助连接能力；主连接和辅助连接均需协商 |
+| `capabilities.sync_channels_v1` | 历史补拉用途能力；与通用能力均协商成功后，才可申请该用途 |
+| `options.kind` / `options.purpose` | 辅助认证使用 `short` / `history_sync` |
+| `options.parent_connection_id` | 绑定有效主连接；AID、device、slot 必须一致 |
+| 控制面开关 | Gateway 的 `sync_channels_enabled` 默认开启，已有显式 `false` 保持关闭；通过现有配置修订和绑定持久化，在线动态应用 |
+
+辅助连接使用主 Client 当前的有效访问凭证完成 `auth.connect`，以响应的 `negotiated_capabilities` 为协商结果，不单独刷新 token。仅主辅均成功协商两种能力的 SDK 可用；本轮 Gateway 按开关与实时压力实际授权 `0/1`，压力可降为 0，关闭时为 0、开启时上限为 1；承接主连接的同一 Gateway 内，`(aid, device_id)` 跨 slot、主会话合计最多 1 条，当前不跨 Gateway 全局统计。不同设备分别计数，历史资源仍按 AID 汇总。此为本轮 Gateway 准入上限，不代表 SDK 协议能力上限；普通短连接继续沿原有用途工作，其它弹性用途需另行定义方法及额度。
+
+### 策略与请求信封
+
+历史请求通过主或辅助连接发送时，都携带外层元数据；不把它放进业务 `params`：
+
+```json
+{"jsonrpc":"2.0","id":"pull-1","method":"message.v2.pull",
+ "params":{"sender_aid":"alice.agentid.pub","storage_scope":"persistent","max_page_bytes":262144},
+ "_meta":{"sync":{"purpose":"history_sync","parent_connection_id":"main-1","has_pending":true}}}
+```
+
+Gateway 在认证响应、可触发 Pull 的事件及相关 RPC 响应中携带外层 `_meta.sync_policy`，也可主动通知恢复：
+
+| 策略字段 | 语义 |
+| --- | --- |
+| `parent_connection_id` | 当前主连接 ID |
+| `version` | 同一主会话内单调递增的正安全整数，最大 `9007199254740991` |
+| `max_aux_channels` | SDK 按策略支持 `0..N`（当前协议实现及测试覆盖到 2）；本轮 Gateway 实际下发 `0/1`、开启时最多 1；同一 Gateway 内 `(aid, device_id)` 跨 slot、主会话合计最多 1 条 |
+| `max_history_pull_inflight` | 主辅合计历史请求额度，`0..3` |
+| `max_page_bytes` | 单页 `result` 的 JSON 编码上限，`1024..786432` 字节；初始 256 KiB |
+| `max_history_inflight_bytes` | 主辅合计编码预留；初始 1 MiB |
+| `history_bytes_per_second` | 历史结果字节速率；`0` 表示暂停 |
+
+SDK 在处理 result/error/notification 前应用策略，忽略错误主连接、无效值和旧版本；缺少快照不解除既有约束。`max_aux_channels=0` 时可退回主连接；历史在途额度或速率为 `0` 时主连接也暂停。等待恢复不占用普通 RPC 额度，不轮询探测。
+
+### 通知回收与断线回退
+
+| 消息 | 作用 |
+| --- | --- |
+| `event/gateway.sync_policy_changed` | 主连接上的策略更新通知，外层携带 `_meta.sync_policy` |
+| `event/gateway.sync_channel_close` | 主连接上提前通知回收；参数含 `parent_connection_id`、`target_connection_id`、`reason`、`drain_timeout_ms` |
+| `gateway.sync_demand` | SDK 需求状态变化时发送 Notification，参数为主连接 ID 和 `has_pending`，不设周期需求心跳 |
+
+Gateway 优先回收已确认无需求的空闲辅助连接。SDK 退役目标连接、排空或取消未完成请求，主 Client 保持在线。辅助断线后不自动重连，也不因冷却结束补开；当前主会话及策略版本内记住故障，待补请求使用剩余期限回到主连接。只有新的策略明确重新授权或新的主会话协商，才可再申请辅助连接；重复同版本快照不解禁。
+
+完整页仍按原游标和应用消费流程提交，半页不提交或 ACK；旧主会话页面不得向新会话提交。同主会话里策略版本更新不否定已经合法接收的页。`storage_scope=volatile` 使用独立主连接 Pull 和 volatile cursor，不受历史暂停阻塞，也不推进持久水位。
+
+所有 Transport 共用总 RPC 16、background 8、event 4、pull 4；历史最多使用 3 个 pull 名额。SDK 按 `max_aux_channels` 策略使用辅助连接；同一 namespace 的网络 Pull 串行，不同 namespace 可在策略授权和共享预算允许时并行复用辅助连接，实际并发仍受上述预算及 Gateway 策略限制。本地历史按编码页上限的 8 倍预留，共享上限初始 8 MiB，并保留至解密、应用消费结束。详细规则以消息弹性补拉方案第 18 节及实施计划第 9.5 节为准。