@agentunion/fastaun-browser 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -6,6 +6,25 @@
 
 ---
 
+## 0.3.3 — 2026-05-25
+
+### Added
+- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
+- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
+- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
+- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
+- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
+
+### Changed
+- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
+- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
+
+### Fixed
+- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
+- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
+
+---
+
 ## 0.3.1 — 2026-05-22
 
 ### Added

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,25 @@
 
 ---
 
+## 0.3.3 — 2026-05-25
+
+### Added
+- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
+- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
+- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
+- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
+- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
+
+### Changed
+- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
+- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
+
+### Fixed
+- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
+- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
+
+---
+
 ## 0.3.1 — 2026-05-22
 
 ### Added

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

@@ -204,28 +204,32 @@ Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
 
 ### 推荐主 API（自 v0.x 起）
 
-SDK 在 `AUNClient` 上提供两个一站式主方法，封装了"读文件/内容 → 签名 → 上传 → 刷新 etag"和"下载 → 自动验签 → 可选写盘"两条主线：
+SDK 在 `AUNClient` 上提供三个一站式主方法，分别封装"发布"、"下载"、"一致性检查"三条主线。文件统一存放在 `{aun_path}/AgentMDs/{aid}/agent.md`，由 SDK 管理；元数据持久化到 `agent_md_cache` 表 / `list.json`。
 
 ```python
-# 发布自己的 agent.md（读文件 → 签名 → 上传 → 刷新内部 etag）
-await client.publish_agent_md("/path/to/agent.md")
+# 发布自己的 agent.md（读 SDK 管理的本地文件 → 签名 → 上传 → 刷新内部 etag）
+await client.publish_agent_md()
 
-# 下载并自动验签别人的 agent.md（aid 缺省取自身 AID）
-info = await client.fetch_agent_md("bob.agentid.pub", save_path="./bob.md")
-print(info["signature"]["status"], info["in_sync"])
+# 检查本地与云端一致性（不主动下载；max_unsynced_days=0 时强制 HEAD）
+state = await client.check_agent_md("bob.agentid.pub", max_unsynced_days=3)
+
+# 下载并自动验签（自动写到 SDK 管理的目录）
+if state["remote_found"] and not state["in_sync"]:
+    info = await client.fetch_agent_md("bob.agentid.pub")
+    print(info["signature"]["status"], info["in_sync"], info["saved_to"])
 ```
 
-详细签名见 `06-API手册.md` 中的 `publish_agent_md` / `fetch_agent_md` 章节。
+详细签名见 `06-API手册.md` 中的 `publish_agent_md` / `fetch_agent_md` / `check_agent_md` 章节。
 
-| SDK | publish | fetch |
-|------|---------|-------|
-| Python | `client.publish_agent_md(path)` | `client.fetch_agent_md(aid, save_path)` |
-| TypeScript（Node） | `client.publishAgentMd(path)` | `client.fetchAgentMd(aid?, savePath?)` |
-| Go | `client.PublishAgentMD(ctx, path)` | `client.FetchAgentMD(ctx, aid, savePath)` |
-| C++ | `client.PublishAgentMd(path, cb)` | `client.FetchAgentMd(aid, save_path, cb)` |
-| JavaScript（浏览器） | `client.publishAgentMd(content)` | `client.fetchAgentMd(aid?)` |
+| SDK | publish | fetch | check |
+|------|---------|-------|-------|
+| Python | `client.publish_agent_md()` | `client.fetch_agent_md(aid?)` | `client.check_agent_md(aid?, max_unsynced_days=0)` |
+| TypeScript（Node） | `client.publishAgentMd()` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
+| Go | `client.PublishAgentMD(ctx)` | `client.FetchAgentMD(ctx, aid)` | `client.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` |
+| C++ | `client.PublishAgentMd(out)` | `client.FetchAgentMd(aid, out)` | `client.CheckAgentMd(aid, max_days, out)` |
+| JavaScript（浏览器） | `client.publishAgentMd(content?)` | `client.fetchAgentMd(aid?)` | `client.checkAgentMd(aid?, maxUnsyncedDays=0)` |
 
-JS 浏览器版本无文件系统，`publish` 接收 markdown 文本（应用层用 `<input type=file>` 等读出），`fetch` 不接受 `savePath`。
+> **`check_agent_md` 不主动下载**：仅当远程存在且本地从未保存过该 aid 时，SDK 才异步触发后台 fetch；其他场景由应用层根据返回值决定是否调 `fetch_agent_md`。
 
 ### Deprecated（保留代码、未来版本将移除）
 
@@ -235,11 +239,40 @@ JS 浏览器版本无文件系统，`publish` 接收 markdown 文本（应用层
 | `client.auth.verify_agent_md` | `client.fetch_agent_md` 内部已包含 |
 | `client.auth.upload_agent_md` | `client.publish_agent_md` |
 | `client.auth.download_agent_md` | `client.fetch_agent_md` |
+| `client.auth.head_agent_md` | `client.check_agent_md`（带缓存窗口） |
 
 底层方法仅推荐用于离线签名 / 纯文本验签等特殊场景。
 
 > v0.x 起删除了 `set_local_agent_md_path` / `get_local_agent_md_etag` / `get_remote_agent_md_etag` 三个 client 端 API；本地 etag 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存。事件 payload 仍会注入 `_agent_md.{local_etag, remote_etag}` 供应用层比对。
 
