@agentunion/fastaun-browser 0.5.1 → 0.5.3

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

@@ -103,7 +103,7 @@
 | [group.set_settings](#groupset_settings) | 统一设置群参数（含公告、规则、入群要求、dispatch_mode 等） |
 | [group.get_settings](#groupget_settings) | 统一读取群参数 |
 
-**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`），内部调用 `set_settings`/`get_settings`，返回旧格式。新代码建议直接使用 `set_settings`/`get_settings`。
+**便利方法**：SDK 提供向后兼容的便利方法（`getAnnouncement`/`updateAnnouncement`/`getRules`/`updateRules`/`getJoinRequirements`/`updateJoinRequirements`）。读取方法优先返回 SDK 本地缓存，本地没有对应值时才调用 `get_settings` 初始化；即使观察到远端 etag 不一致也不会自动 pull 远端。indexed 写入方法内部调用 `updateGroupIndex` 生成签名 `group.index` 并通过 `set_settings` CAS 提交。
 
 ### 群文件系统
 
@@ -137,15 +137,17 @@
 
 ---
 
-## Group ID 规范
-
-`group_id` 的 canonical 形式为 `group.{issuer-domain}/{base}`，例如 `group.agentid.pub/10042`、`group.agentid.pub/team01`、`group.agentid.pub/g-abc123`。服务端接受输入后会规范化为 canonical group_id；响应和内部存储以 canonical 形式为准。SDK 发起 `group.*` 调用时也会对带域旧格式做同等规范化；裸客户端应使用同一规则生成签名和 E2EE AAD，避免同一群的不同别名产生不同材料。
-
-兼容输入包括 canonical `group.{issuer-domain}/{base}`、本域简写 `{base}` / `g-{slug}`，以及旧跨域形式 `{base}@issuer-domain`、`{base}.issuer-domain`、`g-{slug}@issuer-domain`、`g-{slug}.issuer-domain`。`base` 支持 5 位及以上小写字母或数字，或 4 到 64 位 `[a-z0-9_-]` 风格名称；旧 `g-` 前缀形式继续兼容，`g-` 后为 4 到 32 位小写字母或数字。命名群使用 `group_name` 作为 base，规则见 `group.create` 参数说明。
-
-`group.create` 可以指定自定义 `group_id`，但不能是纯数字（纯数字群号保留给服务端自动分配），且规范化后的 canonical group_id 未被占用；如果已被占用或与旧别名碰撞会返回错误。不指定 `group_id` 时服务端按群号自动分配，并通过唯一约束兜底，发现碰撞会重新生成。
-
-在 `https://group.issuer-domain/...` 这类群链接中，host 已携带 issuer，path 中的 `group_id` 使用 base 简写形式，例如 `https://group.agentid.pub/10042/invite/ic-xxx`；旧 `g-` base 群也可以表示为 `https://group.agentid.pub/g-abc123/invite/ic-xxx`。
+## Group 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 简写链接可继续由服务端兼容解析。
 
 ---
 
@@ -153,15 +155,16 @@
 
 ### group.create
 
-创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。
+创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | string | 是 | 群组显示名称 |
-| `group_id` | string | 否 | 自定义群 ID；不提供则服务端自动生成 |
-| `group_name` | string | 否 | 命名群标识，4-64 字符，`[a-z0-9_-]+`，不以 `guest`/`g-` 开头。与 `public_key` 同时提供时创建命名群 |
+| `group_aid` | string | 否 | 目标态群 AID；新代码优先使用。传入时会规范化为 `{base}.{issuer-domain}`，不能是纯数字 |
+| `group_id` | string | 否 | 兼容旧客户端的别名；值语义同 `group_aid`，不再推荐新代码使用 |
+| `group_name` | string | 否 | 命名群标识，4-64 字符，`[a-z0-9_-]+`，不以 `guest`/`g-` 开头。与 `public_key` 同时提供时创建命名群，并生成 `{group_name}.{issuer-domain}` |
 | `public_key` | string | 否 | 命名群公钥（base64 编码），与 `group_name` 同时提供 |
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
 | `visibility` | string | 否 | `"public"` / `"private"`，默认由配置决定 |
@@ -178,7 +181,8 @@
 ```json
 {
     "group": {
-        "group_id": "group.agentid.pub/10001",
+        "group_id": "my-team.agentid.pub",
+        "group_aid": "my-team.agentid.pub",
         "name": "测试群",
         "owner_aid": "alice.agentid.pub",
         "creator_aid": "alice.agentid.pub",
@@ -189,10 +193,9 @@
         "member_count": 1,
         "message_seq": 0,
         "event_seq": 0,
-        "group_url": "https://group.agentid.pub/10001",
-        "group_aid": "my-team.agentid.pub",
-        "created_at": 1234567890,
-        "updated_at": 1234567890
+        "group_url": "https://group.agentid.pub/my-team.agentid.pub",
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000
     },
     "aid_cert": {
         "cert": "-----BEGIN CERTIFICATE-----...",
@@ -204,9 +207,9 @@
 }
 ```
 
-> `aid_cert` 仅在命名群创建时返回。`group_aid` 和 `group_url` 仅在命名群时存在。
-
-**Group ID 格式**：新格式 `group.{issuer}/{group_no_or_name}`，旧格式 `{digits}.{issuer}` API 返回时自动转换。
+> `aid_cert` 仅在命名群创建时返回。`group_aid` 是新代码应使用的主标识；`group_id` 为兼容字段，新群通常与 `group_aid` 相同，历史群可能保留旧存储值。
+
+**标识格式**：目标态为 `{base}.{issuer-domain}`。旧格式 `group.{issuer-domain}/{base}`、`{base}@{issuer-domain}` 会在 API 边界转换为目标态 `group_aid`。
 
 ### group.bind_aid
 
@@ -216,7 +219,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `group_name` | string | 是 | 命名群标识，4-64 字符，`[a-z0-9_-]+` |
 | `public_key` | string | 是 | 群公钥（base64 编码） |
 | `curve` | string | 否 | 密钥曲线，默认 `"P-256"` |
@@ -238,7 +241,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `required` | string[] | 否 | 受限字段声明：`member`、`state`、`e2ee`、`avatar` |
 
 **默认响应**：
@@ -253,7 +256,7 @@
     "status": "active",
     "description": "技术讨论群",
     "member_count": 42,
-    "created_at": 1234567890
+    "created_at": 1234567890000
 }
 ```
 
@@ -269,7 +272,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容参数名，值使用目标态 `group_aid` |
 | `name` | string | 否 | 新名称 |
 | `visibility` | string | 否 | 新可见性 |
 | `description` | string | 否 | 新描述 |
@@ -298,7 +301,7 @@
             "name": "项目讨论",
             "visibility": "private",
             "member_count": 5,
-            "updated_at": 1234567890,
+            "updated_at": 1234567890000,
             "role": "owner"
         }
     ],
@@ -340,7 +343,7 @@
 
 暂停群组。暂停期间不能发送消息。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -357,7 +360,7 @@
 
 恢复暂停的群组。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -374,7 +377,7 @@
 
 永久解散群组。不可恢复。需要 **owner** 权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -398,7 +401,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要添加的 AID |
 | `role` | string | 否 | `"admin"` / `"member"`，默认 `"member"` |
 | `member_type` | string | 否 | `"human"` / `"ai"`，默认 `"human"` |
@@ -412,7 +415,7 @@
         "aid": "bob.agentid.pub",
         "role": "member",
         "member_type": "human",
-        "joined_at": 1234567890
+        "joined_at": 1234567890000
     }
 }
 ```
@@ -425,7 +428,7 @@
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | 50 | 每页条数（最大 200） |
 | `role` | string | 否 | — | 按角色过滤（owner/admin/member） |
@@ -441,9 +444,9 @@
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890,
+            "joined_at": 1234567890000,
             "last_ack_seq": 100,
-            "last_pull_at": 1234567890
+            "last_pull_at": 1234567890000
         }
     ],
     "total": 1,
