@agentunion/fastaun-browser 0.5.2 → 0.5.4

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 媒体类型上的结构化约定。
 
 ---
 
@@ -329,7 +329,7 @@ headers = client.get_protected_headers()
 | Collab | `client.collab` | `client.collab` | `client.Collab()` | 版本化文档、标签、`gc` / `reflog` / `revert` |
 | Group FS | `client.group.fs` | `client.group.fs` | `client.Group().FS()` | POSIX 风格群文件系统；`ls/find/stat/lstat/mkdir/rm/cp/mv/df/mount/umount`，以及 `set_acl/remove_acl/get_acl/list_acl` 角色 ACL 门面，上传下载数据面由 SDK 编排 |
 
-群文件系统路径统一使用 `group_aid:/...`，成员数据区使用 `group_aid:/memberdata/{member_ref}/...`。SDK 不拼接真实 storage 路径，`memberdata` 到成员 `group_data/{group_aid}` 的映射只在服务端完成。群自有区写入允许当前 `group_aid` 证书签名、默认 `role:owner`、以及 owner 通过 `group.fs.set_acl` 显式授权后的 `role:admin`；撤销使用 `group.fs.remove_acl`，查询使用 `group.fs.get_acl/list_acl`，这些角色 ACL 操作都要求当前 group owner 调用且对外权限位显示为 `rwx`。JS 浏览器版上传中 `string` 默认表示文本内容，Node 本地路径需显式 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀；Python/TS/Go 默认把 `string` 当本地路径。
+群文件系统路径统一使用 `group_aid:/...`，成员数据区使用 `group_aid:/memberdata/{member_ref}/...`。SDK 不拼接真实 storage 路径，`memberdata` 到成员 `group_data/{group_aid}` 的映射只在服务端完成。群自有区写入允许当前 `group_aid` 证书签名；成员角色中 `owner/admin` 默认可写群自有区，`member` 默认不可写。`owner/admin` 可通过 `group.fs.set_acl` 对特定业务目录授予 `role:member` 的 `rw` 权限，用于后续群协作场景；`rw` 只允许创建/写入，不授予删除、移动、重命名权限。`rwd` 是 storage 内部权限位，SDK/RPC 对外按 POSIX 视图显示为 `rwx`，不给删除/移动/重命名权限时只使用 `rw`。`.group/` 是系统控制目录，默认给 `owner/admin` 写权限，用于群公告、群规则、入群要求附件，不能向 `role:member` 授权。老群如果缺少 `.group/` 默认 ACL，group 服务会在该群首次被 RPC 访问时 best-effort 触发 namespace/ACL lazy repair；ACL 同步全部成功后才记录本进程已检查，失败会在后续访问继续重试。JS 浏览器版上传中 `string` 默认表示文本内容，Node 本地路径需显式 `sourceType: "path"`、`localPath: true` 或 `local:` 前缀；Python/TS/Go 默认把 `string` 当本地路径。
 
 ### 消息与群组门面
 
@@ -347,16 +347,291 @@ headers = client.get_protected_headers()
 - `getInfo()` — 查询群组信息（扁平化格式，提升常用字段到顶层），**推荐外部使用**
 - `info()` — 查询群组详细信息（带权限控制，非成员只能看公开群，成员能看 seq/epoch 等运行时状态）
 
