@agentunion/fastaun 0.5.33 → 0.5.34

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/01-/345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -1,6 +1,6 @@
 # AUN SDK - 快速开始
 
-**版本**: 0.4.5+ | **Python**: >= 3.11
+**版本**: 0.5.34 | **Python**: >= 3.11
 
 ---
 
@@ -54,7 +54,7 @@ async def load_or_register(store: AIDStore, aid: str):
     if loaded["ok"]:
         return loaded["data"]["aid"]
 
-    registered = await store.register(aid)
+    registered = await store.register(aid, type="human")
     if not registered["ok"]:
         raise RuntimeError(registered["error"]["message"])
 
@@ -65,10 +65,10 @@ async def load_or_register(store: AIDStore, aid: str):
 
 
 async def create_client(aid: str) -> AUNClient:
-    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="", slot_id="main")
     identity = await load_or_register(store, aid)
     client = AUNClient(identity)
-    await client.connect({"slot_id": "main", "auto_reconnect": True})
+    await client.connect({"auto_reconnect": True})
     return client
 
 
@@ -122,7 +122,7 @@ store = AIDStore(
 identity = store.load("alice.agentid.pub")["data"]["aid"]
 client = AUNClient(identity)
 client.set_protected_headers({"sdk": "python"})
-await client.connect({"slot_id": "main", "connection_kind": "long"})
+await client.connect({"connection_kind": "long"})
 ```
 
 `verify_ssl` 在 `AIDStore` 构造时配置，不在 `AUNClient` 中配置。自动模式下 SDK 根据环境变量决定：
@@ -137,7 +137,7 @@ await client.connect({"slot_id": "main", "connection_kind": "long"})
 
 ## 数据目录布局
 
-SDK 使用 `{aun_path}/AIDs/{aid}/` 存储每个 AID 的专属数据：
+Python / TypeScript（Node.js）/ Go 使用 `{aun_path}/AIDs/{aid}/` 存储每个 AID 的专属数据：
 
 ```text
 {aun_path}/
@@ -146,16 +146,17 @@ SDK 使用 `{aun_path}/AIDs/{aid}/` 存储每个 AID 的专属数据：
     ├── alice.agentid.pub/
     │   ├── private/key.json
     │   ├── public/cert.pem
-    │   └── tokens/meta.json
+    │   └── aun.db
     └── bob.agentid.pub/
         ├── private/key.json
         ├── public/cert.pem
-        └── tokens/meta.json
+        └── aun.db
 ```
 
 要点：
 
 - `aun_path` 是应用级目录，一个目录可管理多个 AID。
+- token、消息游标、实例状态及 EventService 状态保存在身份目录的 SQLite `aun.db`；浏览器 JavaScript 使用 IndexedDB，不使用上述文件布局。
 - 不要用 AID 名称作为 `aun_path`，避免出现 `~/.aun/{aid}/AIDs/{aid}/` 冗余嵌套。
 - 私钥、令牌、群密钥等敏感数据由 SDK 的本地保护机制保存，不应手工删除或迁移单个文件。
 
@@ -183,11 +184,11 @@ Go：
 
 ```go
 store := aun.NewAIDStore("~/.aun/myapp", "")
-aid, err := store.Load("alice.agentid.pub")
-if err != nil {
-    return err
+loaded := store.Load("alice.agentid.pub")
+if !loaded.Ok {
+    panic(loaded.Error)
 }
-client := aun.NewAUNClient(aid.Data.AID)
+client := aun.NewAUNClient(loaded.Data.AID)
 ```
 
 ---
@@ -195,12 +196,14 @@ client := aun.NewAUNClient(aid.Data.AID)
 ## 核心流程
 
 1. 创建 `AIDStore`。
-2. `store.load(aid)` 加载本地 AID；本地不存在时调用 `store.register(aid)` 后再次加载。
+2. `store.load(aid)` 加载本地 AID；本地不存在时调用 `store.register(aid, type="human")`（非 human 类型还需提供 `owner`）后再次加载。
 3. 用 AID 对象构造 `AUNClient(aid)`，或先 `AUNClient()` 再 `load_identity(aid)`。
 4. 先注册事件处理器，再调用 `connect(options)`。
 5. 通过 `call(method, params)` 执行业务 RPC。
 6. 通过 `close()` 释放连接和后台任务。
 
+事件发布订阅使用 `client.EventService`（Go 为 `client.EventService()`）：Bus 宿主先 `start`，Pub/Sub 分别 `authorize`，然后发布或订阅；同一 client 可在同一 Bus 上绑定多个角色。完整流程及 SQLite／IndexedDB 恢复规则见 [AUN事件发布订阅应用集成指南](AUN事件发布订阅应用集成指南.md)。
+
 详细 API 见 [06-API手册.md](06-API手册.md)，RPC 参数见各领域的 `09-*-rpc-manual.md`。
 
 

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -18,7 +18,7 @@ AID 是 Agent 的全局唯一身份，格式为域名形式，例如 `alice.agen
 ```python
 store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
 
-registered = await store.register("alice.agentid.pub")
+registered = await store.register("alice.agentid.pub", type="human")
 loaded = store.load("alice.agentid.pub")
 me = loaded["data"]["aid"]
 
@@ -191,6 +191,18 @@ RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-
 
 ---
 
+## EventService 发布订阅
+
+EventService 运行在 Bus AID 的 SDK 内，以 `(bus_aid, event_name)` 标识事件；Pub 向 Bus 发布 JSON 对象，Bus 按有效订阅向设备实例定向分发。同一 client 在同一 Bus 上可以同时承担 `bus`、`pub`、`sub`，发布与订阅分别授权；Bus 身份也须取得相应发布或订阅权限。
+
+四端默认持久保存 Bus 目录、白名单、可复核的授权与订阅，以及客户端授权材料、目录、订阅意图和待发布记录。Python / TypeScript（Node.js）/ Go 使用 SQLite，浏览器 JavaScript 使用 IndexedDB。启动先加载已有状态，再合并本次配置；恢复待发布记录沿用原 `event_id` 与 TTL，过期后记录失败，不重新发送。应用仍须重新启动 Bus 或按角色接入目标 Bus，SDK 不自动枚举历史 Bus。
+
+发布遵循“本地持久化成功 → 入队 → 后台发送 → 按所选回复模式确认成功 → 删除本地正文”。默认 `none` 表示 AUN 已接受发送，`accepted` 表示 Bus 已受理；两者均不表示订阅方已完成业务处理。Bus fanout、服务端 volatile 收件箱和事件历史不在本地待发布队列的恢复范围内。
+
+`catalog` 查询事件定义；`publications` 查询本次 Bus 运行的首次受理汇总，`subscriptions` 查询当前有效订阅，授权目录不等于实际订阅。完整 API、可见范围及分页规则见 [API 手册](06-API手册.md#eventservice-事件发布订阅)与[应用集成指南](AUN事件发布订阅应用集成指南.md)。
+
+---
+
 ## Group Index 观察模型
 
 `group.index` 是群公告、群规则、入群要求和附件稳定引用的签名索引。它由 owner/admin 侧 SDK 生成并签名，Group 服务只校验、CAS 保存和在响应 `_meta.group_indexes` 中注入版本提示。

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -7,23 +7,23 @@
 重构后，注册、身份加载、会话连接分离：
 
 ```python
-store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="", slot_id="main")
 
 loaded = store.load(aid)
 if not loaded["ok"]:
-    registered = await store.register(aid)
+    registered = await store.register(aid, type="human")
     if not registered["ok"]:
         raise RuntimeError(registered["error"]["message"])
     loaded = store.load(aid)
 
 me = loaded["data"]["aid"]
 client = AUNClient(me)
-await client.connect({"slot_id": "main", "auto_reconnect": True})
+await client.connect({"auto_reconnect": True})
 ```
 
 关键约束：
 
-- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
+- `AIDStore.register(aid, *, type, owner=None, exttype=None)` 只负责生成本地密钥、申请证书并落盘；`type` 必填，非 `human` 类型还需按归属流程提供 `owner`。
 - `AIDStore.load(aid)` 返回 AID 值对象；AID 对象加载后不可变。
 - `AUNClient` 只接收 AID 对象，不接收字符串 AID 或配置字典里的 `aid` 字段。
 - `connect(options)` 内部会按需认证、建立 WebSocket、初始化 E2EE 和后台任务。
@@ -59,7 +59,7 @@ store = AIDStore(
 | 方法 | 说明 |
 |------|------|
 | `load(aid)` | 从本地加载 AID，返回 Result |
-| `register(aid)` | 注册新 AID，返回 Result |
+| `register(aid, *, type, owner=None, exttype=None)` | 注册新 AID，返回 Result |
 | `list()` | 列出本地身份 |
 | `exists(aid)` | HEAD PKI 端点，判断 AID 是否已注册 |
 | `resolve(aid, opts=None)` | 解析身份与 agent.md，返回结构化 frontmatter；自有私钥身份优先本地草稿/缓存，可传 `{"skip_agent_md": True}` 跳过名片，或 `{"ownership": client}` 按需查询并缓存共识和 owner.md |
@@ -75,7 +75,7 @@ Result 使用方式：
 ```python
 result = await store.exists("alice.agentid.pub")
 if result["ok"] and not result["data"]["exists"]:
-    await store.register("alice.agentid.pub")
+    await store.register("alice.agentid.pub", type="human")
 ```
 
 ---
@@ -143,7 +143,7 @@ await client.connect({
 | `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
 | `background_sync` | 连接成功后是否执行消息后台补洞 / 未读同步，默认开启；不关闭已读状态查询补偿 |
 | `auto_reconnect` | 断线后是否自动重连 |
-| `heartbeat_interval` | 心跳间隔，秒 |
+| `heartbeat_interval` | 保留的兼容选项；当前不启用 RPC 心跳，连接保活使用 WebSocket 控制帧 |
 | `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
 | `connect_timeout` / `call_timeout` | 连接和 RPC 超时，秒 |
 | `push_notify_aid` / `push_token` | Python SDK 推荐的离线推送登记入口；必须同时提供 |
@@ -151,6 +151,8 @@ await client.connect({
 
 `slot_id` 来自已加载的 AID，不是 `connect()` 选项。Python SDK 在 AUN 会话建立后把 `push_notify_aid` 映射为冻结 RPC 字段 `push_server_aid`，调用 `push.register` 登记当前 `(aid, device_id, slot_id)`；这些字段不会进入 `auth.connect`。登记失败时本次连接回滚并向调用方抛错。Go、TypeScript、JavaScript SDK 本轮未增加该便利入口。
 
+本表使用 Python 选项名；TS/JS 使用 `connectionKind`、`shortTtlMs`、`autoReconnect`、`backgroundSync` 等 camelCase 名称，Go 使用 `ConnectionOptions` 的 `ConnectionKind`、`ShortTTLMS`、`AutoReconnect`、`BackgroundSync` 等字段。
+
 当前稳定实现为 Gateway 模式；Peer / Relay 仍是协议能力定义，SDK 连接层会明确返回未实现。
 
 ---
@@ -180,6 +182,14 @@ await cli.close()
 
 ---
 
+## EventService 接入与恢复
+
+EventService 使用已就绪的 AUNClient：Python / TS / JS 为 `client.EventService`，Go 为 `client.EventService()`。Bus 宿主调用 `start`，要求 Bus AID 等于当前身份；远端 Pub/Sub 直接 `authorize(bus_aid, role, ...)`，内部自动建立该角色客户端。多角色分别授权，使用独立的授权材料与租约。
+
+连接恢复时 SDK 会重新核验授权并恢复订阅和待发布队列；新进程仍需重新 `start` 本地 Bus，或对目标 Bus 的 Pub/Sub 角色调用 `authorize`。默认 SQLite／IndexedDB 保存待发布记录，恢复不延长 TTL，已过期记录转为可查询的失败结果。`close` 保留这些持久状态；停止接收新工作后可先 `drain` 再关闭。方法签名与目录查询见 [API 手册](06-API手册.md#eventservice-事件发布订阅)，完整流程见 [应用集成指南](AUN事件发布订阅应用集成指南.md)。
+
+---
+
 ## 网关发现
 
 注册、解析和认证会根据 AID 的 issuer 自动发现 Gateway：

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

@@ -1,5 +1,7 @@
 # AUN SDK - API 手册
 
+本手册对照四 SDK 0.5.34 的公开接口；历史版本专题中的接口以其标注版本为准。
+
 ---
 
 ## 目录
@@ -8,6 +10,7 @@
 - [AID](#aid)
 - [AUNClient](#aunclient)
 - [业务门面](#业务门面)
+- [EventService 事件发布订阅](#eventservice-事件发布订阅)
 - [事件](#事件)
 - [ServiceProxyClient](#serviceproxyclient)
 - [E2EE 高级 API](#e2ee-高级-api)
@@ -64,7 +67,7 @@ store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
 | `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
-| `register(aid)` | `register(aid)` | `Register(ctx, aid[, opts])` | 注册并落盘证书和私钥；Go 两参数旧调用仍可用，显式选项使用 `AIDStoreRegisterOptions` |
+| `register(aid, *, type, owner=None, exttype=None)` | `register(aid, {type, owner?, exttype?})` | `Register(ctx, aid[, opts])` | 注册并落盘证书和私钥；`type` 必填，非 human 类型还需 `owner`；Go 两参数旧调用仍可用，显式选项使用 `AIDStoreRegisterOptions` |
 | `list()` | `list()` | `List()` | 列出本地 AID |
 | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
 | `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 解析身份及名片，返回结构化 `agent_md.frontmatter`；可按需复用 ownership 共识校验并缓存 owner.md，完整输入输出见下节 |
@@ -270,11 +273,11 @@ AID 由 `AIDStore.load()` 返回，应用层不直接构造。
 
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
-| `aid` | `aid` | `AID()` | AID 字符串 |
-| `cert_pem` | `certPem` | `CertPEM()` | 证书 PEM |
-| `public_key` | `publicKey` | `PublicKey()` | 公钥 |
-| `cert_fingerprint` | `certFingerprint` | `CertFingerprint()` | 证书指纹 |
-| `aun_path` | `aunPath` | `AUNPath()` | 所属数据目录 |
+| `aid` | `aid` | `Aid` 字段 | AID 字符串 |
+| `cert_pem` | `certPem` | `CertPem` 字段 | 证书 PEM |
+| `public_key` | `publicKey` | `PublicKey` 字段 | 公钥 |
+| `cert_fingerprint` | `certFingerprint` | `CertFingerprint` 字段 | 证书指纹 |
+| `aun_path` | `aunPath` | `AunPath` 字段 | 所属数据目录 |
 | `device_id` | `deviceId` | `DeviceID` | 设备 ID |
 | `slot_id` | `slotId` | `SlotID` | 实例槽位 ID；允许 `/`、`:`、空格作为共享隔离键分隔符 |
 | `verify_ssl` | `verifySsl` | `VerifySSL` | 是否校验 TLS 证书 |
@@ -471,6 +474,44 @@ headers = client.get_protected_headers()
 
 除 `client.call(method, params)` 外，四语言 SDK 提供高层门面（Facade），封装常用操作并简化参数。普通应用优先用门面，只有需要精确控制底层参数时再直调 RPC。
 
+### EventService 事件发布订阅
+
+Python / TS / JS 使用 `client.EventService` 属性，Go 使用 `client.EventService()`。以下均为该门面的方法，不是 Gateway `pubsub.*` RPC；跨 AID 请求由 SDK 通过 E2EE P2P 消息承载。
+
+| 操作 | Python | TypeScript / JavaScript | Go |
+|------|--------|-------------------------|----|
+| 启动本地 Bus | `await start(bus_aid, catalog=..., allowlist=...)` | `await start(busAid, {catalog, allowlist})` | `Start(ctx, busAid, EventServiceStartOptions{...})` |
+| 按角色授权 | `await authorize(bus_aid, role, auth_mode, events, credential=None)` | `await authorize(busAid, role, authMode, events, credential?)` | `Authorize(ctx, busAid, role, authMode, events, grant)` |
+| 发布对象 | `await publish(bus_aid, event_name, data, **options)` | `await publish(busAid, eventName, data, options?)` | `Publish(ctx, busAid, eventName, data, options...)` |
+| 等待发布结果 | `await wait_published(bus_aid, event_id)` | `await waitPublished(busAid, eventId)` | `WaitPublished(ctx, busAid, eventID)` |
+| 订阅／取消订阅 | `await subscribe(bus_aid, events)` / `unsubscribe(...)` | `await subscribe(busAid, events)` / `unsubscribe(...)` | `Subscribe(ctx, busAid, events)` / `Unsubscribe(...)` |
+| 接收事件 | `on_event(bus_aid, handler)` / `await next_event(bus_aid, timeout=None)` | `onEvent(busAid, handler)` / `await nextEvent(busAid, timeout?)` | `OnEvent(busAid, handler)` / `NextEvent(ctx, busAid)` |
+| 事件定义目录 | `await catalog(bus_aid, **params)` | `await catalog(busAid, params?)` | `Catalog(ctx, busAid, params)` |
+| 发布／订阅目录 | `await publications(bus_aid, **params)` / `subscriptions(...)` | `await publications(busAid, params?)` / `subscriptions(...)` | `Publications(ctx, busAid, params)` / `Subscriptions(...)` |
+| 宿主管理 | `update_config` / `stats` / `issue_grant` / `revoke_grant` | `updateConfig` / `stats` / `issueGrant` / `revokeGrant` | `UpdateConfig` / `Stats` / `IssueGrant` / `RevokeGrant` |
+| 生命周期 | `renew` / `drain` / `close` | `renew` / `drain` / `close` | `Renew` / `Drain` / `Close` |
+
+`start` 要求 `bus_aid == client.aid`；接入远端 Bus 直接按 `pub` / `sub` 分别 `authorize`，授权成功自动加载获准的事件定义目录。同一 client 可在同一 Bus 上同时绑定 `bus`、`pub`、`sub`，Bus 自发自订仍需相应权限。管理方法仅本地 Bus 宿主可用。`renew`、`drain`、`close` 覆盖该 Bus 相关角色；Go `Close(busAid)` 不接收 context，异步方法的具体参数及返回见[应用集成指南](AUN事件发布订阅应用集成指南.md)。
+
+`publish` 的 `data` 必须是 JSON 对象，成功返回 `event_id` 字符串（Go 另返回 error），表示已持久化并入队。选项分别为 Python `schema_version` / `ttl_seconds` / `reply_mode` / `event_id`，TS/JS `schemaVersion` / `ttlSeconds` / `replyMode` / `eventId`，Go `PubSubPublishOptions`。`wait_published` / `waitPublished` / `WaitPublished` 返回所选阶段结果：默认 `none` 为 AUN 已接受发送，`accepted` 为 Bus 已受理，均不证明订阅方业务完成。后台完成通知分别使用 `on_publish` / `onPublish` / `OnPublish`；Go handler 接收 `(eventID, result, error)`，Python / TS / JS handler 接收含 `event_id` 与 `result` 或 `error` 的对象。
+
+默认持久化覆盖 Bus 事件目录、白名单、有效授权和订阅，以及客户端授权材料、目录、订阅意图、待发布记录和过期失败结果。Python / TS（Node.js）/ Go 复用身份目录的 SQLite `aun.db`，浏览器 JS 使用 IndexedDB；自定义 Bus 存储与 Python / Go 的 `state_path` / `StatePath` 边界见[持久化说明](AUN事件发布订阅应用集成指南.md#7-持久化统计与故障定位)。启动加载旧目录后按事件合并本次配置，未提交的事件保留，同名条目以本次配置为准；后续注册、订阅与配置修改写回持久层。
+
+待发布消息先落库再入队；达到所选回复模式的成功阶段后删除本地正文，关闭或未确认成功时保留。重启重新接入对应角色后按原 `event_id`、原 `expires_at` 恢复，过期后记录 `EXPIRED`，不延长 TTL。成功结果仅有界保留在运行期，过期失败结果也受容量限制。Bus 已受理后的 fanout、服务端 volatile 收件箱及历史事件不在此持久恢复范围内。
+
+#### publications / subscriptions 查询
+
+查询的可选参数为 `event_name`、`limit`（默认 50，范围 1–200）、`page_token`；TS/JS 和 Go 的查询 map 也使用这些 snake_case 字段。`role` 只在本地选择查询端：`publications` 可选 `bus` / `pub`，`subscriptions` 可选 `bus` / `sub`；省略优先本地 Bus，否则使用对应客户端角色，不发送到网络。
+
+Bus 宿主可查询全局；Pub 仅查看自身 AID、当前发布权限内的汇总，Sub 仅查看当前设备租约实际生效的订阅。`authorize` 成功本身不建立订阅。查询返回 `{service_aid, since, as_of, items, next_page_token}`，时间均为 Unix 毫秒，末页 token 为 null：
+
+| 查询 | `items` 字段 |
+|------|---------------|
+| `publications` | `publisher_aid`、`event_name`、`published`、`first_published_at`、`last_published_at` |
+| `subscriptions` | `subscriber_aid`、`event_name`、`device_id`、`slot_id`、`expires_at` |
+
+发布汇总只计 Bus 首次受理，不计拒绝与去重，TTL 到期不删除汇总，Bus 重启清零；订阅目录只返回当前有效关系，不包含凭证或租约令牌。每页是实时视图，不冻结快照；分页 token 有效 60 秒并绑定操作、查询范围及当前 Bus 运行实例，完整回包最多 64 KiB。事件定义仍通过 `catalog` 查询。完整流程和参数见[应用集成指南](AUN事件发布订阅应用集成指南.md)，内部契约见[开发移植指南](AUN事件发布订阅开发移植指南.md)。
+
 ### Ownership、凭证与组织专题
 
 | 领域 | 当前入口 | 详细指南 |
@@ -860,7 +901,7 @@ await client.push.unregister()
 
 ## ServiceProxyClient
 
-Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
+Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。Python、TypeScript、JavaScript 和 Go 均提供 `ServiceProxyClient` 封装；浏览器 JavaScript 需通过可承载 Authorization Bearer 的自定义 WebSocket factory 建立隧道。公开入口与控制面字段见 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md)。
 
 ```python
 from aun_core.service_proxy import ServiceProxyClient
@@ -895,6 +936,8 @@ proxy-server 连接地址不能由应用外部传入或配置。`ServiceProxyCli
 | `serve_once()` | 处理有限数量的 proxy-server 转发请求 |
 | `serve_forever(connection_mode="persistent")` | 持续提供 Service Proxy 服务；支持 persistent / on_demand |
 
+四端构造与生命周期命名：Python `ServiceProxyClient(provider_aid=..., aun_client=client)`；TS/JS `new ServiceProxyClient({providerAid, aunClient})`；Go `NewServiceProxyClient(ServiceProxyClientOptions{ProviderAID: ..., AUNClient: client})`。对应方法分别使用 `register_service` / `registerService` / `RegisterService`、`connect_once` / `connectOnce` / `ConnectOnce`、`serve_once` / `serveOnce` / `ServeOnce`、`serve_forever` / `serveForever` / `ServeForever`。浏览器 JS 的 `webSocketFactory` 必须能发送隧道的 Authorization Bearer 请求头，原生浏览器 WebSocket 不满足该条件。
+
 自动注册顺序：
 
 - `connect_once()`、`serve_once()`、`serve_forever()` 在存在 `aun_client.call()` 时，会先向 Gateway 调用 `proxy.register_services`。
@@ -1046,13 +1089,11 @@ JavaScript 浏览器 SDK 的 Worker 是网络隔离增强：`new Worker()` 同
 
 | API | 说明 |
 |-----|------|
-| `client.e2ee.encrypt_message(...)` | 裸 WebSocket 或特殊集成中的 P2P 加密 |
-| `client.e2ee.decrypt_message(...)` | 裸消息解密 |
-| `client.e2ee.generate_prekey()` | 生成 prekey |
-| `client.e2ee.invalidate_prekey_cache(peer_aid)` | 清理对端 prekey 缓存 |
-| `client.group_e2ee.encrypt(...)` | 群消息加密 |
-| `client.group_e2ee.decrypt(...)` | 群消息解密 |
-| `client.group_e2ee.current_epoch(group_id)` | 查询当前群 epoch |
+| Python | `aun_core.v2.e2ee.encrypt_p2p.encrypt_p2p_message`、`encrypt_group.encrypt_group_message`、`decrypt.decrypt_message` |
+| TypeScript / JavaScript | 根入口导出的 `encryptP2PMessage`、`encryptGroupMessage`、`decryptMessage` |
+| Go | `v2/e2ee.EncryptP2PMessage`、`EncryptGroupMessage`、`DecryptMessage` |
+
+这些是低层 E2EE 函数，需要调用方提供对应的密钥和目标上下文；普通 `message.send` / `group.send` 由 SDK 自动管理加密，不应改用低层函数替代。
 
 ---