@agentunion/fastaun-browser 0.5.0 → 0.5.2

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,63 +95,59 @@
 | 方法 | 说明 |
 |------|------|
 | [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) | 在线成员 |
 
 ---
 
-## 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，避免同一群的不同别名产生不同材料。
+## Group AID / 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` 参数说明。
+目标态群组主标识是 `group_aid`，canonical 形式为 `{base}.{issuer-domain}`，例如 `10042.agentid.pub`、`team01.agentid.pub`、`g-abc123.agentid.pub`。新建群以 `group_aid` 为准；新群的兼容 `group_id` 列值也使用同一个 `group_aid` 字符串。历史 `group_id` 字段名和 RPC 参数名继续保留，但语义上只是兼容字段。
 
-`group.create` 可以指定自定义 `group_id`，但不能是纯数字（纯数字群号保留给服务端自动分配），且规范化后的 canonical group_id 未被占用；如果已被占用或与旧别名碰撞会返回错误。不指定 `group_id` 时服务端按群号自动分配，并通过唯一约束兜底，发现碰撞会重新生成。
+SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_aid` / `groupAid` 统一规范化为 `group_aid`。裸客户端也应使用同一 `group_aid` 生成签名材料和 E2EE AAD，避免同一群的历史别名产生不同材料。服务端响应可能同时返回 `group_id` 和 `group_aid`；新代码应优先读取 `group_aid`，仅兼容旧版本或历史数据时回退读取 `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`。
+兼容输入包括目标态 `{base}.{issuer-domain}`、本域简写 `{base}` / `g-{slug}`，以及旧格式 `group.{issuer-domain}/{base}`、`{base}@issuer-domain`、`g-{slug}@issuer-domain`、`g-{slug}.{issuer-domain}`。带域的旧输入会转换为 `{base}.{issuer-domain}`；本域简写会在服务端或 SDK 有本域 issuer 配置时补成本域 `group_aid`。`base` 支持 5 位及以上小写字母或数字，或 4 到 64 位 `[a-z0-9_-]` 风格名称；旧 `g-` 前缀形式继续兼容，`g-` 后为 4 到 32 位小写字母或数字。命名群使用 `group_name` 作为 base，规则见 `group.create` 参数说明。
+
+`group.create` 的新建语义以 `group_aid` 为准：命名群由 `group_name + issuer` 生成 `group_aid`，自动群由服务端群号生成 `{number}.{issuer}`。`group_id` 参数只作为旧客户端兼容别名；传入时不能是纯数字（纯数字群号保留给服务端自动分配），且规范化后的 `group_aid` 未被占用。如果已被占用或与历史别名碰撞会返回错误。
+
+在 `https://group.issuer-domain/...` 这类群链接中，path 使用单段 `group_aid`，例如 `https://group.agentid.pub/10042.agentid.pub/invite/ic-xxx`、`https://group.agentid.pub/g-abc123.agentid.pub/invite/ic-xxx`。历史 base 简写链接可继续由服务端兼容解析。
 
 ---
 
@@ -160,15 +155,16 @@
 
 ### group.create
 
-创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。
+创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | string | 是 | 群组显示名称 |
-| `group_id` | string | 否 | 自定义群 ID；不提供则服务端自动生成 |
-| `group_name` | string | 否 | 命名群标识，4-64 字符，`[a-z0-9_-]+`，不以 `guest`/`g-` 开头。与 `public_key` 同时提供时创建命名群 |
+| `group_aid` | string | 否 | 目标态群 AID；新代码优先使用。传入时会规范化为 `{base}.{issuer-domain}`，不能是纯数字 |
+| `group_id` | string | 否 | 兼容旧客户端的别名；值语义同 `group_aid`，不再推荐新代码使用 |
+| `group_name` | string | 否 | 命名群标识，4-64 字符，`[a-z0-9_-]+`，不以 `guest`/`g-` 开头。与 `public_key` 同时提供时创建命名群，并生成 `{group_name}.{issuer-domain}` |
 | `public_key` | string | 否 | 命名群公钥（base64 编码），与 `group_name` 同时提供 |
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
 | `visibility` | string | 否 | `"public"` / `"private"`，默认由配置决定 |
