@agentunion/fastaun-browser 0.5.0 → 0.5.2

package/_packed_docs/protocol/08-AUN-E2EE.md

@@ -1,10 +1,12 @@
-# AUN-E2EE 扩展规范
-
-> 版本：2.0-draft
-> 状态：规范性文档
-> 适用范围：AUN 客户端 SDK、客户端应用、跨语言实现
-> 不适用范围：Gateway、Message 模块的加解密实现
-> 定位：**独立安全层**，横跨 `gateway`、`peer`、`relay` 三种连接模式
+# AUN-E2EE 历史扩展规范（Legacy）
+
+> 版本：2.0-draft
+> 状态：历史兼容文档
+> 适用范围：AUN 客户端 SDK、客户端应用、跨语言实现
+> 不适用范围：Gateway、Message 模块的加解密实现
+> 定位：旧 P2P E2EE 信封说明；当前默认主路径已迁移到 E2EE V2 多设备 wrap
+
+> **当前实现说明**：最近版本的 SDK 默认使用 V2 多设备 wrap。P2P 加密消息通过 `message.send` 承载 `e2ee.p2p_encrypted` envelope，Group 加密消息通过 `group.v2.send` 承载 `e2ee.group_encrypted` envelope；每条消息一把 `master_key`，按 recipient 设备生成 `3DH` / `1DH` wrap，接收端验证 `sender_signature`、AAD、recipient digest/proof 后解密。当前 V2 链路见 [E2EE_V2消息通信时序图](../sdk/E2EE_V2消息通信时序图.md)；群组 V2 规范见 [08-AUN-E2EE-Group](08-AUN-E2EE-Group.md)。本文保留 `prekey_ecdh_v2` / `long_term_key` 旧格式，用于历史兼容和迁移排查，不应作为新实现的默认发送格式。
 
 ---
 
@@ -108,7 +110,7 @@ AUN-E2EE 是 Layer 3 扩展协议，建立在以下核心能力之上：
 
 ### 5.2 密文消息
 
-通过 `message.send` 传输的加密业务消息，`encrypted` 必须为 `true`，`payload.type` 必须为 `e2ee.encrypted`。
+旧 `e2ee.encrypted` 信封通过 `message.send` 传输时，`encrypted` 必须为 `true`，`payload.type` 必须为 `e2ee.encrypted`。当前新实现应使用 V2 `e2ee.p2p_encrypted` 信封。
 
 ---
 
@@ -186,7 +188,7 @@ AUN-E2EE 支持两种加密模式，SDK 自动按优先级选择。
 
 ### 7.3 模式选择策略
 
-SDK **MUST** 按以下优先级自动选择：
+旧版 SDK 在 legacy 信封中按以下优先级自动选择：
 
 1. **优先**：prekey_ecdh_v2（服务端有接收方 prekey）
 2. **降级**：long_term_key（无 prekey 时，需客户端安全策略允许）
@@ -195,7 +197,7 @@ SDK **MUST** 按以下优先级自动选择：
 
 ### 7.4 兼容性
 
-- 发送端 **MUST** 使用 `prekey_ecdh_v2` 模式发送
+- 旧版发送端应优先使用 `prekey_ecdh_v2` 模式发送；当前新实现应使用 V2 多设备 wrap。
 
 ---
 

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

