@agentunion/fastaun 0.5.30 → 0.5.32

package/_packed_docs/sdk/0.5.32-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -0,0 +1,319 @@
+# AUN SDK 0.5.32 开发与移植指南
+
+面向四端 SDK 维护者和新语言移植者，说明相对已发布 0.5.31 的实现顺序、关键约束和验收方法。目标 0.5.32 尚未发布，本文按 2026-11-05 工作区整理；应用接线见 [0.5.32 应用集成指南](0.5.32-SDK应用集成指南.md)。
+
+## 1. 本版范围与实现分层
+
+源码对照提交为 `2df732673`。已核验 0.5.31 Python 发布包的 135 个源文件与其一致，TS／JS 各 11 个关键编译文件与其转译结果一致；Go 使用该仓库参考点，本轮未取得可核验的 0.5.31 远端 tag。详细增量与发布证据见 [parity 0.5.32](../../python/CHANGES_FOR_PARITY.md#v0532)。
+
+本版新增 EventService，调整分类消息恢复、RPC 后台隔离及 VFS Cache；群／组织通用共识、`message_classes_v2`、无 `scan_proof` ACK 和严格 CAS 已由 0.5.31 提供。
+
+```mermaid
+%%{init: {"theme":"base","flowchart":{"curve":"linear","nodeSpacing":26,"rankSpacing":34}}}%%
+flowchart TB
+    subgraph SDK["各 Agent 进程内的 SDK"]
+        direction TB
+        F["AUNClient 门面<br/>EventService · VFS / Storage"]:::entry
+        subgraph EVENT["事件逻辑"]
+            direction LR
+            P["Pub<br/>目录缓存 · 有界发布队列"]:::role
+            B["Bus<br/>授权 · 设备订阅 · 公平 fanout"]:::bus
+            S["Sub<br/>接收校验 · 应用交付"]:::role
+        end
+        V["VFS Cache<br/>资源索引 · 正文校验 · 写版本"]:::cache
+        T["公共传输层<br/>分类 Pull · RPC 预算 · deadline · E2EE"]:::entry
+        F --> P & B & S & V
+        P & B & S & V --> T
+    end
+    G["Gateway<br/>认证连接 · 可信 AID / device / slot · 转发"]:::infra
+    M["Message<br/>Bus 单实例租约 · 设备定向 TTL 收件箱"]:::infra
+    C["Credential<br/>登记 · 状态证明 · 撤销"]:::infra
+    R["Storage / Group<br/>对象 · 权威版本 · CAS"]:::infra
+    T --> G
+    G --> M & C & R
+    classDef entry fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
+    classDef role fill:#f0fdf4,stroke:#16a34a,color:#14532d
+    classDef bus fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
+    classDef cache fill:#fff7ed,stroke:#ea580c,color:#7c2d12
+    classDef infra fill:#f8fafc,stroke:#64748b,color:#0f172a
+```
+
+图中 Pub、Bus、Sub 通常属于不同 AID。每个 Client 按 `bus_aid` 保存绑定，同一 Bus 仅绑定一种角色；`close` 后角色约束保留，不同 Bus 可担任不同角色。Message 只维护唯一承接设备与通用定向收件箱；事件目录、权限、订阅表和分发算法都在 Bus SDK。
+
+| 实现层 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 公共门面 | `client.EventService` | `client.EventService` | `client.EventService()` |
+| 生命周期 | `start/drain/close/update_config` | `start/drain/close/updateConfig` | `Start/Drain/Close/UpdateConfig` |
+| 授权与目录 | `authorize/renew/catalog` | 同名 | `Authorize/Renew/Catalog` |
+| 发布结果 | `publish/wait_published/on_publish` | `publish/waitPublished/onPublish` | `Publish/WaitPublished/OnPublish` |
+| 订阅与应用交付 | `subscribe/unsubscribe/on_event/next_event` | `subscribe/unsubscribe/onEvent/nextEvent` | `Subscribe/Unsubscribe/OnEvent/NextEvent` |
+| 本地 Bus 管理 | `issue_grant/revoke_grant/stats` | `issueGrant/revokeGrant/stats` | `IssueGrant/RevokeGrant/Stats` |
+
+以下伪代码描述 SDK 内部顺序，公开方法使用上表名称。完整事件字段与错误码见 [事件服务开发移植指南](AUN事件发布订阅开发移植指南.md)。
+
+## 2. Bus：先注册承接设备，再开放接收
+
+`start` 要求 `bus_aid` 等于自身 AID；Pub／Sub 由 `authorize` 初始化。Bus 启动默认凭证适配器、核心和 Binding，注册成功后才接管消息。服务端从认证连接取得设备身份，不能信任请求正文自报的设备。
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant H as Bus 宿主应用
+    participant B as Bus SDK
+    participant G as Gateway
+    participant M as Message
+    H->>B: EventService.start(bus_aid, options)
+    B->>B: 载入配置和默认凭证材料，生成 registration_id
+    B->>G: message.evtsvc.register
+    G->>M: 可信 AID / device / slot + registration_id
+    alt 已有其它承接实例
+        M-->>B: DEVICE_CONFLICT，经 Gateway 返回
+        B-->>H: 启动失败
+    else 注册成功
+        M-->>B: ttl_seconds=100，renew_after_seconds=30
+        B->>B: 保存保守期限，启动接收与调度
+        B-->>H: 启动成功
+        loop 实例有效期间，每 30 秒
+            B->>G: message.evtsvc.renew
+            G->>M: 当前 registration_id
+            M-->>B: 新期限，经 Gateway 返回
+        end
+        H->>B: close(bus_aid)
+        B->>B: 停接收、取消在途任务、清理队列
+        B->>G: message.evtsvc.unregister
+        G->>M: 注销当前承接实例
+    end
+```
+
+```text
+代次 = 当前生命周期代次
+请求起点 = 单调时钟()
+租约 = register(当前注册令牌)
+确认回复属于当前令牌和代次
+截止 = 请求起点 + 租约.ttl_seconds
+仅在单调时钟() < 截止时接管和发送
+失租时关闭接收、worker 与 fanout
+```
+
+期限从请求发出前起算，不能从慢回复到达后再加 100 秒。续期超时不越过已有截止；失租后显式重启使用新注册令牌，旧回复、队列和任务不得进入新代次。`drain` 等待已有工作，应用应先停止产生新事件，再排空并关闭。
+
+| 状态 | 默认保存位置 | 恢复要求 |
+| --- | --- | --- |
+| 默认凭证签发／登记／撤销材料和结果 | Python／Go／Node TS：自身 `{aun_path}/AIDs/{self-aid}/aun.db`，键 `pubsub_credentials_v1`；浏览器 JS：IndexedDB `aun-keystore/metadata`，同键并按 AID 隔离 | 恢复原操作，不重复签发；显式存储优先 |
+| Bus 配置与服务状态 | Python `state_path`、Go `StatePath`；TS／JS `state.load/save` | 应用显式配置，区别于默认凭证入库 |
+| 运行时租约、订阅关系、队列与事件正文 | 有界内存 | 重新鉴权与恢复订阅意图，不作为重启消息账本 |
+
+凭证适配器可独立覆盖：TS／JS 使用 `credentialOptions.state.load/save`，Python／Go 显式状态路径优先。关闭时要完成本代在途持久化，不能让旧任务写入新身份的状态。
+
+## 3. Pub／Sub：完整鉴权后一次提交目录和租约
+
+白名单依据可信 AID 判断；事件名或 AID 的 `*` 表示不限制，仅建议用于受控本机多 Agent。凭证由 Bus AID 签发、Bus SDK 完整验证；Credential 服务登记并提供签名状态证明和撤销。应用审批后调用本地 Bus 的签发方法；签发、撤销和统计不经 Pub／Sub 通道开放，也不设置 manager。
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as Bus 宿主应用
+    participant B as Bus SDK
+    participant C as Credential，经 Gateway
+    participant P as Pub 或 Sub SDK
+    participant N as Gateway / Message
+    opt 应用批准凭证授权
+        A->>B: 本地 issue_grant / issueGrant
+        B->>B: Bus AID 私钥签发
+        B->>C: 登记凭证，保存原操作材料
+        C-->>B: 登记证据
+        B-->>A: grant 与登记结果
+        A->>P: 通过应用渠道提供 grant
+    end
+    P->>N: authorize，scope 与授权材料
+    N->>B: SDK 消息，携可信发送设备
+    B->>B: 白名单检查，或完整凭证验证
+    opt 凭证模式需要状态证明
+        B->>C: 获取并校验绑定本次请求的状态证明
+        C-->>B: 状态及有效期
+    end
+    B-->>P: 经 Gateway / Message 返回租约与目录首页
+    loop 首页带 next_page_token
+        P->>N: catalog，当前租约与续页 token
+        N->>B: 请求授权范围内的下一页
+        B-->>P: 经 Gateway / Message 返回目录页
+    end
+    P->>P: 全部续页成功且代次有效，提交授权、租约并更新目录缓存
+```
+
+```text
+候选 = 请求 authorize
+暂存目录 = 校验(候选.catalog)
+当仍有续页 token：校验并暂存 catalog 下一页
+确认当前生命周期代次仍有效
+全部成功：提交候选授权、租约并合并目录缓存
+任一步失败：保留原来的本地授权状态
+```
+
+`authorize` 返回值保留首页，取得的目录合并到 SDK 缓存。内嵌目录最多 2 KiB UTF-8 JSON；包含封装的单次回复最多 64 KiB。首页放不下一条时允许空首页与 offset=0 续页；Bus 校验 token 绑定的身份、租约、scope、revision 和期限，客户端检查响应关联、代次及续页进展。分页默认 50、最大 200，目录变化后重新取首页。
+
+Pub／Sub 默认每 1 小时续期，租约 200 分钟，绑定 AID／device／slot。凭证到期会缩短租约；状态证明过期需复核，不能据本地长租约继续使用已撤销授权。续租不能扩权，缩权、撤销、设备切换及迟到校验结果都要核对当前代次。
+
+## 4. 消息与调度：有界接管，再公平分发
+
+| 线上层级 | 移植约定 |
+| --- | --- |
+| Pub → Bus、Bus → Sub、业务回复 | E2EE P2P `message.send`，正整数 TTL，volatile |
+| SDK 消费标记 | `message_class=sdk_control`，受保护 `sdk_control_protocol=aun.pubsub`、`sdk_control_version=1` |
+| 消息正文 | 外层 `payload.type=e2ee.p2p_encrypted`；解密后 `type=app.pubsub.v1`，事件 `op=event`，`data` 为 JSON 对象 |
+| 发往 Bus | 受保护 `service_target=event_service`，由 Message 路由到有效承接实例 |
+| 回复／事件定向 | 受保护 `target_device_id/target_slot_id`；授权关联可信发送设备，不从正文取得权限 |
+| 关联与幂等 | 回复核对 Bus、op、request_id、event_id；物理投递 ID 区分目标设备／slot；Bus 按发布者 AID＋event_id 保留摘要并检查冲突 |
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 发布应用
+    participant P as Pub SDK
+    participant N as Gateway / Message
+    participant B as Bus SDK
+    participant W as 按订阅 AID 调度
+    participant S as Sub SDK / 应用
+    A->>P: publish(bus_aid, event_name, JSON 对象)
+    P->>P: 校验目录、TTL，进入有界发布队列
+    P-->>A: event_id
+    P->>N: event 类别，按剩余 TTL 发送 sdk_control
+    N-->>P: AUN 接受发送
+    N->>B: Push 或分类 Pull
+    alt 接管与 fanout 衔接容量已满
+        B-->>N: 保留待拉取页，不提交接管 ACK
+        Note over N,B: 容量释放后唤醒对应 Pull
+    else 接管成功
+        B->>B: 授权、内容及幂等检查，固定订阅快照
+        opt reply_mode=accepted
+            B->>N: 定向 publish.result
+            N-->>P: Bus 已受理
+        end
+        B->>W: 批次投递，按 AID 公平轮转
+        alt 全局目标容量已满
+            W-->>B: 等待容量，向上游背压
+        else 单个 AID 额度已满
+            W-->>B: 跳过该目标，计 skipped_overloaded
+        else 目标可发送
+            W->>N: 向订阅设备定向发送，保留原截止
+            N->>S: Sub 校验、去重、有界接收
+            S->>S: on_event / onEvent 或 next_event / NextEvent
+        end
+    end
+    P-->>A: wait_published / 对应语言结果接口
+```
+
+`none` 的后台完成表示 AUN 接受发送；`accepted` 表示 Bus 已受理。两者都不等待订阅应用 ACK。Bus 受理去重记录只留摘要及结果；队列为当前分发保留正文，过期即失效，不承诺离线补发或跨重启 exactly-once。
+
+| 预算 | 默认值与边界 |
+| --- | --- |
+| Pub 发布／Sub 接收 | 各 256 条／1 MiB；单个事件封装 64 KiB；Pub 默认 4 个 worker |
+| Pull 接管到 fanout | 合计最多 64 条；未接管不提交 ACK、去重或越过游标 |
+| Bus 正文 | 入站、受理、目标队列、在途与凭证复核保留材料合计硬封 64 MiB，区别于进程 RSS |
+| 目标队列 | 合计 4096 条／8 MiB；每 AID 512 条／2 MiB；全局满等待，单 AID 满跳过 |
+| 公平调度 | 每订阅 AID 一个逻辑 worker；同 AID 多设备共享份额，按 AID／工作量 DRR 调度 |
+| RPC | total=16、background=8；其中 event=4、pull=4；普通 RPC 使用总池 |
+
+```text
+事件入队立即返回 event_id；后台 worker 执行发送
+派生的凭证、密钥和加密准备 RPC 继承 event 类别与 deadline
+前台等待或写缓冲达到 64 KiB：暂停新事件发送
+发送前核对身份、代次、期限，重算 TTL 和签名
+剩余不足 1 秒：结束发送，不能将 TTL 变成 0
+按订阅 AID 串行发送，各 AID 共享最多 4 个发送名额
+```
+
+同一加密消息流的发布和续租在 Pull 前无法区分；SDK 可让普通 RPC、同页及完整 Push 管理消息继续，但同流后续管理消息仍可能受满载背压。当前不增加服务端事件用途注册表。
+
+## 5. 恢复、限流与任务生命周期
+
+| 路径 | 0.5.32 实现要求 |
+| --- | --- |
+| 分类消息恢复 | `control/sdk_control` 接入已有后台 Pull 调度，重连恢复已保存流与 pending ACK，随后由 Push 驱动；替换独立控制扫描 worker |
+| 应用处理器 | 普通／control 消费等待对应处理器注册；内部 sdk_control 由 SDK 消费，注册处理器后唤醒原待处理流 |
+| 群目录 | `group.list_my` 每页 200，按身份、device、slot、连接代次合并完整分页；自动确认提案复用目录，检查游标前进 |
+| 限流等待 | 识别 `-32429/-32029/429/4290`，后台派发、必要回源与 token 刷新等待至少 60 秒或服务端更长提示；不自动重试全部业务失败 |
+| Python 状态 I/O | 串行异步读写，保存成功后确认消息，关闭时排空实际在途 I/O，避免阻塞事件循环 |
+| Python 加解密 | event／normal 独立线程池，各 4 线程、64 个等待项；取消后实际计算结束才归还名额 |
+| Python 应用队列 | 连续最多 4 个 control 后给普通应用事件处理机会 |
+| TS／JS 连接 | Gateway 发现结果绑定当前连接尝试，旧任务不能覆盖新候选 |
+
+实例续租与 Pub／Sub 授权续租各自随有效实例运行；没有独立的周期 peers／群全量扫描。期限等待、重试和队列唤醒复用现有生命周期，关闭、身份切换与重连后都核对代次。移植时保留这些行为边界，线程 API 或协程数量可按语言选择。
+
+## 6. VFS Cache：精确失效与在途读取隔离
+
+本版调整现有缓存，保留有效的无关资源。资源标记包括 space、owner、bucket、路径；对象、子树和目录列表分别匹配。移动／rename 同时失效两端，复制失效目标，ACL 变更失效相关范围；内存与持久缓存索引使用相同规则。缺资源标记的旧持久记录在相关写入时保守失效。
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant R as 读取调用
+    participant V as VFS / 读缓存
+    participant W as 写入调用
+    participant S as Storage，经 Gateway
+    R->>V: 读取资源 A，缓存未命中
+    V->>S: 发起 A 的读取，保存资源标记和有效标志
+    W->>V: 修改资源 A
+    V->>V: 标记 A 的旧在途读取不可回填
+    V->>S: 带 expected_version 提交写入
+    S-->>V: 写入成功
+    V->>V: 失效 A 及受影响列表的内存、持久索引
+    V-->>W: 返回写入结果
+    S-->>V: 原读取返回旧版本
+    V-->>R: 原调用可收到自身读取结果
+    Note over V: 旧结果不回填缓存，也不供后续读取复用
+    R->>V: 再读 A
+    V->>S: 重新读取；无关资源 B 的缓存保留
+```
+
+```text
+写前：推导资源范围，标记匹配的在途读取失效
+写成功：删除匹配的内存条目和持久索引
+读完成：仅当前身份、代次、资源仍有效且无同范围写时回填
+原调用结果：可返回给原调用方，不把旧结果提供给后续调用
+删除或 rename 成功：清除对应路径及受影响子树的写版本
+```
+
+正文按摘要存放的文件可留待正常回收；索引失效不表示立即删除全部正文文件。rename 清理源／目标的旧写版本，删除后重建不沿用已删除对象的版本；冲突和摘要失败也只失效相关资源。
+
+| 读取条件 | 当前行为 |
+| --- | --- |
+| 普通读取，缓存仍有效 | 复用对应正文或元数据，满足原有校验规则 |
+| 限流等待期，缓存仍有效 | 在允许的读取路径复用，可能覆盖 `no_cache/noCache`、`consistency=authoritative`；兼容已验证正文的不同读取形式 |
+| 限流等待期，缓存未命中 | 先等待，再回源；新 TTL 从实际开始回源时起算 |
+| 强制刷新遇限流错误 | 保留原有效缓存，向当前调用方保留限流错误 |
+| 显式签名、Range 或强校验路径 | 继续遵守各自限制，不能统一改为缓存读取 |
+
+Storage 写入仍提交 `expected_version` 供服务端 CAS。Go／TS／JS 补齐 Python 原有例外：显式版本下，权限不足或已核验挂载无法权威预读时可交服务端检查；未提供版本仍需取得权威版本。`force` 不绕过 CAS。
+
+## 7. 四端落点与独有变化
+
+| 模块 | Python | TypeScript／JavaScript | Go |
+| --- | --- | --- | --- |
+| EventService | [pubsub](../../python/src/aun_core/pubsub/__init__.py)：门面、Binding、client、service、credentials、scheduler | [TS](../../ts/src/pubsub/index.ts)／[JS](../../js/src/pubsub/index.ts)：同层级模块，另有 channel | [pubsub_service.go](../../go/pubsub_service.go)、[Binding](../../go/pubsub_binding.go)、[接收](../../go/pubsub_control_receive.go) |
+| 消息恢复 | [delivery](../../python/src/aun_core/_client/delivery.py)、[control](../../python/src/aun_core/_client/control_messages.py) | [TS delivery](../../ts/src/client/delivery.ts)／[JS delivery](../../js/src/client/delivery.ts) 与 control-messages | [delivery](../../go/client_delivery.go)、[control](../../go/control_messages.go) |
+| 预算与期限 | [transport](../../python/src/aun_core/transport.py)、[crypto_executor](../../python/src/aun_core/_client/crypto_executor.py) | [TS transport](../../ts/src/transport.ts)／[JS transport](../../js/src/transport.ts) 与 rpc-pipeline | [transport](../../go/transport.go)、[RPC 管线](../../go/client_rpc_pipeline.go) |
+| VFS Cache | [cache](../../python/src/aun_core/storage/cache.py)、[VFS](../../python/src/aun_core/storage/vfs.py) | [TS cache](../../ts/src/storage/read-cache.ts)／[JS cache](../../js/src/storage/read-cache.ts)、各自 VFS／GroupFS | [cache](../../go/storage_read_cache.go)、[持久索引](../../go/storage_read_cache_disk.go)、[VFS](../../go/storage_vfs.go) |
+
+- 四端本地 Ownership 绑定／转移的 subaid 扩为非空且非 `human/group/org` 类型，支持 service 等；owner／新 owner 仍限 human／agent，保留身份、私钥、已验证名片和共识检查。
+- Python 语义凭证恢复撤销状态时保留已有 `event_seq` 并核对原件摘要，缺序号的旧记录按 0 比较；见 [semantic_facades](../../python/src/aun_core/semantic_facades.py)。
+- Browser JS 恢复 agent.md 的 `refresh_pending` 与待交付事件，验签／共识／ETag 暂未就绪保留刷新意图，同目标串行；见 [agent-md-control](../../js/src/agent-md-control.ts)。Go 加密 Push 补充兼容 `envelope` 字段。
+
+独有修复按其语言验证，不把 Python 线程池或 JS 通知恢复写成所有语言相同的内部机制。
+
+## 8. 验收场景与已有证据
+
+| 必须核对的场景 | 验收结果要求 | 现有回归入口 |
+| --- | --- | --- |
+| 单实例及设备定向 | 第二实例冲突；失租不再承接；回复只给发布设备，事件只给订阅设备 | [Python Binding](../../python/tests/unit/test_pubsub_binding.py)、[Go Binding](../../go/pubsub_binding_test.go) |
+| 双授权与目录续页 | 两种模式均成功；多页目录全部通过才更新缓存；分页失败保留原状态 | [Python 凭证](../../python/tests/unit/test_pubsub_credentials.py)、[TS client](../../ts/tests/unit/pubsub-client.test.ts)、[JS client](../../js/tests/unit/pubsub-client.test.ts) |
+| 异步发布与背压 | 立即返回 ID；none／accepted 完成点正确；满 64 条后保留待处理页 | [容量](../../python/tests/unit/test_pubsub_capacity_contracts.py)、[Pull gate](../../python/tests/unit/test_pubsub_pull_gate.py) |
+| 公平性与 RPC | 慢 AID 不拖住其它 AID；后台不占满前台额度；截止不因重试延长 | [调度](../../python/tests/unit/test_pubsub_sustained_fairness.py)、[Go 预算](../../go/pubsub_rpc_budget_test.go)、[期限](../../python/tests/unit/test_pubsub_deadline.py) |
+| 默认凭证恢复 | 真正关闭重开 SQLite／IndexedDB 后原操作可恢复，AID 隔离，显式存储优先 | 上述凭证测试及 [Go 凭证](../../go/pubsub_credentials_test.go) |
+| VFS Cache | 无关缓存保留；旧在途不回填；重启后失效正确；删除／rename 不留旧写版本 | [Python cache](../../python/tests/unit/test_storage_read_cache.py)、[TS cache](../../ts/tests/unit/storage-read-cache.test.ts)、[JS VFS](../../js/tests/unit/storage-vfs-read-cache.test.ts)、[Go cache](../../go/storage_read_cache_boundary_test.go) |
+| 限流缓存与 TTL | 有效缓存按当前规则复用，未命中等待，等待结束才计算回源 TTL | 上述 cache 测试及 [跨 SDK cache](../../python/tests/unit/test_cross_sdk_cache_control.py) |
+| 生命周期与语言独有修复 | 关闭排空状态 I/O；旧连接不覆盖新连接；独有凭证／通知兼容有回归 | [状态 I/O](../../python/tests/unit/test_pubsub_control_state_io.py)、[TS 连接](../../ts/tests/unit/transport-connect-race.test.ts)、[Python 语义凭证](../../python/tests/unit/test_semantic_facades.py) |
+
+已有 Ubuntu Docker EventService 矩阵完成 **128/128**：4 种 Bus × 2 种授权 × 4 种 Pub × 4 种 Sub，每种 Bus 32 项；256 份获准目录由 `authorize` 自动取得。见 [最终汇总](../../tests/cross-sdk/artifacts/pubsub-4sdk-20261105/remove-manager-acceptance/final-acceptance-summary.json)与[实施计划 §9.9](../../../docs/AUN文档/AUN事件订阅发布TDD实施计划.md#99-凭证默认存储授权目录与移除管理身份)。
+
+这些记录不等同于本版所有改动的完整验收：JS 矩阵使用 Node＋fake-indexeddb，真实浏览器、macOS、真实双域设备、实填 64 MiB／RSS 压力不在其中；全部 Storage／Ownership／限流改动需按相应回归入口分别核实。本轮仅整理文档，未重跑 SDK 测试或发布产物。

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -33,6 +33,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连 / 当前 access token getter / connect-disconnect-close 并发与取消
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
+- AUN EventService：白名单/凭证授权、设备订阅、发布确认、TTL及恢复见[应用集成指南](AUN事件发布订阅应用集成指南.md)；协议、单实例、完整Verify、公平背压和四端差异见[开发移植指南](AUN事件发布订阅开发移植指南.md)
 - 离线推送：Python `connect()` 的 `push_notify_aid/push_token`、`client.push.register/unregister`、Push Server ACK
 - 消息同步：共享 seq 下的 peer A/T/H、稀疏覆盖/前驱、human Tail→Forward、50k 内存去重/应用持久幂等、N=4 网络 Gate、后台工作片续调度、`message.peers_snapshot` 的轻量对端水位/可选整体积压估计、目录/Pull逐页next_pending_seq、可靠commit后持续更新与每N次FIFO（无额外SQL、原列表顺序不改）、need_render/页内计数、`source` 和同步生命周期；Group 保持原终态规则
 - P2P TTL 消息：`message.send.ttl` 秒级钳制、按 device 内存收件箱、volatile 双游标、自动 ACK/去重、服务 epoch 与重启语义
@@ -55,12 +56,15 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 
 | 编号 | 文档 | 定位 |
 |------|------|------|
+| - | [AUN事件发布订阅应用集成指南](AUN事件发布订阅应用集成指南.md) | 在线通知接入、两种授权、多设备、成功语义、恢复和诊断 |
+| - | [AUN事件发布订阅开发移植指南](AUN事件发布订阅开发移植指南.md) | 线上协议、实例注册、凭证、背压、调度预算和跨端实现 |
 | - | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) | 应用开发者的 TypeScript 接入、消息持久幂等、resolve/owner、凭证组织、诊断与升级 |
 | - | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) | SDK 开发者的 peer/batch 提交、共识缓存、原 CAS/旧任务、checkpoint、语言差异及验收 |
 | - | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) | TypeScript 接线、审批恢复、resolve、缓存及凭证组织 |
 | - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前消息接线、无任务 Ownership、两个 local 编排、缓存和凭证组织 |
 | - | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | 消息提交、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度与语言差异 |
