@agentunion/fastaun-browser 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -6,6 +6,80 @@
 
 ---
 
+## 0.5.8 — 2026-08-30
+
+### 新功能
+
+#### AID 注册与 agent.md
+- `AIDStore.register()` 默认生成符合 schema 的 `agent.md`（`aid`、`type: "agent"` 等字段），使用对应 AID 签名并上传；`uploadAgentMd()` 仍可按需显式替换内容，也支持由另一个本地 uploader AID 认证代传。
+- 增加 agent.md 的严格 frontmatter、UTF-8/Base64、大小、证书有效期、证书指纹、公钥指纹和签名校验；校验失败不会覆盖已有内容或可信缓存。
+- 新版本连接能力声明 `agent_md_validation_v1`；收到缺少 agent.md 的 `-32003` 时自动生成、签名、上传并重试原 RPC。恢复只针对当前 AID，群 agent.md 恢复只由持有 group AID 私钥的群主执行。
+
+#### 群身份与 group agent.md
+- 命名群的 `createGroup()` 在 `group.create` 时携带新生成的 group AID 公钥和曲线，并要求服务端返回匹配的 group AID 证书；匿名群先创建，再按原始 `groupId` 绑定证书并导入本地 group AID。
+- `bindGroupAid()`、`renewGroupAid()` 和群主转移完成流程校验证书、公钥和用途，并自动上传 `type: "group"` 的 group agent.md；内容由 group AID 签名，群主 AID 负责认证上传。
+- group agent.md 可以事后上传，但在上传有效证书和 agent.md 前，群管理、群消息、`group.fs` 等后续群 RPC 继续受 Gateway 限制；历史群缺证书或缺 group agent.md 的自动修复仅允许群主执行。
+
+### 安全性
+
+- Gateway 在 client-vs-gateway RPC 入口校验客户端 agent.md、普通 AID 证书、group AID 证书及 group agent.md；`group.create`、`group.bindGroupAid`、`group.renewGroupAid` 等建群/绑定例外保留必要的恢复路径。
+- 上述准入只对 connect 协商声明 `agent_md_validation_v1` 的新 SDK 生效，未声明能力的旧 SDK 保持原有行为；Gateway 同时收紧 AID type、group namespace、RPC 目标和路由边界校验。
+- agent.md、证书和身份解析采用带 TTL 的正/负缓存，支持并发请求合并、容量上限及 CA 写入、agent.md 上传和相关事件触发的失效；代际校验防止过期查询回写缓存。
+
+### 修复
+
+#### Pull gate 与未读提示
+- `AUNClient` 统一使用一个 pull gate 和队列，前台 pull 优先于后台 pull，二者共享 namespace 去重；P2P 作为一个 namespace，每个 group 独立 namespace，后台请求不旁路也不丢弃。
+- pull 生命周期纳入 `idle`、`pulling`、`processing` 等状态和专用 watchdog；从拉取开始计时，约 3 秒超时即复位并继续队列，应用触发和新 push 会主动唤醒状态机。续拉在响应处理完成后重新入队并置于队尾。
+- `client.online` 时服务端为 P2P 及存在未读消息或事件的群发送 unread hint；SDK 每条 hint 转换为一次 background forward pull，按 namespace 去重。
+
+#### V2 消息窗口与游标
+- Forward 页忽略页内空洞并推进到 pulled page 最大 seq；先完成解密/发布，再一次性提交本页连续游标并发送 ACK 或 piggyback ACK。缺少 SPK/IK 时异步 bootstrap，不阻塞页处理；有密钥但解密失败时发布结构化失败事件后再推进游标。
+- 修正 P2P/群 V2 的 1DH/3DH、IK/SPK bootstrap、self-sync、forward cursor/ACK、重叠页去重及跨页有序投递；服务端 ACK 水位不足时保留待确认状态并在后续 pull 重试。
+- Message/Group thought 存储与响应结构统一，并增加响应预算/大小限制；Go `CollabActionResult` 兼容 `removed` 布尔值和整数格式。
+
+#### Gateway 与服务连接可靠性
+- 加固 service attach、连接替换、关闭码、协议错误预算、超时以及 reader/close 竞态；Python/Go 服务端行为和合同测试保持一致。
+- nameservice agent.md upsert、上传验证及数据库/快照兼容性同步修正；SDK 测试器使用阿里云 PyPI 镜像缓解下载超时。
+
+### 改进
+
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 更新为 `0.5.8`。
+- 低层 agent.md 上传能力继续由 `AIDStore` 提供，`AUNClient` 通过高层注册、建群和恢复流程编排；agent.md 替换仍保留为可选、按需操作。
+
+### 测试
+
+- 新增 AID 类型和 Gateway 路由准入的单元、集成、E2E 及跨 SDK 测试，覆盖新旧能力声明、证书/agent.md 缺失恢复、群主权限和缓存失效。
+- 扩展 agent.md、群身份绑定/续期、group.fs、V2 E2EE、pull gate 状态机、unread hint、游标/ACK、thought 响应预算和服务连接合同测试。
+
+## 0.5.7 — 2026-08-20
+
+### 新功能
+
+#### 首次连接自动重试
+- `connect()` 在首次 discovery、认证或 Gateway WebSocket 建连遇到可重试的瞬时错误时，进入与断线重连一致的指数退避生命周期；每轮重新执行完整 discovery/认证并使用最新凭据。
+- 认证、权限、参数和状态类永久错误仍立即返回，不创建后台重连任务。
+
+#### Mail facade 与当前令牌 API
+- 新增 `client.mail` / `MailFacade`，提供 `send()`、`get()`、`list()`、`delete()`、`move()`、`mark()`、`search()`、`getAttachment()`、`getQuota()`、`health()` 和 `status()`；`mail.send` 按非幂等 RPC 使用 35 秒超时。
+- 新增 `getAccessToken()`，同步读取后台刷新任务维护的最新 access token，供应用在每次外部 HTTP 数据面请求前取用；getter 本身不发起认证、刷新或网络请求。
+
+### 修复
+
+- 引入重连代际所有权；显式 `connect()` / `disconnect()` / `close()` 可终止旧重连代，旧任务不能清理或覆盖新连接，事件回调内触发生命周期操作也不会自锁。
+- 收口群 ID 语义：`g-` 不再具有特殊含义，所有群 base 统一按 4–64 字符规则校验；移除 `base@issuer` 兼容输入，仅保留 `group.{issuer}/{base}`、`base.issuer` 和本域短格式。
+- `stream/created` 和 `stream/closed` 内部事件重新发布给公共订阅者。
+- Group tail/history 遇到缺失 payload 的不完整 V1 行时采用有界跳过或失败语义，避免阻断后续同步。
+
+### 改进
+
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.7`。
+
+### 测试
+
+- 新增首连认证/建连失败、永久错误、重连代际取消、事件回调重入、最新 token getter 和 Mail facade 单元测试。
+- 扩展群 ID 校验、浏览器跨域 Group FS、新设备群历史同步、V2 E2EE 和 replay guard E2E 测试。
+
 ## 0.5.6 — 2026-08-13
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,80 @@
 
 ---
 
+## 0.5.8 — 2026-08-30
+
+### 新功能
+
+#### AID 注册与 agent.md
+- `AIDStore.register()` 默认生成符合 schema 的 `agent.md`（`aid`、`type: "agent"` 等字段），使用对应 AID 签名并上传；`uploadAgentMd()` 仍可按需显式替换内容，也支持由另一个本地 uploader AID 认证代传。
+- 增加 agent.md 的严格 frontmatter、UTF-8/Base64、大小、证书有效期、证书指纹、公钥指纹和签名校验；校验失败不会覆盖已有内容或可信缓存。
+- 新版本连接能力声明 `agent_md_validation_v1`；收到缺少 agent.md 的 `-32003` 时自动生成、签名、上传并重试原 RPC。恢复只针对当前 AID，群 agent.md 恢复只由持有 group AID 私钥的群主执行。
+
+#### 群身份与 group agent.md
+- 命名群的 `createGroup()` 在 `group.create` 时携带新生成的 group AID 公钥和曲线，并要求服务端返回匹配的 group AID 证书；匿名群先创建，再按原始 `groupId` 绑定证书并导入本地 group AID。
+- `bindGroupAid()`、`renewGroupAid()` 和群主转移完成流程校验证书、公钥和用途，并自动上传 `type: "group"` 的 group agent.md；内容由 group AID 签名，群主 AID 负责认证上传。
+- group agent.md 可以事后上传，但在上传有效证书和 agent.md 前，群管理、群消息、`group.fs` 等后续群 RPC 继续受 Gateway 限制；历史群缺证书或缺 group agent.md 的自动修复仅允许群主执行。
+
+### 安全性
+
+- Gateway 在 client-vs-gateway RPC 入口校验客户端 agent.md、普通 AID 证书、group AID 证书及 group agent.md；`group.create`、`group.bindGroupAid`、`group.renewGroupAid` 等建群/绑定例外保留必要的恢复路径。
+- 上述准入只对 connect 协商声明 `agent_md_validation_v1` 的新 SDK 生效，未声明能力的旧 SDK 保持原有行为；Gateway 同时收紧 AID type、group namespace、RPC 目标和路由边界校验。
+- agent.md、证书和身份解析采用带 TTL 的正/负缓存，支持并发请求合并、容量上限及 CA 写入、agent.md 上传和相关事件触发的失效；代际校验防止过期查询回写缓存。
+
+### 修复
+
+#### Pull gate 与未读提示
+- `AUNClient` 统一使用一个 pull gate 和队列，前台 pull 优先于后台 pull，二者共享 namespace 去重；P2P 作为一个 namespace，每个 group 独立 namespace，后台请求不旁路也不丢弃。
+- pull 生命周期纳入 `idle`、`pulling`、`processing` 等状态和专用 watchdog；从拉取开始计时，约 3 秒超时即复位并继续队列，应用触发和新 push 会主动唤醒状态机。续拉在响应处理完成后重新入队并置于队尾。
+- `client.online` 时服务端为 P2P 及存在未读消息或事件的群发送 unread hint；SDK 每条 hint 转换为一次 background forward pull，按 namespace 去重。
+
+#### V2 消息窗口与游标
+- Forward 页忽略页内空洞并推进到 pulled page 最大 seq；先完成解密/发布，再一次性提交本页连续游标并发送 ACK 或 piggyback ACK。缺少 SPK/IK 时异步 bootstrap，不阻塞页处理；有密钥但解密失败时发布结构化失败事件后再推进游标。
+- 修正 P2P/群 V2 的 1DH/3DH、IK/SPK bootstrap、self-sync、forward cursor/ACK、重叠页去重及跨页有序投递；服务端 ACK 水位不足时保留待确认状态并在后续 pull 重试。
+- Message/Group thought 存储与响应结构统一，并增加响应预算/大小限制；Go `CollabActionResult` 兼容 `removed` 布尔值和整数格式。
+
+#### Gateway 与服务连接可靠性
+- 加固 service attach、连接替换、关闭码、协议错误预算、超时以及 reader/close 竞态；Python/Go 服务端行为和合同测试保持一致。
+- nameservice agent.md upsert、上传验证及数据库/快照兼容性同步修正；SDK 测试器使用阿里云 PyPI 镜像缓解下载超时。
+
+### 改进
+
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 V2 E2EE envelope `sdk_version` 更新为 `0.5.8`。
+- 低层 agent.md 上传能力继续由 `AIDStore` 提供，`AUNClient` 通过高层注册、建群和恢复流程编排；agent.md 替换仍保留为可选、按需操作。
+
+### 测试
+
+- 新增 AID 类型和 Gateway 路由准入的单元、集成、E2E 及跨 SDK 测试，覆盖新旧能力声明、证书/agent.md 缺失恢复、群主权限和缓存失效。
+- 扩展 agent.md、群身份绑定/续期、group.fs、V2 E2EE、pull gate 状态机、unread hint、游标/ACK、thought 响应预算和服务连接合同测试。
+
+## 0.5.7 — 2026-08-20
+
+### 新功能
+
+#### 首次连接自动重试
+- `connect()` 在首次 discovery、认证或 Gateway WebSocket 建连遇到可重试的瞬时错误时，进入与断线重连一致的指数退避生命周期；每轮重新执行完整 discovery/认证并使用最新凭据。
+- 认证、权限、参数和状态类永久错误仍立即返回，不创建后台重连任务。
+
+#### Mail facade 与当前令牌 API
+- 新增 `client.mail` / `MailFacade`，提供 `send()`、`get()`、`list()`、`delete()`、`move()`、`mark()`、`search()`、`getAttachment()`、`getQuota()`、`health()` 和 `status()`；`mail.send` 按非幂等 RPC 使用 35 秒超时。
+- 新增 `getAccessToken()`，同步读取后台刷新任务维护的最新 access token，供应用在每次外部 HTTP 数据面请求前取用；getter 本身不发起认证、刷新或网络请求。
+
+### 修复
+
+- 引入重连代际所有权；显式 `connect()` / `disconnect()` / `close()` 可终止旧重连代，旧任务不能清理或覆盖新连接，事件回调内触发生命周期操作也不会自锁。
+- 收口群 ID 语义：`g-` 不再具有特殊含义，所有群 base 统一按 4–64 字符规则校验；移除 `base@issuer` 兼容输入，仅保留 `group.{issuer}/{base}`、`base.issuer` 和本域短格式。
+- `stream/created` 和 `stream/closed` 内部事件重新发布给公共订阅者。
+- Group tail/history 遇到缺失 payload 的不完整 V1 行时采用有界跳过或失败语义，避免阻断后续同步。
+
+### 改进
+
+- SDK 包版本、锁文件版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.7`。
+
+### 测试
+
+- 新增首连认证/建连失败、永久错误、重连代际取消、事件回调重入、最新 token getter 和 Mail facade 单元测试。
+- 扩展群 ID 校验、浏览器跨域 Group FS、新设备群历史同步、V2 E2EE 和 replay guard E2E 测试。
+
 ## 0.5.6 — 2026-08-13
 
 ### 新功能

