@agentunion/fastaun-browser 0.5.2 → 0.5.4

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`），并提供通用文档型方法（`getSettingWithIndex`/`updateSettingWithIndex`，Python 为 `get_setting_with_index`/`update_setting_with_index`，Go 为 `GetSettingWithIndex`/`UpdateSettingWithIndex`）。读取方法优先返回 SDK 本地缓存，本地没有对应值时才调用 `get_settings` 初始化；即使观察到远端 etag 不一致也不会自动 pull 远端。indexed 写入方法内部调用 `updateGroupIndex` 生成签名 `group.index` 并通过 `set_settings` CAS 提交。
 
 ### 群文件系统
 
@@ -493,7 +493,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.set_role
 
-设置成员角色。需要 **owner** 权限。不能改变 owner 角色。该 RPC 只改变 membership 中的角色事实，不授予或撤销群自有区写 ACL；`role:admin` 是否可写群自有区由 `group.fs.set_acl` / `group.fs.remove_acl` 显式控制。
+设置成员角色。`owner` 可将普通成员设为 `admin`，也可将 `admin` 设回 `member`；`admin` 不能修改其它成员角色，只能将自己的角色降为 `member`。不能通过 `group.set_role` 改变 `owner` 角色；群主只在建群或 `group.transfer_owner` 中变更。该 RPC 改变 membership 中的角色事实；`owner/admin` 默认拥有群自有区写权限，`member` 默认没有写权限。成员级群协作目录应通过 `group.fs.set_acl` 显式授予 `role:member` 的 `rw` 权限。
 
 **参数**：
 
@@ -951,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` 更新群设置。
 
@@ -960,10 +962,17 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `settings` | object | 是 | 要写入的设置键值 |
-| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
-| `settings["rules.content"]` | string | 否 | 群规则正文 |
-| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `settings` | object | 是 | 要写入的设置键值 |
+| `expected_index_etag` | string | 写 `group.index` 时必填 | CAS 期望旧 etag；空字符串表示只允许创建首个 `group.index` |
+| `settings["dispatch_mode"]` | string | 否 | `"broadcast"` / `"mention"`，默认 `"broadcast"` |
+| `settings["rules.content"]` | string | 否 | 群规则正文 |
+| `settings["rules.attachments"]` | array | 否 | 群规则附件稳定引用 |
+| `settings["announcement.content"]` | string | 否 | 群公告正文 |
+| `settings["announcement.attachments"]` | array | 否 | 群公告附件稳定引用 |
+| `settings["join.attachments"]` | array | 否 | 入群要求附件稳定引用 |
+| `settings["{keyName}.content"]` | string | 否 | 通用文档型 indexed setting 正文；`keyName` 需满足受控命名规则 |
+| `settings["{keyName}.attachments"]` | array | 否 | 通用文档型 indexed setting 附件稳定引用 |
+| `settings["group.index"]` | object | 更新 indexed settings 时必填 | 签名 group index，当前结构至少包含 `body` |
 
 **预定义群级参数**：
 
@@ -977,13 +986,34 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 | `announcement.content` | string | `""` | 群公告正文 |
 | `announcement.attachments` | array | `[]` | 群公告附件 |
 | `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.question` | string | `""` | 入群问题 |
+| `join.auto_approve_patterns` | array | `[]` | 自动批准 AID 匹配规则 |
+| `join.max_pending` | integer | `100` | 最大待审批入群申请数 |
+| `join.attachments` | array | `[]` | 入群材料附件稳定引用 |
+| `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` / `join.attachments` | 入群要求配置与附件稳定引用 |
+| `{keyName}.content` / `{keyName}.attachments` | 通用文档型设置正文与附件稳定引用 |
+
+写入规则：
+
+- 只更新非 indexed settings 时，继续直接调用 `set_settings`，不需要 `group.index`。
+- 更新任意 indexed setting 时，必须在同一次 `settings` 中携带签名 `group.index`。
+- 服务端只接受受控动态文档 key：`{keyName}.content` / `{keyName}.attachments`，其中 `keyName` 匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀。调用方不能用该机制写任意 settings key。
+- 写入 `group.index` 时必须传 `expected_index_etag`。
+- 服务端在同一事务内比较当前 `group.index` etag、写 indexed settings、写 `group.index`。
+- CAS 失败时错误消息包含 `group.index etag conflict`；SDK 的 `updateGroupIndex` 会重新读取当前 index、重建签名并按 `max_attempts` 重试。
+- `rules.attachments`、`announcement.attachments`、`join.attachments` 和 `{keyName}.attachments` 只保存附件引用；附件实体应先写入群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。群自有区默认允许 `owner/admin` 写入，`member` 默认不可写；`.group/` 是系统控制目录，不允许授予 `role:member` 写权限。
+
+```python
+await client.call("group.set_settings", {
     "group_id": "g-abc123.agentid.pub",
     "settings": {"dispatch_mode": "mention"},
 })
@@ -992,33 +1022,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 | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `keys` | array | 否 | 只读取指定 key，如 `["dispatch_mode", "rules.content"]` |
+| `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。
 
 ## 消息
 
