@agentunion/fastaun-browser 0.5.0 → 0.5.2

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

@@ -27,16 +27,17 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | [message.recall](#messagerecall) | 撤回消息 |
 | [message.query_online](#messagequery_online) | 批量查询在线状态 |
 
-### E2EE 辅助方法（SDK 内部使用）
-
-> 以下方法由 SDK E2EE 层自动调用，应用层通常无需直接使用。
-
-| 方法 | 说明 |
-|------|------|
-| message.e2ee.put_prekey | 上传/覆盖当前 AID 的 prekey 材料 |
-| message.e2ee.get_prekey | 读取目标 AID 的 prekey 材料 |
-| message.e2ee.record_replay_guard | 记录已处理消息 ID（防重放） |
-| message.e2ee.check_replay_guard | 检查消息 ID 是否已处理 |
+### E2EE V2 辅助方法（SDK 内部使用）
+
+> 以下方法由 SDK E2EE 层自动调用，应用层通常无需直接使用。
+
+| 方法 | 说明 |
+|------|------|
+| message.v2.put_peer_pk | 注册/更新当前设备的 P2P SPK（`peer_device_prekey`） |
+| message.v2.bootstrap | 拉取对端活跃设备、设备 IK/SPK、audit recipients 与 wrap 策略 |
+| message.v2.group_bootstrap | Group 服务内部批量拉取成员设备 V2 公钥 |
+
+> 旧 `message.e2ee.*` prekey/replay guard RPC 只属于 legacy E2EE 信封兼容路径；当前 SDK 主路径不再直接使用它们。新实现应使用 V2 多设备 wrap，详见 [05-E2EE加密通信](05-E2EE加密通信.md) 和 [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)。
 
 ## 事件索引
 
@@ -74,7 +75,7 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 |------|------|------|--------|------|
 | `to` | string | 是 | — | 接收方 AID |
 | `payload` | object | 是 | — | 消息内容（任意 JSON 对象） |
-| `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
+| `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
 | `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
 | `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
@@ -96,8 +97,17 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
         "message_id": "550e8400-e29b-41d4-a716-446655440000",
         "seq": 42,
         "timestamp": 1234567890000,
-        "status": "delivered",
-        "delivery_mode": "fanout"
+        "status": "delivered",
+        "delivery_mode": "fanout",
+        "envelope": {
+            "from": "alice.agentid.pub",
+            "to": "bob.agentid.pub",
+            "type": "text",
+            "timestamp": 1234567890000,
+            "encrypted": false,
+            "payload_type": "text"
+        },
+        "payload": {"type": "text", "text": "Hello!"}
     },
     "id": 1
 }
@@ -108,9 +118,11 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | `message_id` | string | 消息 ID |
 | `seq` | integer | 接收方收件箱序号 |
 | `timestamp` | integer | 服务端时间戳（毫秒） |
-| `status` | string | `"sent"` / `"delivered"` / `"duplicate"` |
-| `delivery_mode` | string | 最终生效的连接级投递语义：`fanout` 或 `queue` |
-| `cross_domain` | boolean | 仅跨域投递时出现，当前值为 `true` |
+| `status` | string | `"sent"` / `"delivered"` / `"duplicate"` |
+| `delivery_mode` | string | 最终生效的连接级投递语义：`fanout` 或 `queue` |
+| `envelope` | object | SDK 回填的发送结果信封，包含发送方、接收方、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
+| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
+| `cross_domain` | boolean | 仅跨域投递时出现，当前值为 `true` |
 | `target_issuer` | string | 仅跨域投递时出现，表示目标 issuer |
 
 > **duplicate 响应**：当 `message_id` 重复时，若服务端仍缓存首次结果，返回完整首次响应并附加 `"status": "duplicate"`；若缓存已过期，仅返回 `message_id`、`timestamp`、`status`，**不含** `seq` 和 `delivery_mode`。客户端收到 `"duplicate"` 状态时应视为幂等成功，无需重试。
