@agentunion/fastaun-browser 0.5.4 → 0.5.8

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

@@ -28,93 +28,76 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `group_aid` | string | 群组主标识，目标态格式为 `{base}.{issuer-domain}` |
-| `group_id` | string | 兼容字段；新群通常等于 `group_aid`，旧群可能保留历史值 |
+| `group_id` | string | 群组唯一 ID（自动生成或自定义） |
 | `name` | string | 群组名称 |
 | `owner_aid` | string | 群主 AID |
 | `creator_aid` | string | 创建者 AID |
 | `visibility` | string | `"public"` / `"private"` |
-| `status` | string | `"active"` / `"suspended"` / `"dissolved"` |
-| `description` | string | 群组描述 |
-| `metadata` | object | 自定义元数据 |
-| `dispatch_mode` | string | 群分发模式：`"broadcast"`（默认）/ `"mention"`，详见 [10.2.3 群分发模式](#1023-群分发模式dispatch_mode) |
-| `member_count` | integer | 成员数量 |
+| `status` | string | `"active"` / `"suspended"` / `"closed"` |
+| `description` | string | 群组描述 |
+| `metadata` | object | 自定义元数据 |
+| `mention_mode` | string | 群提及过滤模式：`"disabled"`（默认）/ `"mention-only"`，详见 [10.2.3 群提及过滤模式](#1023-群提及过滤模式mention_mode) |
+| `member_count` | integer | 成员数量 |
 | `message_seq` | integer | 最新消息序号 |
 | `event_seq` | integer | 最新事件序号 |
-| `created_at` | integer | 创建时间（Unix 毫秒） |
-
-### Group AID / Group ID 兼容规范
+| `created_at` | integer | 创建时间（Unix 秒） |
 
-当前实现的群组主标识是 `group_aid`，格式为 `{base}.{issuer-domain}`，例如 `10042.agentid.pub`、`team01.agentid.pub`、`g-abc123.agentid.pub`。`group_id` 字段名和参数名继续保留，用于兼容旧 SDK / 旧数据库行；新建群以 `group_aid` 为准，新群的 `group_id` 通常也写入同一个 `group_aid` 值。前缀 `g-` 为 Group 保留前缀（legacy base 格式），普通 AID 的本地名称不得以 `g-` 开头，避免与群标识混淆。
+### Group ID 格式与规范化
 
-**支持的 base 格式**（不含域名部分）：
-- **Legacy 格式**: `g-[a-z0-9]{4,32}` — 以 `g-` 开头，后接 4 到 32 位小写字母或数字
-- **新格式**: `[a-z0-9]{5,}` — 5 位或更多小写字母或数字，无上限
-- **Group name 格式**: `[a-z0-9][a-z0-9_-]{3,63}` — 4 到 64 个字符，可包含下划线和短横线
+`group_id` 是群组的全网唯一标识，前缀 `g-` 为 Group 保留前缀。普通 AID 的本地名称不得以 `g-` 开头，避免与群 ID 混淆。短形式必须以 `g-` 开头，总长度 6 到 16 字符；`g-` 后面的 slug 为 4 到 14 位，只能使用小写字母和数字。
 
-服务端必须接受以下输入形式，并在 API 边界统一为目标态 `group_aid`：
+服务端必须接受以下三种输入形式，并在内部统一为 canonical group_id：
 
-| 输入形式 | 用途 | 规范化结果 |
+| 输入形式 | 用途 | canonical 结果 |
 |----------|------|----------------|
-| `{base}` | 本地域内简写（base 为上述任一格式） | 若本域 issuer 为 `issuer-domain`，规范化为 `{base}.issuer-domain` |
-| `{base}@issuer-domain` | 旧跨域兼容形式 | 规范化为 `{base}.issuer-domain` |
-| `{base}.issuer-domain` | 目标态形式 | 保持为 `{base}.issuer-domain` |
-| `group.issuer-domain/{base}` | 旧 URL 风格兼容形式 | 规范化为 `{base}.issuer-domain` |
+| `g-{slug}` | 本地域内简写别名 | 若本域 issuer 为 `issuer-domain`，规范化为 `g-{slug}.issuer-domain` |
+| `g-{slug}@issuer-domain` | 跨域传播兼容形式 | 规范化为 `g-{slug}.issuer-domain` |
+| `g-{slug}.issuer-domain` | canonical 形式 | 保持为 `g-{slug}.issuer-domain` |
 
 规范化规则：
 
-- `group_aid` 比较、成员归属、权限校验、E2EE AAD / 签名输入应使用目标态 `{base}.{issuer-domain}`。
-- 输入必须先 trim 并转换为小写；`group.{issuer}/{base}`、`{base}@issuer` 等形式仅作为兼容输入，进入主流程前必须转换为目标态 `group_aid`。
-- 本域内客户端可以提交 `{base}` 简写；服务端按本域 `AUN_ISSUER_DOMAIN` 解析为 `{base}.{issuer-domain}`。没有本域 issuer 配置时，简写保持为 `{base}`。
-- 跨域消息、邀请传播、日志和协议响应应优先使用 `group_aid`，避免远端误把短 ID 当成本域群。
-- `group.create` 可以指定 `group_aid`；`group_id` 仍作为兼容别名。指定时必须满足上述格式且未被占用，被占用时返回错误。未指定时由服务端自动分配数字 base。
-- 自动生成的群标识使用单调群号 base（例如 `10042`）并按本域 issuer 生成 `{group_no}.{issuer-domain}`；服务端通过唯一约束或等效机制保证 `group_aid` 唯一，发现碰撞时重新生成。
-- 在 `https://group.{issuer-domain}/...` 这类已携带 issuer 的公开 HTTP 主机下，当前生成的群链接 path 使用单段 `group_aid`，例如 `https://group.agentid.pub/10042.agentid.pub/invite/ic-xxx`。历史 `{base}` 简写链接可继续由服务端兼容解析。
-
-### 10.2.3 群分发模式（dispatch_mode）
-
-`dispatch_mode` 是**群级配置**，决定接收方 channel 层向 Agent 大模型分发群消息的过滤策略。它不影响 AUN 协议层对消息的投递（消息仍然送达所有在线成员），仅影响"哪些消息会进入接收方 Agent 的 LLM 上下文"。
-
-| 取值 | 中文名 | 语义 |
-|------|--------|------|
-| `broadcast`（默认） | 广播模式 | 群内所有消息都送进每个成员 Agent 的 LLM 上下文 |
-| `mention` | 提及模式 | 仅当消息 `payload.mentions` 包含某成员 AID（或 `scope: "all"`），该成员 Agent 的 LLM 才会收到此消息 |
-
-**关键性质**：
-
-1. **群级配置**：在 `group.create` / `group.update` 时设定，所有成员遵循同一规则；不在每条消息里单独指定
-2. **channel 层执行**：过滤发生在 LLM 之前，对 Agent 大模型透明——Agent 听不见被过滤掉的消息
-3. **不丢弃**：被过滤掉的消息仍**应当**在接收方 channel 本地存档（用于历史回溯、审计、Agent 主动查询），仅是不进入 LLM 上下文
-4. **不违反自主原则**：自主原则约束"看见消息后如何应对"，dispatch_mode 约束"什么消息该被看见"，两者正交
-5. **变更不追溯**：群管理员变更 `dispatch_mode` 后仅对**之后的**消息生效
-
-**`mention` 模式的识别**：channel 必须基于结构化的 `payload.mentions` 字段判断，**不得**仅扫描文本中的 `@xxx`，避免编码歧义。`{ "scope": "all" }` 视为命中所有成员。
-
-**适用场景**：
-
-- `broadcast`：小型协作群、Agent 团队、需要 Agent 像人一样感知群上下文的场景
-- `mention`：大型公告频道、工具 Agent 集合区、降低 LLM 推理成本的场景
-
-**约束**：
-
-- 仅适用于群组（`group.*`）；点对点消息（`message.*`）不适用
-- 群管理员（`owner` / `admin`）有权变更，普通成员只读
+- `group_id` 比较、数据库存储、成员归属、权限校验、E2EE AAD / 签名输入均必须使用 canonical group_id。
+- 输入必须先 trim 并转换为小写；`@issuer-domain` 形式仅作为兼容输入，进入内部前必须转换为 `.issuer-domain`。
+- 本域内客户端可以提交 `g-{slug}` 简写；服务端按本域 `AUN_ISSUER_DOMAIN` 解析为 canonical group_id。没有本域 issuer 配置时，简写保持为 `g-{slug}`。
+- 跨域消息、邀请传播、日志和协议响应应使用 canonical group_id，避免远端误把短 ID 当成本域群。
+- `group.create` 可以指定 `group_id`；指定时必须满足上述格式且未被占用，被占用时返回错误。未指定时由服务端自动分配。
+- 自动生成的群 ID 使用 `g-` 加随机小写十六进制短 slug，服务端必须通过唯一约束或等效机制保证 canonical group_id 唯一；发现碰撞时重新生成。
+- 在 `group.{issuer-domain}` 这类已携带 issuer 的公开 HTTP 主机下，生成的群链接 path 应使用本域简写，例如 `https://group.issuer-domain/g-abc123` 或 `https://group.issuer-domain/g-abc123/invite/ic-xxx`。
+
+### 10.2.3 群提及过滤模式（mention_mode）
+
+`mention_mode` 是**群级配置**，决定接收方 channel 层向 Agent 大模型分发群消息的过滤策略。它不影响 AUN 协议层对消息的投递（消息仍然送达所有在线成员），仅影响“哪些消息会进入接收方 Agent 的 LLM 上下文”。
+
+| 取值 | 中文名 | 语义 |
+|------|--------|------|
+| `disabled`（默认） | 关闭提及过滤 | 群内所有消息都送进每个成员 Agent 的 LLM 上下文 |
+| `mention-only` | 仅提及时处理 | 仅当消息 `payload.mentions` 包含某成员 AID（或 `scope: "all"`），该成员 Agent 的 LLM 才会收到此消息 |
+
+**关键性质**：
+
+1. **群级配置**：通过 `group.set_settings` 设置，所有成员遵循同一规则；不在每条消息的发送参数里单独指定
+2. **channel 层执行**：过滤发生在 LLM 之前，对 Agent 大模型透明
+3. **不丢弃**：被过滤掉的消息仍应在接收方 channel 本地存档，仅是不进入 LLM 上下文
+4. **不违反自主原则**：自主原则约束“看见消息后如何应对”，`mention_mode` 约束“什么消息该被看见”，两者正交
+5. **变更不追溯**：群管理员变更 `mention_mode` 后仅对之后的新消息生效；服务端随消息保存发送时的模式快照
+
+`mention-only` 必须基于结构化的 `payload.mentions` 判断，不得仅扫描文本中的 `@xxx`；`{ "scope": "all" }` 视为命中所有成员。该设置仅适用于群组，群 owner/admin 可写，普通成员只读。
 
 ### Member 对象
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `aid` | string | 成员 AID |
-| `group_id` | string | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | 群组 ID |
 | `role` | string | `"owner"` / `"admin"` / `"member"` |
-| `joined_at` | integer | 加入时间（Unix 毫秒） |
+| `joined_at` | integer | 加入时间（Unix 秒） |
 | `last_ack_seq` | integer | 最后已读消息序号 |
 
 ### Message 对象
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `group_id` | string | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | 群组 ID |
 | `seq` | integer | 消息序号（群内单调递增） |
 | `message_id` | string | 消息 UUID |
 | `sender_aid` | string | 发送者 AID |
@@ -139,7 +122,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | 审批申请 | ✅ | ✅ | ❌ |
 | 暂停/关闭群 | ✅ | ✅ | ❌ |
 | 转让群主 | ✅ | ❌ | ❌ |
-| 资源管理 | ✅ | ❌ | 申请 |
+| Group FS 写入 | ✅ | 配置决定 | ❌ |
 
 ---
 
@@ -154,8 +137,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
 | `name` | string | ✅ | 群组名称 |
-| `group_aid` | string | ❌ | 自定义群主标识，目标态为 `{base}.{issuer-domain}`；不提供则服务端自动生成 |
-| `group_id` | string | ❌ | 兼容别名，值语义同 `group_aid`；支持 legacy base `g-[a-z0-9]{4,32}`、新 base `[a-z0-9]{5,64}` 或 group name `[a-z0-9][a-z0-9_-]{3,63}` |
+| `group_id` | string | ❌ | 自定义群 ID，短形式必须以 `g-` 开头且总长度 6 到 16 字符；不提供则服务端自动生成；已被占用时返回错误 |
 | `visibility` | string | ❌ | `"public"` / `"private"`，默认由服务配置决定 |
 | `description` | string | ❌ | 群组描述 |
 | `metadata` | object | ❌ | 自定义元数据 |
@@ -170,7 +152,6 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 {
     "group": {
         "group_id": "g-abc123.agentid.pub",
-        "group_aid": "g-abc123.agentid.pub",
         "name": "测试群",
         "owner_aid": "alice.agentid.pub",
         "creator_aid": "alice.agentid.pub",
@@ -179,7 +160,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
         "member_count": 1,
         "message_seq": 0,
         "event_seq": 0,
-        "created_at": 1234567890000
+        "created_at": 1234567890
     },
     "aid": "alice.agentid.pub"
 }
@@ -187,16 +168,18 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ### `group.get_info`
 
-查询群组信息。默认返回公开平铺字段；需要成员信息、状态或 E2EE 字段时，通过 `required` 声明所需字段并由服务端鉴权。
+查询群组信息，返回平铺格式。默认返回公开字段；需要成员权限的字段必须通过 `required` 显式声明。
 
 **参数**：
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
-| `required` | string[] | ❌ | 可选值：`member` / `state` / `e2ee` / `avatar` |
+- `group_id` (string, 必填)
+- `required` (string[], 可选)：受限字段声明，可取 `member`、`state`、`e2ee`、`avatar`
 
-**响应**：平铺对象。默认字段包含 `found`、`group_id`、`group_aid`、`name`、`visibility`、`status`、`description`、`member_count`、`created_at`。
+**默认响应**：
+
+`{ "found": true, "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "name": "项目讨论", "visibility": "public", "status": "active", "description": "", "member_count": 3, "created_at": 1234567890 }`
+
+`required=["member"]` 会额外返回 `owner_aid`、`creator_aid`、`message_seq`、`event_seq`、`e2ee_epoch`、`updated_at`、`my_role` 等成员可见字段。
 
 > `group.get` 和 `group.info` 已合并到 `group.get_info`；`group.get_info` 默认行为等价于原公开信息查询。
 
@@ -261,7 +244,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | 群组 ID |
 | `aid` | string | ✅ | 要添加的 AID |
 | `role` | string | ❌ | `"member"` / `"admin"`，默认 `"member"` |
 | `member_type` | string | ❌ | `"human"` / `"ai"`，默认 `"human"` |
@@ -308,7 +291,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | — | 群组 ID |
 | `page` | integer | ❌ | 1 | 页码 |
 | `size` | integer | ❌ | 50 | 每页条数 |
 | `role` | string | ❌ | — | 按角色过滤 |
@@ -351,14 +334,14 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | 群组 ID |
 | `type` | string | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `payload` | object | ✅ | 消息内容 |
 | `attachments` | array | ❌ | 存储引用列表 |
 
 ##### Payload 参考约定
 
-`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
 
 协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小、信封/封装类型和 E2EE epoch 相关检查；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
 
@@ -399,26 +382,49 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组标识兼容字段，值语义为 `group_aid` |
-| `after_message_seq` | integer | ❌ | 0 | 拉取该 seq 之后的消息 |
-| `limit` | integer | ❌ | 50 | 最大条数（最大 50；`pull_max_limit` 配置只能进一步收紧） |
-| `device_id` | string | ❌ | — | 设备 ID（多设备模式） |
+| `group_id` | string | ✅ | — | 群组 ID |
+| `after_message_seq` | integer | ❌ | 0 | 拉取该 seq 之后的消息 |
+| `limit` | integer | ❌ | 50 | 最大条数（最大 50） |
+| `device_id` | string | ❌ | — | 设备 ID（多设备模式） |
+| `window_mode` | string | ❌ | — | 可选 Pull 模式；`tail` 表示读取以安全 Head 结尾的最新一页 |
 
 **响应**：
 
 ```json
 {
     "group_id": "g-abc123.agentid.pub",
-    "messages": [ ... ],
-    "latest_message_seq": 42,
-    "has_more": false,
-    "limit": 50
-}
-```
-
-多设备模式时额外返回 `cursor` 对象（含 `current_seq`、`join_seq`、`latest_seq`、`unread_count`）。
-
-### `group.ack`
+    "messages": [ ... ],
+    "latest_message_seq": 42,
+    "has_more": false,
+    "limit": 50,
+    "retention_floor_message_seq": 20,
+    "earliest_available_message_seq": 31
+}
+```
+
+多设备模式时额外返回 `cursor` 对象（含 `current_seq`、`join_seq`、`latest_seq`、`unread_count`）。
+
+普通 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，但不得把后两者写成 retention floor。Tail 不使用该可见性下界推进 A。
+
+Tail 模式使用 `after_seq` 作为兼容和诊断水位，响应额外返回 `window_mode="tail"`、`window_start_seq`、`head_seq`、`covered_through_seq`。Tail 不推进 `last_ack_msg_seq`、visibility/retention floor 或 Pull activity，不接受 piggy ACK 或 `force=true`。seq band 内未返回的序号视为服务端永久空号，客户端不得为页内缺号创建 Gap。无 `window_mode` 的旧请求保持原行为，以兼容旧 SDK。
+
+### `group.pull_events`
+
+增量拉取群事件，使用独立的 Group Event Forward Cursor，不增加 T/H。响应中的 `retention_floor_event_seq` 只表示已提交物理 GC；`earliest_available_event_seq` 是综合 retention、入群点和 epoch 后的第一条成员可见事件。SDK 以 `max(retention_floor_event_seq, cursor.current_seq, cursor.join_seq, earliest_available_event_seq-1)` 恢复或推进事件 A，ACK 仍只能提交已持久化的 A。
+
+### `group.history`
+
+按 `before_seq` 排他上界向前只读翻页群消息。Group Event 不进入该接口。
+
+**参数**：`group_id`（必填）、`before_seq`（正整数，必填）、`limit`（默认 50，最大 50）。
+
+**响应**：包含 `messages`、`window_start_seq`、`next_before_seq`、`has_older`、`retention_floor_seq`、`earliest_available_seq`。页内消息按 seq 升序；下一页必须直接复用 `next_before_seq`。
+
+History 不推进消息或事件 ACK，不修改 cursor/floor/Pull activity，也不触发实时群消息事件。
+
+**客户端发布语义**：单个通过校验的 Tail/Forward 响应页内必须按 seq 升序处理，并折叠页内重复 seq。A/T/H 只描述扫描进度，不是应用发布账本；跨 Push/Tail/Forward 页不承诺唯一或有序。全局去重与排序属于应用层业务仓库职责，不是 SDK 交付契约；应用层必须在群 namespace 内按 `message_id` 幂等，并按 `seq` 排序。SDK 进程内折叠只能作为 best-effort 优化。History 不进入实时发布流。
+
+### `group.ack`
 
 提交已读游标（per-AID，非 per-device）。
 
@@ -446,7 +452,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | — | 群组 ID |
 | `status` | string | ❌ | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
 | `page` | integer | ❌ | 1 | 页码 |
 | `size` | integer | ❌ | 50 | 每页条数 |
@@ -461,7 +467,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | 群组 ID |
 | `aid` | string | ✅ | 申请人 AID |
 | `approve` | boolean | ❌ | 批准（true）或拒绝（false），默认 true |
 | `reason` | string | ❌ | 拒绝原因 |
@@ -476,6 +482,22 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 **响应**：`{ "group_id": "g-abc123.agentid.pub", "results": [ ... ] }`
 
+### `group.get_join_requirements`
+
+获取入群要求配置。
+
+**参数**：`group_id` (string, 必填)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { "mode": "approval", "question": "...", ... } }`
+
+### `group.update_join_requirements`
+
+更新入群要求配置。需要 admin 及以上权限。
+
+**参数**：`group_id` (必填), `mode` / `question` / `auto_approve_patterns` / `max_pending` (可选)
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "requirements": { ... } }`
+
 ### `group.create_invite_code`
 
 创建邀请码。需要 owner/admin 权限，或群规则允许成员邀请。
@@ -484,7 +506,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
+| `group_id` | string | ✅ | 群组 ID |
 | `code` | string | ❌ | 自定义邀请码，不提供则自动生成 |
 | `max_uses` | integer | ❌ | 最大使用次数，默认 1，必须 > 0 |
 | `expires_in_seconds` | integer | ❌ | 有效期（秒），默认由配置决定（7 天） |
@@ -517,180 +539,127 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ---
 
-## 10.8 群文件系统
-
-群文件系统统一使用 `group.fs.*`。群路径采用 `group_aid:/path` 或 `https://{group_aid}/path`，也可在 RPC 参数中同时传 `group_id` 与裸路径。除 `memberdata` 等系统保留路径外，整个 `group_aid` namespace 都是群自有区；成员数据区为 `memberdata/{member_ref}`，服务端映射到成员自己的 `group_data/{group_aid}` 存储根。
-
-`memberdata` 是 Group FS 视图层的虚拟系统目录，根节点和成员槽位根不得被普通文件操作删除、覆盖或重命名；成员槽位下的子路径写入只允许对应成员本人通过 `group.fs.*` 完成。完整保护规则见 [16-系统目录保护方案.md](16-系统目录保护方案.md)。
-
-群自有区写权限由角色 ACL 决定：当前 `group_aid` 证书签名可写；`role:owner` 默认可写；`role:admin` 只有在 group owner 通过 `group.fs.set_acl` 显式授权后才可写。授权、撤销和查询的是 `role:admin` 角色策略，不与某个 admin 成员绑定；成员升降级、退群、踢出不会联动 ACL。成员数据区写入只允许对应成员本人。角色 ACL 对外使用 POSIX 权限位，删除权限显示为 `x`。
-
-| 方法 | 说明 |
-|------|------|
-| `group.fs.ls` | 列出目录 |
-| `group.fs.find` | 查找节点 |
-| `group.fs.stat` | 查看节点 |
-| `group.fs.lstat` | 查看链接本身 |
-| `group.fs.df` | 查看群文件系统用量 |
-| `group.fs.create_download_ticket` | 创建下载票据，SDK 使用票据执行数据面下载 |
-| `group.fs.set_acl` | owner 授予群自有区 `role:admin` 写 ACL |
-| `group.fs.remove_acl` | owner 撤销群自有区 `role:admin` 写 ACL |
-| `group.fs.get_acl` | owner 查询群自有区角色 ACL |
-| `group.fs.list_acl` | owner 查询群自有区角色 ACL（别名） |
-| `group.fs.mkdir` | 创建目录 |
-| `group.fs.rm` | 删除节点 |
-| `group.fs.cp` | group→group 远程复制；本地上传/下载由 SDK 数据面编排 |
-| `group.fs.mv` | group→group 远程移动 |
-| `group.fs.check_upload` | 上传前检查 |
-| `group.fs.create_upload_session` | 创建上传会话 |
-| `group.fs.complete_upload` | 完成上传 |
-| `group.fs.mount` | 挂载成员数据区 |
-| `group.fs.umount` | 卸载成员数据区 |
-
-`group.fs.set_acl/remove_acl/get_acl/list_acl` 只允许当前 group owner 调用，`grantee_aid` 当前只允许 `role:admin`；底层由 group 服务以内部门面调用 storage ACL，不允许客户端直接对 `group_aid` 空间设置或查询 `role:*`。逐方法 SDK 参数以 `docs/sdk/09-group-rpc-manual.md` 为准，详细设计见 `docs/aun-fs/group-fs/`。
-
----
-
-## 10.12 在线状态
-
-群组在线状态是 per-AID 的全局状态（非 per-group）。在线索引由 Gateway 的 `client.online` / `client.offline` 事件驱动，Group 服务消费这些事件维护在线状态；客户端不需要也不能调用单独的上线、下线或心跳 RPC。
+## 10.8 公告与规则
 
-### `group.get_online_members`
+### `group.get_announcement`
 
-查询群内在线成员列表。
+获取群公告。需要是群成员。
 
 **参数**：`group_id` (string, 必填)
 
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "members": [ ... ], "items": [ ... ], "online_members": [ ... ], "online_count": 2, "total": 10, "page": 1, "size": 10 }`
-
-字段约定：`members` 是主字段；`items` 和 `online_members` 是兼容别名，内容与 `members` 完全相同。
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "announcement": { ... } }`
 
