@agentunion/fastaun-browser 0.5.18 → 0.5.20

package/_packed_docs/protocol/10-Group-/345/255/220/345/215/217/350/256/256.md

@@ -1,66 +1,66 @@
-# 10. Group 子协议
-
-> **适用版本**：AUN 1.0 | **状态**：Draft
-
-Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。
-
----
-
-## 10.1 架构与角色
-
-```
-客户端 A ──message.send──► Group Service (AID: group.service.aid)
-                              │
-                              ├── 存储群消息
-                              ├── 广播 event/group.message_created
-                              └── 推送 event/group.changed
-```
-
-- **Group Service**：持有独立 AID，作为 AUN 节点运行，暴露 `group.*` RPC 方法
+# 10. Group 子协议
+
+> **适用版本**：AUN 1.0 | **状态**：Draft
+
+Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。Group 服务本身是一个 AID 持有者，客户端通过标准 `message.*` 协议与 Group 服务通信，Group 服务通过 JSON-RPC 2.0 暴露 `group.*` 命名空间方法。服务 AID、群身份 `group_aid` 与群主 `owner_aid` 是三个不同角色。群主关系由 Group 生命周期管理，不走 Ownership 2.1 的双文件绑定、释放、转移、审批或 NS 关系账本。
+
+---
+
+## 10.1 架构与角色
+
+```
+客户端 A ──message.send──► Group Service (AID: group.service.aid)
+                              │
+                              ├── 存储群消息
+                              ├── 广播 event/group.message_created
+                              └── 推送 event/group.changed
+```
+
+- **Group Service**：持有独立 AID，作为 AUN 节点运行，暴露 `group.*` RPC 方法
 - **成员**：通过 `group.request_join` / `group.add_member` / `group.invite_member` / `group.use_invite_code` 加入
