@agentunion/fastaun-browser 0.5.1 → 0.5.3

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/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -105,12 +105,15 @@ print(auth["access_token"], auth["gateway"])
 ### 连接
 
 ```python
-await client.connect({
-    "slot_id": "main",
-    "connection_kind": "long",
-    "auto_reconnect": True,
-    "heartbeat_interval": 30.0,
-    "token_refresh_before": 60.0,
+await client.connect({
+    "slot_id": "main",
+    "connection_kind": "long",
+    "delivery_mode": {"mode": "fanout"},
+    "background_sync": True,
+    "extra_info": {"app": "demo"},
+    "auto_reconnect": True,
+    "heartbeat_interval": 30.0,
+    "token_refresh_before": 60.0,
     "retry": {
         "initial_delay": 1.0,
         "max_delay": 64.0,
@@ -126,12 +129,14 @@ await client.connect({
 | 选项 | 说明 |
 |------|------|
 | `slot_id` | 同一设备内的实例槽位；允许 `/`、`:`、空格作为共享隔离键分隔符 |
-| `connection_kind` | `"long"` 或 `"short"` |
-| `short_ttl_ms` | 短连接服务端兜底超时 |
-| `delivery_mode` | 连接级投递语义 |
-| `auto_reconnect` | 断线后是否自动重连 |
-| `heartbeat_interval` | 心跳间隔，秒 |
-| `token_refresh_before` | token 过期前刷新提前量，秒 |
+| `connection_kind` | `"long"` 或 `"short"` |
+| `short_ttl_ms` | 短连接服务端兜底超时 |
+| `delivery_mode` | 连接级投递语义 |
+| `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
+| `background_sync` | 连接成功后是否执行 SDK 后台补洞 / 未读同步，默认开启 |
+| `auto_reconnect` | 断线后是否自动重连 |
+| `heartbeat_interval` | 心跳间隔，秒 |
+| `token_refresh_before` | token 过期前刷新提前量，秒 |
 | `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
 | `timeouts.connect/call/http` | 连接、RPC、HTTP 超时 |
 
@@ -188,10 +193,11 @@ print(client.can_connect, client.can_send, client.is_online)
 
 | 事件 | 说明 |
 |------|------|
-| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
-| `connection.error` | 连接、认证、重连错误 |
-| `token.refreshed` | token 自动刷新完成 |
-| `message.received` | 收到消息 |
+| `state_change` | 状态变化，payload 中的 `state` 是九态公开值 |
+| `connection.error` | 连接、认证、重连错误 |
+| `token.refreshed` | token 自动刷新完成 |
+| `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
+| `message.received` | 收到消息 |
 | `group.changed` | 群组事件 |
 | `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
 
@@ -238,8 +244,10 @@ state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
 | `AUNClient` | 连接、事件和 RPC 调用；不再暴露 agent.md 上传入口 |
 
 本地落盘位置由 SDK 管理。Python / TypeScript / Go 写入 `{aun_path}/AIDs/{aid}/agent.md` 和同目录 `agentmd.json`；浏览器 JavaScript 写入 IndexedDB 的等价 logical key，存储不可用时退化为内存缓存。agent.md 不写入 SQLite，也不再使用旧 `{aun_path}/AgentMDs` 目录。
-
----
+
+连接后的 RPC 响应、事件推送和消息信封会被 SDK 自动观察：Gateway `_meta.agent_md_etags` 中的 `requester`、`peer`、`group` 以及兼容别名 `receiver`、`target`、`to`、`sender`、`from` 会更新对应 AID 的 `remote_etag` / `last_modified`；V2 信封中的 `agent_md.sender` 和 `agent_md.group` 也会写入同一份本地记录。`group` 表示群自身 `group_aid` / `group_id` 的 agent.md，缺少 `aid` 时 SDK 会从信封顶层或 AAD 的 `group_aid` / `group_id` 兜底。
+
+---
 
 ## RPC 调用
 

package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md

@@ -41,14 +41,14 @@ await client.call("message.send", {
 })
 ```
 
-SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
-
-1. **prekey_ecdh_v2** — 对方有预上传的 prekey，四路 ECDH（ephemeral×prekey + ephemeral×identity + sender×prekey + sender×identity），前向安全，附带发送方签名
-2. **long_term_key** — 对方无 prekey，双路 ECDH（ephemeral×recipient_identity + sender×recipient_identity）+ HKDF 派生密钥（降级模式），附带发送方签名
-
-> Python SDK 默认 `require_forward_secrecy=true`，当加密结果不满足前向保密（无论是因为无 prekey 还是 prekey 加密失败降级到 long_term_key）时拒绝发送并抛出错误。需显式配置 `require_forward_secrecy=false` 才允许降级。
-
-每条消息独立生成临时 ECDH 密钥对，实现一消息一密钥。
+当前 SDK 使用 E2EE V2 多设备 wrap 主路径：
+
+1. 发送前通过 `message.v2.bootstrap` 或 `group.v2.bootstrap` 获取接收方当前活跃设备、设备 prekey、self-sync 设备和 audit recipients。
+2. SDK 为每条消息生成独立 `master_key`、消息 nonce 和发送方临时 session key，只加密一次正文。
+3. SDK 为每个接收设备生成一条 recipient wrap。设备有可用 SPK 时使用 `3DH` wrap；缺少 SPK 的兼容场景才使用 `1DH` wrap。
+4. E2EE 信封包含 `sender_signature`、AAD、`recipients_digest` / Merkle proof，接收端必须验签、验 AAD、验 recipient proof 后再解密。
+
+每条消息独立密钥；V2 当前主路径不再使用旧 `prekey_ecdh_v2` / `long_term_key` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
 
 ## ProtectedHeaders 与可验证上下文
 
@@ -65,9 +65,11 @@ SDK 优先使用 prekey_ecdh_v2，并默认要求前向保密：
 
 `payload_type` 不需要应用层传入。SDK 会读取加密前 `payload.type`，自动写入 `protected_headers.payload_type`，接收端解密后会校验它与明文 `payload.type` 一致。
 
-`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
-
-示例：
+`protected_headers` / `headers` 是 send/thought 参数的顶层字段，不放入单独的 `envelope` 入参对象，也不属于业务 `payload`。裸 WebSocket 客户端若自行发送已加密信封，需要把 protected headers 放在自构造的 E2EE 信封内并自行完成 `_auth`，服务端不会替裸 RPC 调用生成或校验明文侧的 protected headers。
+
+`agent_md` 是独立于 E2EE 的版本提示元数据，不属于 `protected_headers`，也不参与 AAD 或业务鉴权。当前 Message Service V2 P2P 信封可携带 `agent_md.sender`；SDK 也识别 `agent_md.group`。Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中注入 `requester`、`peer`、`group`，四端 SDK 会自动写入对应 AID 的 `remote_etag` / `last_modified`，后续仍以下载后的 agent.md 签名验证作为可信依据。
+
+示例：
 
 ```python
 from aun_core import ProtectedHeaders
@@ -103,7 +105,8 @@ await client.call("group.send", {
 
 ```json
 {
-  "type": "e2ee.encrypted",
+  "type": "e2ee.p2p_encrypted",
+  "version": "v2",
   "ciphertext": "...",
   "protected_headers": {
     "device_id": "dev-123",
@@ -127,8 +130,8 @@ await client.call("group.send", {
 
 计算规则：
 
-1. 解密流程会派生出本条消息的 `message_key`。
-2. `metadata_key = HMAC-SHA256(message_key, "aun-envelope-metadata-key-v1")`。
+1. 解密流程会得到本条消息的 `master_key`。
+2. `metadata_key = HMAC-SHA256(master_key, "aun-envelope-metadata-key-v1")`。
 3. 对字典去掉 `_auth` 后做 canonical JSON：UTF-8、key 排序、紧凑分隔符。
 4. `tag = HMAC-SHA256(metadata_key, domain + "\0" + canonical_json(body))`。
 5. `domain` 对 `protected_headers` 为 `aun-protected-headers-v1`，对 `context` 为 `aun-protected-context-v1`。
@@ -294,24 +297,20 @@ for msg in result["messages"]:
 
 ---
 
-## Prekey 管理
-
-连接时 SDK 自动上传 prekey，并定时轮换（默认每小时）。一般无需手动管理。
-
-手动上传 prekey：
-
-```python
-# 通过 AUNClient 上传（生成 + RPC）
-await client._upload_prekey()
-```
-
-底层 API（E2EEManager 只生成材料，不做 RPC）：
-
-```python
-prekey_material = client.e2ee.generate_prekey()
-# 返回 {"prekey_id": "...", "public_key": "...", "signature": "...", "created_at": ...}
-# 需要自行上传：await transport.call("message.e2ee.put_prekey", prekey_material)
-```
+## V2 设备公钥与 SPK 管理
+
+连接成功后，SDK 会初始化本设备 V2 session，生成或加载 IK / SPK，并通过 `message.v2.put_peer_pk` 幂等注册当前 P2P 设备 SPK。群组路径会按群生成独立 group SPK，并通过 `group.v2.put_group_pk` 注册。应用层一般无需手动管理这些密钥。
+
+当前主路径的要点：
+
+- P2P 设备 SPK 的 `key_source` 为 `peer_device_prekey`，由 AID 私钥签名背书。
+- 群内独立 group SPK 的 `key_source` 为 `group_device_prekey`，按规范化后的 `group_aid` 隔离。
+- SDK 发送前通过 `message.v2.bootstrap` / `group.v2.bootstrap` 获取目标设备集合和当前 SPK。
+- 旧 SPK 会在本地保留一段安全窗口，用于解密引用旧 SPK 的历史消息；满足已消费和保留窗口条件后才销毁。
+
+裸 WebSocket 客户端如果绕过 SDK，需要自行完成同等的 SPK 生成、AID 私钥签名、注册和 bootstrap 逻辑。旧 `message.e2ee.put_prekey/get_prekey` 只用于 legacy `prekey_ecdh_v2` 信封兼容，不是当前 SDK 的默认路径。
+
+SPK 签名里的 `spk_timestamp` 使用 Unix 秒；消息、群事件和服务端 `timestamp` / `created_at` 等主路径时间字段仍使用 Unix 毫秒。
 
 ---
 
@@ -361,7 +360,7 @@ client = AUNClient(aid)
 | P2P 消息默认要求发送方签名 | 无 `sender_signature` 的消息被拒绝 |
 | 群组消息默认要求发送方签名 | `require_signature=True`，无签名或无发送方证书的消息被拒绝 |
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
-| 默认要求前向保密 | `require_forward_secrecy=true`，无 prekey 时拒绝 long_term_key 降级 |
-| 客户端操作签名 | `group.send`/`group.kick`/`group.add_member`/`group.leave` 等操作自动附加 `client_signature`，服务端强制验签 |
+| 默认要求前向保密 | V2 优先使用设备 SPK 的 `3DH` wrap；缺少 SPK 的 `1DH` 路径仅作为兼容降级 |
+| 客户端操作签名 | SDK 会为关键操作附加 `client_signature`；Gateway 对 `send/pull/ack` 等常规 RPC 优先使用连接级身份认证，只有身份声明与连接不一致、敏感操作、能力身份或主动携签场景才执行 ECDSA 验签 |
 
 

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

@@ -118,6 +118,8 @@ Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览
 
 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 自动发现，无需手动指定端口。
 
 ---
@@ -260,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="group.agentid.pub/123")
+await client.notify("event/app.presence", {"state": "active"}, group_id="g-abc123.agentid.pub")
 ```
 
 路由选项：
@@ -268,7 +270,7 @@ await client.notify("event/app.presence", {"state": "active"}, group_id="group.a
 | 选项 | 说明 |
 |------|------|
 | `to` / `To` | 目标 AID；可同域或跨域 |
-| `group_id` / `groupId` / `GroupID` | 目标群；与 `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`，只控制在线投递过期，不表示离线缓存 |
@@ -310,6 +312,7 @@ 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 媒体类型上的结构化约定。
 
 ---
@@ -344,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,11 +686,13 @@ 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 对象变更事件透传 |
 
 ---
 

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` |
@@ -143,12 +145,38 @@ await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionEr
 发送前检查：
 
 ```python
-if not client.can_send:
-    await client.connect({"auto_reconnect": True})
-```
-
-### E2EE 解密失败
-
-P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 `message.undecryptable` / `group.message_undecryptable` 事件，应用可记录并继续处理其他消息。
-
+if not client.can_send:
+    await client.connect({"auto_reconnect": True})
+```
+
+### refresh_token 失效
+
+当自动刷新命中 `missing refresh_token`、`invalid_or_expired_refresh_token`、刷新链耗尽或服务端返回 `relogin_required=true` 时，SDK 会清理本地 `access_token` / `refresh_token` / `kite_token`，发布 `token.refresh_exhausted` 事件，并在后续重连时重新走完整登录链路。应用层可监听该事件提示用户重新授权；不要继续复用旧 token。
+
+### 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 并重试。超过重试次数仍冲突时，把冲突交给应用层做合并策略。
+