@agentunion/fastaun-browser 0.5.19 → 0.5.21

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

@@ -7,6 +7,7 @@
 - [AIDStore](#aidstore)
 - [AID](#aid)
 - [AUNClient](#aunclient)
+- [业务门面](#业务门面)
 - [事件](#事件)
 - [ServiceProxyClient](#serviceproxyclient)
 - [E2EE 高级 API](#e2ee-高级-api)
@@ -63,18 +64,151 @@ store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
 | `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
-| `register(aid)` | `register(aid)` | `Register(ctx, aid)` | 注册并落盘证书和私钥 |
+| `register(aid)` | `register(aid)` | `Register(ctx, aid[, opts])` | 注册并落盘证书和私钥；Go 两参数旧调用仍可用，显式选项使用 `AIDStoreRegisterOptions` |
 | `list()` | `list()` | `List()` | 列出本地 AID |
 | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
-| `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 拉证书并缓存；默认下载 agent.md，可用 `skip_agent_md` / `skipAgentMd` 跳过 |
-| `upload_agent_md(aid, content=None)` | `uploadAgentMd(aid, content?)` | `UploadAgentMD(ctx, aid, content...)` | 普通主体以本身份签名/token 发布；Group/Org 仅当前 owner 本人尾签并携带 V2 owner 授权上传，见协议 §2.5 |
+| `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 解析身份及名片，返回结构化 `agent_md.frontmatter`；可按需复用 ownership 共识校验并缓存 owner.md，完整输入输出见下节 |
+| `upload_agent_md(aid, content=None, *, uploader_aid=None, co_signer_aid=None)` | `uploadAgentMd(aid, content?, options?)` | `UploadAgentMD(ctx, aid, content...)` / `UploadAgentMDWithOptions(ctx, aid, opts, content...)` | 普通主体自签自传；Group/Org 实体主签、owner token 上传及可选 owner 附签，见协议 §2.5 |
 | `download_agent_md(aid, timeout_s=None)` | `downloadAgentMd(aid, timeoutMs=30000)` | `DownloadAgentMD(ctx, aid)` | 下载 agent.md，返回 `DownloadAgentMdResult` / `AgentMDInfo` |
 | `check_agent_md(aid, ttl_days=1)` | `checkAgentMd(aid, ttlDays=1)` | `CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 通过 HEAD 和本地记录检查一致性 |
+| `sign(aid, input, *, input_type="text", format="raw", tag="", append=False, in_place=False, ...)` | `sign(aid, input, {inputType, format, tag, append, inPlace, ...})` | `Sign(ctx, aid, input, opts)` | 通用裸签或文档多签 |
+| `verify(aid, input, signature=None, *, input_type="text", format="raw", ...)` | `verify(aid, input, signature?, {inputType, format, ...})` | `Verify(ctx, aid, input, opts)` | 裸签或逐块文档验签；Go detached 签名传 opts.Signature |
 | `diagnose(aid)` | `diagnose(aid)` | `Diagnose(ctx, aid)` | 本地 + 远端诊断 |
 | `renew_cert(aid)` / `rekey(aid)` | `renewCert(aid)` / `rekey(aid)` | `RenewCert(ctx, aid)` / `Rekey(ctx, aid)` | 证书运维 |
 | `change_seed(old, new)` | `changeSeed(old, new)` | `ChangeSeed(old, new)` | 本地密钥保护种子迁移 |
 
-Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览器 JS 因 IndexedDB / WebCrypto 约束返回 `Promise<Result>`。联网方法在 TS/JS 中均返回 `Promise<Result>`；Go 形态为 `Result[T]`，字段为 `Ok` / `Data` / `Error`。
+Go 的 `Register(ctx, aid)` 保留原有简单身份注册行为；`Register(ctx, aid, AIDStoreRegisterOptions{...})` 是显式类型/owner 登记入口。历史 owner-aware `RegisterWithOptions(ctx, AIDRegisterParams{...})` 单独保留旧注册编排，不等同于 Ownership 2.1 的双文件关系确认。
+
+Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览器 JS 因 IndexedDB / WebCrypto 约束返回 `Promise<Result>`。TS/Node 的 Store.sign/verify 也是异步 `Promise<Result>`，属于上述本地方法的例外；联网方法在 TS/JS 中均返回 `Promise<Result>`；Go 形态为 `Result[T]`，字段为 `Ok` / `Data` / `Error`。
+
+自有私钥身份的 `resolve` 默认优先返回本地草稿/缓存，标记 `verification.status=unverified`、`source.agent_md_fetched=false`；草稿的 `in_sync=false`。需要读取远端内容时，显式下载或强制刷新，本地草稿仍保留；刷新选项分别为 Python `force_refresh`、TS/JS `forceRefresh`、Go `ForceRefresh`。失败稿由应用显式重试上传，重连不自动重传。
+
+### resolve 输入与输出
+
+沿用 `AIDStore.resolve`，不增加独立的 frontmatter 查询方法。`agent_md.content` 保留完整原文，`agent_md.frontmatter` 提供同一名片的 YAML 元数据；普通调用不额外查询 ownership。
+
+| SDK | 签名 |
+|-----|------|
+| Python | `await store.resolve(aid: str, opts: dict \| None = None) -> Result[ResolveResult]` |
+| TypeScript / JavaScript | `await store.resolve(aid: string, opts?: ResolveOpts): Promise<Result<ResolveResult>>` |
+| Go | `store.Resolve(ctx context.Context, aid string, opts ...AIDStoreResolveOptions) Result[AIDStoreResolveResult]` |
+
+#### 输入与 opts
+
+`aid` 为目标 AID 字符串，如 `alice.agentid.pub`。`opts` 全部可选；Go 不传 options 时使用零值选项。
+
+| TS/JS | Python | Go | 类型、默认值与行为 |
+|-------|--------|----|--------------------|
+| `forceRefresh` | `force_refresh` | `ForceRefresh` | bool，默认 false；绕过本地身份/名片优先路径并刷新证书和远端名片；启用 ownership 时也绕过共识缓存 |
+| `skipAgentMd` | `skip_agent_md` | `SkipAgentMD` | bool，默认 false；省略输出的 `agent_md`。与 ownership 同用时，共识校验仍可在内部读取当前 agent.md |
+| `timeout` | `timeout` | `Timeout` | TS/JS 为毫秒数，名片下载默认 10000 ms；Python 为毫秒数，未传时名片下载默认 30 s；Go 为 `time.Duration`，默认 10 s，约束整个 Resolve context |
+| `ownership` | `ownership` | `Ownership` | 默认不传；传入已有 `AUNClient` 或实现共识查询接口的对象，调用 `checkOwnershipConsensus(aid)` / `check_ownership_consensus(aid)` / `CheckOwnershipConsensus(ctx, aid)`；不接受布尔开关 |
+| `ownershipTtlMs` | `ownership_ttl_ms` | `OwnershipTTL` | TS/JS/Python 为毫秒数，默认 60000；Go 为 `*time.Duration`，nil 表示一分钟，指向 0 表示不复用缓存；各端的 0 均表示每次查询 |
+
+Python 兼容 `forceRefresh`、`skipAgentMd`、`timeoutMs`、`ownershipTtlMs` 别名。TS/JS/Python 的 timeout 沿用名片下载的超时范围，共识请求沿用所传 client 的配置；Go 将 Resolve context 传给共识入口。`ownership` 使用现有身份和连接，不在 resolve 中新建 client。
+
+#### 成功输出
+
+返回既有 Result 包装：Python/TS/JS 读取 `ok/data/error`，Go 读取 `Ok/Data/Error`。
+
+| Python / TS / JS 的 `data` 字段 | Go 字段 | 类型与含义 |
+|-------------------------------|---------|------------|
+| `aid` | `AID` | 目标 `AID` 对象，含既有证书与身份能力；不是 AID 字符串 |
+| `agent_md` | `AgentMD` | `DownloadAgentMdResult` / `AgentMDInfo`，含原文、frontmatter、验签与缓存信息；skip 时省略，Go 为 nil |
+| `ownership` | `Ownership` | 共识结果加 `checked_at/cached`；未传 ownership 时省略，Go 为 nil |
+| `source.cert_from_cache` | `Source.CertFromCache` | bool，身份材料是否由本地加载 |
+| `source.agent_md_fetched` | `Source.AgentMDFetched` | bool，是否执行名片下载；包含使用本地内容完成的 HTTP 304；本地草稿/缓存和 skip 路径为 false |
+
+身份解析、证书或名片下载失败沿用原有外层 `ok=false` 和错误码。身份及名片已成功时，额外的 ownership 查询失败写入 `ownership.status=unavailable`，外层仍成功，不回退为过期的成功关系。
+
+#### frontmatter 结构与公开字段
+
+公开原文 frontmatter 中的全部字段，包括扩展字段；不把字段统一转换成字符串、不扁平化嵌套结构。对象、数组、字符串、数字、布尔值及 null 保留各语言 YAML 解析后的类型。TS/JS 为公开的 `AgentMdFrontmatter` 接口，扩展值类型为 `unknown`；Python 为 `AgentMdFrontmatter = dict[str, Any]`；Go 为 `AgentMDFrontmatter map[string]any`，通过 `AgentMD.Frontmatter` 访问。
+
+| 字段 | 类型 | 当前 Schema 含义 |
+|------|------|-----------------|
+| `aid` | string | 名片所属主体的 AID |
+| `name` | string | 显示名 |
+| `type` | string | 开放字符串；常见 human、agent、service、device、group、org、host |
+| `version` | string | 名片 Schema 版本，SemVer，如 `1.0.0` |
+| `exttype` | string | 主体扩展类型 |
+| `description` | string | 简介，不超过 100 个 Unicode 字符 |
+| `avatar` | string | 头像地址，不超过 256 个 Unicode 字符 |
+| `tags` | string[] | 标签 |
+| `owner` | string | 名片声明的 owner；普通主体需结合 2.1 共识状态判断；Group/Org 属于专属生命周期 |
+| `ownership` | object | 普通主体的声明容器，当前核心字段为 `statement` |
+| `entity_cert_fingerprint` | string | Group/Org 实体证书的 `sha256:<hex>` 指纹 |
+| 其它键 | 任意解析值 | 如 visibility、skills 或应用自定义字段，存在时原样返回 |
+
+当前发布 Schema 要求 `aid/name/type/version`；读取接口兼容历史名片，因此类型声明中的标准字段可缺省，不补默认值，裸 Markdown 正文返回 `{}`。`ownership.statement` 保留六字段：`version=2`（整数）、`declaration_id`（小写 UUIDv4）、`owner_aid`、`sub_aid`、`relation_version`（正整数）和 `declared_at`（Unix 秒）。普通主体的 owner 与 statement 同时存在或同时缺省；human 禁止通用 ownership，Group/Org 不使用此声明容器。
+
+字段定义与签名规则以 [当前协议 §1.3、§2](../protocol/Ownership协议定义2.1.md) 为准；[agent.md/SCHEMA.md](../agent.md/SCHEMA.md) 是 legacy Ownership 2.0。`frontmatter.owner` 和已有 `agent_md.verification.ownership_status` 都不替代下面的 2.1 共识结果。
+
+#### ownership 输出
+
+查询复用现有双文件共识校验：读取当前 NS agent.md 与 owner Storage 的 `default/sub_aids/{aid}/owner.md`，沿用声明、签名、证书、前后新鲜读取及 30 秒窗口检查。
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `status` | string | 下表七种共识状态之一 |
+| `sub_aid` | string | 被查询的目标 AID |
+| `owner_aid` | string \| null | 仅 consensus 返回当前有效 owner，其余状态为 null |
+| `relation_version` | integer \| null | 本次观察的关系代际；尚未取得材料时 TS/JS/Go 为 0，Python 可为 null |
+| `lock` | string \| null | 本次 NS 的 locked/unlocked；尚未取得材料时 TS/JS/Go 为 unlocked，Python 可为 null |
+| `agent_md_etag` | string \| null | 本次共识所读 agent.md 的 ETag |
+| `agent_md_sha256` | string \| null | 本次共识所读完整 agent.md 的 SHA-256 十六进制摘要 |
+| `owner_md_sha256` | string \| null | owner.md 完整原文摘要；缺失时 TS/JS/Go 为空串，Python 可为 null |
+| `ns_protocol` | string，可选 | 既有共识入口提供时保留的 NS 协议标记 |
+| `owner_md` | object，可选 | 实际读取到的 owner 文件快照，结构见下表；未进入 owner 读取阶段时省略 |
+| `code/reason/retryable` | string/string/bool，可选 | 沿用共识入口的错误说明及可重试性，如 unsupported_protocol；不根据缺省值推断成功 |
+| `checked_at` | integer | 本次共识查询完成时间，Unix 毫秒；缓存命中时保留原值 |
+| `cached` | bool | 是否复用了本地共识快照 |
+
+| status | 含义 |
+|--------|------|
+| `consensus` | 双方当前文件匹配且通过校验，关系成立 |
+| `released` | 当前材料确认关系已释放 |
+| `unbound` | 当前没有成立的绑定 |
+| `single_sided` | 只有一方声明或待确认材料，关系尚未成立 |
+| `invalid` | 声明、签名或身份绑定等材料无效 |
+| `unavailable` | 网络、证书、服务能力、权威性或读取一致性不足，当前无法确认 |
+| `not_applicable` | Group/Org 等使用专属生命周期，不适用通用共识 |
+
+`owner_md` 包含 `owner_aid: string`、`bucket: "default"`、`path: "sub_aids/{aid}/owner.md"`、`exists: bool`、`content: string`（完整原文，含签名）、`sha256: string`、`observed_at: integer`（Storage 观察时间，Unix 秒）。确认不存在时 exists=false、content/sha256 为空串；存在快照不表示整体共识成功，须检查 status。
+
+#### 缓存与刷新
+
+共识快照连同 owner.md 原文保存在该 AID 的 `agentmd.json.ownership_snapshot`；浏览器使用 IndexedDB 等价记录，沿用现有存储不可用时的内存回退。该记录不进入名片 frontmatter 或上传内容。
+
+仅在目标匹配、时间未倒退且仍在 TTL 内、上次状态不是 unavailable，并且本次返回的 agent.md 原文摘要与快照一致时复用；skip 路径没有名片内容可比时按目标和 TTL 判断。forceRefresh 绕过缓存，TTL=0 每次重新查询；返回对象与缓存隔离，修改返回值不污染后续结果。
+
+自有身份可返回本地草稿，同时 ownership 检查当前远端原件；两者以 `agent_md_sha256` 区分，不能把草稿中的 owner 当成已成立关系。缓存结果供读取和展示；绑定、释放、转移及其它依赖 owner 的授权操作继续执行原有的新鲜共识校验。
+
+```ts
+const result = await store.resolve('alice.agentid.pub', { ownership: client });
+if (result.ok) console.log(result.data.agent_md?.frontmatter, result.data.ownership?.status);
+```
+
+```python
+result = await store.resolve("alice.agentid.pub", {"ownership": client})
+if result.ok:
+    print(result.data["agent_md"]["frontmatter"], result.data["ownership"]["status"])
+```
+
+```go
+result := store.Resolve(ctx, "alice.agentid.pub", aun.AIDStoreResolveOptions{Ownership: client})
+if result.Ok && result.Data.AgentMD != nil {
+    fmt.Println(result.Data.AgentMD.Frontmatter, result.Data.Ownership.Status)
+}
+```
+
+### 通用 sign / verify
+
+`format="raw"` 为默认，保留 detached Base64 签名／验签；`format="document"` 处理任意 UTF-8 文本文档的连续尾签，不要求 YAML 或 agent.md 业务字段。sign 返回 `signed` 全文、本次 `signature` 和实际 `signatures` 列表；verify 返回 `valid`、`status`、首块前 `payload` 及逐块 `signatures`。普通 agent.md 与 owner.md 主签不输出且业务不接受 signer_aid；实体主块显式 signer_aid=target，主签身份、Schema、资源及授权由调用者另验，SDK 文件流程和服务端均复用各自唯一同构签验 core。
+
+`input_type="text"` 默认把输入视作内容；显式 `input_type="file"` 才读取文件；raw 按原始字节处理，包括非 UTF-8 文件，document 必须严格 UTF-8，raw/document 字符串均严格校验 Unicode 并编码为 UTF-8，无效 Unicode 拒绝。不识别 `file://` 或自动猜路径，缺失文件报错。`in_place=True` 仅适用于 file + document，签名成功后才写回；TS/JS 使用 `inputType/inPlace`，Go 使用 `InputType/Format/Tag/Append/InPlace`。浏览器 File/Blob 只读，FileSystemFileHandle 可原地写，不接受裸本地路径。
+
+`append=True` 仅在已有签名链末尾追加时，末字节非 LF/CR 才补 LF，其余字节不变；无旧块时仍按首签要求正文以 CR/LF 结束，否则拒绝；新块签完整 prefix，含该分隔及所有前序完整块。主块保持旧正文裸签；附签必填 signer_aid。tag 是 `[A-Z0-9-]+` 字面后缀：空串无 TAG，`AGENTMD-V2` 生成 `AUN-SIGNATURE-AGENTMD-V2`，`AUN-SIGNATURE` 不作特殊选项；内部 wrapper 传短 tag，标签不授予角色。verify 必须全块验签并报告实际顺序，不能保证检测末端删签；签名区总计仍限 2048 字节，不加证书链字段，证书沿用可信指纹 resolver。verify 默认离线 load 本地公钥／证书，不要求私钥；历史／远端材料由业务显式注入可信 certificateResolver，并沿用既有证书链及生命周期检查，既有 agent.md 远程下载流程不变。数学验签失败仍返回全部逐签 records；resolver 操作异常保留外层 error，不能误标坏签名。精确字节及主签规则见 [协议 §2.4](../protocol/Ownership协议定义2.1.md#24-文件签名)。
 
 ### Result 类型
 
@@ -92,14 +226,18 @@ Python、TS/Node 与 Go 的 `AIDStore` 本地方法返回 Result 包装；浏览
 |------|------|------|
 | `aid` | str | AID 字符串 |
 | `content` | str | agent.md 原始内容 |
-| `verification` | `{status, reason?}` | 验签结果；`status` 为 `"ok"` / `"no_cert"` / `"invalid"` 等 |
+| `frontmatter` | object | 原文 YAML 元数据，字段和类型见 [resolve 规格](#resolve-输入与输出)；Go 为 `Frontmatter` |
+| `verification` | `{status, reason?, ownership_status?}` | 名片读取的签名状态，如 verified、unsigned；本地草稿为 unverified，验签失败沿用外层错误；ownership_status 保留既有语义 |
 | `signature` | dict | 低层签名解析和验签结果 |
 | `cert_pem` | str | 签名所用证书 PEM |
 | `etag` | str | HTTP ETag |
 | `last_modified` | str | HTTP Last-Modified |
-| `status` | int | HTTP 状态码；异常 304 且本地有内容时可返回 304 |
+| `status` | int | Python/TS/JS 下载的 HTTP 状态码，缓存内容完成读取时可为 304；Go 的 AgentMDInfo 不提供该字段 |
 | `in_sync` | bool\|null | 目标是当前 AID 时表示本地内容 ETag 是否等于远端 ETag；对端 AID 通常为 null |
-| `saved_to` | str | SDK 管理的本地 agent.md 位置或浏览器 logical key |
+| `saved_to` | str\|null | SDK 管理的本地 agent.md 位置或浏览器 logical key |
+| `save_error` | str\|null | 既有本地保存错误信息，无错误时为空；Go 空值可省略 |
+
+resolve 的本地草稿/缓存路径不执行远程下载，其辅助字段沿用各端现状：TS 的 status 为 200、浏览器为 0，Python 可省略 status/signature/saved_to；验签信息不代表本轮重新验签。HTTP 200 与 304 路径均根据实际返回的 content 提供 frontmatter。
 
 ### CheckAgentMdResult
 
@@ -250,6 +388,8 @@ result = await client.call("message.send", {
 
 `ttl` 单位为秒：缺省或 `<=0` 保持持久化；正数钳制到 1–3600 秒，只存于消息服务内存且不分配持久 `seq`。四个 SDK 自动维护 volatile 游标、去重及 ACK；返回和事件中的 `storage`、`volatile_cursor`、`created_at`、`expires_at` 可用于识别此类消息。
 
+`message.send` / `group.send` 的可选 `need_render` 默认为 `true`；SDK 将它放入外层信封，历史缺字段或 NULL 也按 `true`。它用于展示和待同步数量统计，不改变拉取顺序，不进入 E2EE AAD、protected headers、消息保护签名或元数据 HMAC；RPC `client_signature` 仍按原业务参数规则覆盖该字段。
+
 常用 meta RPC 直接透传：
 
 ```python
@@ -312,15 +452,16 @@ headers = client.get_protected_headers()
 
 | Python | TS/JS | Go | 说明 |
 |--------|-------|----|------|
-| `AIDStore.upload_agent_md(aid, content=None)` | `store.uploadAgentMd(aid, content?)` | `store.UploadAgentMD(ctx, aid, content...)` | 发布指定本地 AID 的 agent.md |
+| `AIDStore.upload_agent_md(aid, content=None, *, uploader_aid=None, co_signer_aid=None)` | `store.uploadAgentMd(aid, content?, options?)` | `store.UploadAgentMD(ctx, aid, content...)` / `store.UploadAgentMDWithOptions(ctx, aid, opts, content...)` | 发布指定本地 AID 的 agent.md |
 | `AIDStore.download_agent_md(aid)` | `store.downloadAgentMd(aid)` | `store.DownloadAgentMD(ctx, aid)` | 下载并验签 |
 | `AIDStore.check_agent_md(aid)` | `store.checkAgentMd(aid)` | `store.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 检查一致性 |
 
 说明：
 
 - agent.md 上传、下载和检查入口都在 `AIDStore`；`AUNClient` 不再暴露上传入口。
-- 上传要求目标 AID 已在本地加载且私钥有效；SDK 会对正文签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-- SDK 发起 GET 时只发送 `Accept: text/markdown`，不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304，本地有内容则复用；无内容时再发一次无条件 GET。
+- 普通主体目标 AID 须有本地签名材料并使用自身 token；Group/Org 用实体主签、当前 owner token 上传，可选 owner 附签，不能以附签替换资源授权。agent.md 与 owner.md 统一调用 Store document 签验 core，再验证业务 Schema。
+- 实体上传默认使用名片当前 owner；显式指定上传者分别使用 Python `uploader_aid`、TS/JS `options.uploaderAid`、Go `AIDStoreUploadAgentMDOptions.UploaderAID`。追加 owner 附签分别使用 `co_signer_aid`、`options.coSignerAid`、`AIDStoreUploadAgentMDOptions.CoSignerAID`，值必须为当前 owner；Go 通过 `UploadAgentMDWithOptions` 传入选项。
+- SDK 全部 NS GET/HEAD/PUT 携带 `X-AUN-Signature-Format: multi-v1`；GET 同时发送 `Accept: text/markdown`；实体 fresh GET 另带 `X-AUN-Ownership-Check: 1` 与 `Cache-Control: no-cache` 以绕 LRU 全块验证，仍为 not_applicable、不进入通用账本；不主动发送 `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 媒体类型上的结构化约定。
 
@@ -330,6 +471,15 @@ headers = client.get_protected_headers()
 
 除 `client.call(method, params)` 外，四语言 SDK 提供高层门面（Facade），封装常用操作并简化参数。普通应用优先用门面，只有需要精确控制底层参数时再直调 RPC。
 
+### Ownership、凭证与组织专题
+
+| 领域 | 当前入口 | 详细指南 |
+|------|----------|----------|
+| Ownership 2.1 | 七个关系业务Facade：`bindOwneraid`、`bindSubaid`、`releaseSubaid`、`transferSubaid`、`acceptOwnershipRequest`、`rejectOwnershipRequest`、`checkOwnershipConsensus`；无参数任务管理Facade `resetOwnershipTask()`（Python `reset_ownership_task()`、Go `ResetOwnershipTask(ctx)`），批量清理当前AID发起的未完成任务，返回`{reset_operation_ids:[],skipped_operation_ids:[]}`（其余为TS/JS命名） | [应用集成](Ownership2.1-SDK应用集成指南.md#4-七个-facade-的参数角色与结果)、[开发与移植](Ownership2.1-SDK开发与移植指南.md) |
+| Credential/Org | Python/TS/JS：`client.credential`、`client.org`；Go：`client.Credential()`、`client.Org()`；包含本地协议助手和业务 facade，服务端可用方法以 RPC 手册为准 | [应用集成](凭证与组织服务SDK应用集成指南.md)、[开发与移植](凭证与组织服务SDK开发与移植指南.md) |
+
+Ownership 2.1 关系须检查当前双文件共识；Group/Org 使用专属生命周期，通用关系操作返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
+
 ### 文件与存储门面
 
 | 能力 | Python | TS/JS | Go | 说明 |
@@ -346,7 +496,7 @@ headers = client.get_protected_headers()
 
 | 能力 | Python | TS/JS | Go | 说明 |
 |------|--------|-------|----|------|
-| Message | `client.message` | `client.message` | `client.Message()` | 消息便利方法：`send()`、`pull()`、`history()`、`ack()`、`read()`、`read_state/readState/ReadState`、`recall()`、`queryOnline()` |
+| Message | `client.message` | `client.message` | `client.Message()` | 消息便利方法：`send()`、`peers()`、`pull()`、`history()`、`ack()`、`read()`、`read_state/readState/ReadState`、`recall()`、`queryOnline()` |
 | Message Thought | `client.message.thought` | `client.message.thought` | `client.Message().Thought()` | P2P 思考内容：`put()`、`get()`（不持久化、不分配 seq、强制 E2EE） |
 | Group | `client.group` | `client.group` | `client.Group()` | 群组便利方法：`create()`、`send()`、`pull()`、`history()`、`ack()`、`read()`、`read_state/readState/ReadState`、群管理方法、群查询方法、群设置便利方法 |
 | Group Thought | `client.group.thought` | `client.group.thought` | `client.Group().Thought()` | 群思考内容：`put()`、`get()`（不持久化、不分配 seq、强制 E2EE） |
@@ -355,9 +505,11 @@ headers = client.get_protected_headers()
 
 业务已读与投递 ACK 独立。Python 使用 `read/read_state`，TS/JS 使用 `read/readState`，Go 使用 `Read/ReadState`；四个已读门面保留显式 `None/null/nil` 字段交服务端校验。只有省略 `states` 时兼容顶层单条，显式空/null 批次拒绝；写入回执不是共享汇总。完整字段与事件契约见 [Message RPC](09-message-rpc-manual.md#messageread) 和 [Group RPC](09-group-rpc-manual.md#groupread)。
 
-`message.history` 和 `group.history` 使用 `before_seq` 排他上界向左翻页，下一页直接使用响应的 `next_before_seq`。History 只读，不推进实时 A/T/H、不 ACK、不触发实时消息事件。实时 Push 的最新页同步完全由 SDK 内部自动执行，再按 A/T/H 决定是否补一页 Forward；没有需要应用调用的 Tail 方法或参数。
+新 SDK 声明严格布尔能力 `p2p_peer_pull_v1: true`，保留设备原共享 seq，按完整 `sender_aid` 隔离 P2P 游标。`message.pull` 指定 sender 时读取该对端；省略时先查询完整 pending `message.peers`，再通过共享 N=4 Gate 并发读取全部待同步对端。显式游标（包括 `after_seq=0`）、force 或 Tail 必须指定 sender。pending 列表不分页、不截断到 200，peer 单页 Pull/History 默认及最大 200 条。目录 `next_pending_seq` 直接使用 peer 服务端 A 作近似；调度优先采用有效非负整数提示的原值（含 0），缺失或非法才回退到 `max(已确认覆盖水位,本地A)`，不取 `max(A,hint)`，不改变应用列表顺序。
+
+`message.history` 必须指定 `sender_aid`，与 `group.history` 一样使用 `before_seq` 排他上界向左翻页，下一页复用 `next_before_seq`。History 不推进实时 A/T/H、不 ACK、不触发实时消息事件。P2P 仅在已验证自身 `agent.md.type=human` 时自动优先 Tail→Forward，其余类型直接 Forward；指定 sender 后也可显式传 `window_mode="tail"`。Group 保持原实时窗口模型。
 
-消息回调只提供页级语义：单个 Tail/Forward 响应页内按 seq 升序、同 seq 最多一次；跨 Push/Tail/Forward 页可能重复或乱序。A/T/H 不能用于判断某条消息是否已经回调。全局去重与排序不是 SDK 业务逻辑保证；应用仓库应以 `(namespace, message_id)` 做唯一键，并按 `seq` 排序。SDK 的进程内折叠仅是 best-effort 优化。
+SDK 保留运行期内存去重：发布序号窗口按 namespace 保留最高 50,000 个 seq；P2P 成功交付绑定最多 50,000 条，按接收 AID、设备、slot、事件类别及原正 delivery seq 识别，另校验 sender/message_id，不因 namespace 或 Push/Pull 来源改变该 P2P 身份。消息热路径不逐条读写耐久 receipt，自定义 store 不要求提供 receipt 能力。所选应用 handler 全部成功后才完成内存标记；持久消息 Forward 页依据有效 proof 提交页 A/T/H 后，再发送本页新增累计 seq ACK，实际耐久性取决于 store 的持久化能力。volatile 与群事件 ACK 沿用各自原路径，失败不提前确认。淘汰、重建 client、进程崩溃或新旧 SDK 切换后允许重放，应用须将消息幂等与业务副作用放在同一持久事务中；持久 P2P 使用 message_id 唯一键，volatile 保留原 sender+message_id 隔离；多个 client/进程没有跨实例原子 claim。跨 peer 不保证全局回调顺序，显式 History/force/Tail 返回列表不因内存去重删行。
 
 **群成员管理与状态方法**：
 
@@ -756,11 +908,15 @@ sub.unsubscribe()
 | `token.refreshed` | token 刷新完成 |
 | `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token 并等待重新登录 |
 | `message.received` | 收到 P2P 消息 |
+| `message.batch` | P2P 消息/撤回批次，items 保留原 `message.received` / `message.recalled` |
+| `message.peers_snapshot` | SDK 本地待拉对端、水位、可选 next_pending_seq 与整体积压估计；列表保持响应原顺序，应用查询成功时空/非空均发布，后台仅发布非空列表 |
 | `message.read_changed` / `group.read_changed` | 同一 AID 共享已读位置提交并前进；owner 必须为当前身份、scope 匹配原事件 |
 | `read_state_sync` | SDK 本地已读补偿完成，含本轮 `owner_aid`、去重 `states` 和逐项 `errors`；连接返回不表示补偿完成 |
 | `message.undecryptable` | P2P E2EE 解密失败 |
 | `group.message_created` | 收到群消息 |
+| `group.message_batch` | 群消息/撤回批次，items 保留原 `group.message_created` / `group.message_recalled` |
 | `group.changed` | 群组事件 |
+| `group.event_batch` | 群事件批次，items 保留原 `group.changed` |
 | `group.message_recalled` | 群消息撤回 |
 | `group.message_undecryptable` | 群 E2EE 解密失败 |
 | `sync.started` / `sync.progress` / `sync.stopped` | Pull 同步生命周期 |
@@ -768,13 +924,15 @@ sub.unsubscribe()
 | `push.offline_message` | Push Server 收到离线唤醒批次；普通终端无需订阅 |
 | `storage.object_changed` | Storage 对象变更事件透传 |
 
-服务端不产生 `message.ack` 通知；SDK 保留的透传订阅不能作为可依赖的 ACK 或对端已读事件。已读事件只向 owner AID 分发且不进入 Pull 队列；重连查询补偿不受消息 `background_sync=false` 影响。身份切换按代际隔离旧缓存与补偿完成事件，A→B→A 也不能接收旧代际结果；原在途 RPC 仍可返回。详见 [跨设备已读未读 SDK 集成指南](../跨设备已读未读SDK集成指南.md)。
+`message.ack` 通知与应用业务已读独立。peer ACK 通知携带 `cursor_scope="peer"`、`sender_aid`、`peer_ack_seq`，不能代替本地交付证明或推进旧 global 游标。`message.peers_snapshot` 包含待拉对端、水位、可选 `next_pending_seq` 与整体 `pending_count_estimate`，列表保持响应原顺序，调度只重排内部副本；next_pending_seq只作尽力调度提示，不推进游标或证明完成；取消每 peer/整体三项精确数量；估计仅透传、不求和/缺省填 0，排除 volatile，不用于同步完成或调度；Pull 最终返回页保留含本页 volatile 的三项页内计数；它通过应用事件队列发布，不等待 handler 才继续 Pull，完整字段见 [Message RPC](09-message-rpc-manual.md#messagepeers_snapshot)。已读事件只向 owner AID 分发且不进入 Pull 队列；重连查询补偿不受消息 `background_sync=false` 影响。身份切换按代际隔离旧缓存与补偿完成事件；已排队的 raw/public `read_changed` 与 `read_state_sync` 在出队和每个处理器执行前重新核对身份代际，处理器等待期间切换身份也会停止后续交付，A→B→A 同样隔离；原在途 RPC 仍可返回。详见 [跨设备已读未读 SDK 集成指南](../跨设备已读未读SDK集成指南.md)。
 
 `message.received` 的应用层消息保留 `sender_device_id`，表示发送方设备；需要只回复原设备时，将该值作为下一次 `message.send.device_id`。volatile 消息还保留 `storage="volatile"`、`volatile_cursor`、`created_at`、`expires_at`，不含持久 `seq`；内部 slot 不会暴露给应用。
 
+三类批量事件统一为 `{namespace,items:[{event,payload}],source}`。每个实际页固定 batch 模式与 batch handlers：订阅该类 batch 时只发 batch，否则完整沿用原逐条发布路径；single listeners 仍动态查找，没有 single 订阅也不跳过原处理链，不双发。批次不跨页或 namespace，空 items 不发布，Push/inline 单条使用单元素批次；保留原 event/payload、页内顺序和 need_render=false。全部所需 handler 成功后才进入各类型原页提交/ACK 路径，失败保留重试责任；Go 可用 `OnBatch(event, func(any) error)`，返回 error 阻止成功确认，原 `On` 保持兼容。详见 [SDK 批量消息事件](09-message-rpc-manual.md#sdk-批量消息事件)。
+
 ### delivery.changed
 
-`delivery.changed` 是 Python、Go、JavaScript 和 TypeScript SDK 统一提供的本地事件，用于通知应用层一批消息已经完成交付，可以从业务仓库刷新相关会话 UI。它不替代 `message.received` / `group.message_created`：应用仍应逐条处理和持久化原消息事件，再把 `delivery.changed` 作为批量刷新信号。
+`delivery.changed` 是 Python、Go、JavaScript 和 TypeScript SDK 统一提供的本地事件，用于通知应用层一批消息已经完成交付，可以从业务仓库刷新相关会话 UI。它不替代消息明细交付：应用通过已订阅的批量事件或原逐条事件完成业务幂等与持久化，再把 `delivery.changed` 作为批量刷新信号。
 
 该事件由 SDK 本地 dispatcher 发布，不是 Gateway 推送事件，不属于 JSON-RPC `event/...` 协议；裸 WebSocket 客户端不会收到它。
 
@@ -794,7 +952,7 @@ sub.unsubscribe()
 |------|------|------|
 | `trigger` | string | `pull_drained`、`push` 或 `inline_push` |
 | `changes` | array | 本次刷新涉及的 namespace，按 `namespace` 稳定排序且不重复 |
-| `changes[].namespace` | string | P2P 固定为 `p2p`；群消息为 `group:<canonical-group-aid>` |
+| `changes[].namespace` | string | P2P 仍聚合为逻辑名称 `p2p`，不是内部 peer Pull namespace；群消息为 `group:<canonical-group-aid>` |
 | `changes[].delivered_count` | integer | 本次合并窗口内已发布到应用层的原消息事件数；不是未读数、服务端页大小或最大 seq |
 
 触发与折叠规则：
@@ -804,7 +962,7 @@ sub.unsubscribe()
 - 有效的 `push` / `inline_push` 可以原子吸收尚未通知的 Pull 变更；这些变更不会在后续 `pull_drained` 中再次通知。
 - 空 Pull、重复或过滤消息、非法 payload、解密失败，以及未带来有效消息交付的 Head 通知，不发布 `delivery.changed`。
 
-`delivery.changed` 只表示 UI 刷新时机，不是消息明细或持久化账本。应用仓库仍应按照原消息事件的 `(namespace, message_id)` 做幂等，并按 `seq` 排序。
+`delivery.changed` 只表示 UI 刷新时机，不是消息明细或持久化账本。应用仓库仍应按照原消息业务身份幂等，并在对应会话内按 `seq` 排序。
 
 ### 消息来源 `source`
 
@@ -831,7 +989,7 @@ sub.unsubscribe()
     "source": "pull",
     "syncing": true,
     "namespaces_pending": 1,
-    "namespace": "p2p",
+    "namespace": "p2p.peer.v1/YWxpY2UuYWdlbnRpZC5wdWI",
     "received_total": 0,
     "started_at": 1730000000000
 }
@@ -843,7 +1001,7 @@ sub.unsubscribe()
 {
     "run_id": 7,
     "source": "pull",
-    "namespace": "p2p",
+    "namespace": "p2p.peer.v1/YWxpY2UuYWdlbnRpZC5wdWI",
     "page": 2,
     "page_raw_count": 50,
     "page_pulled_count": 48,
@@ -888,6 +1046,8 @@ JavaScript 浏览器 SDK 的 Worker 是网络隔离增强：`new Worker()` 同
 |------|------|----------|
 | 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.history` / `message.ack` / `message.read` / `message.read_state` / `message.thought.*` |
 | 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.pull` / `group.history` / `group.read` / `group.read_state` / `group.v2.*` / `group.fs.*` |
+| 凭证 | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | `credential.register` / `credential.revoke` / `credential.status` / `credential.revocationList` |
+| 组织 | [组织服务 RPC 手册](09-组织服务RPC手册.md) | `org.lifecycle.*` / `org.member.*` / `org.credential.*` / `org.audit.query` / `org.authz.check`；内部及未实现方法见手册 |
 | 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.fs.*` / `storage.volume.*` / ACL / token / share link |
 | 协作 | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) | `collab.ls-files` / `collab.show` / `collab.commit` / `collab.merge` / `collab.log` / `collab.diff` / `collab.clone` / `collab.prune` / `collab.gc` / `collab.reflog` / `collab.revert` / `collab.tag.*` / `collab.ls-remote` / `collab.unregister` |
 | 元信息 | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | `meta.ping` / `meta.status` / `meta.trust_roots` |

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

@@ -16,7 +16,7 @@ async def ensure_ready(aid: str) -> AUNClient:
         loaded = store.load(aid)
 
     me = loaded["data"]["aid"]
-    client = AUNClient(me)
+    client = AUNClient(me)
     await client.connect({"slot_id": "main", "auto_reconnect": True})
     return client
 ```
@@ -65,7 +65,7 @@ async def close_all(*clients: AUNClient):
 sender.e2ee.invalidate_prekey_cache(peer_aid=receiver_aid)
 receiver.e2ee.invalidate_prekey_cache(peer_aid=sender_aid)
 
-cursor = await receiver.call("message.pull", {"after_seq": 0, "limit": 1})
+cursor = await receiver.call("message.pull", {"sender_aid": sender_aid, "after_seq": 0, "limit": 1})
 recv_cursor = cursor.get("latest_seq", 0)
 ```
 
@@ -78,62 +78,63 @@ recv_cursor = cursor.get("latest_seq", 0)
 实例级 `protected_headers` 适合放 SDK 版本、运行环境、调用方链路标识等需要签名保护的元数据：
 
 ```python
-client = AUNClient(me)
-client.set_protected_headers({"sdk": "python", "trace": "abc"})
+client = AUNClient(me)
+client.set_protected_headers({"sdk": "python", "trace": "abc"})
 ```
 
 只对 `message.send`、`group.send`、`message.thought.put`、`group.thought.put` 生效。
 
 ---
 
-## 6. Flow Control
-
-SDK 内部自动管理 RPC 并发，应用层无需配置：
+## 6. Flow Control
+
+SDK 内部自动管理 RPC 并发，应用层无需配置：
 
 | 机制 | 说明 |
 |------|------|
-| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
-| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
-| Pull Gate | 每个 `AUNClient` 一个客户端级 Gate；P2P Message、Group Message、Group Event Pull 共享该 Gate，始终 single-inflight |
-| 队列优先级 | Tail/History 前台 FIFO 优先于 Forward/Gap Fill 后台 FIFO；Group Event Pull 为后台；同 key 自动折叠 |
-
-Gate 内始终保持单飞；相同 key 的调用共享同一结果，不同 key 按前台优先、队列顺序执行。应用层保持普通 `await client.call(...)` 即可，不应自行实现重复并发控制。
-
----
-
-## 7. 消息同步与历史读取
-
-- V2 Push 只作为服务端 Head 通知。只要本地 H 落后，就先 Tail；Tail 后仍有未扫描 Gap 才执行一页后台 Forward。
-- 不要把回调成功当作 ACK 条件。SDK 按服务端原始页最大 seq 推进 Forward 水位；坏密文通过 `message.undecryptable` / `group.message_undecryptable` 单独处理。
-- 冷启动缺 sender IK 时允许 SDK 最多同步等待 3 秒 bootstrap；同发送端并发请求自动合并。成功后当前消息立即重试解密，失败或超时才 pending，不要在应用层并发重复拉取 IK。
-- SDK 只保证单个 Tail/Forward 响应页内按 seq 升序、同 seq 最多发布一次；A/T/H 只是扫描水位，不是发布账本。
-- 实时消息可能从 Push、Tail、Forward 重复到达，跨页、跨通道都不保证全局回调顺序。全局去重与排序由应用业务仓库负责，不属于 SDK 业务逻辑保证；业务仓库必须按 `(namespace, message_id)` 幂等，并按 seq 排序展示。SDK 进程内折叠只能作为 best-effort 优化。
-- 用 `message.history(before_seq=..., limit=...)` 或 `group.history(group_id=..., before_seq=..., limit=...)` 向左翻页；下一页直接复用响应的 `next_before_seq`。History 不影响实时游标和 ACK。
-- Forward Piggy ACK 保留：有待提交 ACK 时，非满页仍会再拉一页并携带 ACK，拉到空页后停止。
-
----
-
-## 8. 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 的设置，例如 `mention_mode`，仍可直接使用 `setSettings` / `set_settings` / `SetSettings`。
-
----
-
-## 9. 测试数据保护
-
-- 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
-- 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。
-- 需要换身份时使用新的 AID 名称，避免制造不可恢复的 key mismatch。
+| RPC 并发上限 | 全局最多 16 个并发 RPC 请求 |
+| 后台 RPC 限制 | 后台任务额外限制为 8 个 |
+| Pull Gate | 四端均为每个 `AUNClient` 一个客户端级 Gate；P2P Message、Group Message、Group Event Pull 共享，同 namespace 单飞，不同 namespace 最多 4 个并行 |
+| 队列优先级 | Tail/History 前台 FIFO 优先于 Forward/Gap Fill 后台 FIFO；Group Event Pull 为后台；同 key 自动折叠 |
+
+同一 namespace 的 Tail、History、Forward 保持单飞；相同 key 的调用共享同一结果，其余可运行请求按前台优先、队列顺序调度。namespace 划分见 [核心概念](03-核心概念.md#消息实时窗口与历史拉取)。应用层保持普通 `await client.call(...)` 即可，不应自行实现重复并发控制。
+
+---
+
+## 7. 消息同步与历史读取
+
+- P2P 上线/Push 提示由 SDK 查询完整 pending peers 并按 peer 同步；已验证自身 type=human 才自动优先 Tail→Forward，其余直接 Forward。不要用对端 type 决定接收策略，Group 保持原行为。
+- peer A/ACK 只越过已解密并成功交付的消息，覆盖证明不能跳过失败回调；运行中的 server ACK 不替代本地交付。Group 保持原终态规则。
+- 冷启动缺 sender IK 时允许 SDK 最多同步等待 3 秒 bootstrap；同发送端并发请求自动合并。成功后当前消息立即重试解密，失败或超时才 pending，不要在应用层并发重复拉取 IK。
+- 单个 Tail/Forward 响应页内按 seq 升序处理；A/T/H 描述可靠同步进度，SDK 用 50,000 条运行期内存成功记录协调重复交付，不逐条读写持久 receipt。
+- 订阅批量事件时只走 batch，否则完整沿用原单条发布链；全部所需 handler 成功→内存成功标记→可靠页 A/T/H→ACK。内存淘汰、重建 client、崩溃及版本切换后允许重放，应用将消息业务身份去重与副作用放在同一持久事务中。跨 peer 不保证全局回调顺序，volatile 和 Group 维持原去重边界。
+- 用 `message.history(sender_aid=..., before_seq=..., limit=...)` 或 `group.history(group_id=..., before_seq=..., limit=...)` 向左翻页；下一页复用 `next_before_seq`。History 不影响实时游标和 ACK，History/force 返回列表不因内存去重删行。
+- peer Forward 仅按验证通过的覆盖证明及严格 `has_more` 续拉；Group 保持原续页规则。volatile 消息按独立游标及 `volatile_has_more` 续页。正常后页携带已提交水位的 Piggy ACK，末页以独立 ACK 收尾，不会只为 ACK 额外拉取空页。ACK 失败保留待确认水位，供后续 Pull 重试。
+- peer Forward 使用稀疏覆盖证明及严格的持久/volatile `has_more`，不由恰好满页推断；后台 `max_pages` 是工作片预算，达到 100 页后仍有积压会自主续调度。公开无 sender 的 Pull 是全部 pending peer 的聚合，显式游标/force/Tail 必须指定 sender。
+
+---
+
+## 8. 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 的设置，例如 `mention_mode`，仍可直接使用 `setSettings` / `set_settings` / `SetSettings`。
+
+---
+
+## 9. 测试数据保护
+
+- 不要删除 `AIDs/` 下的私钥、证书、seed、数据库或 token 文件。
+- 不要并行跑共享同一身份材料的集成 / E2E / 跨域测试。
+- 需要换身份时使用新的 AID 名称，避免制造不可恢复的 key mismatch。
 
 ---