@agentunion/fastaun-browser 0.5.0 → 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,49 +95,43 @@
 | 方法 | 说明 |
 |------|------|
 | [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) | 统一读取群参数 |
+
+**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`），内部调用 `set_settings`/`get_settings`，返回旧格式。新代码建议直接使用 `set_settings`/`get_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) | 更新入群要求 |
-
-### 群文件系统
-
-| 方法 | 说明 |
-|------|------|
-| [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.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) | 卸载成员数据区 |
-
-### 在线状态
-
-| 方法 | 说明 |
+| [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) | 卸载成员数据区 |
+
+### 在线状态
+
+| 方法 | 说明 |
 |------|------|
 | [group.get_online_members](#groupget_online_members) | 在线成员 |
 
@@ -146,13 +139,13 @@
 
 ## Group ID 规范
 
-`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，避免同一群的不同别名产生不同材料。
-
-兼容输入包括 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` 参数说明。
-
-`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`。
+`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，避免同一群的不同别名产生不同材料。
+
+兼容输入包括 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` 参数说明。
+
+`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`。
 
 ---
 
@@ -237,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
 
@@ -334,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 及以上**权限。
@@ -398,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": { ... }
-}
-```
 
 ---
 
@@ -526,7 +490,7 @@
 
 ### group.set_role
 
-设置成员角色。需要 **owner** 权限。不能改变 owner 角色。
+设置成员角色。需要 **owner** 权限。不能改变 owner 角色。该 RPC 只改变 membership 中的角色事实，不授予或撤销群自有区写 ACL；`role:admin` 是否可写群自有区由 `group.fs.set_acl` / `group.fs.remove_acl` 显式控制。
 
 **参数**：
 
@@ -540,7 +504,7 @@
 
 ```json
 {
-    "group_id": "g-abc123.agentid.pub",
+    "group": { ... },
     "member": {
         "group_id": "g-abc123.agentid.pub",
         "aid": "bob.agentid.pub",
@@ -549,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"
 }
 ```
 
@@ -574,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 及以上**权限。
@@ -942,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
@@ -1234,187 +1283,112 @@ result = await client.call("group.thought.get", {
 
 ---
 
-## 公告与规则
+## 群文件系统
 
-### group.get_announcement
+新代码统一使用 `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 使用：
 
-**参数**：`group_id` (string, 必填)
+| 语言 | 入口 |
+|------|------|
+| Python | `client.group.fs` |
+| TypeScript / JavaScript | `client.group.fs` |
+| Go | `client.Group().FS()` |
+| CLI | `aun group fs ...` |
 
-**响应**：
+权限与签名约束：
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "announcement": { ... }
-}
-```
+- 群自有区是除 `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 当本地路径。
 
-### group.update_announcement
+### group.fs.ls
 
-更新群公告。需要 **admin 及以上**权限。
+列出目录。参数：`path` 必填；可选 `page`、`size`、`marker`、`long`、`recursive`。响应返回 group view `items`，节点 `path` 仍为 group path。
 
-**参数**：
+### group.fs.find
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `content` | string | 是 | 公告内容（上限由 announcement_max_length 配置，默认 4000） |
-| `attachments` | array | 否 | 存储引用数组 |
+查找节点。参数：`path` 必填；可选 `pattern`、`name`、`type`、`size`、`mtime`、`page`、`page_size`。
 
-**响应**：
+### group.fs.stat
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "announcement": { ... }
-}
-```
+查看节点。参数：`path` 必填。响应为 NodeView。
 
-### group.get_rules
+### group.fs.lstat
 
-获取群规则。
+查看链接节点本身。参数同 `group.fs.stat`。
 
-**参数**：`group_id` (string, 必填)
+### group.fs.df
 
-**响应**：
+查看群文件系统用量。参数可传 `path` 或 `group_id`。
 
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "rules": { ... }
-}
-```
+### group.fs.create_download_ticket
 
-### group.update_rules
+创建下载票据。参数：`path` 必填。响应包含 `download_url`、可选 `sha256`、`content_type`、`file_name`。SDK 下载数据面使用该票据执行 HTTP GET 并校验 sha256。
 
-更新群规则。需要 **admin 及以上**权限。
+### group.fs.set_acl
 
-**参数**：`group_id` (string) + 规则字段（max_members, allow_member_invite 等，均可选）
+授予群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
 
-### group.get_join_requirements
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`；`perms` 默认 `rwx`，必须包含写权限。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`。
 
-获取入群要求。
+### group.fs.remove_acl
 
-**参数**：`group_id` (string, 必填)
+撤销群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
 
-**响应**：
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`。撤销后，当前 admin 角色成员不再因该路径的 `role:admin` ACL 获得写权限。
 
-```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.fs.get_acl
 
-### group.update_join_requirements
+查询群自有区角色 ACL。需要当前 group owner 身份签名调用；普通 admin/member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
 
-更新入群要求。需要 **admin 及以上**权限。
+响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此 owner 授权 `role:admin:rwx` 后查询也返回 `rwx`。
 
