@agentunion/fastaun 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -6,6 +6,44 @@
 
 ---
 
+## 0.4.8 — 2026-06-03
+
+### 新功能
+- `cert-utils.ts` 新增 `publicKeyFingerprint`、`certMatchesFingerprint`、`publicKeyMatchesFingerprint`、`normalizeFingerprintHex` 工具函数，支持 DER/SPKI 双格式及 16/64 位短格式（四语言对齐）
+- agent.md 签名块新增 `public_key_fingerprint` 可选字段，签名时自动附加 SPKI 指纹验证时同时校验（四语言对齐）
+- `peerResolver` 接口新增 `certFingerprint` 参数，`AgentMdManager._resolvePeer` 从签名块提取指纹后传入（四语言对齐）
+- `AIDStore.peerResolver` 改造：按指纹优先从 keystore 加载缓存；有指纹时从 PKI 精确拉取并缓存（四语言对齐）
+- `pkiCertUrl` 新增 `certFingerprint` 参数（四语言对齐）
+- 新增 `_v2SessionMatchesIdentity` / `_resetV2IdentityRuntime`，V2 session 校验升级为身份匹配（四语言对齐）
+- 新增在线未读 hint 队列（`_onlineUnreadHintQueue`），同 group 去重 + 延迟 drain（四语言对齐）
+- `_getV2SenderPubDer` 新增 `certFingerprint` 参数，解密时精确锁定发送方证书（四语言对齐）
+
+### 修复
+- `AIDStore` 构造函数移除 `deviceId` 可选参数，统一使用 `getDeviceId(aunPath)` 读取（四语言对齐）
+- `_applyAidRuntimeContext` 切换 AID 时新增旧 transport 清理并调用 `_resetV2IdentityRuntime`，防止 V2 session 残留（四语言对齐）
+- `_fetchPeerCert` 移除带指纹失败后的降级无指纹兜底请求（四语言对齐）
+- cert 缓存只在无 `certFingerprint` 时写裸 key，避免缓存污染（四语言对齐）
+- 指纹验证统一改用 `certMatchesFingerprint`（四语言对齐）
+- 解密结果新增 `attachGatewayProximity`，透传 `proximity`/`same_device`/`same_network`/`same_egress_ip` 字段（四语言对齐）
+
+### 优化
+- `AUNClient` 大规模拆分重构：client.ts 变为薄壳委托层，核心逻辑分散至 `client/` 子目录的 `ClientRuntime`、`LifecycleController`、`RpcPipeline`、`MessageDeliveryEngine`、`V2E2EECoordinator`、`GroupStateCoordinator`、`PeerDirectory`、`IdentityRuntimeManager` 子模块（四语言对齐）
+
+---
+
+## 0.4.7 — 2026-06-01
+
+### Added
+- **`AIDStore.uploadAgentMd(aid, content?)`**：将 `uploadAgentMd` 从 `AUNClient` 迁移到 `AIDStore`，支持指定任意本地 AID 上传 agent.md；内部独立创建 `LocalTokenStore` 和 `AuthFlow` 完成认证，不依赖 `AUNClient` 实例。
+- **`UploadAgentMdResult` 类型**：新增上传结果类型导出。
+
+### Changed
+- **`AUNClient.uploadAgentMd()`**：移除，功能迁移至 `AIDStore.uploadAgentMd(aid)`。
+- **`AIDStore`**：新增内部 `_tokenStore`（`LocalTokenStore`）和 `_crypto`（`CryptoProvider`）字段，供 upload 认证流程使用。
+- **`aid-db.ts`**：`slot_id_full` 列补齐逻辑提取为 `_ensureSlotIdFullColumns()` 私有方法，供多处复用。
+
+---
+
 ## 0.4.6 — 2026-06-01
 
 ### Added

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,44 @@
 
 ---
 