@@ -185,7 +181,8 @@
 ```json
 {
     "group": {
-        "group_id": "group.agentid.pub/10001",
+        "group_id": "my-team.agentid.pub",
+        "group_aid": "my-team.agentid.pub",
         "name": "测试群",
         "owner_aid": "alice.agentid.pub",
         "creator_aid": "alice.agentid.pub",
@@ -196,10 +193,9 @@
         "member_count": 1,
         "message_seq": 0,
         "event_seq": 0,
-        "group_url": "https://group.agentid.pub/10001",
-        "group_aid": "my-team.agentid.pub",
-        "created_at": 1234567890,
-        "updated_at": 1234567890
+        "group_url": "https://group.agentid.pub/my-team.agentid.pub",
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000
     },
     "aid_cert": {
         "cert": "-----BEGIN CERTIFICATE-----...",
@@ -211,9 +207,9 @@
 }
 ```
 
-> `aid_cert` 仅在命名群创建时返回。`group_aid` 和 `group_url` 仅在命名群时存在。
-
-**Group ID 格式**：新格式 `group.{issuer}/{group_no_or_name}`，旧格式 `{digits}.{issuer}` API 返回时自动转换。
+> `aid_cert` 仅在命名群创建时返回。`group_aid` 是新代码应使用的主标识；`group_id` 为兼容字段，新群通常与 `group_aid` 相同，历史群可能保留旧存储值。
+
+**标识格式**：目标态为 `{base}.{issuer-domain}`。旧格式 `group.{issuer-domain}/{base}`、`{base}@{issuer-domain}` 会在 API 边界转换为目标态 `group_aid`。
 
 ### group.bind_aid
 
@@ -223,7 +219,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `group_name` | string | 是 | 命名群标识，4-64 字符，`[a-z0-9_-]+` |
 | `public_key` | string | 是 | 群公钥（base64 编码） |
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
@@ -237,27 +233,36 @@
 }
 ```
 
-### group.get
+### group.get_info
 
-查询群组信息。
+查询群组信息，返回平铺格式。默认返回公开字段；需要成员或管理员权限的字段必须通过 `required` 显式声明。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
+| `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": 1234567890000
 }
 ```
 
-> 若群组不存在，`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
 
@@ -267,7 +272,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `name` | string | 否 | 新名称 |
 | `visibility` | string | 否 | 新可见性 |
 | `description` | string | 否 | 新描述 |
@@ -296,7 +301,7 @@
             "name": "项目讨论",
             "visibility": "private",
             "member_count": 5,
-            "updated_at": 1234567890,
+            "updated_at": 1234567890000,
             "role": "owner"
         }
     ],
@@ -334,26 +339,11 @@
 
 > **注意**：当前 `page` 固定为 1，不支持翻页。仅返回公开群组。
 
-### group.get_public_info
-
-查询公开群组信息。仅限 `visibility=public` 的群组可查询。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group": { ... }
-}
-```
-
 ### group.suspend
 
 暂停群组。暂停期间不能发送消息。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -370,7 +360,7 @@
 
 恢复暂停的群组。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -387,7 +377,7 @@
 
 永久解散群组。不可恢复。需要 **owner** 权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -398,29 +388,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": { ... }
-}
-```
 
 ---
 
@@ -434,7 +401,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要添加的 AID |
 | `role` | string | 否 | `"admin"` / `"member"`，默认 `"member"` |
 | `member_type` | string | 否 | `"human"` / `"ai"`，默认 `"human"` |
@@ -448,7 +415,7 @@
         "aid": "bob.agentid.pub",
         "role": "member",
         "member_type": "human",
