@agentunion/fastaun 0.5.33 → 0.5.35

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

@@ -1,5 +1,7 @@
 # AUN SDK - API 手册
 
+本手册对照四 SDK 0.5.34 的公开接口；历史版本专题中的接口以其标注版本为准。
+
 ---
 
 ## 目录
@@ -8,11 +10,13 @@
 - [AID](#aid)
 - [AUNClient](#aunclient)
 - [业务门面](#业务门面)
+- [EventService 事件发布订阅](#eventservice-事件发布订阅)
 - [事件](#事件)
 - [ServiceProxyClient](#serviceproxyclient)
 - [E2EE 高级 API](#e2ee-高级-api)
 - [RPC 方法参考](#rpc-方法参考)
 - [Stream 使用指南](#stream-使用指南)
+- [AID 空闲 UDP 待机（测试能力）](#aid-空闲-udp-待机测试能力)
 
 > **多语言命名约定**：Python 使用 `snake_case`（如 `aun_path`、`download_agent_md`），TS/JS 使用 `camelCase`（如 `aunPath`、`downloadAgentMd`），Go 使用 `PascalCase` 公开方法（如 `Load`、`Register`）。本手册表格中各列对应各语言的实际命名。
 
@@ -64,7 +68,7 @@ store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
 | `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
-| `register(aid)` | `register(aid)` | `Register(ctx, aid[, opts])` | 注册并落盘证书和私钥；Go 两参数旧调用仍可用，显式选项使用 `AIDStoreRegisterOptions` |
+| `register(aid, *, type, owner=None, exttype=None)` | `register(aid, {type, owner?, exttype?})` | `Register(ctx, aid[, opts])` | 注册并落盘证书和私钥；`type` 必填，非 human 类型还需 `owner`；Go 两参数旧调用仍可用，显式选项使用 `AIDStoreRegisterOptions` |
 | `list()` | `list()` | `List()` | 列出本地 AID |
 | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
 | `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 解析身份及名片，返回结构化 `agent_md.frontmatter`；可按需复用 ownership 共识校验并缓存 owner.md，完整输入输出见下节 |
@@ -137,10 +141,10 @@ Python 兼容 `forceRefresh`、`skipAgentMd`、`timeoutMs`、`ownershipTtlMs`
 | `tags` | string[] | 标签 |
 | `owner` | string | 名片声明的 owner；普通主体需结合 2.1 共识状态判断；Group/Org 属于专属生命周期 |
 | `ownership` | object | 普通主体的声明容器，当前核心字段为 `statement` |
-| `entity_cert_fingerprint` | string | Group/Org 实体证书的 `sha256:<hex>` 指纹 |
+| `entity_cert_fingerprint` | string | 历史 Group/Org 名片的实体证书 `sha256:<hex>` 指纹；现代 ownership.statement 格式不再要求此字段 |
 | 其它键 | 任意解析值 | 如 visibility、skills 或应用自定义字段，存在时原样返回 |
 
-当前发布 Schema 要求 `aid/name/type/version`；读取接口兼容历史名片，因此类型声明中的标准字段可缺省，不补默认值，裸 Markdown 正文返回 `{}`。`ownership.statement` 保留六字段：`version=2`（整数）、`declaration_id`（小写 UUIDv4）、`owner_aid`、`sub_aid`、`relation_version`（正整数）和 `declared_at`（Unix 秒）。普通主体的 owner 与 statement 同时存在或同时缺省；human 禁止通用 ownership，Group/Org 不使用此声明容器。
+当前发布 Schema 要求 `aid/name/type/version`；读取接口兼容历史名片，因此类型声明中的标准字段可缺省，不补默认值，裸 Markdown 正文返回 `{}`。`ownership.statement` 保留六字段：`version=2`（整数）、`declaration_id`（小写 UUIDv4）、`owner_aid`、`sub_aid`、`relation_version`（正整数）和 `declared_at`（Unix 秒）。普通主体的 owner 与 statement 同时存在或同时缺省；human 禁止通用 ownership，现代 Group/Org 同样使用与 owner.md 配对的声明，历史无 ownership 实体名片继续兼容。
 
 字段定义与签名规则以 [当前协议 §1.3、§2](../protocol/Ownership协议定义2.1.md) 为准；[agent.md/SCHEMA.md](../agent.md/SCHEMA.md) 是 legacy Ownership 2.0。`frontmatter.owner` 和已有 `agent_md.verification.ownership_status` 都不替代下面的 2.1 共识结果。
 
@@ -172,7 +176,7 @@ Python 兼容 `forceRefresh`、`skipAgentMd`、`timeoutMs`、`ownershipTtlMs`
 | `single_sided` | 只有一方声明或待确认材料，关系尚未成立 |
 | `invalid` | 声明、签名或身份绑定等材料无效 |
 | `unavailable` | 网络、证书、服务能力、权威性或读取一致性不足，当前无法确认 |
-| `not_applicable` | Group/Org 等使用专属生命周期，不适用通用共识 |
+| `not_applicable` | NS 对缺少 ownership 的历史 Group/Org 保留该标记；现代实体声明参与双文件共识，SDK 以实际返回 status 为准 |
 
 `owner_md` 包含 `owner_aid: string`、`bucket: "default"`、`path: "sub_aids/{aid}/owner.md"`、`exists: bool`、`content: string`（完整原文，含签名）、`sha256: string`、`observed_at: integer`（Storage 观察时间，Unix 秒）。确认不存在时 exists=false、content/sha256 为空串；存在快照不表示整体共识成功，须检查 status。
 
@@ -204,7 +208,7 @@ if result.Ok && result.Data.AgentMD != nil {
 
 ### 通用 sign / verify
 
-`format="raw"` 为默认，保留 detached Base64 签名／验签；`format="document"` 处理任意 UTF-8 文本文档的连续尾签，不要求 YAML 或 agent.md 业务字段。sign 返回 `signed` 全文、本次 `signature` 和实际 `signatures` 列表；verify 返回 `valid`、`status`、首块前 `payload` 及逐块 `signatures`。普通 agent.md 与 owner.md 主签不输出且业务不接受 signer_aid；实体主块显式 signer_aid=target，主签身份、Schema、资源及授权由调用者另验，SDK 文件流程和服务端均复用各自唯一同构签验 core。
+`format="raw"` 为默认，保留 detached Base64 签名／验签；`format="document"` 处理任意 UTF-8 文本文档的连续尾签，不要求 YAML 或 agent.md 业务字段。sign 返回 `signed` 全文、本次 `signature` 和实际 `signatures` 列表；verify 返回 `valid`、`status`、首块前 `payload` 及逐块 `signatures`。普通 agent.md、owner.md 与现代 Group/Org agent.md 主签均不输出且业务不接受 signer_aid；历史实体主签格式另按兼容规则验证，主签身份、Schema、资源及授权由调用者另验，SDK 文件流程和服务端均复用各自唯一同构签验 core。
 
 `input_type="text"` 默认把输入视作内容；显式 `input_type="file"` 才读取文件；raw 按原始字节处理，包括非 UTF-8 文件，document 必须严格 UTF-8，raw/document 字符串均严格校验 Unicode 并编码为 UTF-8，无效 Unicode 拒绝。不识别 `file://` 或自动猜路径，缺失文件报错。`in_place=True` 仅适用于 file + document，签名成功后才写回；TS/JS 使用 `inputType/inPlace`，Go 使用 `InputType/Format/Tag/Append/InPlace`。浏览器 File/Blob 只读，FileSystemFileHandle 可原地写，不接受裸本地路径。
 
@@ -270,11 +274,11 @@ AID 由 `AIDStore.load()` 返回，应用层不直接构造。
 
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
-| `aid` | `aid` | `AID()` | AID 字符串 |
-| `cert_pem` | `certPem` | `CertPEM()` | 证书 PEM |
-| `public_key` | `publicKey` | `PublicKey()` | 公钥 |
-| `cert_fingerprint` | `certFingerprint` | `CertFingerprint()` | 证书指纹 |
-| `aun_path` | `aunPath` | `AUNPath()` | 所属数据目录 |
+| `aid` | `aid` | `Aid` 字段 | AID 字符串 |
+| `cert_pem` | `certPem` | `CertPem` 字段 | 证书 PEM |
+| `public_key` | `publicKey` | `PublicKey` 字段 | 公钥 |
+| `cert_fingerprint` | `certFingerprint` | `CertFingerprint` 字段 | 证书指纹 |
+| `aun_path` | `aunPath` | `AunPath` 字段 | 所属数据目录 |
 | `device_id` | `deviceId` | `DeviceID` | 设备 ID |
 | `slot_id` | `slotId` | `SlotID` | 实例槽位 ID；允许 `/`、`:`、空格作为共享隔离键分隔符 |
 | `verify_ssl` | `verifySsl` | `VerifySSL` | 是否校验 TLS 证书 |
@@ -461,7 +465,7 @@ headers = client.get_protected_headers()
 - agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
 - 普通主体目标 AID 须有本地签名材料并使用自身 token；Group/Org 用实体主签、当前 owner token 上传，可选 owner 附签，不能以附签替换资源授权。agent.md 与 owner.md 统一调用 Store document 签验 core，再验证业务 Schema。
 - 实体上传默认使用名片当前 owner；显式指定上传者分别使用 Python `uploader_aid`、TS/JS `options.uploaderAid`、Go `AIDStoreUploadAgentMDOptions.UploaderAID`。追加 owner 附签分别使用 `co_signer_aid`、`options.coSignerAid`、`AIDStoreUploadAgentMDOptions.CoSignerAID`，值必须为当前 owner；Go 通过 `UploadAgentMDWithOptions` 传入选项。
-- SDK 全部 NS GET/HEAD/PUT 携带 `X-AUN-Signature-Format: multi-v1`；GET 同时发送 `Accept: text/markdown`；实体 fresh GET 另带 `X-AUN-Ownership-Check: 1` 与 `Cache-Control: no-cache` 以绕 LRU 全块验证，仍为 not_applicable、不进入通用账本；不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+- SDK 全部 NS GET/HEAD/PUT 携带 `X-AUN-Signature-Format: multi-v1`；GET 同时发送 `Accept: text/markdown`；实体 fresh GET 另带 `X-AUN-Ownership-Check: 1` 与 `Cache-Control: no-cache` 以绕 LRU 全块验证；现代实体参与双文件共识，NS 对缺少 ownership 的历史实体保留 not_applicable 标记；不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
 - SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
 - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
 
@@ -471,6 +475,44 @@ headers = client.get_protected_headers()
 
 除 `client.call(method, params)` 外，四语言 SDK 提供高层门面（Facade），封装常用操作并简化参数。普通应用优先用门面，只有需要精确控制底层参数时再直调 RPC。
 
+### EventService 事件发布订阅
+
+Python / TS / JS 使用 `client.EventService` 属性，Go 使用 `client.EventService()`。以下均为该门面的方法，不是 Gateway `pubsub.*` RPC；跨 AID 请求由 SDK 通过 E2EE P2P 消息承载。
+
+| 操作 | Python | TypeScript / JavaScript | Go |
+|------|--------|-------------------------|----|
+| 启动本地 Bus | `await start(bus_aid, catalog=..., allowlist=...)` | `await start(busAid, {catalog, allowlist})` | `Start(ctx, busAid, EventServiceStartOptions{...})` |
+| 按角色授权 | `await authorize(bus_aid, role, auth_mode, events, credential=None)` | `await authorize(busAid, role, authMode, events, credential?)` | `Authorize(ctx, busAid, role, authMode, events, grant)` |
+| 发布对象 | `await publish(bus_aid, event_name, data, **options)` | `await publish(busAid, eventName, data, options?)` | `Publish(ctx, busAid, eventName, data, options...)` |
+| 等待发布结果 | `await wait_published(bus_aid, event_id)` | `await waitPublished(busAid, eventId)` | `WaitPublished(ctx, busAid, eventID)` |
+| 订阅／取消订阅 | `await subscribe(bus_aid, events)` / `unsubscribe(...)` | `await subscribe(busAid, events)` / `unsubscribe(...)` | `Subscribe(ctx, busAid, events)` / `Unsubscribe(...)` |
+| 接收事件 | `on_event(bus_aid, handler)` / `await next_event(bus_aid, timeout=None)` | `onEvent(busAid, handler)` / `await nextEvent(busAid, timeout?)` | `OnEvent(busAid, handler)` / `NextEvent(ctx, busAid)` |
+| 事件定义目录 | `await catalog(bus_aid, **params)` | `await catalog(busAid, params?)` | `Catalog(ctx, busAid, params)` |
+| 发布／订阅目录 | `await publications(bus_aid, **params)` / `subscriptions(...)` | `await publications(busAid, params?)` / `subscriptions(...)` | `Publications(ctx, busAid, params)` / `Subscriptions(...)` |
+| 宿主管理 | `update_config` / `stats` / `issue_grant` / `revoke_grant` | `updateConfig` / `stats` / `issueGrant` / `revokeGrant` | `UpdateConfig` / `Stats` / `IssueGrant` / `RevokeGrant` |
+| 生命周期 | `renew` / `drain` / `close` | `renew` / `drain` / `close` | `Renew` / `Drain` / `Close` |
+
+`start` 要求 `bus_aid == client.aid`；接入远端 Bus 直接按 `pub` / `sub` 分别 `authorize`，授权成功自动加载获准的事件定义目录。同一 client 可在同一 Bus 上同时绑定 `bus`、`pub`、`sub`，Bus 自发自订仍需相应权限。管理方法仅本地 Bus 宿主可用。`renew`、`drain`、`close` 覆盖该 Bus 相关角色；Go `Close(busAid)` 不接收 context，异步方法的具体参数及返回见[应用集成指南](AUN事件发布订阅应用集成指南.md)。
+
+`publish` 的 `data` 必须是 JSON 对象，成功返回 `event_id` 字符串（Go 另返回 error），表示已持久化并入队。选项分别为 Python `schema_version` / `ttl_seconds` / `reply_mode` / `event_id`，TS/JS `schemaVersion` / `ttlSeconds` / `replyMode` / `eventId`，Go `PubSubPublishOptions`。`wait_published` / `waitPublished` / `WaitPublished` 返回所选阶段结果：默认 `none` 为 AUN 已接受发送，`accepted` 为 Bus 已受理，均不证明订阅方业务完成。后台完成通知分别使用 `on_publish` / `onPublish` / `OnPublish`；Go handler 接收 `(eventID, result, error)`，Python / TS / JS handler 接收含 `event_id` 与 `result` 或 `error` 的对象。
+
+默认持久化覆盖 Bus 事件目录、白名单、有效授权和订阅，以及客户端授权材料、目录、订阅意图、待发布记录和过期失败结果。Python / TS（Node.js）/ Go 复用身份目录的 SQLite `aun.db`，浏览器 JS 使用 IndexedDB；自定义 Bus 存储与 Python / Go 的 `state_path` / `StatePath` 边界见[持久化说明](AUN事件发布订阅应用集成指南.md#7-持久化统计与故障定位)。启动加载旧目录后按事件合并本次配置，未提交的事件保留，同名条目以本次配置为准；后续注册、订阅与配置修改写回持久层。
+
+待发布消息先落库再入队；达到所选回复模式的成功阶段后删除本地正文，关闭或未确认成功时保留。重启重新接入对应角色后按原 `event_id`、原 `expires_at` 恢复，过期后记录 `EXPIRED`，不延长 TTL。成功结果仅有界保留在运行期，过期失败结果也受容量限制。Bus 已受理后的 fanout、服务端 volatile 收件箱及历史事件不在此持久恢复范围内。
+
+#### publications / subscriptions 查询
+
+查询的可选参数为 `event_name`、`limit`（默认 50，范围 1–200）、`page_token`；TS/JS 和 Go 的查询 map 也使用这些 snake_case 字段。`role` 只在本地选择查询端：`publications` 可选 `bus` / `pub`，`subscriptions` 可选 `bus` / `sub`；省略优先本地 Bus，否则使用对应客户端角色，不发送到网络。
+
+Bus 宿主可查询全局；Pub 仅查看自身 AID、当前发布权限内的汇总，Sub 仅查看当前设备租约实际生效的订阅。`authorize` 成功本身不建立订阅。查询返回 `{service_aid, since, as_of, items, next_page_token}`，时间均为 Unix 毫秒，末页 token 为 null：
+
+| 查询 | `items` 字段 |
+|------|---------------|
+| `publications` | `publisher_aid`、`event_name`、`published`、`first_published_at`、`last_published_at` |
+| `subscriptions` | `subscriber_aid`、`event_name`、`device_id`、`slot_id`、`expires_at` |
+
+发布汇总只计 Bus 首次受理，不计拒绝与去重，TTL 到期不删除汇总，Bus 重启清零；订阅目录只返回当前有效关系，不包含凭证或租约令牌。每页是实时视图，不冻结快照；分页 token 有效 60 秒并绑定操作、查询范围及当前 Bus 运行实例，完整回包最多 64 KiB。事件定义仍通过 `catalog` 查询。完整流程和参数见[应用集成指南](AUN事件发布订阅应用集成指南.md)，内部契约见[开发移植指南](AUN事件发布订阅开发移植指南.md)。
+
 ### Ownership、凭证与组织专题
 
 | 领域 | 当前入口 | 详细指南 |
@@ -478,7 +520,7 @@ headers = client.get_protected_headers()
 | Ownership 2.1 | 七个关系业务Facade：`bindOwneraid`、`bindSubaid`、`releaseSubaid`、`transferSubaid`、`acceptOwnershipRequest`、`rejectOwnershipRequest`、`checkOwnershipConsensus`；无参数任务管理Facade `resetOwnershipTask()`（Python `reset_ownership_task()`、Go `ResetOwnershipTask(ctx)`），批量清理当前AID发起的未完成任务，返回`{reset_operation_ids:[],skipped_operation_ids:[]}`（其余为TS/JS命名） | [应用集成](Ownership2.1-SDK应用集成指南.md#4-七个-facade-的参数角色与结果)、[开发与移植](Ownership2.1-SDK开发与移植指南.md) |
 | Credential/Org | Python/TS/JS：`client.credential`、`client.org`；Go：`client.Credential()`、`client.Org()`；普通与语义凭证共用 credential 入口，无 semantic 子层；包含签验、包／请求、消息证据及额度协调工具 | [应用集成](凭证与组织服务SDK应用集成指南.md)、[开发与移植](凭证与组织服务SDK开发与移植指南.md) |
 
-Ownership 2.1 关系须检查当前双文件共识；Group/Org 使用专属生命周期，通用关系操作返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
+Ownership 2.1 关系须检查当前双文件共识；现代 Group/Org 同样发布配对声明并查询共识，但创建、绑定、转让和解散仍使用专属生命周期，普通 bind/release/transfer 关系管理 Facade 返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
 
 sub-first 绑定在 sub 同意后 Stage 暂存 `agent.md`；NS 的 `pending/unlocked` 对公共共识映射为 `single_sided`，不授予 owner 权限，Storage 名片副本待 fresh 验收清除 pending 后同步。owner-first 绑定先 fresh 确认无锁并条件发布 `owner.md`，sub fresh 验证后同意并直接条件提交 `agent.md`，不走 Stage 或 bind.accept／owner.ready 往返。已有 owner 锁时只能由当前 owner 发起解绑或转移；拒绝清理与 reset 的原件／CAS 边界见 [应用指南 §6.1](Ownership2.1-SDK应用集成指南.md#61-绑定按发起方分流)。普通消息建议连接前订阅，READY 后补订阅也会触发任务恢复。
 
@@ -860,7 +902,7 @@ await client.push.unregister()
 
 ## ServiceProxyClient
 
-Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
+Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。Python、TypeScript、JavaScript 和 Go 均提供 `ServiceProxyClient` 封装；浏览器 JavaScript 需通过可承载 Authorization Bearer 的自定义 WebSocket factory 建立隧道。公开入口与控制面字段见 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md)。
 
 ```python
 from aun_core.service_proxy import ServiceProxyClient
@@ -895,6 +937,8 @@ proxy-server 连接地址不能由应用外部传入或配置。`ServiceProxyCli
 | `serve_once()` | 处理有限数量的 proxy-server 转发请求 |
 | `serve_forever(connection_mode="persistent")` | 持续提供 Service Proxy 服务；支持 persistent / on_demand |
 
+四端构造与生命周期命名：Python `ServiceProxyClient(provider_aid=..., aun_client=client)`；TS/JS `new ServiceProxyClient({providerAid, aunClient})`；Go `NewServiceProxyClient(ServiceProxyClientOptions{ProviderAID: ..., AUNClient: client})`。对应方法分别使用 `register_service` / `registerService` / `RegisterService`、`connect_once` / `connectOnce` / `ConnectOnce`、`serve_once` / `serveOnce` / `ServeOnce`、`serve_forever` / `serveForever` / `ServeForever`。浏览器 JS 的 `webSocketFactory` 必须能发送隧道的 Authorization Bearer 请求头，原生浏览器 WebSocket 不满足该条件。
+
 自动注册顺序：
 
 - `connect_once()`、`serve_once()`、`serve_forever()` 在存在 `aun_client.call()` 时，会先向 Gateway 调用 `proxy.register_services`。
@@ -1046,13 +1090,11 @@ JavaScript 浏览器 SDK 的 Worker 是网络隔离增强：`new Worker()` 同
 
 | API | 说明 |
 |-----|------|
-| `client.e2ee.encrypt_message(...)` | 裸 WebSocket 或特殊集成中的 P2P 加密 |
-| `client.e2ee.decrypt_message(...)` | 裸消息解密 |
-| `client.e2ee.generate_prekey()` | 生成 prekey |
-| `client.e2ee.invalidate_prekey_cache(peer_aid)` | 清理对端 prekey 缓存 |
-| `client.group_e2ee.encrypt(...)` | 群消息加密 |
-| `client.group_e2ee.decrypt(...)` | 群消息解密 |
-| `client.group_e2ee.current_epoch(group_id)` | 查询当前群 epoch |
+| Python | `aun_core.v2.e2ee.encrypt_p2p.encrypt_p2p_message`、`encrypt_group.encrypt_group_message`、`decrypt.decrypt_message` |
+| TypeScript / JavaScript | 根入口导出的 `encryptP2PMessage`、`encryptGroupMessage`、`decryptMessage` |
+| Go | `v2/e2ee.EncryptP2PMessage`、`EncryptGroupMessage`、`DecryptMessage` |
+
+这些是低层 E2EE 函数，需要调用方提供对应的密钥和目标上下文；普通 `message.send` / `group.send` 由 SDK 自动管理加密，不应改用低层函数替代。
 
 ---
 
@@ -1096,3 +1138,28 @@ info = await client.call("stream.get_info", {"stream_id": stream["stream_id"]})
 await client.call("stream.close", {"stream_id": stream["stream_id"]})
 ```
 
+## AID 空闲 UDP 待机（测试能力）
+
+Python、TypeScript/Node.js 与 Go SDK 支持独立 AID 实例的 UDP 待机，浏览器 JS 与本期暂不移植 UDP 的 Rust SDK 保持 WebSocket。具有待机控制器的主长连接通过 `auth.connect.capabilities.udp_standby_v1=true` 声明能力；Gateway 默认关闭，响应 `capabilities.udp_standby_v1` 表达当前实际可用性，只有 `negotiated_capabilities.udp_standby_v1` 与 `udp_standby.enabled` 均严格为布尔 `true` 才启用，缺失、`false` 或字符串 `"true"` 保持 WS；短连接和辅助连接不声明。客户端初次上线仍建立 WS 并正常认证、检查和补拉，通过双向空闲与在途任务门禁后才释放 WS。Node 使用内置 `node:dgram`，无需新增运行依赖。原定 Ubuntu Docker 单域 11 场景已分轮通过，新增动态心跳与 human 准入仍待增量实机验证，容量未验。
+
+准备阶段通过 `AIDStore.resolve(...)` 的 `agent_md.frontmatter.type` 识别自身 AgentMD 类型；已知 `human` 保持 WS，未知沿用原准入，不以注册意图替代本次 AgentMD 结果。UDP 心跳不查询 AgentMD。
+
+`HEARTBEAT_ACK` 正文固定为 `lease_remaining_ms:uint32 + pending_generation:uint64 + reason_mask:uint32 + heartbeat_interval_ms:uint32`，共 20 字节，其他报文结构不变。Gateway 每次收到有效 HEARTBEAT 都返回当前周期 T 并按 4T 续租，SDK 按 T 的 ±20% 抖动安排下一次心跳；动态配置更新不追溯缩短已发租约。SDK 连续 3 次响应超时后恢复 WS；默认 T=25 秒、单次等待 5 秒，服务端正常窗口 100 秒，授权、票据或目录期限可更早到达。正常切换不产生应用离线回调，任一有效 WS/UDP 在线即保持应用在线；未新增切换完成回调或公开字段。
+
+应用仅在确定不依赖瞬时通知时，显式选择可恢复事件；以下示例改变服务端事件过滤，不适用于需要全事件的应用：
+
+```python
+await client.connect()
+await client.call("event.subscribe", {
+    "events": ["message.received", "group.message_created"],
+})
+```
+
+TypeScript 使用 `client.call()`，Go 使用 `client.Call(ctx, ...)` 调用同一 RPC。`event.subscribe` / `event.unsubscribe` 的 `subscribed` 返回完整过滤集合；默认全事件、queue、流式和非白名单事件会话继续保持 WS，SDK 不自动缩窄已有订阅。TypeScript/Node 可通过 `connect({udp_standby: false})` 禁止本次连接声明该能力；不要将该选项直接套用到其他 SDK。
+
+进入待机后，`call`、消息发送、认证刷新等真实网络需求会立即恢复 WS，多个并发调用共享恢复过程，各自保留原 deadline 与取消语义；缓存命中的本地读取不唤醒。服务端消息提示也通过恢复 WS 后的原 Pull/ACK 流程处理。WAKE_ACK 不代表业务消费，UDP 不发送正文、不延长消息 TTL、不重放已经发出的写请求。
+
+为支持连续待机，SDK 使用 `gateway.standby.prepare` 返回的 `event_subscriptions` 权威快照，在恢复 `auth.connect.options.event_subscriptions` 中提交；Gateway 从新会话首次事件路由起应用该过滤。未传字段仍为原全事件语义，显式 `[]` 为无事件。应用不需要每次唤醒后手工重新订阅，也不应自行重放待机票据或认证签名。
+
+`disconnect()` / `close()` 停止本实例的待机与自动恢复，不影响同主机其他 AID。UDP 验证失败、连续无应答、租约/票据到期或 Gateway 故障时回 WS 并遵守冷却与原重连限制；UDP 不能唤醒已退出的进程。协议、事件白名单、错误原因和部署方式见 [Gateway 连接模式 §3.10](../../../docs/AUN文档/AUN协议/03-Gateway-连接模式.md#310-aid-空闲-udp-待机测试能力)，状态机与验收边界见 [详细设计](../../../docs/AUN文档/AID空闲UDP待机详细设计.md)。
+

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

@@ -6,7 +6,15 @@
 >
 > **授权 = 协作根写 ACL**：谁能 `commit` = 谁对 `collab_root` 有写权限。普通 AID storage 可继续用 `storage.set_acl/remove_acl` 管理写授权；群 `memberdata` 协作根必须用 `collab.set_acl/remove_acl` 按 `collab_root` 授权，SDK/CLI 不得拼接真实 `group_data` 路径。
 >
-> SDK 侧通过 `client.collab` 访问（`CollabClient`），每个命令 1:1 映射一条 `collab.*` RPC。
+> Python / TypeScript / Browser SDK 通过 `client.collab` 访问（`CollabClient`）；Go 使用 `client.Collab()`，标签入口为 `.Tag()`。每个命令映射一条 `collab.*` RPC。
+
+## SDK 返回差异
+
+下文定义服务端原始 RPC 字段。Python / TypeScript / Browser 保留原始结果；Go 0.5.34 的类型化返回尚有以下差异，需要完整字段时使用原始 `client.Call()`：
+
+- GC 不保留 `reachable` / `freed_bytes`；Reflog 不保留 `seq` / `metadata`，且其 `RequesterAID` / `CreatedAt` 不能接收当前 `requester` / `timestamp` 字段。
+- Tag Create 不保留 `bump` / `changed`；Revert 不保留 `no_change`；Tag Restore 不保留 `partial`，`new_snapshot_version: null` 解析为空字符串。
+- Tag Diff 的 `added` / `removed` 实际为文档名字符串数组，Go 类型仍按对象数组解析，非空时会返回解码错误；Tag Rm 的 `removed: true` 转为整数 `1`，且不保留 `version`。
 
 ## 方法索引
 
@@ -74,11 +82,11 @@
 
 ### 乐观锁（commit）
 
-1. `put_object`（写新版本文件，永不失败，数据先存下）。
+1. `put_object` 写入候选版本文件；上传失败直接返回错误。
 2. 同一事务：`atomic_repoint(<doc>@current, new_target, expected_version=onto)` + 台账追加。
-3. CAS 成功 → version+1；CAS 失败 → 整事务回滚，返回 `{ok:false, current_version, hint}`。
+3. CAS 成功 → version+1；CAS 失败 → 返回 JSON-RPC `-32009`，`error.data` 包含 `current_version`、`current_target`、`hint`，并清理候选文件。
 
-`onto` 来源：`collab.show` 响应的 `version` 字段；merge 后用 commit 失败响应的 `current_version`。
+`onto` 来源：`collab.show` 响应的 `version` 字段；冲突时由 SDK 的 `CollabConflictError` 取得当前版本，合并后再提交。失败请求不保证保留候选正文，调用方应保留自己的草稿。
 
 ### 数据不变量
 
@@ -126,7 +134,7 @@ docs = await client.collab.ls_files("alice.aid.pub:/projects/myapp")
 |------|------|------|------|
 | `collab_root` | string | 是 | 协作根 `<aid>:<path>` |
 | `doc` | string | 是 | 文档名 |
-| `source` | string | 是 | 初始内容：本地文件路径或 `<aid>:<path>` |
+| `source` | string | 是 | Base64 编码的正文或可读的 `<aid>:<path>`；SDK 不读取本地文件路径 |
 
 ### 响应
 
@@ -153,11 +161,11 @@ docs = await client.collab.ls_files("alice.aid.pub:/projects/myapp")
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `content` | string | base64 编码的当前内容 |
+| `content` | string | base64 编码的所读版本内容 |
 | `version` | integer | 当前或指定版本号（**commit 的 onto 来源**） |
-| `author` | string | 当前版本作者 AID |
-| `anchor` | string | 台账锚点（读取历史版本时返回） |
-| `current_target` | string | 当前版本文件绝对路径（读取当前版本时返回） |
+| `author` | string | 所读版本作者 AID |
+| `anchor` | string | 台账锚点，当前和历史版本均返回 |
+| `current_target` | string | 所读版本文件绝对路径，当前和历史版本均返回 |
 
 ---
 
@@ -171,8 +179,9 @@ docs = await client.collab.ls_files("alice.aid.pub:/projects/myapp")
 |------|------|------|------|
 | `collab_root` | string | 是 | 协作根 `<aid>:<path>` |
 | `doc` | string | 是 | 文档名 |
-| `source` | string | 是 | 新内容：本地路径或 `<aid>:<path>` |
+| `source` | string | 是 | Base64 编码的新正文或可读的 `<aid>:<path>`；不是本地文件路径 |
 | `onto` | integer | 是 | 基线版本号（来自 `collab.show` 的 `version`） |
+| `message` | string | 否 | 台账说明，默认空字符串 |
 
 ### 响应
 
@@ -184,23 +193,27 @@ docs = await client.collab.ls_files("alice.aid.pub:/projects/myapp")
 | `version` | integer | 新版本号（onto+1） |
 | `current_target` | string | 新版本文件绝对路径 |
 
-**撞版本失败**（数据已安全保存，需 merge 后重提）：
+**撞版本失败**：JSON-RPC `-32009` 的 `error.data` 字段如下；四个 SDK 映射为 `CollabConflictError`，不是成功响应中的 `ok:false`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `ok` | boolean | `false` |
 | `current_version` | integer | 当前权威版本号（**merge 后 commit 用此作新 onto**） |
 | `current_target` | string | 当前权威版本文件绝对路径 |
-| `hint` | string | 后端格式化好的下一步命令行字符串 |
+| `hint` | string | 合并并重新提交的提示语，不是可执行命令 |
 
 ### 示例
 
 ```python
+from aun_core.collab.errors import CollabConflictError
+import base64
+source = base64.b64encode(draft_bytes).decode()
 cur = await client.collab.show(root, "design.md")
-res = await client.collab.commit(root, "design.md", "./design.md", cur["version"])
-if not res["ok"]:
-    await client.collab.merge(root, "design.md", "./design.md", cur["version"])
-    res = await client.collab.commit(root, "design.md", "./design.md", res["current_version"])
+try:
+    res = await client.collab.commit(root, "design.md", source, cur["version"])
+except CollabConflictError as conflict:
+    merged = await client.collab.merge(root, "design.md", source, cur["version"])
+    if not merged["conflicts"]:
+        res = await client.collab.commit(root, "design.md", merged["content"], conflict.current_version)
 ```
 
 ---
@@ -215,7 +228,7 @@ if not res["ok"]:
 |------|------|------|------|
 | `collab_root` | string | 是 | 协作根 `<aid>:<path>` |
 | `doc` | string | 是 | 文档名 |
-| `source` | string | 是 | 本地草稿内容（ours）：本地路径或 `<aid>:<path>` |
+| `source` | string | 是 | 草稿内容（ours）：Base64 正文或可读的 `<aid>:<path>` |
 | `onto` | integer | 是 | 共同祖先版本号 |
 
 ### 响应
@@ -225,7 +238,7 @@ if not res["ok"]:
 | `content` | string | base64 编码的合并结果 |
 | `conflicts` | boolean | 是否含冲突标记（`<<<<<<<` / `=======` / `>>>>>>>`） |
 
-`conflicts=true` 时需人工编辑消解冲突后再 commit。
+merge 只计算并返回正文，不修改草稿或当前版本。`conflicts=true` 时需编辑消解冲突；提交时将合并正文编码后传给 `commit`。
 
 ---
 
@@ -256,8 +269,8 @@ if not res["ok"]:
 |------|------|------|------|
 | `collab_root` | string | 是 | 协作根 `<aid>:<path>` |
 | `doc` | string | 是 | 文档名 |
-| `from` | integer | 是 | 起始版本号（SDK 形参 `v_from`） |
-| `to` | integer | 是 | 目标版本号（SDK 形参 `v_to`） |
+| `from` | integer | 是 | 起始版本号；Python 形参 `v_from`，TS/Browser/Go 为 `fromVersion` |
+| `to` | integer | 是 | 目标版本号；Python 形参 `v_to`，TS/Browser/Go 为 `toVersion` |
 
 ### 响应
 
@@ -342,7 +355,7 @@ if not res["ok"]:
 
 ### 响应
 
-返回日志数组，每项包含 `seq`、`action`、`requester`、`doc`、`version`、`onto`、`target`、`status`、`error_code`、`error_msg`、`metadata`、`timestamp` 等字段。
+返回日志数组，每项包含 `seq`、`action`、`requester`、`doc`、`version`、`base_version`、`target`、`status`、`error_code`、`error_msg`、`metadata`、`timestamp` 等字段。
 
 ---
 
@@ -441,13 +454,13 @@ if not res["ok"]:
 
 ### 响应
 
-返回新增/删除/版本变化的文档清单。
+返回 `added`、`removed`、`changed` 三个文档名字符串数组。
 
 ---
 
 ## collab.tag.restore
 
-回滚到某标签。**forward-only**：不回退 version 计数器，而是对每个文档以标签中的旧内容写一个新版本（vN+1），最后以回滚后状态自动创建新标签。
+回滚到某标签。**forward-only**：不回退 version 计数器，而是对每个文档以标签中的旧内容写一个新版本（vN+1），完成后尝试创建新标签；部分失败或无变化时不保证产生新标签。
 
 ### 参数
 
@@ -462,14 +475,16 @@ if not res["ok"]:
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `restored_from` | string | 回滚来源标签版本 |
-| `new_snapshot_version` | string | 回滚后自动创建的新标签版本（历史字段名保留为 `new_snapshot_version`） |
+| `new_snapshot_version` | string / null | 回滚后创建的新标签版本；部分失败或无变化时可为 `null`，历史字段名保留 |
 | `warnings` | array | 回滚过程中的告警（如某文档被他人并发提交而跳过） |
+| `restored_docs` | array | 已恢复的文档 |
+| `partial` | boolean | 可选；部分失败时为 `true`，RPC 本身仍可成功返回 |
 
 ---
 
 ## collab.tag.rm
 
-删除单个标签。
+删除单个标签；当前活动标签不能删除。
 
 ### 参数
 
@@ -482,7 +497,8 @@ if not res["ok"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `ok` | boolean | `true` |
+| `removed` | boolean | 是否删除 |
+| `version` | string | 标签版本 |
 
 ---
 
@@ -537,7 +553,7 @@ if not res["ok"]:
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `ok` | boolean | `true` |
+| `removed` | integer | 删除的注册表条目数 |
 
 ---
 
@@ -577,5 +593,7 @@ if not res["ok"]:
 | -32002 | 服务暂不可用（数据库未连接） |
 | -32004 | 权限拒绝（requester 对 collab_root 无写权限） |
 | -32008 | 协作文档 / 版本 / 标签不存在 |
-| -32009 | 版本冲突（commit 撞版本，见 `ok:false` 响应；tag create 时标签头已移动） |
-| -32000 | 通用错误（参数校验失败、源内容读取失败、无变更可打标签等） |
+| -32009 | 版本冲突；commit 的 `error.data` 包含当前版本与合并提示，tag create 时也可能表示标签头已移动 |
+| -32010 | 无变化可创建标签 |
+| -32602 | 参数校验失败 |
+| -32000 | 其它服务错误，如源内容读取失败 |

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 |
@@ -167,19 +169,19 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ## 群组生命周期
 
-群 owner 由本节生命周期自动建立、转移和解除，不进入 Ownership 2.1 的 `owner.md`、关系版本、owner 锁、P2P 审批或通用 Facade。创建时群公私钥及证书归初始 owner 持有；解散解除有效 owner 授权；专属转移必须 rekey，旧材料失效，新材料归新 owner。Group 服务从不保存群私钥。
+群 owner 由本节专属生命周期建立、转移和解除；SDK 发布配对的 `owner.md`／`agent.md` 声明，并通过 Ownership 2.1 关系版本、owner 锁和双文件共识确认归属，不调用普通 bind/release/transfer Facade 或普通主体 P2P 审批流程。创建时群公私钥及证书归初始 owner 持有；解散解除有效 owner 授权；专属转移必须 rekey，旧材料失效，新材料归新 owner。Group 服务从不保存群私钥。
 
-### 群 agent.md 的 owner 代签与上传
+### 群 agent.md 的实体主签与 owner 上传
 
-新 SDK 群名片 aid 为 group_aid、type=group、owner 为当前群主，entity_cert_fingerprint 为当前群证书指纹；必须省略 ownership、ownership_proof、ownership_release。实体私钥主签，当前 owner token 上传，无需群登录，可选 owner 附签，存在时必须全块验证。取消实体额外 V2 授权头；群证书指纹仍绑定 owner/rekey 代际，完整多签与 CAS 见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
+现代 SDK 群名片 aid 为 group_aid、type=group、owner 为当前群主，携带与 owner.md 配对的 ownership.statement；不再要求旧 entity_cert_fingerprint，主签不含 signer_aid，也不使用 ownership_proof／ownership_release。实体私钥主签，当前 owner token 上传，无需群登录，可选 owner 附签，存在时必须全块验证。SDK 先写 owner.md，再发布实体声明并确认共识；仍校验当前 owner/rekey 证书代际，完整多签与 CAS 见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
 
 管理员的 group.update、group.index 或文件权限不授予现代群名片上传权。NS 新鲜校验当前 owner、生命周期及群当前证书；Group 旧群证书单签、群身份上传始终兼容，仍执行权威检查与文件 CAS，不据此开放 Org。转移完成后新 owner 用新群材料主签并以本人 token 上传；解散后禁止发布。普通 Ownership Facade 对群目标返回 not_applicable。
 
-新 SDK 群名片全部 NS GET/HEAD/PUT 含 fresh 携带 X-AUN-Signature-Format: multi-v1，返回完整多签及对应 ETag；旧客户端按首签投影读取，多块投影不改完整存储，单块保持原文。实体 fresh GET 还必须同时携带 X-AUN-Ownership-Check: 1 和 Cache-Control: no-cache，Check 头才触发 NS 绕 LRU 全块新鲜验证，不进入通用账本；fresh 返回 not_applicable、实体 current/stale、权威 owner/证书指纹；真正 missing 为 404 且带权威头，无 ETag，依赖失败为 503。verified 下载全块验证历史证书和原文，历史验签不能作为当前授权；上传仍校验当前生命周期和证书，实体代际冲突 409、ETag 冲突 412。
+新 SDK 群名片全部 NS GET/HEAD/PUT 含 fresh 携带 X-AUN-Signature-Format: multi-v1，返回完整多签及对应 ETag；旧客户端按首签投影读取，多块投影不改完整存储，单块保持原文。实体 fresh GET 还必须同时携带 X-AUN-Ownership-Check: 1 和 Cache-Control: no-cache，Check 头触发 NS 绕 LRU 全块新鲜验证；现代群声明参与双文件共识，缺少 ownership 的历史群仍返回 not_applicable 及实体校验元数据。真正 missing 为 404 且带权威头，无 ETag，依赖失败为 503。verified 下载全块验证历史证书和原文，历史验签不能作为当前授权；上传仍校验当前生命周期和证书，实体代际冲突 409、ETag 冲突 412。
 
 ### group.create
 
-创建群组。调用者自动成为 owner，无需额外 Ownership 绑定。支持创建命名群（传入 `group_name` + `public_key`）。owner 本地生成、持有群私钥，服务端只接收公钥；证书导入 owner 本地后按本节 owner 规则发布群名片。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+创建群组。调用者自动成为 owner，无需额外调用普通 Ownership 绑定 Facade；SDK 生命周期流程同步完成配对声明和共识确认。支持创建命名群（传入 `group_name` + `public_key`）。owner 本地生成、持有群私钥，服务端只接收公钥；证书导入 owner 本地后按本节 owner 规则发布群名片。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 四种 SDK 的高层建群接口均支持崩溃恢复。命名群在 RPC 前持久化群密钥，并按 `group_name + public_key` 重放已提交结果；匿名群在 RPC 前持久化群密钥和创建上下文，重试会取回同一数字群并继续 `group_aid` 证书绑定与 `agent.md` 上传。群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射由服务端在同一数据库事务提交；证书服务和存储服务不参与该数据库事务，由 SDK pending 状态和服务端幂等重放恢复。
 
@@ -239,7 +241,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.bind_aid
 
-为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。这是群身份生命周期操作，不建立 Ownership 2.1 关系；绑定后身份材料由当前 owner 持有。
+为已有普通群绑定命名 AID（升级为命名群）。仅群主可操作。这是群身份生命周期操作，不调用普通 Ownership 绑定 Facade；绑定后身份材料由当前 owner 持有，SDK 生命周期流程完成配对声明及共识确认。
 
 **参数**：
 
@@ -619,7 +621,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.bind_group_aid
 
-为匿名群绑定群身份（group_aid）。需要 owner 权限。这不是 Ownership 绑定；成功后当前 owner 持有群身份材料，并以本人身份代签代上传群名片。
+为匿名群绑定群身份（group_aid）。需要 owner 权限。这是专属群身份绑定，不调用普通 Ownership 绑定 Facade；成功后当前 owner 持有群身份材料，以实体私钥主签、本人 token 上传群名片，SDK 完成配对 owner.md 声明与共识确认。
 
 **幂等保证**：
 - 已绑定且公钥匹配：返回已绑定的 group_aid 和证书
@@ -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 不可用 |
 
 **订阅**：