@agentunion/fastaun-browser 0.5.3 → 0.5.6

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

@@ -58,7 +58,7 @@
 
 | 方法 | 说明 |
 |------|------|
-| [group.set_settings](#groupset_settings) | 统一设置群参数，含 `dispatch_mode` |
+| [group.set_settings](#groupset_settings) | 统一设置群参数，含 `mention_mode` |
 | [group.get_settings](#groupget_settings) | 统一读取群参数 |
 
 ### 消息
@@ -70,6 +70,7 @@
 | [group.thought.put](#groupthoughtput) | 写入某个群上下文的思考内容 |
 | [group.thought.get](#groupthoughtget) | 获取某个群上下文的思考内容 |
 | [group.pull](#grouppull) | 增量拉取消息 |
+| [group.history](#grouphistory) | 向前只读翻页群消息 |
 | [group.pull_events](#grouppull_events) | 增量拉取事件 |
 | [group.ack](#groupack) | 确认已读（旧接口，等同 ack_messages） |
 | [group.ack_messages](#groupack_messages) | 确认消息游标 |
@@ -100,10 +101,10 @@
 
 | 方法 | 说明 |
 |------|------|
-| [group.set_settings](#groupset_settings) | 统一设置群参数（含公告、规则、入群要求、dispatch_mode 等） |
+| [group.set_settings](#groupset_settings) | 统一设置群参数（含公告、规则、入群要求、mention_mode 等） |
 | [group.get_settings](#groupget_settings) | 统一读取群参数 |
 
-**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`）。读取方法优先返回 SDK 本地缓存，本地没有对应值时才调用 `get_settings` 初始化；即使观察到远端 etag 不一致也不会自动 pull 远端。indexed 写入方法内部调用 `updateGroupIndex` 生成签名 `group.index` 并通过 `set_settings` CAS 提交。
+**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`），并提供通用文档型方法（`getSettingWithIndex`/`updateSettingWithIndex`，Python 为 `get_setting_with_index`/`update_setting_with_index`，Go 为 `GetSettingWithIndex`/`UpdateSettingWithIndex`）。读取方法优先返回 SDK 本地缓存，本地没有对应值时才调用 `get_settings` 初始化；即使观察到远端 etag 不一致也不会自动 pull 远端。indexed 写入方法内部调用 `updateGroupIndex` 生成签名 `group.index` 并通过 `set_settings` CAS 提交。
 
 ### 群文件系统
 
@@ -137,17 +138,17 @@
 
 ---
 
-## Group AID / Group ID 兼容规范
-
-目标态群组主标识是 `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 参数名继续保留，但语义上只是兼容字段。
-
-SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_aid` / `groupAid` 统一规范化为 `group_aid`。裸客户端也应使用同一 `group_aid` 生成签名材料和 E2EE AAD，避免同一群的历史别名产生不同材料。服务端响应可能同时返回 `group_id` 和 `group_aid`；新代码应优先读取 `group_aid`，仅兼容旧版本或历史数据时回退读取 `group_id`。
-
-兼容输入包括目标态 `{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 简写链接可继续由服务端兼容解析。
+## Group AID / Group ID 兼容规范
+
+目标态群组主标识是 `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 参数名继续保留，但语义上只是兼容字段。
+
+SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_aid` / `groupAid` 统一规范化为 `group_aid`。裸客户端也应使用同一 `group_aid` 生成签名材料和 E2EE AAD，避免同一群的历史别名产生不同材料。服务端响应可能同时返回 `group_id` 和 `group_aid`；新代码应优先读取 `group_aid`，仅兼容旧版本或历史数据时回退读取 `group_id`。
+
+兼容输入包括目标态 `{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 简写链接可继续由服务端兼容解析。
 
 ---
 
@@ -155,16 +156,16 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.create
 
-创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | string | 是 | 群组显示名称 |
-| `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}` |
+| `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"`，默认由配置决定 |
@@ -181,8 +182,8 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 ```json
 {
     "group": {
-        "group_id": "my-team.agentid.pub",
-        "group_aid": "my-team.agentid.pub",
+        "group_id": "my-team.agentid.pub",
+        "group_aid": "my-team.agentid.pub",
         "name": "测试群",
         "owner_aid": "alice.agentid.pub",
         "creator_aid": "alice.agentid.pub",
@@ -193,9 +194,9 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
         "member_count": 1,
         "message_seq": 0,
         "event_seq": 0,
-        "group_url": "https://group.agentid.pub/my-team.agentid.pub",
-        "created_at": 1234567890000,
-        "updated_at": 1234567890000
+        "group_url": "https://group.agentid.pub/my-team.agentid.pub",
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000
     },
     "aid_cert": {
         "cert": "-----BEGIN CERTIFICATE-----...",
@@ -207,9 +208,9 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 }
 ```
 
-> `aid_cert` 仅在命名群创建时返回。`group_aid` 是新代码应使用的主标识；`group_id` 为兼容字段，新群通常与 `group_aid` 相同，历史群可能保留旧存储值。
-
-**标识格式**：目标态为 `{base}.{issuer-domain}`。旧格式 `group.{issuer-domain}/{base}`、`{base}@{issuer-domain}` 会在 API 边界转换为目标态 `group_aid`。
+> `aid_cert` 仅在命名群创建时返回。`group_aid` 是新代码应使用的主标识；`group_id` 为兼容字段，新群通常与 `group_aid` 相同，历史群可能保留旧存储值。
+
+**标识格式**：目标态为 `{base}.{issuer-domain}`。旧格式 `group.{issuer-domain}/{base}`、`{base}@{issuer-domain}` 会在 API 边界转换为目标态 `group_aid`。
 
 ### group.bind_aid
 
@@ -219,7 +220,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `group_name` | string | 是 | 命名群标识，4-64 字符，`[a-z0-9_-]+` |
 | `public_key` | string | 是 | 群公钥（base64 编码） |
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
@@ -241,7 +242,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `required` | string[] | 否 | 受限字段声明：`member`、`state`、`e2ee`、`avatar` |
 
 **默认响应**：
@@ -256,7 +257,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
     "status": "active",
     "description": "技术讨论群",
     "member_count": 42,
-    "created_at": 1234567890000
+    "created_at": 1234567890000
 }
 ```
 
@@ -272,7 +273,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `name` | string | 否 | 新名称 |
 | `visibility` | string | 否 | 新可见性 |
 | `description` | string | 否 | 新描述 |
@@ -301,7 +302,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
             "name": "项目讨论",
             "visibility": "private",
             "member_count": 5,
-            "updated_at": 1234567890000,
+            "updated_at": 1234567890000,
             "role": "owner"
         }
     ],
@@ -343,7 +344,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 暂停群组。暂停期间不能发送消息。需要 **admin 及以上**权限。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -360,7 +361,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 恢复暂停的群组。需要 **admin 及以上**权限。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -377,7 +378,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 永久解散群组。不可恢复。需要 **owner** 权限。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -401,7 +402,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要添加的 AID |
 | `role` | string | 否 | `"admin"` / `"member"`，默认 `"member"` |
 | `member_type` | string | 否 | `"human"` / `"ai"`，默认 `"human"` |
@@ -415,7 +416,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
         "aid": "bob.agentid.pub",
         "role": "member",
         "member_type": "human",
-        "joined_at": 1234567890000
+        "joined_at": 1234567890000
     }
 }
 ```
@@ -428,7 +429,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | 50 | 每页条数（最大 200） |
 | `role` | string | 否 | — | 按角色过滤（owner/admin/member） |
@@ -444,9 +445,9 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890000,
+            "joined_at": 1234567890000,
             "last_ack_seq": 100,
-            "last_pull_at": 1234567890000
+            "last_pull_at": 1234567890000
         }
     ],
     "total": 1,
@@ -464,7 +465,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要踢出的 AID |
 
 **响应**：
@@ -480,7 +481,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 主动退出群组。owner 不能直接退群，需先转让群主。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -493,13 +494,13 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.set_role
 
-设置成员角色。需要 **owner** 权限。不能改变 owner 角色。该 RPC 只改变 membership 中的角色事实，不授予或撤销群自有区写 ACL；`role:admin` 是否可写群自有区由 `group.fs.set_acl` / `group.fs.remove_acl` 显式控制。
+设置成员角色。`owner` 可将普通成员设为 `admin`，也可将 `admin` 设回 `member`；`admin` 不能修改其它成员角色，只能将自己的角色降为 `member`。不能通过 `group.set_role` 改变 `owner` 角色；群主只在建群或 `group.transfer_owner` 中变更。该 RPC 改变 membership 中的角色事实；`owner/admin` 默认拥有群自有区写权限，`member` 默认没有写权限。成员级群协作目录应通过 `group.fs.set_acl` 显式授予 `role:member` 的 `rw` 权限。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 目标 AID |
 | `role` | string | 是 | `"admin"` / `"member"` |
 
@@ -513,7 +514,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
         "aid": "bob.agentid.pub",
         "role": "admin",
         "member_type": "human",
-        "joined_at": 1234567890000,
+        "joined_at": 1234567890000,
         "last_ack_seq": 0,
         "last_pull_at": 0
     },
@@ -532,7 +533,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `new_owner` | string | 是 | 新群主 AID（也接受 `aid`） |
 
 **响应**：
@@ -558,7 +559,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `public_key` | string | 是 | 公钥 DER base64（SPKI 格式） |
 | `curve` | string | 否 | 曲线名称（默认 P-256） |
 
@@ -567,7 +568,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 ```json
 {
     "group": {
-        "group_id": "my-team.agentid.pub",
+        "group_id": "my-team.agentid.pub",
         "group_aid": "my-team.agentid.pub",
         ...
     },
@@ -602,7 +603,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `group_aid` | string | 否 | 群身份 AID（可选，服务端可推导） |
 | `old_public_key` | string | 是 | 旧公钥 DER base64 |
 | `new_public_key` | string | 是 | 新公钥 DER base64 |
@@ -632,7 +633,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 ```json
 {
     "group": {
-        "group_id": "my-team.agentid.pub",
+        "group_id": "my-team.agentid.pub",
         "group_aid": "my-team.agentid.pub",
         ...
     },
@@ -660,7 +661,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `subject` | string | 是 | 要封禁的 AID（也接受 `aid`） |
 | `reason` | string | 否 | 封禁原因 |
 | `expires_at` | integer | 否 | 过期时间戳（0 = 永久） |
@@ -677,7 +678,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
         "banned_by": "alice.agentid.pub",
         "reason": "垃圾消息",
         "expires_at": 0,
-        "created_at": 1234567890000
+        "created_at": 1234567890000
     }
 }
 ```
@@ -686,7 +687,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 解除封禁。需要 **admin 及以上**权限。
 
-**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`subject` 或 `aid` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`subject` 或 `aid` (string)
 
 **响应**：
 
@@ -702,7 +703,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 获取封禁列表。需要 **admin 及以上**权限。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -716,7 +717,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
             "banned_by": "alice.agentid.pub",
             "reason": "垃圾消息",
             "expires_at": 0,
-            "created_at": 1234567890000
+            "created_at": 1234567890000
         }
     ],
     "total": 1,
@@ -737,7 +738,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message` | string | 否 | 申请留言 |
 | `answer` | string | 否 | 入群问题的答案 |
 
@@ -773,8 +774,8 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
         "message": "请加我",
         "answer": "...",
         "status": "pending",
-        "created_at": 1234567890000,
-        "updated_at": 1234567890000,
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000,
         "expires_at": 1234654290,
         "reviewed_by": null,
         "rejection_reason": null
@@ -790,7 +791,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `status` | string | 否 | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | — | 每页数量 |
@@ -806,8 +807,8 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
             "aid": "carol.agentid.pub",
             "message": "请加我",
             "status": "pending",
-            "created_at": 1234567890000,
-            "updated_at": 1234567890000
+            "created_at": 1234567890000,
+            "updated_at": 1234567890000
         }
     ],
     "total": 1,
@@ -824,7 +825,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 申请人 AID |
 | `approve` | boolean | 否 | 批准或拒绝，默认 `true` |
 | `reason` | string | 否 | 拒绝原因 |
@@ -862,7 +863,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `requests` | array | 是 | 审批列表 |
 
 `requests` 数组每项：
@@ -894,7 +895,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `code` | string | 否 | 自定义邀请码（不提供则自动生成） |
 | `max_uses` | integer | 否 | 最大使用次数，默认 1，必须 > 0 |
 | `expires_in_seconds` | integer | 否 | 有效期（秒），默认由 invite_code_ttl_days 配置（7 天） |
@@ -912,7 +913,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
         "max_uses": 10,
         "used_count": 0,
         "status": "active",
-        "created_at": 1234567890000
+        "created_at": 1234567890000
     }
 }
 ```
@@ -937,13 +938,13 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 列出群组的邀请码。需要 admin 权限。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 ### group.revoke_invite_code
 
 撤销邀请码。需要 admin 权限。
 
-**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`code` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`code` (string)
 
 ---
 
@@ -951,23 +952,28 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 ### group.set_settings
 
-统一写入群参数。需要 admin 及以上权限。`dispatch_mode` 是群消息的应用层分发模式标签，会随 `group.send` 生成的消息持久化，并由 SDK 在解密后注入到消息顶层和 `payload.dispatch_mode`。
-
-`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引。更新 indexed settings 时必须同包提交新的签名 `group.index`，并通过 `expected_index_etag` 做 CAS。
+统一写入群参数。需要 admin 及以上权限。`mention_mode` 是群消息的应用层提及过滤模式标签，会随 `group.send` 生成的消息持久化，并由 SDK 在解密后注入到消息顶层和对象 `payload.mention_mode`。
 
-`dispatch_mode` 不是 `group.send` 的单次入参；要修改后续消息的模式，请通过 `group.set_settings` 更新群设置。
+`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引。更新 indexed settings 时必须同包提交新的签名 `group.index`，并通过 `expected_index_etag` 做 CAS。
+
+`mention_mode` 不是 `group.send` 的单次入参；要修改后续消息的模式，请通过 `group.set_settings` 更新群设置。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `settings` | object | 是 | 要写入的设置键值 |
-| `expected_index_etag` | string | 写 `group.index` 时必填 | CAS 期望旧 etag；空字符串表示只允许创建首个 `group.index` |
-| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
-| `settings["rules.content"]` | string | 否 | 群规则正文 |
-| `settings["announcement.content"]` | string | 否 | 群公告正文 |
-| `settings["group.index"]` | object | 更新 indexed settings 时必填 | 签名 group index，当前结构至少包含 `body` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `settings` | object | 是 | 要写入的设置键值 |
+| `expected_index_etag` | string | 写 `group.index` 时必填 | CAS 期望旧 etag；空字符串表示只允许创建首个 `group.index` |
+| `settings["mention_mode"]` | string | 否 | `"disabled"` / `"mention-only"`，默认 `"disabled"`；服务端兼容旧名和值 |
+| `settings["rules.content"]` | string | 否 | 群规则正文 |
+| `settings["rules.attachments"]` | array | 否 | 群规则附件稳定引用 |
+| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `settings["announcement.attachments"]` | array | 否 | 群公告附件稳定引用 |
+| `settings["join.attachments"]` | array | 否 | 入群要求附件稳定引用 |
+| `settings["{keyName}.content"]` | string | 否 | 通用文档型 indexed setting 正文；`keyName` 需满足受控命名规则 |
+| `settings["{keyName}.attachments"]` | array | 否 | 通用文档型 indexed setting 附件稳定引用 |
+| `settings["group.index"]` | object | 更新 indexed settings 时必填 | 签名 group index，当前结构至少包含 `body` |
 
 **预定义群级参数**：
 
@@ -983,116 +989,120 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 | `join.mode` | string | 按 `visibility` 推导：`public -> open`，`private -> approval` | 入群模式：`"open"` / `"approval"` / `"invite_only"` / `"closed"` |
 | `join.question` | string | `""` | 入群问题 |
 | `join.auto_approve_patterns` | array | `[]` | 自动批准 AID 匹配规则 |
-| `join.max_pending` | integer | `100` | 最大待审批入群申请数 |
-| `dispatch_mode` | string | `"broadcast"` | 群消息分发标签：`"broadcast"` / `"mention"`；未显式设置时 `get_settings` 仍返回默认值 |
-| `group.index` | object | — | 保留 key；签名 JSONL 群索引，由 SDK 生成，服务端只校验、CAS 保存和返回 |
-
-**indexed settings**：
-
-| key | 说明 |
-|-----|------|
-| `rules.content` / `rules.attachments` | 群规则正文与附件稳定引用 |
-| `announcement.content` / `announcement.attachments` | 群公告正文与附件稳定引用 |
-| `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` | 入群要求配置 |
-
-写入规则：
-
-- 只更新非 indexed settings 时，继续直接调用 `set_settings`，不需要 `group.index`。
-- 更新任意 indexed setting 时，必须在同一次 `settings` 中携带签名 `group.index`。
-- 写入 `group.index` 时必须传 `expected_index_etag`。
-- 服务端在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`。
-- CAS 失败时错误消息包含 `group.index etag conflict`；SDK 的 `updateGroupIndex` 会重新读取当前 index、重建签名并按 `max_attempts` 重试。
-
-```python
-await client.call("group.set_settings", {
+| `join.max_pending` | integer | `100` | 最大待审批入群申请数 |
+| `join.attachments` | array | `[]` | 入群材料附件稳定引用 |
+| `mention_mode` | string | `"disabled"` | 群消息提及过滤标签：`"disabled"` / `"mention-only"`；未显式设置时 `get_settings` 仍返回默认值 |
+| `group.index` | object | — | 保留 key；签名 JSONL 群索引，由 SDK 生成，服务端只校验、CAS 保存和返回 |
+
+**indexed settings**：
+
+| key | 说明 |
+|-----|------|
+| `rules.content` / `rules.attachments` | 群规则正文与附件稳定引用 |
+| `announcement.content` / `announcement.attachments` | 群公告正文与附件稳定引用 |
+| `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` / `join.attachments` | 入群要求配置与附件稳定引用 |
+| `{keyName}.content` / `{keyName}.attachments` | 通用文档型设置正文与附件稳定引用 |
+
+写入规则：
+
+- 只更新非 indexed settings 时，继续直接调用 `set_settings`，不需要 `group.index`。
+- 更新任意 indexed setting 时，必须在同一次 `settings` 中携带签名 `group.index`。
+- 服务端只接受受控动态文档 key：`{keyName}.content` / `{keyName}.attachments`，其中 `keyName` 匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀。调用方不能用该机制写任意 settings key。
+- 写入 `group.index` 时必须传 `expected_index_etag`。
+- 服务端在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`。
+- CAS 失败时错误消息包含 `group.index etag conflict`；SDK 的 `updateGroupIndex` 会重新读取当前 index、重建签名并按 `max_attempts` 重试。
+- `rules.attachments`、`announcement.attachments`、`join.attachments` 和 `{keyName}.attachments` 只保存附件引用；附件实体应先写入群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。群自有区默认允许 `owner/admin` 写入，`member` 默认不可写；`.group/` 是系统控制目录，不允许授予 `role:member` 写权限。
+
+```python
+await client.call("group.set_settings", {
     "group_id": "g-abc123.agentid.pub",
-    "settings": {"dispatch_mode": "mention"},
+    "settings": {"mention_mode": "mention-only"},
 })
 ```
 
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group_aid": "g-abc123.agentid.pub",
-    "updated_keys": ["dispatch_mode"]
-}
-```
-
-写入 `group.index` 成功时，响应顶层会强制携带 `_meta.group_indexes`：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group_aid": "g-abc123.agentid.pub",
-    "updated_keys": ["announcement.content", "group.index"],
-    "_meta": {
-        "group_indexes": {
-            "g-abc123.agentid.pub": {
-                "etag": "\"sha256:...\"",
-                "last_modified": 1780000000000,
-                "schema": "aun.group.index.v1"
-            }
-        }
-    }
-}
-```
-
-`group.index` 的正文格式：
-
-```jsonl
-{"type":"index_meta","group_aid":"g-abc123.agentid.pub","etag":"\"sha256:...\"","last_modified":1780000000000,"schema":"aun.group.index.v1","body_hash":"sha256:...","signed_by":"alice.agentid.pub","sig_alg":"ECDSA-P256-SHA256","signature":"base64..."}
-{"key":"announcement.content","source":"db","etag":"\"sha256:...\"","last_modified":1780000000000}
-```
-
-`etag` 和 `body_hash` 都由 index 条目的 canonical JSONL bytes 计算。`signature` 覆盖去掉 `signature` 字段后的 `index_meta` 和正文条目，`signed_by` 必须等于本次 RPC actor AID。服务端不会根据 DB 状态生成 `group.index`。
-
-### group.get_settings
-
-统一读取群参数。成员可读；不传 `keys` 时返回核心群资料和 settings 表中的全部设置。未显式设置 `dispatch_mode` 时，服务端仍返回默认值 `"broadcast"`。读取 `keys=["group.index"]` 可从服务端摘取当前签名 `group.index`。
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "updated_keys": ["mention_mode"]
+}
+```
+
+写入 `group.index` 成功时，响应顶层会强制携带 `_meta.group_indexes`：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "updated_keys": ["announcement.content", "group.index"],
+    "_meta": {
+        "group_indexes": {
+            "g-abc123.agentid.pub": {
+                "etag": "\"sha256:...\"",
+                "last_modified": 1780000000000,
+                "schema": "aun.group.index.v1"
+            }
+        }
+    }
+}
+```
+
+`group.index` 的正文格式：
+
+```jsonl
+{"type":"index_meta","group_aid":"g-abc123.agentid.pub","etag":"\"sha256:...\"","last_modified":1780000000000,"schema":"aun.group.index.v1","body_hash":"sha256:...","signed_by":"alice.agentid.pub","sig_alg":"ECDSA-P256-SHA256","signature":"base64..."}
+{"key":"announcement.content","source":"db","etag":"\"sha256:...\"","last_modified":1780000000000}
+```
+
+`etag` 和 `body_hash` 都由 index 条目的 canonical JSONL bytes 计算。`signature` 覆盖去掉 `signature` 字段后的 `index_meta` 和正文条目，`signed_by` 必须等于本次 RPC actor AID。服务端不会根据 DB 状态生成 `group.index`。
+
+### group.get_settings
+
+统一读取群参数。成员可读；不传 `keys` 时返回核心群资料和 settings 表中的全部设置。未显式设置 `mention_mode` 时，服务端仍返回默认值 `"disabled"`。读取 `keys=["group.index"]` 可从服务端摘取当前签名 `group.index`。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]`；读取 `["group.index"]` 时强制返回 `_meta.group_indexes` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `keys` | array | 否 | 只读取指定 key，如 `["mention_mode", "rules.content"]`；读取 `["group.index"]` 时强制返回 `_meta.group_indexes` |
 
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group_aid": "g-abc123.agentid.pub",
-    "settings": [
-        {"key": "dispatch_mode", "value": "broadcast", "updated_at": 1234567890000}
-    ]
-}
-```
-
-如果服务端已保存 `group.index`，普通 settings 读取可能在顶层返回 `_meta.group_indexes`。该 meta 受服务端注入频率控制；显式读取 `group.index` 时会强制返回：
-
-```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "group_aid": "g-abc123.agentid.pub",
-    "settings": [
-        {"key": "group.index", "value": {"body": "..."}, "updated_by": "alice.agentid.pub", "updated_at": 1780000000000}
-    ],
-    "_meta": {
-        "group_indexes": {
-            "g-abc123.agentid.pub": {
-                "etag": "\"sha256:...\"",
-                "last_modified": 1780000000000,
-                "schema": "aun.group.index.v1"
-            }
-        }
-    }
-}
-```
-
-SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本地 index 或业务缓存。etag 不一致只表示本地与观察到的远端版本不同，方向由应用层决定：`checkGroupIndex` 用于检查是否不同步，`getGroupIndex` 用于显式 pull 远端 manifest 并同步本地缓存，`updateGroupIndex` 用于显式 CAS push 本地 indexed settings。
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "settings": [
+        {"key": "mention_mode", "value": "disabled", "updated_at": 1234567890000}
+    ]
+}
+```
+
+如果服务端已保存 `group.index`，普通 settings 读取可能在顶层返回 `_meta.group_indexes`。该 meta 受服务端注入频率控制；显式读取 `group.index` 时会强制返回：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "settings": [
+        {"key": "group.index", "value": {"body": "..."}, "updated_by": "alice.agentid.pub", "updated_at": 1780000000000}
+    ],
+    "_meta": {
+        "group_indexes": {
+            "g-abc123.agentid.pub": {
+                "etag": "\"sha256:...\"",
+                "last_modified": 1780000000000,
+                "schema": "aun.group.index.v1"
+            }
+        }
+    }
+}
+```
+
+SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本地 index 或业务缓存。etag 不一致只表示本地与观察到的远端版本不同，方向由应用层决定：`checkGroupIndex` 用于检查是否不同步，`getGroupIndex` 用于显式 pull 远端 manifest 并同步本地缓存，`updateGroupIndex` 用于显式 CAS push 本地 indexed settings。
 
 ## 消息
 
@@ -1100,13 +1110,13 @@ SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本
 
 发送群消息。需要 member 权限。
 
-群消息的持久化 `dispatch_mode` 来自群设置，取值为 `"broadcast"` / `"mention"`；服务端会写入消息对象并在 pull / push 中返回。运行时是否广播全员或分发给值班 Agent，由响应中的 `dispatch` / `message_dispatch` 描述。
+群消息的持久化 `mention_mode` 来自群设置，取值为 `"disabled"` / `"mention-only"`；服务端会写入消息对象并在 pull / push 中返回。运行时是否广播全员或分发给值班 Agent，由响应中的 `dispatch` / `message_dispatch` 描述。V2 加密消息把快照放在既有 `envelope_json` 元数据中，不改变 `per_device` 投递列。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
@@ -1114,7 +1124,7 @@ SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本
 
 ### Payload 参考约定
 
-`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `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-与可验证上下文) 的格式和校验规则。
 