-- **权限层级**：`owner` > `admin` > `member`（只读群另有 `observer` 角色）
-
----
-
-## 10.2 数据模型
-
-### Group 对象
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组唯一 ID（自动生成或自定义） |
-| `name` | string | 群组名称 |
-| `owner_aid` | string | 群主 AID |
-| `creator_aid` | string | 创建者 AID |
-| `visibility` | string | `"public"` / `"private"` |
-| `status` | string | `"active"` / `"suspended"` / `"closed"` |
+- **权限层级**：`owner` > `admin` > `member`（只读群另有 `observer` 角色）
+
+---
+
+## 10.2 数据模型
+
+### Group 对象
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `group_id` | string | 群组唯一 ID（自动生成或自定义） |
+| `name` | string | 群组名称 |
+| `owner_aid` | string | 群主 AID |
+| `creator_aid` | string | 创建者 AID |
+| `visibility` | string | `"public"` / `"private"` |
+| `status` | string | `"active"` / `"suspended"` / `"dissolved"` |
 | `description` | string | 群组描述 |
 | `metadata` | object | 自定义元数据 |
 | `mention_mode` | string | 群提及过滤模式：`"disabled"`（默认）/ `"mention-only"`，详见 [10.2.3 群提及过滤模式](#1023-群提及过滤模式mention_mode) |
 | `member_count` | integer | 成员数量 |
-| `message_seq` | integer | 最新消息序号 |
-| `event_seq` | integer | 最新事件序号 |
-| `created_at` | integer | 创建时间（Unix 秒） |
-
-### Group ID 格式与规范化
-
-`group_id` 是群组的全网唯一标识，前缀 `g-` 为 Group 保留前缀。普通 AID 的本地名称不得以 `g-` 开头，避免与群 ID 混淆。短形式必须以 `g-` 开头，总长度 6 到 16 字符；`g-` 后面的 slug 为 4 到 14 位，只能使用小写字母和数字。
-
-服务端必须接受以下三种输入形式，并在内部统一为 canonical group_id：
-
-| 输入形式 | 用途 | canonical 结果 |
-|----------|------|----------------|
-| `g-{slug}` | 本地域内简写别名 | 若本域 issuer 为 `issuer-domain`，规范化为 `g-{slug}.issuer-domain` |
-| `g-{slug}@issuer-domain` | 跨域传播兼容形式 | 规范化为 `g-{slug}.issuer-domain` |
-| `g-{slug}.issuer-domain` | canonical 形式 | 保持为 `g-{slug}.issuer-domain` |
-
-规范化规则：
-
-- `group_id` 比较、数据库存储、成员归属、权限校验、E2EE AAD / 签名输入均必须使用 canonical group_id。
-- 输入必须先 trim 并转换为小写；`@issuer-domain` 形式仅作为兼容输入，进入内部前必须转换为 `.issuer-domain`。
-- 本域内客户端可以提交 `g-{slug}` 简写；服务端按本域 `AUN_ISSUER_DOMAIN` 解析为 canonical group_id。没有本域 issuer 配置时，简写保持为 `g-{slug}`。
-- 跨域消息、邀请传播、日志和协议响应应使用 canonical group_id，避免远端误把短 ID 当成本域群。
-- `group.create` 可以指定 `group_id`；指定时必须满足上述格式且未被占用，被占用时返回错误。未指定时由服务端自动分配。
+| `message_seq` | integer | 最新消息序号 |
+| `event_seq` | integer | 最新事件序号 |
+| `created_at` | integer | 创建时间（Unix 秒） |
+
+### Group ID 格式与规范化
+
+`group_id` 是群组的全网唯一标识，前缀 `g-` 为 Group 保留前缀。普通 AID 的本地名称不得以 `g-` 开头，避免与群 ID 混淆。短形式必须以 `g-` 开头，总长度 6 到 16 字符；`g-` 后面的 slug 为 4 到 14 位，只能使用小写字母和数字。
+
+服务端必须接受以下三种输入形式，并在内部统一为 canonical group_id：
+
+| 输入形式 | 用途 | canonical 结果 |
+|----------|------|----------------|
+| `g-{slug}` | 本地域内简写别名 | 若本域 issuer 为 `issuer-domain`，规范化为 `g-{slug}.issuer-domain` |
+| `g-{slug}@issuer-domain` | 跨域传播兼容形式 | 规范化为 `g-{slug}.issuer-domain` |
+| `g-{slug}.issuer-domain` | canonical 形式 | 保持为 `g-{slug}.issuer-domain` |
+
+规范化规则：
+
+- `group_id` 比较、数据库存储、成员归属、权限校验、E2EE AAD / 签名输入均必须使用 canonical group_id。
+- 输入必须先 trim 并转换为小写；`@issuer-domain` 形式仅作为兼容输入，进入内部前必须转换为 `.issuer-domain`。
+- 本域内客户端可以提交 `g-{slug}` 简写；服务端按本域 `AUN_ISSUER_DOMAIN` 解析为 canonical group_id。没有本域 issuer 配置时，简写保持为 `g-{slug}`。
+- 跨域消息、邀请传播、日志和协议响应应使用 canonical group_id，避免远端误把短 ID 当成本域群。
+- `group.create` 可以指定 `group_id`；指定时必须满足上述格式且未被占用，被占用时返回错误。未指定时由服务端自动分配。
 - 自动生成的群 ID 使用 `g-` 加随机小写十六进制短 slug，服务端必须通过唯一约束或等效机制保证 canonical group_id 唯一；发现碰撞时重新生成。
 - 在 `group.{issuer-domain}` 这类已携带 issuer 的公开 HTTP 主机下，生成的群链接 path 应使用本域简写，例如 `https://group.issuer-domain/g-abc123` 或 `https://group.issuer-domain/g-abc123/invite/ic-xxx`。
 
@@ -82,16 +82,16 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 5. **变更不追溯**：群管理员变更 `mention_mode` 后仅对之后的新消息生效；服务端随消息保存发送时的模式快照
 
 `mention-only` 必须基于结构化的 `payload.mentions` 判断，不得仅扫描文本中的 `@xxx`；`{ "scope": "all" }` 视为命中所有成员。该设置仅适用于群组，群 owner/admin 可写，普通成员只读。
-
+
 ### Member 对象
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `aid` | string | 成员 AID |
-| `group_id` | string | 群组 ID |
-| `role` | string | `"owner"` / `"admin"` / `"member"` |
-| `joined_at` | integer | 加入时间（Unix 秒） |
-| `last_ack_seq` | integer | 最后已读消息序号 |
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aid` | string | 成员 AID |
+| `group_id` | string | 群组 ID |
+| `role` | string | `"owner"` / `"admin"` / `"member"` |
+| `joined_at` | integer | 加入时间（Unix 秒） |
+| `last_ack_seq` | integer | 投递消费确认位置，与业务已读位置独立 |
 
 ### Member Status 对象
 
@@ -104,169 +104,171 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | `updated_at` | integer | 最近一次状态上报时间（Unix 毫秒） |
 | `last_message_at` | integer | 该成员在此群最后一条成功发送消息的时间（Unix 毫秒） |
 | `last_payload_type` | string | 最后一条成功发送消息的 `payload.type` |
-
-### Message 对象
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组 ID |
-| `seq` | integer | 消息序号（群内单调递增） |
-| `message_id` | string | 消息 UUID |
-| `sender_aid` | string | 发送者 AID |
-| `message_type` | string | 信封/封装类型，如 `e2ee.group_encrypted`；业务负载类型在 `payload.type` 中 |
-| `payload` | object | 消息内容 |
-| `attachments` | array | 附件存储引用列表 |
-| `created_at` | integer | 创建时间（Unix 毫秒） |
-
----
-
-## 10.3 权限模型
-
-| 操作 | owner | admin | member |
-|------|:-----:|:-----:|:------:|
-| 发送消息 | ✅ | ✅ | ✅ |
-| 查看成员 | ✅ | ✅ | ✅ |
-| 邀请成员 | ✅ | ✅ | 规则决定 |
-| 踢出成员 | ✅ | ✅（非 owner）| ❌ |
-| 设置角色 | ✅ | ❌ | ❌ |
-| 更新群信息 | ✅ | ✅ | ❌ |
-| 更新公告 | ✅ | ✅ | ❌ |
+
+### Message 对象
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `group_id` | string | 群组 ID |
+| `seq` | integer | 消息序号（群内单调递增） |
+| `message_id` | string | 消息 UUID |
+| `sender_aid` | string | 发送者 AID |
+| `message_type` | string | 信封/封装类型，如 `e2ee.group_encrypted`；业务负载类型在 `payload.type` 中 |
+| `payload` | object | 消息内容 |
+| `attachments` | array | 附件存储引用列表 |
+| `created_at` | integer | 创建时间（Unix 毫秒） |
+
+---
+
+## 10.3 权限模型
+
+| 操作 | owner | admin | member |
+|------|:-----:|:-----:|:------:|
+| 发送消息 | ✅ | ✅ | ✅ |
+| 查看成员 | ✅ | ✅ | ✅ |
+| 邀请成员 | ✅ | ✅ | 规则决定 |
+| 踢出成员 | ✅ | ✅（非 owner）| ❌ |
+| 设置角色 | ✅ | ❌ | ❌ |
+| 更新群信息 | ✅ | ✅ | ❌ |
+| 更新公告 | ✅ | ✅ | ❌ |
 | 审批申请 | ✅ | ✅ | ❌ |
 | 禁言/取消禁言 | ✅ | ✅（受角色层级限制） | ❌ |
 | 屏蔽/取消屏蔽其他成员 | ✅ | ✅（受角色层级限制） | ❌ |
 | 屏蔽/取消屏蔽自己 | ✅ | ✅ | ✅ |
 | 上报自己状态/查询成员状态 | ✅ | ✅ | ✅ |
 | 暂停/关闭群 | ✅ | ✅ | ❌ |
-| 转让群主 | ✅ | ❌ | ❌ |
-| Group FS 写入 | ✅ | 配置决定 | ❌ |
-
----
-
-## 10.4 群组生命周期方法
-
-### `group.create`
-
+| 转让群主 | ✅ | ❌ | ❌ |
+| Group FS 写入 | ✅ | 配置决定 | ❌ |
+
+---
+
+## 10.4 群组生命周期方法
+
+### `group.create`
+
+创建自动建立调用者与群的 owner 关系；群身份公私钥及证书由该 owner 持有，Group 服务不接收或保存群私钥。群名片须含当前 `owner`，不含通用 `ownership` 声明；由当前 owner 使用本人证书和私钥代签、代上传，文件 `aid` 仍是 `group_aid`。签名块 `signer_aid`、V2 上传授权、实体证书代际和条件恢复见 [Ownership 协议定义 2.1 §2.5](Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。创建、群证书绑定和名片发布的参数/响应以 [Group RPC Manual](../sdk/09-group-rpc-manual.md#groupcreate) 为准。
+
 创建群组。
 
 SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密钥并重放相同 `group_name + public_key` 的已提交结果；匿名群复用已持久化的创建上下文，使响应丢失后的重试返回同一数字群，再继续群身份绑定和 `agent.md` 上传。服务端必须原子提交群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射。直接调用 RPC 且没有 SDK 恢复上下文时，每次调用仍表示一次新的自动群创建。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `name` | string | ✅ | 群组名称 |
-| `group_id` | string | ❌ | 自定义群 ID，短形式必须以 `g-` 开头且总长度 6 到 16 字符；不提供则服务端自动生成；已被占用时返回错误 |
-| `visibility` | string | ❌ | `"public"` / `"private"`，默认由服务配置决定 |
-| `description` | string | ❌ | 群组描述 |
-| `metadata` | object | ❌ | 自定义元数据 |
-| `avatar_ref` | string | ❌ | 头像存储引用 |
-| `join_mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
-| `join_question` | string | ❌ | 入群问题 |
-| `max_pending` | integer | ❌ | 最大待审批数，默认 100 |
-
-**响应**：
-
-```json
-{
-    "group": {
-        "group_id": "g-abc123.agentid.pub",
-        "name": "测试群",
-        "owner_aid": "alice.agentid.pub",
-        "creator_aid": "alice.agentid.pub",
-        "visibility": "private",
-        "status": "active",
-        "member_count": 1,
-        "message_seq": 0,
-        "event_seq": 0,
-        "created_at": 1234567890
-    },
-    "aid": "alice.agentid.pub"
-}
-```
-
-### `group.get_info`
-
-查询群组信息，返回平铺格式。默认返回公开字段；需要成员权限的字段必须通过 `required` 显式声明。
-
-**参数**：
-
-- `group_id` (string, 必填)
-- `required` (string[], 可选)：受限字段声明，可取 `member`、`state`、`e2ee`、`avatar`
-
-**默认响应**：
-
-`{ "found": true, "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "name": "项目讨论", "visibility": "public", "status": "active", "description": "", "member_count": 3, "created_at": 1234567890 }`
-
-`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`
-
-更新群组资料。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填) + 可选字段：`name` / `description` / `metadata` / `avatar_ref`
-
-**响应**：`{ "group": { ... } }`
-
-### `group.list` / `group.list_my`
-
-列出当前 AID 加入的所有群组。
-
-**参数**：`size` (integer, 可选，默认 50)
-
-**响应**：`{ "items": [ ... ], "total": 3, "page": 1, "size": 50, "aid": "alice.agentid.pub" }`
-
-### `group.search`
-
-搜索公开群组（`visibility=public`）。
-
-**参数**：`query` (string, 可选), `size` (integer, 可选)
-
-**响应**：`{ "query": "...", "items": [ ... ], "total": 3 }`
-
-
-### `group.suspend`
-
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `name` | string | ✅ | 群组名称 |
+| `group_id` | string | ❌ | 自定义群 ID，短形式必须以 `g-` 开头且总长度 6 到 16 字符；不提供则服务端自动生成；已被占用时返回错误 |
+| `visibility` | string | ❌ | `"public"` / `"private"`，默认由服务配置决定 |
+| `description` | string | ❌ | 群组描述 |
+| `metadata` | object | ❌ | 自定义元数据 |
+| `avatar_ref` | string | ❌ | 头像存储引用 |
+| `join_mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
+| `join_question` | string | ❌ | 入群问题 |
+| `max_pending` | integer | ❌ | 最大待审批数，默认 100 |
+
+**响应**：
+
+```json
+{
+    "group": {
+        "group_id": "g-abc123.agentid.pub",
+        "name": "测试群",
+        "owner_aid": "alice.agentid.pub",
+        "creator_aid": "alice.agentid.pub",
+        "visibility": "private",
+        "status": "active",
+        "member_count": 1,
+        "message_seq": 0,
+        "event_seq": 0,
+        "created_at": 1234567890
+    },
+    "aid": "alice.agentid.pub"
+}
+```
+
+### `group.get_info`
+
+查询群组信息，返回平铺格式。默认返回公开字段；需要成员权限的字段必须通过 `required` 显式声明。
+
+**参数**：
+
+- `group_id` (string, 必填)
+- `required` (string[], 可选)：受限字段声明，可取 `member`、`state`、`e2ee`、`avatar`
+
+**默认响应**：
+
+`{ "found": true, "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "name": "项目讨论", "visibility": "public", "status": "active", "description": "", "member_count": 3, "created_at": 1234567890 }`
+
+`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`
+
+更新群组资料。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填) + 可选字段：`name` / `description` / `metadata` / `avatar_ref`
+
+**响应**：`{ "group": { ... } }`
+
+### `group.list` / `group.list_my`
+
+列出当前 AID 加入的所有群组。
+
+**参数**：`size` (integer, 可选，默认 50)
+
+**响应**：`{ "items": [ ... ], "total": 3, "page": 1, "size": 50, "aid": "alice.agentid.pub" }`
+
+### `group.search`
+
+搜索公开群组（`visibility=public`）。
+
+**参数**：`query` (string, 可选), `size` (integer, 可选)
+
+**响应**：`{ "query": "...", "items": [ ... ], "total": 3 }`
+
+
+### `group.suspend`
+
 暂停群组。暂停期间 owner/admin 可以继续通过 `group.send`、`group.v2.send` 和 `group.thought.put` 发言；member 禁止发言，入群、邀请、申请审批等准入操作继续拒绝。需要 admin 及以上权限。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group": { ... }, "status": "suspended" }`