+| - | [0.5.32 应用指南](0.5.32-SDK应用集成指南.md)、[开发与移植指南](0.5.32-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0532)；[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) CHANGELOG | 当前目标对照已发布 0.5.31：EventService、设备租约、公平背压、消息调度、限流缓存及 Ownership |
 | - | [0.5.30 应用指南](0.5.30-SDK应用集成指南.md)、[开发与移植指南](0.5.30-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) | 按需控制流恢复、observer.forward 本地字段剥离、本地 human owner、Storage 版本预检及四端差异 |
 | - | [0.5.29 应用指南](0.5.29-SDK应用集成指南.md)、[开发与移植指南](0.5.29-SDK开发与移植指南.md)、[变更与跨端对齐](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) | 0.5.29 基线：共识输入输出、无 TTL 的 ETag 缓存、resolve、普通上传锁与恢复、NS 配套及四端移植 |
 | - | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | 0.5.28 agent.md 上传／下载校验、共识 fresh、分类控制消息、Owner 通知与风控；四端实现和验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) |
@@ -86,7 +90,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、need_render、agent.md 版本提示、旧 SPK 保留 |
 | - | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API、实例级/单次调用、E2EE V2 HMAC 完整性和接收信任边界 |
-| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC；当前 Ownership 与内部 RPC 增量见 [0.5.30 parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) |
+| 06 | [API手册](06-API手册.md) | AIDStore / resolve opts 与输入输出 / frontmatter 类型 / Agent.md 校验签名 / AID / AUNClient 生命周期并发 / 四 SDK access token getter / 群组高层身份编排 / History 与已读门面 / 已读变更及本地补偿完成 / 消息来源与 Pull 同步生命周期 / 事件 / RPC；当前增量见 [0.5.32 parity](../../python/CHANGES_FOR_PARITY.md#v0532) |
 | 07 | [错误处理](07-错误处理.md) | Result、Python `ErrorInfo.cause`、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、消息同步/History、AUNClient 级 Pull Gate（同 namespace 单飞、客户端最多 4 个并行）、测试数据 |
 | - | [Storage RPC 手册](09-storage-rpc-manual.md) | Storage RPC、实际字节 MIME、三阶段 Content-Type、OSS 403、HTTP 下载与凭据边界、默认读缓存持久层、条件读取与 noCache |
@@ -99,21 +103,24 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 
 | 场景 | 推荐路径 |
 |------|----------|
+| 接入 AUN 发布订阅或处理未收到事件 | [应用集成指南](AUN事件发布订阅应用集成指南.md)：场景 L5-38、门面 L39-55、白名单 L56-127、凭证 L128-152、多设备 L153-168、恢复 L169-184、持久化/诊断 L185-216、依据 L217-222 |
+| 实现或移植 AUN 发布订阅 | [开发移植指南](AUN事件发布订阅开发移植指南.md)：分层 L5-19、实例 L20-39、协议/幂等 L40-87、授权 L88-115、目录 L116-127、分发/预算 L128-173、接收 L174-185、跨端状态 L186-204、验收 L205-229 |
 | 接入或升级 0.5.21，查看 TypeScript 应用示例 | [0.5.21 SDK 应用集成指南](0.5.21-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.21 SDK | [0.5.21 SDK 开发与移植指南](0.5.21-SDK开发与移植指南.md) |
 | 接入或升级 0.5.22，查看 TypeScript 示例、关系审批、默认读缓存及完整成员包 | [0.5.22 SDK 应用集成指南](0.5.22-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 接入或升级 0.5.24，查看当前消息、无任务 Ownership、两个 local 场景、缓存及凭证组织 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.24，核对提交／ACK、NS 事实、远端 CAS、local 身份隔离和缓存新鲜度 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) |
-| 接入或移植 0.5.30，核查后台恢复、本地 Ownership 与 Storage 版本处理 | [应用指南](0.5.30-SDK应用集成指南.md)：行为 L5-14、消息恢复 L16-29、Ownership L31-43、Storage L45-47、转发与风控 L49-53、升级 L55-61；[开发与移植指南](0.5.30-SDK开发与移植指南.md)：契约 L5-14、控制恢复 L16-29、转发 L31-43、Ownership/YAML L45-49、Storage L51-55、差异 L57-68；[parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) L15-58 |
-| 接入或移植 0.5.29 基线，核查共识、resolve、上传锁与恢复 | [应用指南](0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；[parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L60-132 |
-| 回看 0.5.28 的 schema、共识、控制消息、Owner 通知与风控，以及 0.5.27 的历史增量 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)：接入与消息 §1—§3 L5-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：校验 §1 L7-36、共识 §2 L37-62、wire §3 L63-108、outbox §4 L109-121、风控 §5 L122-134、移植 §6 L135-146。 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L88-172；公共共识流程以 0.5.29 为准 |
+| 对照已发布 0.5.31，接入或移植 0.5.32 | [应用指南](0.5.32-SDK应用集成指南.md)：本版变化/整体架构 L5-52、身份与入口 L53-87、白名单多事件流程 L88-171、凭证审批签发 L172-246、设备/租约/容量/存储 L247-282、VFS Cache L283-330、其它主要改动与验收 L331-350；[开发与移植指南](0.5.32-SDK开发与移植指南.md)：基线/架构/四端入口 L5-53、单实例注册与状态 L54-107、鉴权和目录原子提交 L108-156、消息/公平背压/RPC预算 L157-227、恢复/限流/任务 L228-242、VFS并发失效 L243-288、四端落点/独有变化 L289-303、验收入口及已有证据 L304-319；[parity](../../python/CHANGES_FOR_PARITY.md#v0532) L17-114 |
+| 接入或移植 0.5.30，核查后台恢复、本地 Ownership 与 Storage 版本处理 | [应用指南](0.5.30-SDK应用集成指南.md)：行为 L5-14、消息恢复 L16-29、Ownership L31-43、Storage L45-47、转发与风控 L49-53、升级 L55-61；[开发与移植指南](0.5.30-SDK开发与移植指南.md)：契约 L5-14、控制恢复 L16-29、转发 L31-43、Ownership/YAML L45-49、Storage L51-55、差异 L57-68；[parity](../../python/CHANGES_FOR_PARITY.md#v0530--控制流按需恢复与-sdk-行为对齐未发布) L186-227 |
+| 接入或移植 0.5.29 基线，核查共识、resolve、上传锁与恢复 | [应用指南](0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；[parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L231-300 |
+| 回看 0.5.28 的 schema、共识、控制消息、Owner 通知与风控，以及 0.5.27 的历史增量 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)：接入与消息 §1—§3 L5-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：校验 §1 L7-36、共识 §2 L37-62、wire §3 L63-108、outbox §4 L109-121、风控 §5 L122-134、移植 §6 L135-146。 [历史 parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L304-385；公共共识流程以 0.5.29 为准 |
 | 0.5.24 应用按主题读：身份、消息、resolve、Ownership、文件缓存、凭证组织和升级 | `0.5.24-SDK应用集成指南.md` §2 L21-75、§3 L76-132、§4 L133-168、§5 L169-298、§6 L299-321、§7 L322-366、§9 L386-401；local bind L227-245、local transfer L246-267 |
 | 0.5.24 移植按主题读：消息提交、名片、观察、Ownership、缓存、PKI、凭证组织及语言差异 | `0.5.24-SDK开发与移植指南.md` §3 L32-84、§4 L85-92、§5 L93-122、§6 L123-217、§7 L218-245、§8 L246-261、§9 L262-297、§10 L298-325；Rust §11 L326-339、验收 §12 L340-354 |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
 | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
 | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 查询 resolve opts、frontmatter 字段及类型、按需 ownership 共识 | [0.5.29 resolve](0.5.29-SDK应用集成指南.md#4-resolve-与-frontmatter) L81-104；完整基础接口见 [API 手册](06-API手册.md#resolve-输入与输出)，实现增量见 [parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L19-47 |
+| 查询 resolve opts、frontmatter 字段及类型、按需 ownership 共识 | [0.5.29 resolve](0.5.29-SDK应用集成指南.md#4-resolve-与-frontmatter) L81-104；完整基础接口见 [API 手册](06-API手册.md#resolve-输入与输出)，实现增量见 [parity](../../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L231-300 |
 | 查旧 SDK owner 注册、绑定、转移、查询及解绑的隔离兼容，或 legacy proof/escrow/代签 | [当前协议兼容边界](../protocol/Ownership协议定义2.1.md) 开篇/§3.2、[详细设计](Ownership2.1详细设计.md) §1 兼容矩阵；历史 wire 见 [Ownership管理专题（legacy）](Ownership管理专题.md)、[legacy 集成指南](Ownership-SDK集成指南.md) |
 | Ownership 2.1 应用：绑定／释放／转移、两个 local 编排、审批及显式重试的 TS 示例与图 | [应用集成指南](Ownership2.1-SDK应用集成指南.md) |
 | Ownership 2.1 移植：NS 验收、条件发布、通用消息交付、本地编排和文件 CAS | [开发与移植指南](Ownership2.1-SDK开发与移植指南.md) |