@agentunion/fastaun-browser 0.4.9 → 0.4.10

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

@@ -6,11 +6,12 @@
 
 - [AIDStore](#aidstore)
 - [AID](#aid)
-- [AUNClient](#aunclient)
-- [事件](#事件)
-- [E2EE 高级 API](#e2ee-高级-api)
-- [RPC 方法参考](#rpc-方法参考)
-- [Stream 使用指南](#stream-使用指南)
+- [AUNClient](#aunclient)
+- [事件](#事件)
+- [ServiceProxyClient](#serviceproxyclient)
+- [E2EE 高级 API](#e2ee-高级-api)
+- [RPC 方法参考](#rpc-方法参考)
+- [Stream 使用指南](#stream-使用指南)
 
 > **多语言命名约定**：Python 使用 `snake_case`（如 `aun_path`、`download_agent_md`），TS/JS 使用 `camelCase`（如 `aunPath`、`downloadAgentMd`），Go 使用 `PascalCase` 公开方法（如 `Load`、`Register`）。本手册表格中各列对应各语言的实际命名。
 
@@ -238,16 +239,51 @@ result = await client.call("message.send", {
 })
 ```
 
-常用 meta RPC 直接透传：
-
-```python
-await client.call("meta.ping", {})
-await client.call("meta.status", {})
-await client.call("meta.trust_roots", {})
-```
-
-### protected_headers
-
+常用 meta RPC 直接透传：
+
+```python
+await client.call("meta.ping", {})
+await client.call("meta.status", {})
+await client.call("meta.trust_roots", {})
+```
+
+### Notify
+
+`notify()` 发送轻量在线通知，底层是 JSON-RPC Notification，无 `id`，不进入离线存储、seq、pull 或 ack。
+
+| Python | TS/JS | Go | 说明 |
+|--------|-------|----|------|
+| `notify(method, params=None, *, to=None, group_id=None, device_id=None, slot_id=None, ttl_ms=None)` | `notify(method, params?, options?)` | `Notify(ctx, method, params, NotifyOptions{...})` | 发送在线轻量通知 |
+
+常见用法：
+
+```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")
+```
+
+路由选项：
+
+| 选项 | 说明 |
+|------|------|
+| `to` / `To` | 目标 AID；可同域或跨域 |
+| `group_id` / `groupId` / `GroupID` | 目标群；与 `to` 互斥 |
+| `device_id` / `deviceId` / `DeviceID` | 限定目标 AID 的在线设备；必须配合 `to` |
+| `slot_id` / `slotId` / `SlotID` | 限定目标设备的在线 slot；必须配合 `device_id` |
+| `ttl_ms` / `ttlMs` / `TTLMS` | `0..60000`，只控制在线投递过期，不表示离线缓存 |
+
+约束：
+
+- 未指定 `to` / `group_id` 时，`method` 必须以 `notification/` 开头，表示直发 Gateway 的协议级通知。
+- 指定 `to` 或 `group_id` 时，`method` 必须是 `event/app.*`，接收端通过 `client.on("app.xxx", handler)` 订阅。
+- 跨域 AID notify 已支持 federation 在线转发，但仍是 best-effort；目标离线或 federation 不可用时丢弃。
+- 可靠、敏感或需要审计的业务事件应继续使用 `message.send` / `group.send`。
+
+详细语义见 [Notify通知方案.md](Notify通知方案.md)。
+
+### protected_headers
+
 ```python
 client = AUNClient(aid)
 client.set_protected_headers({"sdk": "python", "trace": "abc"})
@@ -275,13 +311,62 @@ headers = client.get_protected_headers()
 - 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
 - SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
 - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
-
----
-
-## 事件
-
-```python
-sub = client.on("message.received", handler)
+
+---
+
+## ServiceProxyClient
+
+Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
+
+```python
+from aun_core.service_proxy import ServiceProxyClient
+
+proxy_client = ServiceProxyClient(
+    provider_aid="alice.agentid.pub",
+    aun_client=client,
+)
+proxy_client.register_service(
+    "fileshare",
+    "http://127.0.0.1:8080",
+    visibility="public",
+)
+await proxy_client.serve_forever()
+```
+
+proxy-server 连接地址不能由应用外部传入或配置。`ServiceProxyClient` 会先读取 provider AID 本地 SQLite metadata 中 1 小时 TTL 的 `service_proxy_discovery` 缓存；缓存缺失或过期时，按协议查询 `https://{provider_aid}/.well-known/aun-proxy`，失败后回退 `https://proxy.{issuer}/.well-known/aun-proxy`，并使用返回的 `ws_url` 建立隧道。
+
+关键 API：
+
+| Python | 说明 |
+|--------|------|
+| `register_service(service_name, endpoint, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
+| `unregister_service(service_name)` | 注销本地服务 |
+| `list_service_summaries()` | 获取可上报到 Gateway 和 proxy-server 的服务摘要 |
+| `register_services_with_gateway()` | 显式调用 Gateway `proxy.register_services` |
+| `unregister_services_from_gateway(service_names=None)` | 显式调用 Gateway `proxy.unregister_services` |
+| `list_gateway_services()` | 显式调用 Gateway `proxy.list_services` |
+| `register_services_with_proxy_server(ws)` | 通过已认证 proxy-server 隧道发送 `register_services` |
+| `discover_proxy_server(force_refresh=False)` | 通过缓存 / well-known 发现 proxy-server |
+| `connect_once()` | 建立一次 proxy-server 隧道并完成认证、数据面注册和可选心跳 |
+| `serve_once()` | 处理有限数量的 proxy-server 转发请求 |
+| `serve_forever(connection_mode="persistent")` | 持续提供 Service Proxy 服务；支持 persistent / on_demand |
+
+自动注册顺序：
+
+- `connect_once()`、`serve_once()`、`serve_forever()` 在存在 `aun_client.call()` 时，会先向 Gateway 调用 `proxy.register_services`。
+- 建立 proxy-server 隧道前，SDK 必须通过缓存 / `/.well-known/aun-proxy` 发现得到 `ws_url`；不得由应用传入或配置 proxy-server 地址。
+- proxy-server 隧道使用 `Authorization: Bearer <access_token>` 鉴权；SDK 优先复用 cached token，缺失或过期时通过 `aun_client.authenticate()` 向 Gateway 完成登录刷新。
+- 每次 proxy-server 隧道认证成功后，都会立即向 proxy-server 发送 `register_services` 隧道消息。
+- 服务列表与连接绑定；断开 Gateway 长连接或 proxy-server 隧道后，相应注册立即失效。
+
+详细控制面 RPC、隧道消息和路由语义见 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md)。
+
+---
+
+## 事件
+
+```python
+sub = client.on("message.received", handler)
 client.off("message.received", handler)
 sub.unsubscribe()
 ```
@@ -325,11 +410,12 @@ sub.unsubscribe()
 |------|------|----------|
 | 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.ack` / `message.thought.*` |
 | 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.invite` / `group.send` / `group.v2.*` |
-| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.upload` / `storage.download` / `storage.share` |
-| 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |
-| Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
-
----
+| 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.upload` / `storage.download` / `storage.share` |
+| 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |
+| Stream | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | `stream.create` / `stream.close` / `stream.list_active` |
+| Service Proxy | [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) | `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` |
+
+---
 
 ## Stream 使用指南
 

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

@@ -67,6 +67,7 @@
 | 方法 | 说明 |
 |------|------|
 | [group.send](#groupsend) | 发送群消息 |
+| [group.recall](#grouprecall) | 撤回群消息 |
 | [group.thought.put](#groupthoughtput) | 写入某个群上下文的思考内容 |
 | [group.thought.get](#groupthoughtget) | 获取某个群上下文的思考内容 |
 | [group.pull](#grouppull) | 增量拉取消息 |
@@ -1173,6 +1174,59 @@ result = await client.call("group.thought.get", {
 {"cursor": 42}
 ```
 
+### group.recall
+
+撤回群消息。仅**原发送者**可撤回自己的消息，受时间窗口限制（默认 **120 秒**，由群服务配置 `recall_window_seconds` 控制，`0` 表示不限制）。管理员撤回（`group_admin_recall_enabled`）默认关闭，本期不实现。
+
+**双 tombstone 机制**：群消息使用 per-group 全局 `message_seq`（V1/V2 共享同一空间），直接删除原消息会让"还没拉到原消息"的客户端遇到永久 seq 空洞。因此撤回写入两条 tombstone：
+
+- **原 seq 占位 tombstone**：占住被撤消息原来的 seq。V1 把原 `group_messages` 行 `message_type` 改为 `group.message_recalled` 并清空正文；V2 删除 `v2_group_messages` 密文体与所有 `v2_group_wraps`，再在 `group_messages` 插入同 `original_seq` 的明文 tombstone 顶替。服务对象是**还没读到原消息**的客户端——拉到该 seq 看到 tombstone，而非空洞。
+- **新 seq 通知 tombstone**：分配一个新的 `message_seq`，通知**已经读过原消息**（游标已越过 `original_seq`）的客户端"这条消息被撤回了"。
+
+同时写一条 `group_events`（`event_type = group.message_recalled`）用于事件流审计，并在事务提交后推送 `event/group.message_recalled`（见下）。撤回真相记录在 `group_message_recalls` 表，`(group_id, original_message_id)` 与 `(group_id, original_seq)` 双唯一键防止重复撤回。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
+| `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
+
+**响应**：
+
+```json
+{
+    "success": true,
+    "accepted": ["gm-aaa", "gm-bbb"],
+    "recalled": ["gm-aaa"],
+    "errors": [
+        {"message_id": "gm-bbb", "error": "not_sender"}
+    ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | 整体是否受理 |
+| `accepted` | string[] | 通过时间窗口前置过滤、进入撤回事务的消息 ID |
+| `recalled` | string[] | DB 真实撤回成功的消息 ID（避免并发撤回误通知）|
+| `errors` | array | 逐条错误：`{message_id, error}` |
+
+**逐条错误码**：
+
+| error | 说明 |
+|-------|------|
+| `not_found` | 消息不存在 |
+| `not_sender` | 操作者不是原发送者 |
+| `already_recalled` | 消息已被撤回（命中唯一键 / 占位 tombstone 已存在）|
+| `expired` | 超过撤回时间窗口 |
+| `group_inactive` | 群组非 active 状态（suspended / dissolved）|
+
+**SDK 行为**：SDK 把 pull / push 收到的撤回 tombstone（占位与通知）归一化为 `group.message_recalled` 应用事件，**不**作为普通 `group.message_created` 交付；tombstone 仍占 seq，正常推进 SeqTracker 与 ack。SDK 按 `(group_id, message_ids)` 去重，因此即使同时收到在线 push 事件、占位 tombstone、通知 tombstone，应用层也**只回调一次**。去重键**不含 `recalled_at`**：占位 tombstone、通知 tombstone 与在线 push 三条通道对同一次撤回可能携带不同来源的时间戳（push 在事务提交后重取），若纳入 `recalled_at` 会使去重失效、导致重复回调；一条消息只能被撤回一次（服务端 `group_message_recalls` 唯一键保证），`(group_id, message_ids)` 已能唯一标识一次撤回。
+
+> 所有语言 SDK 统一通过 `client.call("group.recall", {...})` 调用，不提供独立的便捷方法名。
+
 ---
 
 ## 公告与规则
@@ -1874,6 +1928,49 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
 
 SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
 
+### event/group.message_recalled
+
+群消息撤回后推送给所有在线成员（与 pull 双 tombstone 兜底互补）。在线 push 是实时通道，双 tombstone 是离线 / 未读 / push 丢失时的可靠性兜底；两者最终一致，SDK 去重保证应用层只感知一次。
+
+**Payload**：
+
+```json
+{
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 43,
+    "message_id": "grm-uuid",
+    "message_ids": ["gm-aaa"],
+    "target_message_seqs": [42],
+    "sender_aid": "alice.agentid.pub",
+    "recalled_by": "alice.agentid.pub",
+    "recalled_at": 1234567890000,
+    "reason": "",
+    "member_aids": ["bob.agentid.pub"]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `module_id` | string | 固定 `"group"` |
+| `group_id` | string | 群组 ID |
+| `seq` | integer | 撤回通知 tombstone 的**新群消息 seq** |
+| `message_id` | string | 撤回通知 tombstone 自己的 message_id |
+| `message_ids` | string[] | 被撤回的**原消息 ID 列表** |
+| `target_message_seqs` | integer[] | 被撤回的原消息 seq 列表 |
+| `sender_aid` | string | 原消息发送方 |
+| `recalled_by` | string | 撤回操作者 |
+| `recalled_at` | integer | 撤回时间戳（毫秒）|
+| `reason` | string | 可选撤回理由 |
+
+跨域成员通过 federation forward 转发（`group.message_recalled` 在跨域转发白名单内），路径与 `group.message_created` 一致。
+
+**订阅**：
+
+```python
+client.on("group.message_recalled", lambda ev: print("recalled:", ev["message_ids"]))
+```
+
 ---
 
 ## 错误码

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

@@ -0,0 +1,231 @@
+# Service Proxy — RPC Manual
+
+## 方法索引
+
+### Gateway 控制面方法
+
+| 方法 | 说明 |
+|------|------|
+| [proxy.register_services](#proxyregister_services) | 注册当前 Gateway 长连接可提供的 Service Proxy 服务列表 |
+| [proxy.unregister_services](#proxyunregister_services) | 注销当前 Gateway 长连接上的部分或全部服务列表 |
+| [proxy.list_services](#proxylist_services) | 查询当前 Gateway 长连接已注册的服务列表 |
+
+### proxy-server 数据面隧道消息
+
+| 消息 | 方向 | 说明 |
+|------|------|------|
+| [register_services](#register_services-隧道消息) | proxy-client → proxy-server | proxy-server 隧道认证后注册本连接的数据面服务列表 |
+| `register_services_ack` | proxy-server → proxy-client | 数据面服务注册成功确认 |
+
+---
+
+## 控制面与数据面
+
+Service Proxy 有两层注册，二者都必须存在：
+
+- **Gateway 控制面**：provider 的 AUN 长连接调用 `proxy.register_services`，Gateway 记录该 provider 在线且声明了哪些服务。proxy-server 用它判断 provider 是否在线、目标服务是否声明、是否应该 wakeup。
+- **proxy-server 数据面**：proxy-client 连接 proxy-server 的 `/ws/client` 并完成认证后，必须再发送 `register_services` 隧道消息。proxy-server 只会向本地已注册目标服务的数据面连接转发请求。
+
+服务列表与连接绑定。Gateway 长连接断开后，Gateway 上的服务列表立即失效；proxy-server 隧道断开后，proxy-server 上的服务列表立即失效。
+
+同一个 provider AID 可以有多个实例连接，但所有实例注册的服务摘要必须一致。若同一 provider AID 的第二条连接注册了不同服务列表，服务端应拒绝该次注册并返回 `proxy_services_inconsistent`。
+
+---
+
+## 服务摘要
+
+服务摘要只描述可公开发现的服务能力，不包含本地 endpoint。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `service_name` | string | 是 | 服务名，建议使用 `[a-z0-9_-]+` |
+| `service_type` | string | 否 | 服务类型，默认 `http`；常见值为 `http` / `websocket` / `sse` / `mcp` |
+| `visibility` | string | 否 | 可见性，默认 `private` |
+| `metadata` | object | 否 | 非敏感描述信息。服务端会移除 token、secret、endpoint、url、cookie、key、cert 等敏感字段 |
+
+Python `ServiceProxyClient.register_service()` 会保存本地 endpoint，但 `list_service_summaries()`、Gateway 注册和 proxy-server 注册只发送摘要。
+
+---
+
+## proxy.register_services
+
+注册当前 Gateway 长连接提供的 Service Proxy 服务列表。服务端必须以连接认证得到的 AID 作为 provider AID，不能信任客户端传入的 `provider_aid` 覆盖认证身份。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `provider_aid` | string | 否 | 兼容字段或诊断字段；服务端以认证身份为准 |
+| `services` | array | 是 | 服务摘要列表 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | boolean | 固定为 `true` |
+| `provider_aid` | string | 认证后的 provider AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `count` | integer | 已注册服务数量 |
+| `services` | array | 服务端清洗后的服务摘要列表 |
+
+### 示例
+
+```python
+result = await client.call("proxy.register_services", {
+    "services": [
+        {
+            "service_name": "fileshare",
+            "service_type": "http",
+            "visibility": "public",
+            "metadata": {"label": "Files"},
+        }
+    ],
+})
+```
+
+### 错误
+
+| JSON-RPC code | message | 原因 |
+|---------------|---------|------|
+| -32602 | `proxy service registration requires a long connection` | 短连接不能注册 Service Proxy 服务 |
+| -32020 | `proxy_services_inconsistent` | 同一 provider AID 的已有连接注册了不一致的服务列表 |
+
+---
+
+## proxy.unregister_services
+
+注销当前 Gateway 长连接上的部分或全部服务。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `service_names` | array | 否 | 要注销的服务名列表；省略时注销当前连接上的全部服务 |
+| `service_name` | string | 否 | 单服务兼容字段 |
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | boolean | 固定为 `true` |
+| `provider_aid` | string | 认证后的 provider AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `removed` | array | 实际移除的服务名 |
+| `count` | integer | 剩余服务数量；全部注销时可省略 |
+
+### 示例
+
+```python
+await client.call("proxy.unregister_services", {
+    "service_names": ["fileshare"],
+})
+```
+
+---
+
+## proxy.list_services
+
+查询当前 Gateway 长连接已注册的 Service Proxy 服务列表。
+
+### 参数
+
+无有效参数。`provider_aid` 若存在，也只能作为兼容字段；服务端以当前连接身份为准。
+
+### 响应
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `provider_aid` | string | 当前连接认证后的 AID |
+| `connection_id` | string | Gateway 连接 ID |
+| `services` | array | 当前连接已注册的服务摘要列表 |
+
+### 示例
+
+```python
+current = await client.call("proxy.list_services", {})
+```
+
+---
+
+## register_services 隧道消息
+
+proxy-client 连接 proxy-server `/ws/client` 并收到 `service_proxy_auth_response.ok=true` 后，必须立即发送 `register_services` 隧道消息。proxy-server 只根据这个数据面注册表选择实际转发连接。
+
+### 请求
+
+```json
+{
+  "type": "register_services",
+  "request_id": "register-services",
+  "services": [
+    {
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }
+  ]
+}
+```
+
+### 成功响应
+
+```json
+{"type": "register_services_ack", "request_id": "register-services", "ok": true, "count": 1}
+```
+
+### 失败响应
+
+```json
+{
+  "type": "service_proxy_error",
+  "request_id": "register-services",
+  "error": {
+    "code": "proxy_services_inconsistent",
+    "message": "provider service list is inconsistent with existing connections"
+  }
+}
+```
+
+---
+
+## Python ServiceProxyClient
+
+Python SDK 的 `ServiceProxyClient` 已封装双注册流程：
+
+1. `connect_once()` / `serve_once()` / `serve_forever()` 建立 proxy-server 隧道前，会在存在 `aun_client.call()` 时自动调用 `proxy.register_services`。
+2. proxy-server 连接地址必须通过 `/.well-known/aun-proxy` 发现：先读 provider AID SQLite metadata 中 1 小时 TTL 的 `service_proxy_discovery` 缓存；缓存缺失或过期时查询 `https://{provider_aid}/.well-known/aun-proxy`，失败后回退 `https://proxy.{issuer}/.well-known/aun-proxy`。应用不得传入、配置或硬拼 proxy-server URL。
+3. proxy-server 隧道使用 AUN auth token 鉴权：优先复用 cached access token；缓存缺失或过期时，必须通过 `aun_client.authenticate()` 经 Gateway 两步登录刷新 token。
+4. proxy-server 隧道认证成功后，会自动发送 `register_services` 隧道消息。
+5. persistent 和 on-demand 重连时，每条新连接都会重新执行以上流程。
+
+常用入口：
+
+| 方法 | 说明 |
+|------|------|
+| `register_service(name, endpoint, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
+| `unregister_service(name)` | 移除本地 endpoint |
+| `list_service_summaries()` | 返回可上报的服务摘要 |
+| `register_services_with_gateway()` | 显式向 Gateway 注册控制面服务列表 |
+| `unregister_services_from_gateway(names=None)` | 显式从 Gateway 注销控制面服务 |
+| `list_gateway_services()` | 查询 Gateway 当前连接服务列表 |
+| `register_services_with_proxy_server(ws)` | 通过已认证 proxy-server 隧道注册数据面服务列表 |
+| `discover_proxy_server(force_refresh=False)` | 通过缓存 / well-known 发现 proxy-server |
+| `serve_once()` / `serve_forever()` | 连接 proxy-server 并处理转发请求 |
+
+---
+
+## 路由与 wakeup 语义
+
+proxy-server 收到 `https://proxy.{issuer}/{user_name}/{svc_name}` 或对应 WebSocket 请求时，应按以下顺序处理：
+
+1. 本 proxy-server 已有 `(provider_aid, service_name)` 数据面连接：直接转发，并按 visitor/provider/service 维持稳定粘性。
+2. provider 已连接本 proxy-server 且已注册服务列表，但没有目标服务：返回 `service_not_registered`，不 wakeup。
+3. provider 未连接本 proxy-server：查询 Gateway 控制面。
+4. Gateway 检查 provider AID 证书不存在：返回 `provider_aid_not_found`；证书查询失败：返回 `provider_aid_check_failed`。
+5. Gateway 显示 provider 没有在线长连接：返回 `provider_offline`。
+6. Gateway 显示 provider 在线但未声明目标服务：返回 `service_not_registered`，不 wakeup。
+7. Gateway 显示 provider 在线且声明目标服务：仅向注册了该服务的 provider 连接发送 wakeup。
+8. wakeup 已投递但本 proxy-server 等不到目标数据面隧道注册时，返回 `provider_wakeup_timeout`。
+
+因此，只向 Gateway 注册不足以承载请求；只有 proxy-server 数据面也注册了目标服务，访问才会真正转发。