-
-### `group.resume`
-
-恢复已暂停的群组。需要 admin 及以上权限。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group": { ... }, "status": "active" }`
-
-### `group.dissolve`
-
-永久解散群组。需要 **owner** 权限。解散后不可恢复。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "status": "dissolved" }`
-
----
-
-## 10.5 成员管理方法
-
-### `group.add_member`
-
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group": { ... }, "status": "suspended" }`
+
+### `group.resume`
+
+恢复已暂停的群组。需要 admin 及以上权限。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group": { ... }, "status": "active" }`
+
+### `group.dissolve`
+
+永久解散群组。需要 **owner** 权限。解散后不可恢复，自动解除有效 owner 关系，终止待处理转移并撤销群证书及相关授权；旧 owner、旧证书、实体 token 和旧 pending 均不能继续上传群名片或代表群鉴权。历史 owner 和签名记录保留用于审计，不作为当前授权。解散墓碑及待转移清理先原子提交；事件发布、CA 撤销、Storage 权限失效与缓存清理通过持久 outbox 收尾，未全完成返回 -32002、status=unavailable/retryable=true/committed=true，重试续跑收尾，不能提前宣告成功。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "status": "dissolved" }`
+
+---
+
+## 10.5 成员管理方法
+
+### `group.add_member`
+
 直接添加成员。需要 **owner** 权限；这是立即成为正式成员的显式例外。普通指定 AID 入群应使用 `group.invite_member`，由目标 AID 接受。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `aid` | string | ✅ | 要添加的 AID |
-| `role` | string | ❌ | `"member"` / `"admin"`，默认 `"member"` |
-| `member_type` | string | ❌ | `"human"` / `"ai"`，默认 `"human"` |
-
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `aid` | string | ✅ | 要添加的 AID |
+| `role` | string | ❌ | `"member"` / `"admin"`，默认 `"member"` |
+| `member_type` | string | ❌ | `"human"` / `"ai"`，默认 `"human"` |
+
 **响应**：`{ "group": { ... }, "member": { ... } }`
 
 ### `group.invite_member`
@@ -286,76 +288,84 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 ### `group.revoke_invite`
 
 由原邀请发出者以 `invite_id` 撤回自己的待处理邀请。撤回、接受、拒绝和过期是互斥终态转换。
-
-### `group.leave`
-
-主动退出群组。owner 不可退出（须先转让）。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group": { ... }, "left_aid": "alice.agentid.pub" }`
-
-### `group.kick`
-
-踢出成员。需要 admin 及以上权限，不能踢 owner。
-
-**参数**：`group_id` (必填), `aid` (必填)
-
-**响应**：`{ "group": { ... }, "removed_aid": "bob.agentid.pub" }`
-
-### `group.set_role`
-
-设置成员角色。需要 **owner** 权限。
-
-**参数**：`group_id` (必填), `aid` (必填), `role` (`"admin"` / `"member"`)
-
-**响应**：`{ "group": { ... }, "member": { ... } }`
-
+
+### `group.leave`
+
+主动退出群组。owner 不可退出（须先转让）。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group": { ... }, "left_aid": "alice.agentid.pub" }`
+
+### `group.kick`
+
+踢出成员。需要 admin 及以上权限，不能踢 owner。
+
+**参数**：`group_id` (必填), `aid` (必填)
+
+**响应**：`{ "group": { ... }, "removed_aid": "bob.agentid.pub" }`
+
+### `group.set_role`
+
+设置成员角色。需要 **owner** 权限。
+
+**参数**：`group_id` (必填), `aid` (必填), `role` (`"admin"` / `"member"`)
+
+**响应**：`{ "group": { ... }, "member": { ... } }`
+
 ### `group.transfer_owner`
 