@@ -26,43 +26,50 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ### Group 对象
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组唯一 ID（自动生成或自定义） |
-| `name` | string | 群组名称 |
-| `owner_aid` | string | 群主 AID |
-| `creator_aid` | string | 创建者 AID |
-| `visibility` | string | `"public"` / `"private"` |
-| `status` | string | `"active"` / `"suspended"` / `"closed"` |
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `group_aid` | string | 群组主标识，目标态格式为 `{base}.{issuer-domain}` |
+| `group_id` | string | 兼容字段；新群通常等于 `group_aid`，旧群可能保留历史值 |
+| `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.x 群分发模式](#1023-群分发模式dispatch_mode) |
 | `member_count` | integer | 成员数量 |
 | `message_seq` | integer | 最新消息序号 |
 | `event_seq` | integer | 最新事件序号 |
-| `created_at` | integer | 创建时间（Unix 秒） |
-
-### Group ID 格式与规范化
-
-`group_id` 是群组的全网唯一标识，前缀 `g-` 为 Group 保留前缀。普通 AID 的本地名称不得以 `g-` 开头，避免与群 ID 混淆。短形式必须以 `g-` 开头，总长度 6 到 16 字符；`g-` 后面的 slug 为 4 到 14 位，只能使用小写字母和数字。
-
-服务端必须接受以下三种输入形式，并在内部统一为 canonical group_id：
-
-| 输入形式 | 用途 | canonical 结果 |
-|----------|------|----------------|
-| `g-{slug}` | 本地域内简写别名 | 若本域 issuer 为 `issuer-domain`，规范化为 `g-{slug}.issuer-domain` |
-| `g-{slug}@issuer-domain` | 跨域传播兼容形式 | 规范化为 `g-{slug}.issuer-domain` |
-| `g-{slug}.issuer-domain` | canonical 形式 | 保持为 `g-{slug}.issuer-domain` |
+| `created_at` | integer | 创建时间（Unix 毫秒） |
+
+### Group AID / Group ID 兼容规范
+
+当前实现的群组主标识是 `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-` 开头，避免与群标识混淆。
 
-规范化规则：
+**支持的 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` 比较、数据库存储、成员归属、权限校验、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`。
+服务端必须接受以下输入形式，并在 API 边界统一为目标态 `group_aid`：
+
+| 输入形式 | 用途 | 规范化结果 |
+|----------|------|----------------|
+| `{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` |
+
+规范化规则：
+
+- `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）
 
@@ -95,20 +102,20 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ### Member 对象
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `aid` | string | 成员 AID |
-| `group_id` | string | 群组 ID |
-| `role` | string | `"owner"` / `"admin"` / `"member"` |
-| `joined_at` | integer | 加入时间（Unix 秒） |
-| `last_ack_seq` | integer | 最后已读消息序号 |
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aid` | string | 成员 AID |
+| `group_id` | string | 群组标识兼容字段，值语义为 `group_aid` |
+| `role` | string | `"owner"` / `"admin"` / `"member"` |
+| `joined_at` | integer | 加入时间（Unix 毫秒） |
+| `last_ack_seq` | integer | 最后已读消息序号 |
 
 ### Message 对象
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `group_id` | string | 群组 ID |
-| `seq` | integer | 消息序号（群内单调递增） |
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `group_id` | string | 群组标识兼容字段，值语义为 `group_aid` |
+| `seq` | integer | 消息序号（群内单调递增） |
 | `message_id` | string | 消息 UUID |
 | `sender_aid` | string | 发送者 AID |
 | `message_type` | string | 信封/封装类型，如 `e2ee.group_encrypted`；业务负载类型在 `payload.type` 中 |
@@ -144,10 +151,11 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 **参数**：
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `name` | string | ✅ | 群组名称 |
-| `group_id` | string | ❌ | 自定义群 ID，短形式必须以 `g-` 开头且总长度 6 到 16 字符；不提供则服务端自动生成；已被占用时返回错误 |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `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}` |
 | `visibility` | string | ❌ | `"public"` / `"private"`，默认由服务配置决定 |
 | `description` | string | ❌ | 群组描述 |
 | `metadata` | object | ❌ | 自定义元数据 |
@@ -160,9 +168,10 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ```json
 {
-    "group": {
-        "group_id": "g-abc123.agentid.pub",
-        "name": "测试群",
+    "group": {
+        "group_id": "g-abc123.agentid.pub",
+        "group_aid": "g-abc123.agentid.pub",
+        "name": "测试群",
         "owner_aid": "alice.agentid.pub",
         "creator_aid": "alice.agentid.pub",
         "visibility": "private",
@@ -170,19 +179,26 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
         "member_count": 1,
         "message_seq": 0,
         "event_seq": 0,
-        "created_at": 1234567890
+        "created_at": 1234567890000
     },
     "aid": "alice.agentid.pub"
 }
 ```
 
-### `group.get`
+### `group.get_info`
 
-查询群组信息。需要是群成员。
+查询群组信息。默认返回公开平铺字段；需要成员信息、状态或 E2EE 字段时，通过 `required` 声明所需字段并由服务端鉴权。
 
-**参数**：`group_id` (string, 必填)
+**参数**：
 
-**响应**：`{ "group": { ... } }`
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
+| `required` | string[] | ❌ | 可选值：`member` / `state` / `e2ee` / `avatar` |
+
+**响应**：平铺对象。默认字段包含 `found`、`group_id`、`group_aid`、`name`、`visibility`、`status`、`description`、`member_count`、`created_at`。
+
+> `group.get` 和 `group.info` 已合并到 `group.get_info`；`group.get_info` 默认行为等价于原公开信息查询。
 
 ### `group.update`
 
@@ -208,21 +224,6 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 **响应**：`{ "query": "...", "items": [ ... ], "total": 3 }`
 
-### `group.get_public_info`
-
-查询公开群组信息，无需是成员。仅限 `visibility=public` 的群组。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group": { ... } }`
-
-### `group.get_stats`
-
-获取群组统计信息。需要 admin 及以上权限。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "stats": { ... } }`
 
 ### `group.suspend`
 
@@ -260,7 +261,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
+| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
 | `aid` | string | ✅ | 要添加的 AID |
 | `role` | string | ❌ | `"member"` / `"admin"`，默认 `"member"` |
 | `member_type` | string | ❌ | `"human"` / `"ai"`，默认 `"human"` |
@@ -307,7 +308,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组 ID |
+| `group_id` | string | ✅ | — | 群组标识兼容字段，值语义为 `group_aid` |
 | `page` | integer | ❌ | 1 | 页码 |
 | `size` | integer | ❌ | 50 | 每页条数 |
 | `role` | string | ❌ | — | 按角色过滤 |
@@ -350,14 +351,14 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
+| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
 | `type` | string | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密群消息时自动使用 `e2ee.group_encrypted` |
 | `payload` | object | ✅ | 消息内容 |
 | `attachments` | array | ❌ | 存储引用列表 |
 
 ##### Payload 参考约定
 
-`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
+`group.send.params.payload` 的统一业务负载格式见 [消息Payload参考约定](../sdk/消息Payload参考约定.md)。完整群消息请求仍在 `payload` 同级传入 `group_id`（兼容参数名，值使用目标态 `group_aid`）；业务类型放在 `payload.type`，不要与 `group.send.params.type` 信封/封装类型混用。
 
 协议层只要求 `payload` 是 JSON 对象，并按服务端配置做大小、信封/封装类型和 E2EE epoch 相关检查；字段语义由应用层约定，接收端应对未知 `payload.type`、未知 `kind` 和缺失展示字段做降级处理。
 
