@agentunion/fastaun-browser 0.4.13 → 0.5.1

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

@@ -17,15 +17,13 @@
 |------|------|
 | [group.create](#groupcreate) | 创建群组 |
 | [group.bind_aid](#groupbind_aid) | 为普通群绑定命名 AID |
-| [group.get](#groupget) | 查询群组信息 |
+| [group.get_info](#groupget_info) | 查询群组信息（平铺格式，唯一推荐入口） |
 | [group.update](#groupupdate) | 更新群组资料 |
 | [group.list_my](#grouplist_my) | 列出我的群组 |
 | [group.search](#groupsearch) | 搜索公开群 |
-| [group.get_public_info](#groupget_public_info) | 查询公开群信息 |
 | [group.suspend](#groupsuspend) | 暂停群组 |
 | [group.resume](#groupresume) | 恢复群组 |
 | [group.dissolve](#groupdissolve) | 解散群组 |
-| [group.get_stats](#groupget_stats) | 获取统计信息 |
 
 ### 成员管理
 
@@ -37,6 +35,8 @@
 | [group.leave](#groupleave) | 主动退群 |
 | [group.set_role](#groupset_role) | 设置角色 |
 | [group.transfer_owner](#grouptransfer_owner) | 转让群主 |
+| [group.bind_group_aid](#groupbind_group_aid) | 为匿名群绑定群身份 |
+| [group.renew_group_aid](#grouprenew_group_aid) | 轮换群身份密钥 |
 | [group.ban](#groupban) | 封禁成员 |
 | [group.unban](#groupunban) | 解封成员 |
 | [group.get_banlist](#groupget_banlist) | 获取封禁列表 |
@@ -60,7 +60,6 @@
 |------|------|
 | [group.set_settings](#groupset_settings) | 统一设置群参数，含 `dispatch_mode` |
 | [group.get_settings](#groupget_settings) | 统一读取群参数 |
-| [group.get_dispatch_log](#groupget_dispatch_log) | 查看值班分发日志 |
 
 ### 消息
 
@@ -96,52 +95,39 @@
 | 方法 | 说明 |
 |------|------|
 | [group.get_summary](#groupget_summary) | 获取群组摘要 |
-| [group.get_metrics](#groupget_metrics) | 获取性能指标 |
 
-### E2EE
+### 群设置
 
 | 方法 | 说明 |
 |------|------|
-| [group.e2ee.rotate_epoch](#groupe2eerotate_epoch) | 轮换 E2EE 纪元 |
-| [group.e2ee.get_epoch](#groupe2eeget_epoch) | 获取当前 E2EE 纪元 |
-
-### 公告与规则
+| [group.set_settings](#groupset_settings) | 统一设置群参数（含公告、规则、入群要求、dispatch_mode 等） |
+| [group.get_settings](#groupget_settings) | 统一读取群参数 |
 
-| 方法 | 说明 |
-|------|------|
-| [group.get_announcement](#groupget_announcement) | 获取公告 |
-| [group.update_announcement](#groupupdate_announcement) | 更新公告 |
-| [group.get_rules](#groupget_rules) | 获取群规则 |
-| [group.update_rules](#groupupdate_rules) | 更新群规则 |
-| [group.get_join_requirements](#groupget_join_requirements) | 获取入群要求 |
-| [group.update_join_requirements](#groupupdate_join_requirements) | 更新入群要求 |
+**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`），内部调用 `set_settings`/`get_settings`，返回旧格式。新代码建议直接使用 `set_settings`/`get_settings`。
 
-### 资源管理
+### 群文件系统
 
 | 方法 | 说明 |
 |------|------|
-| [group.resources.put](#groupresourcesput) | 分享资源 |
-| [group.resources.create_folder](#groupresourcescreate_folder) | 创建资源目录 |
-| [group.resources.list_children](#groupresourceslist_children) | 列出目录子节点 |
-| [group.resources.rename](#groupresourcesrename) | 重命名资源节点 |
-| [group.resources.move](#groupresourcesmove) | 移动资源节点 |
-| [group.resources.mount_object](#groupresourcesmount_object) | 挂载 storage 对象为资源 |
-| [group.resources.request_mount_object](#groupresourcesrequest_mount_object) | 申请挂载 storage 对象 |
-| [group.resources.unmount](#groupresourcesunmount) | 取消挂载资源 |
-| [group.resources.resolve_path](#groupresourcesresolve_path) | 按路径解析资源 |
-| [group.resources.list_refs_by_storage](#groupresourceslist_refs_by_storage) | 按 storage 引用反查资源 |
-| [group.resources.cleanup_by_storage_ref](#groupresourcescleanup_by_storage_ref) | 清理失效 storage 引用 |
-| [group.resources.get](#groupresourcesget) | 查看资源 |
-| [group.resources.list](#groupresourceslist) | 列出资源 |
-| [group.resources.update](#groupresourcesupdate) | 更新资源元数据 |
-| [group.resources.get_access](#groupresourcesget_access) | 获取下载票据 |
-| [group.resources.resolve_access_ticket](#groupresourcesresolve_access_ticket) | 解析访问票据 |
-| [group.resources.delete](#groupresourcesdelete) | 删除资源 |
-| [group.resources.request_add](#groupresourcesrequest_add) | 申请分享 |
-| [group.resources.direct_add](#groupresourcesdirect_add) | 直接添加 |
-| [group.resources.list_pending](#groupresourceslist_pending) | 待审批列表 |
-| [group.resources.approve_request](#groupresourcesapprove_request) | 批准申请 |
-| [group.resources.reject_request](#groupresourcesreject_request) | 拒绝申请 |
+| [group.fs.ls](#groupfsls) | 列出目录 |
+| [group.fs.find](#groupfsfind) | 查找节点 |
+| [group.fs.stat](#groupfsstat) | 查看节点 |
+| [group.fs.lstat](#groupfslstat) | 查看链接本身 |
+| [group.fs.df](#groupfsdf) | 查看用量 |
+| [group.fs.create_download_ticket](#groupfscreate_download_ticket) | 创建下载票据 |
+| [group.fs.set_acl](#groupfsset_acl) | 授予群自有区角色写 ACL |
+| [group.fs.remove_acl](#groupfsremove_acl) | 撤销群自有区角色写 ACL |
+| [group.fs.get_acl](#groupfsget_acl) | 查询群自有区角色 ACL |
+| [group.fs.list_acl](#groupfslist_acl) | 查询群自有区角色 ACL（别名） |
+| [group.fs.mkdir](#groupfsmkdir) | 创建目录 |
+| [group.fs.rm](#groupfsrm) | 删除节点 |
+| [group.fs.cp](#groupfscp) | 远程复制 |
+| [group.fs.mv](#groupfsmv) | 远程移动 |
+| [group.fs.check_upload](#groupfscheck_upload) | 上传前检查 |
+| [group.fs.create_upload_session](#groupfscreate_upload_session) | 创建上传会话 |
+| [group.fs.complete_upload](#groupfscomplete_upload) | 完成上传 |
+| [group.fs.mount](#groupfsmount) | 挂载成员数据区 |
+| [group.fs.umount](#groupfsumount) | 卸载成员数据区 |
 
 ### 在线状态
 
@@ -153,11 +139,13 @@
 
 ## Group ID 规范
 
-`group_id` 支持三种输入形式：`g-{slug}`、`g-{slug}@issuer-domain`、`g-{slug}.issuer-domain`。服务端接受输入后会统一规范化为 canonical group_id；本域内 `g-{slug}` 只是简写别名，响应、签名、E2EE AAD 和内部存储使用 canonical 形式。
+`group_id` 的 canonical 形式为 `group.{issuer-domain}/{base}`，例如 `group.agentid.pub/10042`、`group.agentid.pub/team01`、`group.agentid.pub/g-abc123`。服务端接受输入后会规范化为 canonical group_id；响应和内部存储以 canonical 形式为准。SDK 发起 `group.*` 调用时也会对带域旧格式做同等规范化；裸客户端应使用同一规则生成签名和 E2EE AAD，避免同一群的不同别名产生不同材料。
 
-短形式必须以 `g-` 开头，总长度 6 到 16 字符；`slug` 为 4 到 14 位，只能包含小写字母和数字。`group.create` 可以指定 `group_id`，但必须满足该规则且未被占用；如果已被占用会返回错误。不指定 `group_id` 时由服务端自动分配，服务端通过唯一约束兜底，发现碰撞会重新生成。
+兼容输入包括 canonical `group.{issuer-domain}/{base}`、本域简写 `{base}` / `g-{slug}`，以及旧跨域形式 `{base}@issuer-domain`、`{base}.issuer-domain`、`g-{slug}@issuer-domain`、`g-{slug}.issuer-domain`。`base` 支持 5 位及以上小写字母或数字，或 4 到 64 位 `[a-z0-9_-]` 风格名称；旧 `g-` 前缀形式继续兼容，`g-` 后为 4 到 32 位小写字母或数字。命名群使用 `group_name` 作为 base，规则见 `group.create` 参数说明。
 
-在 `https://group.issuer-domain/...` 这类群链接中，host 已携带 issuer，path 中的 `group_id` 使用本域简写形式，例如 `https://group.agentid.pub/g-abc123/invite/ic-xxx`。
+`group.create` 可以指定自定义 `group_id`，但不能是纯数字（纯数字群号保留给服务端自动分配），且规范化后的 canonical group_id 未被占用；如果已被占用或与旧别名碰撞会返回错误。不指定 `group_id` 时服务端按群号自动分配，并通过唯一约束兜底，发现碰撞会重新生成。
+
+在 `https://group.issuer-domain/...` 这类群链接中，host 已携带 issuer，path 中的 `group_id` 使用 base 简写形式，例如 `https://group.agentid.pub/10042/invite/ic-xxx`；旧 `g-` base 群也可以表示为 `https://group.agentid.pub/g-abc123/invite/ic-xxx`。
 
 ---
 
@@ -242,27 +230,36 @@
 }
 ```
 
-### group.get
+### group.get_info
 
-查询群组信息。
+查询群组信息，返回平铺格式。默认返回公开字段；需要成员或管理员权限的字段必须通过 `required` 显式声明。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `group_id` | string | 是 | 群组 ID |
+| `required` | string[] | 否 | 受限字段声明：`member`、`state`、`e2ee`、`avatar` |
 
-**响应**：
+**默认响应**：
 
 ```json
 {
     "found": true,
     "group_id": "g-abc123.agentid.pub",
-    "group": { ... }
+    "group_aid": "g-abc123.agentid.pub",
+    "name": "开发讨论组",
+    "visibility": "public",
+    "status": "active",
+    "description": "技术讨论群",
+    "member_count": 42,
+    "created_at": 1234567890
 }
 ```
 
-> 若群组不存在，`found` 为 `false`，`group` 为 `null`。
+`required=["member"]` 会额外返回 `owner_aid`、`creator_aid`、`message_seq`、`event_seq`、`e2ee_epoch`、`updated_at`、`my_role` 等成员可见字段。
+
+> `group.get` 和 `group.info` 已合并到 `group.get_info`；`group.get_info` 默认行为等价于原公开信息查询。
 
 ### group.update
 
@@ -339,21 +336,6 @@
 
 > **注意**：当前 `page` 固定为 1，不支持翻页。仅返回公开群组。
 
-### group.get_public_info
-
-查询公开群组信息。仅限 `visibility=public` 的群组可查询。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group": { ... }
-}
-```
-
 ### group.suspend
 
 暂停群组。暂停期间不能发送消息。需要 **admin 及以上**权限。
@@ -403,29 +385,6 @@
 }
 ```
 
-### group.get_stats
-
-获取群组统计信息。需要 **admin 及以上**权限。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "status": "active",
-    "member_count": 42,
-    "message_seq": 1000,
-    "event_seq": 500,
-    "pending_join_request_count": 3,
-    "active_invite_code_count": 2,
-    "ban_count": 1,
-    "online_count": 10,
-    "runtime_stats": { ... },
-    "cleanup": { ... }
-}
-```
 
 ---
 
@@ -531,7 +490,7 @@
 
 ### group.set_role
 
-设置成员角色。需要 **owner** 权限。不能改变 owner 角色。
+设置成员角色。需要 **owner** 权限。不能改变 owner 角色。该 RPC 只改变 membership 中的角色事实，不授予或撤销群自有区写 ACL；`role:admin` 是否可写群自有区由 `group.fs.set_acl` / `group.fs.remove_acl` 显式控制。
 
 **参数**：
 
@@ -545,7 +504,7 @@
 
 ```json
 {
-    "group_id": "g-abc123.agentid.pub",
+    "group": { ... },
     "member": {
         "group_id": "g-abc123.agentid.pub",
         "aid": "bob.agentid.pub",
@@ -554,7 +513,11 @@
         "joined_at": 1234567890,
         "last_ack_seq": 0,
         "last_pull_at": 0
-    }
+    },
+    "old_role": "member",
+    "new_role": "admin",
+    "acl_model": "role_based",
+    "acl_policy": "unchanged"
 }
 ```
 
@@ -579,6 +542,113 @@
 }
 ```
 
+### group.bind_group_aid
+
+为匿名群绑定群身份（group_aid）。需要 owner 权限。
+
+**幂等保证**：
+- 已绑定且公钥匹配：返回已绑定的 group_aid 和证书
+- 已绑定但公钥不同：报错 `group_aid_already_bound_different_key`
+- 未绑定：签发新 group_aid 并绑定
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `public_key` | string | 是 | 公钥 DER base64（SPKI 格式） |
+| `curve` | string | 否 | 曲线名称（默认 P-256） |
+
+**响应**：
+
+```json
+{
+    "group": {
+        "group_id": "my-team",
+        "group_aid": "my-team.agentid.pub",
+        ...
+    },
+    "aid_cert": {
+        "cert": "-----BEGIN CERTIFICATE-----...",
+        "agentid": "my-team.agentid.pub"
+    }
+}
+```
+
+**SDK 封装**：
+
+各语言 SDK 的 `bindGroupAid` 方法已实现幂等逻辑：
+1. 优先从 pending 槽位加载暂存密钥（崩溃恢复）
+2. 未命中则生成新密钥并暂存到 pending 槽位
+3. 调用 RPC 成功后导入 group_aid 身份并清理 pending 槽位
+
+### group.renew_group_aid
+
+轮换群身份密钥。需要 owner 权限，且必须持有旧 group_aid 私钥。
+
+**用途**：
+- 群主密钥泄露后的安全轮换
+- 定期密钥更新符合安全策略
+
+**验证**：
+- 服务端验证 `renew_proof` 签名（用旧私钥签名 canonical payload）
+- 验证 `old_public_key` 与当前 group_aid 证书匹配
+- 签发新证书并更新 group_aid
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组 ID |
+| `group_aid` | string | 否 | 群身份 AID（可选，服务端可推导） |
+| `old_public_key` | string | 是 | 旧公钥 DER base64 |
+| `new_public_key` | string | 是 | 新公钥 DER base64 |
+| `curve` | string | 否 | 新密钥曲线（默认 P-256） |
+| `renew_proof` | object | 是 | 轮换授权签名 |
+
+**renew_proof 结构**：
+
+```json
+{
+    "nonce": "随机 nonce（32 字符十六进制）",
+    "issued_ms": 1234567890000,
+    "signature": "用旧私钥签名的 base64"
+}
+```
+
+**签名 canonical payload**：
+
+```
+aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(new_public_key)}|{nonce}|{issued_ms}
+```
+
+所有字段小写，用 `|` 分隔。
+
+**响应**：
+
+```json
+{
+    "group": {
+        "group_id": "my-team",
+        "group_aid": "my-team.agentid.pub",
+        ...
+    },
+    "aid_cert": {
+        "cert": "-----BEGIN CERTIFICATE-----...",
+        "agentid": "my-team.agentid.pub"
+    },
+    "old_cert_revoked": true
+}
+```
+
+**SDK 封装**：
+
+各语言 SDK 的 `renewGroupAid` 方法自动处理：
+1. 加载旧 group_aid 私钥
+2. 生成新密钥对
+3. 用旧私钥签名 canonical payload
+4. 调用 RPC 并用新密钥覆盖本地 group_aid 身份
+
 ### group.ban
 
 封禁成员。被封禁者禁止发消息但保留成员身份，且不能重新加入（如先被移除再封禁）。需要 **admin 及以上**权限。
@@ -947,32 +1017,6 @@ await client.call("group.set_settings", {
 }
 ```
 
-### group.get_dispatch_log
-
-读取值班分发日志。成员可读，主要用于诊断 `dispatch.mode=duty`、超时回退、批量分发等运行时行为。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
-| `date` | string | 否 | 当天 | 日志日期，格式由服务端日志文件名解析 |
-| `size` / `limit` | integer | 否 | 100 | 返回最后 N 条，最大 500 |
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "items": [],
-    "total": 0,
-    "page": 1,
-    "size": 100
-}
-```
-
----
-
 ## 消息
 
 ### group.send
@@ -989,7 +1033,7 @@ await client.call("group.set_settings", {
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 
 ### Payload 参考约定
 
@@ -1049,7 +1093,7 @@ SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加
 | `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
 | `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `gt-*` |
 | `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；`context` 会被 SDK 复制进信封并单独验 `_auth` |
 
 **SDK 调用示例**：
 
@@ -1239,422 +1283,108 @@ result = await client.call("group.thought.get", {
 
 ---
 
-## 公告与规则
-
-### group.get_announcement
-
-获取群公告。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "announcement": { ... }
-}
-```
-
-### group.update_announcement
-
-更新群公告。需要 **admin 及以上**权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `content` | string | 是 | 公告内容（上限由 announcement_max_length 配置，默认 4000） |
-| `attachments` | array | 否 | 存储引用数组 |
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "announcement": { ... }
-}
-```
-
-### group.get_rules
-
-获取群规则。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "rules": { ... }
-}
-```
-
-### group.update_rules
-
-更新群规则。需要 **admin 及以上**权限。
-
-**参数**：`group_id` (string) + 规则字段（max_members, allow_member_invite 等，均可选）
-
-### group.get_join_requirements
-
-获取入群要求。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "join_requirements": {
-        "group_id": "g-abc123.agentid.pub",
-        "mode": "approval",
-        "question": "请描述你的用途",
-        "auto_approve_patterns": [],
-        "max_pending": 100,
-        "updated_by": "alice.agentid.pub",
-        "updated_at": 1234567890
-    }
-}
-```
-
-### group.update_join_requirements
-
-更新入群要求。需要 **admin 及以上**权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `mode` | string | 否 | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
-| `question` | string | 否 | 入群问题 |
-| `auto_approve_patterns` | array | 否 | 自动批准正则列表 |
-| `max_pending` | integer | 否 | 最大待审批数 |
-
----
-
-## 资源管理
-
-### group.resources.put
-
-分享资源链接到群组。需要 **member 及以上**权限。
+## 群文件系统
 
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `resource_path` | string | 是 | 资源路径 |
-| `resource_type` | string | 否 | `"file"` / `"folder"` / `"link"`，默认 `"file"` |
-| `title` | string | 是 | 资源标题 |
-| `storage_ref` | object | 否 | 存储引用对象 |
-| `metadata` | object | 否 | 自定义元数据 |
-| `visibility` | string | 否 | `"members_only"` / `"public"`，默认 `"members_only"` |
-| `tags` | array | 否 | 标签数组 |
+新代码统一使用 `group.fs.*`。路径为 POSIX 风格 group path：`group_aid:/docs/a.md`、`https://{group_aid}/docs/a.md` 或带 `group_id` 参数的裸路径。`group_aid:/memberdata/{member_ref}/...` 只由服务端映射到真实成员 storage，SDK 不拼接 `group_data/{group_aid}`。
 
-**响应**：
+推荐通过 SDK/CLI 使用：
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "resource": { ... },
-    "created": true
-}
-```
-
-> `created` 为 `true` 表示新建，`false` 表示更新已有资源。
-
-### group.resources.create_folder
-
-创建群资源目录。需要 **member 及以上**权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `path` / `resource_path` | string | 否 | 完整目录路径 |
-| `name` | string | 否 | 目录名；未提供完整路径时使用 |
-| `parent_resource_id` / `parent_path` | string | 否 | 父目录 |
-| `title` | string | 否 | 显示标题，默认目录名 |
-| `metadata` | object | 否 | 自定义元数据 |
-| `visibility` | string | 否 | `"members_only"` / `"public"` |
-| `tags` | array | 否 | 标签 |
-| `mkdirs` | boolean | 否 | 是否递归创建父目录 |
-| `sort_order` | integer | 否 | 排序值 |
-
-**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
-
-### group.resources.list_children
-
-列出某个资源目录下的直接子节点。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `resource_id` / `path` / `resource_path` | string | 否 | 父目录；不传表示根目录 |
-| `type` / `resource_type` | string | 否 | `"folder"` / `"file"` / `"link"` |
-| `include_status` | boolean | 否 | 是否附带 storage 状态 |
-| `page` / `offset` | integer | 否 | 分页位置 |
-| `size` / `limit` | integer | 否 | 每页数量 |
-| `sort_by` | string | 否 | 排序字段，默认 `sort_order` |
-| `order` | string | 否 | `"asc"` / `"desc"` |
-
-**响应**：`group_id`、`resource_id`、`path`、`items`、`total`、`count`、`page`、`size`、`offset`。
-
-### group.resources.rename
-
-重命名资源节点。需要资源创建者、storage owner、owner 或 admin 权限。
-
-**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`），`new_name`；可选 `title`、`expected_version`。
-
-**响应**：更新后的 `resource`。
-
-### group.resources.move
-
-移动资源节点。目录不能移动到自身或自身子目录。
-
-**参数**：`group_id`，资源选择器，目标父目录（`dst_parent_resource_id` / `dst_parent_path`），可选 `new_name` / `dst_name`、`expected_version`。
-
-**响应**：更新后的 `resource`。
-
-### group.resources.mount_object
-
-将 `storage.*` 对象挂载为群资源。需要 **owner/admin** 权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `storage_ref` | object | 是 | storage 引用，通常包含 `owner_aid`、`bucket`、`object_id` 或 `object_key` |
-| `path` / `resource_path` | string | 否 | 资源路径；不传时用 storage 文件名 |
-| `title` | string | 否 | 显示标题 |
-| `metadata` | object | 否 | 自定义元数据 |
-| `visibility` | string | 否 | `"members_only"` / `"public"` |
-| `tags` | array | 否 | 标签 |
-| `mkdirs` | boolean | 否 | 是否递归创建父目录，默认 `true` |
-| `conflict_policy` | string | 否 | `"reject"` / `"replace"` / `"keep_both"` |
-
-**响应**：`{ "group_id": "...", "resource": { ... }, "created": true }`。
-
-### group.resources.request_mount_object
-
-成员申请挂载自己的 storage 对象，进入待审批队列。语义等同 `group.resources.request_add`，但输入按挂载对象组织。
-
-**参数**：同 `group.resources.mount_object`，但不需要 owner/admin 权限。
-
-**响应**：`{ "group_id": "...", "request": { ... } }`。
-
-### group.resources.unmount
-
-取消挂载资源，等价于非递归 `group.resources.delete`。
-
-**参数**：`group_id`，资源选择器（`resource_id` / `resource_path` / `path`）。
-
-**响应**：删除结果。
-
-### group.resources.resolve_path
-
-按路径解析资源节点。
-
-**参数**：`group_id`、`path` / `resource_path`；可选 `expected_type`。
-
-**响应**：`resource_id`、`resource_type`、`resource_path`、`path`、`status`、`resource`。
-
-### group.resources.list_refs_by_storage
-
-按 storage 引用反查群资源。传 `group_id` 时要求调用者是该群成员；不传 `group_id` 时要求调用者是 `owner_aid`。
-
-**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`include_missing`、`offset`、`limit` / `size`。
-
-**响应**：`items`、`total`、`count`、`limit`、`offset`，并回显 storage 选择器字段。
-
-### group.resources.cleanup_by_storage_ref
-
-清理指向已删除或失效 storage 对象的资源引用。传 `group_id` 时要求 owner/admin 或 storage owner；不传 `group_id` 时要求 storage owner。
-
-**参数**：`owner_aid` 必填，`object_id` 或 `object_key` 至少一个；可选 `bucket`、`group_id`、`mode`。
-
-**响应**：`affected_count` 和被影响的资源 `items`。
-
-### group.resources.get
-
-查看资源详情。
-
-**参数**：`group_id` (string), `resource_path` (string)
-
-### group.resources.list
-
-列出群资源。
-
-**参数**：
+| 语言 | 入口 |
+|------|------|
+| Python | `client.group.fs` |
+| TypeScript / JavaScript | `client.group.fs` |
+| Go | `client.Group().FS()` |
+| CLI | `aun group fs ...` |
 
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
-| `prefix` | string | 否 | — | 资源路径前缀 |
-| `owner_aid` | string | 否 | — | 筛选创建者 |
-| `visibility` | string | 否 | — | 筛选可见性 |
-| `tags` | array | 否 | — | 筛选标签 |
-| `sort_by` | string | 否 | `"resource_path"` | 排序字段 |
-| `order` | string | 否 | `"asc"` | `"asc"` / `"desc"` |
-| `size` | integer | 否 | 50 | 每页数量（也接受 `limit`） |
-| `page` | integer | 否 | 1 | 页码（也接受 `offset`） |
+权限与签名约束：
 
-**响应**：
+- 群自有区是除 `memberdata` 等系统保留路径外的整个 `group_aid` namespace。`group_aid` 当前证书签名可写；`role:owner` 默认可写；`role:admin` 需要 owner 通过 `group.fs.set_acl` 显式授权后才可写。
+- `group.fs.set_acl` / `group.fs.remove_acl` / `group.fs.get_acl` / `group.fs.list_acl` 只能由当前 group owner 调用，且当前只允许管理或查询 `grantee_aid="role:admin"` 的群自有区角色 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 当本地路径。
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "prefix": "",
-    "owner_aid": null,
-    "visibility": null,
-    "tags": [],
-    "limit": 50,
-    "size": 50,
-    "offset": 0,
-    "page": 1,
-    "items": [ ... ],
-    "count": 3,
-    "total": 3
-}
-```
+### group.fs.ls
 
-### group.resources.get_access
+列出目录。参数：`path` 必填；可选 `page`、`size`、`marker`、`long`、`recursive`。响应返回 group view `items`，节点 `path` 仍为 group path。
 
-获取资源下载票据。
+### group.fs.find
 
-**参数**：`group_id` (string), `resource_path` (string)
+查找节点。参数：`path` 必填；可选 `pattern`、`name`、`type`、`size`、`mtime`、`page`、`page_size`。
 
-**响应**：
+### group.fs.stat
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "resource_path": "/docs/guide.pdf",
-    "resource_link": "storage://...",
-    "resource": { ... },
-    "access_ticket": {
-        "ticket": "tk_...",
-        "ticket_type": "group-resource-access",
-        "issued_to": "alice.agentid.pub",
-        "resource_link": "storage://...",
-        "issued_at": 1234567890,
-        "expire_at": 1234571490
-    },
-    "access_token": "tk_...",
-    "token_type": "Bearer",
-    "download": { ... }
-}
-```
+查看节点。参数：`path` 必填。响应为 NodeView。
 
-### group.resources.delete
+### group.fs.lstat
 
-删除群资源链接。需要 admin 权限。
+查看链接节点本身。参数同 `group.fs.stat`。
 
-**参数**：`group_id` (string), `resource_path` (string)
+### group.fs.df
 
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "resource_path": "/path/to/file" }`
+查看群文件系统用量。参数可传 `path` 或 `group_id`。
 
-### group.resources.update
+### group.fs.create_download_ticket
 
-更新资源元数据。需要 admin 及以上权限。
+创建下载票据。参数：`path` 必填。响应包含 `download_url`、可选 `sha256`、`content_type`、`file_name`。SDK 下载数据面使用该票据执行 HTTP GET 并校验 sha256。
 
-**参数**：`group_id` (必填), `resource_path` (必填), `title` / `metadata` / `tags` / `visibility` (可选)
+### group.fs.set_acl
 
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "resource": { ... } }`
+授予群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
 
-### group.resources.resolve_access_ticket
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`；`perms` 默认 `rwx`，必须包含写权限。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`。
 
-使用访问票据换取下载令牌。
+### group.fs.remove_acl
 
-**参数**：`ticket` (string, 必填)
+撤销群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
 
-**响应**：`{ "resource": { ... }, "download": { ... } }`
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`。撤销后，当前 admin 角色成员不再因该路径的 `role:admin` ACL 获得写权限。
 
-### group.resources.request_add
+### group.fs.get_acl
 
-成员申请分享资源（需审批）。
+查询群自有区角色 ACL。需要当前 group owner 身份签名调用；普通 admin/member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
 
-**参数**：同 `group.resources.put`（不需要 `storage_ref`）。
+响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此 owner 授权 `role:admin:rwx` 后查询也返回 `rwx`。
 
-**响应**：
+### group.fs.list_acl
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "request": {
-        "request_id": "req_...",
-        "group_id": "g-abc123.agentid.pub",
-        "requester_aid": "bob.agentid.pub",
-        "resource_path": "/docs/my-file.pdf",
-        "resource_type": "file",
-        "title": "我的文件",
-        "status": "pending",
-        "created_at": 1234567890,
-        "updated_at": 1234567890,
-        "visibility": "members_only",
-        "tags": [],
-        "reviewed_by": null,
-        "review_note": null,
-        "resource_created": false
-    }
-}
-```
+`group.fs.get_acl` 的别名，参数、权限和返回结构完全相同。
 
-### group.resources.direct_add
+### group.fs.mkdir
 
-Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限。
+创建目录。参数：`path` 必填；`parents` 可选，默认 `false`。
 
-**参数**：同 `group.resources.put`（`resource_type` 不能是 `"folder"`）。
+### group.fs.rm
 
-**响应**：同 `group.resources.put`。
+删除节点。参数：`path` 必填；`recursive`、`force` 可选。
 
-### group.resources.list_pending
+### group.fs.cp
 
-列出待审批的资源申请。需要 **owner** 权限。
+只处理 group→group 远程复制。参数：`src`、`dst` 必填；`force`、`recursive`、`follow_symlinks` 可选。本地上传和下载由 SDK 的 `cp` 编排数据面，不直接调用此 RPC。
 
-**参数**：`group_id` (string)
+### group.fs.mv
 
-### group.resources.approve_request
+只处理 group→group 远程移动。参数：`src`、`dst` 必填；`force` 可选。本地路径参与时 SDK/CLI 应拒绝。
 
-批准资源申请。需要 **owner** 权限。
+### group.fs.check_upload
 
-**参数**：`request_id` (string, 必填), `note` (string, 可选)
+上传前检查。参数：`path`、`size_bytes`、`sha256`、`content_type`；可选 `force`、`parents`、`expected_version`、`metadata`。响应可包含 `target_exists`、`within_limit`、`instant`、`dedup_hit` 或 `skip_upload`。
 
-**响应**：
+### group.fs.create_upload_session
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "request": { ... },
-    "resource": { ... }
-}
-```
+创建上传会话。参数同 `check_upload`。响应包含 `upload_url`、`session_id`、可选 `headers`。SDK 使用该 URL 执行 HTTP PUT。
 
-### group.resources.reject_request
+### group.fs.complete_upload
 
-拒绝资源申请。需要 **owner** 权限。
+完成上传。参数包含 `path`、`sha256`、`size_bytes`、可选 `session_id`、`skip_blob`、`metadata`、`expected_version`。响应为 group view NodeView。
 
-**参数**：`request_id` (string, 必填), `note` (string, 可选)
+### group.fs.mount
 
-**响应**：
+挂载成员数据区。参数：`path` 必填；可选 `readonly`、`require_approval`、`source_bucket`、`expires_at`、`volume_id`。
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "request": { ... }
-}
-```
+### group.fs.umount
 
----
+卸载成员数据区。参数：`path` 必填。对成员数据区卸载不删除成员源数据。
 
 ## 在线状态
 
@@ -1850,36 +1580,6 @@ Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限
 }
 ```
 
-### group.get_metrics
-
-获取群组性能指标，包含 E2EE epoch 范围记录。需要 **admin 及以上**权限。
-
-**参数**：`group_id` (必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "message_seq": 1000,
-    "event_seq": 2000,
-    "member_count": 10,
-    "online_count": 5,
-    "e2ee_epoch": 3,
-    "epoch_count": 4,
-    "epoch_ranges": [
-        {
-            "epoch": 0,
-            "start_msg_seq": 0,
-            "start_event_seq": 0,
-            "end_msg_seq": 100,
-            "end_event_seq": 200,
-            "rotated_by": "alice.agentid.pub",
-            "rotated_at": 1234567890
-        }
-    ]
-}
-```
 
 ### group.refresh_member_types
 
@@ -1903,37 +1603,6 @@ Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限
 
 ---
 
-## E2EE
-
-### group.e2ee.rotate_epoch
-
-CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `current_epoch` | integer | 是 | 当前 epoch 值（CAS 校验） |
-| `rotation_signature` | string | 是 | 轮换签名（Base64，ECDSA SHA-256） |
-| `rotation_timestamp` | string | 是 | 轮换时间戳（秒） |
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "success": true, "epoch": 4 }`
-
-> 签名格式：`{group_id}|{current_epoch}|{new_epoch}|{aid}|{rotation_timestamp}`。时间戳必须在 5 分钟窗口内。签名去重防止重放攻击（10 分钟窗口）。
-
-### group.e2ee.get_epoch
-
-获取当前 E2EE Epoch 值。
-
-**参数**：`group_id` (必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "epoch": 3 }`
-
----
-
----
-
 ## 事件
 
 ### event/group.created
@@ -1957,32 +1626,31 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 
 **Payload**：
 
-```json
-{
-    "envelope": {
-        "module_id": "group",
-        "action": "member_added",
-        "group_id": "g-abc123.agentid.pub",
-        "event_seq": 42
-    },
-    "module_id": "group",
-    "action": "member_added",
-    "group_id": "g-abc123.agentid.pub",
+```json
+{
+    "envelope": {
+        "module_id": "group",
+        "action": "member_added",
+        "group_id": "g-abc123.agentid.pub",
+        "event_seq": 42
+    },
+    "module_id": "group",
+    "action": "member_added",
+    "group_id": "g-abc123.agentid.pub",
     "event_seq": 42
-}
-```
-
-SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `ev["envelope"]["action"]` 等路径访问。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `envelope` | object | 群事件信封，包含 `module_id`、`action`、`group_id`、`event_seq`、`event_type`、`actor_aid`、`created_at`、`device_id`、`slot_id` 等存在的字段 |
-| `module_id` | string | 固定 `"group"` |
-| `action` | string | 变更类型（见下表） |
-| `group_id` | string | 群组 ID |
+}
+```
+
+SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `ev["envelope"]["action"]` 等路径访问。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 群事件信封，包含 `module_id`、`action`、`group_id`、`event_seq`、`event_type`、`actor_aid`、`created_at`、`device_id`、`slot_id` 等存在的字段 |
+| `module_id` | string | 固定 `"group"` |
+| `action` | string | 变更类型（见下表） |
+| `group_id` | string | 群组 ID |
 | `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
-| `request_id` | string | 可选，仅资源审批相关 action |
-| `resource_path` | string | 可选，仅资源相关 action |
+| `path` | string | 可选，Group FS 相关 action 的节点路径 |
 
 **保序去重（SDK 内部行为）**：
 
@@ -2021,10 +1689,6 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x
 | `resource_put` | 资源上传 |
 | `resource_updated` | 资源更新 |
 | `resource_deleted` | 资源删除 |
-| `resource_request_created` | 资源申请创建 |
-| `resource_direct_added` | 资源直接添加 |
-| `resource_request_approved` | 资源申请批准 |
-| `resource_request_rejected` | 资源申请拒绝 |
 | `suspended` | 群组暂停 |
 | `resumed` | 群组恢复 |
 | `dissolved` | 群组解散 |
@@ -2074,71 +1738,71 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
 }
 ```
 
-SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
-
-**SDK 应用层回调形态**：
-
-```json
-{
-    "envelope": {
-        "group_id": "g-abc123.agentid.pub",
-        "from": "alice.agentid.pub",
-        "type": "text",
-        "timestamp": 1234567890000
-    },
-    "group_id": "g-abc123.agentid.pub",
-    "seq": 42,
-    "message_id": "uuid",
-    "sender_aid": "alice.agentid.pub",
-    "message_type": "group.message",
-    "dispatch_mode": "broadcast",
-    "payload": {"type": "text", "text": "Hello"}
-}
-```
-
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
-
-### event/group.message_recalled
+SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
+
+**SDK 应用层回调形态**：
+
+```json
+{
+    "envelope": {
+        "group_id": "g-abc123.agentid.pub",
+        "from": "alice.agentid.pub",
+        "type": "text",
+        "timestamp": 1234567890000
+    },
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 42,
+    "message_id": "uuid",
+    "sender_aid": "alice.agentid.pub",
+    "message_type": "group.message",
+    "dispatch_mode": "broadcast",
+    "payload": {"type": "text", "text": "Hello"}
+}
+```
+
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
+
+### event/group.message_recalled
 
 群消息撤回后推送给所有在线成员（与 pull 双 tombstone 兜底互补）。在线 push 是实时通道，双 tombstone 是离线 / 未读 / push 丢失时的可靠性兜底；两者最终一致，SDK 去重保证应用层只感知一次。
 
 **Payload**：
 
-```json
-{
-    "envelope": {
-        "group_id": "g-abc123.agentid.pub",
-        "from": "alice.agentid.pub",
-        "type": "group.message_recalled",
-        "kind": "group.message_recalled",
-        "timestamp": 1234567890000
-    },
-    "module_id": "group",
-    "group_id": "g-abc123.agentid.pub",
-    "seq": 43,
-    "message_id": "grm-uuid",
-    "tombstone_message_id": "grm-uuid",
-    "message_ids": ["gm-aaa"],
-    "target_message_seqs": [42],
-    "sender_aid": "alice.agentid.pub",
+```json
+{
+    "envelope": {
+        "group_id": "g-abc123.agentid.pub",
+        "from": "alice.agentid.pub",
+        "type": "group.message_recalled",
+        "kind": "group.message_recalled",
+        "timestamp": 1234567890000
+    },
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 43,
+    "message_id": "grm-uuid",
+    "tombstone_message_id": "grm-uuid",
+    "message_ids": ["gm-aaa"],
+    "target_message_seqs": [42],
+    "sender_aid": "alice.agentid.pub",
     "recalled_by": "alice.agentid.pub",
     "recalled_at": 1234567890000,
     "reason": "",
     "member_aids": ["bob.agentid.pub"]
-}
-```
-
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
-| `module_id` | string | 固定 `"group"` |
-| `group_id` | string | 群组 ID |
-| `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
-| `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
-| `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
-| `message_ids` | string[] | 被撤回的**原消息 ID 列表** |
+}
+```
+
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
+| `module_id` | string | 固定 `"group"` |
+| `group_id` | string | 群组 ID |
+| `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
+| `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
+| `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
+| `message_ids` | string[] | 被撤回的**原消息 ID 列表** |
 | `target_message_seqs` | integer[] | 被撤回的原消息 seq 列表 |
 | `sender_aid` | string | 原消息发送方 |
 | `recalled_by` | string | 撤回操作者 |
@@ -2168,7 +1832,10 @@ Group 服务定义了以下专用错误码（-33xxx 段）：
 | -33005 | Not a member | 需先加入群组 |
 | -33006 | Invite code invalid or expired | 获取新邀请码 |
 | -33007 | Join request pending | 等待审批，勿重复提交 |
-| -33008 | Resource not found | 检查 resource_path |
+| -33008 | Group FS path not found | 检查 path |
 | -33009 | Resource request not found | 检查 request_id |
 
 > SDK 客户端将 -33001 映射为 `GroupNotFoundError`，-33002~-33003 映射为 `GroupStateError`，其余映射为 `GroupError`。未识别的错误码 fallback 到 `AUNError`。
+
+
+