@agentunion/fastaun-browser 0.5.1 → 0.5.3

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。
 
 ---