@agentunion/fastaun-browser 0.4.9 → 0.4.11

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -6,11 +6,12 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 
 当前 SDK 聚焦三主体模型：
 
-- `AIDStore`：注册、加载、列举、解析和证书运维。
-- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
-- `AUNClient`：认证、连接、状态机、事件和 RPC。
-
-业务操作统一通过 `client.call(method, params)` 调用；消息、群组、存储、meta、stream 的参数见 `09-*-rpc-manual.md`。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。在线轻量通知方案见 `Notify通知方案.md`。
+- `AIDStore`：注册、加载、列举、解析和证书运维。
+- `AID`：不可变身份值对象，负责签名、验签和 agent.md 签验。
+- `AUNClient`：认证、连接、状态机、事件和 RPC。
+- `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
+
+业务操作统一通过 `client.call(method, params)` 调用；消息、群组、存储、meta、stream、proxy 的参数见 `09-*-rpc-manual.md`。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
 
 ## 渐进式查阅流程
 
@@ -26,6 +27,7 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
+- Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`
 - 错误处理：Result、异常、错误码、重试
 
@@ -42,11 +44,12 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 | 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
 | 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE、ProtectedHeaders、密钥管理 |
-| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / 事件 / RPC |
-| 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
-| 08 | [最佳实践](08-最佳实践.md) | 幂等、多 AID、资源清理、测试数据 |
-| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
-| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
+| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / ServiceProxyClient / 事件 / RPC |
+| 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
+| 08 | [最佳实践](08-最佳实践.md) | 幂等、多 AID、资源清理、测试数据 |
+| 09 | `09-*-rpc-manual.md` | 各服务 RPC 参数和响应 |
+| 09 | [Service Proxy RPC手册](09-proxy-rpc-manual.md) | `proxy.*` 控制面和 proxy-server 数据面注册 |
+| 09 | [AID托管API手册](09-custody-api-manual.md) | 可选 custody HTTP 服务 |
 
 ## 常见查阅场景
 
@@ -59,7 +62,8 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
 | 查方法签名 | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
-| 查 notify 在线轻量通知 | [Notify通知方案.md](Notify通知方案.md) |
+| 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
+| 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |
 | 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
 | 排查错误 | [07-错误处理](07-错误处理.md) |
 | 写测试或 demo | [08-最佳实践](08-最佳实践.md) |

package/_packed_docs/sdk/INDEX.md