-转让群主身份。需要 **owner** 权限。受让方无需手动确认，SDK 自动完成确认和转让收尾。
-
-**参数**：`group_id` (必填), `new_owner` (必填，新群主 AID；别名 `aid` 向后兼容)
-
-**响应**：`{ "group": { ... }, "new_owner_aid": "bob.agentid.pub" }`
-
-### `group.get_members`
-
-获取群成员列表。需要是群成员。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组 ID |
-| `page` | integer | ❌ | 1 | 页码 |
-| `size` | integer | ❌ | 50 | 每页条数 |
-| `role` | string | ❌ | — | 按角色过滤 |
-
-**响应**：`{ "members": [ ... ], "total": 10, "page": 1, "size": 50 }`
-
-### `group.ban`
-
-封禁成员（禁止发消息但保留群成员身份）。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `aid` (必填), `duration_seconds` (integer, 可选，0 表示永久)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "banned_aid": "bob.agentid.pub" }`
-
-### `group.unban`
-
-解除封禁。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `aid` (必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "unbanned_aid": "bob.agentid.pub" }`
-
+发起两阶段群主转让。需要 **owner** 权限，只建立 `pending_rekey`，暂不切换 owner；新 owner 通过 `group.complete_transfer` 提交本人接受证明和新群公钥，完成强制 rekey 后切换 owner，原 owner 降为 admin。旧群证书失效，新身份材料归新 owner；新 owner 按当前代际重新代签、代上传含新 `owner` 的群名片。
+
+**参数**：`group_id` (必填), `new_owner` (必填，新群主 AID；别名 `aid` 向后兼容)
+
+**响应**：`{ "status": "pending_rekey", "requires_ca_rekey": true, "complete_rpc": "group.complete_transfer", "group": { ... }, "new_owner": "bob.agentid.pub" }`。完整参数、旧群身份授权、新 owner 接受证明及幂等规则见 [Group RPC Manual](../sdk/09-group-rpc-manual.md#grouptransfer_owner)。
+
+### `group.complete_transfer`
+
+仅待转移的新 owner 可完成，必须生成新群密钥并提交 `transfer_accept`，禁止同密钥续证代替 rekey。成功状态为 `transferred`；重复提交同一已完成转移可返回原结果。名片发布失败不反向撤销已提交的 owner 切换，SDK 保留新代际原字节和原 CAS 条件恢复上传。服务持久原已验证证书及 transfer nonce/旧 serial CAS，已提交 CA 的可恢复待办超 TTL 仍收敛，未提交 CA 的过期待办拒绝，旧请求不得提交新的转移。
+
+### `group.bind_group_aid` / `group.renew_group_aid`
+
+`bind_group_aid` 为匿名群补齐专属群身份，不是 Ownership 绑定；仅当前 owner 可操作，匹配公钥可幂等重放，不同公钥拒绝。`renew_group_aid` 是当前 owner 主动换钥，必须持有旧群私钥并提交换钥证明；它不替代两阶段 owner 转移。成功后 owner 持有新材料，并用本人身份重新代签、代上传群名片。
+
+### `group.get_members`
+
+获取群成员列表。需要是群成员。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|:----:|--------|------|
+| `group_id` | string | ✅ | — | 群组 ID |
+| `page` | integer | ❌ | 1 | 页码 |
+| `size` | integer | ❌ | 50 | 每页条数 |
+| `role` | string | ❌ | — | 按角色过滤 |
+
+**响应**：`{ "members": [ ... ], "total": 10, "page": 1, "size": 50 }`
+
+### `group.ban`
+
+封禁成员（禁止发消息但保留群成员身份）。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `aid` (必填), `duration_seconds` (integer, 可选，0 表示永久)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "banned_aid": "bob.agentid.pub" }`
+
+### `group.unban`
+
+解除封禁。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `aid` (必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "unbanned_aid": "bob.agentid.pub" }`
+
 ### `group.get_banlist`
-
-获取封禁列表。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填)
-
+
+获取封禁列表。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填)
+
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "items": [ ... ] }`
 
 禁言和屏蔽是独立状态，可以同时设置。禁言禁止发送但不影响接收；屏蔽停止接收但不影响发送。
@@ -399,78 +409,78 @@ SDK 高层建群流程必须支持崩溃恢复：命名群复用已持久化密
 **参数**：`group_id`（必填）
 
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "items": [ { "group_id": "g-abc123.agentid.pub", "aid": "alice.agentid.pub", "online_status": "online", "work_status": "busy", "updated_at": 1234567890000, "last_message_at": 1234567890123, "last_payload_type": "text" } ] }`
-
----
-
-## 10.6 消息方法
-
-### `group.send`
-
-发送群消息。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `type` | string | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
-| `payload` | object | ✅ | 消息内容 |
-| `attachments` | array | ❌ | 存储引用列表 |
-
-##### Payload 参考约定
-
-`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
-
-协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小、信封/封装类型和 E2EE epoch 相关检查；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "message": {
-        "seq": 42,
-        "message_id": "gm-...",
-        "sender_aid": "alice.agentid.pub",
-        "message_type": "text",
-        "payload": { ... },
-        "attachments": [],
-        "created_at": 1234567890123
-    },
-    "event": {
-        "seq": 10,
-        "event_type": "message_created",
-        "actor_aid": "alice.agentid.pub",
-        "data": { "dispatch": { ... } },
-        "created_at": 1234567890123
-    },
-    "dispatch": { ... }
-}
-```
-
-**设计约束**：
+
+---
+
+## 10.6 消息方法
+
+### `group.send`
+
+发送群消息。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `type` | string | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
+| `payload` | object | ✅ | 消息内容 |
+| `attachments` | array | ❌ | 存储引用列表 |
+
+##### Payload 参考约定
+
+`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+
+协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小、信封/封装类型和 E2EE epoch 相关检查；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
+
+**响应**：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "message": {
+        "seq": 42,
+        "message_id": "gm-...",
+        "sender_aid": "alice.agentid.pub",
+        "message_type": "text",
+        "payload": { ... },
+        "attachments": [],
+        "created_at": 1234567890123
+    },
+    "event": {
+        "seq": 10,
+        "event_type": "message_created",
+        "actor_aid": "alice.agentid.pub",
+        "data": { "dispatch": { ... } },
+        "created_at": 1234567890123
+    },
+    "dispatch": { ... }
+}
+```
+
+**设计约束**：
 - 群 `status=suspended` 时仅 owner/admin 可以发送，member 发送会被拒绝