@@ -141,15 +153,15 @@ result = await client.call("message.send", {
 
 写入当前发送者针对一个上下文的思考内容。它不是普通消息：不广播、不进 `message.pull`、不占用收件箱 `seq`，只通过 `message.thought.get` 主动读取。
 
-SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加密成 `e2ee.encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，则必须自行完成同等加密和签名。
+SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.p2p_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature` 和 AAD 生成；`client_signature` 按 Gateway 连接级身份语义携带。
 
-存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
+存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
 
 ### 参数
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `to` | string | 是 | P2P 会话另一方 AID，不能是 `group.{issuer}` |
+| `to` | string | 是 | P2P 会话另一方 AID，不能是群 `group_aid` |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
 | `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
@@ -175,9 +187,9 @@ await client.call("message.thought.put", {
     "to": "bob.agentid.pub",
     "context": {"type": "run", "id": "run-xxx"},
     "thought_id": "mt-...",
-    "type": "e2ee.encrypted",
-    "encrypted": true,
-    "payload": {"type": "e2ee.encrypted", "...": "..."},
+    "type": "e2ee.p2p_encrypted",
+    "encrypted": true,
+    "payload": {"type": "e2ee.p2p_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -251,7 +263,7 @@ result = await client.call("message.thought.get", {
             "to": "alice.agentid.pub",
             "payload": {"type": "thought", "text": "需要补一个边界条件"},
             "created_at": 1234567890000,
-            "e2ee": {"encryption_mode": "prekey_ecdh_v2"}
+            "e2ee": {"version": "v2", "wrap_protocol": "3DH"}
         }
     ],
     "updated_at": 1234567890000
@@ -287,7 +299,7 @@ result = await client.call("message.thought.get", {
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | `after_seq` | integer | 否 | 0 | 拉取 seq > after_seq 的消息 |
-| `limit` | integer | 否 | 100 | 单次返回上限（最大 200） |
+| `limit` | integer | 否 | 50 | 单次返回上限（最大 50；`pull_max_limit` 配置只能在 1-50 内进一步收紧） |
 | `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
 | `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
 
@@ -525,12 +537,22 @@ result = await client.call("message.ack", {"seq": 150})
     "seq": 42,
     "timestamp": 1234567890000,
     "payload": {"type": "text", "text": "Hello!"},
-    "delivery_mode": "queue",
-    "encrypted": false
+    "delivery_mode": "queue",
+    "encrypted": false,
+    "proximity": {
+        "same_device": false,
+        "same_egress_ip": true,
+        "same_network": true,
+        "basis": "egress_ip",
+        "asserted_by": "gateway"
+    },
+    "same_device": false,
+    "same_egress_ip": true,
+    "same_network": true
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。`envelope.agent_md.sender` / `envelope.agent_md.group` 是 agent.md 云端版本提示，SDK 会自动观察并写入本地 `remote_etag`。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
 
 ### 订阅
 
@@ -564,7 +586,7 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 }
 ```
 
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示撤回 tombstone / 通知自身的信封，不是被撤回原消息的信封；被撤回的原消息继续通过 `message_ids` 表达。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示撤回 tombstone / 通知自身的信封，不是被撤回原消息的信封；被撤回的原消息继续通过 `message_ids` 表达。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先读取 `envelope` 和 `message_ids`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|

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

@@ -2,7 +2,7 @@
 
 `message.send.params.payload`、`message.thought.put.params.payload`、`group.send.params.payload` 和 `group.thought.put.params.payload` 使用同一套业务负载约定。`payload` 是应用层 JSON 对象，服务端只做大小、JSON 可序列化、信封/封装类型和加密相关的必要检查；业务字段由发送端和接收端协商，服务端不按本文字段做强制校验。
 
-示例展示的是 `payload` 片段：P2P 完整请求仍需要在同级传入 `to`；群消息完整请求仍需要在同级传入 `group_id`；思考内容需要在顶层通过 `context.type + context.id` 指定 selector。文本、图片、文件、思考内容等业务消息类型只能放在 `payload.type`；`message.send.params.type` / `message.thought.put.params.type` / `group.send.params.type` / `group.thought.put.params.type` 是信封或封装类型，例如 SDK 加密发送时自动填充的 `e2ee.encrypted` / `e2ee.group_encrypted`。
+示例展示的是 `payload` 片段：P2P 完整请求仍需要在同级传入 `to`；群消息完整请求仍需要在同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；思考内容需要在顶层通过 `context.type + context.id` 指定 selector。文本、图片、文件、思考内容等业务消息类型只能放在 `payload.type`；`message.send.params.type` / `message.thought.put.params.type` / `group.send.params.type` / `group.thought.put.params.type` 是信封或封装类型，例如 SDK V2 加密发送时自动填充的 `e2ee.p2p_encrypted` / `e2ee.group_encrypted`。
 
 ## 类型总览
 
@@ -38,14 +38,14 @@
 | 字段 | 所在位置 | 说明 |
 |------|----------|------|
 | `to` | `message.send.params` | P2P 接收方 AID |
-| `group_id` | `group.send.params` 和群消息信封 | 群组 ID |
+| `group_id` | `group.send.params` 和群消息信封 | 兼容字段名；值语义为目标态 `group_aid` |
 | `context.type + context.id` | `message.thought.put/get.params` 和 `group.thought.put/get.params` | 思考内容 selector；必填，不要只放在 payload 内 |
 | `protected_headers` / `headers` | `message.send` / `message.thought.put` / `group.send` / `group.thought.put` 参数 | E2EE 信封元数据，类似 HTTP headers；推荐 `protected_headers`，`headers` 仅为兼容别名；SDK 验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 | `from` / `sender_aid` | 服务端生成的消息信封 | 发送方身份 |
 | `message_id` / `seq` / `timestamp` / `created_at` | 服务端生成或发送参数 | 当前消息 ID、序号和服务端时间 |
 | `encrypted` / `delivery_mode` | 发送参数或连接上下文 | 加密和 P2P 投递语义 |
 | `dispatch_mode` | 群消息信封和 SDK 注入的群消息 payload | 群消息应用层分发模式标签：`broadcast` / `mention`；由群设置决定，不作为 `group.send` 单次入参 |
-| `type` / `message_type` | 发送参数或消息信封 | 信封/封装类型，如 `e2ee.encrypted` / `e2ee.group_encrypted` |
+| `type` / `message_type` | 发送参数或消息信封 | 信封/封装类型，如 `e2ee.p2p_encrypted` / `e2ee.group_encrypted` |
 | `dispatch` / `duty_state` / `message_dispatch` | `group.send` 响应和群消息事件 | 群消息运行时分发状态和值班分发结果 |
 
 `protected_headers` 用于可见但需防篡改的信封元数据，例如 `device_id`、`slot_id`、`sdk_version`。它不属于业务 payload，也不提供机密性；需要端到端保密的上下文仍应放在 `payload.client_context` 或其他 payload 字段内。

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

@@ -59,7 +59,7 @@
 
 ### POSIX VFS 方法
 
-> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/mkdir/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
+> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/lstat/mkdir/touch/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
 
 | 方法 | 说明 |
 |------|------|
@@ -69,6 +69,7 @@
 | [storage.fs.stat](#storagefsstat) | 查节点（stat，跟随末级软链） |
 | [storage.fs.lstat](#storagefslstat) | 查节点（lstat，不跟随软链） |
 | [storage.fs.mkdir](#storagefsmkdir) | 建目录（mkdir） |
+| [storage.fs.touch](#storagefstouch) | 创建空文件或更新时间戳（touch） |
 | [storage.fs.remove](#storagefsremove) | 删除文件/目录/软链（rm） |
 | [storage.fs.rename](#storagefsrename) | 同 owner 内移动/改名（mv） |
 | [storage.fs.copy](#storagefscopy) | 复制对象或软链（cp） |
@@ -91,6 +92,8 @@
 ### ACL / 权限方法
 
 > 统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。
+>
+> AID storage 的 `storage.set_acl/remove_acl` 面向具体 AID，当前主要用于写/删除授权；直接读授权不通过 ACL 下发，读访问应使用 `storage.create_share_link` / `storage.get_by_share`，撤销分享使用 `storage.revoke_share_link`。`role:*` 伪主体只允许可信 group 内部门面管理，客户端不得直接对 `group_aid` 空间设置角色 ACL；群自有区 admin 写授权使用 `group.fs.set_acl/remove_acl`。
 
 | 方法 | 说明 |
 |------|------|
@@ -113,15 +116,15 @@
 
 ---
 
-> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
-
-## SDK 封装状态
-
-Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
-
-## storage.put_object
-
-上传小对象（内容 base64 编码通过 RPC 传输）。
+> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
+
+## SDK 封装状态
+
+Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`；`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+
+## storage.put_object
+
+上传小对象（内容 base64 编码通过 RPC 传输）。
 
 ### 参数
 
@@ -885,7 +888,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 ## storage.fs.list
 
-列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
+列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
 
 ### 参数
 
@@ -915,7 +918,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 ## storage.fs.find
 
-递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
+递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
 
 ### 参数
 
@@ -1014,6 +1017,36 @@ fs 目录节点视图。
 
 ---
 
+## storage.fs.touch
+
+创建空文件或刷新已有节点的修改时间（POSIX `touch`）。已存在的文件、目录或软链会更新时间戳；不存在时默认创建 0 字节私有文件；`no_create=true` 时不存在不创建并返回 `{touched:false, created:false}`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `parents` | boolean | 否 | `false` | 创建文件时是否递归创建父目录 |
+| `no_create` / `noCreate` | boolean | 否 | `false` | 目标不存在时不创建 |
+| `mtime` | integer | 否 | 当前时间 | Unix 秒或毫秒；小于 `10000000000` 按秒解释 |
+| `follow_symlinks` / `followSymlinks` | boolean | 否 | `false` | 目标为软链时是否跟随末级软链 |
+| `content_type` | string | 否 | `"application/octet-stream"` | 新建空文件的 MIME 类型 |
+| `metadata` | object | 否 | `{}` | 新建空文件的元数据 |
+| `expire_in_seconds` | integer | 否 | `0` | 新建空文件的过期秒数 |
+
+### 响应
+
+成功返回 fs 节点视图，并额外包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `touched` | boolean | 是否实际更新或创建 |
+| `created` | boolean | 是否新建了空文件 |
+
+---
+
 ## storage.fs.remove
 
 删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
@@ -1107,6 +1140,8 @@ fs 目录节点视图。
 | `mount` | object | 挂载视图 |
 | `status` | string | `active`（直接生效）/ `pending`（待批准） |
 
+> `status` 字段仅在直接调用 lowlevel RPC（`fs_mount`/`FSMount`/`fsMount` 原始返回）时可见。四语言 SDK 的高层 VFS 门面（`vfs.mount()`/`StorageVFS.Mount()`/`vfs.mount()`）会把响应解析为通用 NodeView，该视图不保留顶层 `status` 字段；需要判断是否 `pending` 时请改用 lowlevel 接口读取原始响应，或检查服务端在 `pending` 场景下额外写入的 `request_id`。
+
 ---
 
 ## storage.fs.approve
@@ -1167,7 +1202,7 @@ fs 目录节点视图。
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
-| `group_id` | string | 是 | — | 群 ID |
+| `group_id` | string | 是 | — | 群组标识兼容字段，值语义为目标态 `group_aid` |
 | `group_owner_aid` | string | 是 | — | 群 owner AID |
 | `member_aid` | string | 否 | — | 成员 AID（不传=全员） |
 | `reason` | string | 否 | `"membership_changed"` | `dissolved` / `membership_changed` |
@@ -1219,7 +1254,7 @@ fs 目录节点视图。
 
 ## storage.atomic_repoint
 
-原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
+原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
 
 ### 参数
 
@@ -1280,14 +1315,16 @@ fs 目录节点视图。
 
 ## storage.set_acl
 
-授予路径前缀 ACL grant（群内部 admin 或群代理写授权）。支持 `role:<role>` 形式 grantee。ACL 对目录前缀授权，子路径默认继承（最近祖先覆盖）。
+授予路径前缀 ACL grant。普通 AID storage 的 `grantee_aid` 必须是具体 AID，主要用于授予写/删除权限；子路径默认继承（最近祖先覆盖）。读取不通过 AID ACL 直接授权，应用应改用 `storage.create_share_link` 并在需要时用 `storage.revoke_share_link` 撤销。
+
+`role:*` 伪主体只允许可信 group 内部门面写入。客户端不能直接对 `group_aid` 空间调用 `storage.set_acl` 设置 `role:admin`；群自有区角色写授权统一使用 `group.fs.set_acl`。
 
 ### 参数
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aid` | string | 是 | — | 被授权 AID（或 `role:<role>`） |
+| `grantee_aid` | string | 是 | — | 被授权 AID；`role:*` 仅限 group 内部调用 |
 | `perms` | string | 是 | — | 权限位：`r`/`w`/`rw`/`rwx`（`rwx` 含删除） |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
@@ -1302,7 +1339,7 @@ ACL 视图。
 
 ## storage.remove_acl
 
-移除路径 ACL 授权。
+移除路径 ACL 授权。对 AID storage，这是撤销写/删除授权的入口；读分享的撤销入口是 `storage.revoke_share_link`。群自有区角色写授权撤销使用 `group.fs.remove_acl`，不要由客户端直接调用 `storage.remove_acl` 操作 `role:*`。
 
 ### 参数
 
@@ -1339,7 +1376,7 @@ ACL 视图。
 
 ## storage.set_visibility
 
-切换对象或目录的公开/私有（软链不支持）。`allow_roles` 替换 `role:` 类 ACL。
+切换对象或目录的公开/私有（软链不支持）。`allow_roles` 是低层兼容字段，不能作为群自有区 admin 写授权入口；群自有区角色写授权必须使用 `group.fs.set_acl/remove_acl`。
 
 ### 参数
 
@@ -1349,7 +1386,7 @@ ACL 视图。
 | `visibility` | string | 是 | — | `public` / `private` |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
-| `allow_roles` | array | 否 | — | 允许的角色列表（替换 role ACL） |
+| `allow_roles` | array | 否 | — | 低层兼容字段，仅表示可见性读角色；不能用于群自有区写授权 |
 
 ### 响应
 
@@ -1502,4 +1539,4 @@ token 列表（hash 摘要 + 元数据）。
 | -32004 | 权限拒绝（requester 不是对象 owner，或非公开对象的读权限不足） |
 | -32008 | 对象不存在（`ErrNotFound`） |
 | -32009 | 版本冲突（`ErrVersionConflict`，`expected_version` 与实际版本不匹配） |
-| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |
+| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -11,10 +11,10 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `AUNClient`：认证、连接、状态机、事件和 RPC。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
-
-Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
-Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区 `group_aid` 写身份、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名，详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
+
+Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
+Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
 
 ## 渐进式查阅流程
 
@@ -29,12 +29,12 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
-- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
-- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区 `group_aid` 写身份、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
-- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
+- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
+- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
-- agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`
+- agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
 - 错误处理：Result、异常、错误码、重试
 
 ### Step 3：读 Layer 3 摘要
@@ -48,9 +48,9 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
 | 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket |
 | 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
-| 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件 |
-| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE、ProtectedHeaders、密钥管理 |
-| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / ServiceProxyClient / 事件 / RPC |
+| 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件、agent.md 自动观察 |
+| 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
+| 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / agent.md / ServiceProxyClient / 事件 / RPC |
 | 07 | [错误处理](07-错误处理.md) | Result、异常、错误码、重试 |
 | 08 | [最佳实践](08-最佳实践.md) | 幂等、多 AID、资源清理、测试数据 |
 | - | [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层 |
@@ -65,14 +65,15 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
 | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
 | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
-| 发布、下载或检查 agent.md | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
+| 发布、下载、检查或排查 agent.md 远端 ETag | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
 | 查方法签名 | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区写身份、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
-| 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
-| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
+| 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
+| 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
 | 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
 | 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |
 | 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |

package/_packed_docs/sdk/E2EE_V2/346/266/210/346/201/257/351/200/232/344/277/241/346/227/266/345/272/217/345/233/276.md

@@ -7,8 +7,9 @@
 - SDK 默认 `message.send` / `group.send` 为 `encrypt=true`，由 SDK 本地构造 V2 加密 envelope。
 - 显式 `encrypt=false` 时走明文发送；V2 SDK 接收端仍通过 `message.v2.pull` / `group.v2.pull` 合并拉取明文历史行。
 - P2P 加密 envelope 类型为 `e2ee.p2p_encrypted`，通过 `message.send` 提交，服务端按 V2 分流处理。
-- GROUP 加密 envelope 类型为 `e2ee.group_encrypted`，通过 `group.v2.send` 提交。
-- 服务端只做认证、路由、结构校验、密文存储和事件通知，不持有明文 payload，也不执行端到端解密。
+- GROUP 加密 envelope 类型为 `e2ee.group_encrypted`，通过 `group.v2.send` 提交。
+- 服务端只做认证、路由、结构校验、密文存储和事件通知，不持有明文 payload，也不执行端到端解密。
+- 图中的 `group_id` 是 RPC 兼容参数名，传值语义均为规范化后的 `group_aid`（`{base}.{issuer}`）。
 
 ## V2 设备密钥注册
 

package/_packed_docs/sdk/INDEX.md

@@ -11,20 +11,20 @@
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
 | [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE |
-| [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 网关发现 · 事件 · agent.md |
-| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 消息 · ProtectedHeaders · 密钥管理 · 高级存储 |
+| [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 网关发现 · 事件 · agent.md 自动观察 |
+| [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE V2 消息 · ProtectedHeaders · agent.md 版本提示 · recipient wrap |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
-| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 事件 · E2EE 高级 API · RPC 索引 |
+| [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 事件 · agent.md · E2EE 高级 API · RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
 | [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
-| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group.fs.*` 群文件系统 RPC、群自有区写身份和 `parents` 语义） |
-| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
-| [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
-| [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | 下一版 `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区写身份、`parents` 和 JS string 语义 |
-| [group.fs POSIX 化分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md) | group.fs 重构的 IPO、Step-by-step、用例集、Checklist、验收和回滚 |
-| [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、服务端分层、类 Linux 权限、mount/symlink 与关键时序 |
+| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group_aid` / `group_id` 兼容规范、`group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
+| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
+| [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
+| [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区角色 ACL、`parents` 和 JS string 语义 |
+| [group.fs POSIX 化分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md) | group.fs 重构的 IPO、Step-by-step、用例集、Checklist、验收和回滚 |
+| [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、服务端分层、类 Linux 权限、mount/symlink 与关键时序 |
 | [09-meta-rpc-manual](09-meta-rpc-manual.md) | meta RPC 和信任根 |
 | [09-stream-rpc-manual](09-stream-rpc-manual.md) | stream RPC |
 | [09-proxy-rpc-manual](09-proxy-rpc-manual.md) | Service Proxy 控制面 RPC 和数据面隧道注册 |
@@ -37,9 +37,10 @@
 
 ### 身份与认证
 
-- AID 格式、证书、不可变值对象 → [03-核心概念](03-核心概念.md)
-- `AIDStore.register()` / `load()` / `exists()` / `resolve()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
-- AID 构造约束与多语言入口 → [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md)
+- AID 格式、证书、不可变值对象 → [03-核心概念](03-核心概念.md)
+- `AIDStore.register()` / `load()` / `exists()` / `resolve()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
+- agent.md 上传/下载/检查、`remote_etag` / `last_modified` 自动观察、`requester` / `peer` / `group` 角色 → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[远程 agent.md 缓存与 ETag 透传方案](../agent.md/远程agent.md缓存与etag透传方案.md)
+- AID 构造约束与多语言入口 → [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md)
 - 认证链路和 token → [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md)
 - AID 托管恢复 / 跨设备复制 → [09-custody-api-manual](09-custody-api-manual.md)
 
@@ -53,7 +54,7 @@
 ### E2EE
 
 - E2EE 原理和默认行为 → [03-核心概念](03-核心概念.md)
-- ProtectedHeaders、prekey、replay guard → [05-E2EE加密通信](05-E2EE加密通信.md)
+- ProtectedHeaders、agent.md 版本提示边界、V2 recipient wrap、sender_signature / AAD / recipient proof → [05-E2EE加密通信](05-E2EE加密通信.md)
 - V2 P2P/GROUP 时序 → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
 - 高级 E2EE API → [06-API手册](06-API手册.md)
 - 解密失败排查 → [07-错误处理](07-错误处理.md)
@@ -62,12 +63,12 @@
 
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
-- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
-- Group RPC 与群文件系统 `group.fs.*` 控制面、群自有区写身份和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
-- 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
-- Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
-- Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
-- Collab RPC（`collab.*` 版本化文档、乐观锁、标签、GC、reflog、revert）→ [09-collab-rpc-manual](09-collab-rpc-manual.md)
+- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
+- Group RPC、`group_aid` / `group_id` 兼容规范、群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
+- 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
+- Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
+- Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / `storage.fs.touch` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
+- Collab RPC（`collab.*` 版本化文档、乐观锁、标签、GC、reflog、revert）→ [09-collab-rpc-manual](09-collab-rpc-manual.md)
 - Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
 - Stream RPC → [09-stream-rpc-manual](09-stream-rpc-manual.md)
 - Service Proxy RPC 和隧道注册 → [09-proxy-rpc-manual](09-proxy-rpc-manual.md)
@@ -98,15 +99,15 @@
 
 ### 04-连接与认证
 
-描述 `AIDStore` 注册加载、`AUNClient` 身份加载、显式认证、连接选项、长短连接共存、网关发现、agent.md 和 RPC 调用。
+描述 `AIDStore` 注册加载、`AUNClient` 身份加载、显式认证、连接选项、长短连接共存、网关发现、agent.md 上传/下载/检查，以及连接后从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 自动观察远端版本。
 
 ### 05-E2EE加密通信
 
-覆盖默认加密发送、接收自动解密、ProtectedHeaders、prekey、群 E2EE、replay guard 和高级存储扩展边界。
+覆盖默认加密发送、接收自动解密、E2EE V2 多设备 wrap、ProtectedHeaders、agent.md 版本提示与 E2EE 安全边界、`sender_signature` / AAD / recipient proof、群 E2EE 和高级存储扩展边界。
 
 ### 06-API手册
 
-列出 AIDStore、AID、AUNClient、事件、ServiceProxyClient、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
+列出 AIDStore、AID、AUNClient、事件、agent.md、ServiceProxyClient、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
 
 ### 07-错误处理
 
@@ -118,7 +119,7 @@
 
 ### 09-*-rpc-manual
 
-各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
+各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
 
 ### AUN Storage架构设计
 
@@ -126,7 +127,7 @@
 
 ### 09-collab-rpc-manual
 
-定义协作层 `collab.*` RPC（共 21 个）：文档版本线（ls-files/create/show/commit/merge/log/diff/revert/prune）、运维备份迁移（gc/reflog/clone）、目录级标签（tag.create/list/show/diff/restore/rm/prune）、群内发现（ls-remote/unregister）。collab 编排并入 storage 服务进程，以调用者身份直调 storage 原语，授权下沉到 storage ACL。涵盖乐观锁 CAS commit 撞版本响应、三方合并冲突标记、forward-only 标签回滚、垃圾扫描和审计日志语义。
+定义协作层 `collab.*` RPC（共 21 个）：文档版本线（ls-files/create/show/commit/merge/log/diff/revert/prune）、运维备份迁移（gc/reflog/clone）、目录级标签（tag.create/list/show/diff/restore/rm/prune）、群内发现（ls-remote/unregister）。collab 编排并入 storage 服务进程，以调用者身份直调 storage 原语，授权下沉到 storage ACL。涵盖乐观锁 CAS commit 撞版本响应、三方合并冲突标记、forward-only 标签回滚、垃圾扫描和审计日志语义。
 
 ### 09-proxy-rpc-manual
 

package/_packed_docs/sdk/Notify/351/200/232/347/237/245/346/226/271/346/241/210.md

@@ -41,9 +41,11 @@
 ```python
 await client.notify("notification/client.activity", {"state": "idle"})
 await client.notify("event/app.typing", {"thread_id": "t1"}, to="bob.agentid.pub", ttl_ms=5000)
-await client.notify("event/app.presence", {"state": "active"}, group_id="group.agentid.pub/123")
+await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc123.agentid.pub")
 ```
 
+> `group_id` 是兼容参数名，传值应使用目标态 `group_aid`。
+
 `await client.notify(...)` 只表示 SDK 已尝试把 Notification 帧写入当前 WebSocket，不表示服务端接受、目标在线或对端收到。
 
 ## 路由模型
@@ -119,10 +121,12 @@ Gateway 校验发送方认证上下文、payload 大小、TTL、方法名前缀
 
 ### 4. 群在线转发
 
-指定 `group_id` 时，SDK 发送 `notification/group.route`。Gateway 调用 Group 服务解析目标成员，Group 服务负责校验成员身份、群状态和权限；Gateway 只按 Group 服务返回的成员 AID 做在线 fanout。
+指定 `group_id` 时，SDK 发送 `notification/group.route`。这里的 `group_id` 是兼容参数名，值使用目标态 `group_aid`。Gateway 调用 Group 服务解析目标成员，Group 服务负责校验成员身份、群状态和权限；Gateway 只按 Group 服务返回的成员 AID 做在线 fanout。
 
 群成员包含外域 AID 时，Gateway 会按成员 AID issuer 做 federation 转发。Gateway 不直接跨域解析远端 `group_id`，群权限仍以 Group 服务返回的目标成员集合为准。
 
+Gateway 在线推送 notify / event 时会复用 agent.md 元数据注入机制：缓存命中且未被节流时，`_meta.agent_md_etags.group` 表示群自身 `group_aid` / `group_id` 的 agent.md 版本，SDK 会自动观察并更新本地 `remote_etag`。
+
 ## 在线投递规则
 
 - `to=aid`：默认投递该 AID 的所有在线长连接设备。

package/dist/agent-md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-md.d.ts","sourceRoot":"","sources":["../src/agent-md.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-md.d.ts","sourceRoot":"","sources":["../src/agent-md.ts"],"names":[],"mappings":"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"}