@agentunion/fastaun-browser 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -6,6 +6,22 @@
 
 ---
 
+## 0.4.10 — 2026-06-06
+
+### 新功能
+- **Service Proxy 服务代理**：新增 `service-proxy.ts` 客户端（控制面 `proxy.register`/`unregister`/`list_services` + 数据面隧道）及 `tools/service-proxy-holder-boundary.mjs`、`tools/service-proxy-visitor.mjs` 工具（四语言对齐）
+- **notify() 单向通知**：新增 `notify()` 公开 API，发送无 id 的 JSON-RPC 2.0 Notification，只面向在线长连接、不落库、不分配 seq、无 ack（四语言对齐）
+- **Storage 逻辑下载 URL**：支持干净逻辑下载 URL `storage.{issuer}/{user_name}/{object_key}`，无签名无 CAS
+
+### 修复
+- **群消息撤回（`group.message_recalled`）端到端打通**：新增在线 push 通道（`_raw.group.message_recalled`），与 pull 双 tombstone（占位 + 通知）兜底互补；push 路径推进 `notice_seq` 的 seq/ack 与普通群消息对齐，避免 seq 留洞导致重复拉取；按 `(group_id, message_ids)` 去重（去重键不含 `recalled_at`），确保应用层只回调一次（四语言+服务端对齐）
+- `group.recall` 加入 RPC 白名单；`transport` 事件名映射补充 `group.message_recalled`
+
+### 测试
+- `tests/e2e-browser/notify.spec.ts`/`tests/integration/notify.test.ts` 覆盖 notify；`service-proxy` 系列单元+集成+E2E 测试；`tests/e2e-browser/v2-group.spec.ts` 补充群撤回断言
+
+---
+
 ## 0.4.9 — 2026-06-03
 
 ### 修复

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,22 @@
 
 ---
 
+## 0.4.10 — 2026-06-06
+
+### 新功能
+- **Service Proxy 服务代理**：新增 `service-proxy.ts` 客户端（控制面 `proxy.register`/`unregister`/`list_services` + 数据面隧道）及 `tools/service-proxy-holder-boundary.mjs`、`tools/service-proxy-visitor.mjs` 工具（四语言对齐）
+- **notify() 单向通知**：新增 `notify()` 公开 API，发送无 id 的 JSON-RPC 2.0 Notification，只面向在线长连接、不落库、不分配 seq、无 ack（四语言对齐）
+- **Storage 逻辑下载 URL**：支持干净逻辑下载 URL `storage.{issuer}/{user_name}/{object_key}`，无签名无 CAS
+
+### 修复
+- **群消息撤回（`group.message_recalled`）端到端打通**：新增在线 push 通道（`_raw.group.message_recalled`），与 pull 双 tombstone（占位 + 通知）兜底互补；push 路径推进 `notice_seq` 的 seq/ack 与普通群消息对齐，避免 seq 留洞导致重复拉取；按 `(group_id, message_ids)` 去重（去重键不含 `recalled_at`），确保应用层只回调一次（四语言+服务端对齐）
+- `group.recall` 加入 RPC 白名单；`transport` 事件名映射补充 `group.message_recalled`
+
+### 测试
+- `tests/e2e-browser/notify.spec.ts`/`tests/integration/notify.test.ts` 覆盖 notify；`service-proxy` 系列单元+集成+E2E 测试；`tests/e2e-browser/v2-group.spec.ts` 补充群撤回断言
+
+---
+
 ## 0.4.9 — 2026-06-03
 
 ### 修复

package/_packed_docs/INDEX.md

@@ -8,7 +8,7 @@
 
 | 文档 | 定位 |
 | --- | --- |
-| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
+| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 与 Service Proxy E2E 测试运行命令 |
 | [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md) | 本轮 SDK 重构的实际修改点、测试结果和遗留事项 |
 | [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md) | Python / Go / TS / JS SDK AUNClient 内部拆分边界、执行步骤和验收矩阵 |
 | [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md) | AUNClient 完全门面化、ClientRuntime 单一状态源和四端分批迁移步骤 |