+### Gateway 多 AID etag 推送（v0.x+）
+
+Gateway 在 RPC response 和事件通知的 `_meta` 中**最多同时注入两个 AID** 的 agent.md 元数据，每个条目都带 `aid` 字段：
+
+- **requester**：调用者 / 事件订阅方（自身）
+- **peer**：RPC 对端 / 事件源（仅当 `peer_aid != requester_aid` 时注入；否则该条目省略）
+
+```json
+{
+  "_meta": {
+    "agent_md_etag": "\"requester-etag\"",
+    "agent_md_etags": {
+      "requester": {"aid": "alice.agentid.pub", "etag": "\"...\"", "last_modified": "..."},
+      "peer":      {"aid": "bob.agentid.pub",   "etag": "\"...\"", "last_modified": "..."}
+    }
+  }
+}
+```
+
+| 场景 | requester | peer |
+|------|-----------|------|
+| RPC response | 调用者 | RPC 涉及的 `to_aid`（不等于调用者时） |
+| 事件通知 | 订阅方 | 事件源（存在且不等于订阅方时） |
+
+`receiver` / `to` / `target` / `sender` / `from` 等键也会同时注入以兼容旧 SDK，但它们指向与 `requester` 或 `peer` 完全相同的对象（不是独立 AID）。**新 SDK 只需读 `requester` 和 `peer` 即可**。
+
+SDK 收到后通过 `_observe_agent_md_meta` 写入 `agent_md_cache` 持久化记录（按 AID 自动去重）；若发现"远程有 etag 但本地从未保存该 aid"，会异步触发后台 fetch（不阻塞 RPC 返回）。
+
 ### 错误返回
 
 - `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）

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

@@ -15,9 +15,10 @@
 - [disconnect()](#await-disconnect---none) - 断开连接（可重连）
 - [list_identities()](#list_identities---listdict) - 列出本地身份
 - [ping()](#await-pingparams-dict--none---any) - 连通性探测
-- [set_local_agent_md_path()](#set_local_agent_md_pathpath-str---str--agentmd-版本一致性) - **已删除**，请改用 `publish_agent_md()` / `fetch_agent_md()`
-- [publish_agent_md()](#await-publish_agent_mdpath-str---dict--agentmd-发布主-api) - 读取本地 agent.md → 签名 → 上传，并刷新内部 etag
-- [fetch_agent_md()](#await-fetch_agent_mdaid-str--none-save_path-str--none---dict--agentmd-下载主-api) - 下载 agent.md → 自动验签 → 可选写盘
+- [set_agent_md_path()](#set_agent_md_pathpath-str--none---str--agentmd-存储目录设置) - 设置 agent.md 本地存储根目录
+- [publish_agent_md()](#await-publish_agent_md---dict--agentmd-发布主-api) - 读取本地 agent.md → 签名 → 上传，并刷新内部 etag
+- [fetch_agent_md()](#await-fetch_agent_mdaid-str--none---dict--agentmd-下载主-api) - 下载 agent.md → 自动验签 → 持久化到 SDK 管理的目录
+- [check_agent_md()](#await-check_agent_mdaid-str--none-max_unsynced_days-float--0---dict--agentmd-本地云端一致性检查) - 检查本地 agent.md 是否与云端一致（带缓存窗口）
 - [status()](#await-statusparams-dict--none---any) - 网关状态查询
 - [check_gateway_health()](#await-check_gateway_healthgateway_url-str-timeout-float--50---bool) - 检查网关可用性
 
@@ -397,50 +398,103 @@ for item in identities:
 
 ---
 
-### `await publish_agent_md(path: str) -> dict` — agent.md 发布主 API
+### `set_agent_md_path(path: str | None = None) -> str` — agent.md 存储目录设置
 
-读取本地 `agent.md` 文件 → 调用 `auth.sign_agent_md` 在尾部追加 `<!-- AUN-SIGNATURE -->` 块 → 调用 `auth.upload_agent_md` 上传到服务端，并以**上传字节的 sha256**计算 quoted etag 写入内部 `_local_agent_md_etag`，使后续应用事件 payload 中的 `_agent_md.local_etag` 字段反映服务端实际生效的版本。
+设置 agent.md 本地存储根目录。SDK 的 `publish_agent_md` / `fetch_agent_md` / `check_agent_md` 都基于此目录读写文件和元数据。
+
+- 传入非空路径：切换到指定目录
+- 传入空字符串或 `None`：恢复默认目录 `{aun_path}/AgentMDs`
+- 目录不存在时自动创建
+- 切换后清空内存中的 agent.md 缓存（下次操作会重新从磁盘/list.json 加载）
 
 **API 跨语言对齐：**
 
 | SDK | 签名 |
 |------|------|
-| Python | `await client.publish_agent_md(path: str) -> dict` |
-| TypeScript（Node） | `await client.publishAgentMd(path: string)` |
-| Go | `client.PublishAgentMD(ctx, path string) (map[string]any, error)` |
-| C++ | `client.PublishAgentMd(path, callback)` |
-| JavaScript（浏览器） | `await client.publishAgentMd(content: string)` — 浏览器无文件系统，接收 markdown 文本 |
+| Python | `client.set_agent_md_path(path=None) -> str` |
+| TypeScript（Node） | `client.setAgentMdPath(root?)` |
+| Go | `client.SetAgentMDPath(root string) string` |
+| C++ | `client.SetAgentMDPath(root) -> std::string` |
+| JavaScript（浏览器） | `client.setAgentMdPath(root?)` |
+
+**返回值：** 实际生效的根目录绝对路径。
+
+**目录结构：**
+
+```
+{agent_md_path}/
+├── list.json                    # 所有 AID 的元数据索引
+├── {aid_1}/
+│   └── agent.md                 # aid_1 的 agent.md 正文
+├── {aid_2}/
+│   └── agent.md
+└── ...
+```
+
+**示例：**
+
+```python
+# 切换到自定义目录
+actual = client.set_agent_md_path("/data/my-agents")
+print(actual)  # "/data/my-agents"
+
+# 恢复默认
+client.set_agent_md_path()  # 回到 {aun_path}/AgentMDs
+```
+
+> **注意：** 此方法应在 `connect()` 之前或 `publish_agent_md()` / `fetch_agent_md()` 之前调用。连接后切换目录不会触发重新下载，但后续的 publish/fetch/check 会使用新目录。
+
+---
+
+### `await publish_agent_md() -> dict` — agent.md 发布主 API
+
+读取 SDK 管理的本地 `agent.md`（路径：`{aun_path}/AgentMDs/{self_aid}/agent.md`）→ 调用 `auth.sign_agent_md` 在尾部追加 `<!-- AUN-SIGNATURE -->` 块 → 调用 `auth.upload_agent_md` 上传到服务端 → 以**上传字节的 sha256**计算 quoted etag 写入内部 `_local_agent_md_etag` 与持久化缓存（`agent_md_cache` 表 / `list.json`），使后续应用事件 payload 中的 `_agent_md.local_etag` 字段反映服务端实际生效的版本。
+
+**API 跨语言对齐：**
+
+| SDK | 签名 |
+|------|------|
+| Python | `await client.publish_agent_md() -> dict` |
+| TypeScript（Node） | `await client.publishAgentMd()` |
+| Go | `client.PublishAgentMD(ctx) (map[string]any, error)` |
+| C++ | `client.PublishAgentMd(out_result)` |
+| JavaScript（浏览器） | `await client.publishAgentMd(content?: string)` |
 
 **返回值：** 透传 `auth.upload_agent_md` 的返回，含 `aid` / `etag` / `last_modified` / `agent_md_url` / `bytes`。
 
+**副作用：**
+- 更新内存中的 `_local_agent_md_etag`，等于上传字节的 quoted sha256
+- 若服务端返回 `etag` 字段，同步更新内存中的 `_remote_agent_md_etag`
+- 把 `content` / `local_etag` / `remote_etag` / `last_modified` / `fetched_at` / `remote_status="found"` 写入 `agent_md_cache` 持久化记录
+- 把签名后的内容原子写回本地文件（含 `<!-- AUN-SIGNATURE -->` 块）
+
 **异常：**
-- `ValidationError`：path / content 为空
-- `FileNotFoundError`（其它语言对应）：文件不存在
-- `StateError`：尚未持有本地身份
+- `ValidationError`：未持有本地身份 / 本地 agent.md 文件不存在或为空
+- `StateError`：SDK 未连接
 - `AUNError`：上传失败
 
 **示例：**
 
 ```python