-        "joined_at": 1234567890
+        "joined_at": 1234567890000
     }
 }
 ```
@@ -461,7 +428,7 @@
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | 50 | 每页条数（最大 200） |
 | `role` | string | 否 | — | 按角色过滤（owner/admin/member） |
@@ -477,9 +444,9 @@
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890,
+            "joined_at": 1234567890000,
             "last_ack_seq": 100,
-            "last_pull_at": 1234567890
+            "last_pull_at": 1234567890000
         }
     ],
     "total": 1,
@@ -497,7 +464,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要踢出的 AID |
 
 **响应**：
@@ -513,7 +480,7 @@
 
 主动退出群组。owner 不能直接退群，需先转让群主。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -526,13 +493,13 @@
 
 ### group.set_role
 
-设置成员角色。需要 **owner** 权限。不能改变 owner 角色。
+设置成员角色。需要 **owner** 权限。不能改变 owner 角色。该 RPC 只改变 membership 中的角色事实，不授予或撤销群自有区写 ACL；`role:admin` 是否可写群自有区由 `group.fs.set_acl` / `group.fs.remove_acl` 显式控制。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 目标 AID |
 | `role` | string | 是 | `"admin"` / `"member"` |
 
@@ -540,16 +507,20 @@
 
 ```json
 {
-    "group_id": "g-abc123.agentid.pub",
+    "group": { ... },
     "member": {
         "group_id": "g-abc123.agentid.pub",
         "aid": "bob.agentid.pub",
         "role": "admin",
         "member_type": "human",
-        "joined_at": 1234567890,
+        "joined_at": 1234567890000,
         "last_ack_seq": 0,
         "last_pull_at": 0
-    }
+    },
+    "old_role": "member",
+    "new_role": "admin",
+    "acl_model": "role_based",
+    "acl_policy": "unchanged"
 }
 ```
 
@@ -561,7 +532,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `new_owner` | string | 是 | 新群主 AID（也接受 `aid`） |
 
 **响应**：
@@ -574,6 +545,113 @@
 }
 ```
 
+### group.bind_group_aid
+
+为匿名群绑定群身份（group_aid）。需要 owner 权限。
+
+**幂等保证**：
+- 已绑定且公钥匹配：返回已绑定的 group_aid 和证书
+- 已绑定但公钥不同：报错 `group_aid_already_bound_different_key`
+- 未绑定：签发新 group_aid 并绑定
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `public_key` | string | 是 | 公钥 DER base64（SPKI 格式） |
+| `curve` | string | 否 | 曲线名称（默认 P-256） |
+
+**响应**：
+
+```json
+{
+    "group": {
+        "group_id": "my-team.agentid.pub",
+        "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 | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `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.agentid.pub",
+        "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 及以上**权限。
@@ -582,7 +660,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `subject` | string | 是 | 要封禁的 AID（也接受 `aid`） |
 | `reason` | string | 否 | 封禁原因 |
 | `expires_at` | integer | 否 | 过期时间戳（0 = 永久） |
@@ -599,7 +677,7 @@
         "banned_by": "alice.agentid.pub",
         "reason": "垃圾消息",
         "expires_at": 0,
-        "created_at": 1234567890
+        "created_at": 1234567890000
     }
 }
 ```
@@ -608,7 +686,7 @@
 
 解除封禁。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string), `subject` 或 `aid` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`subject` 或 `aid` (string)
 
 **响应**：
 
@@ -624,7 +702,7 @@
 
 获取封禁列表。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -638,7 +716,7 @@
             "banned_by": "alice.agentid.pub",
             "reason": "垃圾消息",
             "expires_at": 0,
-            "created_at": 1234567890
+            "created_at": 1234567890000
         }
     ],
     "total": 1,
@@ -659,7 +737,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message` | string | 否 | 申请留言 |
 | `answer` | string | 否 | 入群问题的答案 |
 
@@ -695,8 +773,8 @@
         "message": "请加我",
         "answer": "...",
         "status": "pending",
-        "created_at": 1234567890,
-        "updated_at": 1234567890,
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000,
         "expires_at": 1234654290,
         "reviewed_by": null,
         "rejection_reason": null
@@ -712,7 +790,7 @@
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `status` | string | 否 | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | — | 每页数量 |
@@ -728,8 +806,8 @@
             "aid": "carol.agentid.pub",
             "message": "请加我",
             "status": "pending",
-            "created_at": 1234567890,
-            "updated_at": 1234567890
+            "created_at": 1234567890000,
+            "updated_at": 1234567890000
         }
     ],
     "total": 1,
@@ -746,7 +824,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 申请人 AID |
 | `approve` | boolean | 否 | 批准或拒绝，默认 `true` |
 | `reason` | string | 否 | 拒绝原因 |
@@ -784,7 +862,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `requests` | array | 是 | 审批列表 |
 
 `requests` 数组每项：
@@ -816,7 +894,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `code` | string | 否 | 自定义邀请码（不提供则自动生成） |
 | `max_uses` | integer | 否 | 最大使用次数，默认 1，必须 > 0 |
 | `expires_in_seconds` | integer | 否 | 有效期（秒），默认由 invite_code_ttl_days 配置（7 天） |