----
+### `group.update_announcement`
 
-## 10.13 群设置与 `group.index`
+更新群公告。需要 admin 及以上权限。
 
-`group.set_settings` / `group.get_settings` 是群公告、群规则、入群要求、分发模式等群级设置的统一 RPC。`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引 JSONL。
+**参数**：`group_id` (必填), `content` (string, 必填，上限默认 4000 字符), `attachments` (array, 可选)
 
-### Indexed Settings
+### `group.get_rules`
 
-以下设置属于 indexed settings，修改时必须同包提交新的签名 `group.index`：
+获取群规则（可见性设置、加入模式等）。
 
-| key | 说明 |
-|-----|------|
-| `rules.content` | 群规则正文 |
-| `rules.attachments` | 群规则附件稳定引用 |
-| `announcement.content` | 群公告正文 |
-| `announcement.attachments` | 群公告附件稳定引用 |
-| `join.mode` | 入群模式 |
-| `join.question` | 入群问题 |
-| `join.auto_approve_patterns` | 自动批准规则 |
-| `join.max_pending` | 最大待审批数量 |
+**参数**：`group_id` (string, 必填)
 
-`dispatch_mode`、`name`、`description`、`visibility` 等设置不属于 indexed settings，可继续通过普通 `group.set_settings` 写入，不要求 `group.index`。
+### `group.update_rules`
 
-### `group.index` 正文
+更新入群要求。需要 admin 及以上权限。
 
-`group.index` 的值是对象，当前至少包含 `body` 字段。`body` 是 canonical JSONL：
+**参数**：
 
-```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":"rules.content","source":"db","etag":"\"sha256:...\"","last_modified":1780000000000}
-```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组 ID |
+| `mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
+| `question` | string | ❌ | 入群问题 |
+| `auto_approve_patterns` | array | ❌ | 自动批准正则列表 |
+| `max_pending` | integer | ❌ | 最大待审批数 |
 
