@agentunion/fastaun-browser 0.4.8 → 0.4.10

package/_packed_docs/sdk/09-storage-rpc-manual.md

@@ -24,6 +24,14 @@
 | [storage.complete_upload](#storagecomplete_upload) | 确认上传完成 |
 | [storage.create_download_ticket](#storagecreate_download_ticket) | 申请下载 URL |
 
+### 分享方法
+
+| 方法 | 说明 |
+|------|------|
+| [storage.create_share_link](#storagecreate_share_link) | 创建分享链接 |
+| [storage.list_share_links](#storagelist_share_links) | 列举分享链接 |
+| [storage.revoke_share_link](#storagerevoke_share_link) | 撤销分享链接 |
+
 ---
 
 > `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
@@ -51,6 +59,8 @@
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转到直链 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
@@ -313,12 +323,13 @@ for obj in result["items"]:
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `object_key` | string | 是 | 对象路径 |
-| `sha256` | string | 是 | 文件 SHA-256 哈希 |
+| `sha256` | string | 否 | 文件 SHA-256 哈希；提供则校验完整性，`skip_blob=true` 时必填 |
 | `bucket` | string | 否 | 存储桶，默认 `"default"` |
 | `owner_aid` | string | 否 | 所有者 AID，默认当前用户 |
 | `content_type` | string | 否 | MIME 类型，默认 `"application/octet-stream"` |
 | `is_private` | boolean | 否 | 是否私有，默认 `true` |
 | `size_bytes` | integer | 否 | 预期文件大小（用于校验） |
+| `skip_blob` | boolean | 否 | 秒传模式，默认 `false`；为 `true` 时跳过 blob 上传，必须提供 `sha256` 且服务端已存在对应内容 |
 | `expected_version` | integer | 否 | 乐观并发控制版本号 |
 | `expire_in_seconds` | integer | 否 | 过期时间（秒） |
 | `metadata` | object | 否 | 自定义元数据 |
@@ -327,6 +338,8 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，无跳转 |
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
@@ -356,8 +369,10 @@ for obj in result["items"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `download_url` | string | 下载用 presigned URL |
-| `expire_at` | integer | URL 过期时间戳 |
+| `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/storage/{object_key}`，经 NameService 302 跳转 |
+| `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
+| `download_url` | string | 预签名下载 URL（有时效，签名形式由 BlobStore 后端决定） |
+| `expire_at` | integer | `download_url` 的过期时间戳（Unix 秒） |
 | `file_name` | string | 文件名（从 object_key 提取） |
 | `size_bytes` | integer | 文件大小（字节） |
 | `content_type` | string | MIME 类型 |
@@ -365,7 +380,7 @@ for obj in result["items"]:
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
 
-客户端获得 `download_url` 后，通过 HTTP GET 下载文件。
+客户端获得 `download_url` 后，通过 HTTP GET 下载文件。`url` 为永久可分享的 AID 风格链接，`logical_url` 为无跳转直链。
 
 > 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
 
@@ -486,6 +501,104 @@ else:
 
 ---
 
+## storage.create_share_link
+
+创建分享链接。生成一个短码（share_id），通过短码可访问对象，支持授权 AID 白名单、有效期、使用次数限制。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `object_key` | string | 是 | 被分享对象的路径 |
+| `bucket` | string | 否 | 存储桶，默认 `"default"` |
+| `owner_aid` | string | 否 | 对象所有者 AID，默认当前用户（仅可分享自己的对象） |
+| `allowed_aids` | string[] | 否 | 授权访问的 AID 列表，默认 `["*"]`（任意 AID 可访问）；含 `"*"` 即视为公开 |
+| `expire_in_seconds` | integer | 否 | 有效期（秒），默认 86400（1 天），`0` 表示永不过期 |
+| `max_uses` | integer | 否 | 最大使用次数，默认 `0`（无限制） |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `share_id` | string | 10 位 Base62 分享短码 |
+| `aid_share_url` | string | **AID 风格分享 URL（默认/推荐）**：`https://{owner_aid}/storage/{share_id}`，体现分享者身份 |
+| `share_url` | string | 直链分享 URL：`{base_url}/s/{share_id}`，兼容字段 |
+| `expire_at` | integer | 过期时间戳（Unix 秒），`0` 表示永不过期 |
+| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
+| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+
+> 访问 `aid_share_url` 时经 NameService 302 跳转到 `share_url`。share_id 是 10 位无斜杠 Base62，与 object_key 路径天然区分（object_key 含 `/` 或非 10 位）。
+> share_id 指向 `(owner_aid, bucket, object_key)` 逻辑引用，非内容快照：对象改名/移动后原 share_id 失效，内容覆盖后下载到新内容。
+
+### 示例
+
+```python
+result = await client.call("storage.create_share_link", {
+    "object_key": "docs/report.pdf",
+    "allowed_aids": ["alice.agentid.pub"],
+    "expire_in_seconds": 3600,
+    "max_uses": 5,
+})
+share_url = result["aid_share_url"]
+```
+
+---
+
+## storage.list_share_links
+
+列举分享链接，可按 bucket / object_key 过滤。仅返回当前用户自己创建的链接。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bucket` | string | 否 | 按存储桶过滤 |
+| `object_key` | string | 否 | 按对象路径过滤 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `links` | array | 分享链接列表 |
+
+每个 link 包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `share_id` | string | 分享短码 |
+| `aid_share_url` | string | AID 风格分享 URL（主字段） |
+| `share_url` | string | 直链分享 URL（兼容） |
+| `object_key` | string | 被分享对象路径 |
+| `bucket` | string | 存储桶 |
+| `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+| `expire_at` | integer | 过期时间戳（秒），`0` 表示永不过期 |
+| `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
+| `used_count` | integer | 已使用次数 |
+| `created_at` | integer | 创建时间戳（毫秒） |
+
+---
+
+## storage.revoke_share_link
+
+撤销分享链接。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `share_id` | string | 是 | 待撤销的分享短码 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `revoked` | boolean | 是否成功撤销 |
+| `share_id` | string | 被撤销的分享短码 |
+
+> 链接不存在或已撤销时返回通用错误（`-32000`）。
+
+---
+
 ## 错误码
 
 | code | 说明 |

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`。
+- `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`。
 
 ## 渐进式查阅流程
 
@@ -25,7 +26,8 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
-- RPC 与事件：`client.call()`、`client.on()`、RPC 手册
+- 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 服务 |
 
 ## 常见查阅场景
 
@@ -58,7 +61,9 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 | 发布、下载或检查 agent.md | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
 | 查方法签名 | [06-API手册](06-API手册.md) |
-| 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
-| 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
+| 查消息或群组 RPC | 对应 `09-*-rpc-manual.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

@@ -20,10 +20,12 @@
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
 | [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC |
-| [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-custody-api-manual](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
+| [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()` 在线轻量通知、跨域 federation 和可靠消息分工 |
 
 ---
 
@@ -54,13 +56,15 @@
 
 ### RPC 与事件
 
-- `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
-- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
+- `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.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)
 
 ### 错误与测试
 
@@ -95,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-错误处理
 
@@ -105,6 +109,14 @@
 
 给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control 和测试数据保护建议。
 
-### 09-*-rpc-manual
-
-各业务服务的 RPC 参数、响应和错误语义。SDK 不为每个 RPC 提供一层业务 wrapper，应用直接通过 `client.call()` 调用。
+### 09-*-rpc-manual
+
+各业务服务的 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/群路由方式、跨域 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)` 订阅。
+- **统一 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,9 +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、资源清理、测试数据保护 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接、多 AID、资源清理、测试数据保护 |
+| [Notify通知方案](Notify通知方案.md) | `client.notify()` 在线轻量通知、跨域 federation 和可靠消息分工 |
 
 RPC 专项手册：
 
@@ -118,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/`。