@@ -834,7 +912,7 @@
         "max_uses": 10,
         "used_count": 0,
         "status": "active",
-        "created_at": 1234567890
+        "created_at": 1234567890000
     }
 }
 ```
@@ -859,13 +937,13 @@
 
 列出群组的邀请码。需要 admin 权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 ### group.revoke_invite_code
 
 撤销邀请码。需要 admin 权限。
 
-**参数**：`group_id` (string), `code` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`code` (string)
 
 ---
 
@@ -881,7 +959,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `settings` | object | 是 | 要写入的设置键值 |
 | `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
 | `settings["rules.content"]` | string | 否 | 群规则正文 |
@@ -928,7 +1006,7 @@ await client.call("group.set_settings", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]` |
 
 **响应**：
@@ -942,32 +1020,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
@@ -980,7 +1032,7 @@ await client.call("group.set_settings", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
@@ -988,7 +1040,7 @@ await client.call("group.set_settings", {
 
 ### Payload 参考约定
 
-`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
 
 `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
 
@@ -1010,34 +1062,45 @@ await client.call("group.set_settings", {
     },
     "event": { ... },
     "dispatch_mode": "broadcast",
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "message_dispatch": { ... }
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "message_dispatch": { ... },
+    "envelope": {
+        "from": "alice.agentid.pub",
+        "group_id": "g-abc123.agentid.pub",
+        "type": "text",
+        "timestamp": 1234567890000,
+        "encrypted": true,
+        "payload_type": "text"
+    },
+    "payload": {"type": "text", "text": "Hello"}
+}
+```
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `message` | object | 消息对象（含 seq、message_id、sender_aid 等） |
 | `event` | object | 关联的群事件对象 |
 | `dispatch_mode` | string | 群消息持久化分发模式标签：`"broadcast"` / `"mention"`；SDK 解密后也会注入到 `payload.dispatch_mode` |
-| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
-| `duty_state` | object | 可选，值班模式下的当前状态 |
-| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
+| `duty_state` | object | 可选，值班模式下的当前状态 |
+| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `envelope` | object | SDK 回填的发送结果信封，包含发送方、群标识、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
+| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
 
 ### group.thought.put
 
 写入某个发送者针对一个群上下文的思考内容。该内容不是普通群消息：服务端不分配消息 `seq`，不广播，不进入 `group.pull`，不需要 ack，也不持久化；只在内存中保留当前 head。
 
-SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，则必须自行完成同等加密和签名。
+SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature`、AAD 和 state commitment 生成；`client_signature` 按 Gateway 连接级身份语义携带。
 
-存储键为 `group_id + sender_aid + context.type + context.id`。其中 `sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_id, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
+存储键为规范化后的 `group_aid + sender_aid + context.type + context.id`。RPC 字段名仍为 `group_id` 以兼容旧客户端，但服务端会先规范化为目标态群标识；`sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_aid, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
 | `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