@@ -1312,8 +1395,9 @@ result = await client.call("group.thought.get", {
 
 权限与签名约束：
 
-- 群自有区是除 `memberdata` 等系统保留路径外的整个 `group_aid` namespace。`group_aid` 当前证书签名可写；`role:owner` 默认可写；`role:admin` 需要 owner 通过 `group.fs.set_acl` 显式授权后才可写。
-- `group.fs.set_acl` / `group.fs.remove_acl` / `group.fs.get_acl` / `group.fs.list_acl` 只能由当前 group owner 调用，且当前只允许管理或查询 `grantee_aid="role:admin"` 的群自有区角色 ACL；成员升降级、退群、踢出不会联动授权或撤销。
+- 群自有区是除 `memberdata` 等系统保留路径外的整个 `group_aid` namespace。`group_aid` 当前证书签名可写；成员角色中 `owner/admin` 默认可写，`member` 默认不可写。`group_aid:/.group/` 是系统控制目录，用于群公告、群规则、入群要求附件，默认允许 `owner/admin` 写入。
+- 老群如果缺少 `.group/` 默认 ACL，group 服务会在该群首次被 RPC 访问时 best-effort 触发 namespace/ACL lazy repair；只有本次 baseline ACL 全部同步成功才记录本进程已检查，失败会在后续访问继续重试。
+- `group.fs.set_acl` / `group.fs.remove_acl` / `group.fs.get_acl` / `group.fs.list_acl` 只能由当前 group `owner/admin` 调用。当前支持 `grantee_aid="role:admin"` 与 `grantee_aid="role:member"`；`role:member` 只能授予具体业务目录的 `rw` 权限，不能授予根目录或 `.group/`，也不能获得删除、移动、重命名权限。成员升降级、退群、踢出不会联动授权或撤销目录 ACL。
 - `memberdata/{member_ref}` 写入默认只允许该成员本人；SDK 只传 group path，不拼接真实 storage 路径。
 - 上传控制面会透传 `parents` 到 storage：默认 `parents=true` 时可递归创建父目录，显式 `parents=false` 时父目录必须已存在。
 - JavaScript 浏览器版 `cp(string, group)` 默认把 string 当文本内容上传；Node 本地路径需显式传 `sourceType: "path"`、`localPath: true` 或使用 `local:` 前缀。Python、TypeScript 和 Go 默认把 string 当本地路径。
@@ -1344,21 +1428,21 @@ result = await client.call("group.thought.get", {
 
 ### group.fs.set_acl
 
-授予群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
-
-参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`；`perms` 默认 `rwx`，必须包含写权限。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`。
+授予群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；底层由 group 服务以内部门面写入 `storage.set_acl`。
+
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 可为 `role:admin` 或 `role:member`。`role:admin` 默认 `rwx`；`role:member` 只能为 `rw`，且只能授到具体业务目录，不能授到根目录或 `.group/`。`path` 可传 `group_aid:/archive` 等 group path。服务端写入 storage 内部权限位时会把 POSIX 删除位 `x` 映射为内部 `d`，对外响应仍显示 `rwx`；不授删除、移动、重命名权限时使用 `rw`。
 
 ### group.fs.remove_acl
 
-撤销群自有区角色 ACL。需要当前 group owner 身份签名调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
-
-参数：`path` 必填，指向群自有区路径；`grantee_aid` 只能为 `role:admin`。撤销后，当前 admin 角色成员不再因该路径的 `role:admin` ACL 获得写权限。
+撤销群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；底层由 group 服务以内部门面写入 `storage.remove_acl`。
+
+参数：`path` 必填，指向群自有区路径；`grantee_aid` 可为 `role:admin` 或 `role:member`。撤销 `role:member` 后，member 不再因该目录 ACL 获得创建/写入权限。
 
 ### group.fs.get_acl
 
-查询群自有区角色 ACL。需要当前 group owner 身份签名调用；普通 admin/member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
-
-响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此 owner 授权 `role:admin:rwx` 后查询也返回 `rwx`。
+查询群自有区角色 ACL。需要当前 group `owner/admin` 身份调用；普通 member 不能查询。参数：`path` 必填，指向群自有区路径；可传裸路径 + `group_id`，也可传完整 `group_aid:/...`。
+
+响应包含 `group_id`、`group_aid`、`path`、`area`、`storage` 和 `acls`。`acls[].perms` 使用 POSIX 视图，删除权限显示为 `x`，因此授权 `role:admin:rwx` 后查询也返回 `rwx`；`role:member` 只应返回 `rw`。
 
 ### group.fs.list_acl
 

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -11,7 +11,7 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `AUNClient`：认证、连接、状态机、事件和 RPC。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名，详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。群组标识以 `group_aid` 为主，`group_id` 只作为兼容参数名；`group.index` 的签名索引、`_meta.group_indexes` 观察和 `expected_index_etag` CAS 详见 `09-group-rpc-manual.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
 
 Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
 Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
@@ -31,7 +31,8 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
 - RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
 - Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- Group RPC：`group_aid` / `group_id` 兼容、`group.index` 签名索引、`_meta.group_indexes`、`check/get/updateGroupIndex`、`expected_index_etag` CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
 - 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
@@ -47,7 +48,7 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 |------|------|------|
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
 | 02 | [WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket |
-| 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
+| 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE、Group Index 观察模型 |
 | 04 | [连接与认证](04-连接与认证.md) | AIDStore、连接、网关发现、事件、agent.md 自动观察 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、agent.md 版本提示、recipient wrap |
 | 06 | [API手册](06-API手册.md) | AIDStore / AID / AUNClient / agent.md / ServiceProxyClient / 事件 / RPC |
@@ -70,7 +71,8 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 查方法签名 | [06-API手册](06-API手册.md) |
 | 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
 | 查群组标识 `group_aid` / `group_id` 兼容规范 | [09-group-rpc-manual.md](09-group-rpc-manual.md) |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 group.index 签名索引、版本观察、不同步判断、CAS 更新和 facade | [03-核心概念.md](03-核心概念.md)、[06-API手册.md](06-API手册.md)、[09-group-rpc-manual.md](09-group-rpc-manual.md)、[08-最佳实践.md](08-最佳实践.md) |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
 | 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
 | 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
 | 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |

package/_packed_docs/sdk/INDEX.md

@@ -10,16 +10,16 @@
 |------|------|
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE |
+| [03-核心概念](03-核心概念.md) | AID · AIDStore · AUNClient · 九态状态机 · E2EE · Group Index 观察模型 |
 | [04-连接与认证](04-连接与认证.md) | 注册加载 · 认证连接 · 网关发现 · 事件 · agent.md 自动观察 |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE V2 消息 · ProtectedHeaders · agent.md 版本提示 · recipient wrap |
 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2 P2P/GROUP 明文与加密主链路 |
 | [06-API手册](06-API手册.md) | AIDStore · AID · AUNClient · 事件 · agent.md · E2EE 高级 API · RPC 索引 |
 | [07-错误处理](07-错误处理.md) | Result · 错误类层级 · 错误码 · 重试 |
-| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · 测试数据保护 |
+| [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · group.index 更新流程 · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
-| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group_aid` / `group_id` 兼容规范、`group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
+| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group_aid` / `group_id` 兼容规范、`group.index` 签名索引与 CAS、`group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
 | [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
 | [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
 | [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区角色 ACL、`parents` 和 JS string 语义 |
@@ -64,7 +64,7 @@
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
 - Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
-- Group RPC、`group_aid` / `group_id` 兼容规范、群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
+- Group RPC、`group_aid` / `group_id` 兼容规范、`group.index` 签名索引、`_meta.group_indexes` 观察、`expected_index_etag` CAS、群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
 - 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
 - Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
 - Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / `storage.fs.touch` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
@@ -93,9 +93,9 @@
 
 说明 Gateway WebSocket 握手、JSON-RPC 请求/响应/通知格式，以及裸 WebSocket 客户端如何借助 SDK 完成 token 获取。
 
-### 03-核心概念
-
-解释 AID 身份、三主体职责、device_id / slot_id 隔离键、九态状态机、认证挑战-响应、默认 E2EE 行为和 RPC/事件模型。
+### 03-核心概念
+
+解释 AID 身份、三主体职责、device_id / slot_id 隔离键、九态状态机、认证挑战-响应、默认 E2EE 行为、RPC/事件模型，以及 `group.index` 的 `_meta.group_indexes` 观察、不同步标记和应用层 pull/push 边界。
 
 ### 04-连接与认证
 
@@ -105,21 +105,21 @@
 
 覆盖默认加密发送、接收自动解密、E2EE V2 多设备 wrap、ProtectedHeaders、agent.md 版本提示与 E2EE 安全边界、`sender_signature` / AAD / recipient proof、群 E2EE 和高级存储扩展边界。
 
-### 06-API手册
-
-列出 AIDStore、AID、AUNClient、事件、agent.md、ServiceProxyClient、E2EE 高级 API 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
-
-### 07-错误处理
-
-说明 Result 字典、AUNError 异常层级、错误码映射、重试策略和常见错误场景。
+### 06-API手册
+
+列出 AIDStore、AID、AUNClient、事件、agent.md、ServiceProxyClient、E2EE 高级 API、Group Index facade 和 RPC 手册索引，包含 Python / TS / JS / Go 的主要命名差异。
 
-### 08-最佳实践
+### 07-错误处理
+
+说明 Result 字典、AUNError 异常层级、错误码映射、重试策略、`group.index etag conflict` CAS 冲突处理和常见错误场景。
 
-给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control 和测试数据保护建议。
+### 08-最佳实践
+
+给出幂等加载身份、连接、关闭、多 AID 管理、protected_headers、Flow Control、Group Index 更新流程和测试数据保护建议。
 
 ### 09-*-rpc-manual
 
-各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
+各业务服务的 RPC 参数、响应和错误语义。Group RPC 覆盖 `group.index` 签名索引、`expected_index_etag` CAS 和 `_meta.group_indexes` 观察。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
 
 ### AUN Storage架构设计