+## 0.4.8 — 2026-06-03
+
+### 新功能
+- `cert-utils.ts` 新增 `publicKeyFingerprint`、`certMatchesFingerprint`、`publicKeyMatchesFingerprint`、`normalizeFingerprintHex` 工具函数，支持 DER/SPKI 双格式及 16/64 位短格式（四语言对齐）
+- agent.md 签名块新增 `public_key_fingerprint` 可选字段，签名时自动附加 SPKI 指纹验证时同时校验（四语言对齐）
+- `peerResolver` 接口新增 `certFingerprint` 参数，`AgentMdManager._resolvePeer` 从签名块提取指纹后传入（四语言对齐）
+- `AIDStore.peerResolver` 改造：按指纹优先从 keystore 加载缓存；有指纹时从 PKI 精确拉取并缓存（四语言对齐）
+- `pkiCertUrl` 新增 `certFingerprint` 参数（四语言对齐）
+- 新增 `_v2SessionMatchesIdentity` / `_resetV2IdentityRuntime`，V2 session 校验升级为身份匹配（四语言对齐）
+- 新增在线未读 hint 队列（`_onlineUnreadHintQueue`），同 group 去重 + 延迟 drain（四语言对齐）
+- `_getV2SenderPubDer` 新增 `certFingerprint` 参数，解密时精确锁定发送方证书（四语言对齐）
+
+### 修复
+- `AIDStore` 构造函数移除 `deviceId` 可选参数，统一使用 `getDeviceId(aunPath)` 读取（四语言对齐）
+- `_applyAidRuntimeContext` 切换 AID 时新增旧 transport 清理并调用 `_resetV2IdentityRuntime`，防止 V2 session 残留（四语言对齐）
+- `_fetchPeerCert` 移除带指纹失败后的降级无指纹兜底请求（四语言对齐）
+- cert 缓存只在无 `certFingerprint` 时写裸 key，避免缓存污染（四语言对齐）
+- 指纹验证统一改用 `certMatchesFingerprint`（四语言对齐）
+- 解密结果新增 `attachGatewayProximity`，透传 `proximity`/`same_device`/`same_network`/`same_egress_ip` 字段（四语言对齐）
+
+### 优化
+- `AUNClient` 大规模拆分重构：client.ts 变为薄壳委托层，核心逻辑分散至 `client/` 子目录的 `ClientRuntime`、`LifecycleController`、`RpcPipeline`、`MessageDeliveryEngine`、`V2E2EECoordinator`、`GroupStateCoordinator`、`PeerDirectory`、`IdentityRuntimeManager` 子模块（四语言对齐）
+
+---
+
+## 0.4.7 — 2026-06-01
+
+### Added
+- **`AIDStore.uploadAgentMd(aid, content?)`**：将 `uploadAgentMd` 从 `AUNClient` 迁移到 `AIDStore`，支持指定任意本地 AID 上传 agent.md；内部独立创建 `LocalTokenStore` 和 `AuthFlow` 完成认证，不依赖 `AUNClient` 实例。
+- **`UploadAgentMdResult` 类型**：新增上传结果类型导出。
+
+### Changed
+- **`AUNClient.uploadAgentMd()`**：移除，功能迁移至 `AIDStore.uploadAgentMd(aid)`。
+- **`AIDStore`**：新增内部 `_tokenStore`（`LocalTokenStore`）和 `_crypto`（`CryptoProvider`）字段，供 upload 认证流程使用。
+- **`aid-db.ts`**：`slot_id_full` 列补齐逻辑提取为 `_ensureSlotIdFullColumns()` 私有方法，供多处复用。
+
+---
+
 ## 0.4.6 — 2026-06-01
 
 ### Added

package/_packed_docs/INDEX.md

@@ -8,11 +8,15 @@
 
 | 文档 | 定位 |
 | --- | --- |
-| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
-| [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md) | 本轮 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 设计 |
+| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
+| [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md) | 本轮 SDK 重构的实际修改点、测试结果和遗留事项 |
+| [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md) | Python / Go / TS / JS SDK AUNClient 内部拆分边界、执行步骤和验收矩阵 |
+| [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md) | AUNClient 完全门面化、ClientRuntime 单一状态源和四端分批迁移步骤 |
+| [跨语言容器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 设计 |
+| [AUN 服务端消息通信诊断面板方案](design/AUN服务端消息通信诊断面板方案.md) | aun-console 消息通信页的服务端可观察诊断面板总体方案 |
+| [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md) | aun-console 消息通信页的服务端可观察 P0 诊断面板 |
 | [远程 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 文档按行区间渐进式查阅方法 |
@@ -26,9 +30,11 @@
 
 ### 测试与 E2E
 
-- 现有测试命令、容器名、单域/双域运行入口 → [aun测试运行指南](aun测试运行指南.md)
-- 本轮 SDK 重构阶段进度、修改点和测试结果 → [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md)
-- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- 现有测试命令、容器名、单域/双域运行入口 → [aun测试运行指南](aun测试运行指南.md)
+- 本轮 SDK 重构阶段进度、修改点和测试结果 → [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md)
+- AUNClient 巨类拆分、内部组件边界、逐步迁移和验收矩阵 → [AUNClient 拆分重构执行方案](design/AUNClient拆分重构执行方案.md)
+- AUNClient 完全门面化、Runtime 状态归属、状态写入收口和四端分批实施 → [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md)
+- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 - 多语言 SDK 测试缺口与补测清单 → [审查与路线图目录](audit/)
 
 ### SDK 使用与协议
@@ -40,8 +46,10 @@
 
 ### 诊断与可观测性
 
-- RPC trace span、跨模块诊断字段、安全字段白名单 → [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md)
-- 测试日志路径、测试输出、容器日志查看 → [aun测试运行指南](aun测试运行指南.md)
+- RPC trace span、跨模块诊断字段、安全字段白名单 → [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md)
+- aun-console 消息通信服务端可观察总体面板、事实/推断边界 → [AUN 服务端消息通信诊断面板方案](design/AUN服务端消息通信诊断面板方案.md)
+- 服务端可观察的消息通信 P0 面板、过滤语义、数据来源 → [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md)
+- 测试日志路径、测试输出、容器日志查看 → [aun测试运行指南](aun测试运行指南.md)
 - 跨语言 E2E trace 字段、日志产物、失败分类 → [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 
 ### E2EE 与跨语言一致性
@@ -58,23 +66,39 @@
 
 记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
 
-### AUN SDK 重构修改清单
-
-记录本轮 AUN SDK 重构执行中的阶段进度、实际修改点、测试命令、测试结果和遗留事项。它是实施过程中的工作清单，最终以 SDK 文档和 skill 同步结果为准。
-
-### 跨语言容器E2E测试方案
-
-定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
+### AUN SDK 重构修改清单
+
+记录本轮 AUN SDK 重构执行中的阶段进度、实际修改点、测试命令、测试结果和遗留事项。它是实施过程中的工作清单，最终以 SDK 文档和 skill 同步结果为准。
+
+### AUNClient 拆分重构执行方案
+
+定义在不改变公开 API、协议字段、事件名和默认行为的前提下，如何把 Python / Go / TypeScript / JavaScript SDK 的 `AUNClient` 拆为内部门面、运行时上下文、生命周期控制、RPC 流水线、消息投递、V2 E2EE、群状态和 peer 目录等组件。文档给出 19 个执行步骤、跨 SDK 迁移顺序、风险点和验收矩阵，并记录当前进度：Python 已形成组件化参考实现，TS/JS/Go 已完成 runtime、identity、peers、lifecycle 和 `RpcPipeline` preflight/签名/pull gate/raw call 接入。
+
+### AUNClient 门面化与 Runtime 状态迁移细化方案
+
+在既有 AUNClient 拆分方案基础上，进一步定义“完全门面化、状态全部迁入 runtime”的完成标准和分步执行方法。文档给出状态归属表，将身份与配置、基础依赖、生命周期、RPC、消息投递、V2 E2EE、群状态和 peer 状态分别归入 runtime 与对应 coordinator，并按 Step 0 到 Step 10 说明基线建立、ClientRuntime 状态分区、identity/lifecycle/RPC/delivery/V2/group state 迁移、runtime 写入接口收口、shim 清理、四端 parity 验证和回滚策略。
+
+### 跨语言容器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 透传方案
+### AUN RPC Trace 增强设计
+
+设计 RPC trace 的 enter/exit span 结构，补充方法、AID、route、错误码、业务结果等诊断字段，并定义安全字段白名单。目标是在跨模块 RPC 失败时能定位到具体业务原因，而不是只看到模块路径和耗时。
+
+### AUN 服务端消息通信诊断面板方案
+
+记录 aun-console“消息通信”页面的服务端可观察诊断总体方案。方案明确只展示 Gateway、Message/Group、Federation、Service Plane 和模块业务指标可观察事实，不依赖 SDK 诊断模式，不读取 SDK 本地状态，并定义发送端、接收端、消息 ID、Group ID、关键词和任意方向过滤语义。服务端自主 Trace 默认关闭，只能通过面板临时开启。
+
+### 服务端消息通信诊断面板 P0 方案
+
+定义 aun-console 消息通信页的 P0 服务端诊断面板。范围限定为 Gateway、Message/Group、Federation 和 Service Plane 可观察事实，不采集 SDK 本地状态。文档给出发送端、接收端、消息 ID、Group ID 和任意方向过滤语义，并定义服务端 Trace、投递路径、Pull/ACK/GAP、E2EE、Federation、Service Plane 六个子标签，其中服务端自主 Trace 是默认关闭的运行时开关，`message.ack` 需区分 RPC 与同名事件的设备字段语义。
+
+### 远程 agent.md 缓存与 ETag 透传方案
 
 定义每个远程 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 一致性规则。
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -8,18 +8,18 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ### Step 1：先读根级 Layer 1
 
-- `docs/INDEX.md` L7-21：根级文档地图。
+- `docs/INDEX.md` L7-25：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L27-32。
-- SDK 使用与协议：`docs/INDEX.md` L34-39。
-- 诊断与可观测性：`docs/INDEX.md` L41-45。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L47-51。
+- 测试与 E2E：`docs/INDEX.md` L31-38。
+- SDK 使用与协议：`docs/INDEX.md` L40-45。
+- 诊断与可观测性：`docs/INDEX.md` L47-53。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L55-59。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L55-87：重点文档摘要。
+- `docs/INDEX.md` L63-111：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -29,17 +29,21 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 | 场景 | 推荐读取 |
 | --- | --- |
-| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
-| 本轮 SDK 重构修改清单 | `docs/AUN_SDK_重构修改清单.md` |
-| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L48-63 |
+| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
+| 本轮 SDK 重构修改清单 | `docs/AUN_SDK_重构修改清单.md` |
+| AUNClient 巨类拆分重构执行方案 | `docs/design/AUNClient拆分重构执行方案.md` L3-252、L253-698、L699-803 |
+| AUNClient 完全门面化与 Runtime 状态迁移细化方案 | `docs/design/AUNClient门面化与Runtime状态迁移细化方案.md` |
+| 测试环境数据保护规则 | `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 |
+| 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
+| E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
+| 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
+| 服务端消息通信 P0 诊断面板 | `docs/design/服务端消息通信诊断面板P0方案.md` L3-73 |
+| 跨语言 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 |