-- 消息 ID 自动生成（格式：`gm-{uuid}`），客户端无需提供
-
-### `group.pull`
-
-增量拉取群消息。事件请用 `group.pull_events` 单独拉取。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|:----:|--------|------|
+- 消息 ID 自动生成（格式：`gm-{uuid}`），客户端无需提供
+
+### `group.pull`
+
+增量拉取群消息。事件请用 `group.pull_events` 单独拉取。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|:----:|--------|------|
 | `group_id` | string | ✅ | — | 群组 ID |
 | `after_message_seq` | integer | ❌ | 0 | 拉取该 seq 之后的消息 |
 | `limit` | integer | ❌ | 50 | 最大条数（最大 50） |
 | `device_id` | string | ❌ | — | 设备 ID（多设备模式） |
 | `window_mode` | string | ❌ | — | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
-
-**响应**：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
+
+**响应**：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
@@ -503,212 +513,220 @@ History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，
 **客户端发布语义**：单个通过校验的 Tail/Forward 响应页内必须按 seq 升序处理，并折叠页内重复 seq。A/T/H 只描述扫描进度，不是应用发布账本；跨 Push/Tail/Forward 页不承诺唯一或有序。全局去重与排序属于应用层业务仓库职责，不是 SDK 交付契约；应用层必须在群 namespace 内按 `message_id` 幂等，并按 `seq` 排序。SDK 进程内折叠只能作为 best-effort 优化。History 不进入实时发布流。
 
 ### `group.ack`
