@agentunion/fastaun-browser 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -6,6 +6,34 @@
 
 ---
 
+## 0.4.6 — 2026-06-01
+
+### Added
+- **IndexedDB 存储拆分**：将单一 `IndexedDBKeyStore` 拆分为两个专职类：
+  - `IndexedDBIdentityStore`（`keystore/indexeddb-identity-store.ts`）：负责私钥、密钥对、完整身份、pending 注册、证书、metadata KV。
+  - `IndexedDBTokenStore`（`keystore/indexeddb-token-store.ts`）：负责 prekeys、群组密钥、sessions、seq 跟踪、agent.md 缓存、群组状态、信任根。
+  - 共享基础设施提取到 `keystore/indexeddb-shared.ts`。
+- **`AgentMdManager` 类**（`agent-md.ts`）：独立的 agent.md 管理器，支持 ETag/Last-Modified 缓存验证、TTL 策略、内容签名验证、信任根存储（虚拟路径 `indexeddb://trust-roots/...`）。
+- **`KeyStore` 接口新增方法**：`loadCert(aid, certFingerprint?)` / `saveCert(aid, certPem, certFingerprint?, opts?)`。
+- **`RegisterFlow` 新增公开方法**：`validateAidName`、`fetchPeerCert`、`shortRpc`、`generateIdentity`、`newClientNonce`、`verifyPhase1Response`。
+- **`AIDStore` 新增方法**：`downloadAgentMd`（替代 `fetchAgentMd`）、`checkAgentMd`（替代 `headAgentMd`）。
+- **`AUNClient.uploadAgentMd()`**：新增方法，签名并上传当前 AID 的 agent.md。
+- **IndexedDB 新增对象仓库**：`agent_md_cache`、`group_state`、`pending_identities`、`e2ee_sessions`；数据库版本升级至 v7。
+- **导出新增**：`IndexedDBIdentityStore`、`IndexedDBTokenStore`、`TokenStore` 类型。
+
+### Changed
+- **`AUNClient` 架构**：移除内部 agent.md 缓存字段（`_agentMdCache`、`_agentMdFetchInflight` 等），改由 `AgentMdManager` 统一管理。
+- **`AIDStore`**：使用 `IndexedDBIdentityStore` 替代 `IndexedDBKeyStore`；移除内部 `AuthFlow` 实例，改为按需创建。
+- **`AIDStore.fetchAgentMd()`** 重命名为 `downloadAgentMd()`，返回类型同步更新为 `DownloadAgentMdResult`。
+- **私钥加密**：默认启用 AES-256-GCM + PBKDF2（100,000 迭代）；支持 `changeSeed()` 密码迁移。
+
+### Removed
+- **`IndexedDBKeyStore` 类**（`keystore/indexeddb.ts`，2280 行）：完整移除，功能分解为 `IndexedDBIdentityStore` 和 `IndexedDBTokenStore`。
+- **`FullKeyStore` 类型别名**：不再需要。
+- **`AIDStore.headAgentMd()`**：功能整合到 `AgentMdManager.check()`。
+
+---
+
 ## 0.4.5 — 2026-05-31
 
 ### Added

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,34 @@
 
 ---
 
+## 0.4.6 — 2026-06-01
+
+### Added
+- **IndexedDB 存储拆分**：将单一 `IndexedDBKeyStore` 拆分为两个专职类：
+  - `IndexedDBIdentityStore`（`keystore/indexeddb-identity-store.ts`）：负责私钥、密钥对、完整身份、pending 注册、证书、metadata KV。
+  - `IndexedDBTokenStore`（`keystore/indexeddb-token-store.ts`）：负责 prekeys、群组密钥、sessions、seq 跟踪、agent.md 缓存、群组状态、信任根。
+  - 共享基础设施提取到 `keystore/indexeddb-shared.ts`。
+- **`AgentMdManager` 类**（`agent-md.ts`）：独立的 agent.md 管理器，支持 ETag/Last-Modified 缓存验证、TTL 策略、内容签名验证、信任根存储（虚拟路径 `indexeddb://trust-roots/...`）。
+- **`KeyStore` 接口新增方法**：`loadCert(aid, certFingerprint?)` / `saveCert(aid, certPem, certFingerprint?, opts?)`。
+- **`RegisterFlow` 新增公开方法**：`validateAidName`、`fetchPeerCert`、`shortRpc`、`generateIdentity`、`newClientNonce`、`verifyPhase1Response`。
+- **`AIDStore` 新增方法**：`downloadAgentMd`（替代 `fetchAgentMd`）、`checkAgentMd`（替代 `headAgentMd`）。
+- **`AUNClient.uploadAgentMd()`**：新增方法，签名并上传当前 AID 的 agent.md。
+- **IndexedDB 新增对象仓库**：`agent_md_cache`、`group_state`、`pending_identities`、`e2ee_sessions`；数据库版本升级至 v7。
+- **导出新增**：`IndexedDBIdentityStore`、`IndexedDBTokenStore`、`TokenStore` 类型。
+
+### Changed
+- **`AUNClient` 架构**：移除内部 agent.md 缓存字段（`_agentMdCache`、`_agentMdFetchInflight` 等），改由 `AgentMdManager` 统一管理。
+- **`AIDStore`**：使用 `IndexedDBIdentityStore` 替代 `IndexedDBKeyStore`；移除内部 `AuthFlow` 实例，改为按需创建。
+- **`AIDStore.fetchAgentMd()`** 重命名为 `downloadAgentMd()`，返回类型同步更新为 `DownloadAgentMdResult`。
+- **私钥加密**：默认启用 AES-256-GCM + PBKDF2（100,000 迭代）；支持 `changeSeed()` 密码迁移。
+
+### Removed
+- **`IndexedDBKeyStore` 类**（`keystore/indexeddb.ts`，2280 行）：完整移除，功能分解为 `IndexedDBIdentityStore` 和 `IndexedDBTokenStore`。
+- **`FullKeyStore` 类型别名**：不再需要。
+- **`AIDStore.headAgentMd()`**：功能整合到 `AgentMdManager.check()`。
+
+---
+
 ## 0.4.5 — 2026-05-31
 
 ### Added