@@ -17,10 +17,12 @@
 | [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md) | RPC trace 诊断字段与 enter/exit span 设计 |
 | [AUN 服务端消息通信诊断面板方案](design/AUN服务端消息通信诊断面板方案.md) | aun-console 消息通信页的服务端可观察诊断面板总体方案 |
 | [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md) | aun-console 消息通信页的服务端可观察 P0 诊断面板 |
+| [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、消息信封与 RPC 响应 ETag 透传方案 |
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE 手册的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
-| [Notify 通知方案](sdk/Notify通知方案.md) | `client.notify()` 在线轻量通知、路由和可靠消息分工 |
+| [Notify 通知方案](sdk/Notify通知方案.md) | `client.notify()` 在线轻量通知、跨域 federation 和可靠消息分工 |
+| [Service Proxy RPC 手册](sdk/09-proxy-rpc-manual.md) | `proxy.*` 控制面、proxy-server 数据面注册、服务列表一致性和 wakeup 路由语义 |
 | [协议文档目录](protocol/) | AUN 协议相关文档 |
 | [审查与路线图目录](audit/) | 历史审查、修复路线图、测试补充清单 |
 | [superpowers 目录](superpowers/) | AUN SDK 规范类补充文档 |
@@ -35,19 +37,26 @@
 - 本轮 SDK 重构阶段进度、修改点和测试结果 → [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md)
 - AUNClient 巨类拆分、内部组件边界、逐步迁移和验收矩阵 → [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md)
 - AUNClient 完全门面化、Runtime 状态归属、状态写入收口和四端分批实施 → [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md)
-- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- Python / TypeScript / Go 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 - 多语言 SDK 测试缺口与补测清单 → [审查与路线图目录](audit/)
 
 ### SDK 使用与协议
 
 - Python / TS / Go / JS SDK 使用手册、RPC 参数、E2EE 机制 → [SDK 文档索引](sdk/INDEX.md)
 - 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
-- `client.notify()` 在线轻量通知、AID/群路由和不离线存储边界 → [Notify 通知方案](sdk/Notify通知方案.md)
+- `client.notify()` 在线轻量通知、AID/群路由、跨域 federation 和不离线存储边界 → [Notify 通知方案](sdk/Notify通知方案.md)
 - 协议细节、子协议和消息格式 → [协议文档目录](protocol/)
-- agent.md 远程缓存、`remote_etag` / `local_etag`、消息信封 ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
-
-### 诊断与可观测性
-
+- agent.md 远程缓存、`remote_etag` / `local_etag`、消息信封 ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
+
+### Service Proxy 与服务暴露
+
+- AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、embedded registry、URL 路由、隧道协议和 Docker E2E 入口 → [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md)
+- Service Proxy `proxy.*` 控制面、proxy-server `register_services` 数据面注册、服务列表一致性和 wakeup 路由语义 → [Service Proxy RPC 手册](sdk/09-proxy-rpc-manual.md)、[服务协议](protocol/06-服务协议.md)
+- ACP Proxy 可借鉴点、GlobalRegistry/RSA 不照搬项、目录式 Web 边界 → [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md)
+- 不影响现有 Gateway、NameService、SDK 接口的 TDD 分阶段计划 → [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md)
+
+### 诊断与可观测性
+
 - RPC trace span、跨模块诊断字段、安全字段白名单 → [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md)
 - aun-console 消息通信服务端可观察总体面板、事实/推断边界 → [AUN 服务端消息通信诊断面板方案](design/AUN服务端消息通信诊断面板方案.md)
 - 服务端可观察的消息通信 P0 面板、过滤语义、数据来源 → [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md)
@@ -58,7 +67,7 @@
 
 - SDK E2EE API、会话管理、ProtectedHeaders → [SDK 文档索引](sdk/INDEX.md)
 - E2EE V2 1DH/per-AID wrap、bootstrap 能力声明、服务端 fanout → [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md)
-- 共享测试向量、transcript 回放、Python / TS / Go / C++ E2EE 互通 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- 共享测试向量、transcript 回放、Python / TS / Go E2EE 互通 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 
 ---
 
@@ -66,7 +75,7 @@
 
 ### aun测试运行指南
 
-记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
+记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript 四语言测试矩阵，Python / TypeScript / Go 跨语言容器 E2E 的 42 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及三语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、双域 federation 测试、Service Proxy 单域/双域 E2E 入口和数据保护规则。
 
 ### AUN SDK 重构修改清单
 
@@ -82,7 +91,7 @@
 
 ### 跨语言容器E2E测试方案
 
-定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
+定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go，浏览器 JavaScript 仍按宿主机 Playwright 运行。
 
 ### E2EE V2 简化为 1DH + Per-AID Wrap 方案
 
@@ -100,13 +109,21 @@
 
 定义 aun-console 消息通信页的 P0 服务端诊断面板。范围限定为 Gateway、Message/Group、Federation 和 Service Plane 可观察事实，不采集 SDK 本地状态。文档给出发送端、接收端、消息 ID、Group ID 和任意方向过滤语义，并定义服务端 Trace、投递路径、Pull/ACK/GAP、E2EE、Federation、Service Plane 六个子标签，其中服务端自主 Trace 是默认关闭的运行时开关，`message.ack` 需区分 RPC 与同名事件的设备字段语义。
 
+### AUN 反向代理服务方案与 TDD 实施计划
+
+定义 AUN Service Proxy / AUN 服务代理的整体方案：服务侧新增 `service_proxy` 模块，`service-proxy-server` 负责公网 HTTP/HTTPS 入口、WSS 隧道、在线连接索引和协议桥接；SDK 侧 `service-proxy-client` 负责 provider 侧 embedded registry、本地 endpoint 调用和服务摘要上报。方案明确去掉 ACP GlobalRegistry/RSA 同步，URL 以 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 为 canonical，`https://{user_name}.{issuer}/proxy/{svc_name}/...` 由 NameService 跳转；Web 服务推荐 host-root 模式，目录式 path-prefix 只做受限转发。文档还按 Phase 0 到 Phase 11 给出 TDD 实施步骤，记录 Phase 10 已新增宿主机进程内 7 类 HTTP/SSE/WS/NameService/Web/ACL/双域边界 E2E，以及单域和双域 Docker E2E 脚本入口；真实 Docker 执行仍需先满足模块启用、镜像包含新模块和 `/ws/client` AUN 身份 resolver 前置条件。
+
 ### 远程 agent.md 缓存与 ETag 透传方案
-
+
 定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案同时规定 `message.send` 响应向发送端透传 `to` 的 agent.md ETag，消息信封向接收端透传 `from` 的 agent.md ETag，并给出按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
 
 ### SDK 文档索引
 
-`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE、API 手册、错误处理、最佳实践、payload 和各类 RPC 手册。
+`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE、API 手册、错误处理、最佳实践、payload、Service Proxy 和各类 RPC 手册。
+
+### Service Proxy RPC 手册
+
+定义 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services` 的 Gateway 控制面语义，以及 proxy-server `register_services` 数据面隧道消息、服务列表与连接绑定、一致性约束和 wakeup 路由策略。
 
 ### SDK 查阅指南
 
@@ -114,4 +131,4 @@
 
 ### Notify 通知方案
 
-定义 `client.notify()` 的 JSON-RPC Notification 发送语义。方案规定 notify 只投递在线长连接设备，不做离线存储、不分配 seq、不进入 pull/ack；同时说明服务端通知、AID 在线转发、群在线转发的路由模型，以及和 `message.send` / `group.send` 可靠应用事件的分工。
+定义 `client.notify()` 的 JSON-RPC Notification 发送语义。方案规定 notify 只投递在线长连接设备，不做离线存储、不分配 seq、不进入 pull/ack；同时说明服务端通知、AID 在线转发、群在线转发、跨域 federation 转发的路由模型，以及和 `message.send` / `group.send` 可靠应用事件的分工。

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -8,18 +8,19 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ### Step 1：先读根级 Layer 1
 
-- `docs/INDEX.md` L7-26：根级文档地图。
+- `docs/INDEX.md` L7-28：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
 - 测试与 E2E：`docs/INDEX.md` L32-39。
-- SDK 使用与协议：`docs/INDEX.md` L41-47。
-- 诊断与可观测性：`docs/INDEX.md` L49-55。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L57-61。
+- SDK 使用与协议：`docs/INDEX.md` L43-49。
+- Service Proxy 与服务暴露：`docs/INDEX.md` L51-56。
+- 诊断与可观测性：`docs/INDEX.md` L58-64。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L66-70。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L65-117：重点文档摘要。
+- `docs/INDEX.md` L74-134：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -29,27 +30,32 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 | 场景 | 推荐读取 |
 | --- | --- |
-| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
+| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-43、L62-70 |
 | 本轮 SDK 重构修改清单 | `docs/AUN_SDK_重构修改清单.md` |
 | AUNClient 巨类拆分重构执行方案 | `docs/design/AUNClient拆分重构执行方案.md` L3-252、L253-698、L699-803 |
 | AUNClient 完全门面化与 Runtime 状态迁移细化方案 | `docs/design/AUNClient门面化与Runtime状态迁移细化方案.md` |
-| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L48-63 |
-| 单域 Docker 测试容器和命令 | `docs/aun测试运行指南.md` L113-533 |
-| 跨语言容器 E2E 执行方式 | `docs/aun测试运行指南.md` L146-263 |
-| 双域 federation 测试容器和命令 | `docs/aun测试运行指南.md` L534-714 |
-| 何时 rebuild / restart | `docs/aun测试运行指南.md` L715-762 |
-| 测试故障排查 | `docs/aun测试运行指南.md` L763-782 |
+| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L45-60 |
+| 单域 Docker 测试容器和命令 | `docs/aun测试运行指南.md` L105-463 |
+| 跨语言容器 E2E 执行方式 | `docs/aun测试运行指南.md` L139-250 |
+| 双域 federation 测试容器和命令 | `docs/aun测试运行指南.md` L464-630 |
+| 何时 rebuild / restart | `docs/aun测试运行指南.md` L631-675 |
+| 测试故障排查 | `docs/aun测试运行指南.md` L677-704 |
 | 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
 | E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
 | 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
 | 服务端消息通信 P0 诊断面板 | `docs/design/服务端消息通信诊断面板P0方案.md` L3-73 |
+| AUN Service Proxy 总体架构、参考项目与边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L3-127 |
+| AUN Service Proxy URL、注册、隧道协议和 Web 边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L129-384 |
+| AUN Service Proxy 服务列表注册、双注册和 wakeup 路由 | `docs/sdk/09-proxy-rpc-manual.md` L1-226、`docs/protocol/06-服务协议.md` L43-204 |
+| AUN Service Proxy 不影响现有接口的约束 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L385-422 |
+| AUN Service Proxy TDD 分阶段实施计划 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L424-906 |
 | 跨语言 Docker 拓扑 | `docs/design/跨语言容器E2E测试方案.md` L37-76 |
 | 共享测试向量、CLI transcript、单域/双域分层 | `docs/design/跨语言容器E2E测试方案.md` L78-147 |
 | test-runner 如何控制不同语言 client | `docs/design/跨语言容器E2E测试方案.md` L149-158 |
 | test-control HTTP API | `docs/design/跨语言容器E2E测试方案.md` L160-305 |
 | 客户端容器要求和 Compose 建议 | `docs/design/跨语言容器E2E测试方案.md` L307-411 |
 | test-runner 标准用例流程 | `docs/design/跨语言容器E2E测试方案.md` L413-440 |
-| Python / TypeScript / Go / C++ 跨 SDK 测试矩阵 | `docs/aun测试运行指南.md` L210-228 |
+| Python / TypeScript / Go 跨 SDK 测试矩阵 | `docs/aun测试运行指南.md` L200-218 |
 | 跨语言日志、trace、身份隔离、CLI 定位 | `docs/design/跨语言容器E2E测试方案.md` L514-576 |
 | 失败分类与落地阶段 | `docs/design/跨语言容器E2E测试方案.md` L579-625 |
 | 与现有测试环境的关系和验收标准 | `docs/design/跨语言容器E2E测试方案.md` L627-665 |
@@ -58,4 +64,4 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L187-268 |
 | agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L269-317 |
 | SDK API、RPC、E2EE 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
-| Notify 在线轻量通知方案 | `docs/sdk/Notify通知方案.md` |
+| Notify 在线轻量通知 / 跨域 federation 方案 | `docs/sdk/Notify通知方案.md` |

package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md

@@ -20,11 +20,12 @@
 | `meta.*` | 核心 | 健康检查、状态查询、受信根证书 | meta 服务 | WebSocket |
 | `storage.*` | 扩展 | 对象存储、大文件上传下载（详见 [11-Storage-子协议.md](11-Storage-子协议.md)） | storage 服务 | WebSocket + HTTP |
 | `group.*` | 扩展 | 群组管理、群消息、资源共享（详见 [10-Group-子协议.md](10-Group-子协议.md)） | group 服务 | WebSocket |
-| `mail.*` | 扩展 | 邮件服务 | mail 服务 | WebSocket |
-| `stream.*` | 扩展 | 实时流式传输（详见 [12-Stream-子协议.md](12-Stream-子协议.md)） | stream 服务 | WebSocket + HTTP SSE |
-| `search.*` | 扩展 | Agent 搜索与发现 | search 服务 | WebSocket |
-| `relay.*` | 扩展 | NAT 穿透中继（详见 [05-Relay-子协议.md](05-Relay-子协议.md)） | relay 服务 | WebSocket |
-| `peer.*` | 协议定义 | 点对点直连（详见 [04-Peer-子协议.md](04-Peer-子协议.md)） | 无对应服务 | WebSocket |
+| `mail.*` | 扩展 | 邮件服务 | mail 服务 | WebSocket |
+| `stream.*` | 扩展 | 实时流式传输（详见 [12-Stream-子协议.md](12-Stream-子协议.md)） | stream 服务 | WebSocket + HTTP SSE |
+| `proxy.*` | 扩展 | Service Proxy 服务列表控制面 | Gateway 本地处理 / service_proxy 查询 | WebSocket |
+| `search.*` | 扩展 | Agent 搜索与发现 | search 服务 | WebSocket |
+| `relay.*` | 扩展 | NAT 穿透中继（详见 [05-Relay-子协议.md](05-Relay-子协议.md)） | relay 服务 | WebSocket |
+| `peer.*` | 协议定义 | 点对点直连（详见 [04-Peer-子协议.md](04-Peer-子协议.md)） | 无对应服务 | WebSocket |
 | `task.*` | 协议定义 | Agent 协作与任务执行 | 无对应服务 | WebSocket |
 
 **控制面与数据面分离**：
@@ -35,11 +36,215 @@
 - 大文件、二进制附件、长时流式内容不应直接嵌入 `message.*` 的 `payload`，应先经 `storage.*` 存储，再由 `message.*` 传递对象引用
 - 实现应分别对 `message.*` 的消息体大小和 `storage.*` 的对象大小进行独立限制
 
-**应用层扩展服务**本身也是 AID 持有者，通过核心协议（`message.*`）与客户端通信。客户端可以选择使用或不使用这些扩展服务。
-
----
-
-### 6.2 点对点消息 `message.*`
+**应用层扩展服务**本身也是 AID 持有者，通过核心协议（`message.*`）与客户端通信。客户端可以选择使用或不使用这些扩展服务。
+
+---
+
+### 6.2 Service Proxy 服务列表控制面 `proxy.*`
+
+`proxy.*` 是 AUN Service Proxy 的控制面命名空间，用于 provider 通过 Gateway 长连接声明自己能够通过 Service Proxy 暴露哪些服务。它不承载 HTTP/WS 数据面流量；真实访问数据面由 `service_proxy` 模块的独立 proxy-server 隧道处理。
+
+#### 控制面与数据面
+
+- **Gateway 控制面**：provider 的 AUN 长连接调用 `proxy.register_services` / `proxy.unregister_services` / `proxy.list_services`。Gateway 记录每个 provider 长连接声明的服务摘要，供 `service_proxy` 模块判断 provider 是否在线、是否声明目标服务。
+- **proxy-server 数据面**：service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须再次发送隧道消息 `register_services`。proxy-server 只向已在本地数据面连接并注册目标服务的 provider 隧道转发请求。
+- **服务列表生命周期**：Gateway 控制面服务列表绑定 Gateway 长连接；proxy-server 数据面服务列表绑定 proxy-server 隧道连接。连接断开后对应服务列表必须清理。
+- **一致性要求**：同一 provider AID 的多个实例可以同时在线，但它们注册的服务列表必须一致。这里的一致性以清洗后的服务摘要为准，包括 `service_name`、`service_type`、`visibility` 和非敏感 `metadata`。
+- **粘性路由**：同一 provider AID 的多个实例若提供相同服务，proxy-server 必须对同一访问亲和键保持稳定路由；亲和键可由 requester AID、客户端 IP、provider AID 和服务名组合得到。
+
+#### 服务摘要
+
+服务摘要不得包含内网 endpoint、token、cookie、私钥、证书等敏感字段。实现必须在 Gateway 控制面和 proxy-server 数据面分别清洗摘要，不能依赖共享代码。
+
+```json
+{
+  "service_name": "fileshare",
+  "service_type": "http",
+  "visibility": "public",
+  "metadata": {"label": "Files"}
+}
+```
+
+| 字段 | 必需 | 说明 |
+|------|:----:|------|
+| `service_name` | ✅ | 服务名，只允许小写字母、数字、`_`、`-`；不得使用 `api`、`health`、`proxy`、`ws` 等保留名 |
+| `service_type` | ❌ | 服务类型，默认 `http`；可用于提示 `http` / `sse` / `websocket` / `mcp` / `file` 等 |
+| `visibility` | ❌ | 访问策略，默认 `private`；当前实现支持 `public`、`private`、`aun-auth` |
+| `metadata` | ❌ | 非敏感元数据；实现必须过滤 endpoint、url、token、authorization、cookie、secret、private_key、cert 等敏感键 |
+
+#### `proxy.register_services`
+
+注册当前 Gateway 长连接提供的 Service Proxy 服务列表。服务端必须以连接认证得到的 AID 作为 provider AID；客户端传入的 `provider_aid` 只能作为兼容字段或诊断字段，不能覆盖认证身份。
+
+**请求**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "reg-1",
+  "method": "proxy.register_services",
+  "params": {
+    "provider_aid": "alice.agentid.pub",
+    "services": [{
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }]
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "reg-1",
+  "result": {
+    "ok": true,
+    "provider_aid": "alice.agentid.pub",
+    "connection_id": "conn-1",
+    "count": 1,
+    "services": [{
+      "service_name": "fileshare",
+      "service_type": "http",
+      "visibility": "public",
+      "metadata": {"label": "Files"}
+    }]
+  }
+}
+```
+
+#### `proxy.unregister_services`
+
+注销当前 Gateway 长连接上的部分或全部 Service Proxy 服务。省略 `service_names` 时注销该连接全部服务。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "unreg-1",
+  "method": "proxy.unregister_services",
+  "params": {"service_names": ["fileshare"]}
+}
+```
+
+响应包含 `removed` 和剩余 `count`。如果同一 provider AID 还有其他连接，部分注销导致服务列表不一致时，服务端应拒绝该操作。
+
+#### `proxy.list_services`
+
+列出当前 Gateway 长连接已注册的服务摘要。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "list-1",
+  "method": "proxy.list_services",
+  "params": {}
+}
+```
+
+#### 内部查询 `gateway.query_proxy_services`
+
+`gateway.query_proxy_services` 是 service_proxy 模块调用 Gateway 的内部模块 RPC，不是普通客户端公开方法。调用方必须是 `service_proxy` 模块。
+
+请求参数：
+
+| 参数 | 必需 | 说明 |
+|------|:----:|------|
+| `provider_aid` | ✅ | 被访问 provider AID |
+| `service_name` | ❌ | 目标服务名；为空时只查询 provider 在线和服务列表概览 |
+
+响应字段：
+
+| 字段 | 说明 |
+|------|------|
+| `provider_aid_exists` | Gateway 通过 CA 证书查询确认 provider AID 是否存在；查询失败时为 `null` |
+| `provider_online` | provider 是否存在 Gateway 长连接 |
+| `has_registered_services` | 在线连接中是否已有 proxy 服务列表注册 |
+| `service_registered` | 指定 `service_name` 是否已由在线 provider 注册 |
+| `service_names` | 当前 provider 声明的服务名集合 |
+| `connections` | 已注册服务列表的 Gateway 长连接摘要 |
+| `matched_connections` | 注册了指定服务的 Gateway 长连接摘要 |
+
+#### proxy-server well-known 发现
+
+proxy-client 不得由应用外部传入、配置或硬拼 proxy-server 地址。连接 proxy-server 前必须先执行发现：
+
+1. 优先请求 `https://{provider_aid}/.well-known/aun-proxy`。
+2. 请求失败时回退 `https://proxy.{issuer}/.well-known/aun-proxy`。
+3. 发现结果可缓存到 provider AID 本地 SQLite metadata，缓存 TTL 为 1 小时。
+
+响应示例：
+
+```json
+{
+  "issuer": "agentid.pub",
+  "provider_aid": "alice.agentid.pub",
+  "proxy_host": "proxy.agentid.pub",
+  "https_url": "https://proxy.agentid.pub:19890",
+  "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
+  "proxy_servers": [{
+    "https_url": "https://proxy.agentid.pub:19890",
+    "ws_url": "wss://proxy.agentid.pub:19890/ws/client",
+    "priority": 1
+  }]
+}
+```
+
+proxy-client 连接 `ws_url` 时必须带 `Authorization: Bearer <access_token>`。`access_token` 优先复用本地 cached token；缓存缺失或过期时，必须通过 AUNClient 向 Gateway 完成两步登录取得新 token。
+
+#### proxy-server 隧道注册
+
+service-proxy-client 连接 `service_proxy` 模块的 `/ws/client` 后，认证成功后必须发送：
+
+```json
+{
+  "type": "register_services",
+  "request_id": "reg-1",
+  "services": [{
+    "service_name": "fileshare",
+    "service_type": "http",
+    "visibility": "public",
+    "metadata": {"label": "Files"}
+  }]
+}
+```
+
+成功响应：
+
+```json
+{"type": "register_services_ack", "request_id": "reg-1", "ok": true, "count": 1}
+```
+
+若同一 provider AID 的另一条 proxy-server 隧道已注册不同服务列表，proxy-server 必须返回：
+
+```json
+{
+  "type": "service_proxy_error",
+  "request_id": "reg-1",
+  "error": {
+    "code": "proxy_services_inconsistent",
+    "message": "provider service list is inconsistent with existing connections"
+  }
+}
+```
+
+#### 路由与 wakeup 策略
+
+proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等价路由时，必须按以下顺序决策：
+
+1. 本地 proxy-server 连接索引中存在 `(provider_aid, service_name)`：直接选择对应数据面连接；多连接时按亲和键稳定选择。
+2. provider 已连接本 proxy-server 且已注册服务列表，但没有目标服务：返回 `service_not_registered`，不得 wakeup。
+3. provider 未连接本 proxy-server 时，查询 Gateway 控制面：
+   - `provider_aid_exists=false`：返回 `provider_aid_not_found`。
+   - `provider_aid_exists=null`：返回 `provider_aid_check_failed`。
+   - `provider_online=false`：返回 `provider_offline`。
+   - `provider_online=true` 且 `service_registered=false`：返回 `service_not_registered`，不得 wakeup。
+   - `provider_online=true` 且 `service_registered=true`：通过 Gateway 向注册了目标服务的 provider 长连接发送 `app.service_proxy.wakeup`。
+4. wakeup 已投递但本 proxy-server 仍未等到目标服务注册时，返回 `provider_wakeup_timeout`。
+
+---
+
+### 6.3 点对点消息 `message.*`
 
 **设计原则**：
 