@@ -461,7 +464,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 要踢出的 AID |
 
 **响应**：
@@ -477,7 +480,7 @@
 
 主动退出群组。owner 不能直接退群，需先转让群主。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -496,7 +499,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 目标 AID |
 | `role` | string | 是 | `"admin"` / `"member"` |
 
@@ -510,7 +513,7 @@
         "aid": "bob.agentid.pub",
         "role": "admin",
         "member_type": "human",
-        "joined_at": 1234567890,
+        "joined_at": 1234567890000,
         "last_ack_seq": 0,
         "last_pull_at": 0
     },
@@ -529,7 +532,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `new_owner` | string | 是 | 新群主 AID（也接受 `aid`） |
 
 **响应**：
@@ -555,7 +558,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `public_key` | string | 是 | 公钥 DER base64（SPKI 格式） |
 | `curve` | string | 否 | 曲线名称（默认 P-256） |
 
@@ -564,7 +567,7 @@
 ```json
 {
     "group": {
-        "group_id": "my-team",
+        "group_id": "my-team.agentid.pub",
         "group_aid": "my-team.agentid.pub",
         ...
     },
@@ -599,7 +602,7 @@
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `group_aid` | string | 否 | 群身份 AID（可选，服务端可推导） |
 | `old_public_key` | string | 是 | 旧公钥 DER base64 |
 | `new_public_key` | string | 是 | 新公钥 DER base64 |
@@ -629,7 +632,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 ```json
 {
     "group": {
-        "group_id": "my-team",
+        "group_id": "my-team.agentid.pub",
         "group_aid": "my-team.agentid.pub",
         ...
     },
@@ -657,7 +660,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `subject` | string | 是 | 要封禁的 AID（也接受 `aid`） |
 | `reason` | string | 否 | 封禁原因 |
 | `expires_at` | integer | 否 | 过期时间戳（0 = 永久） |
@@ -674,7 +677,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": 1234567890
+        "created_at": 1234567890000
     }
 }
 ```
@@ -683,7 +686,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 解除封禁。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string), `subject` 或 `aid` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`subject` 或 `aid` (string)
 
 **响应**：
 
@@ -699,7 +702,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 获取封禁列表。需要 **admin 及以上**权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -713,7 +716,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": 1234567890
+            "created_at": 1234567890000
         }
     ],
     "total": 1,
@@ -734,7 +737,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message` | string | 否 | 申请留言 |
 | `answer` | string | 否 | 入群问题的答案 |
 