-**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法，基于 `group.set_settings` / `group.get_settings` 实现：
+**群设置便利方法**：`GroupFacade` 提供向后兼容的便利方法：
+
+- `getAnnouncement()` / `updateAnnouncement()` — 群公告
+- `getRules()` / `updateRules()` — 群规则
+- `getJoinRequirements()` / `updateJoinRequirements()` — 入群要求
+- `getSettingWithIndex()` / `updateSettingWithIndex()` — 通用文档型 indexed setting（Python 为 `get_setting_with_index()` / `update_setting_with_index()`，Go 为 `GetSettingWithIndex()` / `UpdateSettingWithIndex()`）
+
+读取方法优先返回 SDK 本地缓存；本地没有对应值时才读取相应 settings 做初始化。便利读取从服务端拿到 canonical `group_aid` 后，会同时以 canonical `group_aid` 和本次入参 `group_id` 写入 settings cache，避免 legacy/base `group_id` 下一次读取直接 cache miss。即使 `checkGroupIndex` 观察到远端 etag 与本地 etag 不一致，`getAnnouncement()` / `getRules()` / `getJoinRequirements()` / `getSettingWithIndex()` 也不会自动拉取远端版本覆盖本地缓存。`updateAnnouncement()` / `updateRules()` / `updateJoinRequirements()` / `updateSettingWithIndex()` 属于 indexed 写入，内部会调用 `updateGroupIndex` 生成签名 `group.index` 并带 `expected_index_etag` CAS 提交。
+
+`getSettingWithIndex()` / `updateSettingWithIndex()` 比三对预定义方法多一个 `keyName`（Python 可传 `key_name`，Go 同时接受 `keyName` / `key_name`）。SDK 会生成 `{keyName}.content` 和 `{keyName}.attachments` 两个 settings key；`keyName` 只能是受控文档名（`^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀）。`getRules()` / `updateRules()` 与 `getAnnouncement()` / `updateAnnouncement()` 是该通用方法在 `rules`、`announcement` 上的薄封装；`getJoinRequirements()` / `updateJoinRequirements()` 保持结构化 schema，不改成 `join.content`。
+
+这些 `update*` 便利方法只更新群设置元数据：`updateRules()` / `updateAnnouncement()` / `updateSettingWithIndex()` 写入 `*.content` 与 `*.attachments`，`updateJoinRequirements()` 写入 `join.mode` / `join.question` / `join.auto_approve_patterns` / `join.max_pending` / `join.attachments`。`attachments` 只保存稳定引用，附件实体应先上传到 group.fs 群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。
+
+**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": "...",
+    ...
+  }
+}
+```
+
+**行为**：
 
-- `getAnnouncement()` / `updateAnnouncement()` — 群公告
-- `getRules()` / `updateRules()` — 群规则
-- `getJoinRequirements()` / `updateJoinRequirements()` — 入群要求
+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)` 标记本地与远端同步
 
-便利方法返回旧格式（嵌套对象 `{announcement: {content, attachments}}`），屏蔽 `settings` 数组的繁琐。新代码建议直接使用 `group.set_settings` / `group.get_settings` 以获得更灵活的批量操作能力（一次调用可设置多个键）。
+**错误处理**：
+
+- **签名验证失败**：抛异常，不更新本地缓存
+- **不支持的 `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` / `join.attachments` — 入群要求及附件
+- `{keyName}.content` / `{keyName}.attachments` — 通用文档型 indexed setting；`keyName` 需满足 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，且不能使用 `join` 等保留前缀
+
+**返回值**：
+
+```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": "你是如何知道本群的？",
+        "join.attachments": []any{
+            map[string]any{"type": "group.fs", "path": "/.group/attachments/join/guide.pdf"},
+        },
+    },
+})
+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 会被拒绝
+5. **附件字段只存引用**：`updateRules` / `updateAnnouncement` / `updateSettingWithIndex` 传入 `content` 和 `attachments` 元数据引用；`updateJoinRequirements` 传入结构化入群字段和 `attachments` 元数据引用。附件实体先上传到群自有区，推荐路径为 `group_aid:/.group/attachments/{rules|announcement|join|<keyName>}/...`。群自有区默认允许 `owner/admin` 写入，`member` 默认不可写；`.group/` 不允许授予 `role:member` 写权限。
+
+---
+
 ## ServiceProxyClient
 
 Service Proxy 用于 provider 通过 AUN 身份暴露本地 HTTP / WebSocket 服务。当前公开封装在 Python SDK 的 `ServiceProxyClient` 中；其它语言可以按 [09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) 直接实现同等控制面和隧道消息。
@@ -418,16 +693,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。
 
 ---