@@ -254,7 +459,7 @@
 }
 ```
 
-**说明**：`ack_seq` 仅增不减。现代连接按 `(aid, device_id, slot_id)` 维护 ack 游标；未携带 `device_id` 的 legacy 连接继续走 per-AID 兼容路径。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。`message.ack` 只更新接收方消费游标，服务端 **MUST NOT** 向发送方或其他客户端发布 ack 通知事件。
+**说明**：`ack_seq` 仅增不减。现代连接按 `(aid, device_id, slot_id)` 维护 ack 游标；未携带 `device_id` 的 legacy 连接继续走 per-AID 兼容路径。显式传入的 `device_id` / `slot_id` 若与连接认证上下文不一致，服务端 **MUST** 拒绝请求。
 
 #### `message.recall`
 
@@ -360,6 +565,29 @@
 }
 ```
 
+#### `event/message.ack`
+
+消息确认事件（通知发送方消息已被接收方确认）。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/message.ack",
+  "params": {
+    "to": "bob.aid.pub",
+    "device_id": "device-001",
+    "slot_id": "slot-a",
+    "ack_seq": 43,
+    "timestamp": 1709712003
+  }
+}
+```
+
+- `to`：确认方 AID
+- `device_id`：触发 ack 的设备标识；legacy 客户端为空字符串
+- `slot_id`：触发 ack 的消费槽位；空字符串表示设备单实例或 legacy 路径
+- `ack_seq`：确认到的序列号（含该 seq 及之前的所有消息）
+
 #### `event/message.recalled`
 
 消息被撤回事件（通知接收方消息已被发送方撤回）。
@@ -384,7 +612,7 @@
 
 ---
 
-### 6.3 元协议 `meta.*`
+### 6.4 元协议 `meta.*`
 
 #### `meta.ping`
 
@@ -520,7 +748,7 @@ Issuer 必须通过 `https://ct.{issuer}` 提供证书透明日志（CT）的公
 
 ---
 
-### 6.4 搜索与发现 `search.*`
+### 6.5 搜索与发现 `search.*`
 
 `search.*` 定义 AUN 中 Agent 的公开发现机制，围绕 `agent.md` 工作：
 
@@ -768,7 +996,7 @@ tags:
 
 ---
 
-### 6.5 Agent 协作与任务 `task.*`
+### 6.6 Agent 协作与任务 `task.*`
 
 `task.*` 用于表达 Agent 之间的长生命周期协作任务，参考 A2A 的 task 机制，对齐 AUN 特点：
 
@@ -1059,7 +1287,7 @@ event/task.delegated      # 已创建子任务
 
 ---
 
-### 6.6 端到端加密（E2EE）摘要
+### 6.7 端到端加密（E2EE）摘要
 
 > 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
 
@@ -1089,7 +1317,7 @@ event/task.delegated      # 已创建子任务
 
 ---
 
-### 6.7 跨域消息路由
+### 6.8 跨域消息路由
 
 **当前实现事实**：