-**参数**：
+### group.fs.list_acl
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `mode` | string | 否 | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
-| `question` | string | 否 | 入群问题 |
-| `auto_approve_patterns` | array | 否 | 自动批准正则列表 |
-| `max_pending` | integer | 否 | 最大待审批数 |
-
----
-
-## 群文件系统
-
-新代码统一使用 `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 不拼接 `groupdata/{group_id}`。
-
-推荐通过 SDK/CLI 使用：
-
-| 语言 | 入口 |
-|------|------|
-| Python | `client.group.fs` |
-| TypeScript / JavaScript | `client.group.fs` |
-| Go | `client.Group().FS()` |
-| CLI | `aun group fs ...` |
-
-权限与签名约束：
-
-- 群自有区（如 `group_aid:/announce`、`/public`、`/archive`）只有 owner 可写，但实际调用身份必须是 `group_aid`，并且 `client_signature_aid` 必须是当前 group_identity。`group_aid` 私钥由群主持有；admin/member 不能用个人 AID 直接写群自有区。
-- `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 当本地路径。
-
-### group.fs.ls
-
-列出目录。参数：`path` 必填；可选 `page`、`size`、`marker`、`long`、`recursive`。响应返回 group view `items`，节点 `path` 仍为 group path。
-
-### group.fs.find
-
-查找节点。参数：`path` 必填；可选 `pattern`、`name`、`type`、`size`、`mtime`、`page`、`page_size`。
-
-### group.fs.stat
-
-查看节点。参数：`path` 必填。响应为 NodeView。
-
-### group.fs.lstat
-
-查看链接节点本身。参数同 `group.fs.stat`。
-
-### group.fs.df
-
-查看群文件系统用量。参数可传 `path` 或 `group_id`。
-
-### group.fs.create_download_ticket
-
-创建下载票据。参数：`path` 必填。响应包含 `download_url`、可选 `sha256`、`content_type`、`file_name`。SDK 下载数据面使用该票据执行 HTTP GET 并校验 sha256。
-
-### group.fs.mkdir
-
-创建目录。参数：`path` 必填；`parents` 可选，默认 `false`。
-
-### group.fs.rm
-
-删除节点。参数：`path` 必填；`recursive`、`force` 可选。
-
-### group.fs.cp
-
-只处理 group→group 远程复制。参数：`src`、`dst` 必填；`force`、`recursive`、`follow_symlinks` 可选。本地上传和下载由 SDK 的 `cp` 编排数据面，不直接调用此 RPC。
-
-### group.fs.mv
-
-只处理 group→group 远程移动。参数：`src`、`dst` 必填；`force` 可选。本地路径参与时 SDK/CLI 应拒绝。
-
-### group.fs.check_upload
-
-上传前检查。参数：`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
-
-创建上传会话。参数同 `check_upload`。响应包含 `upload_url`、`session_id`、可选 `headers`。SDK 使用该 URL 执行 HTTP PUT。
-
-### group.fs.complete_upload
-
-完成上传。参数包含 `path`、`sha256`、`size_bytes`、可选 `session_id`、`skip_blob`、`metadata`、`expected_version`。响应为 group view NodeView。
-
-### group.fs.mount
-
-挂载成员数据区。参数：`path` 必填；可选 `readonly`、`require_approval`、`source_bucket`、`expires_at`、`volume_id`。
-
-### group.fs.umount
-
-卸载成员数据区。参数：`path` 必填。对成员数据区卸载不删除成员源数据。
-
-## 在线状态
-
-### group.get_online_members
+`group.fs.get_acl` 的别名，参数、权限和返回结构完全相同。
+
+### group.fs.mkdir
+
+创建目录。参数：`path` 必填；`parents` 可选，默认 `false`。
+
+### group.fs.rm
+
+删除节点。参数：`path` 必填；`recursive`、`force` 可选。
+
+### group.fs.cp
+
+只处理 group→group 远程复制。参数：`src`、`dst` 必填；`force`、`recursive`、`follow_symlinks` 可选。本地上传和下载由 SDK 的 `cp` 编排数据面，不直接调用此 RPC。
+
+### group.fs.mv
+
+只处理 group→group 远程移动。参数：`src`、`dst` 必填；`force` 可选。本地路径参与时 SDK/CLI 应拒绝。
+
+### group.fs.check_upload
+
+上传前检查。参数：`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
+
+创建上传会话。参数同 `check_upload`。响应包含 `upload_url`、`session_id`、可选 `headers`。SDK 使用该 URL 执行 HTTP PUT。
+
+### group.fs.complete_upload
+
+完成上传。参数包含 `path`、`sha256`、`size_bytes`、可选 `session_id`、`skip_blob`、`metadata`、`expected_version`。响应为 group view NodeView。
+
+### group.fs.mount
+
+挂载成员数据区。参数：`path` 必填；可选 `readonly`、`require_approval`、`source_bucket`、`expires_at`、`volume_id`。
+
+### group.fs.umount
+
+卸载成员数据区。参数：`path` 必填。对成员数据区卸载不删除成员源数据。
+
+## 在线状态
+
+### group.get_online_members
 
 获取当前在线成员列表。
 
@@ -1606,36 +1580,6 @@ result = await client.call("group.thought.get", {
 }
 ```
 
-### 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
 
@@ -1659,37 +1603,6 @@ result = await client.call("group.thought.get", {
 
 ---
 
-## 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
@@ -1737,8 +1650,7 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x
 | `action` | string | 变更类型（见下表） |
 | `group_id` | string | 群组 ID |
 | `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
-| `request_id` | string | 可选，仅资源审批相关 action |
-| `resource_path` | string | 可选，仅资源相关 action |
+| `path` | string | 可选，Group FS 相关 action 的节点路径 |
 
 **保序去重（SDK 内部行为）**：
 
@@ -1920,9 +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`。
 
 
+