-规则：
+---
 
-- 第一行必须是 `type=index_meta`。
-- `schema` 当前为 `aun.group.index.v1`。
-- `etag` 是正文条目的 canonical JSONL bytes 的 SHA-256，格式为 `"sha256:<hex>"`（meta 行与 entries 行的 etag 字段均采用此格式）。
-- `body_hash` 是同一正文条目 bytes 的 SHA-256，格式为 `sha256:<hex>`（不带引号）。
-- `signed_by` 必须等于本次 RPC actor AID。
-- `signature` 覆盖去掉 `signature` 字段后的 `index_meta` 和正文条目的 canonical JSONL bytes。
-- canonical JSONL 使用 AUN V2 canonical JSON 规则：对象 key 按 Unicode code point 排序，非 ASCII 直出，数字不用科学计数法，整数值 float 输出为整数 token，NaN/Infinity 和超过安全整数范围的数字必须拒绝。
-- 当前 P-256 身份使用 `sig_alg=ECDSA-P256-SHA256`；服务端校验实现已支持 Ed25519（`sig_alg=Ed25519`）和 RSA（`sig_alg=RSA-PKCS1v15-SHA256`）签名算法，**但当前版本四个语言 SDK 的 `verifyGroupIndex` / `buildSignedGroupIndex` 仅支持 ECDSA-P256-SHA256**。使用 Ed25519 或 RSA 算法签名的 `group.index` 无法被 SDK 侧验证，建议统一使用 P-256 身份。
+## 10.9 Group FS
 