@@ -398,9 +399,9 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `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（多设备模式） |
 
 **响应**：
@@ -411,7 +412,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
     "messages": [ ... ],
     "latest_message_seq": 42,
     "has_more": false,
-    "limit": 100
+    "limit": 50
 }
 ```
 
@@ -445,7 +446,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `group_id` | string | ✅ | — | 群组 ID |
+| `group_id` | string | ✅ | — | 群组标识兼容字段，值语义为 `group_aid` |
 | `status` | string | ❌ | `"pending"` | `"pending"` / `"approved"` / `"rejected"` |
 | `page` | integer | ❌ | 1 | 页码 |
 | `size` | integer | ❌ | 50 | 每页条数 |
@@ -460,7 +461,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
+| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
 | `aid` | string | ✅ | 申请人 AID |
 | `approve` | boolean | ❌ | 批准（true）或拒绝（false），默认 true |
 | `reason` | string | ❌ | 拒绝原因 |
@@ -475,22 +476,6 @@ 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 权限，或群规则允许成员邀请。
@@ -499,7 +484,7 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
+| `group_id` | string | ✅ | 群组标识兼容字段，值语义为 `group_aid` |
 | `code` | string | ❌ | 自定义邀请码，不提供则自动生成 |
 | `max_uses` | integer | ❌ | 最大使用次数，默认 1，必须 > 0 |
 | `expires_in_seconds` | integer | ❌ | 有效期（秒），默认由配置决定（7 天） |
@@ -532,69 +517,37 @@ Group 服务是 AUN 协议的应用层扩展，提供多人群组通信能力。
 
 ---
 