@@ -1129,52 +1139,52 @@ SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本
         "message_id": "uuid",
         "sender_aid": "alice.agentid.pub",
         "message_type": "e2ee.group_encrypted",
-        "dispatch_mode": "broadcast",
+        "mention_mode": "disabled",
         "payload": {"type": "e2ee.group_encrypted", "...": "..."},
         "attachments": [],
         "created_at": 1234567890000
     },
     "event": { ... },
-    "dispatch_mode": "broadcast",
-    "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"}
-}
-```
+    "mention_mode": "disabled",
+    "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 | 兼容字段，值语义为目标态 `group_aid` |
+| `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"` |
-| `envelope` | object | SDK 回填的发送结果信封，包含发送方、群标识、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
-| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
+| `mention_mode` | string | 群消息提及过滤模式标签：`"disabled"` / `"mention-only"`；SDK 解密后也会注入到对象 `payload.mention_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"` |
+| `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 会加密成 V2 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature`、AAD 和 state commitment 生成；`client_signature` 按 Gateway 连接级身份语义携带。
+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_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_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 | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `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思考内容) |
@@ -1202,7 +1212,7 @@ await client.call("group.thought.put", {
     "thought_id": "gt-...",
     "type": "e2ee.group_encrypted",
     "encrypted": true,
-    "payload": {"type": "e2ee.group_encrypted", "version": "v2", "...": "..."},
+    "payload": {"type": "e2ee.group_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -1228,7 +1238,7 @@ await client.call("group.thought.put", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `sender_aid` | string | 是 | thought 作者 AID |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
@@ -1277,9 +1287,9 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `after_message_seq` | integer | 否 | 0 | 从该消息 seq 之后拉取 |
-| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 | `device_id` | string | 否 | — | 设备 ID（多设备模式） |
 
 **响应**：
@@ -1290,13 +1300,35 @@ result = await client.call("group.thought.get", {
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
-    "limit": 50
+    "limit": 50,
+    "retention_floor_message_seq": 20,
+    "earliest_available_message_seq": 31
 }
 ```
 
 多设备模式时额外返回 `cursor` 对象（含 `current_seq`、`join_seq`、`latest_seq`、`unread_count`）。
 
