@agentunion/fastaun 0.5.32 → 0.5.34

package/_packed_docs/sdk/09-custody-api-manual.md

@@ -20,7 +20,7 @@ SDK 使用约束：
 
 - `custody_url` 不作为 `AUNClient` 构造配置参数传入。
 - Python SDK 不在 `AUNClient` 上挂载 custody namespace；需要时使用独立 custody 辅助客户端或直接按本手册 HTTP API 调用。
-- TS / JS / Go 仍保留历史 custody namespace 兼容层；新代码应避免把 custody 当作 AUNClient 核心会话能力。
+- 各 SDK 均不把 custody 作为 AUNClient 核心会话能力；如需调用，请使用独立 custody 辅助客户端（若 SDK 提供）或直接按本手册 HTTP API 调用。
 - 可通过 `https://{aid}/.well-known/aun-custody` 自动发现官方托管服务地址，并缓存发现结果。
 
 ## 手机号验证码备份/恢复时序
@@ -96,8 +96,8 @@ SDK 方法：
 | 语言 | 发起复制 | 上传复制材料 | 领取复制材料 |
 |------|----------|--------------|--------------|
 | Python | 独立 custody 辅助客户端或 HTTP API | 独立 custody 辅助客户端或 HTTP API | 独立 custody 辅助客户端或 HTTP API |
-| JS/TS | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API |
-| Go | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API | 历史 custody namespace 兼容层或 HTTP API |
+| JS/TS | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API |
+| Go | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API | 独立 custody 辅助客户端（若 SDK 提供）或 HTTP API |
 
 复制请求：
 

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