-## 10.8 公告与规则
-
-### `group.get_announcement`
-
-获取群公告。需要是群成员。
-
-**参数**：`group_id` (string, 必填)
-
-**响应**：`{ "group_id": "g-abc123.agentid.pub", "announcement": { ... } }`
-
-### `group.update_announcement`
-
-更新群公告。需要 admin 及以上权限。
-
-**参数**：`group_id` (必填), `content` (string, 必填，上限默认 4000 字符), `attachments` (array, 可选)
-
-### `group.get_rules`
-
-获取群规则（可见性设置、加入模式等）。
-
-**参数**：`group_id` (string, 必填)
-
-### `group.update_rules`
-
-更新入群要求。需要 admin 及以上权限。
-
-**参数**：
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|:----:|------|
-| `group_id` | string | ✅ | 群组 ID |
-| `mode` | string | ❌ | `"open"` / `"approval"` / `"invite_only"` / `"closed"` |
-| `question` | string | ❌ | 入群问题 |
-| `auto_approve_patterns` | array | ❌ | 自动批准正则列表 |
-| `max_pending` | integer | ❌ | 最大待审批数 |
-
----
-
-## 10.9 群文件系统
-
-群文件系统统一使用 `group.fs.*`。群路径采用 `group_aid:/path` 或 `https://{group_aid}/path`，也可在 RPC 参数中同时传 `group_id` 与裸路径。群自有区包括 `announce`、`public`、`archive`；成员数据区为 `memberdata/{member_ref}`，服务端映射到成员自己的 `groupdata/{group_id}` 存储根。
-
-群自有区写入必须满足双身份规则：连接身份 `_auth.aid` 是群 owner，签名身份 `_auth.client_signature_aid` 是当前 `group_aid`。`group_aid` 私钥由群主持有，gateway 仅允许 `group.fs.*` 出现签名身份与连接身份不一致。成员数据区写入只允许对应成员本人。
-
-| 方法 | 说明 |
-|------|------|
-| `group.fs.ls` | 列出目录 |
-| `group.fs.find` | 查找节点 |
-| `group.fs.stat` | 查看节点 |
-| `group.fs.lstat` | 查看链接本身 |
-| `group.fs.df` | 查看群文件系统用量 |
-| `group.fs.create_download_ticket` | 创建下载票据，SDK 使用票据执行数据面下载 |
-| `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` | 卸载成员数据区 |
-
-逐方法 SDK 参数以 `docs/sdk/09-group-rpc-manual.md` 为准，详细设计见 `docs/aun-fs/group-fs/`。
+## 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/`。
 
 ---
 
@@ -663,19 +616,12 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | `invite_code_used` | 邀请码使用 |
 | `invite_code_revoked` | 邀请码撤销 |
 | `member_banned` | 成员被封禁 |
-| `member_unbanned` | 成员解除封禁 |
-| `suspended` | 群组暂停 |
-| `resumed` | 群组恢复 |
-| `dissolved` | 群组解散 |
-| `resource_put` | 资源添加/更新 |
-| `resource_updated` | 资源元数据更新 |
-| `resource_deleted` | 资源删除 |
-| `resource_request_created` | 资源申请创建 |
-| `resource_direct_added` | 资源直接添加（owner） |
-| `resource_request_approved` | 资源申请批准 |
-| `resource_request_rejected` | 资源申请拒绝 |
-
-### `event/group.message_created`
+| `member_unbanned` | 成员解除封禁 |
+| `suspended` | 群组暂停 |
+| `resumed` | 群组恢复 |
+| `dissolved` | 群组解散 |
+
+### `event/group.message_created`
 
 群内新消息时推送给所有在线成员。支持两种模式：
 
@@ -723,7 +669,7 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 | -32602 | Invalid params（如缺少 group_id） | 检查参数 |
 | -32004 | Permission denied（权限不足） | 提示用户，不重试 |
 | -32001 | Authentication failed | 重新认证 |
-| -33001 | Group not found | 检查 group_id |
+| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
 | -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
 | -33003 | Group suspended | 等待恢复或联系管理员 |
 | -33004 | Group member limit reached | 不重试 |