package/_packed_docs/INDEX.md

@@ -24,16 +24,16 @@
 | [AUN 服务端消息通信诊断面板方案](design/AUN服务端消息通信诊断面板方案.md) | aun-console 消息通信页的服务端可观察诊断面板总体方案 |
 | [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md) | aun-console 消息通信页的服务端可观察 P0 诊断面板 |
 | [消息收件箱统一迁移方案](design/消息收件箱统一迁移方案.md) | P2P `message_inbox` 与群消息 `group_inbox` 的统一读模型、后台回填和旧表清理方案 |
-| [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
-| [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
+| [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
+| [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
 | [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md) | `group.index` 签名索引、`_meta.group_indexes` 版本提示、CAS 更新、服务端缓存注入和附件稳定引用 |
-| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、Python Push 自动登记/Facade、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
+| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、四 SDK 当前 access token getter、Python Push 自动登记/Facade、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md) | 以 0.5.5 为基线的四 SDK 发布汇总；覆盖首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 和语言能力边界 |
 | [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.6 跨语言对齐清单；0.5.6 重点覆盖首次签名者发现、下载提交前验签、消息窗口、inline push、显式 change-seed 与语言能力边界 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI 源码位置、安装运行入口、全局选项、profile 配置和主要命令集 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
-| [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、服务端分层和 direct backend 上传下载 |
+| [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、服务端分层和 direct backend 上传下载 |
 | [AUN Storage SDK 存储分层设计](<aun-fs/SDK存储分层设计.md>) | Python SDK StorageVFS / StorageLowLevel 接口契约、返回类型、错误映射和跨语言对齐要求 |
 | [AUN Storage CLI-fs 命令设计](<aun-fs/CLI-fs命令设计.md>) | `aun fs` 命令语义、寻址规则、输出格式、CLI 工程改造和端到端场景 |
 | [AUN Storage 分阶段实施计划](<aun-fs/分阶段实施计划.md>) | AUN Storage VFS + CLI 的 6 阶段 TDD 实施计划、P1-P6 实际执行记录和验收口径 |
@@ -83,12 +83,13 @@
 ### SDK 使用与协议
 
 - Python / TS / Go / JS SDK 使用手册，以及 Python `push_notify_aid` connect 自动登记和 PushFacade → [SDK 文档索引](sdk/INDEX.md)
+- 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 → [连接与认证](sdk/04-连接与认证.md)、[API 手册](sdk/06-API手册.md)、[Storage RPC 手册](sdk/09-storage-rpc-manual.md)、[AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
 - 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
 - 四 SDK 0.5.6 发布摘要、首次签名者回源、可信缓存提交、消息窗口、语言能力边界 → [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md)
 - 四 SDK 相对发布基线的实现级差异、代码/测试落点、对齐优先级、首次签名者发现、可信缓存和显式 change-seed 边界 → [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)
 - Python CLI 源码位置、安装运行入口、全局选项、profile 配置、身份/消息/群组/Storage/Group FS/Collab/诊断等命令用法 → [AUN CLI 手册](cli/CLI手册.md)
 - Python CLI 当前实现架构、`main.py` 命令注册、`CLISession` SDK 桥接、配置解析和实现边界 → [AUN CLI 设计文档](cli/AUN-CLI设计文档.md)
-- Storage SDK VFS、控制面/数据面分离、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
+- Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
 - StorageVFS / StorageLowLevel 接口契约、NodeView/ObjectView、错误映射和跨语言对齐 → [AUN Storage SDK 存储分层设计](<aun-fs/SDK存储分层设计.md>)
 - `aun fs` 命令语义、AID 路径解析、输出格式和 CLI 到 SDK 的调用边界 → [AUN Storage CLI-fs 命令设计](<aun-fs/CLI-fs命令设计.md>)
 - AUN Storage 6 阶段 TDD 计划、P1/P2/P3/P4/P5/P6 实际执行记录、阶段实施前详细计划和 Docker 验证纪律 → [AUN Storage 分阶段实施计划](<aun-fs/分阶段实施计划.md>)
@@ -102,7 +103,7 @@
 - 终端如何登记、Push Server 如何签发 token、接收批次、平台推送、幂等 ACK，以及如何运行 Mock smoke → [AUN 离线推送接入与演示指南](AUN离线推送接入与演示指南.md)
 - P2P/Group 离线唤醒、Python connect/Facade 登记、六项冻结契约、9 Phase/40 Task、发布门和回滚 → [离线推送协议](protocol/15-离线推送通知协议.md)、[Push Service 设计](superpowers/specs/2026-07-24-push-service-design-v3.md)、[契约冻结](superpowers/契约冻结-v3-to-v4.md)、[v4 实施计划](superpowers/plans/2026-07-24-push-service-implementation-v4.md)、[运维与发布指南](AUN离线推送服务运维与发布指南.md)；[旧 Codex 版本](AUN离线推送服务架构与详细实现计划-codex.md)仅作历史背景
 - 协议细节、Agent 自主行为、群 `mention_mode` 提及过滤和消息格式 → [协议文档目录](protocol/)、[Group 子协议](protocol/10-Group-子协议.md)、[Agent 行为规范](protocol/13-Agent行为规范.md)
-- agent.md 远程缓存、`remote_etag` / `local_etag`、`requester` / `peer` / `group` 角色、消息信封与 Gateway `_meta` ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
+- agent.md 远程缓存、`remote_etag` / `local_etag`、`requester` / `peer` / `group` 角色、消息信封与 Gateway `_meta` ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
 - `group.index` owner/admin SDK 生成签名索引、`_meta.group_indexes` 观察、`expected_index_etag` CAS、服务端正/负缓存与注入频率控制 → [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md)、[SDK 文档索引](sdk/INDEX.md)
 
 ### Service Proxy 与服务暴露
@@ -195,10 +196,10 @@
 
 定义 AUN Service Proxy / AUN 服务代理的整体方案：服务侧新增 `service_proxy` 模块，`service-proxy-server` 负责公网 HTTP/HTTPS 入口、WSS 隧道、在线连接索引和协议桥接；SDK 侧 `service-proxy-client` 负责 provider 侧 embedded registry、本地 endpoint 调用和服务摘要上报。方案明确去掉 ACP GlobalRegistry/RSA 同步，URL 以 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 为 canonical，`https://{user_name}.{issuer}/proxy/{svc_name}/...` 由 NameService 跳转；Web 服务推荐 host-root 模式，目录式 path-prefix 只做受限转发。文档还按 Phase 0 到 Phase 11 给出 TDD 实施步骤，记录 Phase 10 已新增宿主机进程内 7 类 HTTP/SSE/WS/NameService/Web/ACL/双域边界 E2E，以及单域和双域 Docker E2E 脚本入口；真实 Docker 执行仍需先满足模块启用、镜像包含新模块和 `/ws/client` AUN 身份 resolver 前置条件。
 
-### 远程 agent.md 缓存与 ETag 透传方案
-
-定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案规定 Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中按 `requester`、`peer`、`group` 注入元数据，保留旧别名兼容，并通过 300 秒正缓存、60 秒负缓存和默认 60 秒发送节流控制热路径开销；Message Service V2 P2P 信封携带 `agent_md.sender`。四端 SDK 自动观察 `_meta` 和信封 `agent_md.sender/group`，写入 `remote_etag` / `last_modified`，并遵守按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
-
+### 远程 agent.md 缓存与 ETag 透传方案
+
+定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案规定 Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中按 `requester`、`peer`、`group` 注入元数据，保留旧别名兼容，并通过 300 秒正缓存、60 秒负缓存和默认 60 秒发送节流控制热路径开销；Message Service V2 P2P 信封携带 `agent_md.sender`。四端 SDK 自动观察 `_meta` 和信封 `agent_md.sender/group`，写入 `remote_etag` / `last_modified`，并遵守按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
+
 ### 群索引版本提示与附件引用方案
 
 定义 `group.index` 的 owner/admin SDK 生成、canonical JSONL、签名、`etag` / `body_hash`、`expected_index_etag` CAS、`_meta.group_indexes` 版本提示、Gateway/Message 转发边界、服务端正/负缓存、singleflight、写后失效/刷新、注入频率控制，以及 DB 保存核心设置、group.fs 保存大附件、附件稳定引用和 SDK `check/get/updateGroupIndex` 语义。
@@ -233,7 +234,7 @@
 
 ### AUN Storage 架构设计
 
-定义 AUN Storage 的 SDK VFS、low-level storage client、Storage Service、Storage Core、Metadata Engine 和 Blob Backend 分层。文档明确大文件主数据流量直连 localfs/OSS/S3/COS backend，控制面通过 `storage.*` RPC 管理权限、配额、session/ticket、元数据提交和事件；普通应用通过 SDK VFS 使用类 POSIX 文件操作，底层 session/ticket/complete RPC 保留给 SDK 和高级客户端。文档还定义类 Linux mode/ACL、目录 `x` 位、mount/unmount、symlink/readlink/lstat、share link 与 direct backend ticket 的授权边界。
+定义 AUN Storage 的 SDK VFS、low-level storage client、Storage Service、Storage Core、Metadata Engine 和 Blob Backend 分层。文档明确大文件主数据流量直连 localfs/OSS/S3/COS backend，控制面通过 `storage.*` RPC 管理权限、配额、session/ticket、元数据提交和事件；普通应用通过 SDK VFS 使用类 POSIX 文件操作，底层 session/ticket/complete RPC 保留给 SDK 和高级客户端。文档还定义下载 ticket 与 AID Bearer 的语义边界、跨 issuer 下载和当前 access token getter 用法，以及类 Linux mode/ACL、目录 `x` 位、mount/unmount、symlink/readlink/lstat、share link 与 direct backend ticket 的授权边界。
 
 ### AUN Storage SDK 存储分层设计
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -48,7 +48,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 消息同步 TDD、Gateway、兼容性和分布式 E2E 门禁 | `docs/消息同步与历史拉取改造方案.md` L434-750 |
 | 当前实现的代码审查结论、P0/P1/P2 问题与跨语言差异 | `docs/消息同步与历史拉取代码审查问题清单.md` L3-207 |
 | 消息同步问题修复顺序与已排除误报 | `docs/消息同步与历史拉取代码审查问题清单.md` L208-229 |
-| SDK 中如何使用 History、理解页内发布边界、缺 sender IK 有界同步 bootstrap、应用幂等、坏密文推进和 Piggy ACK | `docs/sdk/03-核心概念.md` L60-80、`docs/sdk/05-E2EE加密通信.md` L33-56、`docs/sdk/08-最佳实践.md` L89-116、`docs/sdk/09-message-rpc-manual.md` L278-395、`docs/sdk/09-group-rpc-manual.md` L1282-1353、L1548-1587 |
+| SDK 中如何使用 History、理解页内发布边界、缺 sender IK 有界同步 bootstrap、应用幂等、坏密文推进和 Piggy ACK | `docs/sdk/03-核心概念.md` L60-80、`docs/sdk/05-E2EE加密通信.md` L33-56、`docs/sdk/08-最佳实践.md` L89-116、`docs/sdk/09-message-rpc-manual.md` L278-395、`docs/sdk/09-group-rpc-manual.md` L1282-1353、L1547-1605 |
 | 测试环境数据保护规则 | `docs/aun测试运行指南.md` L145-161 |
 | 默认单实例 Docker 服务端、Tester 和常规测试命令 | `docs/aun测试运行指南.md` L171-317、L501-827 |
 | 断网依赖准备、Go 1.24 和 Tester 复用纪律 | `docs/aun测试运行指南.md` L103-144、L171-317、`docs/aun分布式测试运行指南.md` L318-484 |
@@ -71,7 +71,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 离线 Push Service 协议、持久状态机、调度、生产者、安全、生命周期和验证范围 | `docs/superpowers/specs/2026-07-24-push-service-design-v3.md` L78-265 |
 | `query_sessions`、Push RPC/ACK、状态汇总、dispatch 恢复、Gateway ACL、关闭顺序、横向约束和 TDD 执行原则的冻结契约 | `docs/superpowers/契约冻结-v3-to-v4.md` L15-273 |
 | 离线 Push Service 相关文档、实施原则、Phase/Task TDD 门禁及 9 个 Phase、40 个 Task | `docs/superpowers/plans/2026-07-24-push-service-implementation-v4.md` L5-213 |
-| Python SDK 的 `connect()` 自动登记和 `client.push.register/unregister` 运行期接口 | `docs/sdk/04-连接与认证.md` L105-132、`docs/sdk/06-API手册.md` L640-665 |
+| Python SDK 的 `connect()` 自动登记和 `client.push.register/unregister` 运行期接口 | `docs/sdk/04-连接与认证.md` L125-150、`docs/sdk/06-API手册.md` L643-670 |
 | 终端客户端和 Push Server 如何接入，以及如何使用 Python Mock 完成隔离演示 | `docs/AUN离线推送接入与演示指南.md` L7-250 |
 | 离线推送接入验收、常见问题和生产硬门 | `docs/AUN离线推送接入与演示指南.md` L252-290 |
 | 离线推送 RPC、事件、批次 ACK、持久恢复和发布边界 | `docs/protocol/15-离线推送通知协议.md` L27-165 |
@@ -100,12 +100,13 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L241-319 |
 | agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L321-370 |
 | SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L94-123、`docs/sdk/06-API手册.md` L192-209、`docs/sdk/09-storage-rpc-manual.md` L621-663、`docs/sdk/09-group-rpc-manual.md` L1448-1452、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
 | 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
 | 四 SDK 版本差异、跨语言对齐优先级、验签缓存与 change-seed 边界 | `python/CHANGES_FOR_PARITY.md` L11-110 |
 | 群 `mention_mode` 提及过滤、Agent 自主行为、SDK group.index facade 和 CAS 冲突处理 | `docs/protocol/10-Group-子协议.md`、`docs/protocol/13-Agent行为规范.md`、`docs/sdk/09-group-rpc-manual.md`、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-333 |
 | AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-265 |
-| AUN Storage 架构、SDK VFS、direct backend 数据面、类 Linux 权限和 mount/symlink | `docs/aun-fs/AUN Storage架构设计.md` L16-47、L74-120、L183-228、L289-315 |
+| AUN Storage 架构、SDK VFS、direct backend 数据面、类 Linux 权限和 mount/symlink | `docs/aun-fs/AUN Storage架构设计.md` L16-47、L74-120、L153-166、L192-237、L298-324 |
 | AUN Storage SDK VFS / LowLevel 接口契约和错误映射 | `docs/aun-fs/SDK存储分层设计.md` L20-112、L169-317 |
 | AUN Storage CLI `aun fs` 命令语义和输出格式 | `docs/aun-fs/CLI-fs命令设计.md` L26-61、L89-207、L279-399 |
 | AUN Storage 分阶段 TDD 计划、P1/P2/P3/P4/P5/P6 执行记录、P6 mount/umount 验收和阶段验证纪律 | `docs/aun-fs/分阶段实施计划.md` L24-37、L108-1013、L1015-1071 |

package/_packed_docs/agent.md/SCHEMA.md

@@ -4,18 +4,21 @@
 
 ## 限制
 
-- **文件大小**: 最大 4KB
+- **文件大小**: 被签名 payload 最大 4KB（尾部签名块不计入）
+- **签名块大小**: 尾部签名载体最大 2KB（2048 字节，按 UTF-8 原始字节计算）
+- **请求读取上限**: `PUT /agent.md` 最多读取 `payload_max + signature_max` 字节；超出即返回 `413 agent_md_too_large`，不执行证书查询、数据库或缓存写入
+- **编码**: UTF-8
 
 ## 文件格式
 
-agent.md 文件采用 **YAML frontmatter + Markdown 内容 + 签名块（可选，位于文件尾部）** 的格式：
+agent.md 文件采用 **YAML frontmatter + Markdown 内容 + 签名块（必需，位于文件尾部）** 的格式：
 
 ```markdown
 ---
 # YAML 元数据 (核心字段)
 aid: "agent-name.aid.pub"
 name: "Agent Name"
-type: "assistant"
+type: "agent"
 version: "1.0.0"
 description: "一句话描述"
 tags:
@@ -26,14 +29,15 @@ tags:
 # Markdown 正文内容
 详细说明、Skills、使用示例等...
 
-<!-- AUN-SIGNATURE
-cert_fingerprint: sha256:abc123...
-timestamp: 1715300000
-signature: MEUCIQDx...
--->
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:abc123...
+public_key_fingerprint: sha256:def456...
+timestamp: 1715300000
+signature: MEUCIQDx...
+-->
 ```
 
-无签名的文件仍然合法，第一行直接以 `---` 开头。
+上传接收契约要求签名块存在且有效；无签名文件只可作为本地草稿或只读示例，不得通过 `PUT /agent.md`。
 
 ## 签名块规范
 
@@ -45,47 +49,57 @@ signature: MEUCIQDx...
 
 ```
 <!-- AUN-SIGNATURE
-cert_fingerprint: sha256:<hex>
-timestamp: <unix_seconds>
-signature: <base64_der>
--->
-```
-
-- **cert_fingerprint**: 签名证书的 SHA-256 指纹，格式 `sha256:<64位hex>`
-- **timestamp**: 签名时刻的 Unix 时间戳（秒）
-- **signature**: ECDSA P-256 签名的 DER 编码，Base64 表示
+cert_fingerprint: sha256:<hex>
+public_key_fingerprint: sha256:<hex>
+timestamp: <unix_seconds>
+signature: <base64_der>
+-->
+```
+
+- **cert_fingerprint**（必填）: X.509 证书 DER 的 SHA-256 指纹，格式 `sha256:<64位hex>`；不得使用公钥指纹代替
+- **public_key_fingerprint**（可选）: SubjectPublicKeyInfo DER 的 SHA-256 指纹，格式 `sha256:<64位hex>`
+- **timestamp**: 签名时刻的 Unix 时间戳（秒）
+- **signature**: ECDSA P-256 / SHA-256 签名的 DER 编码，使用严格 Base64 表示
 
 ### 签名计算
 
-1. **被签内容（payload）**：签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部字节
-2. **哈希**：对 payload 计算 SHA-256
-3. **签名**：使用 NIST P-256 私钥对哈希值进行 ECDSA 签名
+1. **被签内容（payload）**：签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部 UTF-8 字节，换行和空白均不得规范化
+2. **哈希**：对 payload 计算 SHA-256
+3. **签名**：使用证书对应的 NIST P-256 私钥执行 ECDSA 签名，结果采用 DER 编码
 
 ### 验签流程
 
-1. 检测文件尾部是否存在 `<!-- AUN-SIGNATURE` 签名块
+1. 检测文件尾部是否存在且只能存在一个 `<!-- AUN-SIGNATURE` 签名块
 2. 提取签名块中的 `cert_fingerprint`、`timestamp`、`signature`
 3. 剥离签名块，取剩余内容为 payload
 4. 对 payload 计算 SHA-256
-5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
-6. 使用公钥验证 ECDSA 签名
+5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
+6. 确认证书公钥为 NIST P-256，并使用 ECDSA / SHA-256 验证签名
 
 ### 约束
 
-- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
-- 签名块与正文之间应至少保留一个换行
-- 签名块不计入 4KB 文件大小限制
+- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
+- 签名块必须从新行开始，因此 payload 的最后一个原始字节必须是 `LF` 或 `CR`；SDK 不得自动补换行或改写 payload
+- frontmatter 与签名块均接受 `LF`、`CRLF` 或 `CR` 行尾；解析签名块时可识别行尾，但不得据此改写 payload
+- 签名块只能包含上述四个字段；除 `public_key_fingerprint` 外均为必填；重复字段和未知字段必须拒绝
+- 签名块不计入 4KB 文件大小限制，但自身不得超过 2048 字节；服务端必须在解析和证书查询前拒绝超限载体
+- `timestamp` 最多允许比服务端时间快 300 秒，不设置过去时间窗口，并且必须落在证书有效期内
+- `aid`、Host、Bearer Token 和签名证书 AID 必须一致
+- agent.md 上传签名算法固定为 ECDSA P-256 / SHA-256；其他曲线或密钥类型必须拒绝
+- 签名证书必须由当前 Issuer CA 返回，状态为 `active_signing` 且处于有效期内；证书 Subject CN 必须等于 AID
+- `PUT /agent.md` 成功验收后，文档不得仅因签名证书随后自然过期而失效；历史验签仍须确认 `timestamp` 落在该证书的有效期内
+- 服务端在数据库和缓存写入前完成全部校验；任一校验失败均拒绝接收
 
 ## YAML Schema (核心字段)
 
 ```yaml
 # ===== 身份标识 (必填) =====
-aid:
-  type: string
-  required: true
-  pattern: "^[a-zA-Z0-9_-]+\\.aid\\.pub$"
-  description: "Agent 的唯一身份标识 (AID 格式)"
-  example: "lobster.aid.pub"
+aid:
+  type: string
+  required: true
+  pattern: "^[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*)+$"
+  description: "至少两个标签的 DNS 型 AID；Issuer 后缀不固定，比较时不区分大小写"
+  example: "lobster.agentid.pub"
 
 # ===== 基本信息 =====
 name:
@@ -94,16 +108,15 @@ name:
   description: "Agent 显示名称"
   example: "Code Reviewer"
 
-type:
-  type: string
-  required: true
-  enum:
-    - human          # 真人用户
-    - assistant      # 通用助手
-    - avatar         # 用户化身/分身
-    - openclaw       # OpenClaw AI 助手
-    - codeagent      # 代码编程 Agent
-  description: "Agent 类型"
+type:
+  type: string
+  required: true
+  predefined_values:  # 预设值，不是封闭枚举
+    - human          # 真人用户
+    - agent          # AI 助手
+    - group          # 群组
+  allow_extensions: true
+  description: "Agent 类型；允许使用未预设的扩展值"
 
 version:
   type: string
@@ -127,24 +140,36 @@ tags:
   description: "用于分类和检索"
 ```
 
-## Agent Type 说明
-
-| Type | 用途 | 示例 |
-|------|------|------|
-| `human` | 真人用户 | 开发者、管理员、终端用户 |
-| `assistant` | 通用对话助手 | 聊天机器人、客服 |
-| `avatar` | 用户分身 | 代表用户行动的 agent |
-| `openclaw` | OpenClaw AI 助手 | 本地个人助手、ACP 桥接 |
-| `codeagent` | 代码编程 Agent | Claude Code、Cursor Agent |
+## Agent Type 说明
+
+`type` 是可扩展字符串。下表只定义当前预设值；解析方必须保留并容忍未知类型，不得因其不在预设列表中拒绝 agent.md。
+
+| 预设 Type | 用途 | 示例 |
+|------|------|------|
+| `human` | 真人用户 | 开发者、管理员、终端用户 |
+| `agent` | 通用 Agent | 对话助手、代码 Agent、自动化 Agent |
+| `group` | 群组身份 | 项目团队、协作群组 |
 
 ## 示例文件
 
-| 文件 | Type | AID | 说明 |
-|------|------|-----|------|
-| [human-developer.md](examples/human-developer.md) | `human` | `zhangsan.aid.pub` | 全栈开发者 |
-| [openclaw-lobster.md](examples/openclaw-lobster.md) | `openclaw` | `lobster.aid.pub` | OpenClaw AI 助手（无签名） |
-| [signed-openclaw-lobster.md](examples/signed-openclaw-lobster.md) | `openclaw` | `lobster.aid.pub` | OpenClaw AI 助手（带签名） |
-| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `codeagent` | `claudecode.aid.pub` | Claude Code 编程助手 |
+| 文件 | Type | AID | 说明 |
+|------|------|-----|------|
+| [human-developer.md](examples/human-developer.md) | `human` | `zhangsan.aid.pub` | 全栈开发者 |
+| [openclaw-lobster.md](examples/openclaw-lobster.md) | `agent` | `lobster.aid.pub` | OpenClaw AI 助手（无签名） |
+| [signed-openclaw-lobster.md](examples/signed-openclaw-lobster.md) | `agent` | `lobster.aid.pub` | OpenClaw AI 助手（带签名） |
+| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `agent` | `claudecode.aid.pub` | Claude Code 编程助手 |
+| [群组-开发团队.md](examples/群组-开发团队.md) | `group` | `dev-team.aid.pub` | 开发团队协作群组 |
+
+表中无签名文件仅用于展示 payload 格式，不符合 `PUT /agent.md` 接收契约；静态签名示例也不代表可由线上 CA 验证的有效身份材料。
+
+## `PUT /agent.md` 接收顺序
+
+1. SDK 在联网前校验 UTF-8、payload 大小、frontmatter Schema；失败时不得签名或发起 HTTP 请求。
+2. SDK 使用当前 AID 的签名私钥追加签名块，再执行一次完整 Schema 校验和本地验签；失败时不得上传。
+3. Name Service 完成 Bearer Token 与 Host 绑定校验、完整 Schema 校验、CA 证书查询和验签。
+4. 只有全部校验成功后，Name Service 才能写入数据库并失效缓存。
+
+接收失败使用稳定的机器可读错误：格式或签名无效返回 `400 invalid_agent_md`，payload 超限返回 `413 agent_md_too_large`，CA 不可用返回 `503 certificate_verification_unavailable`，数据库不可用返回 `503 database_unavailable`。
 
 ## Markdown 部分建议内容
 

package/_packed_docs/agent.md/examples/codeagent-claudecode.md

@@ -1,7 +1,7 @@
 ---
 aid: "claudecode.aid.pub"
 name: "Claude Code"
-type: "codeagent"
+type: "agent"
 version: "1.0.0"
 description: "Anthropic 官方代码助手，终端内的 AI 编程伙伴"
 

package/_packed_docs/agent.md/examples/openclaw-lobster.md

@@ -1,7 +1,7 @@
 ---
 aid: "lobster.aid.pub"
 name: "Lobster"
-type: "openclaw"
+type: "agent"
 version: "1.0.0"
 description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
 

package/_packed_docs/agent.md/examples/signed-openclaw-lobster.md

@@ -1,7 +1,7 @@
 ---
 aid: "lobster.aid.pub"
 name: "Lobster"
-type: "openclaw"
+type: "agent"
 version: "1.0.0"
 description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
 

package/_packed_docs/audit/AUN/346/234/215/345/212/241Go/345/214/226/351/207/215/346/236/204/347/262/276/347/273/206/345/214/226/346/272/220/347/240/201/345/256/241/346/237/245-20260718.md

@@ -46,7 +46,7 @@
 | Group | `group RPC -> membership/E2EE/duty/Group FS -> store/WAL -> push/event` |
 | Leaderboard | `ingest event -> pending journal -> batch aggregate -> metric repository -> query/status` |
 | Message | `send/v2.send -> auth/rate/audit -> WAL/transaction -> inbox/push -> pull/ack/recall` |
-| NameService | `HTTP/RPC -> name/Agent.md repository/cache/mirror -> snapshot/proxy -> response` |
+| NameService | `HTTP/RPC -> name/Agent.md validation/repository/cache -> snapshot/proxy -> response` |
 | Service Proxy | `public HTTP/WS -> route/wakeup -> provider tunnel/frame queue -> client response` |
 | Storage | `RPC/data HTTP -> auth/ACL/mount/symlink -> repository/blob/collab -> event` |
 | Stream | `create -> WS push -> history/puller queue -> SSE pull -> created/closed event` |
@@ -139,7 +139,7 @@
 ### 3.7 NameService
 
 - host-root reverse proxy 增加完整 header/body/upstream timeout。
-- Agent.md DB/cache/mirror 更新采用可恢复顺序；DB 故障 GET/PUT 分别返回对齐的服务错误。
+- Agent.md 仅经 `PUT /agent.md` 完成严格校验后写入 DB 并更新缓存；DB 故障 GET/PUT 分别返回对齐的服务错误，不使用文件镜像降级。
 - snapshot 和 Agent.md 覆盖替换使用平台实现；Linux 使用原子 rename，Windows 使用 replace 语义。
 - snapshot 全量按 `aid`、增量按 `(updated_at, aid)` 做 keyset 分页，避免 OFFSET 漂移和大表退化。
 - cache、证书缓存和 runtime reconnect 竞态已收口；proxy diagnostics 使用可注入时钟，补齐 `connection_id` trace/filter、稳定排序和汇总，host-root 事件也进入诊断，URL 敏感参数统一脱敏。
@@ -216,7 +216,7 @@
 | 内存/队列 | Gateway event、Proxy frame、Stream history/puller、CA nonce 和 federation 连接均有条数/字节/并发上限 |
 | 慢连接 | HTTP body/header、WS frame、Gateway fanout和 service RPC 均有 deadline/cancel |
 | 大表性能 | NameService keyset pagination、Leaderboard batch、Storage streaming Range和 status O(1) 路径已落地 |
-| 文件可靠性 | WAL fsync/rotate、snapshot/Agent.md replace、cleanup和 legacy blob 删除边界已修复 |
+| 文件可靠性 | WAL fsync/rotate、snapshot replace、cleanup 和 legacy blob 删除边界已修复；Agent.md 不使用文件副本 |
 
 当前源码未见新的锁顺序环、持锁网络 I/O、send-on-closed-channel 或无界外部输入队列。
 

package/_packed_docs/aun/345/205/254/347/275/221/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -2,6 +2,13 @@
 
 本文说明如何对 `evolagent.cn`、`agentid.pub` 或同拓扑的其他公网 issuer domain 运行 Python SDK integration/E2E。公网测试与本地 Docker 单域、分布式 `data-dist` 完全分离，不复用其身份、临时文件或报告目录。
 
+## 测试指南:
+D:\modelunion\kite\aun-sdk-core\docs\aun测试运行指南.md
+D:\modelunion\kite\aun-sdk-core\docs\aun分布式测试运行指南.md
+D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
+
+运行测试(单元、集成、E2E, cross-sdk, 双域)时应该使用断点续跑的方法，即运行到某个测试时如果发生失败，应该立即停下来，修复此用例，然后再接着此用例运行后续用例。之前通过的用例如果手续修改不受影响则不要重复跑。
+
 ## 1. 测试入口与边界
 
 Python SDK 公网入口：