-result = await client.publish_agent_md("/path/to/agent.md")
-print(result["agent_md_url"])
+result = await client.publish_agent_md()
+print(result["agent_md_url"], result["etag"])
 ```
 
 ---
 
-### `await fetch_agent_md(aid: str | None = None, save_path: str | None = None) -> dict` — agent.md 下载主 API
+### `await fetch_agent_md(aid: str | None = None) -> dict` — agent.md 下载主 API
 
-下载指定 AID 的 `agent.md`，自动调用 `auth.verify_agent_md` 验签；`aid` 缺省取本地身份；可选 `save_path` 写盘；若目标 aid 是自己则同步刷新内部 `_local_agent_md_etag` 并计算 `in_sync`。
+下载指定 AID 的 `agent.md`，自动调用 `auth.verify_agent_md` 验签；`aid` 缺省取本地身份；下载结果**固定保存**到 `{aun_path}/AgentMDs/{aid}/agent.md`，并同步更新持久化缓存（`agent_md_cache` 表 / `list.json`）。若目标 aid 是自己则刷新内部 `_local_agent_md_etag` 并计算 `in_sync`。
 
 **API 跨语言对齐：**
 
 | SDK | 签名 |
 |------|------|
-| Python | `await client.fetch_agent_md(aid=None, save_path=None) -> dict` |
-| TypeScript（Node） | `await client.fetchAgentMd(aid?, savePath?)` |
-| Go | `client.FetchAgentMD(ctx, aid string, savePath string) (*AgentMDInfo, error)` |
-| C++ | `client.FetchAgentMd(aid, save_path, callback)` |
-| JavaScript（浏览器） | `await client.fetchAgentMd(aid?)` — 无 savePath（浏览器无文件系统） |
+| Python | `await client.fetch_agent_md(aid=None) -> dict` |
+| TypeScript（Node） | `await client.fetchAgentMd(aid?)` |
+| Go | `client.FetchAgentMD(ctx, aid string) (*AgentMDInfo, error)` |
+| C++ | `client.FetchAgentMd(aid, out_info)` |
+| JavaScript（浏览器） | `await client.fetchAgentMd(aid?)` |
 
 **返回字段：**
 
@@ -450,25 +504,92 @@ print(result["agent_md_url"])
 | `content` | `str` | agent.md 完整文本 |
 | `signature` | `dict` | `auth.verify_agent_md` 的返回（status / verified / reason / cert_fingerprint / timestamp） |
 | `in_sync` | `bool \| None` | 仅当 aid 是自己时给出：本地 etag == 服务端 etag；否则为 `null` |
-| `saved_to` | `str \| None` | 若传了 save_path 且写盘成功，返回路径；其他情况为 `null`（JS 浏览器版无此字段） |
-| `save_error` | `str \| None` | 写盘失败原因；不影响下载成功（JS 浏览器版无此字段） |
+| `saved_to` | `str \| None` | 实际写入路径（`{aun_path}/AgentMDs/{aid}/agent.md`）；浏览器 SDK 无此字段 |
+| `save_error` | `str \| None` | 写盘失败原因；不影响下载成功；浏览器 SDK 无此字段 |
+
+**副作用：**
+- 把 `content` / `local_etag = sha256(content)` / `remote_etag` / `last_modified` / `fetched_at` / `remote_status="found"` / `verify_status` / `verify_error` 写入 `agent_md_cache` 持久化记录
+- 若 `aid == self_aid`：刷新 `_local_agent_md_etag` 并比对 `_remote_agent_md_etag` 计算 `in_sync`
 
 **异常：**
 - `ValidationError`：未传 aid 且本地无身份
 - `NotFoundError`：服务端 404
 - `AUNError`：其他 HTTP 错误
 
-**etag 缓存：** 内部沿用 `auth.download_agent_md` 的 If-None-Match / 304 缓存机制；命中 304 时返回上次缓存的内容。
+**调用建议：** 通常先调 `check_agent_md` 检查状态，仅当 `local_found=False` 且 `remote_found=True` 或用户明确要更新本地版本时才调 `fetch_agent_md`。SDK 不会因为 `_observe_rpc_meta` 收到新 etag 而主动下载（除非本地从未保存过该 aid 的内容）。
 
 **示例：**
 
 ```python
 # 拉自己的 agent.md，并判断是否与服务端同步
 info = await client.fetch_agent_md()