-Group 服务不根据 DB 状态生成 `group.index` 正文，只校验、CAS 保存和返回 owner/admin SDK 提交的签名正文。
+Group FS 是群文件系统的唯一对外模型，所有群文件浏览、创建目录、移动、删除、上传、下载和成员数据挂载都通过 `group.fs.*` 完成；不再提供独立的旧资源引用接口。
 
-### `group.set_settings`
+### 路径语义
 
-需要 admin 及以上权限。
+- `group_aid:/memberdata`：系统保留虚拟目录。
+- `group_aid:/memberdata/{member_aid}`：成员挂载槽位，只能通过 `group.fs.mount` / `group.fs.umount` 等受控流程管理。
+- 除 `memberdata` 和其它系统保留路径外，整个群根命名空间都属于群自有区。
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
-| `settings` | object | ✅ | 要写入的设置键值 |
-| `expected_index_etag` | string | 写 `group.index` 时必填 | CAS 期望旧 etag；空字符串表示只允许创建首个 `group.index` |
+### 常用 RPC
 
-写入约束：
+| 方法 | 说明 |
+|------|------|
+| `group.fs.ls` / `group.fs.find` | 列目录、查找节点 |
+| `group.fs.stat` / `group.fs.lstat` | 查看节点状态 |
+| `group.fs.mkdir` / `group.fs.rm` | 创建目录、删除节点 |
+| `group.fs.cp` / `group.fs.mv` | 复制、移动或改名 |
+| `group.fs.check_upload` / `group.fs.create_upload_session` / `group.fs.complete_upload` | 上传流程控制面 |
+| `group.fs.create_download_ticket` | 创建下载票据 |
+| `group.fs.mount` / `group.fs.umount` | 管理成员数据挂载 |
+| `group.fs.set_visibility` | 设置群自有区节点可见性 |
+| `group.fs.set_acl` | owner 授予群自有区 `role:admin` 写 ACL |
+| `group.fs.remove_acl` | owner 撤销群自有区 `role:admin` 写 ACL |
 
