@agentunion/fastaun-browser 0.4.12 → 0.5.0

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

@@ -116,36 +116,29 @@
 | [group.get_join_requirements](#groupget_join_requirements) | 获取入群要求 |
 | [group.update_join_requirements](#groupupdate_join_requirements) | 更新入群要求 |
 
-### 资源管理
-
-| 方法 | 说明 |
-|------|------|
-| [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.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) | 在线成员 |
 
@@ -153,11 +146,13 @@
 
 ## Group ID 规范
 
-`group_id` 支持三种输入形式：`g-{slug}`、`g-{slug}@issuer-domain`、`g-{slug}.issuer-domain`。服务端接受输入后会统一规范化为 canonical group_id；本域内 `g-{slug}` 只是简写别名，响应、签名、E2EE AAD 和内部存储使用 canonical 形式。
-
-短形式必须以 `g-` 开头，总长度 6 到 16 字符；`slug` 为 4 到 14 位，只能包含小写字母和数字。`group.create` 可以指定 `group_id`，但必须满足该规则且未被占用；如果已被占用会返回错误。不指定 `group_id` 时由服务端自动分配，服务端通过唯一约束兜底，发现碰撞会重新生成。
-
-在 `https://group.issuer-domain/...` 这类群链接中，host 已携带 issuer，path 中的 `group_id` 使用本域简写形式，例如 `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`。
 
 ---
 
@@ -989,7 +984,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 +1044,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 调用示例**：
 
@@ -1335,330 +1330,91 @@ result = await client.call("group.thought.get", {
 | `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 | 否 | 标签数组 |
-
-**响应**：
-
-```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
-
-列出群资源。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `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`） |
-
-**响应**：
-
-```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.resources.get_access
-
-获取资源下载票据。
-
-**参数**：`group_id` (string), `resource_path` (string)
-
-**响应**：
-
-```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": { ... }
-}
-```
-
-### group.resources.delete
-
-删除群资源链接。需要 admin 权限。
-
-**参数**：`group_id` (string), `resource_path` (string)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "resource_path": "/path/to/file" }`
-
-### group.resources.update
-
-更新资源元数据。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `resource_path` (必填), `title` / `metadata` / `tags` / `visibility` (可选)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "resource": { ... } }`
-
-### group.resources.resolve_access_ticket
-
-使用访问票据换取下载令牌。
-
-**参数**：`ticket` (string, 必填)
-
-**响应**：`{ "resource": { ... }, "download": { ... } }`
-
-### group.resources.request_add
-
-成员申请分享资源（需审批）。
-
-**参数**：同 `group.resources.put`（不需要 `storage_ref`）。
-
-**响应**：
-
-```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.resources.direct_add
-
-Owner/Admin 直接添加资源（无需审批）。需要 **owner/admin** 权限。
-
-**参数**：同 `group.resources.put`（`resource_type` 不能是 `"folder"`）。
-
-**响应**：同 `group.resources.put`。
-
-### group.resources.list_pending
-
-列出待审批的资源申请。需要 **owner** 权限。
-
-**参数**：`group_id` (string)
-
-### group.resources.approve_request
-
-批准资源申请。需要 **owner** 权限。
-
-**参数**：`request_id` (string, 必填), `note` (string, 可选)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "request": { ... },
-    "resource": { ... }
-}
-```
-
-### group.resources.reject_request
-
-拒绝资源申请。需要 **owner** 权限。
-
-**参数**：`request_id` (string, 必填), `note` (string, 可选)
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "request": { ... }
-}
-```
-
----
-
-## 在线状态
-
-### group.get_online_members
+---
+
+## 群文件系统
+
+新代码统一使用 `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
 
 获取当前在线成员列表。
 
@@ -1957,29 +1713,29 @@ 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 |
@@ -2021,10 +1777,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,73 +1826,71 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
 }
 ```
 
-SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
-
-**SDK 应用层回调形态**：
-
-```json
-{
-    "envelope": {
-        "group_id": "g-abc123.agentid.pub",
-        "seq": 42,
-        "message_id": "uuid",
-        "sender_aid": "alice.agentid.pub",
-        "message_type": "group.message",
-        "dispatch_mode": "broadcast"
-    },
-    "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`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `msg["envelope"]["message_id"]` 等路径访问。
-
-### 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": {
-        "module_id": "group",
-        "group_id": "g-abc123.agentid.pub",
-        "seq": 43,
-        "message_id": "grm-uuid",
-        "sender_aid": "alice.agentid.pub"
-    },
-    "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`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `module_id`、`group_id`、`seq`、`message_id`、`sender_aid`、`device_id`、`slot_id` 等存在的字段 |
-| `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 | 撤回操作者 |
@@ -2174,3 +1924,5 @@ Group 服务定义了以下专用错误码（-33xxx 段）：
 | -33009 | Resource request not found | 检查 request_id |
 
 > SDK 客户端将 -33001 映射为 `GroupNotFoundError`，-33002~-33003 映射为 `GroupStateError`，其余映射为 `GroupError`。未识别的错误码 fallback 到 `AUNError`。
+
+