@@ -770,8 +773,8 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
         "message": "请加我",
         "answer": "...",
         "status": "pending",
-        "created_at": 1234567890,
-        "updated_at": 1234567890,
+        "created_at": 1234567890000,
+        "updated_at": 1234567890000,
         "expires_at": 1234654290,
         "reviewed_by": null,
         "rejection_reason": null
@@ -787,7 +790,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `status` | string | 否 | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
 | `page` | integer | 否 | 1 | 页码 |
 | `size` | integer | 否 | — | 每页数量 |
@@ -803,8 +806,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": 1234567890,
-            "updated_at": 1234567890
+            "created_at": 1234567890000,
+            "updated_at": 1234567890000
         }
     ],
     "total": 1,
@@ -821,7 +824,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `aid` | string | 是 | 申请人 AID |
 | `approve` | boolean | 否 | 批准或拒绝，默认 `true` |
 | `reason` | string | 否 | 拒绝原因 |
@@ -859,7 +862,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `requests` | array | 是 | 审批列表 |
 
 `requests` 数组每项：
@@ -891,7 +894,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `code` | string | 否 | 自定义邀请码（不提供则自动生成） |
 | `max_uses` | integer | 否 | 最大使用次数，默认 1，必须 > 0 |
 | `expires_in_seconds` | integer | 否 | 有效期（秒），默认由 invite_code_ttl_days 配置（7 天） |
@@ -909,7 +912,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": 1234567890
+        "created_at": 1234567890000
     }
 }
 ```
@@ -934,13 +937,13 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 列出群组的邀请码。需要 admin 权限。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 ### group.revoke_invite_code
 
 撤销邀请码。需要 admin 权限。
 
-**参数**：`group_id` (string), `code` (string)
+**参数**：`group_id`（string，兼容字段，值使用目标态 `group_aid`），`code` (string)
 
 ---
 
@@ -948,7 +951,9 @@ 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`。
+统一写入群参数。需要 admin 及以上权限。`dispatch_mode` 是群消息的应用层分发模式标签，会随 `group.send` 生成的消息持久化，并由 SDK 在解密后注入到消息顶层和 `payload.dispatch_mode`。
+
+`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引。更新 indexed settings 时必须同包提交新的签名 `group.index`，并通过 `expected_index_etag` 做 CAS。
 
 `dispatch_mode` 不是 `group.send` 的单次入参；要修改后续消息的模式，请通过 `group.set_settings` 更新群设置。
 
@@ -956,11 +961,13 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
-| `settings` | object | 是 | 要写入的设置键值 |
-| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
-| `settings["rules.content"]` | string | 否 | 群规则正文 |
-| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `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` |
 
 **预定义群级参数**：
 
@@ -976,11 +983,28 @@ 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` 仍返回默认值 |
-
-```python
-await client.call("group.set_settings", {
+| `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", {
     "group_id": "g-abc123.agentid.pub",
     "settings": {"dispatch_mode": "mention"},
 })