-返回的每条群消息包含 `dispatch_mode`。Python / Go / TS / JS SDK 在解密后会保留顶层 `dispatch_mode`，并把同一值注入到 `payload.dispatch_mode`，方便应用层按 `"broadcast"` / `"mention"` 做 UI 或通知策略。
+`group.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。普通 Forward 中，`retention_floor_message_seq` 只表示已提交物理 GC；`earliest_available_message_seq-1` 表示服务端综合 retention、入群点和 epoch 后的当前成员可见性排他下界。SDK 以 `max(retention_floor_message_seq, cursor.join_seq, earliest_available_message_seq-1)` 推进 A；History 不修改 A/T/H。
+
+Forward 原始页校验通过后按页内最大 seq 推进 A，单条解密失败通过 `group.message_undecryptable` 报告而不阻塞水位。Piggy ACK 保留：有待提交 ACK 时，非满页会继续拉一页并携带 ACK，空页后停止。
+
+解密当前群消息时若缺少 sender IK，SDK 先执行同发送端 single-flight 的有界同步 bootstrap，最多等待 3 秒；P2P bootstrap 未命中时可继续读取 Group bootstrap。成功后立即重试当前消息，失败或超时才 pending，且不阻塞实时扫描水位。
+
+SDK 只保证单个实时拉取响应页内按 seq 升序、同 seq 最多发布一次。A/T/H 是扫描水位，不记录应用是否已经收到回调；跨 Push、SDK 自动最新页同步和 Forward 页允许重复和乱序。全局去重与排序由应用业务仓库负责，不是 SDK 交付契约；应用必须在群 namespace 内按 `message_id` 幂等并按 `seq` 排序。SDK 进程内折叠仅作 best-effort 优化。History 只返回结果，不参与实时发布。
+
+返回的每条群消息包含 `mention_mode`。Python / Go / TS / JS SDK 在解密后会保留顶层 `mention_mode`，并把同一值注入到对象 `payload.mention_mode`，方便应用层按 `"disabled"` / `"mention-only"` 做 UI 或通知策略。
+
+### group.history
+
+只读向前翻页群消息。Group Event 不进入此接口，也不受消息 A/T/H 影响。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `group_id` | string | 是 | — | 群组标识 |
+| `before_seq` | integer | 是 | — | 排他上界，只返回 `seq < before_seq` 的消息 |
+| `limit` | integer | 否 | 50 | 单页上限，最大 50 |
+
+响应包含 `messages`、`window_start_seq`、`next_before_seq`、`has_older`、`retention_floor_seq` 和 `earliest_available_seq`。页内按 seq 升序；解密失败项以结构化错误返回。下一页必须直接复用 `next_before_seq`，不得根据首条消息自行加减。History 不推进消息/事件 ACK，不修改实时 A/T/H，也不触发 `group.message_created`。
 
 ### group.ack
 
@@ -1306,7 +1338,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1331,7 +1363,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
 | `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
 
