npm - @agentunion/fastaun-browser - Versions diffs - 0.5.1 → 0.5.2 - Mend

@agentunion/fastaun-browser 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

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

@@ -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)
 ---
@@ -956,7 +959,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` |
 | `settings` | object | 是 | 要写入的设置键值 |
 | `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
 | `settings["rules.content"]` | string | 否 | 群规则正文 |
@@ -1003,7 +1006,7 @@ await client.call("group.set_settings", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]` |
 **响应**：
@@ -1029,7 +1032,7 @@ await client.call("group.set_settings", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `payload` | object | 否 | 消息内容 |
 | `type` | string | 否 | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `attachments` | array | 否 | 兼容旧接口的顶层附件元数据；推荐把业务附件放入 `payload.attachments` |
@@ -1037,7 +1040,7 @@ await client.call("group.set_settings", {
 ### Payload 参考约定
-`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+`group.send.params.payload` 的统一业务负载格式见 [09-payload-reference](09-payload-reference.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
 `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
@@ -1059,34 +1062,45 @@ await client.call("group.set_settings", {
     },
     "event": { ... },
     "dispatch_mode": "broadcast",
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "message_dispatch": { ... }
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "message_dispatch": { ... },
+    "envelope": {
+        "from": "alice.agentid.pub",
+        "group_id": "g-abc123.agentid.pub",
+        "type": "text",
+        "timestamp": 1234567890000,
+        "encrypted": true,
+        "payload_type": "text"
+    },
+    "payload": {"type": "text", "text": "Hello"}
+}
+```
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `message` | object | 消息对象（含 seq、message_id、sender_aid 等） |
 | `event` | object | 关联的群事件对象 |
 | `dispatch_mode` | string | 群消息持久化分发模式标签：`"broadcast"` / `"mention"`；SDK 解密后也会注入到 `payload.dispatch_mode` |
-| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
-| `duty_state` | object | 可选，值班模式下的当前状态 |
-| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `dispatch` | object | 分发策略：`mode` 为 `"broadcast"`（广播全员）或 `"duty"`（值班分发）；`reason` 说明原因（如 `"duty_disabled"` / `"active_duty"` / `"no_duty_candidate"` 等） |
+| `duty_state` | object | 可选，值班模式下的当前状态 |
+| `message_dispatch` | object | 运行时分发结果；常见 `status` 包括 `"broadcast"`、`"sent"`、`"queued_batch"`、`"debounced"`、`"skipped"`、`"failed"` |
+| `envelope` | object | SDK 回填的发送结果信封，包含发送方、群标识、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
+| `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
 ### group.thought.put
 写入某个发送者针对一个群上下文的思考内容。该内容不是普通群消息：服务端不分配消息 `seq`，不广播，不进入 `group.pull`，不需要 ack，也不持久化；只在内存中保留当前 head。
-SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，则必须自行完成同等加密和签名。
+SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature`、AAD 和 state commitment 生成；`client_signature` 按 Gateway 连接级身份语义携带。
-存储键为 `group_id + sender_aid + context.type + context.id`。其中 `sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_id, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
+存储键为规范化后的 `group_aid + sender_aid + context.type + context.id`。RPC 字段名仍为 `group_id` 以兼容旧客户端，但服务端会先规范化为目标态群标识；`sender_aid` 由服务端认证态派生，不能由客户端指定；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一 `(group_aid, sender_aid)` 保留最近 N 个 context 对应的 head，N 由群服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 100；同一个 head 下可追加多条 thought item。
 **参数**：
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
 | `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
@@ -1114,7 +1128,7 @@ await client.call("group.thought.put", {
     "thought_id": "gt-...",
     "type": "e2ee.group_encrypted",
     "encrypted": true,
-    "payload": {"type": "e2ee.group_encrypted", "...": "..."},
+    "payload": {"type": "e2ee.group_encrypted", "version": "v2", "...": "..."},
     "client_signature": { "...": "..." }
 }
 ```
@@ -1140,7 +1154,7 @@ await client.call("group.thought.put", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `sender_aid` | string | 是 | thought 作者 AID |
 | `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
 | `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
@@ -1189,9 +1203,9 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `after_message_seq` | integer | 否 | 0 | 从该消息 seq 之后拉取 |
-| `limit` | integer | 否 | 100 | 最大条数 |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 | `device_id` | string | 否 | — | 设备 ID（多设备模式） |
 **响应**：
@@ -1202,7 +1216,7 @@ result = await client.call("group.thought.get", {
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
-    "limit": 100
+    "limit": 50
 }
 ```
@@ -1218,7 +1232,7 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
@@ -1243,7 +1257,7 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `message_ids` | string[] | 是 | 待撤回消息 ID 列表，最多 100 个（`recall_max_batch`）|
 | `reason` | string | 否 | 可选撤回理由，建议短文本（最长 255 字符）|
@@ -1392,7 +1406,7 @@ result = await client.call("group.thought.get", {
 获取当前在线成员列表。
-**参数**：`group_id` (string, 必填)
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：
@@ -1407,10 +1421,10 @@ result = await client.call("group.thought.get", {
         {
             "aid": "alice.agentid.pub",
             "role": "owner",
-            "joined_at": 1234567890,
+            "joined_at": 1234567890000,
             "online": true,
             "session_id": "sess_123",
-            "last_active_at": 1234567890,
+            "last_active_at": 1234567890000,
             "expire_at": 1234571490
         }
     ]
@@ -1431,12 +1445,12 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `group_id` | string | 是 | — | 群组 ID |
+| `group_id` | string | 是 | — | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 否 | — | 设备 ID，多设备模式必填 |
 | `device_name` | string | 否 | — | 设备名称（首次注册时使用） |
 | `device_type` | string | 否 | — | 设备类型 |
 | `after_event_seq` | integer | 否 | 游标位置 | 从该事件 seq 之后拉取；多设备模式下默认使用设备游标 |
-| `limit` | integer | 否 | 100 | 最大条数（受 `pull_max_limit` 配置限制） |
+| `limit` | integer | 否 | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
 **响应**：
@@ -1446,7 +1460,7 @@ result = await client.call("group.thought.get", {
     "events": [ ... ],
     "latest_event_seq": 100,
     "has_more": false,
-    "limit": 100,
+    "limit": 50,
     "cursor": {
         "current_seq": 50,
         "join_seq": 0,
@@ -1466,7 +1480,7 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `msg_seq` | integer | 是 | 确认到的消息序号 |
@@ -1482,7 +1496,7 @@ result = await client.call("group.thought.get", {
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `group_id` | string | 是 | 群组 ID |
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
 | `device_id` | string | 是 | 设备 ID |
 | `event_seq` | integer | 是 | 确认到的事件序号 |
@@ -1492,7 +1506,7 @@ result = await client.call("group.thought.get", {
 列出当前用户在指定群组的所有设备及游标状态。
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：
@@ -1515,7 +1529,7 @@ result = await client.call("group.thought.get", {
 注销设备游标（清理不再使用的设备记录）。
-**参数**：`group_id` (必填), `device_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`），`device_id` (必填)
 **响应**：`{ "success": true }`
@@ -1527,7 +1541,7 @@ result = await client.call("group.thought.get", {
 获取管理员列表（owner + admin 角色）。
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：
@@ -1538,7 +1552,7 @@ result = await client.call("group.thought.get", {
             "aid": "alice.agentid.pub",
             "role": "owner",
             "member_type": "human",
-            "joined_at": 1234567890
+            "joined_at": 1234567890000
         }
     ]
 }
@@ -1548,7 +1562,7 @@ result = await client.call("group.thought.get", {
 获取群主 AID。
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "owner_aid": "alice.agentid.pub" }`
@@ -1556,7 +1570,7 @@ result = await client.call("group.thought.get", {
 获取群组综合统计摘要。
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：
@@ -1575,8 +1589,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 +1599,7 @@ result = await client.call("group.thought.get", {
 刷新成员类型分类统计。
-**参数**：`group_id` (必填)
+**参数**：`group_id`（必填；兼容字段，值使用目标态 `group_aid`）
 **响应**：
@@ -1641,14 +1655,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 +1700,9 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.4.x
 | `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员封禁 |
 | `member_unbanned` | 成员解封 |
-| `resource_put` | 资源上传 |
-| `resource_updated` | 资源更新 |
-| `resource_deleted` | 资源删除 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
 **订阅**：
@@ -1715,11 +1726,21 @@ client.on("group.changed", lambda ev: print(ev["action"]))
     "type": "e2ee.group_encrypted",
     "dispatch_mode": "broadcast",
     "payload": { "type": "e2ee.group_encrypted", "..." : "..." },
-    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
-    "kind": "group.broadcast",
-    "member_aids": ["bob.agentid.pub"]
-}
-```
+    "dispatch": {"mode": "broadcast", "reason": "duty_disabled"},
+    "kind": "group.broadcast",
+    "member_aids": ["bob.agentid.pub"],
+    "proximity": {
+        "same_device": false,
+        "same_egress_ip": true,
+        "same_network": true,
+        "basis": "egress_ip",
+        "asserted_by": "gateway"
+    },
+    "same_device": false,
+    "same_egress_ip": true,
+    "same_network": true
+}
+```
 SDK 收到后自动解密 `payload`，解密后的明文消息直接交付用户回调。
@@ -1760,7 +1781,7 @@ SDK 收到后自动调用 `group.pull` 拉取最新消息并逐条解密后交
 }
 ```
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等别名，下一个大版本 0.5.* 将移除这些顶层别名；请通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` / `dispatch_mode` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
 ### event/group.message_recalled
@@ -1792,13 +1813,13 @@ SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；群消息信
 }
 ```
-SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.4.x 兼容期仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等别名，下一个大版本 0.5.* 将移除这些顶层别名。
+SDK 交付给应用层的撤回事件同样带 `envelope`。`envelope` 表示当前交付的撤回 tombstone / 通知自身信封，不是被撤回原消息的信封；业务侧被撤回的原消息列表继续使用 `message_ids` / `target_message_seqs`。`message_id` / `seq` 继续只保留在顶层兼容字段中，不进入 `envelope`。0.5.x 当前仍保留顶层 `group_id` / `seq` / `message_id` / `sender_aid` 等兼容别名；新代码应优先读取 `envelope`、`message_ids` 和 `target_message_seqs`。
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `envelope` | object | 撤回 tombstone / 通知自身信封，包含 `group_id`、`from`、`type`、`kind`、`timestamp`、`encrypted`、`context`、`protected_headers` 等存在的字段 |
 | `module_id` | string | 固定 `"group"` |
-| `group_id` | string | 群组 ID |
+| `group_id` | string | 兼容字段，值语义为目标态 `group_aid` |
 | `seq` | integer | 当前交付的撤回 tombstone / 通知 seq；在线 push 为 notice_seq，原 seq 占位 tombstone 为原消息 seq |
 | `message_id` | string | 当前交付的撤回 tombstone / 通知自己的 message_id |
 | `tombstone_message_id` | string | 兼容别名，等同于撤回 tombstone / 通知自身的 `message_id` |