@@ -1065,7 +1128,7 @@ await client.call("group.thought.put", {
     "thought_id": "gt-...",
     "type": "e2ee.group_encrypted",
     "encrypted": true,
-    "payload": {"type": "e2ee.group_encrypted", "...": "..."},
+    "payload": {"type": "e2ee.group_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -1091,7 +1154,7 @@ await client.call("group.thought.put", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `sender_aid` | string | 是 | thought 作者 AID |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
@@ -1140,9 +1203,9 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `after_message_seq` | integer | 否 | 0 | 从该消息 seq 之后拉取 |
-| `limit` | integer | 否 | 100 | 最大条数 |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 | `device_id` | string | 否 | — | 设备 ID（多设备模式） |
 
 **响应**：
@@ -1153,7 +1216,7 @@ result = await client.call("group.thought.get", {
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
-    "limit": 100
+    "limit": 50
 }
 ```
 
@@ -1169,7 +1232,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1194,7 +1257,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
 | `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
 
@@ -1234,191 +1297,116 @@ 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.get_acl` 的别名，参数、权限和返回结构完全相同。
 
----
-
-## 群文件系统
-
-新代码统一使用 `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.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_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1433,10 +1421,10 @@ result = await client.call("group.thought.get", {
         {
             "aid": "alice.agentid.pub",
             "role": "owner",
-            "joined_at": 1234567890,
+            "joined_at": 1234567890000,
             "online": true,
             "session_id": "sess_123",
-            "last_active_at": 1234567890,
+            "last_active_at": 1234567890000,
             "expire_at": 1234571490
         }
     ]
@@ -1457,12 +1445,12 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 否 | — | 设备 ID，多设备模式必填 |
 | `device_name` | string | 否 | — | 设备名称（首次注册时使用） |
 | `device_type` | string | 否 | — | 设备类型 |
 | `after_event_seq` | integer | 否 | 游标位置 | 从该事件 seq 之后拉取；多设备模式下默认使用设备游标 |
-| `limit` | integer | 否 | 100 | 最大条数（受 `pull_max_limit` 配置限制） |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 
 **响应**：
 
@@ -1472,7 +1460,7 @@ result = await client.call("group.thought.get", {
     "events": [ ... ],
     "latest_event_seq": 100,
     "has_more": false,
-    "limit": 100,
+    "limit": 50,
     "cursor": {
         "current_seq": 50,
         "join_seq": 0,
@@ -1492,7 +1480,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1508,7 +1496,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `event_seq` | integer | 是 | 确认到的事件序号 |
 
@@ -1518,7 +1506,7 @@ result = await client.call("group.thought.get", {
 
 列出当前用户在指定群组的所有设备及游标状态。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1541,7 +1529,7 @@ result = await client.call("group.thought.get", {
 
 注销设备游标（清理不再使用的设备记录）。
 
-**参数**：`group_id` (必填), `device_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`），`device_id` (必填)
 
 **响应**：`{ "success": true }`
 
@@ -1553,7 +1541,7 @@ result = await client.call("group.thought.get", {
 
 获取管理员列表（owner + admin 角色）。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1564,7 +1552,7 @@ result = await client.call("group.thought.get", {
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890
+            "joined_at": 1234567890000
         }
     ]
 }
@@ -1574,7 +1562,7 @@ result = await client.call("group.thought.get", {
 
 获取群主 AID。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "owner_aid": "alice.agentid.pub" }`
 
@@ -1582,7 +1570,7 @@ result = await client.call("group.thought.get", {
 
 获取群组综合统计摘要。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1601,47 +1589,17 @@ result = await client.call("group.thought.get", {
     "message_seq": 1000,
     "event_seq": 2000,
     "e2ee_epoch": 3,
-    "created_at": 1234567890,
-    "updated_at": 1234567890
+    "created_at": 1234567890000,
+    "updated_at": 1234567890000
 }
 ```
 
-### 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
 
 刷新成员类型分类统计。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1659,37 +1617,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
@@ -1728,17 +1655,16 @@ CAS 轮换群组 E2EE Epoch。需要 **admin 及以上**权限。
 }
 ```
 
-SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `ev["envelope"]["action"]` 等路径访问。
+SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x 当前仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等兼容别名；新代码应优先通过 `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 |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
-| `request_id` | string | 可选，仅资源审批相关 action |
-| `resource_path` | string | 可选，仅资源相关 action |
+| `path` | string | 可选，Group FS 相关 action 的节点路径 |
 
 **保序去重（SDK 内部行为）**：
 
@@ -1774,12 +1700,9 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x
 | `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员封禁 |
 | `member_unbanned` | 成员解封 |
-| `resource_put` | 资源上传 |
-| `resource_updated` | 资源更新 |
-| `resource_deleted` | 资源删除 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
 
 **订阅**：
 
@@ -1803,11 +1726,21 @@ client.on("group.changed", lambda ev: print(ev["action"]))
     "type": "e2ee.group_encrypted",
     "dispatch_mode": "broadcast",
     "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "kind": "group.broadcast",
-    "member_aids": ["bob.agentid.pub"]
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "kind": "group.broadcast",
+    "member_aids": ["bob.agentid.pub"],
+    "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`，解密后的明文消息直接交付用户回调。
 
@@ -1848,7 +1781,7 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
 }
 ```
 
-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"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
 
 ### event/group.message_recalled
 
@@ -1880,13 +1813,13 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 }
 ```
 
-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.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等兼容别名；新代码应优先读取 `envelope`、`message_ids` 和 `target_message_seqs`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
 | `module_id` | string | 固定 `"group"` |
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
 | `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
 | `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |
@@ -1920,9 +1853,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`。
 
 
+