-
-提交已读游标（per-AID，非 per-device）。
-
-**参数**：`group_id` (必填), `seq` (integer, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "aid": "alice.agentid.pub", "ack_seq": 42, "latest_message_seq": 100 }`
-
----
-
-## 10.7 入群方式
-
-### `group.request_join`
-
-申请加入群组（适用于 `join_mode=approval` 的群）。
-
-**参数**：`group_id` (必填), `message` (string, 可选，申请消息), `answer` (string, 可选，回答入群问题)
-
-**响应**：`{ "status": "pending", "request": { ... } }`
-
-### `group.list_join_requests`
-
-列出入群申请。需要 admin 及以上权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组 ID |
-| `status` | string | ❌ | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
-| `page` | integer | ❌ | 1 | 页码 |
-| `size` | integer | ❌ | 50 | 每页条数 |
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "items": [ ... ], "total": 1 }`
-
-### `group.review_join_request`
-
-审批单个入群申请。需要 admin 及以上权限。**以 `aid` 定位申请**（非 request_id）。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `aid` | string | ✅ | 申请人 AID |
-| `approve` | boolean | ❌ | 批准（true）或拒绝（false），默认 true |
-| `reason` | string | ❌ | 拒绝原因 |
-
-**响应**：`{ "request": { ... }, "group": { ... } }`
-
-### `group.batch_review_join_request`
-
-批量审批入群申请。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `aids` (array, 必填), `approve` (boolean, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "results": [ ... ] }`
-
-### `group.get_join_requirements`
-
-获取入群要求配置。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { "mode": "approval", "question": "...", ... } }`
-
-### `group.update_join_requirements`
-
-更新入群要求配置。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `mode` / `question` / `auto_approve_patterns` / `max_pending` (可选)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { ... } }`
-
-### `group.create_invite_code`
-
-创建邀请码。需要 owner/admin 权限，或群规则允许成员邀请。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `code` | string | ❌ | 自定义邀请码，不提供则自动生成 |
-| `max_uses` | integer | ❌ | 最大使用次数，默认 1，必须 > 0 |
-| `expires_in_seconds` | integer | ❌ | 有效期（秒），默认由配置决定（7 天） |
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "invite_code": { ... } }`
-
-### `group.list_invite_codes`
-
-列出群组的邀请码。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `status` (可选，`"active"` / `"expired"` / `"revoked"`)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "items": [ ... ] }`
-
-### `group.use_invite_code`
-
-使用邀请码加入群组。邀请码自动转为小写匹配。
-
-**参数**：`code` (string, 必填)
-
-**响应**：`{ "status": "joined", "group": { ... }, "invite_code": { ... } }`
-
-### `group.revoke_invite_code`
-
-撤销邀请码。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `code` (必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "code": "abc123", "status": "revoked" }`
-
----
-
-## 10.8 公告与规则
-
-### `group.get_announcement`
-
-获取群公告。需要是群成员。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "announcement": { ... } }`
-
-### `group.update_announcement`
-
-更新群公告。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `content` (string, 必填，上限默认 4000 字符), `attachments` (array, 可选)
-
-### `group.get_rules`
-
-获取群规则（可见性设置、加入模式等）。
-
-**参数**：`group_id` (string, 必填)
-
-### `group.update_rules`
-
-更新入群要求。需要 admin 及以上权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
-| `question` | string | ❌ | 入群问题 |
-| `auto_approve_patterns` | array | ❌ | 自动批准正则列表 |
-| `max_pending` | integer | ❌ | 最大待审批数 |
-
----
-
-## 10.9 Group FS
-
-Group FS 是群文件系统的唯一对外模型，所有群文件浏览、创建目录、移动、删除、上传、下载和成员数据挂载都通过 `group.fs.*` 完成；不再提供独立的旧资源引用接口。
-
-### 路径语义
-
-- `group_aid:/memberdata`：系统保留虚拟目录。
-- `group_aid:/memberdata/{member_aid}`：成员挂载槽位，只能通过 `group.fs.mount` / `group.fs.umount` 等受控流程管理。
-- 除 `memberdata` 和其它系统保留路径外，整个群根命名空间都属于群自有区。
-
-### 常用 RPC
-
-| 方法 | 说明 |
-|------|------|
-| `group.fs.ls` / `group.fs.find` | 列目录、查找节点 |
-| `group.fs.stat` / `group.fs.lstat` | 查看节点状态 |
-| `group.fs.mkdir` / `group.fs.rm` | 创建目录、删除节点 |
-| `group.fs.cp` / `group.fs.mv` | 复制、移动或改名 |
-| `group.fs.check_upload` / `group.fs.create_upload_session` / `group.fs.complete_upload` | 上传流程控制面 |
-| `group.fs.create_download_ticket` | 创建下载票据 |
-| `group.fs.mount` / `group.fs.umount` | 管理成员数据挂载 |
-| `group.fs.set_visibility` | 设置群自有区节点可见性 |
-| `group.fs.set_acl` | owner 授予群自有区 `role:admin` 写 ACL |
-| `group.fs.remove_acl` | owner 撤销群自有区 `role:admin` 写 ACL |
-
-### 权限规则
-
-- 群自有区默认 `public` 表示群内公开，当前群成员可读。
-- `private` 节点不再自动授予所有成员读权限，需要显式读授权或下载票据。
-- 群自有区写权限默认授予当前 `group_aid` 证书签名和 `role:owner`；`role:admin` 只有在 group owner 通过 `group.fs.set_acl` 显式授权后才可写。
-- `group.fs.set_acl/remove_acl` 只允许当前 group owner 调用，当前只允许管理 `grantee_aid="role:admin"`；授权和撤销的是角色策略，不与某个 admin 成员绑定，成员升降级、退群、踢出不会联动 ACL。
-- `memberdata` 不受普通群自有区规则覆盖；群主、管理员和 `group_aid` 都不能用普通文件操作删除或改名成员槽位根。
-- 成员写自己的挂载区，本质上写入成员个人 Storage 的群专属目录，由 `group.fs` 映射到 `/memberdata/{member_aid}`。
-
----
-
+
+提交投递消费游标。SDK 的多设备/slot 游标按当前实例隔离；业务已读独立使用 `group.read/read_state`，不能以 ACK 表示用户已经阅读话题。
+
+**参数**：`group_id` (必填), `seq` (integer, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "aid": "alice.agentid.pub", "ack_seq": 42, "latest_message_seq": 100 }`
+
+---
+
+### `group.read` / `group.read_state`
+
+`group.read` 以 `states` 上报当前认证 AID/device 的群话题最后已读消息，每项包含 `group_id`、原样保存的 `topic_key`、`last_read_message_id`；缺省 scope 为 `group`。只有省略 `states` 时兼容顶层单条，显式空数组/null 拒绝；四个已读门面保留显式空值供服务端校验。历史 Group ID 别名解析为 canonical ID，新写状态键、响应和事件使用 canonical ID，历史别名参与事实/公共位置/设备映射的事务查询，权限复用既有版本同步。回执是设备写入结果，不是共享汇总。同域先校验全部项；混合域按所属域逐域校验和提交，任何域失败则 RPC 返回错误，已提交域不回滚，原样幂等重试可收敛。
+
+`group.read_state` 按当前 AID 的 `group_id`、`topic_key` 可选条件查询共享汇总；未指定群时发现本域及远域有权限的成员群。响应 `states` 包含公共 `last_read_order`、当前设备 `current_device_seq` 和 `mapping_status`（resolved/not_received/unresolved）；无映射 seq 为 null。晚到公共位置对仍匹配该消息且 order=0 的事实条件持久回填，不能只更新缓存或覆盖并发前进的事实。网络整数保持 int64 语义，Gateway 本域服务及 federation 回程不得经浮点中转，TS/JS API 超安全整数使用精确十进制字符串。
+
+共享位置已提交并前进后发布 `event/group.read_changed`，SDK 订阅名为 `group.read_changed`，owner 必须非空且为当前身份，scope 必须匹配原事件；Gateway 校验 Kernel 转发的可信 Group 来源，即使显式 route 也只向该 owner AID 分发，支持所属域向该外域成员 AID 转发，不能广播给其他成员。事件 ID 对身份、话题及公共位置组成的 JSON 元组取 SHA-256，失败日志不泄露 topic。事件包含 owner AID、scope、group、topic、消息 ID、公共顺序和更新时间，不进入 Pull 队列。SDK 重连保留原查询过滤范围，通过仅本地发布的 `read_state_sync` 交付本轮状态及逐项错误；身份切换按代际隔离旧缓存及补偿完成事件，A→B→A 也不能接收旧代际结果；原在途 RPC 仍可返回。完整契约见 `aun-sdk-core/docs/跨设备已读未读详细设计.md`。
+
+## 10.7 入群方式
+
+### `group.request_join`
+
+申请加入群组（适用于 `join_mode=approval` 的群）。
+
+**参数**：`group_id` (必填), `message` (string, 可选，申请消息), `answer` (string, 可选，回答入群问题)
+
+**响应**：`{ "status": "pending", "request": { ... } }`
+
+### `group.list_join_requests`
+
+列出入群申请。需要 admin 及以上权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|:----:|--------|------|
+| `group_id` | string | ✅ | — | 群组 ID |
+| `status` | string | ❌ | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
+| `page` | integer | ❌ | 1 | 页码 |
+| `size` | integer | ❌ | 50 | 每页条数 |
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "items": [ ... ], "total": 1 }`
+
+### `group.review_join_request`
+
+审批单个入群申请。需要 admin 及以上权限。**以 `aid` 定位申请**（非 request_id）。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `aid` | string | ✅ | 申请人 AID |
+| `approve` | boolean | ❌ | 批准（true）或拒绝（false），默认 true |
+| `reason` | string | ❌ | 拒绝原因 |
+
+**响应**：`{ "request": { ... }, "group": { ... } }`
+
+### `group.batch_review_join_request`
+
+批量审批入群申请。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `aids` (array, 必填), `approve` (boolean, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "results": [ ... ] }`
+
+### `group.get_join_requirements`
+
+获取入群要求配置。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { "mode": "approval", "question": "...", ... } }`
+
+### `group.update_join_requirements`
+
+更新入群要求配置。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `mode` / `question` / `auto_approve_patterns` / `max_pending` (可选)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { ... } }`
+
+### `group.create_invite_code`
+
+创建邀请码。需要 owner/admin 权限，或群规则允许成员邀请。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `code` | string | ❌ | 自定义邀请码，不提供则自动生成 |
+| `max_uses` | integer | ❌ | 最大使用次数，默认 1，必须 > 0 |
+| `expires_in_seconds` | integer | ❌ | 有效期（秒），默认由配置决定（7 天） |
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "invite_code": { ... } }`
+
+### `group.list_invite_codes`
+
+列出群组的邀请码。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `status` (可选，`"active"` / `"expired"` / `"revoked"`)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "items": [ ... ] }`
+
+### `group.use_invite_code`
+
+使用邀请码加入群组。邀请码自动转为小写匹配。
+
+**参数**：`code` (string, 必填)
+
+**响应**：`{ "status": "joined", "group": { ... }, "invite_code": { ... } }`
+
+### `group.revoke_invite_code`
+
+撤销邀请码。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `code` (必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "code": "abc123", "status": "revoked" }`
+
+---
+
+## 10.8 公告与规则
+
+### `group.get_announcement`
+
+获取群公告。需要是群成员。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "announcement": { ... } }`
+
+### `group.update_announcement`
+
+更新群公告。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `content` (string, 必填，上限默认 4000 字符), `attachments` (array, 可选)
+
+### `group.get_rules`
+
+获取群规则（可见性设置、加入模式等）。
+
+**参数**：`group_id` (string, 必填)
+
+### `group.update_rules`
+
+更新入群要求。需要 admin 及以上权限。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
+| `question` | string | ❌ | 入群问题 |
+| `auto_approve_patterns` | array | ❌ | 自动批准正则列表 |
+| `max_pending` | integer | ❌ | 最大待审批数 |
+
+---
+
+## 10.9 Group FS
+
+Group FS 是群文件系统的唯一对外模型，所有群文件浏览、创建目录、移动、删除、上传、下载和成员数据挂载都通过 `group.fs.*` 完成；不再提供独立的旧资源引用接口。
+
+### 路径语义
+
+- `group_aid:/memberdata`：系统保留虚拟目录。
+- `group_aid:/memberdata/{member_aid}`：成员挂载槽位，只能通过 `group.fs.mount` / `group.fs.umount` 等受控流程管理。
+- 除 `memberdata` 和其它系统保留路径外，整个群根命名空间都属于群自有区。
+
+### 常用 RPC
+
+| 方法 | 说明 |
+|------|------|
+| `group.fs.ls` / `group.fs.find` | 列目录、查找节点 |
+| `group.fs.stat` / `group.fs.lstat` | 查看节点状态 |
+| `group.fs.mkdir` / `group.fs.rm` | 创建目录、删除节点 |
+| `group.fs.cp` / `group.fs.mv` | 复制、移动或改名 |
+| `group.fs.check_upload` / `group.fs.create_upload_session` / `group.fs.complete_upload` | 上传流程控制面 |
+| `group.fs.create_download_ticket` | 创建下载票据 |
+| `group.fs.mount` / `group.fs.umount` | 管理成员数据挂载 |
+| `group.fs.set_visibility` | 设置群自有区节点可见性 |
+| `group.fs.set_acl` | owner 授予群自有区 `role:admin` 写 ACL |
+| `group.fs.remove_acl` | owner 撤销群自有区 `role:admin` 写 ACL |
+
+### 权限规则
+
+- 群自有区默认 `public` 表示群内公开，当前群成员可读。
+- `private` 节点不再自动授予所有成员读权限，需要显式读授权或下载票据。
+- 群自有区写权限默认授予当前 `group_aid` 证书签名和 `role:owner`；`role:admin` 只有在 group owner 通过 `group.fs.set_acl` 显式授权后才可写。
+- `group.fs.set_acl/remove_acl` 只允许当前 group owner 调用，当前只允许管理 `grantee_aid="role:admin"`；授权和撤销的是角色策略，不与某个 admin 成员绑定，成员升降级、退群、踢出不会联动 ACL。
+- `memberdata` 不受普通群自有区规则覆盖；群主、管理员和 `group_aid` 都不能用普通文件操作删除或改名成员槽位根。
+- 成员写自己的挂载区，本质上写入成员个人 Storage 的群专属目录，由 `group.fs` 映射到 `/memberdata/{member_aid}`。
+
+---
+
 ## 10.12 在线状态与群内成员状态
