@agentunion/fastaun-browser 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -6,6 +6,51 @@
 
 ---
 
+## 0.3.4 — 2026-05-28
+
+### Breaking Changes
+- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
+- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
+
+### Added
+- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
+- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
+- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
+- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
+- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
+
+### Changed
+- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
+- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
+- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
+- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
+- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
+
+### Removed
+- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
+- **`createAid` 方法**：已移除
+
+---
+
+## 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,51 @@
 
 ---
 
+## 0.3.4 — 2026-05-28
+
+### Breaking Changes
+- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
+- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
+
+### Added
+- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
+- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
+- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
+- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
+- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
+
+### Changed
+- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
+- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
+- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
+- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
+- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
+
+### Removed
+- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
+- **`createAid` 方法**：已移除
+
+---
+
+## 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/INDEX.md

@@ -0,0 +1,81 @@
+# AUN SDK Core 文档索引
+
+> 根级文档索引采用三层结构。Layer 1 用于快速定位，Layer 2 按主题交叉查找，Layer 3 给出重点文档摘要。SDK API 细节继续查看 `docs/sdk/INDEX.md`。
+
+---
+
+## Layer 1：文档地图
+
+| 文档 | 定位 |
+| --- | --- |
+| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
+| [跨语言容器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 透传方案 |
+| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE 手册的子索引 |
+| [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
+| [协议文档目录](protocol/) | AUN 协议相关文档 |
+| [审查与路线图目录](audit/) | 历史审查、修复路线图、测试补充清单 |
+| [superpowers 目录](superpowers/) | AUN SDK 规范类补充文档 |
+
+---
+
+## Layer 2：主题交叉索引
+
+### 测试与 E2E
+
+- 现有测试命令、容器名、单域/双域运行入口 → [aun测试运行指南](aun测试运行指南.md)
+- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- 多语言 SDK 测试缺口与补测清单 → [审查与路线图目录](audit/)
+
+### SDK 使用与协议
+
+- Python / TS / Go / JS SDK 使用手册、RPC 参数、E2EE 机制 → [SDK 文档索引](sdk/INDEX.md)
+- 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
+- 协议细节、子协议和消息格式 → [协议文档目录](protocol/)
+- agent.md 远程缓存、`remote_etag` / `local_etag`、消息信封 ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
+
+### 诊断与可观测性
+
+- RPC trace span、跨模块诊断字段、安全字段白名单 → [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md)
+- 测试日志路径、测试输出、容器日志查看 → [aun测试运行指南](aun测试运行指南.md)
+- 跨语言 E2E trace 字段、日志产物、失败分类 → [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+
+### E2EE 与跨语言一致性
+
+- SDK E2EE API、会话管理、ProtectedHeaders → [SDK 文档索引](sdk/INDEX.md)
+- E2EE V2 1DH/per-AID wrap、bootstrap 能力声明、服务端 fanout → [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md)
+- 共享测试向量、transcript 回放、Python / TS / Go / C++ E2EE 互通 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+
+---
+
+## Layer 3：重点文档摘要
+
+### aun测试运行指南
+
+记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
+
+### 跨语言容器E2E测试方案
+
+定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
+
+### E2EE V2 简化为 1DH + Per-AID Wrap 方案
+
+定义新 SDK 通过 bootstrap 入参声明 `e2ee_wrap_capabilities`，服务端再返回实际 `e2ee_wrap_policy`；旧 SDK 未声明时保留 legacy `3DH/device`。policy 不进入 envelope 或 AAD。方案规定 per-AID row 使用现有 8 字段结构并以 `device_id=""` 标识，服务端按真实 device fanout 但保存 `recipient_row_json` 原始 row，pull 时用原始 row 重建 recipient，确保 Merkle proof 和历史消息兼容。
+
+### AUN RPC Trace 增强设计
+
+设计 RPC trace 的 enter/exit span 结构，补充方法、AID、route、错误码、业务结果等诊断字段，并定义安全字段白名单。目标是在跨模块 RPC 失败时能定位到具体业务原因，而不是只看到模块路径和耗时。
+
+### 远程 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 一致性规则。
+
+### SDK 文档索引
+
+`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE、API 手册、错误处理、最佳实践、payload 和各类 RPC 手册。
+
+### SDK 查阅指南
+
+`docs/sdk/AUN_DOCS_GUIDE.md` 说明如何按行区间渐进式读取 SDK 文档，避免一次性加载过多文档内容。

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -0,0 +1,55 @@
+# Kite / AUN SDK Core 文档查阅指南
+
+AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API 子索引为 `docs/sdk/INDEX.md`。
+
+行区间格式：`L7-18` 表示读取第 7 行到第 18 行。需要查 SDK 细节时，优先进入 `docs/sdk/AUN_DOCS_GUIDE.md`，不要一次性读取整套 SDK 手册。
+
+## 渐进式查阅流程
+
+### Step 1：先读根级 Layer 1
+
+- `docs/INDEX.md` L7-20：根级文档地图。
+
+### Step 2：按主题读根级 Layer 2
+
+- 测试与 E2E：`docs/INDEX.md` L25-29。
+- SDK 使用与协议：`docs/INDEX.md` L31-36。
+- 诊断与可观测性：`docs/INDEX.md` L38-42。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L45-49。
+
+### Step 3：需要判断文档价值时读 Layer 3 摘要
+
+- `docs/INDEX.md` L53-81：重点文档摘要。
+
+### Step 4：再读目标文档章节
+
+只读取目标章节，不要默认读取全文。常用入口如下。
+
+## 常见查阅场景
+
+| 场景 | 推荐读取 |
+| --- | --- |
+| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
+| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L48-63 |
+| 单域 Docker 测试容器和命令 | `docs/aun测试运行指南.md` L113-533 |
+| 跨语言容器 E2E 执行方式 | `docs/aun测试运行指南.md` L146-263 |
+| 双域 federation 测试容器和命令 | `docs/aun测试运行指南.md` L534-714 |
+| 何时 rebuild / restart | `docs/aun测试运行指南.md` L715-762 |
+| 测试故障排查 | `docs/aun测试运行指南.md` L763-782 |
+| 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
+| E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
+| 跨语言 Docker 拓扑 | `docs/design/跨语言容器E2E测试方案.md` L37-76 |
+| 共享测试向量、CLI transcript、单域/双域分层 | `docs/design/跨语言容器E2E测试方案.md` L78-147 |
+| test-runner 如何控制不同语言 client | `docs/design/跨语言容器E2E测试方案.md` L149-158 |
+| test-control HTTP API | `docs/design/跨语言容器E2E测试方案.md` L160-305 |
+| 客户端容器要求和 Compose 建议 | `docs/design/跨语言容器E2E测试方案.md` L307-411 |
+| test-runner 标准用例流程 | `docs/design/跨语言容器E2E测试方案.md` L413-440 |
+| Python / TypeScript / Go / C++ 跨 SDK 测试矩阵 | `docs/aun测试运行指南.md` L210-228 |
+| 跨语言日志、trace、身份隔离、CLI 定位 | `docs/design/跨语言容器E2E测试方案.md` L514-576 |
+| 失败分类与落地阶段 | `docs/design/跨语言容器E2E测试方案.md` L579-625 |
+| 与现有测试环境的关系和验收标准 | `docs/design/跨语言容器E2E测试方案.md` L627-665 |
+| 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 |
+| 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

@@ -0,0 +1,328 @@
+# 远程 agent.md 缓存与 ETag 透传方案
+
+状态：方案草案
+
+## 目标
+
+让 SDK 在给对端发送消息、收到对端消息时，都能观察到对端云端 `agent.md` 的最新 ETag，并据此维护本机远程 `agent.md` 缓存状态。
+
+核心目标：
+
+- 每个远程 AID 在 SDK 本地内存中维护一条 `agent.md` 记录，包含 `remote_etag`、`local_etag`、`content`、`last_modified` 等字段。
+- 同一条远程缓存记录持久化到本地 SQLite 表，SDK 启动或内存 miss 时按需加载。
+- `message.send` 的 RPC 响应携带接收方 `agent.md` ETag，让发送方更新 `to` 的云端版本。
+- 接收端收到消息信封时携带发送方 `agent.md` ETag，让接收方更新 `from` 的云端版本。
+- ETag 只作为版本提示，不替代 `agent.md` 内容下载和验签。
+
+## 可行性结论
+
+方案可行。服务端已有 `agent.md` HEAD/ETag 能力，Gateway 当前也已经在 RPC response `_meta.agent_md_etag` 中注入“请求者自己”的服务端 ETag。需要扩展两条路径：
+
+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 时本地可能没有可用内容。
+
+## 字段建议
+
+消息信封新增字段：
+
+```json
+{
+  "agent_md": {
+    "sender": {
+      "aid": "alice.agentid.pub",
+      "etag": "\"sha256...\""
+    }
+  }
+}
+```
+
+`message.send` RPC response 的 `_meta` 新增字段：
+
+```json
+{
+  "_meta": {
+    "agent_md_etag": "\"sender-self-etag\"",
+    "agent_md_etags": {
+      "to": {
+        "aid": "bob.agentid.pub",
+        "etag": "\"sha256...\""
+      }
+    }
+  }
+}
+```
+
+兼容说明：
+
+- `_meta.agent_md_etag` 保持现有语义，仍表示请求者自己在服务端的 `agent.md` ETag。
+- `_meta.agent_md_etags.to` 表示本次消息接收方的 `agent.md` ETag。
+- `envelope.agent_md.sender` 表示本条消息发送方的 `agent.md` ETag。
+- 字段缺失、ETag 为空、HEAD 失败均不影响消息收发。
+
+## SDK 缓存模型
+
+每个远程 AID 在内存和 SQLite 表中都维护一条缓存记录。内存记录与 SQLite 表记录字段语义一致，SQLite 用于 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` |
+
+状态规则：
+
+- 收到远端 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`。
+- `verify_status=invalid` 时内容可以缓存但应用层应能看到无效状态；是否拒绝展示由上层策略决定。
+
+## 时序图
+
+### 发送消息时，发送端获得 to 的 agent.md ETag
+
+```mermaid
+sequenceDiagram
+    participant A as Sender SDK
+    participant GW as Gateway
+    participant MSG as Message Service
+    participant NS as NameService
+    participant DB as Message DB
+
+    A->>GW: RPC message.send(to=B, payload=v2 envelope)
+    GW->>MSG: 转发 send，附带 _auth.aid=A
+    MSG->>NS: HEAD https://A/agent.md<br/>取 sender ETag（缓存命中则不请求）
+    NS-->>MSG: ETag(A)
+    MSG->>MSG: 注入 envelope.agent_md.sender={aid:A, etag}
+    MSG->>DB: 持久化 envelope / wraps
+    MSG-->>GW: send result
+    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
+```
+
+### 接收消息时，接收端获得 from 的 agent.md ETag
+
+```mermaid
+sequenceDiagram
+    participant MSG as Message Service
+    participant B as Receiver SDK
+    participant Cache as SDK AgentMdCache
+    participant NS as NameService
+
+    MSG-->>B: peer.v2.message_received(seq, from=A)
+    B->>MSG: message.v2.pull(after_seq)
+    MSG-->>B: messages[].envelope_json<br/>包含 agent_md.sender={aid:A, etag}
+    B->>Cache: observeRemoteAgentMdEtag(A, etag)
+
+    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
+        B->>B: verify_agent_md(content, aid=A)
+        B->>Cache: 写内存 + SQLite
+    end
+```
+
+### SDK 本地缓存按需加载
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant SDK
+    participant Mem as Memory Cache
+    participant SQL as SQLite
+    participant NS as NameService
+
+    App->>SDK: fetchAgentMd(A) / getRemoteAgentMd(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->>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->>Mem: upsert
+        SDK->>SQL: upsert
+    end
+
+    SDK-->>App: agent.md content + signature + sync 状态
+```
+
+### agent.md 上传后的服务端缓存失效
+
+```mermaid
+sequenceDiagram
+    participant A as A SDK
+    participant NS as NameService
+    participant GW as Gateway
+    participant MSG as Message Service
+
+    A->>NS: PUT /agent.md
+    NS->>NS: 保存 content，生成新 ETag
+    NS-->>A: upload result + ETag
+    NS-->>GW: event nameservice.agent_md_updated(aid=A)
+    GW->>GW: invalidate agent_md_etag_cache[A]
+    NS-->>MSG: 可选同事件
+    MSG->>MSG: invalidate message-side agent_md_etag_cache[A]
+```
+
+## 服务端流程细化
+
+### Gateway
+
+现有行为：
+
+- `deliver_response_to_client` 会在 RPC response `_meta.agent_md_etag` 中注入请求者自己的 `agent.md` ETag。
+- ETag 获取采用本地 TTL 缓存，miss 时异步 HEAD 预热，不阻塞响应热路径。
+- `nameservice.agent_md_updated` 事件会失效对应 AID 的 Gateway ETag 缓存。
+
+新增行为：
+
+- 对 `message.send` 和未来真实启用的 `message.v2.send`，根据请求参数提取 `to`。
+- 在响应 `_meta.agent_md_etags.to` 中注入 `to` 的 ETag。
+- 注入逻辑应使用同一套 ETag 缓存和 HEAD fetcher。
+- 如果缓存 miss，第一轮响应可以不带 `to` ETag；后台预热后下一次消息或 RPC 再带上。
+- 如果产品希望“发送后立即拿到 to ETag”，可对 message send 做同步 HEAD，但应设置短超时并保证失败不影响发送。
+
+### Message Service
+
+现有 V2 路径：
+
+- SDK 加密 P2P 消息当前实际调用 `message.send`。
+- 服务端通过 payload `type=e2ee.p2p_encrypted` 且 `version=v2` 进入 `_rpc_send_v2_p2p`。
+- `_rpc_send_v2_p2p` 持久化 `protected_headers`、`context`，并在 `message.v2.pull` 时重建 `envelope_json`。
+
+新增行为：
+
+- 在 `_rpc_send_v2_p2p` 写入共享体前，为 `from_aid` 查询 `agent.md` ETag。
+- 将结果注入 envelope 顶层 `agent_md.sender`。
+- `agent_md` 应随 envelope 持久化并在 `_rebuild_v2_envelope_json` 中恢复。
+- 在线 push 事件可以只带 seq，不强制带完整 ETag；接收端通过 pull 取得完整信封即可。
+- V1 明文/旧 `message.send` 如需同样能力，可在传统 message envelope 中透传同等 `agent_md.sender` 字段。
+
+### NameService
+
+现有能力足够支撑：
+
+- `GET /agent.md` 与 `HEAD /agent.md` 返回 `ETag` 和 `Last-Modified`。
+- `PUT /agent.md` 上传后生成新 ETag。
+- 上传后发布 `nameservice.agent_md_updated` 事件，Gateway 已订阅并失效缓存。
+
+建议补齐：
+
+- 如果 Message Service 也维护自己的 ETag 缓存，应订阅同一事件或复用 Gateway 的注入结果。
+- HEAD 失败、404、超时返回空 ETag，不影响消息主链路。
+
+## SDK 流程细化
+
+### 观察远端 ETag
+
+SDK 增加统一入口：
+
+```text
+observe_remote_agent_md_etag(aid, etag, source)
+```
+
+触发来源：
+
+- RPC response `_meta.agent_md_etags.to`：发送消息后观察 `to`。
+- 消息信封 `agent_md.sender`：收到消息后观察 `from`。
+- 现有 `_meta.agent_md_etag`：仍用于当前客户端自己的云端 ETag。
+
+处理规则：
+
+- aid 或 etag 为空时忽略。
+- etag 与当前 `remote_etag` 相同：只刷新 `observed_at`。
+- etag 变化：更新 `remote_etag`、`observed_at`，并根据 `local_etag` 设置 `stale`。
+- 变更需要同时写入内存和 SQLite。
+
+### 按需下载
+
+当应用调用 `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++ 落各自现有本地存储。
+
+## 异常与竞态处理
+
+- 多个消息同时观察同一 AID 的新 ETag：按 ETag 值幂等 upsert。
+- 多个协程同时触发同一 AID 下载：需要 per-AID in-flight 去重。
+- 观察到 ETag A 后开始下载，期间又观察到 ETag B：下载完成时只更新 `local_etag=A`，随后仍保持 stale，下一轮继续拉 B。
+- 304 但本地 content 缺失：不能返回空内容，必须无条件 GET 重试。
+- 信封里的 ETag 不参与 AAD，不作为安全声明；安全性仍依赖 `agent.md` 签名和证书校验。
+- HEAD/GET 超时不影响 message send 和 message pull。
+- 跨域场景中，目标域 Message Service 注入 sender ETag 时可能需要跨域 HEAD；失败时允许缺字段。
+
+## 测试要点
+
+- 发送方收到 `message.send` 响应后，能把 `to` 的 ETag 写入本地缓存 `remote_etag`。
+- 接收方 `message.v2.pull` 后，能从 `envelope.agent_md.sender` 写入 `from` 的 `remote_etag`。
+- ETag 变化但内容未下载时，缓存状态为 stale。
+- 本地 SQLite 有缓存、内存为空时，SDK 能按需加载。
+- 304 且本地有内容时复用内容；304 但本地无内容时强制重拉。
+- `agent.md` 上传后，Gateway 缓存失效，后续消息能看到新 ETag。
+- HEAD/GET 404、超时、网络错误不影响消息收发主链路。
+- Python / TS / JS / Go / C++ 五个 SDK 对 `remote_etag`、`local_etag`、`content`、`stale` 语义一致。