-print(info["signature"]["status"], info["in_sync"])
+print(info["signature"]["status"], info["in_sync"], info["saved_to"])
 
-# 拉别人的 agent.md，并存到本地路径
-info = await client.fetch_agent_md("bob.agentid.pub", save_path="./bob.md")
+# 拉别人的 agent.md（自动写到 {aun_path}/AgentMDs/bob.agentid.pub/agent.md）
+info = await client.fetch_agent_md("bob.agentid.pub")
+```
+
+---
+
+### `await check_agent_md(aid: str | None = None, max_unsynced_days: float = 0) -> dict` — agent.md 本地/云端一致性检查
+
+检查指定 AID 的 agent.md 在本地和服务端的状态，**不主动下载**（除非远程存在而本地从未保存过——由 `_observe_rpc_meta` 异步触发的延迟下载除外）。返回值包含本地是否存在、是否与云端一致、验签状态、是否走了 HEAD 等信息，由应用层根据返回值决定是否调 `fetch_agent_md`。
+
+**API 跨语言对齐：**
+
+| SDK | 签名 |
+|------|------|
+| Python | `await client.check_agent_md(aid=None, max_unsynced_days: float = 0) -> dict` |
+| TypeScript（Node） | `await client.checkAgentMd(aid?, maxUnsyncedDays = 0)` |
+| Go | `client.CheckAgentMD(ctx, aid string, maxUnsyncedDays ...float64) (*AgentMDCheckResult, error)` |
+| C++ | `client.CheckAgentMd(aid, out_result)` 或 `client.CheckAgentMd(aid, max_unsynced_days, out_result)` |
+| JavaScript（浏览器） | `await client.checkAgentMd(aid?, maxUnsyncedDays = 0)` |
+
+**`max_unsynced_days` 语义：**
+
+- `= 0`（默认）：每次都强制 HEAD 服务端确认 etag/last_modified
+- `> 0`：若距上次 HEAD（`checked_at` 字段）在 N 天内，且本地缓存的 `local_etag == remote_etag`，则直接返回缓存（`cached=true`），跳过 HEAD；否则仍走 HEAD
+
+> **重要：** N 天的窗口基于 SDK 上次 HEAD 的时间（`checked_at`），不是基于服务端 `Last-Modified`。这样即使 agent.md 长期不变，也会在 N 天后强制重新确认。
+
+**返回字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aid` | `str` | 检查的 AID |
+| `local_found` | `bool` | 本地 `agent_md_cache` 是否有 content 或 local_etag |
+| `remote_found` | `bool` | 服务端是否存在该 AID 的 agent.md |
+| `local_etag` | `str` | 本地缓存的 quoted sha256 etag |
+| `remote_etag` | `str` | 服务端 HEAD 返回的 etag（命中缓存时用缓存值） |
+| `in_sync` | `bool` | `local_etag == remote_etag` 且两者都非空 |
+| `last_modified` | `str` | 服务端 HTTP 日期格式的 Last-Modified |
+| `status` | `int` | HEAD 响应状态码（缓存命中时为 200） |
+| `cached` | `bool` | 是否命中本地窗口缓存（true 时未走 HEAD） |
+| `verify_status` | `str` | 上次 fetch 的验签状态（cached 时复用） |
+| `verify_error` | `str` | 上次 fetch 的验签错误（cached 时复用） |
+
+**副作用：**
+- 走 HEAD 路径时：更新 `agent_md_cache` 的 `remote_etag` / `last_modified` / `checked_at` / `remote_status` 字段
+- 若 aid 是自身且 HEAD 拿到 remote_etag：同步更新内存中的 `_remote_agent_md_etag`
+- 若远程存在但本地从未保存过 → 通过 `_observe_agent_md_meta` 异步调度后台 fetch（不阻塞返回）
+
+**异常：**
+- `ValidationError`：未传 aid 且本地无身份
+- HEAD 网络错误：抛出原始异常（同时把 `last_error` 写入缓存记录）
+
+**典型用法：**
+
+```python
+# 严格模式：每次都确认服务端
+state = await client.check_agent_md("bob.agentid.pub")
+if state["remote_found"] and not state["in_sync"]:
+    # 服务端有更新版本
+    info = await client.fetch_agent_md("bob.agentid.pub")
+
+# 宽松模式：3 天内不重复 HEAD
+state = await client.check_agent_md("bob.agentid.pub", max_unsynced_days=3)
+if state["local_found"] and state["in_sync"]:
+    print("本地版本是最新的")
 ```
 
 ---
