@agentunion/fastaun-browser 0.5.2 → 0.5.3

package/_packed_docs/protocol/index.md

@@ -19,7 +19,7 @@
 | E2EE | [08-AUN-E2EE.md](08-AUN-E2EE.md) | Legacy P2P E2EE 信封说明；当前默认主路径见 SDK V2 多设备 wrap 文档 |
 | E2EE-Group | [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE V2：消息级密钥、逐设备密钥包裹、成员状态签名验证 |
 | 09 | [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、升级安全、验签时序 |
-| 10 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、邀请码、资源共享、在线状态 |
+| 10 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、`group.index` 签名索引、邀请码、资源共享、在线状态 |
 | 11 | [11-Storage-子协议.md](11-Storage-子协议.md) | `storage.*` 对象存储、大文件上传下载、预签名 URL |
 | 12 | [12-Stream-子协议.md](12-Stream-子协议.md) | `stream.*` 实时流式传输、WebSocket 推流、HTTP SSE 拉流、跨域拉流 |
 | 15 | [15-离线推送通知协议.md](15-离线推送通知协议.md) | `push.*` 离线推送、push_notify_aid 代理、事件通知 + 背压 ack、白名单与去重 |
@@ -53,8 +53,9 @@
 | 任务协作（task.*） | 06 §6.5 |
 | 跨域消息路由 | 06 §6.7 |
 | E2EE 端到端加密 | AUN-E2EE, 06 §6.6 |
-| 群组管理（group.*） | 10 |
-| 群消息收发（group.send/pull） | 10 §10.5 |
+| 群组管理（group.*） | 10 |
+| 群索引（group.index / _meta.group_indexes / CAS） | 10 §10.13 |
+| 群消息收发（group.send/pull） | 10 §10.6 |
 | 群成员权限（owner/admin/member） | 10 §10.2 |
 | 邀请码（group.create_invite_code） | 10 §10.7 |
 | 群文件系统（group.fs.*） | 10 §10.9 |
@@ -113,8 +114,8 @@ Gateway 模式定位与职责、Gateway 发现机制、连接时序（auth.* →
 ### 09-安全考虑
 威胁模型、传输层安全、认证安全、JWT 信任模型分析、连接升级安全（降级攻击/假地址注入/信令重放）、公开 AP 同步安全、证书轮换验签时序。
 
-### 10-Group-子协议
-`group.*` 命名空间完整协议规范。群组生命周期（create/suspend/resume/dissolve）、成员管理（add/kick/set_role/transfer_owner）、群消息（send/pull/ack、`payload.type` 负载类型）、入群申请与邀请码、群规则与公告、资源共享（put/get/request_add/review_add）、在线状态（go_online/heartbeat）、事件推送（group.created/changed/message_created）、错误码（-33001~-33009）。Group Service 作为独立 AID 持有者运行。
+### 10-Group-子协议
+`group.*` 命名空间完整协议规范。群组生命周期（create/suspend/resume/dissolve）、成员管理（add/kick/set_role/transfer_owner）、群消息（send/pull/ack、`payload.type` 负载类型）、`group.index` 签名索引与 `expected_index_etag` CAS、`_meta.group_indexes` 版本提示、入群申请与邀请码、群规则与公告、资源共享、在线状态、事件推送（group.created/changed/message_created）、错误码（-33001~-33009）。Group Service 作为独立 AID 持有者运行，Gateway/Message 不生成或改写 group index。
 
 ### 11-Storage-子协议
 `storage.*` 命名空间完整协议规范。控制面与数据面分离（小对象内联 RPC，大对象预签名 URL HTTP 传输）、per-AID 隔离、对象键路径化、版本化 CAS 并发控制。方法：put_object / get_object / delete_object / list_objects / create_upload_session / create_download_ticket。

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -165,6 +165,25 @@ client.on("state_change", lambda e: print(e["state"]))
 client.on("message.received", lambda e: print(e["payload"]))
 ```
 
-RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-storage-rpc-manual.md` 等专项手册。
+RPC 方法参数见 `09-message-rpc-manual.md`、`09-group-rpc-manual.md`、`09-storage-rpc-manual.md` 等专项手册。
+
+---
+
+## Group Index 观察模型
+
+`group.index` 是群公告、群规则、入群要求和附件稳定引用的签名索引。它由 owner/admin 侧 SDK 生成并签名，Group 服务只校验、CAS 保存和在响应 `_meta.group_indexes` 中注入版本提示。
+
+关键语义：
+
+- `_meta.group_indexes` 只包含 `etag`、`last_modified`、`schema`，不包含 index 正文。
+- SDK 观察到远端 `etag` 变化后只记录观察到的远端版本；etag 不一致只表示本地与远端不同步，不表示远端一定更新，也不表示本地一定应被覆盖。
+- `getAnnouncement` / `getRules` / `getJoinRequirements` 只返回 SDK 本地缓存；本地没有对应值时才读取相应 settings 初始化缓存，不会因为 etag 不一致自动 pull 远端。
+- 应用层调用 `checkGroupIndex` 判断是否不同步；如选择远端为准，再调用 `getGroupIndex` 从服务端摘取当前 index 并同步本地缓存。
+- owner/admin 修改 indexed settings 时调用 `updateGroupIndex`；SDK 会先读取当前 index，再基于 `expected_index_etag` CAS push 新签名版本。
+- Gateway/Message 不生成、不校验、不更新 `group.index`，最多转发或合并 `_meta`。
+- `getGroupIndex` pull 验签通过后必须持久化本地视图：Python / TypeScript(Node) / Go 写入 `{aun_path}/AIDs/{local_aid}/groups/{group_aid}/index.jsonl` 和同目录 `group-index-cache.json`；浏览器 JavaScript 写入 IndexedDB `group_index_cache`，字段包含 `index_jsonl`、`local_etag`、`remote_meta`、`settings`、`entry_etags`。
+- 本地持久化目录按 `local_aid + group_aid` 隔离，不是 `{aun_path}/AIDs/{group_aid}/`；`index.jsonl` 保存签名 `group.index.body` 原文，SDK cache envelope 不再使用旧单文件 `group-index.json`。
+
+这个模型与 `agent.md` 的版本观察机制对齐：先观察变化，再由应用层决定以本地还是远端为准，显式 pull、merge 或 push。
 
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -116,11 +116,11 @@ Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览
 | `cached` | bool | 是否命中 TTL 窗口内的本地检查记录 |
 | `verify_status` / `verify_error` | str | 最近一次下载验签状态 |
 
-agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
-
-`remote_etag` / `last_modified` 除了来自 `check_agent_md()` 的 HEAD，也会由连接后的内部观察器更新：SDK 会读取 RPC response / event push `_meta.agent_md_etags` 的 `requester`、`peer`、`group` 及兼容别名，并读取 V2 envelope 的 `agent_md.sender` / `agent_md.group`。`group` 记录使用群自身 `group_aid` / `group_id` 作为 AID key。
-
-> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
+agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
+
+`remote_etag` / `last_modified` 除了来自 `check_agent_md()` 的 HEAD，也会由连接后的内部观察器更新：SDK 会读取 RPC response / event push `_meta.agent_md_etags` 的 `requester`、`peer`、`group` 及兼容别名，并读取 V2 envelope 的 `agent_md.sender` / `agent_md.group`。`group` 记录使用群自身 `group_aid` / `group_id` 作为 AID key。
+
+> **v0.4.2 变更**：`discoveryPort` 配置项已移除，Gateway 地址完全由 SDK 根据 AID issuer 自动发现，无需手动指定端口。
 
 ---
 
@@ -262,7 +262,7 @@ await client.call("meta.trust_roots", {})
 ```python
 await client.notify("notification/client.activity", {"state": "idle"})
 await client.notify("event/app.typing", {"thread_id": "t1"}, to="bob.agentid.pub", ttl_ms=5000)
-await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc123.agentid.pub")
+await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc123.agentid.pub")
 ```
 
 路由选项：
@@ -270,7 +270,7 @@ await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc12
 | 选项 | 说明 |
 |------|------|
 | `to` / `To` | 目标 AID；可同域或跨域 |
-| `group_id` / `groupId` / `GroupID` | 目标群；兼容参数名，值使用目标态 `group_aid`，与 `to` 互斥 |
+| `group_id` / `groupId` / `GroupID` | 目标群；兼容参数名，值使用目标态 `group_aid`，与 `to` 互斥 |
 | `device_id` / `deviceId` / `DeviceID` | 限定目标 AID 的在线设备；必须配合 `to` |
 | `slot_id` / `slotId` / `SlotID` | 限定目标设备的在线 slot；必须配合 `device_id` |
 | `ttl_ms` / `ttlMs` / `TTLMS` | `0..60000`，只控制在线投递过期，不表示离线缓存 |
@@ -309,11 +309,11 @@ headers = client.get_protected_headers()
 
 说明：
 
-- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
-- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
-- SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
-- `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
+- agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
+- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
+- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+- SDK 会自动从 Gateway `_meta.agent_md_etags` 和信封 `agent_md` 观察远端版本；`requester`、`peer`、`group` 是标准角色键，`receiver`、`target`、`to`、`sender`、`from` 是兼容别名。
+- `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容；agent.md 仍是 Markdown 媒体类型上的结构化约定。
 
 ---
 
@@ -347,13 +347,278 @@ headers = client.get_protected_headers()
 - `getInfo()` — 查询群组信息（扁平化格式，提升常用字段到顶层），**推荐外部使用**
 - `info()` — 查询群组详细信息（带权限控制，非成员只能看公开群，成员能看 seq/epoch 等运行时状态）
 
-**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法，基于 `group.set_settings` / `group.get_settings` 实现：
+**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法：
 
 - `getAnnouncement()` / `updateAnnouncement()` — 群公告
 - `getRules()` / `updateRules()` — 群规则
 - `getJoinRequirements()` / `updateJoinRequirements()` — 入群要求
 
-便利方法返回旧格式（嵌套对象 `{announcement: {content, attachments}}`），屏蔽 `settings` 数组的繁琐。新代码建议直接使用 `group.set_settings` / `group.get_settings` 以获得更灵活的批量操作能力（一次调用可设置多个键）。
+读取方法优先返回 SDK 本地缓存；本地没有对应值时才读取相应 settings 做初始化。便利读取从服务端拿到 canonical `group_aid` 后，会同时以 canonical `group_aid` 和本次入参 `group_id` 写入 settings cache，避免 legacy/base `group_id` 下一次读取直接 cache miss。即使 `checkGroupIndex` 观察到远端 etag 与本地 etag 不一致，`getAnnouncement()` / `getRules()` / `getJoinRequirements()` 也不会自动拉取远端版本覆盖本地缓存。`updateAnnouncement()` / `updateRules()` / `updateJoinRequirements()` 属于 indexed 写入，内部会调用 `updateGroupIndex` 生成签名 `group.index` 并带 `expected_index_etag` CAS 提交。
+
+**Group Index 高级同步方法**：`group.index` 是 SDK 内部签名 manifest，用于记录群公告、群规则、入群要求及附件稳定引用的版本。SDK 观察 `_meta.group_indexes` 后只记录远端 etag；etag 不一致只表示本地与观察到的远端版本不同，可能是远端更新，也可能是本地有未提交修改。应用层需要显式选择 pull 远端或 push 本地。
+
+| 语义 | Python | TS/JS | Go | 说明 |
+|------|--------|-------|----|------|
+| 检查 index 是否不同步 | `client.group.check_group_index({...})` | `client.group.checkGroupIndex({...})` | `client.Group().CheckGroupIndex(ctx, params)` | 本地判断，不发网络请求；返回 `local_found/remote_found/local_etag/remote_etag/in_sync/needs_update/last_modified/status/cached` |
+| 显式 pull 远端 index | `client.group.get_group_index({...})` | `client.group.getGroupIndex({...})` | `client.Group().GetGroupIndex(ctx, params)` | 调用 `group.get_settings(keys=["group.index"])` 摘取 manifest，并按 entry etag 只拉取变化的 db settings 写入本地缓存 |
+| 显式 push 本地 indexed settings + index | `client.group.update_group_index({...})` | `client.group.updateGroupIndex({...})` | `client.Group().UpdateGroupIndex(ctx, params)` | 先读取当前 index 得到 `expected_index_etag`，在远端基线上合并本地变更，生成签名 `group.index` 后 CAS push |
+
+`getGroupIndex` pull 验签成功后会持久化本地视图。Python / TypeScript(Node) / Go 使用 `{aun_path}/AIDs/{local_aid}/groups/{group_aid}/index.jsonl` 保存签名 `group.index.body` 原文，并用同目录 `group-index-cache.json` 保存 `local_etag`、`remote_meta`、`settings`、`entry_etags` 等 cache envelope。浏览器 JavaScript 使用 IndexedDB `group_index_cache` store 的等价记录，按 `local_aid + group_aid` 隔离。普通便利读取可额外写入本次请求 `group_id` 的 settings cache alias；签名正文和 `getGroupIndex` 视图仍以 canonical `group_aid` 为准。不要使用 `{aun_path}/AIDs/{group_aid}/`，也不要使用旧单文件 `group-index.json`。
+
+#### checkGroupIndex — 检查 index 同步状态
+
+**本地判断**，不发网络请求。基于 SDK 观察到的 `_meta.group_indexes` 远端 etag 与本地缓存 etag 对比，返回同步状态。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组标识（支持 `group_aid` 格式） |
+
+**返回值**：
+
+```python
+{
+  "group_id": "g-team.agentid.pub",
+  "group_aid": "g-team.agentid.pub",
+  "local_found": true,          # 本地是否有缓存 etag
+  "remote_found": true,         # 是否观察到远端 _meta.group_indexes
+  "local_etag": "\"sha256:...\"",  # 本地缓存 etag（带引号）
+  "remote_etag": "\"sha256:...\"", # 远端 etag（带引号）
+  "in_sync": false,             # local_etag == remote_etag
+  "needs_update": true,         # remote_found && !in_sync（建议 pull）
+  "last_modified": 1780000000000, # 远端 last_modified（若有）
+  "schema": "aun.group.index.v1", # 远端 schema（若有）
+  "status": "stale"             # "fresh" / "stale" / "unknown"
+}
+```
+
+**使用场景**：
+
+- 群列表展示同步状态图标（如"本地有未同步修改"或"远端有更新"）
+- 判断是否需要调用 `getGroupIndex` pull 远端
+
+**示例**：
+
+```python
+# Python
+status = await client.group.check_group_index(group_id="g-team.agentid.pub")
+if status["needs_update"]:
+    print("远端有更新，建议 pull")
+```
+
+```typescript
+// TypeScript/JavaScript
+const status = await client.group.checkGroupIndex({ group_id: 'g-team.agentid.pub' });
+if (status.needs_update) {
+  console.log('远端有更新，建议 pull');
+}
+```
+
+```go
+// Go
+status, err := client.Group().CheckGroupIndex(ctx, map[string]any{
+    "group_id": "g-team.agentid.pub",
+})
+if status["needs_update"].(bool) {
+    fmt.Println("远端有更新，建议 pull")
+}
+```
+
+---
+
+#### getGroupIndex — 拉取远端 index 并更新本地缓存
+
+调用 `group.get_settings(keys=["group.index"])` 摘取远端签名 manifest，验签后按 entry etag 只拉取变化的 indexed settings，更新本地缓存。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组标识（支持 `group_aid` 格式） |
+
+**返回值**：
+
+```python
+{
+  "group_id": "g-team.agentid.pub",
+  "group_aid": "g-team.agentid.pub",
+  "group_index": {              # 完整的 group.index 值
+    "body": "...",              # 签名 JSONL 原文
+    "meta": {...},              # 解析出的 meta 行
+    "entries": [...]            # 解析出的 entries 行数组
+  },
+  "meta": {                     # 从 meta 行提取的关键字段
+    "etag": "\"sha256:...\"",
+    "last_modified": 1780000000000,
+    "schema": "aun.group.index.v1"
+  },
+  "entries": [...],             # 同 group_index.entries
+  "settings": {                 # 水合后的 indexed settings 值
+    "rules.content": "...",
+    "announcement.content": "...",
+    ...
+  }
+}
+```
+
+**行为**：
+
+1. 调用 `group.get_settings(keys=["group.index"])` 获取远端 manifest
+2. 解析 JSONL，验证 `signed_by` / `body_hash` / `etag` / 签名（当前仅支持 **ECDSA-P256-SHA256**）
+3. 按 entry etag 对比本地缓存，只拉取变化的 settings（如 `rules.content`、`announcement.content` 等）
+4. 持久化 `index.jsonl` 和 `group-index-cache.json`（或 IndexedDB）
+5. 调用 `client.mark_group_index_fresh(group_aid, etag)` 标记本地与远端同步
+
+**错误处理**：
+
+- **签名验证失败**：抛异常，不更新本地缓存
+- **不支持的 `sig_alg`**：当前四语言 SDK 仅支持 `ECDSA-P256-SHA256`，其他算法（Ed25519/RSA）会被拒绝
+- **网络错误**：透传底层 RPC 错误
+
+**使用场景**：
+
+- 群成员首次进群后拉取群公告、群规则
+- `checkGroupIndex` 发现远端有更新时主动 pull
+- 冲突解决：放弃本地修改，以远端为准
+
+**示例**：
+
+```python
+# Python
+result = await client.group.get_group_index(group_id="g-team.agentid.pub")
+print(f"拉取成功，etag: {result['meta']['etag']}")
+print(f"群公告: {result['settings'].get('announcement.content')}")
+```
+
+```typescript
+// TypeScript/JavaScript
+const result = await client.group.getGroupIndex({ group_id: 'g-team.agentid.pub' });
+console.log(`拉取成功，etag: ${result.meta.etag}`);
+console.log(`群公告: ${result.settings['announcement.content']}`);
+```
+
+```go
+// Go
+result, err := client.Group().GetGroupIndex(ctx, map[string]any{
+    "group_id": "g-team.agentid.pub",
+})
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("拉取成功，etag: %s\n", result["meta"].(map[string]any)["etag"])
+```
+
+---
+
+#### updateGroupIndex — 推送本地 indexed settings 修改
+
+在远端基线上合并本地 indexed settings 修改，生成签名 `group.index` 后通过 CAS（Compare-And-Swap）机制提交。支持自动重试 etag 冲突。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `group_id` | string | ✅ | 群组标识（支持 `group_aid` 格式） |
+| `settings` | object | ✅ | 要更新的 indexed settings（key-value 对象） |
+| `signer` | AID | ❌ | 签名者身份（默认 `client.current_aid`） |
+| `last_modified` | int | ❌ | 时间戳毫秒（默认 `Date.now()` / `time.time()*1000`） |
+| `max_attempts` | int | ❌ | CAS 冲突最大重试次数（默认 2） |
+
+**支持的 indexed settings keys**：
+
+- `rules.content` / `rules.attachments` — 群规则及附件
+- `announcement.content` / `announcement.attachments` — 群公告及附件
+- `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` — 入群要求
+
+**返回值**：
+
+```python
+{
+  "group_id": "g-team.agentid.pub",
+  "group_aid": "g-team.agentid.pub",
+  "updated_keys": ["announcement.content", "group.index"],
+  "_meta": {
+    "group_indexes": {
+      "g-team.agentid.pub": {
+        "etag": "\"sha256:...\"",     # 推送成功后的新 etag
+        "last_modified": 1780000000000,
+        "schema": "aun.group.index.v1"
+      }
+    }
+  }
+}
+```
+
+**行为**：
+
+1. 调用 `group.get_settings(keys=["group.index"])` 获取当前远端 etag（作为 CAS 基线）
+2. 解析远端 `group.index` 的 entries，保留不在 `settings` 中的条目
+3. 为 `settings` 中每个 key 计算新的 entry（包含 `etag: "sha256:<value的sha256>"`）
+4. 合并远端保留条目和新 entries，生成新的 canonical JSONL
+5. 用 `signer` 签名生成完整的 `group.index`（包含 meta 行的 `signature` 字段）
+6. 调用 `group.set_settings(settings={...修改的key..., "group.index": {...}}, expected_index_etag=<远端etag>)`
+7. **CAS 冲突自动重试**：若返回 "etag conflict" 错误，回到步骤 1 重新拉取基线（最多 `max_attempts` 次）
+8. 推送成功后调用 `client.mark_group_index_fresh()` 和 `client.cache_group_index_settings()` 更新本地缓存
+
+**错误处理**：
+
+- **CAS 冲突重试耗尽**：抛出最后一次的 "etag conflict" 异常
+- **非 CAS 错误**：立即抛出（如权限不足、签名失败）
+- **`signer` 与 RPC `actor` 不一致**：服务端会拒绝（`signed_by` 必须等于 `actor_aid`）
+
+**使用场景**：
+
+- 群主/管理员修改群公告、群规则后推送
+- 冲突解决：本地修改优先，覆盖远端（若冲突次数超限需人工介入）
+
+**示例**：
+
+```python
+# Python - 更新群公告
+result = await client.group.update_group_index(
+    group_id="g-team.agentid.pub",
+    settings={
+        "announcement.content": "新公告内容",
+        "announcement.attachments": []
+    }
+)
+print(f"推送成功，新 etag: {result['_meta']['group_indexes']['g-team.agentid.pub']['etag']}")
+```
+
+```typescript
+// TypeScript/JavaScript - 更新群规则
+const result = await client.group.updateGroupIndex({
+  group_id: 'g-team.agentid.pub',
+  settings: {
+    'rules.content': '1. 禁止广告\n2. 尊重他人',
+    'rules.attachments': []
+  }
+});
+console.log(`推送成功，新 etag: ${result._meta.group_indexes['g-team.agentid.pub'].etag}`);
+```
+
+```go
+// Go - 更新入群要求
+result, err := client.Group().UpdateGroupIndex(ctx, map[string]any{
+    "group_id": "g-team.agentid.pub",
+    "settings": map[string]any{
+        "join.mode": "approval",
+        "join.question": "你是如何知道本群的？",
+    },
+})
+if err != nil {
+    log.Fatal(err)
+}
+fmt.Printf("推送成功\n")
+```
+
+**注意事项**：
+
+1. **权限要求**：写入 indexed settings 需要 admin 及以上权限
+2. **签名算法限制**：当前版本仅支持 ECDSA-P256-SHA256，使用其他算法的 AID 无法签名
+3. **CAS 冲突策略**：默认重试 2 次，高并发场景建议增加 `max_attempts`
+4. **`signer` 必须是当前连接身份**：服务端强制校验 `signed_by == actor_aid`，传入其他 AID 会被拒绝
 
 ---
 
@@ -418,16 +683,16 @@ sub.unsubscribe()
 
 | 事件 | 说明 |
 |------|------|
-| `state_change` | 状态变化，`state` 为九态公开值 |
-| `connection.error` | 连接或重连错误 |
-| `token.refreshed` | token 刷新完成 |
-| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token 并等待重新登录 |
-| `message.received` | 收到 P2P 消息 |
-| `message.ack` | 消息 ack |
-| `message.undecryptable` | P2P E2EE 解密失败 |
-| `group.changed` | 群组事件 |
-| `group.message_undecryptable` | 群 E2EE 解密失败 |
-| `storage.object_changed` | Storage 对象变更事件透传 |
+| `state_change` | 状态变化，`state` 为九态公开值 |
+| `connection.error` | 连接或重连错误 |
+| `token.refreshed` | token 刷新完成 |
+| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token 并等待重新登录 |
+| `message.received` | 收到 P2P 消息 |
+| `message.ack` | 消息 ack |
+| `message.undecryptable` | P2P E2EE 解密失败 |
+| `group.changed` | 群组事件 |
+| `group.message_undecryptable` | 群 E2EE 解密失败 |
+| `storage.object_changed` | Storage 对象变更事件透传 |
 
 ---
 

package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -60,11 +60,13 @@ except AUNError as e:
 | -32008 | 资源不存在 | `NotFoundError` |
 | -32009 | 版本冲突 | `VersionConflictError` |
 | -32010 / -32011 / -32013 | 会话错误 | `SessionError` |
-| -32051 | 客户端签名验证失败 | `ClientSignatureError`（继承自 `ValidationError`） |
-| -32029 | 请求限流（目标/联邦维度） | `RateLimitError` |
-| -32429 | 请求限流（Gateway 入口背压，排队超时） | `RateLimitError` |
-| -32600 / -32601 / -32602 | JSON-RPC 参数错误 | `ValidationError` |
-| -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
+| -32051 | 客户端签名验证失败 | `ClientSignatureError`（继承自 `ValidationError`） |
+| -32029 | 请求限流（目标/联邦维度） | `RateLimitError` |
+| -32429 | 请求限流（Gateway 入口背压，排队超时） | `RateLimitError` |
+| -32600 / -32601 / -32602 | JSON-RPC 参数错误 | `ValidationError` |
+| -32602 且消息包含 `group.index etag conflict` | group.index CAS 冲突 | 应重新 `getGroupIndex`、合并、签名后重试 |
+| -32602 且消息包含 `group.index` 签名/schema/hash/etag 错误 | group.index 校验失败 | 检查 signer、canonical JSONL、`body_hash`、`etag` 和 `signature` |
+| -32040 ~ -32044 | E2EE 群组错误 | `E2EEError` 子类 |
 | 4090 | 身份冲突 | `IdentityConflictError` |
 | -32050 | 证书已吊销 | `CertificateRevokedError` |
 | -33001 | 群组不存在 | `GroupNotFoundError` |
@@ -154,5 +156,27 @@ if not client.can_send:
 ### E2EE 解密失败
 
 P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 `message.undecryptable` / `group.message_undecryptable` 事件，应用可记录并继续处理其他消息。
-
+
+### group.index CAS 冲突
+
+多个 owner/admin 并发修改公告、规则或入群要求时，服务端通过 `expected_index_etag` 做 CAS。冲突时错误消息包含 `group.index etag conflict`。
+
+处理方式：
+
+```python
+try:
+    await client.group.update_group_index({
+        "group_id": group_aid,
+        "settings": {"announcement.content": "new text"},
+    })
+except Exception as exc:
+    if "etag conflict" in str(exc):
+        latest = await client.group.get_group_index({"group_id": group_aid})
+        # 在 latest["entries"] 上合并本地修改，然后重新 update_group_index
+        raise
+    raise
+```
+
+通常优先使用 SDK 的 `updateGroupIndex` facade；它会按 `max_attempts` 自动重读当前 index 并重试。超过重试次数仍冲突时，把冲突交给应用层做合并策略。
+
 

package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -86,9 +86,9 @@ client.set_protected_headers({"sdk": "python", "trace": "abc"})
 
 ---
 
-## 6. Flow Control
-
-SDK 内部自动管理 RPC 并发，应用层无需配置：
+## 6. Flow Control
+
+SDK 内部自动管理 RPC 并发，应用层无需配置：
 
 | 机制 | 说明 |
 |------|------|
@@ -97,15 +97,31 @@ SDK 内部自动管理 RPC 并发，应用层无需配置：
 | Pull Gate | 同一 namespace/group 的 pull 操作自动序列化 |
 | 队列超时 | 排队超过 timeout 抛 `TimeoutError` |
 
-应用层保持普通 `await client.call(...)` 即可。
-
----
-
-## 7. 测试数据保护
-
-- 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
-- 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。
-- 需要换身份时使用新的 AID 名称，避免制造不可恢复的 key mismatch。
+应用层保持普通 `await client.call(...)` 即可。
+
+---
+
+## 7. Group Index 更新流程
+
+公告、规则、入群要求属于 indexed settings。owner/admin 修改这些内容时，不要直接裸调 `group.set_settings` 写单个 key，应使用 SDK facade 的 `updateGroupIndex` 语义。
+
+推荐流程：
+
+1. 调用 `checkGroupIndex` 判断本地已处理 etag 与观察到的远端 etag 是否不同步。
+2. 如果不同步，由应用层决定以本地还是远端为准：选择远端时调用 `getGroupIndex` 显式 pull，选择本地时继续保留本地缓存并准备 push。
+3. 在选定基线上合并本地要修改的 settings 和附件稳定引用。
+4. 调用 `updateGroupIndex`。SDK 会读取当前服务端 index、生成新签名 index，并带 `expected_index_etag` 调用 `group.set_settings`。
+5. 如果服务端返回 `group.index etag conflict`，说明提交基线已变化；应用层需要重新决定 pull、merge 或保留本地修改后再提交。
+
+`getAnnouncement`、`getRules`、`getJoinRequirements` 只读 SDK 本地缓存；本地没有对应值时才读取相应 settings 初始化缓存，不会因为 etag 不一致自动 pull 远端。`updateAnnouncement`、`updateRules`、`updateJoinRequirements` 已内置 indexed 写入路径。普通不进入 index 的设置，例如 `dispatch_mode`，仍可直接使用 `setSettings` / `set_settings` / `SetSettings`。
+
+---
+
+## 8. 测试数据保护
+
+- 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
+- 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。
+- 需要换身份时使用新的 AID 名称，避免制造不可恢复的 key mismatch。
 
 ---