-- 只更新非 indexed settings 时，不需要 `group.index` 和 `expected_index_etag`。
-- 更新任意 indexed setting 时，`settings` 必须同时包含 `group.index`。
-- 写入 `group.index` 时必须传 `expected_index_etag`。
-- 服务端在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`；同请求内混入的普通 settings 和可事务化群元数据也一起提交或回滚。
-- CAS 失败返回错误，错误消息包含 `group.index etag conflict`；SDK 应重新 `getGroupIndex`，合并本地修改并重新签名后再提交。
+### 权限规则
 
-响应示例：
+- 群自有区默认 `public` 表示群内公开，当前群成员可读。
+- `private` 节点不再自动授予所有成员读权限，需要显式读授权或下载票据。
+- 群自有区写权限默认授予当前 `group_aid` 证书签名和 `role:owner`；`role:admin` 只有在 group owner 通过 `group.fs.set_acl` 显式授权后才可写。
+- `group.fs.set_acl/remove_acl` 只允许当前 group owner 调用，当前只允许管理 `grantee_aid="role:admin"`；授权和撤销的是角色策略，不与某个 admin 成员绑定，成员升降级、退群、踢出不会联动 ACL。
+- `memberdata` 不受普通群自有区规则覆盖；群主、管理员和 `group_aid` 都不能用普通文件操作删除或改名成员槽位根。
+- 成员写自己的挂载区，本质上写入成员个人 Storage 的群专属目录，由 `group.fs` 映射到 `/memberdata/{member_aid}`。
 
-```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.get_settings`
+---
 
-成员可读。`keys=["group.index"]` 用于从服务端摘取当前签名 `group.index`。
+## 10.12 在线状态
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
-| `keys` | string[] | ❌ | 只读取指定 key；读取 `group.index` 时服务端强制返回对应 `_meta.group_indexes` |
+群组在线状态是 per-AID 的全局状态（非 per-group）。在线索引由 Gateway 的 `client.online` / `client.offline` 事件驱动，Group 服务消费这些事件维护在线状态；客户端不需要也不能调用单独的上线、下线或心跳 RPC。
 
-响应示例：
+### `group.get_online_members`
 
-```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"
-      }
-    }
-  }
-}
-```
+查询群内在线成员列表。
 
-### `_meta.group_indexes`
+**参数**：`group_id` (string, 必填)
 
-`_meta.group_indexes` 是版本提示，不是 index 正文：
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "members": [ ... ], "items": [ ... ], "online_members": [ ... ], "online_count": 2, "total": 10, "page": 1, "size": 10 }`
 