@@ -1386,8 +1418,9 @@ result = await client.call("group.thought.get", {
 
 权限与签名约束：
 
-- 群自有区是除 `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` 等系统保留路径外的整个 `group_aid` namespace。`group_aid` 当前证书签名可写；成员角色中 `owner/admin` 默认可写，`member` 默认不可写。`group_aid:/.group/` 是系统控制目录，用于群公告、群规则、入群要求附件，默认允许 `owner/admin` 写入。
+- 老群如果缺少 `.group/` 默认 ACL，group 服务会在该群首次被 RPC 访问时 best-effort 触发 namespace/ACL lazy repair；只有本次 baseline ACL 全部同步成功才记录本进程已检查，失败会在后续访问继续重试。
+- `group.fs.set_acl` / `group.fs.remove_acl` / `group.fs.get_acl` / `group.fs.list_acl` 只能由当前 group `owner/admin` 调用。当前支持 `grantee_aid="role:admin"` 与 `grantee_aid="role:member"`；`role:member` 只能授予具体业务目录的 `rw` 权限，不能授予根目录或 `.group/`，也不能获得删除、移动、重命名权限。成员升降级、退群、踢出不会联动授权或撤销目录 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 当本地路径。
@@ -1418,21 +1451,21 @@ result = await client.call("group.thought.get", {
 
 ### group.fs.set_acl
 
-授予群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
+授予群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
 
-参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`；`perms` 默认 `rwx`，必须包含写权限。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`。
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 可为 `role:admin` 或 `role:member`。`role:admin` 默认 `rwx`；`role:member` 只能为 `rw`，且只能授到具体业务目录，不能授到根目录或 `.group/`。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`；不授删除、移动、重命名权限时使用 `rw`。
 
 ### group.fs.remove_acl
 
-撤销群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
+撤销群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
 
-参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`。撤销后，当前 admin 角色成员不再因该路径的 `role:admin` ACL 获得写权限。
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 可为 `role:admin` 或 `role:member`。撤销 `role:member` 后，member 不再因该目录 ACL 获得创建/写入权限。
 
 ### group.fs.get_acl
 
-查询群自有区角色 ACL。需要当前 group owner 身份签名调用；普通 admin/member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
+查询群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；普通 member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
 
-响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此 owner 授权 `role:admin:rwx` 后查询也返回 `rwx`。
+响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此授权 `role:admin:rwx` 后查询也返回 `rwx`；`role:member` 只应返回 `rw`。
 
 ### group.fs.list_acl
 
@@ -1480,7 +1513,7 @@ result = await client.call("group.thought.get", {
 
 获取当前在线成员列表。
 
-**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1495,10 +1528,10 @@ result = await client.call("group.thought.get", {
         {
             "aid": "alice.agentid.pub",
             "role": "owner",
-            "joined_at": 1234567890000,
+            "joined_at": 1234567890000,
             "online": true,
             "session_id": "sess_123",
-            "last_active_at": 1234567890000,
+            "last_active_at": 1234567890000,
             "expire_at": 1234571490
         }
     ]
@@ -1513,18 +1546,18 @@ result = await client.call("group.thought.get", {
 
 ### group.pull_events
 
-增量拉取群事件，支持多设备独立游标。
+增量拉取群事件，支持多设备独立游标。SDK 将其作为后台 Pull 放入独立的 Group Event Gate；该 Gate 内单飞、同请求 key 折叠、不同 key FIFO，排队超过 3 秒时旁路执行。它不与 Group Message Gate 共用，也不修改消息 A/T/H。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 否 | — | 设备 ID，多设备模式必填 |
 | `device_name` | string | 否 | — | 设备名称（首次注册时使用） |
 | `device_type` | string | 否 | — | 设备类型 |
 | `after_event_seq` | integer | 否 | 游标位置 | 从该事件 seq 之后拉取；多设备模式下默认使用设备游标 |
-| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 
 **响应**：
 
@@ -1534,17 +1567,20 @@ result = await client.call("group.thought.get", {
     "events": [ ... ],
     "latest_event_seq": 100,
     "has_more": false,
-    "limit": 50,
+    "limit": 50,
+    "retention_floor_event_seq": 20,
+    "earliest_available_event_seq": 31,
     "cursor": {
-        "current_seq": 50,
-        "join_seq": 0,
+        "current_seq": 25,
+        "join_seq": 30,
         "latest_seq": 100,
-        "unread_count": 50
+        "retention_floor_seq": 20,
+        "unread_count": 70
     }
 }
 ```
 
-> `cursor` 仅多设备模式（提供 `device_id`）时返回。响应大小受 `pull_max_response_bytes` 配置限制。包含 E2EE epoch 范围检查，不返回成员加入前的加密事件。
+> `retention_floor_event_seq` 只表示已提交物理 GC；`earliest_available_event_seq-1` 是综合 retention、入群点和 epoch 后的当前成员可见性排他下界。SDK 以 `max(retention_floor_event_seq, cursor.current_seq, cursor.join_seq, earliest_available_event_seq-1)` 恢复或推进 Group Event A，ACK 仍只能提交已持久化 A。`cursor` 仅多设备模式（提供 `device_id`）时返回。响应大小受 `pull_max_response_bytes` 配置限制。
 
 ### group.ack_messages
 
@@ -1554,7 +1590,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1570,7 +1606,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `event_seq` | integer | 是 | 确认到的事件序号 |
 
@@ -1580,7 +1616,7 @@ result = await client.call("group.thought.get", {
 
 列出当前用户在指定群组的所有设备及游标状态。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1603,7 +1639,7 @@ result = await client.call("group.thought.get", {
 
 注销设备游标（清理不再使用的设备记录）。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`），`device_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`），`device_id` (必填)
 
 **响应**：`{ "success": true }`
 
@@ -1615,7 +1651,7 @@ result = await client.call("group.thought.get", {
 
 获取管理员列表（owner + admin 角色）。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1626,7 +1662,7 @@ result = await client.call("group.thought.get", {
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890000
+            "joined_at": 1234567890000
         }
     ]
 }
@@ -1636,7 +1672,7 @@ result = await client.call("group.thought.get", {
 
 获取群主 AID。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "owner_aid": "alice.agentid.pub" }`
 
@@ -1644,7 +1680,7 @@ result = await client.call("group.thought.get", {
 
 获取群组综合统计摘要。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1663,8 +1699,8 @@ result = await client.call("group.thought.get", {
     "message_seq": 1000,
     "event_seq": 2000,
     "e2ee_epoch": 3,
-    "created_at": 1234567890000,
-    "updated_at": 1234567890000
+    "created_at": 1234567890000,
+    "updated_at": 1234567890000
 }
 ```
 
@@ -1673,7 +1709,7 @@ result = await client.call("group.thought.get", {
 
 刷新成员类型分类统计。
 
-**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1729,14 +1765,14 @@ result = await client.call("group.thought.get", {
 }
 ```
 
-SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x 当前仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等兼容别名；新代码应优先通过 `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 | 兼容字段，值语义为目标态 `group_aid` |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
 | `path` | string | 可选，Group FS 相关 action 的节点路径 |
 
@@ -1774,9 +1810,9 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x
 | `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员封禁 |
 | `member_unbanned` | 成员解封 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
 
 **订阅**：
 
@@ -1786,9 +1822,13 @@ client.on("group.changed", lambda ev: print(ev["action"]))
 
 ### event/group.message_created
 
-群消息创建时推送给所有在线成员。支持两种模式：
+群消息创建时推送给所有在线成员。
+
+**实时推送优化**（0.5.6+）：当客户端在 `auth.connect` 时声明 `inline_realtime_payload_v1: true` 能力后，Gateway 会优先推送带完整 `payload` 的消息模式。SDK 自动声明此能力，应用层无需关注。
 
-**消息推送模式**（带 `payload`）：
+支持两种模式：
+
+**模式 1：消息推送模式**（带 `payload`）：
 
 ```json
 {
@@ -1798,27 +1838,27 @@ client.on("group.changed", lambda ev: print(ev["action"]))
     "message_id": "uuid",
     "sender_aid": "alice.agentid.pub",
     "type": "e2ee.group_encrypted",
-    "dispatch_mode": "broadcast",
+    "mention_mode": "disabled",
     "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
-    "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
-}
-```
+    "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`，解密后的明文消息直接交付用户回调。
 
-**通知模式**（不带 `payload`）：
+**模式 2：通知模式**（不带 `payload`，回退场景）：
 
 ```json
 {
@@ -1828,12 +1868,12 @@ SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户
     "message_id": "uuid",
     "sender_aid": "alice.agentid.pub",
     "type": "e2ee.group_encrypted",
-    "dispatch_mode": "broadcast",
+    "mention_mode": "disabled",
     "dispatch": {"mode": "broadcast", "reason": "duty_disabled"}
 }
 ```
 
-SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交付用户回调。
+SDK 收到新 Head 后自动同步最新消息页并逐条解密；若 A 与 T 之间仍有未扫描区间，再执行一页后台 Forward。应用无需为此调用 `group.pull`。
 
 **SDK 应用层回调形态**：
 
@@ -1850,12 +1890,12 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
     "message_id": "uuid",
     "sender_aid": "alice.agentid.pub",
     "message_type": "group.message",
-    "dispatch_mode": "broadcast",
+    "mention_mode": "disabled",
     "payload": {"type": "text", "text": "Hello"}
 }
 ```
 
-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 或业务鉴权。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `mention_mode` 等字段；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
 
 ### event/group.message_recalled
 
@@ -1887,13 +1927,13 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 }
 ```
 
-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`。
+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 | 兼容字段，值语义为目标态 `group_aid` |
+| `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` |