@@ -23,8 +23,9 @@
 | [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC |
 | [09-meta-rpc-manual](09-meta-rpc-manual.md) | meta RPC 和信任根 |
 | [09-stream-rpc-manual](09-stream-rpc-manual.md) | stream RPC |
+| [09-proxy-rpc-manual](09-proxy-rpc-manual.md) | Service Proxy 控制面 RPC 和数据面隧道注册 |
 | [09-custody-api-manual](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
-| [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知设计 |
+| [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知、跨域 federation 和可靠消息分工 |
 
 ---
 
@@ -56,13 +57,14 @@
 ### RPC 与事件
 
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
-- `client.notify()` 在线轻量通知 → [Notify通知方案](Notify通知方案.md)
+- `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
 - Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
 - Group RPC → [09-group-rpc-manual](09-group-rpc-manual.md)
-- Storage RPC → [09-storage-rpc-manual](09-storage-rpc-manual.md)
-- Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
-- Stream RPC → [09-stream-rpc-manual](09-stream-rpc-manual.md)
-- Payload 格式 → [09-payload-reference](09-payload-reference.md)
+- Storage RPC → [09-storage-rpc-manual](09-storage-rpc-manual.md)
+- Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
+- Stream RPC → [09-stream-rpc-manual](09-stream-rpc-manual.md)
+- Service Proxy RPC 和隧道注册 → [09-proxy-rpc-manual](09-proxy-rpc-manual.md)
+- Payload 格式 → [09-payload-reference](09-payload-reference.md)
 
 ### 错误与测试
 
@@ -97,7 +99,7 @@
 
 ### 06-API手册
 
-列出 AIDStore、AID、AUNClient、事件、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
+列出 AIDStore、AID、AUNClient、事件、ServiceProxyClient、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
 
 ### 07-错误处理
 
@@ -111,6 +113,10 @@
 
 各业务服务的 RPC 参数、响应和错误语义。SDK 不为每个 RPC 提供一层业务 wrapper，应用直接通过 `client.call()` 调用。
 
+### 09-proxy-rpc-manual
+
+定义 Service Proxy 的 Gateway 控制面 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`，以及 proxy-server 数据面 `register_services` 隧道消息、双注册顺序、服务列表一致性和 wakeup 路由语义。
+
 ### Notify通知方案
 
-定义 `client.notify()` 的在线轻量通知语义、服务端/AID/群路由方式、无离线存储边界、安全约束，以及与 `message.send` / `group.send` 可靠应用事件的分工。
+定义 `client.notify()` 的在线轻量通知语义、服务端/AID/群路由方式、跨域 federation 在线转发、无离线存储边界、安全约束，以及与 `message.send` / `group.send` 可靠应用事件的分工。

package/_packed_docs/sdk/Notify/351/200/232/347/237/245/346/226/271/346/241/210.md

@@ -0,0 +1,214 @@
+# Notify 通知方案
+
+> 状态：已实现。本文定义 SDK 公开 `notify()` API 的语义边界、路由方式、跨域行为，以及与可靠消息通道的分工。
+
+## 目标
+
+`notify()` 用于发送 JSON-RPC 2.0 Notification：无 `id`、不等待业务响应、只面向在线长连接的轻量通知。
+
+它补齐 SDK 发送侧能力：SDK 已通过 `client.on(event, handler)` 接收 `event/...`，`notify()` 则提供对称的发送端能力。可靠应用事件仍走 `message.send` / `group.send`，在 payload 中使用 `type="event"` 或 `type="status"`。
+
+## 非目标
+
+- 不做离线存储。
+- 不分配 `seq`。
+- 不进入 `message.pull` / `group.pull`。
+- 不需要 ack。
+- 不提供送达保证。
+- 不承载敏感内容，除非应用自行加密。
+- 不替代 `message.send` / `group.send`。
+
+## API 形态
+
+公共方法命名为 `notify()`，不用 `emit()`。
+
+原因：
+
+- `notify` 对齐 JSON-RPC Notification 术语。
+- `emit` 容易被理解为触发本地事件 handler，和 `client.on()` 组合时有歧义。
+- `notify` 更清楚表达单向、轻量、无业务响应。
+
+四端 SDK 公开形态：
+
+| 语言 | API |
+|------|-----|
+| Python | `await client.notify(method, params=None, *, to=None, group_id=None, device_id=None, slot_id=None, ttl_ms=None)` |
+| TypeScript / JavaScript | `await client.notify(method, params?, { to?, groupId?/group_id?, deviceId?/device_id?, slotId?/slot_id?, ttlMs?/ttl_ms? })` |
+| Go | `client.Notify(ctx, method, params, NotifyOptions{To, GroupID, DeviceID, SlotID, TTLMS})` |
+
+示例：
+
+```python
+await client.notify("notification/client.activity", {"state": "idle"})
+await client.notify("event/app.typing", {"thread_id": "t1"}, to="bob.agentid.pub", ttl_ms=5000)
+await client.notify("event/app.presence", {"state": "active"}, group_id="group.agentid.pub/123")
+```
+
+`await client.notify(...)` 只表示 SDK 已尝试把 Notification 帧写入当前 WebSocket，不表示服务端接受、目标在线或对端收到。
+
+## 路由模型
+
+### 1. 服务端通知
+
+未指定 `to` / `group_id` 时，SDK 直接发送无 `id` 的 JSON-RPC Notification：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "notification/client.activity",
+  "params": {"state": "idle"}
+}
+```
+
+直发服务端通知只允许 `notification/...` 方法名。Gateway 可按自身 handler 处理；无 handler、限流、背压或连接异常时可以丢弃。
+
+### 2. AID 在线转发
+
+指定 `to` 时，SDK 不直接发送 `event/app.*`，而是包装成 `notification/route`：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "notification/route",
+  "params": {
+    "target": {"type": "aid", "aid": "bob.agentid.pub"},
+    "deliver": {
+      "method": "event/app.typing",
+      "params": {"thread_id": "t1"}
+    },
+    "ttl_ms": 5000
+  }
+}
+```
+
+Gateway 校验发送方认证上下文、payload 大小、TTL、方法名前缀和目标在线状态后，转发给目标在线长连接：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/app.typing",
+  "params": {
+    "thread_id": "t1",
+    "_notify": {
+      "from_aid": "alice.agentid.pub",
+      "device_id": "dev-1",
+      "slot_id": "main",
+      "connection_id": "conn-xxx",
+      "sent_at": 1760000000000,
+      "ttl_ms": 5000
+    }
+  }
+}
+```
+
+接收端 SDK 复用现有 `event/...` 分发，把它发布成本地 `app.typing` 事件。
+
+### 3. 跨域 AID 在线转发
+
+当 `to` 的 issuer 与发送方当前 Gateway issuer 不同时，源域 Gateway 通过 federation 把 notify 转发到目标 AID 所属域 Gateway。目标域 Gateway 再按本域在线索引投递。
+
+跨域 notify 仍保持 best-effort：
+
+- 目标域在线则实时投递。
+- 目标域离线或 federation 不可用则丢弃。
+- 不写入消息库，不产生 pull/ack 补偿。
+- `_notify.from_aid` 必须属于 federation `from_issuer`，否则目标域 Gateway 拒绝。
+- 目标 AID 必须属于目标域 Gateway issuer，避免被远端 Gateway 转发到第三域。
+
+指定 `device_id` / `slot_id` 时，源域不会尝试解析远端连接 ID；过滤条件随 federation 转发到目标域，由目标域 Gateway 用本地在线索引解析。
+
+### 4. 群在线转发
+
+指定 `group_id` 时，SDK 发送 `notification/group.route`。Gateway 调用 Group 服务解析目标成员，Group 服务负责校验成员身份、群状态和权限；Gateway 只按 Group 服务返回的成员 AID 做在线 fanout。
+
+群成员包含外域 AID 时，Gateway 会按成员 AID issuer 做 federation 转发。Gateway 不直接跨域解析远端 `group_id`，群权限仍以 Group 服务返回的目标成员集合为准。
+
+## 在线投递规则
+
+- `to=aid`：默认投递该 AID 的所有在线长连接设备。
+- `to=aid + device_id`：只投递指定在线设备。
+- `to=aid + device_id + slot_id`：只投递指定在线实例槽位。
+- `group_id=...`：只投递 Group 服务确认的成员在线长连接设备。
+- 跨域 AID notify 按目标 AID issuer 转发到目标域后再执行同样规则。
+- 短连接默认不接收 notify。
+- 目标离线、目标无在线长连接、TTL 过期、写入失败、背压超限时直接丢弃。
+
+`ttl_ms` 取值范围为 `0..60000`，只用于在线投递过期控制，不表示离线缓存。
+
+## 方法名前缀
+
+客户端发出的 notify 限制为：
+
+- `notification/...`：直发 Gateway 的协议级通知。
+- `event/app.*`：应用自定义在线事件；仅在指定 `to` 或 `group_id` 时允许。
+
+禁止客户端伪造服务端权威事件，例如：
+
+- `event/message.received`
+- `event/message.recalled`
+- `event/group.changed`
+- `event/group.message_created`
+- `event/storage.object_changed`
+
+这些事件只能由对应服务端模块产生。
+
+## 安全与限流
+
+Gateway 会覆盖注入 `_notify.from_aid`、`device_id`、`slot_id`、`connection_id`、`sent_at`、`ttl_ms`，不信任客户端传入的同名字段。
+
+约束：
+
+- payload 大小限制为 64KB。
+- `ttl_ms` 最大 60000ms。
+- `slot_id` 必须和 `device_id` 一起使用。
+- `to` 和 `group_id` 不能同时设置。
+- 跨域入站 notify 只接受带 `_notify` 的 `app.*` 事件，并做 sender issuer 绑定校验。
+- notify 默认不做 E2EE；敏感、可靠、需审计内容必须走消息通道。
+
+## 适用场景
+
+适合：
+
+- typing / composing。
+- 临时在线状态。
+- UI 提示。
+- 轻量 wake hint。
+- “在线的话刷新一下”。
+- push proxy 在线时接收离线摘要。
+
+不适合：
+
+- 任务完成结果。
+- 文件可用通知。
+- 重要业务事件。
+- 需要离线后还能看到的状态。
+- 需要审计、ack、重放保护的内容。
+
+这些场景应继续使用：
+
+```text
+message.send(payload.type="event")
+group.send(payload.type="event")
+```
+
+## 与现有 RPC/事件的分工
+
+| 能力 | `notify()` | `message.send` / `group.send` |
+|------|------------|--------------------------------|
+| JSON-RPC 类型 | Notification | Request |
+| 是否等待业务响应 | 否 | 是 |
+| 离线存储 | 否 | 是，取决于消息通道配置 |
+| seq / pull / ack | 否 | 是 |
+| 默认 E2EE | 否 | SDK 默认加密 |
+| 跨域 | 支持在线 federation 转发，best-effort | 支持可靠跨域消息 |
+| 适合内容 | 瞬时在线提示 | 可靠业务消息和事件 |
+| 失败处理 | 丢弃 | 返回错误或后续 pull/ack 补偿 |
+
+## 测试覆盖
+
+notify 专项测试覆盖：
+
+- 四端 SDK 单元测试：Notification 无 `id`、AID/group route 包装。
+- 单域集成：AID 在线实时投递、group 在线成员投递。
+- E2E：`device_id` / `slot_id` 精确投递、离线不存储不补发。
+- 双域跨域：Python / TypeScript / Go / 浏览器 JavaScript 从 `aid.com` 在线投递到 `aid.net`。

package/_packed_docs/sdk/README.md

@@ -10,7 +10,8 @@ AUN（Agent Union Network）定义 Agent 之间安全通信的标准接口，基
 - **三主体 SDK 模型**：`AIDStore` 管理 keystore，`AID` 是不可变身份值对象，`AUNClient` 管理连接与会话。
 - **Gateway 连接**：当前各语言 SDK 稳定支持 Gateway 接入；Peer / Relay 仍处于协议定义或未实现状态。
 - **默认 E2EE**：P2P 和 Group V2 消息默认加密；普通明文消息需要显式关闭加密。
-- **统一 RPC**：业务方法通过 `client.call(method, params)` 调用，事件通过 `client.on(event, handler)` 订阅；在线轻量通知方案见 `Notify通知方案.md`。
+- **统一 RPC / 事件 / Notify**：业务方法通过 `client.call(method, params)` 调用，事件通过 `client.on(event, handler)` 订阅；在线轻量通知通过 `client.notify()` 发送，支持同域和跨域在线 federation，详见 `Notify通知方案.md`。
+- **Service Proxy**：Python SDK 提供 `ServiceProxyClient`，provider 会先向 Gateway 注册 `proxy.*` 控制面服务列表，再在每条 proxy-server 隧道认证后注册数据面服务列表。
 
 ---
 
@@ -107,10 +108,10 @@ Layer 1: 安全层   TLS + AUN E2EE
 | [03-核心概念](03-核心概念.md) | AID、AIDStore、AUNClient、九态状态机、E2EE |
 | [04-连接与认证](04-连接与认证.md) | 注册、加载、认证、连接、事件、agent.md |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 收发、ProtectedHeaders、密钥管理 |
-| [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / 事件 / RPC 索引 |
+| [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / ServiceProxyClient / 事件 / RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result、异常层级、错误码、重试策略 |
 | [08-最佳实践](08-最佳实践.md) | 幂等连接、多 AID、资源清理、测试数据保护 |
-| [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知设计 |
+| [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知、跨域 federation 和可靠消息分工 |
 
 RPC 专项手册：
 
@@ -119,9 +120,10 @@ RPC 专项手册：
 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | P2P 消息、ack、thought |
 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | 群组生命周期、成员、群消息、群 thought |
 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | 文件和对象存储 |
-| [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | ping / status / trust_roots |
-| [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | 流式数据传输 |
-| [09-payload-reference.md](09-payload-reference.md) | message / group payload 结构 |
+| [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | ping / status / trust_roots |
+| [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | 流式数据传输 |
+| [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | Service Proxy 控制面 RPC 和数据面隧道注册 |
+| [09-payload-reference.md](09-payload-reference.md) | message / group payload 结构 |
 | [09-custody-api-manual.md](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
 
 协议文档随 SDK 包分发，位于 `aun_core/docs/protocol/`。