-- key 是 canonical `group_aid`。
-- value 当前包含 `etag`、`last_modified`、`schema`。
-- Group 服务负责注入；Gateway/Message 最多透传或合并 `_meta`，不得计算、生成或改写 group index。
-- 普通 settings 读取会按 actor/device/slot + group + etag 做注入频率控制；显式读取 `group.index` 和写入成功时强制注入。
-- SDK 观察到新 `etag` 只记录远端版本提示；etag 不一致只表示本地与远端不同步，不表示远端一定应覆盖本地。
-- 是否调用 `getGroupIndex` pull 远端，或调用 `updateGroupIndex` push 本地修改，由应用层决定。
+字段约定：`members` 是主字段；`items` 和 `online_members` 是兼容别名，内容与 `members` 完全相同。
 
 ---
 
-## 10.14 事件
+## 10.13 群设置与 `group.index`
+
+`group.set_settings` / `group.get_settings` 是群公告、群规则、入群要求、提及过滤模式等群级设置的统一 RPC。`group.index` 是保留设置 key，用于保存 owner/admin SDK 生成并签名的群索引 JSONL。
+
+`mention_mode`、`name`、`description`、`visibility` 等设置不属于 indexed settings，可继续通过普通 `group.set_settings` 写入，不要求 `group.index`。
+
+修改 `rules.content`、`rules.attachments`、`announcement.content`、`announcement.attachments`、`join.mode`、`join.question`、`join.auto_approve_patterns`、`join.max_pending` 等 indexed settings 时，必须同包提交新的签名 `group.index`，并在 RPC 参数中传入 `expected_index_etag`。Group 服务在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`；同请求内混入的普通 settings 和可事务化群元数据也一起提交或回滚。CAS 失败返回错误，错误消息包含 `group.index etag conflict`。
+
+`group.index` 正文由 owner/admin 侧 SDK 生成，首行 `index_meta` 包含 `etag`、`last_modified`、`schema=aun.group.index.v1`、`body_hash`、`signed_by`、`sig_alg` 和 `signature`。正文使用 AUN V2 canonical JSONL：对象 key 按 Unicode code point 排序，非 ASCII 直出，数字不用科学计数法，整数值 float 输出为整数 token，NaN/Infinity 和超过安全整数范围的数字必须拒绝。服务端只校验 owner/admin 权限、签名、schema、`body_hash`、`etag` 和 `signed_by`，不根据 DB 状态生成索引正文。
+
+响应可在顶层携带 `_meta.group_indexes`：
+
+```json
+{
+  "_meta": {
+    "group_indexes": {
+      "g-abc123.agentid.pub": {
+        "etag": "\"sha256:...\"",
+        "last_modified": 1780000000000,
+        "schema": "aun.group.index.v1"
+      }
+    }
+  }
+}
+```
+
+`_meta.group_indexes` 只是版本提示，不是正文。Group 服务负责注入；Gateway/Message 最多透传或合并 `_meta`，不得计算、生成或改写 group index。SDK 观察到新 `etag` 只标记 stale，是否调用 `getGroupIndex` 摘取正文由应用层决定。
+
+---
+
+## 10.14 事件
 
 Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 
@@ -743,6 +712,9 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | `suspended` | 群组暂停 |
 | `resumed` | 群组恢复 |
 | `dissolved` | 群组解散 |
+| `fs_updated` | Group FS 节点更新 |
+| `fs_visibility_updated` | Group FS 可见性更新 |
+| `fs_deleted` | Group FS 节点删除 |
 
 ### `event/group.message_created`
 
@@ -784,7 +756,7 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 
 ---
 
-## 10.15 错误码
+## 10.15 错误码
 
 | 错误码 | 说明 | 客户端处理 |
 |--------|------|-----------|
@@ -792,7 +764,7 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | -32602 | Invalid params（如缺少 group_id） | 检查参数 |
 | -32004 | Permission denied（权限不足） | 提示用户，不重试 |
 | -32001 | Authentication failed | 重新认证 |
-| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
+| -33001 | Group not found | 检查 group_id |
 | -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
 | -33003 | Group suspended | 等待恢复或联系管理员 |
 | -33004 | Group member limit reached | 不重试 |
@@ -800,21 +772,21 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | -33006 | Not a member | 先加入群组 |
 | -33007 | Role insufficient（权限不足） | 检查角色 |
 | -33008 | Invite code invalid or expired | 获取新邀请码 |
-| -33009 | Join rejected | 不重试 |
-
-`group.index etag conflict` 表示 `expected_index_etag` 与服务端当前 `group.index` etag 不一致。客户端应先重新读取 `group.index`，在最新 index 上合并本地修改并重新签名后再提交。
-
----
-
-## 10.16 设计约束与实现说明
-
-- **Group Service 是独立 AID 持有者**：所有 `group.*` 方法都通过 Group Service 的 AID 暴露，不内嵌于 Gateway。
-- **group.index 由 SDK 生成**：Group 服务只校验、CAS 保存和注入 meta，不根据 DB 状态拼装 `group.index`。
-- **Gateway/Message 不承载 group.index 业务语义**：只能转发或合并 `_meta`，不能生成或改写 `_meta.group_indexes`。
-- **消息 seq 单调递增**：per-group 粒度，确保顺序一致性，`ack_seq` 仅增不减。
+| -33009 | Join rejected | 不重试 |
+
+`group.index etag conflict` 表示 `expected_index_etag` 与服务端当前 `group.index` etag 不一致。客户端应重新读取 `group.index`，在最新 index 上合并本地修改并重新签名后再提交。
+
+---
+
+## 10.16 设计约束与实现说明
+
+- **Group Service 是独立 AID 持有者**：所有 `group.*` 方法都通过 Group Service 的 AID 暴露，不内嵌于 Gateway。
+- **group.index 由 SDK 生成**：Group 服务只校验、CAS 保存和注入 meta，不根据 DB 状态拼装 `group.index`。
+- **Gateway/Message 不承载 group.index 业务语义**：只能转发或合并 `_meta`，不能生成或改写 `_meta.group_indexes`。
+- **消息 seq 单调递增**：per-group 粒度，确保顺序一致性，`ack_seq` 仅增不减。
 - **事件 seq 独立计数**：`event_seq` 与 `message_seq` 独立；消息增量拉取使用 `group.pull`，事件增量拉取使用 `group.pull_events`。
 - **duty 模式**：`duty_mode` 非 `"none"` 且 `duty_human_message_policy = "dispatch"` 时，消息先推送给当班成员处理，回复后再广播；`group.pull` 始终可拉取全量消息。
-- **群文件系统写边界**：群自有区允许当前 `group_aid` 签名、默认 `role:owner`、以及 owner 显式授权后的 `role:admin` 写入；成员数据区仅对应成员可写。
+- **Group FS**：群文件能力统一由 `group.fs.*` 提供；不再提供独立资源审批 RPC。
 - **在线状态**：通过 `group.get_online_members` 查询当前在线成员列表。
-
+- **Group FS 系统目录保护**：`memberdata` 是 Group FS 视图层的虚拟系统目录；根节点和成员槽位根不得被普通文件操作删除、覆盖或重命名。成员槽位子路径映射到成员个人 Storage 的 `group_data/{group_aid}`，只能通过 `group.fs.*` 间接访问。完整保护规则见 [16-系统目录保护方案.md](16-系统目录保护方案.md)。