package/_packed_docs/INDEX.md

@@ -13,7 +13,7 @@
 | [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md) | 多语言 SDK 同网同服、test-runner 控制面的跨语言 E2E 方案 |
 | [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md) | SDK bootstrap 能力声明 + 服务端 policy 控制 1DH/per-AID wrap 的兼容方案 |
 | [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md) | RPC trace 诊断字段与 enter/exit span 设计 |
-| [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 缓存、SQLite 表、消息信封与 RPC 响应 ETag 透传方案 |
+| [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、消息信封与 RPC 响应 ETag 透传方案 |
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE 手册的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [协议文档目录](protocol/) | AUN 协议相关文档 |
@@ -76,7 +76,7 @@
 
 ### 远程 agent.md 缓存与 ETag 透传方案
 
-定义每个远程 AID 在 SDK 内存和 SQLite 中维护一条 `remote_agent_md_cache` 记录，字段包含 `remote_etag`、`local_etag`、`content`、`last_modified`、`fetched_at`、`observed_at` 等。方案同时规定 `message.send` 响应向发送端透传 `to` 的 agent.md ETag，消息信封向接收端透传 `from` 的 agent.md ETag，并给出按需下载、304 处理、竞态和跨 SDK 一致性规则。
+定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案同时规定 `message.send` 响应向发送端透传 `to` 的 agent.md ETag，消息信封向接收端透传 `from` 的 agent.md ETag，并给出按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
 
 ### SDK 文档索引
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -52,5 +52,5 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | agent.md 远程缓存目标与字段 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L5-86 |
 | agent.md ETag 透传时序图 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L88-185 |
 | agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L187-268 |
-| agent.md SQLite 表结构、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L270-328 |
+| agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L269-317 |
 | SDK API、RPC、E2EE 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |

package/_packed_docs/agent.md//350/277/234/347/250/213agent.md/347/274/223/345/255/230/344/270/216etag/351/200/217/344/274/240/346/226/271/346/241/210.md

@@ -8,8 +8,8 @@
 
 核心目标：
 
-- 每个远程 AID 在 SDK 本地内存中维护一条 `agent.md` 记录，包含 `remote_etag`、`local_etag`、`content`、`last_modified` 等字段。
-- 同一条远程缓存记录持久化到本地 SQLite 表，SDK 启动或内存 miss 时按需加载。
+- 每个远程 AID 在 SDK 本地维护一条 `agent.md` 记录，包含 `remote_etag`、`local_etag`、`content`、`last_modified` 等字段。
+- Python / TypeScript / Go 将正文和元数据持久化到 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`；浏览器 JavaScript 使用 IndexedDB 等价 key，存储不可用时退化为内存缓存。
 - `message.send` 的 RPC 响应携带接收方 `agent.md` ETag，让发送方更新 `to` 的云端版本。
 - 接收端收到消息信封时携带发送方 `agent.md` ETag，让接收方更新 `from` 的云端版本。
 - ETag 只作为版本提示，不替代 `agent.md` 内容下载和验签。
@@ -21,7 +21,7 @@
 1. `message.send` / V2 P2P send：把 `from` 的 `agent.md` ETag 注入消息信封，随消息到达接收端。
 2. `message.send` RPC response：把 `to` 的 `agent.md` ETag 注入响应 `_meta`，返回发送端。
 
-注意：服务端注入的 ETag 只能代表云端版本。SDK 本地必须区分“观察到的远端云端 ETag”和“当前本地内容对应的 ETag”。字段命名固定为 `remote_etag` 和 `local_etag`，其中 `remote_etag` 表示远端云端版本，`local_etag` 表示本地 `content` 对应版本。不能在只有远端 ETag、没有内容的情况下直接覆盖 `local_etag`，否则后续 `If-None-Match` 命中 304 时本地可能没有可用内容。
+注意：服务端注入的 ETag 只能代表云端版本。SDK 本地必须区分“观察到的远端云端 ETag”和“当前本地内容对应的 ETag”。字段命名固定为 `remote_etag` 和 `local_etag`，其中 `remote_etag` 表示远端云端版本，`local_etag` 表示本地 `content` 对应版本。下载必须始终使用无条件 GET，不能把 `remote_etag` 或 `local_etag` 放进 `If-None-Match` / `If-Modified-Since`，否则会把版本提示误用成 HTTP 缓存状态。
 
 ## 字段建议
 
@@ -63,26 +63,29 @@
 
 ## SDK 缓存模型
 
-每个远程 AID 在内存和 SQLite 表中都维护一条缓存记录。内存记录与 SQLite 表记录字段语义一致，SQLite 用于 SDK 重启或内存 miss 时按需加载。
+每个远程 AID 在内存和本地持久化记录中都维护一条 agent.md 状态。Python / TypeScript / Go 的持久化记录是 `{aun_path}/AIDs/{aid}/agentmd.json`；浏览器 JavaScript 是 IndexedDB 中的 `{aid}/agentmd.json` logical key。SDK 启动或内存 miss 时按需加载该记录。
 
 | 字段 | 含义 |
 | --- | --- |
 | `aid` | 远程 AID |
-| `content` | 本地缓存的完整 `agent.md` 内容，可为空 |
-| `local_etag` | 当前 `content` 对应的 ETag，只能由 GET 200/304 确认 |
-| `remote_etag` | 从消息信封或 RPC `_meta` 观察到的远端云端 ETag |
-| `last_modified` | GET 响应的 `Last-Modified` |
-| `fetched_at` | 最近一次成功确认内容的本机时间 |
-| `observed_at` | 最近一次观察到远端 ETag 的本机时间 |
-| `stale` | `remote_etag` 与 `local_etag` 不一致，或有远端 ETag 但无内容 |
-| `verify_status` | 最近一次 `verify_agent_md` 结果：`verified` / `unsigned` / `invalid` |
+| `content` | 本地缓存的完整 `agent.md` 内容，可为空 |
+| `local_etag` | 当前 `content` 对应的 ETag，由成功 GET 200 内容确认；304 复用本地内容时沿用原值 |
+| `remote_etag` | 从消息信封或 RPC `_meta` 观察到的远端云端 ETag |
+| `last_modified` | GET 响应的 `Last-Modified` |
+| `fetched_at` | 最近一次成功确认内容的本机时间 |
+| `checked_at` | 最近一次 HEAD / GET 确认远端状态的本机时间 |
+| `observed_at` | 最近一次观察到远端 ETag 的本机时间 |
+| `remote_status` | `found` / `missing` / `error` |
+| `verify_status` | 最近一次 agent.md 验签结果：`ok` / `unsigned` / `invalid` 等 |
+| `verify_error` | 最近一次验签失败原因 |
+| `last_error` | 最近一次网络或 HTTP 错误 |
 
 状态规则：
 
 - 收到远端 ETag 时，只更新 `remote_etag` 和 `observed_at`。
 - 只有下载到内容并完成验签后，才能更新 `content`、`local_etag`、`last_modified`、`fetched_at`。
-- `remote_etag == local_etag` 时，`stale=false`。
-- `remote_etag != local_etag` 或 `content` 为空时，`stale=true`。
+- `remote_etag == local_etag` 时视为同步。
+- `remote_etag != local_etag` 或 `content` 为空时视为需要更新；该状态可由字段推导，不要求单独存储 `stale` 字段。
 - `verify_status=invalid` 时内容可以缓存但应用层应能看到无效状态；是否拒绝展示由上层策略决定。
 
 ## 时序图
@@ -107,7 +110,7 @@ sequenceDiagram
     GW->>NS: HEAD https://B/agent.md<br/>取 to ETag（缓存命中则不请求）
     NS-->>GW: ETag(B)
     GW-->>A: RPC response + _meta.agent_md_etags.to
-    A->>A: observeRemoteAgentMdEtag(B, etag)<br/>更新内存 + SQLite remote_etag
+    A->>A: observeRemoteAgentMdEtag(B, etag)<br/>更新内存 + agentmd.json/IndexedDB remote_etag
 ```
 
 ### 接收消息时，接收端获得 from 的 agent.md ETag
@@ -127,11 +130,11 @@ sequenceDiagram
     alt 本地 local_etag == remote_etag
         Cache-->>B: 只刷新 observed_at，不下载
     else 本地无内容或 ETag 不一致
-        Cache->>Cache: 标记 stale，按需或后台拉取
-        B->>NS: GET https://A/agent.md<br/>If-None-Match=local_etag
-        NS-->>B: 200 content + ETag 或 304
+        Cache->>Cache: 标记需要更新，按需或后台拉取
+        B->>NS: GET https://A/agent.md<br/>不带条件请求头
+        NS-->>B: 200 content + ETag，或异常 304/404/error
         B->>B: verify_agent_md(content, aid=A)
-        B->>Cache: 写内存 + SQLite
+        B->>Cache: 写内存 + agentmd.json/IndexedDB
     end
 ```
 
@@ -142,25 +145,25 @@ sequenceDiagram
     participant App
     participant SDK
     participant Mem as Memory Cache
-    participant SQL as SQLite
+    participant Store as agentmd.json / IndexedDB
     participant NS as NameService
 
-    App->>SDK: fetchAgentMd(A) / getRemoteAgentMd(A)
+    App->>SDK: downloadAgentMd(A)
     SDK->>Mem: 查 A
     alt 内存有可用 content
         Mem-->>SDK: content, local_etag
     else 内存缺失
-        SDK->>SQL: load remote_agent_md_cache where aid=A
-        SQL-->>SDK: content/remote_etag/local_etag/last_modified
+        SDK->>Store: load {aid}/agentmd.json
+        Store-->>SDK: content/remote_etag/local_etag/last_modified
         SDK->>Mem: 回填内存
     end
 
     alt 内容缺失或 remote_etag != local_etag
-        SDK->>NS: GET /agent.md<br/>If-None-Match=local_etag
-        NS-->>SDK: 200/304/404/error
-        SDK->>SDK: 200 时验签；304 时复用旧 content
+        SDK->>NS: GET /agent.md<br/>不带条件请求头
+        NS-->>SDK: 200/304/404/error
+        SDK->>SDK: 200 时验签；304 时有本地 content 则复用，无 content 则再无条件 GET 一次
         SDK->>Mem: upsert
-        SDK->>SQL: upsert
+        SDK->>Store: upsert agent.md + agentmd.json
     end
 
     SDK-->>App: agent.md content + signature + sync 状态
@@ -251,67 +254,53 @@ observe_remote_agent_md_etag(aid, etag, source)
 
 - aid 或 etag 为空时忽略。
 - etag 与当前 `remote_etag` 相同：只刷新 `observed_at`。
-- etag 变化：更新 `remote_etag`、`observed_at`，并根据 `local_etag` 设置 `stale`。
-- 变更需要同时写入内存和 SQLite。
+- etag 变化：更新 `remote_etag`、`observed_at`，并根据 `local_etag` 推导是否需要更新。
+- 变更需要同时写入内存和 agentmd.json / IndexedDB。
 
 ### 按需下载
 
-当应用调用 `fetchAgentMd(aid)` 或 SDK 需要展示远程 agent 信息时：
-
-- 先查内存，miss 时查 SQLite 表。
-- 如果 `content` 存在且 `local_etag == remote_etag`，可直接返回缓存。
-- 如果 `content` 缺失或 stale，则发起 GET。
-- GET 时优先带 `If-None-Match=local_etag`，其次带 `If-Modified-Since=last_modified`。
-- 200：验签，更新内容和 `local_etag`。
-- 304：只有本地已有 content 时才能复用；如果本地没有 content 却收到 304，应清空条件头重试一次 GET。
-- 404：标记远端未发布 `agent.md`，不要删除已有内容，除非产品要求严格同步。
-- 网络错误：保留旧内容，记录 `fetch_error` 或更新失败时间。
-
-### SQLite 持久化
-
-新增结构化表 `remote_agent_md_cache`，每个远程 AID 一行：
-
-| 列 | 类型 |
-| --- | --- |
-| `aid` | TEXT PRIMARY KEY |
-| `content` | TEXT NOT NULL DEFAULT '' |
-| `local_etag` | TEXT NOT NULL DEFAULT '' |
-| `remote_etag` | TEXT NOT NULL DEFAULT '' |
-| `last_modified` | TEXT NOT NULL DEFAULT '' |
-| `fetched_at` | INTEGER NOT NULL DEFAULT 0 |
-| `observed_at` | INTEGER NOT NULL DEFAULT 0 |
-| `verify_status` | TEXT NOT NULL DEFAULT '' |
-| `verify_error` | TEXT NOT NULL DEFAULT '' |
-| `updated_at` | INTEGER NOT NULL DEFAULT 0 |
-
-建议 SQL：
-
-```sql
-CREATE TABLE IF NOT EXISTS remote_agent_md_cache (
-  aid TEXT PRIMARY KEY,
-  content TEXT NOT NULL DEFAULT '',
-  local_etag TEXT NOT NULL DEFAULT '',
-  remote_etag TEXT NOT NULL DEFAULT '',
-  last_modified TEXT NOT NULL DEFAULT '',
-  fetched_at INTEGER NOT NULL DEFAULT 0,
-  observed_at INTEGER NOT NULL DEFAULT 0,
-  verify_status TEXT NOT NULL DEFAULT '',
-  verify_error TEXT NOT NULL DEFAULT '',
-  updated_at INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE INDEX IF NOT EXISTS idx_remote_agent_md_cache_observed_at
-ON remote_agent_md_cache(observed_at);
-```
-
-五个 SDK 应保持字段语义一致。浏览器 JS 可落 IndexedDB；Node TS、Python、Go、C++ 落各自现有本地存储。
+当应用调用 `downloadAgentMd(aid)` 或 SDK 需要展示远程 agent 信息时：
+
+- 可先查内存，miss 时查 agentmd.json / IndexedDB，用于展示本地已有状态。
+- `downloadAgentMd(aid)` 的远端下载请求一律发起无条件 GET，不用本地 ETag 决定请求头。
+- GET 请求不得发送 `If-None-Match` / `If-Modified-Since`。
+- 200：验签，更新内容和 `local_etag`。
+- 304：本地已有 content 时复用该 content；本地没有 content 时再发起一次无条件 GET。第二次仍非 2xx 时按错误返回。
+- 404：标记远端未发布 `agent.md`，不要删除已有内容，除非产品要求严格同步。
+- 网络错误：保留旧内容，记录 `fetch_error` 或更新失败时间。
+
+### 本地文件 / 浏览器持久化
+
+agent.md 不写入 SQLite。当前 SDK 使用以下持久化位置：
+
+| SDK | 正文 | 元数据 |
+| --- | --- | --- |
+| Python | `{aun_path}/AIDs/{aid}/agent.md` | `{aun_path}/AIDs/{aid}/agentmd.json` |
+| TypeScript / Node | `{aun_path}/AIDs/{aid}/agent.md` | `{aun_path}/AIDs/{aid}/agentmd.json` |
+| Go | `{aun_path}/AIDs/{aid}/agent.md` | `{aun_path}/AIDs/{aid}/agentmd.json` |
+| JavaScript / 浏览器 | IndexedDB logical key `{root}/{aid}/agent.md` | IndexedDB logical key `{root}/{aid}/agentmd.json` |
+
+`agentmd.json` 至少承载以下语义字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `aid` | AID |
+| `content` | 正文副本；文件系统 SDK 也会单独写 `agent.md` |
+| `local_etag` / `remote_etag` | 本地内容版本 / 远端观察版本 |
+| `last_modified` | 远端 Last-Modified |
+| `fetched_at` / `checked_at` / `observed_at` / `updated_at` | 本机时间戳 |
+| `remote_status` | `found` / `missing` / `error` |
+| `verify_status` / `verify_error` | 最近一次验签状态 |
+| `last_error` | 最近一次错误 |
+
+四个已实现 SDK 应保持字段语义一致。旧 `agent_md_cache` / `remote_agent_md_cache` SQLite 表不再作为 agent.md 缓存来源；迁移逻辑可清理旧表，但不得把新 agent.md 写回 SQLite。
 
 ## 异常与竞态处理
 
 - 多个消息同时观察同一 AID 的新 ETag：按 ETag 值幂等 upsert。
 - 多个协程同时触发同一 AID 下载：需要 per-AID in-flight 去重。
-- 观察到 ETag A 后开始下载，期间又观察到 ETag B：下载完成时只更新 `local_etag=A`，随后仍保持 stale，下一轮继续拉 B。
-- 304 但本地 content 缺失：不能返回空内容，必须无条件 GET 重试。
+- 观察到 ETag A 后开始下载，期间又观察到 ETag B：下载完成时只更新 `local_etag=A`，随后仍可由 `remote_etag != local_etag` 推导为需要更新，下一轮继续拉 B。
+- 304 但本地 content 缺失：不能返回空内容，必须再无条件 GET 一次。
 - 信封里的 ETag 不参与 AAD，不作为安全声明；安全性仍依赖 `agent.md` 签名和证书校验。
 - HEAD/GET 超时不影响 message send 和 message pull。
 - 跨域场景中，目标域 Message Service 注入 sender ETag 时可能需要跨域 HEAD；失败时允许缺字段。
@@ -320,9 +309,9 @@ ON remote_agent_md_cache(observed_at);
 
 - 发送方收到 `message.send` 响应后，能把 `to` 的 ETag 写入本地缓存 `remote_etag`。
 - 接收方 `message.v2.pull` 后，能从 `envelope.agent_md.sender` 写入 `from` 的 `remote_etag`。
-- ETag 变化但内容未下载时，缓存状态为 stale。
-- 本地 SQLite 有缓存、内存为空时，SDK 能按需加载。
-- 304 且本地有内容时复用内容；304 但本地无内容时强制重拉。
+- ETag 变化但内容未下载时，可由 `remote_etag != local_etag` 推导为需要更新。
+- 本地文件 / IndexedDB 有缓存、内存为空时，SDK 能按需加载。
+- 304 且本地有内容时复用内容；304 但本地无内容时再无条件 GET 一次。
 - `agent.md` 上传后，Gateway 缓存失效，后续消息能看到新 ETag。
 - HEAD/GET 404、超时、网络错误不影响消息收发主链路。
-- Python / TS / JS / Go / C++ 五个 SDK 对 `remote_etag`、`local_etag`、`content`、`stale` 语义一致。
+- Python / TS / JS / Go 四个 SDK 对 `remote_etag`、`local_etag`、`content`、`remote_status`、`verify_status` 语义一致。

package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -26,7 +26,7 @@ pip install fastaun
 
 - `AUNClient()`：无身份客户端，状态为 `no_identity`，随后用 `load_identity(AID对象)` 加载身份。
 - `AUNClient(aid)`：带身份客户端，`aid` 必须是 `AIDStore.load()` 返回的 AID 对象，状态为 `standby`。
-- TS/JS/Go 同构：只允许 `options` 或 `AID对象 + options`；字符串 AID、把 aid 放进 options、旧 `(config, debug)` 都不是公开入口。
+- TS/JS/Go 同构：只允许无参或 `AID` 对象；字符串 AID、把 aid 放进 options、旧 `(config, debug)` / `(aid, options)` 都不是公开入口。
 
 ---
 
@@ -67,7 +67,7 @@ async def load_or_register(store: AIDStore, aid: str):
 async def create_client(aid: str) -> AUNClient:
     store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
     identity = await load_or_register(store, aid)
-    client = AUNClient(identity, debug=True)
+    client = AUNClient(identity)
     await client.connect({"slot_id": "main", "auto_reconnect": True})
     return client
 
@@ -116,13 +116,14 @@ store = AIDStore(
 )
 ```
 
-`AUNClient` 只接收 AID 对象和连接级选项：
+`AUNClient` 只接收可选 AID 对象。调试、TLS、根证书和默认 slot 等配置由 `AIDStore` 注入到 AID 对象，再由 client 继承；`protected_headers` 通过 setter 配置：
 
 ```python
-identity = store.load("alice.agentid.pub")["data"]["aid"]
-client = AUNClient(identity, debug=True, protected_headers={"sdk": "python"})
-await client.connect({"slot_id": "main", "connection_kind": "long"})
-```
+identity = store.load("alice.agentid.pub")["data"]["aid"]
+client = AUNClient(identity)
+client.set_protected_headers({"sdk": "python"})
+await client.connect({"slot_id": "main", "connection_kind": "long"})
+```
 
 `verify_ssl` 在 `AIDStore` 构造时配置，不在 `AUNClient` 中配置。自动模式下 SDK 根据环境变量决定：
 
@@ -165,17 +166,17 @@ SDK 使用 `{aun_path}/AIDs/{aid}/` 存储每个 AID 的专属数据：
 TypeScript / Node：
 
 ```ts
-const store = new AIDStore({ aunPath: "~/.aun/myapp", encryptionSeed: "" });
-const loaded = store.load("alice.agentid.pub");
-const client = new AUNClient(loaded.data!.aid, { debug: true });
+const store = new AIDStore({ aunPath: "~/.aun/myapp", encryptionSeed: "" });
+const loaded = store.load("alice.agentid.pub");
+const client = new AUNClient(loaded.data!.aid);
 ```
 
 JavaScript / 浏览器：
 
 ```js
-const store = new AIDStore({ aunPath: "browser-demo", encryptionSeed: "" });
-const loaded = await store.load("alice.agentid.pub");
-const client = new AUNClient(loaded.data.aid, { debug: true });
+const store = new AIDStore({ aunPath: "browser-demo", encryptionSeed: "" });
+const loaded = await store.load("alice.agentid.pub");
+const client = new AUNClient(loaded.data.aid);
 ```
 
 Go：
@@ -195,7 +196,7 @@ client := aun.NewAUNClient(aid.Data.AID)
 
 1. 创建 `AIDStore`。
 2. `store.load(aid)` 加载本地 AID；本地不存在时调用 `store.register(aid)` 后再次加载。
-3. 用 AID 对象构造 `AUNClient(aid, ...)`，或先 `AUNClient()` 再 `load_identity(aid)`。
+3. 用 AID 对象构造 `AUNClient(aid)`，或先 `AUNClient()` 再 `load_identity(aid)`。
 4. 先注册事件处理器，再调用 `connect(options)`。
 5. 通过 `call(method, params)` 执行业务 RPC。
 6. 通过 `close()` 释放连接和后台任务。

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -73,9 +73,9 @@ sequenceDiagram
 
 - `protocol.min/max` 在 `auth.connect` 阶段完成 Gateway 会话版本协商；详细规则见协议文档 `03-Gateway-连接模式.md`。
 - `device.id` 是设备级稳定标识，Python SDK 默认从 `~/.aun/.device_id` 读取。
-- `client.slot_id` 由应用层显式传入，用于区分同设备上的多个实例槽位。
+- `client.slot_id` 由应用层显式传入，用于区分同设备上的多个实例槽位。SDK 允许 `/`、`:`、空格作为隔离键分隔符，例如 `evolclaw cli`、`evolclaw/cli`、`evolclaw:cli` 的隔离键都是 `evolclaw`。
 - `delivery_mode` 决定该 AID 当前连接的投递语义；同一 AID 的所有在线连接必须保持一致。
-- `options.kind` 声明连接类型：`"long"`（默认）= 长连接，承担服务端推送 / 事件订阅；`"short"` = 短连接，仅用于发送 RPC 并等待响应即断开。同 `(aid, device.id, client.slot_id)` 槽位下，长连接最多 1 条，短连接最多 10 条；短连接不会顶掉长连接。
+- `options.kind` 声明连接类型：`"long"`（默认）= 长连接，承担服务端推送 / 事件订阅；`"short"` = 短连接，仅用于发送 RPC 并等待响应即断开。同 `(aid, device.id, slotIsolationKey(client.slot_id))` 隔离槽下，长连接最多 1 条，短连接最多 10 条；短连接不会顶掉长连接。
 - `options.short_ttl_ms` 仅在 `kind="short"` 时有效，可选；服务端兜底超时后主动关闭短连接，防止占名额。
 - `capabilities` 是客户端能力声明；`hello-ok.result.capabilities` 是服务端能力公告，不是双方能力交集。
 

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -36,11 +36,28 @@ assert me.is_private_key_valid()
 | `AID` | 身份值对象，负责签名、验签、agent.md 签验 | 否 |
 | `AUNClient` | 会话对象，负责认证、连接、重连、事件和 RPC | 是 |
 
-`AUNClient` 不再通过配置字典持有某个字符串 AID；它只接收已加载并校验过私钥的 AID 对象。
-
----
-
-## 连接状态机
+`AUNClient` 不再通过配置字典持有某个字符串 AID；它只接收已加载并校验过私钥的 AID 对象。
+
+---
+
+## device_id 与 slot_id
+
+`device_id` 是设备级稳定标识，默认写在 `{aun_path}/.device_id`，用于 token、实例状态、V2 设备密钥和消息游标的一级隔离。它是单段安全 token，只允许字母、数字、`.`、`_`、`-`。
+
+`slot_id` 是同一设备下的连接/消费槽位，允许用 `/`、`:`、空格表达共享隔离键。隔离键取第一个分隔符前的部分：
+
+| slot_id | slotIsolationKey |
+|---------|------------------|
+| `evolclaw daemon` | `evolclaw` |
+| `evolclaw cli` | `evolclaw` |
+| `evolclaw/netcheck` | `evolclaw` |
+| `evolclaw-daemon` | `evolclaw-daemon` |
+
+SDK 在 `message.pull` / `message.ack` 中自动注入当前 `device_id` / `slot_id`，并按隔离键校验显式传入的 `slot_id`。因此共享消费槽位时应使用 `/`、`:` 或空格作为分隔符。
+
+---
+
+## 连接状态机
 
 ```mermaid
 stateDiagram-v2

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

@@ -16,9 +16,9 @@ if not loaded["ok"]:
         raise RuntimeError(registered["error"]["message"])
     loaded = store.load(aid)
 
-me = loaded["data"]["aid"]
-client = AUNClient(me, debug=True)
-await client.connect({"slot_id": "main", "auto_reconnect": True})
+me = loaded["data"]["aid"]
+client = AUNClient(me)
+await client.connect({"slot_id": "main", "auto_reconnect": True})
 ```
 
 关键约束：
@@ -62,9 +62,9 @@ store = AIDStore(
 | `register(aid)` | 注册新 AID，返回 Result |
 | `list()` | 列出本地身份 |
 | `exists(aid)` | HEAD PKI 端点，判断 AID 是否已注册 |
-| `resolve(aid, opts=None)` | 拉取并缓存对端证书和 agent.md |
-| `fetch_agent_md(aid)` | 下载并验签对端 agent.md |
-| `check_agent_md(aid, ttl_days=1)` | 检查本地缓存与远端 agent.md 状态 |
+| `resolve(aid, opts=None)` | 拉取并缓存对端证书；默认同时下载并验签 agent.md，可传 `skip_agent_md=True` 跳过 |
+| `download_agent_md(aid)` | 下载并验签对端 agent.md |
+| `check_agent_md(aid, ttl_days=1)` | 检查本地缓存与远端 agent.md 状态 |
 | `diagnose(aid)` | 本地和远端一致性诊断 |
 | `renew_cert(aid)` / `rekey(aid)` | 证书续签和换钥，成功后重新 `load()` |
 
@@ -125,7 +125,7 @@ await client.connect({
 
 | 选项 | 说明 |
 |------|------|
-| `slot_id` | 同一设备内的实例槽位 |
+| `slot_id` | 同一设备内的实例槽位；允许 `/`、`:`、空格作为共享隔离键分隔符 |
 | `connection_kind` | `"long"` 或 `"short"` |
 | `short_ttl_ms` | 短连接服务端兜底超时 |
 | `delivery_mode` | 连接级投递语义 |
@@ -141,7 +141,7 @@ await client.connect({
 
 ## 长短连接共存
 
-同一 `(aid, device_id, slot_id)` 槽位下允许 1 条长连接 + 最多 10 条短连接。
+同一 `(aid, device_id, slotIsolationKey(slot_id))` 隔离槽下允许 1 条长连接 + 最多 10 条短连接。`slot_id` 的第一个 `/`、`:` 或空格之前的部分是共享隔离键，因此 `evolclaw daemon`、`evolclaw cli`、`evolclaw/netcheck` 会共享 `evolclaw` 隔离槽。
 
 长连接：
 
@@ -199,27 +199,43 @@ print(client.can_connect, client.can_send, client.is_online)
 
 ---
 
-## Agent Web / agent.md
-
-发布自己的 agent.md：
-
-```python
-await client.publish_agent_md(content)
-```
-
-解析对端并验签 agent.md：
+## Agent Web / agent.md
+
+发布自己的 agent.md：
+
+```python
+await client.upload_agent_md(content)
+```
+
+解析对端并验签 agent.md：
 
 ```python
 resolved = await store.resolve("bob.agentid.pub")
-if resolved["ok"]:
-    print(resolved["data"]["agent_md"]["signature"]["status"])
-```
-
-只检查远端是否存在：
-
-```python
-head = await store.head_agent_md("bob.agentid.pub")
-```
+if resolved["ok"]:
+    print(resolved["data"]["agent_md"]["verification"]["status"])
+```
+
+只下载对端 agent.md：
+
+```python
+downloaded = await store.download_agent_md("bob.agentid.pub")
+```
+
+只检查本地缓存与远端状态：
+
+```python
+state = await store.check_agent_md("bob.agentid.pub", ttl_days=1)
+```
+
+当前公开入口分工固定：
+
+| 主体 | 公开能力 |
+|------|----------|
+| `AUNClient` | `upload_agent_md(content=None)`：读取/签名/上传当前 AID 的 agent.md |
+| `AIDStore` | `download_agent_md(aid)`、`check_agent_md(aid, ttl_days=1)`、`resolve(aid, opts)` |
+| `AID` | `sign_agent_md(content)`、`verify_agent_md(content)` 低层签验能力 |
+
+本地落盘位置由 SDK 管理。Python / TypeScript / Go 写入 `{aun_path}/AIDs/{aid}/agent.md` 和同目录 `agentmd.json`；浏览器 JavaScript 写入 IndexedDB 的等价 logical key，存储不可用时退化为内存缓存。agent.md 不写入 SQLite，也不再使用旧 `{aun_path}/AgentMDs` 目录。
 
 ---
 

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

@@ -596,7 +596,7 @@ class MySecretStore:
 client = AUNClient(aid)
 ```
 
-`AUNClient` 构造函数只接收可选 AID 对象和会话选项。`SecretStore` / `KeyStore` / `SQLiteBackup` 属于 SDK 内部基础设施，不作为应用层构造参数暴露。
+`AUNClient` 构造函数只接收可选 AID 对象。`SecretStore` / `KeyStore` / `SQLiteBackup` 属于 SDK 内部基础设施，不作为应用层构造参数暴露。
 
 ---