@@ -489,6 +610,39 @@ SDK 在 publish `message.received` / `group.message_created` 等应用事件时
 
 应用层比对二者是否一致即可知本地是否需要重新 publish。
 
+**Gateway 多 AID etag 注入（v0.x+）：** Gateway 现在在 RPC response 和事件通知的 `_meta` 中**最多同时注入两个 AID** 的 agent.md 元数据：
+
+- **requester**：调用者 / 事件订阅方（自身）
+- **peer**：RPC 对端 / 事件源（仅当 `peer_aid != requester_aid` 时注入）
+
+每个条目都带 `aid` 字段。`receiver` / `to` / `target` / `sender` / `from` 等是为了兼容旧 SDK 而保留的**别名**，它们指向与 `requester` 或 `peer` 完全相同的对象（不是独立 AID），新 SDK 只需读 `requester` 和 `peer` 即可：
+
+```json
+{
+  "_meta": {
+    "agent_md_etag": "\"requester-etag\"",
+    "agent_md_etags": {
+      "requester": {"aid": "alice.agentid.pub", "etag": "\"...\"", "last_modified": "..."},
+      "peer":      {"aid": "bob.agentid.pub",   "etag": "\"...\"", "last_modified": "..."},
+
+      "receiver":  { /* 与 requester 同一对象（事件场景）或与 peer 同一对象（RPC 场景） */ },
+      "to":        { /* alias of peer（RPC 场景） */ },
+      "target":    { /* alias of peer / requester */ },
+      "sender":    { /* alias of peer（事件场景） */ },
+      "from":      { /* alias of peer（事件场景） */ }
+    }
+  }
+}
+```
+
+| 场景 | requester | peer | 别名分布 |
+|------|-----------|------|---------|
+| RPC response | 调用者 | 对端（如果 RPC 涉及 to_aid 且不等于调用者） | `receiver/to/target` → peer |
+| 事件通知 | 订阅方 | 事件源（如果存在且不等于订阅方） | `receiver/target` → requester；`sender/from` → peer |
+
+- 各 SDK 收到后通过 `_observe_rpc_meta` → `_observe_agent_md_meta(aid, etag, last_modified)` 写入 `agent_md_cache` 持久化记录（`setdefault` 自动按 AID 去重，别名不会重复处理）
+- 若发现"远程有 etag 但本地从未保存该 aid"，SDK 会异步触发后台 `fetch_agent_md` 拉取一次（不阻塞 RPC 返回）；其他场景**不会**主动下载
+
 > **注意：** v0.x 起删除了 `set_local_agent_md_path()` / `get_local_agent_md_etag()` / `get_remote_agent_md_etag()` 三个旧 API。`_local_etag` 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存；不再支持外部直接设置或读取。
 
 ---

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -12,7 +12,7 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 
 ## 渐进式查阅流程
 
-### Step 1：只读 Layer 1（L7-33）
+### Step 1：只读 Layer 1（L7-34）
 
 列出所有文档名和章节行区间。能直接定位目标 → 跳 Step 4。
 
@@ -20,13 +20,13 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 
 仅当 Step 1 不够时，按关键词读：
 
