@agentunion/fastaun 0.5.33 → 0.5.35

package/_packed_docs/sdk/0.5.34-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,133 @@
+# AUN SDK 0.5.34 应用集成指南
+
+本文只记录相对已发布 `0.5.33` 的应用接入增量。已有的控制消息、Ownership、基础 Storage/VFS、E2EE 和消息同步用法请先阅读 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md) 及基础 [API 手册](06-API手册.md)。四端实现差异见 [parity 0.5.34](../../python/CHANGES_FOR_PARITY.md#v0534)，移植边界见 [0.5.34 开发与移植指南](0.5.34-SDK开发与移植指南.md)。
+
+0.5.34 尚未发布，安装产物、配套服务和真实跨域验收需按实际环境单独核对。
+
+## 1. 本版增量地图
+
+| 增量 | 应用影响 |
+| --- | --- |
+| EventService 多角色 | 同一个 AID 在同一个 Bus 可同时承担 `bus`、`pub`、`sub`，不再要求拆分 Client 或身份 |
+| 目录与订阅持久化 | Bus 目录、授权、订阅和客户端订阅意图在 SQLite/IndexedDB 中恢复，并与后续配置合并 |
+| durable outbox | 发布正文先落盘，再进入内存队列；达到 `reply_mode` 成功阶段后删除，重启恢复未完成记录 |
+| 实时目录查询 | Bus 查询全局，Pub 查询自己的发布汇总，Sub 查询自己的有效订阅关系；不返回消息正文 |
+| Storage 条件 ACL | 以 Ownership 和 `agent.md` 名片条件授权，并保留多 AID `grantee_aids` |
+| Group FS / Service Proxy | 统一命名空间、上传 session headers、Content-Type 三阶段和浏览器隧道约束 |
+| 弹性补拉 | 按策略复用主 Client 的历史辅助连接；持久消息和 volatile 消息分流 |
+
+## 2. EventService 多角色与本地恢复
+
+### 2.1 同一 Bus 绑定三个角色
+
+角色授权仍按 `(bus_aid, role)` 分开校验，但一个 `AUNClient.EventService` 可以在同一个 Bus 同时使用三个角色。Bus 仍只能由 `bus_aid == client.aid` 的本地身份启动；Pub 和 Sub 分别取得对应授权。
+
+```ts
+const service = client.EventService;
+const aid = String(client.aid);
+await service.start(aid, { catalog, allowlist });
+await service.authorize(aid, 'pub', 'allowlist', ['task.completed']);
+await service.authorize(aid, 'sub', 'allowlist', ['task.completed']);
+```
+
+Python 使用 `start`、`authorize`，Go 使用 `Start`、`Authorize` 并传入 `context.Context`；TypeScript 和浏览器 JavaScript 使用同一套 camelCase 门面。已有的启动、授权和回调参数沿用 0.5.33，只有角色冲突限制被移除。
+
+### 2.2 目录、授权和订阅的持久化
+
+Python、Node.js TypeScript 和 Go 默认使用当前 AID 的 SQLite 状态；浏览器 JavaScript 使用 IndexedDB。状态按 AID、Bus、角色、device 和 slot 隔离。启动或重新授权时按以下顺序处理：
+
+1. 加载本地目录、授权材料、订阅意图和待发布记录。
+2. 校验仍有效的凭证、租约和事件范围。
+3. 将本次注册、授权和订阅按事件名合并写回；本次没有出现的条目不会被清空。
+4. 恢复有效订阅和待发布队列。
+
+本地状态暂时无法验证时保留记录，等待重新连接或重新授权；不能因为一次启动失败删除原有目录。
+
+### 2.3 发布队列和 TTL
+
+发布调用的顺序固定为“持久化正文、原 `event_id` 和 `expires_at` → 进入内存队列 → 发送”。`reply_mode=none` 在 AUN 接受发送后删除正文，`reply_mode=accepted` 在 Bus 受理后删除正文。发送失败、关闭或结果未知时保留记录。
+
+重启后先加载未完成记录到内存队列，重新授权后按原 `event_id` 和原 TTL 继续发送。已过期记录不再发送，记录 `EXPIRED` 失败结果；TTL 不重新计算，也不生成新的事件 ID。成功删除正文后只保留有界的结果摘要，不保存消息正文。
+
+Bus 已受理后的 fanout、Message 的 volatile 收件箱、目标设备投递和事件历史不属于本地待发布队列恢复范围，应用仍需使用业务幂等和自己的历史存储。
+
+### 2.4 发布和订阅目录查询
+
+```ts
+const publications = await service.publications(aid, {
+  role: 'pub', eventName: 'task.completed', limit: 100,
+});
+const subscriptions = await service.subscriptions(aid, {
+  role: 'sub', eventName: 'task.completed', limit: 100,
+});
+```
+
+发布清单按 `publisher_aid + event_name` 汇总 `published`、`first_published_at` 和 `last_published_at`，不保存逐消息 `event_id` 或消息正文。订阅清单返回当前有效的 `subscriber_aid`、`event_name`、`device_id`、`slot_id` 和 `expires_at`。两者均支持事件过滤和分页；Bus 重启后旧 `page_token` 失效，需从首页重新查询。
+
+权限范围如下：
+
+| 角色 | 可查询范围 |
+| --- | --- |
+| Bus | 当前 Bus 的全局发布和有效订阅目录 |
+| Pub | 自身 AID 可见范围内的发布汇总 |
+| Sub | 当前设备实际生效的订阅关系 |
+
+## 3. Storage ACL 及上传接线增量
+
+0.5.33 的单 AID、批量 AID 和缓存失效规则继续有效；本版应用可增加条件主体：
+
+```ts
+const subject = {
+  ownership: { ownerAid, scope: 'direct' },
+  card: { type: ['agent'], exttype: ['assistant', 'worker'] },
+};
+await ownerClient.storage.setAcl('/reports', { subject, perms: 'r' });
+```
+
+`ownership.owner_aid`／`scope` 匹配当前 Ownership 关系，`card.type`／`exttype` 匹配可信 `agent.md` 名片；不同属性之间是 AND，同一属性数组内是 OR。`grantee_aids` 支持多 AID，`grantee_aid` 保留兼容。授权、撤销和失败后的缓存失效仍由 SDK 透传，最终判权由 Storage 服务完成。
+
+上传 session、HTTP PUT 和 complete 三个阶段使用同一个实际 `Content-Type`，显式值优先。应用应保留 session 返回的 `session_id` 和 `headers`，不要把短期 ticket、URL 或 token 写入长期业务索引。
+
+## 4. Group FS 与 Service Proxy
+
+Group FS 四端门面在本版补齐 `set_visibility` 和 `namespace_ready`；`ls` 使用 `page`／`size`，`limit` 仅作兼容别名；挂载路径为 `/memberdata/{member_ref}`。`readonly` 默认 `true`，`require_approval` 默认 `false`，实际写权限仍以角色 ACL 和服务端判权为准。
+
+浏览器 JavaScript 的 `cp(string, group)` 默认按 UTF-8 文本处理；本地路径必须显式使用 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀。Python、TypeScript 和 Go 保留字符串为本地路径的既有语义。
+
+Service Proxy 统一服务名校验、Gateway 控制面注册、proxy-server 数据面隧道注册和 provider wakeup 错误映射。Browser provider 必须传入能设置 `Authorization` 请求头的 `webSocketFactory`。具体字段见 [Service Proxy RPC 手册](09-proxy-rpc-manual.md) 和 [Storage RPC 手册](09-storage-rpc-manual.md)。
+
+## 5. 弹性补拉的本版变化
+
+0.5.33 的基础补拉接线、策略开关和故障边界见 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md)。0.5.34 增加以下应用可见行为：
+
+- 同一 AUNClient 复用主连接的身份、解密、游标和应用分发状态，应用不创建第二个完整 Client。
+- 持久消息使用原有 seq/cursor 和 ACK；volatile 消息使用独立 cursor，不推进持久水位，也不被暂停的历史任务阻塞。
+- 辅助连接被回收、断开或策略降额时，未完成页退回主连接；旧会话结果不能提交新游标或 ACK。
+- 首条记录超过 `max_page_bytes` 返回 `OVERSIZED_MESSAGE`，该流停止自动续页，其它流继续。
+
+应用仍按消息 ID 幂等处理；补拉不改变跨流全局顺序，也不恢复已过期的临时消息。详细共同契约见 [0.5.34 开发与移植指南第 5 节](0.5.34-SDK开发与移植指南.md#5-弹性补拉的本版共同契约)。
+
+## 6. Python 专项
+
+Python 0.5.34 的限流等待优先使用服务端正的 `retry_after_seconds`／`retry_after_ms`；明确为队列、背压或容量拥塞且没有有效提示时默认等待 1 秒，其它限流仍默认 60 秒。新增 `aun bench run` 和 `aun bench report`，支持套件、场景、预算和断点续跑；`run_id` 示例使用 `sdk034`。
+
+## 7. 升级与验收
+
+升级时先阅读 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md)，仅对本版增量执行以下检查：
+
+| 检查项 | 关键断言 |
+| --- | --- |
+| 版本 | 四端运行时、配置、锁文件和测试引用均为 `0.5.34` |
+| EventService | 同 Bus 三角色共存；目录和订阅重开后合并；发布先落盘、成功后删除；原 TTL 过期记为 `EXPIRED` |
+| 实时目录 | Bus、Pub、Sub 按权限返回各自范围；发布按事件汇总，不含正文 |
+| Storage ACL | Ownership／名片条件和 `grantee_aids` 在四端映射一致；撤销后不能命中旧缓存或票据 |
+| Group FS / Proxy | 命名空间、上传 headers、Content-Type 三阶段和 Browser `Authorization` 隧道约束一致 |
+| 弹性补拉 | 持久／volatile 分流、策略降额、断线退主、超页和旧代际不推进 ACK |
+
+已有测试证据、服务端依赖和未执行范围见 [parity 0.5.34](../../python/CHANGES_FOR_PARITY.md#v0534)。本专题不把静态检查、mock 或历史测试结果写成真实服务 E2E 通过。
+
+## 8. 历史基线索引
+
+- [0.5.33 SDK 应用集成指南](0.5.33-SDK应用集成指南.md)：控制消息、Ownership 批次、本地共识、批量 ACL 和弹性补拉基础。
+- [0.5.32 SDK 应用集成指南](0.5.32-SDK应用集成指南.md)：EventService 初始 API、租约、凭证、fanout 和 RPC 预算。
+- [AUN SDK API 手册](06-API手册.md)：稳定的 Client、RPC、消息、Storage 和 E2EE 基础接口。

package/_packed_docs/sdk/0.5.34-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,107 @@
+# AUN SDK 0.5.34 开发与移植指南
+
+本文只定义相对已发布 `0.5.33` 的四端实现增量。控制消息、Ownership、基础 Storage/VFS、E2EE、消息游标和原有 EventService wire 请先阅读 [0.5.33 开发与移植指南](0.5.33-SDK开发与移植指南.md) 及 [RPC 手册](09-message-rpc-manual.md)。实现级差异见 [parity 0.5.34](../../python/CHANGES_FOR_PARITY.md#v0534)，应用接线见 [0.5.34 应用集成指南](0.5.34-SDK应用集成指南.md)。
+
+本指南描述工作区源码和现有测试契约，不表示服务端部署、Ubuntu Docker、浏览器 live E2E 或跨域 E2E 已全部通过。
+
+## 1. 0.5.34 增量范围
+
+| 范围 | SDK 共同责任 | 配套服务责任 |
+| --- | --- | --- |
+| EventService 多角色 | `(bus_aid, role)` 独立绑定、授权、恢复和查询 | Message 仅维护 Bus 实例租约和投递 |
+| 本地持久化 | SQLite/IndexedDB 保存目录、订阅意图、授权材料和待发布 outbox | 服务端继续维护事件接收和历史边界 |
+| Storage 条件 ACL | VFS、LowLevel、RPC 字段一致透传和定向失效 | Storage/NS 负责条件判权、名片回源和计次 |
+| Group FS / Proxy | 门面参数、上传 headers、隧道请求头和错误映射一致 | Group、Storage、Gateway、proxy-server 提供对应 RPC |
+| 弹性补拉 | 主辅生命周期、策略代际、持久/volatile 分流和消费背压 | Gateway 授权/回收；Message/Group 分页和游标 |
+| Python 专项 | 限流等待和容量压测工具 | 保持现有服务接口 |
+
+## 2. EventService 多角色共同契约
+
+同一 SDK 身份在同一 Bus 按 `(bus_aid, role)` 保存 `bus`、`pub`、`sub` 三类状态。Bus 启动仍要求 `bus_aid == client.aid`；Pub/Sub 必须分别完成授权。移植实现不能再以单个 AID 已承担其它角色为冲突条件。
+
+公开查询入口为 `publications` 和 `subscriptions`：
+
+| 查询 | 返回内容 |
+| --- | --- |
+| `publications` | `publisher_aid`、`event_name`、`published`、`first_published_at`、`last_published_at` 汇总 |
+| `subscriptions` | 当前有效的 `subscriber_aid`、`event_name`、`device_id`、`slot_id`、`expires_at` |
+
+两者支持事件过滤、`limit`、`page_token`；分页 token 绑定运行实例、查询范围和操作，Bus 重启后失效。发布查询不保存消息正文或逐消息 `event_id`；订阅查询只返回当前生效的关系，不能把授权目录当作订阅。
+
+## 3. SQLite/IndexedDB 状态与 durable outbox
+
+Python、Node.js TypeScript 和 Go 默认使用当前 AID 的 SQLite metadata；浏览器 JavaScript 使用 IndexedDB。实现必须按 AID、Bus、角色、device 和 slot 隔离状态，并支持显式状态路径或适配器覆盖。
+
+状态恢复顺序固定为：
+
+1. 打开本地数据库并加载旧目录、授权材料、订阅意图和待发布记录。
+2. 复核当前身份、凭证、租约和事件范围；复核失败时保留记录等待重新授权。
+3. 将新注册、授权和订阅按事件名增量合并；缺省条目不能清空旧状态。
+4. 恢复有效订阅和未完成发布到内存队列。
+
+发布队列必须遵守“持久化正文及原 `event_id`／`expires_at` → 确认入队 → 后台发送 → 达到所选 `reply_mode` 成功阶段 → 删除正文”。关闭、发送失败、结果未知或删除失败时保留正文；成功后只保留有界结果摘要。TTL 过期的记录写入 `EXPIRED`，不再发送、不延长 TTL、不生成新 ID。
+
+| SDK | 默认后端 | 恢复入口 |
+| --- | --- | --- |
+| Python | 当前 AID SQLite metadata | `start`／`authorize` 后恢复目录、订阅和 pending publish |
+| TypeScript | Node SQLite 状态适配器 | `start`／`authorize` 后恢复角色状态 |
+| JavaScript | IndexedDB 状态适配器 | 重新连接并授权后恢复 |
+| Go | 当前 AID SQLite instance state | `Start`／`Authorize` 后恢复，`StatePath` 可覆盖 |
+
+Bus 已受理后的 fanout、Message 的 volatile 收件箱、目标投递和事件历史不属于 SDK durable outbox；实现不得把这些运行时状态写入发布队列恢复账本。
+
+## 4. Storage、Group FS 与 Service Proxy wire
+
+### 4.1 条件 ACL
+
+四端统一透传以下主体结构：
+
+- `subject.ownership.owner_aid` 和可选 `scope`（`direct` 或 `descendants`）匹配当前 Ownership 关系。
+- `subject.card.type` 和 `exttype` 匹配可信 `agent.md` 名片；跨属性 AND，同属性数组 OR。
+- `grantee_aids` 支持多 AID，`grantee_aid` 保留兼容；VFS、LowLevel 和 RPC 不得改变字段语义。
+
+服务端负责当前 Owner 声明、名片 TTL、规则计次和最终判权。SDK 在 ACL 成功或异常（包括批量部分完成）后定向失效受影响路径缓存，保留无关路径缓存和原始错误。短期 ticket、URL 和 token 不进入长期本地索引。
+
+### 4.2 Group FS 和上传 Content-Type
+
+四端门面补齐 `group.fs.set_visibility`、`group.fs.namespace_ready`；`group.fs.ls` 使用 `page/size`，`limit` 为兼容别名；挂载路径限定为 `/memberdata/{member_ref}`，`readonly=true`、`require_approval=false` 为默认值。
+
+上传 session、HTTP PUT 和 complete 必须使用同一个实际 `Content-Type`，显式值优先；session 返回的 `session_id`／`headers` 必须原样保留。Browser JS 的 `cp(string, group)` 默认按 UTF-8 文本；本地路径要求 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀，其他 SDK 保持既有字符串路径语义。
+
+### 4.3 Service Proxy
+
+四端统一服务名校验、Gateway 控制面注册、proxy-server 数据面隧道注册和 provider wakeup 错误映射。Browser provider 的 `webSocketFactory` 必须具备设置 `Authorization` 请求头的能力；隧道认证失败不能降级为无认证连接。
+
+## 5. 弹性补拉的本版共同契约
+
+0.5.33 已定义基础策略开关、`history_sync` 用途和连接回收；本版只补充下列实现边界：
+
+- 辅助 Transport 复用主 Client 的 AID、device、slot、token、解密、游标和应用分发状态，不创建完整 Client，不刷新 refresh token。
+- `storage_scope=persistent` 使用持久 cursor/ACK；`storage_scope=volatile` 使用独立 cursor，不提交持久水位、覆盖证明或服务端 ACK；`all` 保留旧请求行为。
+- 同一 namespace 的 Pull 串行，不同 namespace 可按 Gateway 策略和共享预算并行。策略、连接和任务均绑定主会话代际，旧结果不能向新会话提交游标或 ACK。
+- Gateway 回收或辅助连接断开时，释放页内存预留，将未完成任务退回主连接；同一策略版本内不自动冷重连。
+- `max_page_bytes` 超限时返回 `OVERSIZED_MESSAGE`，停止该流自动续页并发布 `sync.error`；其它流继续。
+
+共享预算仍为总 16、background 8、event 4、pull 4；历史使用 pull 子额度。完整策略字段、回收通知和服务端限制见 [消息弹性补拉通道方案](../消息弹性补拉通道方案.md) 和 [0.5.33 开发与移植指南](0.5.33-SDK开发与移植指南.md)。
+
+## 6. Python 专项
+
+Python 0.5.34 的 `_record_rate_limit` 优先使用正的 `retry_after_seconds`／`retry_after_ms`；明确为队列、背压或容量拥塞且没有有效提示时默认等待 1 秒，其它限流仍默认 60 秒。新增容量压测 CLI `aun bench run/report`，支持 16 种场景、套件、预算和断点续跑；该工具不新增网络协议。
+
+## 7. 四端移植验收
+
+| 范围 | 必须覆盖 |
+| --- | --- |
+| 版本 | Python、TypeScript、JavaScript、Go 的运行时、配置、锁文件和测试引用均为 `0.5.34` |
+| EventService | 三角色共存、状态重开、目录合并、写入失败不确认、成功删除正文、原 TTL 恢复、`EXPIRED` 结果和分页 token 失效 |
+| Storage ACL | 条件主体、批量主体、ACL 错误后的定向缓存失效、四端 VFS/LowLevel/RPC 字段一致 |
+| Group FS / Proxy | namespace、`ls` 分页、mount、session headers、Content-Type 三阶段和 Browser Authorization 隧道 |
+| 弹性补拉 | 策略代际、持久/volatile 分流、断线退主、消费预留、超页和旧会话无 ACK |
+
+按 Python → Node TypeScript → Go → 浏览器 JavaScript 顺序执行受影响定向测试，再执行跨 SDK runner；首失败停止并从失败项续跑。真实 Gateway cap、服务端重启、Ubuntu Docker、浏览器 live E2E 和跨域 E2E 需单独记录，不能由静态检查替代。
+
+## 8. 历史基线索引
+
+- [0.5.33 SDK 开发与移植指南](0.5.33-SDK开发与移植指南.md)：控制消息、Ownership、基础 ACL、消息同步和弹性补拉原有契约。
+- [0.5.32 SDK 开发与移植指南](0.5.32-SDK开发与移植指南.md)：EventService 初始实现、租约、凭证、fanout、队列和 RPC 预算。
+- [parity 0.5.34](../../python/CHANGES_FOR_PARITY.md#v0534)：四端实现路径、测试入口和服务端依赖。

package/_packed_docs/sdk/0.5.35-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,189 @@
+# 0.5.35 SDK 应用集成指南
+
+本文面向从已发布 **0.5.34** 升级到 **0.5.35** 的应用，依据截至 2026-11-12 的工作区源码整理。0.5.35 为目标版本，本文不代表安装包已发布或部署验收已完成。
+
+首次接入先读 [快速开始](01-快速开始.md)、[连接与认证](04-连接与认证.md)和 [API 手册](06-API手册.md)。本版实现契约见 [开发与移植指南](0.5.35-SDK开发与移植指南.md)，源码差异和比较基线见 [parity 0.5.35](../../python/CHANGES_FOR_PARITY.md#v0535)。0.5.34 的多角色、持久目录、durable outbox、Storage／Group FS／Service Proxy 接入见 [历史应用指南](0.5.34-SDK应用集成指南.md)。
+
+## 1. 升级范围与支持边界
+
+| 能力 | Python | Node TypeScript | Browser JavaScript | Go |
+| --- | --- | --- | --- | --- |
+| EventService 通配订阅、发布者过滤、同 Client 本地收发 | 支持 | 支持 | 支持 | 支持 |
+| 后台累计 ACK、同步恢复调整、Echo v3.2 | 支持 | 支持 | 支持 | 支持 |
+| 原生 UDP 待机 | 支持 | 支持 | 无原生实现 | 支持 |
+| 独立 SMTP／IMAP MailClient | 支持 | 支持 | 无原生实现 | 支持 |
+| 本版语言专属变化 | Windows 路径、上传清理、闭环压测 CLI | 邮件信封与 ImapFlow 适配 | 浏览器交付与测试版本对齐 | 只读凭据身份、DNS 回退、SQLite 初始化 |
+
+本次发布按**配套服务单实例部署**支持。Redis 缓存的存在不代表同一服务已支持多副本共享状态；本版不据此扩大部署范围。独立 Mail 尚未完成整体端到端验收，核心 IM 接入不要求启用 Mail。
+
+四 SDK 的代码、项目配置和相关测试版本已统一为 `0.5.35`。应用需核对实际安装产物的版本，并使用支持对应能力的配套服务；客户端升级不会自动启用 Gateway 的 UDP 待机或部署独立 Mail。
+
+## 2. EventService：通配订阅和发布者过滤
+
+### 2.1 先授权具体事件，再按模式订阅
+
+`subscribe`／`unsubscribe` 新增点分层通配：`task.*` 可匹配 `task.completed`，不能匹配 `task.worker.completed`。层内可使用 `*`，不支持 `**`、空层或正则表达式。
+
+授权申请、grant scope 和发布仍使用完整事件名。订阅模式只在**当前 Bus 目录与当前设备有效租约的授权交集**内展开，返回实际订阅的具体事件。目录后来新增事件时，应在取得相应授权后重新订阅；旧通配订阅不会自动扩展。
+
+没有目录命中返回 `UNKNOWN_EVENT`；有目录命中但无可用授权返回 `FORBIDDEN`。取消订阅按当前已订阅集合展开模式。
+
+### 2.2 按可信发布者信息筛选
+
+| 过滤含义 | Python／线上字段 | TS／JS 选项 | Go 选项 |
+| --- | --- | --- | --- |
+| 发布者 AID | `publisher_aids` | `publisherAids` | `PublisherAIDs` |
+| 名片主体类型 | `publisher_types` | `publisherTypes` | `PublisherTypes` |
+| 名片扩展类型 | `publisher_exttypes` | `publisherExttypes` | `PublisherExtTypes` |
+
+同一字段内多个模式为 OR，不同字段之间为 AND；模式沿用上述分层 `*` 规则。省略字段表示该维度不限，显式空数组无效。每个字段允许 1–64 项，每个模式的 UTF-8 长度最多 256 字节。
+
+以下示例假定应用已启动 EventService、取得 Sub 授权，且当前目录包含允许订阅的 `task` 事件：
+
+```ts
+await client.EventService.subscribe(busAid, ['task.*'], {
+  publisherTypes: ['worker-*'],
+  publisherExttypes: ['task.executor'],
+});
+```
+
+AID 来自认证发送者，`type`／`exttype` 来自验签通过的发布者 `agent.md`，不能通过事件正文自报身份。名片暂时无法读取或验证时，要求类型的订阅不会匹配；不设类型条件或仅按 AID 过滤的订阅不受该名片读取失败影响。
+
+### 2.3 修改、恢复与同进程投递
+
+再次订阅同一具体事件会**替换该事件的过滤条件**；省略过滤字段会恢复为不限。希望保留过滤时，更新订阅应再次传入完整条件。
+
+SDK 持久化具体事件及其过滤条件，重新授权后逐事件恢复。Python／Node／Go 使用 SQLite，Browser 使用 IndexedDB；状态按身份、Bus、设备与 slot 隔离。修改条件或取消订阅后，排队和回调开始前会复核订阅代次，已经执行的业务操作仍由应用负责。
+
+同一个 Client 内，Bus 为本端 AID、device／slot 匹配的 Bus／Pub／Sub 可以直接在进程内投递。跨 Client、设备或 slot 仍走网络。本地路径继续执行角色授权、租约、TTL、去重和容量检查；容量满时等待容量或期限到达，不提供无限队列。
+
+完整角色配置、凭证和事件生命周期见 [事件应用集成专题](AUN事件发布订阅应用集成指南.md)。
+
+## 3. 消息 ACK、同步与连接恢复
+
+后台 Pull 在本地提交消息后调度累计 ACK，同一 namespace 的更高水位会合并，失败后重试。前台 Pull 继续等待 ACK。ACK 表示协议消费进度，不是应用的业务处理完成证明；业务入库、幂等和完成回执仍按应用自己的契约处理。
+
+关闭 Client 仅有限等待后台 ACK，不保证关闭前全部确认已抵达服务端。重连后的重复交付应继续使用现有消息标识去重，不能因后台 ACK 改为异步就删除应用幂等逻辑。
+
+| 变化 | 升级时的应用影响 |
+| --- | --- |
+| 自动连接后恢复随机延后 30–60 秒 | 包含补拉及组织身份／待上传名片恢复；不要将认证成功等同于历史已补齐 |
+| 关闭后台同步时不调度上述自动恢复 | 显式 Pull 和消息通知触发仍使用各自入口 |
+| 移除 `history_bytes_per_second` 主动节流 | 不再依赖该项限制历史吞吐；并发、页字节上限、在途内存预留和背压仍有效 |
+| 辅助连接 ready／退役时更新同步需求 | SDK 随实际连接状态调整；`gateway.sync_demand` 不计为业务活动 |
+| TS／JS 减少重复 Pull／ACK、合并群补拉 | 应用继续按消息和同步生命周期消费，不依赖内部任务次数 |
+
+现有同步事件及 `source`、History、已读语义见 [API 手册](06-API手册.md)和 [最佳实践](08-最佳实践.md)。
+
+## 4. Echo v3.2：诊断请求与结果
+
+SDK 去掉首行前导空白后，按最长前缀识别 `echo.ecdiag`、`echo.ask`、`echo`，大小写不敏感。这类诊断强制明文，应用不要把敏感正文放入 Echo 请求。
+
+控制字段统一为 `hop`，默认 100。payload 中有效整数优先于首行 `hop=N`；安全整数范围为 ±9007199254740991。去程递减到 0 后立即返程，负数表示回程并继续递减；旧 `max_hop`／`rhop` 不再控制转发。
+
+本版保留完整正文及重复经过节点的 trace，回程耗时采用本地单调时钟。本地提前返回和服务返回的 `echo_return` 都通过既有 `message.received`／`group.message_created` 入口交付；群接收端的提前返回定向原发送者。
+
+| 结果字段 | 应用解释 |
+| --- | --- |
+| `reason=timeout`／`send_failed` | 本地发送超时或失败的诊断原因 |
+| `delivery_state=not_delivered` | 该诊断判断未完成投递 |
+| `delivery_state=unknown` | 远端是否收到尚不确定，不应直接判为丢失并盲目重发 |
+| `echo_error` | 原发送错误的诊断信息 |
+
+认证错误和密文发送不转换为上述本地诊断；业务回调抛错不会重复生成一条诊断。完整格式见 [Echo SDK 规范](../protocol/echo-probe-sdk.md)，本文不宣称外部 App／Rust／EvolCore 链路已完成验收。
+
+## 5. UDP 待机：何时可以释放 WebSocket
+
+### 5.1 协商与准入
+
+Python、Node TS、Go 的主长连接只有在服务端同时返回严格布尔值 `negotiated_capabilities.udp_standby_v1=true`、`udp_standby.enabled=true` 时才启用。Gateway 缺省关闭；未协商、短连接、辅助连接及 Browser 保持原连接方式。Node 可通过 `connect({ udp_standby: false })` 退出该能力，此选项写法不要套用于其他语言。
+
+空闲准入仍受名片 `type=human`、未完成 RPC、ACK、同步／交付、关闭和迁移等状态约束。待机执行 prepare → UDP 路径验证 → commit，成功后释放 WebSocket；正常切换不作为应用离线。
+
+### 5.2 区分两套订阅
+
+Gateway 的协议级 `event.subscribe` 控制连接接收哪些通知；`EventService.subscribe` 控制 Bus 事件订阅。两者不是同一套订阅。
+
+默认全事件、queue／stream 或不在待机白名单的订阅会保持 WebSocket；SDK 不会为省连接擅自缩窄订阅。只有应用确认无需其他通知时，才可显式设置所需集合，例如：
+
+```python
+await client.call("event.subscribe", {
+    "events": ["message.received", "group.message_created"],
+})
+```
+
+SDK 使用 prepare 返回的 `event_subscriptions` 快照，在恢复认证时写回 `auth.connect.options.event_subscriptions`。应用修改通知集合时应重新核对待机资格。
+
+### 5.3 唤醒和心跳
+
+新业务请求、消息提示、ticket／lease／对账期限以及连续心跳故障会恢复 WebSocket。并发唤醒会合并，各请求保留自己的超时和取消边界；SDK 不自动重放已经发出的写请求。
+
+UDP 只承载控制提示，不传消息正文；`WAKE_ACK` 不代表应用已消费，不延长业务 TTL，也不能唤醒已经退出的进程。
+
+三端均采用当前有效 `HEARTBEAT_ACK` 返回的新心跳周期，下一轮按新周期执行 ±20% 抖动。Python 在收包匹配当前请求后更新策略，再由心跳循环读取；默认策略约为 25 秒周期、5 秒等待，连续三次失败回到 WebSocket，实际以服务端协商策略为准。
+
+## 6. 原生 MailClient：独立接线和恢复
+
+### 6.1 与 Gateway 客户端分开配置
+
+原生 MailClient 直接连接独立 SMTP STARTTLS（默认 587）和 IMAPS（默认 993），默认主机为 `mail.{issuer}`。认证使用 AID 证书、TLS 和 SASL EXTERNAL，不使用 Gateway JWT。旧 `client.mail`／Go `Mail()` RPC 门面继续兼容，但不能用它代替原生客户端的部署与认证配置。
+
+| SDK | 构造入口 | 凭据 provider 返回值 | 自定义服务端信任根 |
+| --- | --- | --- | --- |
+| Python | `aun_core.MailClient(issuer, credential_provider=...)` | `cert_pem`／`private_key_pem`，或 `cert_file`／`key_file` | `server_trust_bundle` 为 CA 文件路径 |
+| Node TS | `new MailClient({ issuer, credentialProvider, serverTrustBundle })` | `{ cert, key }`，内容为 string／Buffer，可异步提供 | CA 内容，string／Buffer |
+| Go | `NewMailClient(MailClientOptions{...})` | `func(context.Context) (tls.Certificate, error)` | `ServerTrustBundle []byte` |
+
+连接会准备 SMTP 和 IMAP 两条连接，默认连接超时 10 秒、命令超时 30 秒。provider 应提供当前身份凭据；轮换后客户端重建连接。关闭时使用各语言的客户端关闭入口，Browser 不提供这些原生网络能力。
+
+### 6.2 分开处理发送与 Sent 结果
+
+支持结构化 MIME、附件或 raw MIME，并返回逐收件人状态。`accepted` 仅代表 SMTP 接受，不能当作最终送达回执。
+
+| 状态维度 | 返回值 | 应用处理 |
+| --- | --- | --- |
+| 发送 | `accepted`／`partial`／`rejected`／`accepted_unknown` | 按收件人结果展示；未知状态应先核对，避免重复邮件 |
+| Sent 副本 | `not_requested`／`saved`／`failed`／`unknown` | 独立于发送结果；副本失败不代表 SMTP 一定未接受 |
+
+Python raw MIME 保留原始头部和正文，仅补缺失的 Date／Message-ID；投递时剥离 Bcc 及折行，Sent 保留完整副本。Node 会复制并规范化信封、去重收件人，不修改调用者传入的信封。
+
+### 6.3 用 UIDVALIDITY／UID 恢复监听
+
+IMAP 提供 UID 查询／修改、流式读取和 watch。检查点应连同邮箱保存 `UIDVALIDITY`／UID，不能在 UIDVALIDITY 变化后复用旧 UID。
+
+| SDK | 监听入口与变化事件 | UIDVALIDITY 改变后的行为 |
+| --- | --- | --- |
+| Python | `watch(mailbox, uidvalidity, uid=0)` 异步迭代；`change` | 产出 `resync_required` 后结束迭代 |
+| Node TS | `watch(mailbox, { uidValidity, uid }, signal?)` 异步生成器；`changes` | 产出 `resync_required`，重置 UID 后继续 |
+| Go | `Watch(ctx, mailbox, checkpoint, consume)` 回调；初始 `sync`，后续 `changed` | 回调 `resync_required` 后结束当前 Watch，返回 nil |
+
+应用收到 `resync_required` 后重建该邮箱的索引和检查点，并按所在语言决定继续消费或重新启动 watch。流式读取对应 Python `fetch_stream`、Node `fetchStream`、Go `FetchStream`，按各自接口管理流的生命周期。
+
+Mail SDK 能力不等于独立邮件服务整体可用。本次 Mail 端到端验收未完成，默认 Go 运行镜像 `AUN_INCLUDE_MAIL=0` 不启用 Mail；构建阶段仍编译 Mail，不能据此忽略其构建依赖。
+
+## 7. Python／Go 专属接入变化
+
+Python 修正 Windows 长路径下的 pending 身份、名片缓存和 group index 写入，并在 HTTP 上传结束时清理会话。应用沿用原存储和上传入口，无需迁移数据格式。
+
+Python CLI 新增闭环容量工具，区分 RPC 接受和完整投递的吞吐／P99，支持有限 pending、阶梯并发、持续复验及断点恢复。仅查看计划可运行：
+
+```bash
+aun bench capacity closed-loop example.com --case p2p-plain --run-id sdk035 --dry-run
+```
+
+场景包括 `p2p-plain`、`p2p-online`、`group-plain`、`group-online`；实际压测前按 [测试运行指南](../aun测试运行指南.md)准备环境。命令存在不代表已测得服务器容量。
+
+Go 新增 `NewReadOnlyIdentityClient`，接收已有 P-256 证书／私钥、明确的 WSS 地址、device／slot 和可选 CA，状态在实例内存中隔离。“只读”指凭据存储，不限制为只读 RPC。相同证书 PEM 首尾空白可接受，实际换证书会被拒绝；DNS IP 回退仍保留原域名和显式端口 Host。
+
+## 8. 升级验收清单
+
+| 范围 | 应用验收重点 |
+| --- | --- |
+| 版本与服务 | 四 SDK 实际产物版本、配套服务版本、单实例部署边界 |
+| EventService | 具体事件授权、通配展开、过滤替换、重启恢复、取消后的排队事件、本地与网络路径 |
+| 消息恢复 | 后台 ACK 重试、重连重复消息幂等、30–60 秒恢复窗口、历史背压 |
+| Echo | 明文、唯一 hop、现有回调入口、未知投递状态分支 |
+| UDP（三端） | 未协商保持 WS、human／忙碌阻止入睡、订阅恢复、周期更新、故障唤醒 |
+| Mail（按需） | 独立服务与凭据轮换、逐收件人和 Sent 状态、UIDVALIDITY 变化、断线恢复 |
+
+本文核对了当前接口和源码，并定向运行 Python UDP 心跳测试（11 项通过）；未执行 Docker、公网、浏览器 live、跨域 E2E 或 Mail 整体验收。其余既有执行记录及限制见 [parity 的核验范围](../../python/CHANGES_FOR_PARITY.md#v0535)，不能把文档清单当作完整发布测试报告。