-
-群组在线状态是 per-AID 的全局状态（非 per-group）。在线索引由 Gateway 的 `client.online` / `client.offline` 事件驱动，Group 服务消费这些事件维护在线状态；客户端不需要也不能调用单独的上线、下线或心跳 RPC。
-
-### `group.get_online_members`
-
-查询群内在线成员列表。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "members": [ ... ], "items": [ ... ], "online_members": [ ... ], "online_count": 2, "total": 10, "page": 1, "size": 10 }`
-
+
+群组在线状态是 per-AID 的全局状态（非 per-group）。在线索引由 Gateway 的 `client.online` / `client.offline` 事件驱动，Group 服务消费这些事件维护在线状态；客户端不需要也不能调用单独的上线、下线或心跳 RPC。
+
+### `group.get_online_members`
+
+查询群内在线成员列表。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "members": [ ... ], "items": [ ... ], "online_members": [ ... ], "online_count": 2, "total": 10, "page": 1, "size": 10 }`
+
 字段约定：`members` 是主字段；`items` 和 `online_members` 是兼容别名，内容与 `members` 完全相同。
 
 `group.get_online_members` 返回 Gateway 在线索引中的全局连接状态。`group.report_status` / `group.get_member_statuses` 管理成员在单个群内主动上报的在线/工作状态及最后发言摘要，两套状态来源相互独立。
-
----
-
+
+---
+
 ## 10.13 群设置与 `group.index`
 
 `group.set_settings` / `group.get_settings` 是群公告、群规则、入群要求、提及过滤模式等群级设置的统一 RPC。`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引 JSONL。
@@ -740,120 +758,121 @@ Group FS 是群文件系统的唯一对外模型，所有群文件浏览、创
 ---
 
 ## 10.14 事件
-
-Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
-
-### `event/group.created`
-
-群组创建时推送给群主。
-
-```json
-{
-    "module_id": "group",
-    "group_id": "g-abc123.agentid.pub",
-    "owner_aid": "alice.agentid.pub",
-    "visibility": "private"
-}
-```
-
-### `event/group.changed`
-
-群组状态变化时推送给所有成员。
-
-```json
-{
-    "module_id": "group",
-    "action": "member_added",
-    "group_id": "g-abc123.agentid.pub"
-}
-```
-
-| `action` 值 | 说明 |
-|-------------|------|
-| `upsert` | 群组创建/更新 |
-| `update` | 群组信息更新 |
-| `member_added` | 成员加入 |
-| `member_left` | 成员退出 |
-| `member_removed` | 成员被踢出 |
-| `role_changed` | 角色变更 |
-| `owner_transferred` | 群主转让 |
-| `rules_updated` | 规则更新 |
-| `announcement_updated` | 公告更新 |
-| `join_requested` | 收到入群申请 |
-| `joined` | 成员加入（通过邀请码等） |
-| `join_approved` | 入群申请批准 |
-| `join_rejected` | 入群申请拒绝 |
-| `join_requirements_updated` | 入群要求配置更新 |
-| `invite_code_created` | 邀请码创建 |
-| `invite_code_used` | 邀请码使用 |
-| `invite_code_revoked` | 邀请码撤销 |
+
+Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
+
+### `event/group.created`
+
+群组创建时推送给群主。
+
+```json
+{
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "owner_aid": "alice.agentid.pub",
+    "visibility": "private"
+}
+```
+
+### `event/group.changed`
+
+群组状态变化时推送给所有成员。
+
+```json
+{
+    "module_id": "group",
+    "action": "member_added",
+    "group_id": "g-abc123.agentid.pub"
+}
+```
+
+| `action` 值 | 说明 |
+|-------------|------|
+| `upsert` | 群组创建/更新 |
+| `update` | 群组信息更新 |
+| `member_added` | 成员加入 |
+| `member_left` | 成员退出 |
+| `member_removed` | 成员被踢出 |
+| `role_changed` | 角色变更 |
+| `owner_transfer_rekey_pending` | 群主转让已发起，等待新 owner 完成强制换钥与确认 |
+| `owner_transferred` | 强制 rekey 后群主转让完成 |
+| `rules_updated` | 规则更新 |
+| `announcement_updated` | 公告更新 |
+| `join_requested` | 收到入群申请 |
+| `joined` | 成员加入（通过邀请码等） |
+| `join_approved` | 入群申请批准 |
+| `join_rejected` | 入群申请拒绝 |
+| `join_requirements_updated` | 入群要求配置更新 |
+| `invite_code_created` | 邀请码创建 |
+| `invite_code_used` | 邀请码使用 |
+| `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员被封禁 |
 | `member_unbanned` | 成员解除封禁 |
 | `member_blocked` | 成员被屏蔽 |
 | `member_unblocked` | 成员取消屏蔽 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