-身份与认证 L39-44 · 连接与状态 L46-51 · E2EE L53-61 · RPC与事件 L63-75 · 配置与存储 L77-83 · 错误处理 L85-88 · AID托管 L44
+身份与认证 L40-45 · 连接与状态 L47-52 · E2EE L54-63 · RPC与事件 L65-77 · 配置与存储 L79-85 · 错误处理 L87-90 · AID托管 L45
 
 ### Step 3：按需读 Layer 3 单篇摘要
 
 仅当需要某篇详情但不确定读哪个章节时：
 
-快速开始 L94-95 · WebSocket协议 L97-98 · 核心概念 L100-101 · 连接与认证 L103-104 · E2EE加密通信 L106-107 · GROUP-E2EE轮换竞态清单 L109-110 · GROUP-E2EE现状对比与改进建议 L112-113 · API参考 L115-116 · 错误处理 L118-119 · 最佳实践 L121-122 · AID托管 L124-125 · 消息Payload L127-128 · 多语言SDK对齐审查 L130-131
+快速开始 L96-97 · WebSocket协议 L99-100 · 核心概念 L102-103 · 连接与认证 L105-106 · E2EE加密通信 L108-109 · E2EE_V2消息通信时序图 L111-112 · GROUP-E2EE轮换竞态清单 L114-115 · GROUP-E2EE现状对比与改进建议 L117-118 · API参考 L120-121 · 错误处理 L123-124 · 最佳实践 L126-127 · AID托管 L129-130 · 消息Payload L132-133 · 多语言SDK对齐审查 L135-136
 
 大多数问题在摘要层就能解答。
 
@@ -43,6 +43,7 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 | 03 | [核心概念](03-核心概念.md) | AID、状态机、认证、E2EE |
 | 04 | [连接与认证](04-连接与认证.md) | 认证封装、call()、on()、连接 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE封装、ProtectedHeaders、自定义存储 |
+| - | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 Mermaid 时序图 |
 | - | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态、竞态条件、补测清单 |
 | - | [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位、成熟方案对比、风险边界、分阶段改进建议 |
 | 06 | [API手册](06-API手册.md) | AUNClient / AuthNamespace / MetaNamespace（信任根列表与 issuer root 更新） / E2EEManager |
@@ -60,8 +61,9 @@ SDK 文档聚焦核心封装：**认证（`client.auth`）**、**元信息与信
 | 裸 WebSocket 或其他语言实现 | 02-WebSocket协议 |
 | 理解 AID / E2EE 原理 | 03-核心概念 对应章节 |
 | 认证 + 连接 + call/on 用法 | 04-连接与认证 |
-| 需要加密通信 | 05-E2EE加密通信 |
-| GROUP E2EE 轮换竞态/测试设计 | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) |
+| 需要加密通信 | 05-E2EE加密通信 |
+| 需要查看 E2EE V2 消息主链路时序 | [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) |
+| GROUP E2EE 轮换竞态/测试设计 | [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) |
 | GROUP E2EE 架构评估/演进路线 | [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) |
 | 查消息或思考内容 payload 类型和格式 | [09-payload-reference](09-payload-reference.md) |
 | 查某个方法的签名 | 06-API手册 |

package/_packed_docs/sdk/INDEX.md

@@ -10,12 +10,13 @@
 |------|------|
 | [01-快速开始](01-快速开始.md) | 最小示例 · 安装 · 配置 · 核心流程 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · 消息格式 · 裸 WebSocket 示例 |
-| [03-核心概念](03-核心概念.md) | AID · 连接状态机 · 认证流程 · E2EE |
-| [04-连接与认证](04-连接与认证.md) | 创建AID · 连接网关 · 网关发现 · 调用RPC · 事件订阅 |
+| [03-核心概念](03-核心概念.md) | AID · 连接状态机 · 认证流程 · E2EE |
+| [04-连接与认证](04-连接与认证.md) | 创建AID · 连接网关 · 网关发现 · 调用RPC · 事件订阅 |
 | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE加密消息 · ProtectedHeaders · 会话管理 · 自定义密钥存储 |