@@ -741,7 +687,7 @@ Group 服务通过 `event/group.*` 事件推送变更通知给相关 AID。
 - **消息 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` 始终可拉取全量消息。
-- **群文件系统写边界**：群自有区仅 owner 可写且必须使用 `group_aid` 签名；成员数据区仅对应成员可写。
+- **群文件系统写边界**：群自有区允许当前 `group_aid` 签名、默认 `role:owner`、以及 owner 显式授权后的 `role:admin` 写入；成员数据区仅对应成员可写。
 - **在线状态**：通过 `group.get_online_members` 查询当前在线成员列表。
 
 

package/_packed_docs/protocol/11-Storage-/345/255/220/345/215/217/350/256/256.md

@@ -249,6 +249,8 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 统一权限求值顺序（硬顺序，不可调换）：① 公开位（`set_visibility`/`is_public`，仅读）→ ② token（`issue_token` 签发，scope 到路径）→ ③ 路径前缀 ACL（`set_acl`，最近祖先匹配，权限位 `r`/`w`/`rw`/`rwx`）→ ④ 角色（群内）→ ⑤ owner → ⑥ 拒绝 `EACCES`。方法：`storage.set_acl` / `remove_acl` / `list_acl` / `set_visibility` / `check_access`（非抛错探测）/ `issue_token` / `revoke_token` / `list_tokens`。
 
+AID storage 的 ACL 面向具体 AID，主要用于写/删除授权；撤销写授权使用 `storage.remove_acl`。读权限不通过 AID ACL 直接下发，应用应使用 `storage.create_share_link` / `storage.get_by_share` 间接读取，撤销读分享使用 `storage.revoke_share_link`。`role:*` 伪主体只允许可信 group 内部门面管理；普通客户端不得直接对 `group_aid` 空间设置或删除角色 ACL，群自有区 `role:admin` 写授权统一由 `group.fs.set_acl/remove_acl` 管理。
+
 ### 11.5.5 卷与配额
 
 `storage.volume.create`（upsert 配额卷 + mount_point）/ `volume.renew`（续期）/ `volume.expire_due`（过期到期卷并标记其挂载 unavailable）。卷生命周期：active → grace（只读宽限，df 标 *）→ expired。
@@ -257,6 +259,10 @@ Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负
 
 Storage 通过 CA 的 `aid_type` 字段（`normal`/`group`）识别群命名空间。命中 `aid_type=group` 且挂载路径落在 `/memberdata/` 时，放宽 owner 校验，改为调 `group.check_membership` RPC 实时校验成员身份 + 路径约束（mount_path 第一级 == requester_aid）。详见 `10-Group-子协议.md` 与 `docs/aun-fs/topics/group-space.md`。
 
+成员个人 Storage 内的 `group_data` 是系统级真实存储根，Storage 服务端必须对普通 `storage.*` / `storage.fs.*` 请求隐藏并拒绝直接写入、删除、重命名或挂载；`aun fs` / Storage VFS 只呈现服务端返回结果，不新增保护逻辑。`group_data` 只能由可信 `group.fs.*` 内部上下文间接访问，占用的空间仍必须计入真实 owner AID 的 Storage 配额。完整规则见 [16-系统目录保护方案.md](16-系统目录保护方案.md)。
+
+POSIX VFS 写侧包含 `storage.fs.touch`：它可创建 0 字节文件或刷新已有文件、目录、软链的修改时间，支持 `parents`、`no_create`、`mtime` 和 `follow_symlinks`。这是普通 AID storage 的 VFS 能力；群自有区仍应通过 `group.fs.*` 面进入。
+
 ### 11.5.7 collab 协作编排
 
 协作层 `collab.*`（版本化文档 + 目录快照）的编排已并入 Storage 服务进程，handler 与 `storage.*` 并列注册，以调用者身份直调 storage 原语，授权下沉 storage ACL，无特权通道。方法清单与语义见 SDK 手册 `docs/sdk/09-collab-rpc-manual.md`。

package/_packed_docs/protocol/15-/347/246/273/347/272/277/346/216/250/351/200/201/351/200/232/347/237/245/345/215/217/350/256/256.md

@@ -290,7 +290,7 @@ Gateway 向 push_notify_aid 下发的事件通知：
           "unread_count": 3,
           "senders": ["alice.example.com", "charlie.example.com"],
           "latest_ts": 1716100005,
-          "group_ids": ["group-uuid-1"]
+          "group_ids": ["g-abc123.agentid.pub"]
         }
       }
     ]