-| `fs_updated` | Group FS 节点更新 |
-| `fs_visibility_updated` | Group FS 可见性更新 |
-| `fs_deleted` | Group FS 节点删除 |
-
-### `event/group.message_created`
-
-群内新消息时推送给所有在线成员。支持两种模式：
-
-**消息推送模式**（带 `payload`）：事件包含完整消息体，SDK 自动解密后直接交付用户。
-
-```json
-{
-    "module_id": "group",
-    "group_id": "g-abc123.agentid.pub",
-    "seq": 42,
-    "message_id": "550e8400-...",
-    "sender_aid": "alice.agentid.pub",
-    "type": "e2ee.group_encrypted",
-    "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
-    "dispatch": { "mode": "broadcast", "reason": "duty_disabled" },
-    "kind": "group.broadcast",
-    "member_aids": ["bob.agentid.pub", "carol.agentid.pub"]
-}
-```
-
-**通知模式**（不带 `payload`）：仅包含元数据，SDK 收到后自动调用 `group.pull` 拉取最新消息。
-
-```json
-{
-    "module_id": "group",
-    "group_id": "g-abc123.agentid.pub",
-    "seq": 42,
-    "message_id": "550e8400-...",
-    "sender_aid": "alice.agentid.pub",
-    "type": "e2ee.group_encrypted",
-    "dispatch": { "mode": "broadcast", "reason": "duty_disabled" },
-    "member_aids": ["bob.agentid.pub", "carol.agentid.pub"]
-}
-```
-
-> **SDK 行为**：`payload.type == "e2ee.group_encrypted"` 时自动 E2EE 解密；`payload` 缺失时自动 pull；其他情况原样透传。
-
----
-
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
+| `fs_updated` | Group FS 节点更新 |
+| `fs_visibility_updated` | Group FS 可见性更新 |
+| `fs_deleted` | Group FS 节点删除 |
+
+### `event/group.message_created`
+
+群内新消息时推送给所有在线成员。支持两种模式：
+
+**消息推送模式**（带 `payload`）：事件包含完整消息体，SDK 自动解密后直接交付用户。
+
+```json
+{
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 42,
+    "message_id": "550e8400-...",
+    "sender_aid": "alice.agentid.pub",
+    "type": "e2ee.group_encrypted",
+    "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
+    "dispatch": { "mode": "broadcast", "reason": "duty_disabled" },
+    "kind": "group.broadcast",
+    "member_aids": ["bob.agentid.pub", "carol.agentid.pub"]
+}
+```
+
+**通知模式**（不带 `payload`）：仅包含元数据，SDK 收到后自动调用 `group.pull` 拉取最新消息。
+
+```json
+{
+    "module_id": "group",
+    "group_id": "g-abc123.agentid.pub",
+    "seq": 42,
+    "message_id": "550e8400-...",
+    "sender_aid": "alice.agentid.pub",
+    "type": "e2ee.group_encrypted",
+    "dispatch": { "mode": "broadcast", "reason": "duty_disabled" },
+    "member_aids": ["bob.agentid.pub", "carol.agentid.pub"]
+}
+```
+
+> **SDK 行为**：`payload.type == "e2ee.group_encrypted"` 时自动 E2EE 解密；`payload` 缺失时自动 pull；其他情况原样透传。
+
+---
+
 ## 10.15 错误码
-
-| 错误码 | 说明 | 客户端处理 |
-|--------|------|-----------|
-| -32601 | Method not found | 检查方法名 |
-| -32602 | Invalid params（如缺少 group_id） | 检查参数 |
-| -32004 | Permission denied（权限不足） | 提示用户，不重试 |
-| -32001 | Authentication failed | 重新认证 |
-| -33001 | Group not found | 检查 group_id |
-| -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
-| -33003 | Group suspended | 等待恢复或联系管理员 |
-| -33004 | Group member limit reached | 不重试 |
-| -33005 | Already a member | 无需处理 |
-| -33006 | Not a member | 先加入群组 |
-| -33007 | Role insufficient（权限不足） | 检查角色 |
-| -33008 | Invite code invalid or expired | 获取新邀请码 |
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32601 | Method not found | 检查方法名 |
+| -32602 | Invalid params（如缺少 group_id） | 检查参数 |
+| -32004 | Permission denied（权限不足） | 提示用户，不重试 |
+| -32001 | Authentication failed | 重新认证 |
+| -33001 | Group not found | 检查 group_id |
+| -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
+| -33003 | Group suspended | 等待恢复或联系管理员 |
+| -33004 | Group member limit reached | 不重试 |
+| -33005 | Already a member | 无需处理 |
+| -33006 | Not a member | 先加入群组 |
+| -33007 | Role insufficient（权限不足） | 检查角色 |
+| -33008 | Invite code invalid or expired | 获取新邀请码 |
 | -33009 | Join rejected | 不重试 |
 
 `group.index etag conflict` 表示 `expected_index_etag` 与服务端当前 `group.index` etag 不一致。客户端应重新读取 `group.index`，在最新 index 上合并本地修改并重新签名后再提交。
@@ -866,8 +885,8 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 - **group.index 由 SDK 生成**：Group 服务只校验、CAS 保存和注入 meta，不根据 DB 状态拼装 `group.index`。
 - **Gateway/Message 不承载 group.index 业务语义**：只能转发或合并 `_meta`，不能生成或改写 `_meta.group_indexes`。
 - **消息 seq 单调递增**：per-group 粒度，确保顺序一致性，`ack_seq` 仅增不减。
-- **事件 seq 独立计数**：`event_seq` 与 `message_seq` 独立；消息增量拉取使用 `group.pull`，事件增量拉取使用 `group.pull_events`。
-- **duty 模式**：`duty_mode` 非 `"none"` 且 `duty_human_message_policy = "dispatch"` 时，消息先推送给当班成员处理，回复后再广播；`group.pull` 始终可拉取全量消息。
-- **Group FS**：群文件能力统一由 `group.fs.*` 提供；不再提供独立资源审批 RPC。
-- **在线状态**：通过 `group.get_online_members` 查询当前在线成员列表。
-- **Group FS 系统目录保护**：`memberdata` 是 Group FS 视图层的虚拟系统目录；根节点和成员槽位根不得被普通文件操作删除、覆盖或重命名。成员槽位子路径映射到成员个人 Storage 的 `group_data/{group_aid}`，只能通过 `group.fs.*` 间接访问。完整保护规则见 [16-系统目录保护方案.md](16-系统目录保护方案.md)。
+- **事件 seq 独立计数**：`event_seq` 与 `message_seq` 独立；消息增量拉取使用 `group.pull`，事件增量拉取使用 `group.pull_events`。
+- **duty 模式**：`duty_mode` 非 `"none"` 且 `duty_human_message_policy = "dispatch"` 时，消息先推送给当班成员处理，回复后再广播；`group.pull` 始终可拉取全量消息。
+- **Group FS**：群文件能力统一由 `group.fs.*` 提供；不再提供独立资源审批 RPC。
+- **在线状态**：通过 `group.get_online_members` 查询当前在线成员列表。
+- **Group FS 系统目录保护**：`memberdata` 是 Group FS 视图层的虚拟系统目录；根节点和成员槽位根不得被普通文件操作删除、覆盖或重命名。成员槽位子路径映射到成员个人 Storage 的 `group_data/{group_aid}`，只能通过 `group.fs.*` 间接访问。完整保护规则见 [16-系统目录保护方案.md](16-系统目录保护方案.md)。