-| [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态 · 竞态条件 · 补测清单 |
-| [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位 · 成熟方案对比 · 风险边界 · 分阶段改进建议 |
-| [06-API手册](06-API手册.md) | AUNClient · AuthNamespace · MetaNamespace（信任根列表 / issuer root 更新） · E2EEManager · 内置事件 · RPC手册索引 |
+| [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md) | V2-only 明文/加密 P2P/GROUP 消息主链路 · Mermaid 时序图 |
+| [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md) | GROUP epoch key 轮换状态 · 竞态条件 · 补测清单 |
+| [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md) | 当前 GROUP E2EE 实现定位 · 成熟方案对比 · 风险边界 · 分阶段改进建议 |
+| [06-API手册](06-API手册.md) | AUNClient · AuthNamespace · MetaNamespace（信任根列表 / issuer root 更新） · E2EEManager · 内置事件 · RPC手册索引 |
 | [07-错误处理](07-错误处理.md) | 错误类层级 · 错误码速查 · 重试策略 |
 | [08-最佳实践](08-最佳实践.md) | 幂等初始化 · 多AID隔离 · 环境变量 · 资源清理 |
 | [10-custody-api-manual](10-custody-api-manual.md) | AID 托管 · 手机号验证码 · 备份恢复 · 跨设备复制 |
@@ -51,10 +52,11 @@
 - **连接状态事件** → [06-API手册](06-API手册.md)
 
 ### E2EE 端到端加密
-- **E2EE 机制概述** → [03-核心概念](03-核心概念.md)
-- **加密消息收发** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **会话管理** → [05-E2EE加密通信](05-E2EE加密通信.md)
-- **GROUP epoch key 轮换竞态/补测清单** → [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md)
+- **E2EE 机制概述** → [03-核心概念](03-核心概念.md)
+- **加密消息收发** → [05-E2EE加密通信](05-E2EE加密通信.md)
+- **V2-only P2P/GROUP 明文与加密时序** → [E2EE_V2消息通信时序图](E2EE_V2消息通信时序图.md)
+- **会话管理** → [05-E2EE加密通信](05-E2EE加密通信.md)
+- **GROUP epoch key 轮换竞态/补测清单** → [GROUP-E2EE轮换竞态清单](GROUP-E2EE轮换竞态清单.md)
 - **GROUP E2EE 现状对比与演进建议** → [GROUP-E2EE现状对比与改进建议](GROUP-E2EE现状对比与改进建议.md)
 - **E2EEManager API** → [06-API手册](06-API手册.md)
 - **E2EE 错误类** → [07-错误处理](07-错误处理.md)
@@ -105,9 +107,12 @@ SDK 高层封装。`create_aid` + `authenticate` 认证流程；`connect` 参数
 
 ### 05-E2EE加密通信
 E2EE 完整收发流程（加密发送 + 监听解密 + 后台消息循环）；`protected_headers` 与可验证 `context` 元数据；密钥管理（prekey 缓存 / replay guard / group epoch）；自定义 `KeyStore` / `SecretStore` Protocol。
-
-### GROUP-E2EE轮换竞态清单
-GROUP epoch key 两阶段轮换的状态边界和竞态检查项。覆盖 pending 期间成员变更、leader 竞争、分发/ack/commit 失败、stale pending、key recovery、旧 epoch 保留等场景，用于补充测试和实现审查。
+
+### E2EE_V2消息通信时序图
+当前 V2-only 实现下的主通信链路图。覆盖 V2 设备密钥注册、P2P 明文、P2P 加密、GROUP 明文、GROUP 加密五条时序；明确 P2P 加密走 `message.send` 承载 `e2ee.p2p_encrypted`，GROUP 加密走 `group.v2.send` 承载 `e2ee.group_encrypted`，接收端统一通过 V2 pull 后由 SDK 解密。
+
+### GROUP-E2EE轮换竞态清单
+GROUP epoch key 两阶段轮换的状态边界和竞态检查项。覆盖 pending 期间成员变更、leader 竞争、分发/ack/commit 失败、stale pending、key recovery、旧 epoch 保留等场景，用于补充测试和实现审查。
 
 ### GROUP-E2EE现状对比与改进建议
 当前 GROUP E2EE 实现的架构评估。对比 Signal Private Groups、WhatsApp Sender Key、Matrix Megolm 和 MLS，明确 AUN 当前处于“内容 E2EE + 服务端可见成员关系”的安全层级；列出旧 epoch key 恢复、signed group state commit、manifest hash / epoch chain 绑定、多设备模型和 epoch 内前向安全等改进方向。

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAkE,MAAM,aAAa,CAAC;AAM7G,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAwFpB,UAAU,WAAY,SAAQ,UAAU;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC7D;AAqTD;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,IAAI,CAA0B;IACtC,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAElC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAKnC;IAEX,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,UAAU,CAAU;IAG5B,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,kBAAkB,CAAoC;IAC9D,OAAO,CAAC,gBAAgB,CAAkF;IAC1G,OAAO,CAAC,iBAAiB,CAAkF;IAC3G,OAAO,CAAC,mBAAmB,CAAkC;IAC7D,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAmC;gBAEjD,IAAI,EAAE;QAChB,QAAQ,EAAE,QAAQ,CAAC;QACnB,MAAM,EAAE,cAAc,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAaD,eAAe;IACT,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAiBzD,uBAAuB;IACjB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAQtE,2CAA2C;IACrC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAItE,2BAA2B;IAC3B,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAM7D,kBAAkB,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKrE;;;;;;;OAOG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA4CrE;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA4EzE;;OAEG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BnE;;OAEG;IACG,mBAAmB,CACvB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,GAAG,IAAI,EAC5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GACA,OAAO,CAAC,UAAU,CAAC;IA2BtB;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,GAAG,IAAI,EAC5B,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GACA,OAAO,CAAC,WAAW,CAAC;IA0IvB;;OAEG;IACG,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAkB1B;;OAEG;IACG,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAkChB,sDAAsD;YACxC,SAAS;IA+EvB,qBAAqB;YACP,UAAU;IAexB,wBAAwB;YACV,UAAU;YAsBV,UAAU;IAYxB,oBAAoB;YACN,uBAAuB;YAyBvB,MAAM;IAiCpB,sBAAsB;YACR,mBAAmB;IAajC,yCAAyC;YAC3B,kBAAkB;YAiElB,qBAAqB;YAiDrB,oBAAoB;IAqElC,2BAA2B;YACb,mBAAmB;IAUjC,8BAA8B;YAChB,oBAAoB;YAQpB,yBAAyB;IA2BvC,2BAA2B;YACb,0BAA0B;IAcxC,gCAAgC;YAClB,gBAAgB;YA2ChB,mBAAmB;IAcjC,sBAAsB;YACR,sBAAsB;IAqBpC,oCAAoC;YACtB,uBAAuB;IAyCrC,8BAA8B;IAC9B,kBAAkB,IAAI,MAAM;IAQ5B,iCAAiC;IACjC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQpC,OAAO,CAAC,iBAAiB;IAmCzB,OAAO,CAAC,eAAe;IAqBvB,gCAAgC;YAClB,gBAAgB;IA4E9B,2BAA2B;IAC3B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAErE,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B,sBAAsB;YACR,oBAAoB;IAuBlC,oBAAoB;YACN,oBAAoB;IAclC,oBAAoB;YACN,eAAe;YAcf,kBAAkB;YAOlB,gBAAgB;IAkC9B,kCAAkC;IAClC,kBAAkB,IAAI,IAAI;CAe3B"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAkE,MAAM,aAAa,CAAC;AAM7G,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAwFpB,UAAU,WAAY,SAAQ,UAAU;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC7D;AAqTD;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,IAAI,CAA0B;IACtC,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAElC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAKnC;IAEX,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,UAAU,CAAU;IAG5B,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,kBAAkB,CAAoC;IAC9D,OAAO,CAAC,gBAAgB,CAAkF;IAC1G,OAAO,CAAC,iBAAiB,CAAkF;IAC3G,OAAO,CAAC,mBAAmB,CAAkC;IAC7D,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAmC;gBAEjD,IAAI,EAAE;QAChB,QAAQ,EAAE,QAAQ,CAAC;QACnB,MAAM,EAAE,cAAc,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAaD,eAAe;IACT,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAiBzD,uBAAuB;IACjB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAQtE,2CAA2C;IACrC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAItE,2BAA2B;IAC3B,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI;IAM7D,kBAAkB,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKrE;;;;;;;OAOG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA4CrE;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA4EzE;;OAEG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BnE;;OAEG;IACG,mBAAmB,CACvB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,GAAG,IAAI,EAC5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GACA,OAAO,CAAC,UAAU,CAAC;IA2BtB;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,GAAG,IAAI,EAC5B,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GACA,OAAO,CAAC,WAAW,CAAC;IA0IvB;;OAEG;IACG,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,cAAc,CAAC;IAkB1B;;OAEG;IACG,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAkChB,sDAAsD;YACxC,SAAS;IA+EvB,qBAAqB;YACP,UAAU;IAexB,wBAAwB;YACV,UAAU;YAsBV,UAAU;IAYxB,oBAAoB;YACN,uBAAuB;YAyBvB,MAAM;IAiCpB,sBAAsB;YACR,mBAAmB;IAajC,yCAAyC;YAC3B,kBAAkB;YAiElB,qBAAqB;YAiDrB,oBAAoB;IAqElC,2BAA2B;YACb,mBAAmB;IAUjC,8BAA8B;YAChB,oBAAoB;YAQpB,yBAAyB;IA2BvC,2BAA2B;YACb,0BAA0B;IAcxC,gCAAgC;YAClB,gBAAgB;YA2ChB,mBAAmB;IAcjC,sBAAsB;YACR,sBAAsB;IAqBpC,oCAAoC;YACtB,uBAAuB;IAyCrC,8BAA8B;IAC9B,kBAAkB,IAAI,MAAM;IAQ5B,iCAAiC;IACjC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQpC,OAAO,CAAC,iBAAiB;IAmCzB,OAAO,CAAC,eAAe;IAqBvB,gCAAgC;YAClB,gBAAgB;IA4E9B,2BAA2B;IAC3B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAErE,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B,sBAAsB;YACR,oBAAoB;IAuBlC,oBAAoB;YACN,oBAAoB;IAclC,oBAAoB;YACN,eAAe;YAcf,kBAAkB;YAOlB,gBAAgB;IA8B9B,kCAAkC;IAClC,kBAAkB,IAAI,IAAI;CAe3B"}

package/dist/auth.js

@@ -1509,7 +1509,7 @@ export class AuthFlow {
         }
     }
     async _loadInstanceState(aid) {
-        if (!this._deviceId || typeof this._keystore.loadInstanceState !== 'function') {
+        if (typeof this._keystore.loadInstanceState !== 'function') {
             return null;
         }
         return (await this._keystore.loadInstanceState(aid, this._deviceId, this._slotId));
@@ -1530,9 +1530,6 @@ export class AuthFlow {
             }
         }
         await this._keystore.saveIdentity(aid, persisted);
-        if (!this._deviceId) {
-            return;
-        }
         // 实例级字段已拆分到 instance_state，无需从共享 metadata 清理
         if (Object.keys(instanceState).length === 0 || typeof this._keystore.updateInstanceState !== 'function') {
             return;