@@ -129,6 +129,8 @@
 | [group.fs.lstat](#groupfslstat) | 查看链接本身 |
 | [group.fs.df](#groupfsdf) | 查看用量 |
 | [group.fs.create_download_ticket](#groupfscreate_download_ticket) | 创建下载票据 |
+| [group.fs.set_visibility](#groupfsset_visibility) | 设置节点可见性 |
+| [group.fs.namespace_ready](#groupfsnamespace_ready) | 初始化群文件命名空间 |
 | [group.fs.set_acl](#groupfsset_acl) | 授予群自有区角色写 ACL |
 | [group.fs.remove_acl](#groupfsremove_acl) | 撤销群自有区角色写 ACL |
 | [group.fs.get_acl](#groupfsget_acl) | 查询群自有区角色 ACL |
@@ -1444,6 +1446,27 @@ result = await client.call("group.thought.get", {
 | `limit` | integer | 否 | 50 | Python V2 Forward 最大 200；其余模式保留原限制，`pull_max_limit` 配置可进一步收紧 |
 | `device_id` | string | 否 | — | 设备 ID（多设备模式） |
 
+#### 存储范围与字节分页
+
+群消息 Pull（含底层 `group.v2.pull`）、`group.history` 及 `group.pull_events` 支持可选字节上限；Forward Pull 通过存储范围选择持久或临时数据：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `storage_scope` | string | `all` | `all` 保持既有来源；`persistent` 只读取持久消息/事件；`volatile` 返回临时来源专用页 |
+| `max_page_bytes` | integer | 原服务配置 | 显式范围 `1024..786432`，按单次 RPC `result` 的 JSON 编码字节截页，与条数上限同时执行 |
+
+`persistent` 不读取 volatile mailbox；`volatile` 沿用原消息类别、设备、slot 与 TTL 过滤，没有临时数据时返回空页。临时页不返回持久消息/事件 coverage、head 或 server ACK，也不接受 `ack_up_to_seq`、`before_seq` 或 `window_mode`。群消息与群事件仍使用独立游标，History 保持只读。
+
+首条记录超过预算时，`error.data.code="OVERSIZED_MESSAGE"`，并附带 `required_page_bytes`、`max_page_bytes` 及可用的记录标识；该失败页不推进游标或 ACK。后台 SDK 通过 `sync.error` 报告并停止该流自动续页，其它流继续；显式前台调用返回原错误。
+
+弹性历史请求使用 `persistent`，主辅合计初始编码预留 1 MiB，本地按页上限的 8 倍预留至消费结束、初始总额 8 MiB；实时临时页独立走主连接。群成员可见性、入群下界及 ACK 提交规则沿用原契约。
+
+SDK 遵从 `max_aux_channels` 支持 0..N 条辅助连接（当前协议测试到 2）；本轮 Gateway 对同一 AID＋设备跨 slot 最多授权 1 条，开关关闭或压力回收时为 0。连接数量不是 Pull 总并发上限：同 namespace 串行，不同 namespace 可在策略和预算允许时并行。
+
+普通持久 Forward 带 `max_page_bytes` 时，`group.pull`、`group.v2.pull`、`group.pull_events` 可返回 `pending_count_lower_bound`（0—100）；Group 当前 `all` 也只含持久来源。它只取本次既有读取、可见且去重候选中最终未返回的数量，包含字节截页移出的行，不新增查询、COUNT、扫描或读取 limit。缺省或 0 都不证明追平；续页、游标与 ACK 继续遵守原分页契约。force、Tail、History、control、sdk_control、volatile 不返回此提示。`limit+1` 通常只能证明还有 1 条，V2 原读取可能只能证明 0，不能保证识别所有单流大积压。
+
+普通短连接和 `history_sync` 补拉辅助连接均不触发或接收群 unread hint；群提示由主长连接接收。短连接显式调用 Pull 不受影响。
+
 **响应**：
 
 ```json
@@ -1581,7 +1604,7 @@ SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布
 - `group.fs.set_acl` / `group.fs.remove_acl` / `group.fs.get_acl` / `group.fs.list_acl` 只能由当前 group `owner/admin` 调用。当前支持 `grantee_aid="role:admin"` 与 `grantee_aid="role:member"`；`role:member` 只能授予具体业务目录的 `rw` 权限，不能授予根目录或 `.group/`，也不能获得删除、移动、重命名权限。成员升降级、退群、踢出不会联动授权或撤销目录 ACL。
 - `memberdata/{member_ref}` 写入默认只允许该成员本人；SDK 只传 group path，不拼接真实 storage 路径。
 - 上传控制面会透传 `parents` 到 storage：默认 `parents=true` 时可递归创建父目录，显式 `parents=false` 时父目录必须已存在。
-- JavaScript 浏览器版 `cp(string, group)` 默认把 string 当文本内容上传；Node 本地路径需显式传 `sourceType: "path"`、`localPath: true` 或使用 `local:` 前缀。Python、TypeScript 和 Go 默认把 string 当本地路径。
+- JavaScript SDK 的 `cp(string, group)` 默认把 string 当 UTF-8 文本内容上传；本地路径需显式传 `sourceType: "path"`、`localPath: true` 或使用 `local:` 前缀。Python、TypeScript 和 Go 默认把 string 当本地路径。
 
 ### SDK 默认读缓存
 
@@ -1591,7 +1614,7 @@ SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布
 
 ### group.fs.ls
 
-列出目录。参数：`path` 必填；可选 `page`、`size`、`marker`、`long`、`recursive`。响应返回 group view `items`，节点 `path` 仍为 group path。
+列出目录。参数：`path` 必填；可选 `page`、`size`（也接受 `limit` 作为 `size` 别名）。当前 Group 服务将 `page` 规范化为至少 1、`size` 限制在 1..1000，并向 Storage 传递这两个分页参数；`marker`、`long`、`recursive` 不属于当前 RPC 的生效参数。响应返回 group view `items`，节点 `path` 仍为 group path。
 
 ### group.fs.find
 
@@ -1663,19 +1686,27 @@ Group FS 的读缓存保存符合策略的已验证正文，不把下载票据
 
 ### group.fs.create_upload_session
 
-创建上传会话。参数同 `check_upload`。响应透传 Storage session 字段并增加 Group FS 路径视图，包含 `upload_url`、`content_type`、`size_bytes` 等；当前 Storage 服务不返回 `session_id` 或 `headers`。四个 SDK 的 Group FS 门面会按实际字节识别 MIME，并在 session、HTTP PUT 与 complete 中保持 `Content-Type` 一致；若 session 返回 headers，SDK 保留其它 header 并替换其中的 Content-Type，避免 OSS 签名不一致导致 403。
+创建上传会话。参数同 `check_upload`。响应透传 Storage session 字段并增加 Group FS 路径视图，通常包含 `upload_url`、可选 `session_id`、可选 `headers`、`content_type`、`size_bytes` 等。四个 SDK 的 Group FS 门面会按实际字节识别 MIME，并在 session、HTTP PUT 与 complete 中保持 `Content-Type` 一致；若 session 返回 headers，SDK 保留其它 header 并替换其中的 Content-Type，避免 OSS 签名不一致导致 403。
 
 ### group.fs.complete_upload
 
 完成上传。参数包含 `path`、`sha256`、`size_bytes`、可选 `session_id`、`skip_blob`、`metadata`、`expected_version`。响应为 group view NodeView。
 
+### group.fs.set_visibility
+
+设置群自有区节点可见性。参数：`path` 必填；`visibility` 必填，为 `public` 或 `private`（也可用兼容布尔参数 `is_public`）；可选 `expected_version`。`memberdata` 及其子路径的可见性由成员自挂载流程管理，不能通过此 RPC 修改。成功响应为 NodeView，并包含最终 `visibility`。
+
+### group.fs.namespace_ready
+
+初始化或检查群文件命名空间。参数：`group_id` 必填；可选 `folder_ids` 对已有 Storage 文件夹 ID 做绑定。调用者须为群身份、owner 或 admin。成功响应包含 `namespace_ready=true`、`baseline_paths`、`items`、`baseline_role_acls_synced`、`own_area_ready` 和 `memberdata_ready`；命名群的基线目录为 `.group`、`announce`、`public`、`archive`、`memberdata`，普通群至少返回 `memberdata`。该调用会触发缺失基线目录/ACL 的 best-effort 初始化。
+
 ### group.fs.mount
 
-挂载成员数据区。参数：`path` 必填；可选 `readonly`、`require_approval`、`source_bucket`、`expires_at`、`volume_id`。
+挂载成员数据区。`path` 必须是 `/memberdata/{member_ref}`（可使用带 group AID 的 group path）；可选 `readonly`（默认 `true`）、`require_approval`（默认 `false`）、`source_bucket`、`expires_at`、`volume_id`。未提供 `volume_id` 时从成员 AID 和其群数据根目录挂载；提供 `volume_id` 时挂载指定 volume。
 
 ### group.fs.umount
 
-卸载成员数据区。参数：`path` 必填。对成员数据区卸载不删除成员源数据。
+卸载成员数据区。`path` 必须是 `/memberdata/{member_ref}`（可使用带 group AID 的 group path）；对成员数据区卸载不删除成员源数据。
 
 ## 在线状态
 
@@ -1716,7 +1747,9 @@ Group FS 的读缓存保存符合策略的已验证正文，不把下载票据
 
 ### group.pull_events
 
-增量拉取群事件，支持多设备独立游标。SDK 将其作为后台 Pull 放入当前 `AUNClient` 的客户端级 Pull Gate；该 Gate 与 P2P Message、Group Message Pull 共享，同一 namespace 单飞，客户端最多 4 个不同 namespace 并行。Group Event 使用 `group_event:{群标识}`，与同群消息 namespace 独立；相同完整请求 key 折叠并共享结果，可运行的不同 key 按后台 FIFO 调度并让前台请求优先。Group Event 使用独立的 Forward Cursor，不修改消息 A/T/H；不同 `AUNClient` 实例之间不共享 Gate。应用层无需自行实现并发控制。
+`storage_scope`、`max_page_bytes` 及超页错误沿用[群 Pull 的存储与字节分页规则](#存储范围与字节分页)。
+
+增量拉取群事件，支持多设备独立游标；`pending_count_lower_bound` 沿用上述普通持久字节限页规则。SDK 将其作为后台 Pull 放入当前 `AUNClient` 的客户端级 Pull Gate；该 Gate 与 P2P Message、Group Message Pull 共享，同一 namespace 单飞，客户端最多 4 个不同 namespace 并行。Group Event 使用 `group_event:{群标识}`，与同群消息 namespace 独立；相同完整请求 key 折叠并共享结果，可运行的不同 key 按后台 FIFO 调度并让前台请求优先。Group Event 使用独立的 Forward Cursor，不修改消息 A/T/H；不同 `AUNClient` 实例之间不共享 Gate。应用层无需自行实现并发控制。
 
 **参数**：
 
@@ -2006,6 +2039,20 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x
 | `suspended` | 群组暂停 |
 | `resumed` | 群组恢复 |
 | `dissolved` | 群组解散 |
+| `fs_set_visibility` | 文件节点可见性变更 |
+| `fs_set_acl` | 文件节点 ACL 授予 |
+| `fs_remove_acl` | 文件节点 ACL 撤销 |
+| `fs_mkdir` | 创建目录 |
+| `fs_rm` | 删除节点 |
+| `fs_cp` | 远程复制节点 |
+| `fs_mv` | 远程移动节点 |
+| `fs_upload_completed` | 上传完成 |
+| `fs_mount` | 挂载成员数据区 |
+| `fs_umount` | 卸载成员数据区 |
+| `fs_namespace_ready` | 文件命名空间初始化完成 |
+| `fs_confirmed` | 文件 ACL 操作确认 |
+| `fs_mount_confirmed` | 挂载操作确认 |
+| `fs_mount_unavailable` | 挂载 volume 不可用 |
 
 **订阅**：
 

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

@@ -406,6 +406,25 @@ result = await client.call("message.thought.get", {
 
 新 SDK 的 peer Pull/Tail/History 单页默认及最大 200；旧 SDK 的 global 请求保留原默认值和限制。连接上线提示及重连恢复触发 pending 目录查询。后台同步的 `max_pages` 是工作片预算，达到 100 页仍有剩余时必须继续编排，不能将其当作同步终点。
 
+### 存储范围与字节分页
+
+`message.pull`／底层 `message.v2.pull` 增加两个可选参数；旧请求不传时保留原行为：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `storage_scope` | string | `all` | `all` 合并原有来源；`persistent` 只读持久消息；`volatile` 只读当前设备/slot 的内存收件箱 |
+| `max_page_bytes` | integer | 原服务配置 | 显式范围 `1024..786432`，按单次 RPC `result` 的 JSON 编码字节截页；可比 `limit` 更早结束 |
+
+`persistent` 不读取 volatile mailbox。`volatile` 返回 `storage_scope`、`messages`、volatile cursor 与 `volatile_has_more` 等临时页信息，不返回持久 coverage/head/server ACK，不接受 `ack_up_to_seq`、Tail 或 History 条件；SDK 仅交付临时消息并更新独立 volatile cursor。`message.history` 保持只读持久消息，可使用相同字节上限。
+
+首条单消息仍超过预算时返回结构化错误，`error.data.code="OVERSIZED_MESSAGE"`，附带 `required_page_bytes`、`max_page_bytes` 及可用的消息标识。该页不成功，也不越过未返回消息推进游标。后台 SDK 发布 `sync.error`（`namespace`、`method`、`code`、`error`）并停止该流自动续页，其它流继续；显式前台调用返回原 RPC 错误。
+
+弹性历史补拉的初始页上限为 256 KiB，主辅共享编码预留 1 MiB、本地放大预留 8 MiB；历史 `persistent` 请求遵守 Gateway 策略，实时 `volatile` Pull 独立走主连接。设备、slot、TTL 和分类路由继续使用原有规则。
+
+SDK 遵从 `max_aux_channels` 支持 0..N 条辅助连接（当前协议测试到 2）；本轮 Gateway 对同一 AID＋设备跨 slot 最多授权 1 条，开关关闭或压力回收时为 0。连接数量不是 Pull 总并发上限：同 namespace 串行，不同 namespace 可在策略和预算允许时并行。
+
+带 `max_page_bytes` 的普通 `persistent` Forward 响应可含 `pending_count_lower_bound`（1—100）：只用本次既有读取、去重及可见性过滤后最终未返回的候选数，字节截页移出的行计入下界，不增加查询或读取 limit。未能证明正下界时省略；缺省不表示追平。该字段仅供 SDK 判断明显积压，续页/完成仍遵守原分页证明；force、Tail、History、control、sdk_control、volatile 和混合来源不返回。`limit+1` 常只能证明还有 1 条，不能据此声称所有单流大积压均能识别。
+
 ### 响应
 
 以下基础消息字段沿用原格式；下表扫描证明与页内计数描述服务端单次 RPC 的原始页。SDK 自动续页后可能合并 `messages`，即使保留某一页的 proof/count，也只能解释该原始页，不能用于验证或计数整个合并列表。多 peer 聚合外层返回 `peers` / `messages` / `partial`，保留逐 peer 进度，不提供全体 peer 共用的 proof、可提交游标或精确总计数。
@@ -441,6 +460,7 @@ result = await client.call("message.thought.get", {
 | `count` | integer | 本次返回的消息数 |
 | `latest_seq` | integer | 返回的最大 seq |
 | `has_more` | boolean | 服务端 Forward 响应中仍有可见持久消息未返回；通过 `limit + 1` 探测及响应截页确定，不由 `unread_count` 或恰好满页推断 |
+| `pending_count_lower_bound` | integer | 可选，普通持久字节限页 Forward 的剩余候选数下界，上限 100；用于辅助连接门槛，不参与游标、ACK 或完成判断 |
 | `latest_volatile_cursor` | string\|null | 本页最后一个 volatile 游标；不影响 `latest_seq` |
 | `volatile_has_more` | boolean | 是否仍有未返回的 volatile 消息；SDK 在 volatile cursor 前进时据此继续分页 |
 | `volatile_earliest_cursor` | string\|null | 当前 boot epoch 内仍可读取的最早 volatile 游标 |
@@ -689,6 +709,8 @@ result = await client.call("message.ack", {"sender_aid": "alice.agentid.pub", "s
 
 收到新消息时推送。
 
+普通短连接和 `history_sync` 补拉辅助连接均不触发或接收 unread hint；消息提示由主长连接接收。短连接显式调用 Pull 不受影响。
+
 **实时推送优化**（0.5.6+）：当客户端在 `auth.connect` 时声明 `inline_realtime_payload_v1: true` 能力后，Gateway 会在事件中直接内联完整的消息载荷（`payload`、`envelope` 等），无需额外调用 `message.pull`。SDK 自动声明此能力，应用层无需关注。对于离线消息和历史消息，仍需通过 `message.pull` 拉取。
 
 ### Payload

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

@@ -12,7 +12,7 @@
 
 ## meta.ping
 
-心跳检测。SDK Core 自动调用以保持连接活性，也可手动调用验证连接是否正常。
+诊断连接并校验服务端时间。RPC `meta.ping` 不再承担 WebSocket 连接保活；连接保活由 WebSocket 控制帧完成，也可手动调用本方法验证连接是否正常。
 
 ### 参数
 
@@ -26,6 +26,7 @@
 |------|------|------|
 | `pong` | boolean | 固定为 `true` |
 | `timestamp` | integer | 服务端当前 Unix 时间戳（秒） |
+| `heartbeat_interval` | integer | 兼容字段，当前为 `0`；不表示 RPC 保活间隔 |
 
 ### 示例
 

package/_packed_docs/sdk/09-payload-reference.md

@@ -44,6 +44,7 @@
 | `from` / `sender_aid` | 服务端生成的消息信封 | 发送方身份 |
 | `message_id` / `seq` / `timestamp` / `created_at` | 服务端生成或发送参数 | 当前消息 ID、序号和服务端时间 |
 | `encrypted` / `delivery_mode` | 发送参数或连接上下文 | 加密和 P2P 投递语义 |
+| `need_render` | 消息信封 | 是否需要在接收端展示；默认 `true`，不属于 `payload`，不进入 E2EE AAD 或保护头 |
 | `mention_mode` | 群消息信封和 SDK 注入的群消息 payload | 群消息应用层提及过滤模式标签：`disabled` / `mention-only`；由群设置决定，不作为 `group.send` 单次入参。SDK 从服务端消息元数据复制到对象 payload |
 | `type` / `message_type` | 发送参数或消息信封 | 信封/封装类型，如 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` |
 | `dispatch` / `duty_state` / `message_dispatch` | `group.send` 响应和群消息事件 | 群消息运行时分发状态和值班分发结果 |
@@ -163,7 +164,7 @@
   "duration_ms": 8200,
   "transcript": "我稍后处理这个问题",
   "attachments": [{
-    "url": "aun://storage/default/voice/msg-1.opus",
+    "url": "https://alice.agentid.pub/voice/msg-1.opus",
     "filename": "msg-1.opus",
     "content_type": "audio/ogg"
   }]
@@ -188,7 +189,7 @@
   "width": 1280,
   "height": 720,
   "attachments": [{
-    "url": "aun://storage/default/images/flow.png",
+    "url": "https://alice.agentid.pub/images/flow.png",
     "filename": "flow.png",
     "content_type": "image/png"
   }]
@@ -211,11 +212,11 @@
   "text": "演示录屏",
   "duration_ms": 30500,
   "thumbnail": {
-    "url": "aun://storage/default/videos/demo-cover.jpg",
+    "url": "https://alice.agentid.pub/videos/demo-cover.jpg",
     "content_type": "image/jpeg"
   },
   "attachments": [{
-    "url": "aun://storage/default/videos/demo.mp4",
+    "url": "https://alice.agentid.pub/videos/demo.mp4",
     "filename": "demo.mp4",
     "content_type": "video/mp4"
   }]
@@ -235,7 +236,7 @@
   "type": "file",
   "text": "请查收附件",
   "attachments": [{
-    "url": "aun://storage/default/docs/report.pdf",
+    "url": "https://alice.agentid.pub/docs/report.pdf",
     "filename": "report.pdf",
     "content_type": "application/pdf",
     "size_bytes": 245678,
@@ -283,7 +284,7 @@
   "title": "AUN 设计说明",
   "description": "消息、群组和 E2EE 的设计摘要",
   "thumbnail": {
-    "url": "aun://storage/default/previews/aun-design.png",
+    "url": "https://alice.agentid.pub/previews/aun-design.png",
     "content_type": "image/png"
   }
 }
@@ -682,7 +683,7 @@ Agent 场景中，长时间运行的任务（代码生成、文件处理、多
 | `sha256` | string | 否 | 内容哈希，用于完整性校验 |
 | `thumbnail` | object | 否 | 缩略图引用，结构同附件引用 |
 
-AUN Storage 的 `url` 是长期对象引用，不是最终文件下载地址。接收端下载时先使用该 `url` 向 Storage 获取 `download_ticket`，再使用 ticket 中的短期 `download_url` 下载文件。`owner_aid`、`bucket`、`object_key` 可作为可选对象标识补充，便于没有 `url` 解析能力的客户端或服务端工具定位对象。
+AUN Storage 的 `url` 是长期对象引用，不是最终文件下载地址。接收端使用 `owner_aid`、`bucket`、`object_key`（或从 AID 风格的 `url` 解析这些字段）调用 `storage.create_download_ticket`，再使用票据返回的短期 `url` / `download_url` 下载文件。`logical_url` 仅用于服务端返回的直达对象引用；票据、短期 URL 和授权 token 不应长期写入消息正文或附件索引。
 
 ```json
 {
@@ -692,7 +693,7 @@ AUN Storage 的 `url` 是长期对象引用，不是最终文件下载地址。
     "owner_aid": "alice.agentid.pub",
     "bucket": "default",
     "object_key": "docs/report.pdf",
-    "url": "https://storage.agentid.pub/objects/default/docs/report.pdf",
+    "url": "https://alice.agentid.pub/docs/report.pdf",
     "filename": "report.pdf",
     "content_type": "application/pdf",
     "size_bytes": 245678,

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

@@ -38,12 +38,12 @@ Service Proxy 有两层注册，二者都必须存在：
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `service_name` | string | 是 | 服务名，建议使用 `[a-z0-9_-]+` |
+| `service_name` | string | 是 | 服务名，必须匹配 `[a-z0-9_-]+`，且不能使用 `api`、`health`、`metrics`、`status`、`proxy`、`admin`、`ws`、`wss`、`static` 等保留名 |
 | `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 注册只发送摘要。
+四端 `ServiceProxyClient` 会保存本地 endpoint，但服务摘要、Gateway 注册和 proxy-server 注册只发送摘要。
 
 ---
 
@@ -111,7 +111,7 @@ result = await client.call("proxy.register_services", {
 | `provider_aid` | string | 认证后的 provider AID |
 | `connection_id` | string | Gateway 连接 ID |
 | `removed` | array | 实际移除的服务名 |
-| `count` | integer | 剩余服务数量；全部注销时可省略 |
+| `count` | integer | 剩余服务数量；全部注销时为 `0` |
 
 ### 示例
 
@@ -182,32 +182,36 @@ proxy-client 连接 proxy-server `/ws/client` 并收到 `service_proxy_auth_resp
   "request_id": "register-services",
   "error": {
     "code": "proxy_services_inconsistent",
-    "message": "provider service list is inconsistent with existing connections"
+    "message": "provider connections must register identical services"
   }
 }
 ```
 
 ---
 
-## Python ServiceProxyClient
+## 四端 ServiceProxyClient
 
-Python SDK 的 `ServiceProxyClient` 已封装双注册流程：
+Python、Go、Node.js TypeScript 和 Browser SDK 均公开 `ServiceProxyClient`，封装服务注册、发现、双注册及 persistent / on-demand 重连流程。Python 使用 `aun_core.service_proxy.ServiceProxyClient`，TS/Browser 从 SDK 包入口导入，Go 使用 `NewServiceProxyClient()`。入口及选项见 [SDK API 手册](06-API手册.md)。
+
+Browser 原生 WebSocket 不能设置隧道认证所需的 `Authorization` header；在 Browser SDK 中运行 provider 隧道时，需要注入支持该 header 的 `webSocketFactory`，仅提供原生 WebSocket 不足以建立隧道。
+
+流程如下（方法名以 Python 为例）：
 
 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。
+2. proxy-server 连接地址通过 `/.well-known/aun-proxy` 发现：先读 provider AID metadata 中 1 小时 TTL 的 `service_proxy_discovery` 缓存（Python / Go / Node TS 使用 SQLite，Browser 使用 IndexedDB）；缓存缺失或过期时查询 `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 重连时，每条新连接都会重新执行以上流程。
 
-常用入口：
+常用入口（Python；TS/Browser 使用对应 camelCase，Go 使用 PascalCase 并传 `context.Context`）：
 
 | 方法 | 说明 |
 |------|------|
-| `register_service(name, endpoint, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
-| `unregister_service(name)` | 移除本地 endpoint |
+| `register_service(service_name, endpoint, *, service_type="http", visibility="private", metadata=None)` | 注册本地 embedded endpoint |
+| `unregister_service(service_name)` | 移除本地 endpoint |
 | `list_service_summaries()` | 返回可上报的服务摘要 |
 | `register_services_with_gateway()` | 显式向 Gateway 注册控制面服务列表 |
-| `unregister_services_from_gateway(names=None)` | 显式从 Gateway 注销控制面服务 |
+| `unregister_services_from_gateway(service_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 |
@@ -222,12 +226,14 @@ proxy-server 收到 `https://proxy.{issuer}/{user_name}/{svc_name}` 或对应 We
 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。
+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 内部拒绝原因不会逐项原样返回给 visitor：当前 proxy-server 将控制面查询／wakeup 失败统一为 `provider_wakeup_failed`，HTTP / WebSocket 入口返回 503；本地已有 provider 数据面连接但缺少目标服务时，直接返回 404 `service_not_registered`。
+
 因此，只向 Gateway 注册不足以承载请求；只有 proxy-server 数据面也注册了目标服务，访问才会真正转发。