@@ -989,33 +1013,86 @@ await client.call("group.set_settings", {
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "updated_keys": ["dispatch_mode"]
-}
-```
-
-### group.get_settings
-
-统一读取群参数。成员可读；不传 `keys` 时返回核心群资料和 settings 表中的全部设置。未显式设置 `dispatch_mode` 时，服务端仍返回默认值 `"broadcast"`。
+{
+    "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` | string | 是 | 群组 ID |
-| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]` |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]`；读取 `["group.index"]` 时强制返回 `_meta.group_indexes` |
 
 **响应**：
 
 ```json
-{
-    "group_id": "g-abc123.agentid.pub",
-    "settings": [
-        {"key": "dispatch_mode", "value": "broadcast", "updated_at": 1234567890000}
-    ]
-}
-```
+{
+    "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。
 
 ## 消息
 
@@ -1029,7 +1106,7 @@ await client.call("group.set_settings", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
@@ -1037,7 +1114,7 @@ await client.call("group.set_settings", {
 
 ### Payload 参考约定
 
-`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
 
 `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
 
@@ -1059,34 +1136,45 @@ await client.call("group.set_settings", {
     },
     "event": { ... },
     "dispatch_mode": "broadcast",
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "message_dispatch": { ... }
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "message_dispatch": { ... },
+    "envelope": {
+        "from": "alice.agentid.pub",
+        "group_id": "g-abc123.agentid.pub",
+        "type": "text",
+        "timestamp": 1234567890000,
+        "encrypted": true,
+        "payload_type": "text"
+    },
+    "payload": {"type": "text", "text": "Hello"}
+}
+```
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `message` | object | 消息对象（含 seq、message_id、sender_aid 等） |
 | `event` | object | 关联的群事件对象 |
 | `dispatch_mode` | string | 群消息持久化分发模式标签：`"broadcast"` / `"mention"`；SDK 解密后也会注入到 `payload.dispatch_mode` |
-| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
-| `duty_state` | object | 可选，值班模式下的当前状态 |
-| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
+| `duty_state` | object | 可选，值班模式下的当前状态 |
+| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `envelope` | object | SDK 回填的发送结果信封，包含发送方、群标识、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
+| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
 
 ### group.thought.put
 
 写入某个发送者针对一个群上下文的思考内容。该内容不是普通群消息：服务端不分配消息 `seq`，不广播，不进入 `group.pull`，不需要 ack，也不持久化；只在内存中保留当前 head。
 
-SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，则必须自行完成同等加密和签名。
+SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature`、AAD 和 state commitment 生成；`client_signature` 按 Gateway 连接级身份语义携带。
 
-存储键为 `group_id + sender_aid + context.type + context.id`。其中 `sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_id, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
+存储键为规范化后的 `group_aid + sender_aid + context.type + context.id`。RPC 字段名仍为 `group_id` 以兼容旧客户端，但服务端会先规范化为目标态群标识；`sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_aid, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
 | `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
@@ -1114,7 +1202,7 @@ await client.call("group.thought.put", {
     "thought_id": "gt-...",
     "type": "e2ee.group_encrypted",
     "encrypted": true,
-    "payload": {"type": "e2ee.group_encrypted", "...": "..."},
+    "payload": {"type": "e2ee.group_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -1140,7 +1228,7 @@ await client.call("group.thought.put", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `sender_aid` | string | 是 | thought 作者 AID |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
@@ -1189,9 +1277,9 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `after_message_seq` | integer | 否 | 0 | 从该消息 seq 之后拉取 |
-| `limit` | integer | 否 | 100 | 最大条数 |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 | `device_id` | string | 否 | — | 设备 ID（多设备模式） |
 
 **响应**：
@@ -1202,7 +1290,7 @@ result = await client.call("group.thought.get", {
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
-    "limit": 100
+    "limit": 50
 }
 ```
 
@@ -1218,7 +1306,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1243,7 +1331,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
 | `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
 
@@ -1392,7 +1480,7 @@ result = await client.call("group.thought.get", {
 
 获取当前在线成员列表。
 
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1407,10 +1495,10 @@ result = await client.call("group.thought.get", {
         {
             "aid": "alice.agentid.pub",
             "role": "owner",
-            "joined_at": 1234567890,
+            "joined_at": 1234567890000,
             "online": true,
             "session_id": "sess_123",
-            "last_active_at": 1234567890,
+            "last_active_at": 1234567890000,
             "expire_at": 1234571490
         }
     ]
@@ -1431,12 +1519,12 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 否 | — | 设备 ID，多设备模式必填 |
 | `device_name` | string | 否 | — | 设备名称（首次注册时使用） |
 | `device_type` | string | 否 | — | 设备类型 |
 | `after_event_seq` | integer | 否 | 游标位置 | 从该事件 seq 之后拉取；多设备模式下默认使用设备游标 |
-| `limit` | integer | 否 | 100 | 最大条数（受 `pull_max_limit` 配置限制） |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 
 **响应**：
 
@@ -1446,7 +1534,7 @@ result = await client.call("group.thought.get", {
     "events": [ ... ],
     "latest_event_seq": 100,
     "has_more": false,
-    "limit": 100,
+    "limit": 50,
     "cursor": {
         "current_seq": 50,
         "join_seq": 0,
@@ -1466,7 +1554,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
 
@@ -1482,7 +1570,7 @@ result = await client.call("group.thought.get", {
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `event_seq` | integer | 是 | 确认到的事件序号 |
 
@@ -1492,7 +1580,7 @@ result = await client.call("group.thought.get", {
 
 列出当前用户在指定群组的所有设备及游标状态。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1515,7 +1603,7 @@ result = await client.call("group.thought.get", {
 
 注销设备游标（清理不再使用的设备记录）。
 
-**参数**：`group_id` (必填), `device_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`），`device_id` (必填)
 
 **响应**：`{ "success": true }`
 
@@ -1527,7 +1615,7 @@ result = await client.call("group.thought.get", {
 
 获取管理员列表（owner + admin 角色）。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1538,7 +1626,7 @@ result = await client.call("group.thought.get", {
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890
+            "joined_at": 1234567890000
         }
     ]
 }
@@ -1548,7 +1636,7 @@ result = await client.call("group.thought.get", {
 
 获取群主 AID。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "owner_aid": "alice.agentid.pub" }`
 
@@ -1556,7 +1644,7 @@ result = await client.call("group.thought.get", {
 
 获取群组综合统计摘要。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1575,8 +1663,8 @@ result = await client.call("group.thought.get", {
     "message_seq": 1000,
     "event_seq": 2000,
     "e2ee_epoch": 3,
-    "created_at": 1234567890,
-    "updated_at": 1234567890
+    "created_at": 1234567890000,
+    "updated_at": 1234567890000
 }
 ```
 
@@ -1585,7 +1673,7 @@ result = await client.call("group.thought.get", {
 
 刷新成员类型分类统计。
 
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 
 **响应**：
 
@@ -1641,14 +1729,14 @@ result = await client.call("group.thought.get", {
 }
 ```
 
-SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x 兼容期仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等别名，下一个大版本 0.5.* 将移除这些顶层别名，请通过 `ev["envelope"]["action"]` 等路径访问。
+SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x 当前仍保留顶层 `module_id` / `action` / `group_id` / `event_seq` 等兼容别名；新代码应优先通过 `ev["envelope"]["action"]` 等路径访问。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `envelope` | object | 群事件信封，包含 `module_id`、`action`、`group_id`、`event_seq`、`event_type`、`actor_aid`、`created_at`、`device_id`、`slot_id` 等存在的字段 |
 | `module_id` | string | 固定 `"group"` |
 | `action` | string | 变更类型（见下表） |
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `event_seq` | integer | 可选，服务端分配的单调递增序号，用于 SDK 内部保序去重 |
 | `path` | string | 可选，Group FS 相关 action 的节点路径 |
 
@@ -1686,12 +1774,9 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x
 | `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员封禁 |
 | `member_unbanned` | 成员解封 |
-| `resource_put` | 资源上传 |
-| `resource_updated` | 资源更新 |
-| `resource_deleted` | 资源删除 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
 
 **订阅**：
 
@@ -1715,11 +1800,21 @@ client.on("group.changed", lambda ev: print(ev["action"]))
     "type": "e2ee.group_encrypted",
     "dispatch_mode": "broadcast",
     "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "kind": "group.broadcast",
-    "member_aids": ["bob.agentid.pub"]
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "kind": "group.broadcast",
+    "member_aids": ["bob.agentid.pub"],
+    "proximity": {
+        "same_device": false,
+        "same_egress_ip": true,
+        "same_network": true,
+        "basis": "egress_ip",
+        "asserted_by": "gateway"
+    },
+    "same_device": false,
+    "same_egress_ip": true,
+    "same_network": true
+}
+```
 
 SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户回调。
 
@@ -1760,7 +1855,7 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
 
 ### event/group.message_recalled
 
@@ -1792,13 +1887,13 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 }
 ```
 
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等兼容别名；新代码应优先读取 `envelope`、`message_ids` 和 `target_message_seqs`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
 | `module_id` | string | 固定 `"group"` |
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
 | `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
 | `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |