@agentunion/fastaun-browser 0.5.19 → 0.5.21

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -23,7 +23,7 @@ await client.connect({"slot_id": "main", "auto_reconnect": True})
 
 关键约束：
 
-- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
+- `AIDStore.register(aid)` 只负责生成本地密钥、申请证书并落盘。
 - `AIDStore.load(aid)` 返回 AID 值对象；AID 对象加载后不可变。
 - `AUNClient` 只接收 AID 对象，不接收字符串 AID 或配置字典里的 `aid` 字段。
 - `connect(options)` 内部会按需认证、建立 WebSocket、初始化 E2EE 和后台任务。
@@ -62,12 +62,14 @@ store = AIDStore(
 | `register(aid)` | 注册新 AID，返回 Result |
 | `list()` | 列出本地身份 |
 | `exists(aid)` | HEAD PKI 端点，判断 AID 是否已注册 |
-| `resolve(aid, opts=None)` | 拉取并缓存对端证书；默认同时下载并验签 agent.md，可传 `skip_agent_md=True` 跳过 |
+| `resolve(aid, opts=None)` | 解析身份与 agent.md，返回结构化 frontmatter；自有私钥身份优先本地草稿/缓存，可传 `{"skip_agent_md": True}` 跳过名片，或 `{"ownership": client}` 按需查询并缓存共识和 owner.md |
 | `download_agent_md(aid)` | 下载并验签对端 agent.md |
 | `check_agent_md(aid, ttl_days=1)` | 检查本地缓存与远端 agent.md 状态 |
-| `diagnose(aid)` | 本地和远端一致性诊断 |
-| `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
-
+| `diagnose(aid)` | 本地和远端一致性诊断 |
+| `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
+
+自有私钥身份的 `resolve` 默认优先返回本地草稿或缓存，标记 `verification.status=unverified`、`source.agent_md_fetched=false`；草稿的 `in_sync=false`。需要读取远端权威内容时，显式调用 `download_agent_md` 或 `resolve(..., {"force_refresh": True})`，本地草稿仍保留；失败稿由应用显式重试上传，重连不自动重传。
+
 Result 使用方式：
 
 ```python
@@ -89,65 +91,65 @@ client.load_identity(me)   # standby
 client = AUNClient(me)     # standby
 ```
 
-`load_identity()` 只允许在 `no_identity` 或 `closed` 状态调用；传入对象必须是私钥有效的 AID。
-
+`load_identity()` 只允许在 `no_identity` 或 `closed` 状态调用；传入对象必须是私钥有效的 AID。
+
 ### 显式认证
 
-通常不需要单独调用认证，`connect()` 会自动完成。需要提前完成认证或检查认证链路时可调用：
+通常不需要单独调用认证，`connect()` 会自动完成。需要提前完成认证或检查认证链路时可调用：
 
 ```python
 auth = await client.authenticate()
 print(auth["access_token"], auth["gateway"])
 ```
 
-认证成功后状态进入 `authenticated`，随后调用 `connect()` 建立会话。
-
-`authenticate()` 返回的 `access_token` 只是认证完成时的快照。后台刷新会更新 SDK 内部身份状态，但无法更新应用已经保存的字符串，因此不得把首次返回值长期用于 HTTP 请求。
-
-### 读取当前 access token
-
-应用绕过 SDK 门面、自行访问要求 AID Bearer 的 HTTP 数据面时，应在每次请求前同步读取当前缓存：
-
-```python
-token = client.get_access_token()       # str | None
-```
-
-```typescript
-const token = client.getAccessToken();  // string | null
-```
-
-```go
-token := client.GetAccessToken()        // 缺失时为空字符串
-```
-
-这些 getter 只读取后台刷新任务维护的最新缓存，不发起认证、刷新或网络请求，也不独立检查 token 是否临近过期；其有效性依赖客户端连接生命周期和后台刷新任务正常运行。返回空值时应先完成身份加载和认证/连接，不得发送空 Bearer。应用不得跨请求长期保存 getter 的返回值；具体的数据面票据、跨域凭据和重试规则见 [Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程)。
+认证成功后状态进入 `authenticated`，随后调用 `connect()` 建立会话。
+
+`authenticate()` 返回的 `access_token` 只是认证完成时的快照。后台刷新会更新 SDK 内部身份状态，但无法更新应用已经保存的字符串，因此不得把首次返回值长期用于 HTTP 请求。
+
+### 读取当前 access token
+
+应用绕过 SDK 门面、自行访问要求 AID Bearer 的 HTTP 数据面时，应在每次请求前同步读取当前缓存：
+
+```python
+token = client.get_access_token()       # str | None
+```
+
+```typescript
+const token = client.getAccessToken();  // string | null
+```
+
+```go
+token := client.GetAccessToken()        // 缺失时为空字符串
+```
+
+这些 getter 只读取后台刷新任务维护的最新缓存，不发起认证、刷新或网络请求，也不独立检查 token 是否临近过期；其有效性依赖客户端连接生命周期和后台刷新任务正常运行。返回空值时应先完成身份加载和认证/连接，不得发送空 Bearer。应用不得跨请求长期保存 getter 的返回值；具体的数据面票据、跨域凭据和重试规则见 [Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程)。
 
 ### 连接
 
 ```python
-await client.connect({
-    "connection_kind": "long",
-    "auto_reconnect": True,
-    "push_notify_aid": "push.example.com",
-    "push_token": "opaque-token",
-})
+await client.connect({
+    "connection_kind": "long",
+    "auto_reconnect": True,
+    "push_notify_aid": "push.example.com",
+    "push_token": "opaque-token",
+})
 ```
 
 | 选项 | 说明 |
 |------|------|
-| `connection_kind` | `"long"` 或 `"short"` |
-| `short_ttl_ms` | 短连接服务端兜底超时 |
-| `delivery_mode` | 连接级投递语义 |
-| `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
-| `background_sync` | 连接成功后是否执行消息后台补洞 / 未读同步，默认开启；不关闭已读状态查询补偿 |
-| `auto_reconnect` | 断线后是否自动重连 |
-| `heartbeat_interval` | 心跳间隔，秒 |
-| `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
-| `connect_timeout` / `call_timeout` | 连接和 RPC 超时，秒 |
-| `push_notify_aid` / `push_token` | Python SDK 推荐的离线推送登记入口；必须同时提供 |
-| `push_provider` / `push_app_id` | Python SDK 可选诊断字段 |
-
-`slot_id` 来自已加载的 AID，不是 `connect()` 选项。Python SDK 在 AUN 会话建立后把 `push_notify_aid` 映射为冻结 RPC 字段 `push_server_aid`，调用 `push.register` 登记当前 `(aid, device_id, slot_id)`；这些字段不会进入 `auth.connect`。登记失败时本次连接回滚并向调用方抛错。Go、TypeScript、JavaScript SDK 本轮未增加该便利入口。
+| `connection_kind` | `"long"` 或 `"short"` |
+| `short_ttl_ms` | 短连接服务端兜底超时 |
+| `delivery_mode` | 连接级投递语义 |
+| `extra_info` | 应用层自定义连接信息；下划线开头的键不会透传给 Gateway |
+| `background_sync` | 连接成功后是否执行消息后台补洞 / 未读同步，默认开启；不关闭已读状态查询补偿 |
+| `auto_reconnect` | 断线后是否自动重连 |
+| `heartbeat_interval` | 心跳间隔，秒 |
+| `retry.initial_delay` / `retry.max_delay` | 退避重连参数 |
+| `connect_timeout` / `call_timeout` | 连接和 RPC 超时，秒 |
+| `push_notify_aid` / `push_token` | Python SDK 推荐的离线推送登记入口；必须同时提供 |
+| `push_provider` / `push_app_id` | Python SDK 可选诊断字段 |
+
+`slot_id` 来自已加载的 AID，不是 `connect()` 选项。Python SDK 在 AUN 会话建立后把 `push_notify_aid` 映射为冻结 RPC 字段 `push_server_aid`，调用 `push.register` 登记当前 `(aid, device_id, slot_id)`；这些字段不会进入 `auth.connect`。登记失败时本次连接回滚并向调用方抛错。Go、TypeScript、JavaScript SDK 本轮未增加该便利入口。
 
 当前稳定实现为 Gateway 模式；Peer / Relay 仍是协议能力定义，SDK 连接层会明确返回未实现。
 
@@ -160,16 +162,16 @@ await client.connect({
 长连接：
 
 ```python
-daemon = AUNClient(me)
-await daemon.connect({"connection_kind": "long"})
+daemon = AUNClient(me)
+await daemon.connect({"connection_kind": "long"})
 daemon.on("message.received", lambda e: print(e["payload"]))
 ```
 
 短连接：
 
 ```python
-cli = AUNClient(me)
-await cli.connect({"connection_kind": "short", "short_ttl_ms": 30000})
+cli = AUNClient(me)
+await cli.connect({"connection_kind": "short", "short_ttl_ms": 30000})
 await cli.call("message.send", {"to": peer, "payload": {"type": "text", "text": "hello"}})
 await cli.close()
 ```
@@ -206,19 +208,19 @@ print(client.can_connect, client.can_send, client.is_online)
 | `connection.error` | 连接、认证、重连错误 |
 | `token.refreshed` | token 自动刷新完成 |
 | `token.refresh_exhausted` | refresh_token 缺失、过期或刷新链耗尽，SDK 已清理本地 token，下一次重连会重新走完整登录 |
-| `message.received` | 收到消息 |
-| `group.changed` | 群组事件 |
-| `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
-| `delivery.changed` | SDK 本地批量交付完成通知，用于合并 UI 刷新（完整契约见 [06-API手册](06-API手册.md#deliverychanged)） |
-| `read_state_sync` | SDK 本地已读状态补偿完成，含本轮 `owner_aid`、`states` 和逐项 `errors`；连接返回不代表补偿完成 |
-
-建议在 `connect()` 前注册事件处理器。`read_state_sync` 只交付本轮成功查询涉及的去重状态及逐项错误，空查询不夹带旧缓存。AID/device 切换按身份代际隔离缓存、登记及补偿完成事件，A→B→A 也不能接受旧代际结果；原在途 RPC 仍可返回。
+| `message.received` | 收到消息 |
+| `group.changed` | 群组事件 |
+| `message.undecryptable` / `group.message_undecryptable` | E2EE 解密失败 |
+| `delivery.changed` | SDK 本地批量交付完成通知，用于合并 UI 刷新（完整契约见 [06-API手册](06-API手册.md#deliverychanged)） |
+| `read_state_sync` | SDK 本地已读状态补偿完成，含本轮 `owner_aid`、`states` 和逐项 `errors`；连接返回不代表补偿完成 |
+
+建议在 `connect()` 前注册事件处理器。`read_state_sync` 只交付本轮成功查询涉及的去重状态及逐项错误，空查询不夹带旧缓存。AID/device 切换按身份代际隔离缓存、登记及补偿完成事件，A→B→A 也不能接受旧代际结果；原在途 RPC 仍可返回。
 
 ---
 
 ## Agent Web / agent.md
 
-以下普通主体示例以本 AID 签名和 token 上传。Group/Org 使用专属 owner 生命周期：owner 与 entity_cert_fingerprint 必填、可无 ownership；仅当前 owner 用本人证书和私钥尾签（signer_aid=owner）并携带 V2 owner 授权，实体自身 token 不授予名片上传权。上传与恢复新鲜核对 owner/状态及实体证书代际，格式见 [Ownership 协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传)。
+以下普通主体示例以本 AID 主签和 token 上传。Group/Org 名片由实体私钥生成主签，当前 owner 以本人 token 上传，无需实体登录；可选 owner 附签，存在就必须验全部块。Group 旧实体单签及实体身份上传始终兼容，Org 不开放该旧入口。取消实体额外 V2 上传授权，保留当前 owner、生命周期、实体证书代际与 CAS 检查，见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。
 
 发布自己的 agent.md：
 
@@ -226,16 +228,19 @@ print(client.can_connect, client.can_send, client.is_online)
 uploaded = await store.upload_agent_md("alice.agentid.pub", content)
 ```
 
-`aid` 必须是本地 AID。上传由 `AIDStore` 读取本地私钥签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
-
+`aid` 必须是本地 AID。上传由 `AIDStore` 读取本地私钥签名，并通过 `AuthFlow` 获取或复用该 AID 的 access_token。
+
 解析对端并验签 agent.md：
 
 ```python
 resolved = await store.resolve("bob.agentid.pub")
 if resolved["ok"]:
+    print(resolved["data"]["agent_md"]["frontmatter"].get("name"))
     print(resolved["data"]["agent_md"]["verification"]["status"])
 ```
 
+frontmatter 保留原文的标准字段、扩展字段及其类型，历史名片缺字段不补默认值。需要 ownership 时传入已有 client：`await store.resolve("bob.agentid.pub", {"ownership": client})`，读取 `data.ownership.status`；复用既有双文件共识校验，默认缓存 60 秒，包含读取到的 owner.md 原文。`ownership_ttl_ms=0` 禁止复用，`force_refresh=True` 同时绕过共识缓存；缓存不用于授权。完整 opts、字段、状态及四语言差异见 [resolve 输入与输出](06-API手册.md#resolve-输入与输出)。
+
 只下载对端 agent.md：
 
 ```python
@@ -248,11 +253,13 @@ downloaded = await store.download_agent_md("bob.agentid.pub")
 state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
 ```
 
+新 SDK 全部 NS GET/HEAD/PUT（含 fresh）携带 `X-AUN-Signature-Format: multi-v1` 获取完整多签；实体 fresh GET 必须同时携带 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`、`X-AUN-Signature-Format: multi-v1`；NS 仅凭 Check 头绕过 LRU 并新鲜验证全部签块，仍返回 not_applicable，不进入通用 Ownership 账本。无头客户端读取首签投影，表示 ETag 与完整存储 CAS 的映射见 [协议 §3.3](../protocol/Ownership协议定义2.1.md#33-读取并发与接口)。
+
 当前公开入口分工固定：
 
 | 主体 | 公开能力 |
 |------|----------|
-| `AIDStore` | `upload_agent_md(aid, content=None)`、`download_agent_md(aid)`、`check_agent_md(aid, ttl_days=1)`、`resolve(aid, opts)` |
+| `AIDStore` | `sign/verify` 通用 raw/document 签验、`upload_agent_md(aid, content=None)`、`download_agent_md(aid)`、`check_agent_md(aid, ttl_days=1)`、`resolve(aid, opts)` |
 | `AID` | `sign_agent_md(content)`、`verify_agent_md(content)` 低层签验能力 |
 | `AUNClient` | 连接、事件和 RPC 调用；不再暴露 agent.md 上传入口 |
 

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

@@ -41,20 +41,22 @@ await client.call("message.send", {
 })
 ```
 
-当前 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` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
-
-接收端校验签名需要发送方 IK。若本地 session 和 PKI 证书都没有目标 sender/device 的 IK，Python、TypeScript、Go、JavaScript SDK 会先给当前消息一次有界同步补救机会：同一发送端的并发请求通过 single-flight 合并，最多阻塞 3 秒调用 `message.v2.bootstrap`；群消息仍未命中时再调用 `group.v2.bootstrap`。获取成功后立即重试当前消息解密；获取失败或超时才进入原有 pending 后台重试，History 则返回结构化解密失败项而不进入实时 pending。该补救会增加少量首条消息延迟，但避免冷启动时“消息已 ACK、IK 稍后才到、当前消息无回调”。
-
-同步获取失败意味着当前时点仍不具备验签和解密条件，SDK 不伪造明文，也不因永久坏密文阻塞 Forward/Tail 水位。实时消息通过 `message.undecryptable` / `group.message_undecryptable` 暴露诊断；应用仍需按 `message_id` 幂等处理后续 pending 重试可能产生的补交付。
-
-## ProtectedHeaders 与可验证上下文
+当前 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` 信封作为默认发送格式。旧术语只用于历史兼容文档或迁移排查。
+
+接收端校验签名需要发送方 IK。若本地 session 和 PKI 证书都没有目标 sender/device 的 IK，Python、TypeScript、Go、JavaScript SDK 会先给当前消息一次有界同步补救机会：同一发送端的并发请求通过 single-flight 合并，最多阻塞 3 秒调用 `message.v2.bootstrap`；群消息仍未命中时再调用 `group.v2.bootstrap`。获取成功后立即重试当前消息解密；获取失败或超时才进入原有 pending 后台重试，History 则返回结构化解密失败项而不进入实时 pending。该补救会增加少量首条消息延迟，但避免冷启动时“消息已 ACK、IK 稍后才到、当前消息无回调”。
+
+同步获取失败意味着当前时点仍不具备验签和解密条件，SDK 不伪造明文。P2P peer 路径不能仅凭扫描证明越过未成功解密或交付的消息，永久坏密文同样不推进该处 A/ACK；Group 保持原有终态规则。实时消息通过 `message.undecryptable` / `group.message_undecryptable` 暴露诊断；应用仍需按消息业务身份幂等处理后续 pending 重试可能产生的补交付。
+
+## ProtectedHeaders 与可验证上下文
+
+`message.send` / `group.send` 的可选 `need_render` 默认 `true`，由 SDK 提取到外层信封；缺字段及历史 NULL 也按 `true`。它是展示/统计提示，不进入 AAD、`protected_headers`、消息保护签名或元数据 HMAC。RPC `client_signature` 仍按既有完整业务参数规则覆盖它，不能因为不进 AAD 就从 RPC canonical 中排除。
 
 `protected_headers` 是 E2EE 信封里的可选元数据字典，语义接近 HTTP headers：适合放 `device_id`、`slot_id`、`device_name`、`os`、`sdk_version`、`app_name` 等需要被接收端识别、且需要防篡改的非业务内容。`payload` 仍然类似 HTTP body，业务内容应放在 `payload` 内。
 
@@ -69,11 +71,11 @@ await client.call("message.send", {
 
 `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。
-
-`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 签名验证作为可信依据。
-
-示例：
+`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
@@ -109,8 +111,8 @@ await client.call("group.send", {
 
 ```json
 {
-  "type": "e2ee.p2p_encrypted",
-  "version": "v2",
+  "type": "e2ee.p2p_encrypted",
+  "version": "v2",
   "ciphertext": "...",
   "protected_headers": {
     "device_id": "dev-123",
@@ -134,8 +136,8 @@ await client.call("group.send", {
 
 计算规则：
 
-1. 解密流程会得到本条消息的 `master_key`。
-2. `metadata_key = HMAC-SHA256(master_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`。
@@ -292,7 +294,7 @@ client.on("message.received", handler)
 `message.pull` 返回的消息已自动解密：
 
 ```python
-result = await client.call("message.pull", {"after_seq": 0, "limit": 50})
+result = await client.call("message.pull", {"sender_aid": "alice.agentid.pub", "limit": 200})
 for msg in result["messages"]:
     if msg.get("encrypted"):
         print(f"加密消息: {msg['payload']}")
@@ -301,20 +303,21 @@ for msg in result["messages"]:
 
 ---
 
-## 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 毫秒。
+## 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；P2P 定向设备未命中缓存时的单次新鲜重试与失败边界见 [message.send](09-message-rpc-manual.md#messagesend)。
+- 旧 SPK 会在本地保留一段安全窗口，用于解密引用旧 SPK 的历史消息；满足已消费和保留窗口条件后才销毁。
+- peer 拉取保留原 seq 与历史密文，不更改 AAD。peer ACK 和 slot 级 `legacy_safe_ack_seq` 不是设备全部消费 slot 的安全证明；当前实现可省略 `device_safe_ack_seq`，SDK 不据前两者销毁旧 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 毫秒。
 
 ---
 
@@ -364,7 +367,7 @@ client = AUNClient(aid)
 | P2P 消息默认要求发送方签名 | 无 `sender_signature` 的消息被拒绝 |
 | 群组消息默认要求发送方签名 | `require_signature=True`，无签名或无发送方证书的消息被拒绝 |
 | 群组 E2EE 为固定启用能力 | `group_e2ee=true`，不可关闭 |
-| 默认要求前向保密 | V2 优先使用设备 SPK 的 `3DH` wrap；缺少 SPK 的 `1DH` 路径仅作为兼容降级 |
-| 客户端操作签名 | SDK 会为关键操作附加 `client_signature`；Gateway 对 `send/pull/ack` 等常规 RPC 优先使用连接级身份认证，只有身份声明与连接不一致、敏感操作、能力身份或主动携签场景才执行 ECDSA 验签 |
+| 默认要求前向保密 | V2 优先使用设备 SPK 的 `3DH` wrap；缺少 SPK 的 `1DH` 路径仅作为兼容降级 |
+| 客户端操作签名 | SDK 会为关键操作附加 `client_signature`；Gateway 对 `send/pull/ack` 等常规 RPC 优先使用连接级身份认证，只有身份声明与连接不一致、敏感操作、能力身份或主动携签场景才执行 ECDSA 验签 |