@agentunion/fastaun-browser 0.5.11 → 0.5.13

package/CHANGELOG.md

@@ -6,6 +6,52 @@
 
 ---
 
+## 0.5.13 — 2026-09-08
+
+### 修复
+
+#### agent.md description 可选字段
+- `validateAgentMdDocument` 不再要求 frontmatter 必须包含 `description`，缺失或空字符串均可通过校验，与 `description` 的可选字段定义保持一致。
+- `description` 存在时仍必须是字符串，长度上限保持为 100 个 Unicode 码点；`aid`、`name`、`type`、`version` 的必填和格式校验不变。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 和 conformance 期望统一更新为 `0.5.13`。
+
+### 测试
+
+- 新增缺失、空字符串和非字符串 `description` 的 Schema 单元测试，并更新 P2P/Group E2EE conformance 版本断言。
+
+## 0.5.12 — 2026-09-05
+
+### 新功能
+
+#### 定向群邀请
+- `GroupFacade` 新增 `inviteMember`、`listMyInvites`、`acceptInvite`、`rejectInvite` 和 `revokeInvite`，统一规范化群 ID、邀请 ID/AID 别名并接入签名 RPC。
+- `create({ members })` 在群创建完成后逐一发出定向邀请，支持 `member_type`，跳过自身和重复 AID；浏览器 cross-SDK agent 和群管理 E2E 覆盖邀请流程。
+- 邀请按群和目标 AID 聚合并持久化，在线重复、分页恢复和连接恢复只发布一次 `group.invite_received`；终态清理，部分撤回保留剩余 pending 邀请。
+
+### 修复
+
+#### Forward Pull、ACK 与游标
+- Forward 页完成后忽略页内空洞，按页最大序号和服务端 `contiguous_seq` 证明推进 seq-tracker，并在提交成功后 ACK；已观察到的 Push 上界未追平时继续翻页，即使 `has_more=false`。
+- 空页不直接用高位服务端 cursor 覆盖本地连续游标，待恢复 cursor 在下一次成功 Forward 时应用；持久化失败回滚 tracker 并禁止 ACK。
+- inline push 只有在包含非空 inline payload 时才推进连续游标并 ACK；非 inline push 只更新 `maxSeen` 并触发 Forward，不直接推进 A/T/H 或 ACK。Tail 仅维护窗口，History 不推进实时游标。
+
+#### Push、V2 与浏览器生命周期
+- P2P、群消息和群事件的 plain/V2 路径统一上述边界；缺少 sender IK/SPK 时保留阻塞页，不错误推进、ACK 或续页，密钥恢复后按 `pending_retry` 投递。
+- 当前设备自发消息在 Pull 中只标记序号，不重复发布；重复/迟到 inline ACK 保留 pending。群 changed、dissolved、自入群等非 inline Push 只记录上界并交由 Forward 处理。
+- 浏览器 Worker/原生 transport 事件映射补齐邀请创建、接收和终态，连接恢复不阻塞邀请状态重建。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.12`。
+
+### 测试
+
+- 新增定向邀请 facade、聚合持久化、分页/重连恢复、部分终态和浏览器群管理 E2E 测试。
+- 扩展 Forward 空洞、服务端 contiguous 证明、空页 cursor、持久化回滚、inline/non-inline Push、Tail/History 不推进、self-sync 去重及缺 IK/SPK 阻塞边界测试；跨域 runner 使用 `agentid.cn`/`agentid.pub`。
+
 ## 0.5.11 — 2026-09-03
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,52 @@
 
 ---
 
+## 0.5.13 — 2026-09-08
+
+### 修复
+
+#### agent.md description 可选字段
+- `validateAgentMdDocument` 不再要求 frontmatter 必须包含 `description`，缺失或空字符串均可通过校验，与 `description` 的可选字段定义保持一致。
+- `description` 存在时仍必须是字符串，长度上限保持为 100 个 Unicode 码点；`aid`、`name`、`type`、`version` 的必填和格式校验不变。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version` 和 conformance 期望统一更新为 `0.5.13`。
+
+### 测试
+
+- 新增缺失、空字符串和非字符串 `description` 的 Schema 单元测试，并更新 P2P/Group E2EE conformance 版本断言。
+
+## 0.5.12 — 2026-09-05
+
+### 新功能
+
+#### 定向群邀请
+- `GroupFacade` 新增 `inviteMember`、`listMyInvites`、`acceptInvite`、`rejectInvite` 和 `revokeInvite`，统一规范化群 ID、邀请 ID/AID 别名并接入签名 RPC。
+- `create({ members })` 在群创建完成后逐一发出定向邀请，支持 `member_type`，跳过自身和重复 AID；浏览器 cross-SDK agent 和群管理 E2E 覆盖邀请流程。
+- 邀请按群和目标 AID 聚合并持久化，在线重复、分页恢复和连接恢复只发布一次 `group.invite_received`；终态清理，部分撤回保留剩余 pending 邀请。
+
+### 修复
+
+#### Forward Pull、ACK 与游标
+- Forward 页完成后忽略页内空洞，按页最大序号和服务端 `contiguous_seq` 证明推进 seq-tracker，并在提交成功后 ACK；已观察到的 Push 上界未追平时继续翻页，即使 `has_more=false`。
+- 空页不直接用高位服务端 cursor 覆盖本地连续游标，待恢复 cursor 在下一次成功 Forward 时应用；持久化失败回滚 tracker 并禁止 ACK。
+- inline push 只有在包含非空 inline payload 时才推进连续游标并 ACK；非 inline push 只更新 `maxSeen` 并触发 Forward，不直接推进 A/T/H 或 ACK。Tail 仅维护窗口，History 不推进实时游标。
+
+#### Push、V2 与浏览器生命周期
+- P2P、群消息和群事件的 plain/V2 路径统一上述边界；缺少 sender IK/SPK 时保留阻塞页，不错误推进、ACK 或续页，密钥恢复后按 `pending_retry` 投递。
+- 当前设备自发消息在 Pull 中只标记序号，不重复发布；重复/迟到 inline ACK 保留 pending。群 changed、dissolved、自入群等非 inline Push 只记录上界并交由 Forward 处理。
+- 浏览器 Worker/原生 transport 事件映射补齐邀请创建、接收和终态，连接恢复不阻塞邀请状态重建。
+
+### 改进
+
+- SDK、锁文件、运行时 `VERSION`、V2 E2EE envelope `sdk_version`、conformance 及相关测试期望统一更新为 `0.5.12`。
+
+### 测试
+
+- 新增定向邀请 facade、聚合持久化、分页/重连恢复、部分终态和浏览器群管理 E2E 测试。
+- 扩展 Forward 空洞、服务端 contiguous 证明、空页 cursor、持久化回滚、inline/non-inline Push、Tail/History 不推进、self-sync 去重及缺 IK/SPK 阻塞边界测试；跨域 runner 使用 `agentid.cn`/`agentid.pub`。
+
 ## 0.5.11 — 2026-09-03
 
 ### 新功能

package/_packed_docs/INDEX.md

@@ -30,7 +30,7 @@
 | [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.11 跨语言对齐清单；0.5.11 重点覆盖消息来源、sync 生命周期、连接后身份准入自愈、Worker 降级与 V1 wrapper 内 V2 envelope 兼容 |
+| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.13 跨语言对齐清单；0.5.13 重点覆盖 agent.md `description` 可选字段、Unicode 长度边界与四端版本一致性 |
 | [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、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、服务端分层和 direct backend 上传下载 |
@@ -86,7 +86,7 @@
 - 四 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 相对发布基线的实现级差异、代码/测试落点、对齐优先级、消息来源、sync 生命周期、身份准入自愈和 Worker 降级边界 → [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)
+- 四 SDK 相对发布基线的实现级差异、代码/测试落点、对齐优先级、agent.md 可选字段及历史消息同步边界 → [四 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、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
@@ -222,7 +222,7 @@
 
 ### 四 SDK 版本对齐变更清单
 
-`python/CHANGES_FOR_PARITY.md` 以 Python SDK 历史实现为主线记录 Go / TypeScript / JavaScript 的对齐要求。当前 v0.5.11 章节以 `8abb1d7d` 的 v0.5.10 为基线，区分四语言共有能力与 JS/TS Worker 专属边界，并明确消息来源、sync 生命周期、连接后身份准入自愈、V1 wrapper 内 V2 envelope 兼容和分页进度的一致性要求。
+`python/CHANGES_FOR_PARITY.md` 以 Python SDK 历史实现为主线记录 Go / TypeScript / JavaScript 的对齐要求。当前 v0.5.13 章节以 `8df55664` 的 v0.5.12 为基线，明确 agent.md `description` 缺失、空字符串、类型和 Unicode 长度边界，并列出四语言实现、测试与版本落点。
 
 ### AUN CLI 手册
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -102,7 +102,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 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 版本差异、跨语言对齐优先级、消息来源、sync 生命周期、身份准入自愈与 Worker 降级边界 | `python/CHANGES_FOR_PARITY.md` L11-101 |
+| 四 SDK 版本差异、跨语言对齐优先级、agent.md `description` 可选字段及版本落点 | `python/CHANGES_FOR_PARITY.md` L11-54 |
 | 群 `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 |

package/_packed_docs/agent.md/SCHEMA.md

@@ -4,21 +4,21 @@
 
 ## 限制
 
-- **文件大小**: 被签名 payload 最大 4KB（尾部签名块不计入）
-- **签名块大小**: 尾部签名载体最大 2KB（2048 字节，按 UTF-8 原始字节计算）
-- **请求读取上限**: `PUT /agent.md` 最多读取 `payload_max + signature_max` 字节；超出即返回 `413 agent_md_too_large`，不执行证书查询、数据库或缓存写入
-- **编码**: UTF-8
+- **文件大小**: 被签名 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: "agent"
+type: "agent"
 version: "1.0.0"
 description: "一句话描述"
 tags:
@@ -29,15 +29,15 @@ tags:
 # Markdown 正文内容
 详细说明、Skills、使用示例等...
 
-<!-- AUN-SIGNATURE
-cert_fingerprint: sha256:abc123...
-public_key_fingerprint: sha256:def456...
-timestamp: 1715300000
-signature: MEUCIQDx...
--->
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:abc123...
+public_key_fingerprint: sha256:def456...
+timestamp: 1715300000
+signature: MEUCIQDx...
+-->
 ```
 
-上传接收契约要求签名块存在且有效；无签名文件只可作为本地草稿或只读示例，不得通过 `PUT /agent.md`。
+上传接收契约要求签名块存在且有效；无签名文件只可作为本地草稿或只读示例，不得通过 `PUT /agent.md`。
 
 ## 签名块规范
 
@@ -49,57 +49,57 @@ signature: MEUCIQDx...
 
 ```
 <!-- AUN-SIGNATURE
-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 表示
+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` 之前的全部 UTF-8 字节，换行和空白均不得规范化
-2. **哈希**：对 payload 计算 SHA-256
-3. **签名**：使用证书对应的 NIST P-256 私钥执行 ECDSA 签名，结果采用 DER 编码
+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. 确认证书公钥为 NIST P-256，并使用 ECDSA / SHA-256 验证签名
+5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
+6. 确认证书公钥为 NIST P-256，并使用 ECDSA / SHA-256 验证签名
 
 ### 约束
 
-- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
-- 签名块必须从新行开始，因此 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` 落在该证书的有效期内
-- 服务端在数据库和缓存写入前完成全部校验；任一校验失败均拒绝接收
+- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
+- 签名块必须从新行开始，因此 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_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*)+$"
-  description: "至少两个标签的 DNS 型 AID；Issuer 后缀不固定，比较时不区分大小写"
-  example: "lobster.agentid.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:
@@ -108,15 +108,15 @@ name:
   description: "Agent 显示名称"
   example: "Code Reviewer"
 
-type:
-  type: string
-  required: true
-  predefined_values:  # 预设值，不是封闭枚举
-    - human          # 真人用户
-    - agent          # AI 助手
-    - group          # 群组
-  allow_extensions: true
-  description: "Agent 类型；允许使用未预设的扩展值"
+type:
+  type: string
+  required: true
+  predefined_values:  # 预设值，不是封闭枚举
+    - human          # 真人用户
+    - agent          # AI 助手
+    - group          # 群组
+  allow_extensions: true
+  description: "Agent 类型；允许使用未预设的扩展值"
 
 version:
   type: string
@@ -127,7 +127,7 @@ version:
 # ===== 描述信息 =====
 description:
   type: string
-  required: true
+  required: false
   max_length: 100
   description: "一句话简介，用于列表展示"
 
@@ -140,36 +140,36 @@ tags:
   description: "用于分类和检索"
 ```
 
-## Agent Type 说明
-
-`type` 是可扩展字符串。下表只定义当前预设值；解析方必须保留并容忍未知类型，不得因其不在预设列表中拒绝 agent.md。
-
-| 预设 Type | 用途 | 示例 |
-|------|------|------|
-| `human` | 真人用户 | 开发者、管理员、终端用户 |
-| `agent` | 通用 Agent | 对话助手、代码 Agent、自动化 Agent |
-| `group` | 群组身份 | 项目团队、协作群组 |
+## 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) | `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`。
+| 文件 | 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/aun/345/210/206/345/270/203/345/274/217/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -20,7 +20,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 
 - 当前 worktree：`D:\modelunion\kite`
 - 三节点单域集群：`D:\modelunion\kite\docker-deploy\docker-compose.distributed.yml`
-- 本地真实域名双域：两域基础 Compose + 域覆盖 + `D:\modelunion\kite\docker-deploy\docker-compose.agentid-federation.yml`
+- 本地真实域名双域：两域基础 Compose + 域覆盖 + `D:\modelunion\kite\docker-deploy\docker-compose.agentid-federation.yml`，当前不加载 Mail overlay
 - 隔离双域 federation：`D:\modelunion\kite\docker-deploy\federation-test\docker-compose.yml`
 - 分布式 Tester：`D:\modelunion\kite\docker-deploy\docker-compose.distributed-testers.yml`
 - 分布式 Cross-SDK：`D:\modelunion\kite\aun-sdk-core\tests\cross-sdk\docker-compose.cross-sdk.distributed.yml`
@@ -43,11 +43,11 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 
 ## 本地真实域名双域与公网环境边界
 
-`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一服务镜像，但各自拥有独立 Issuer CA、10 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
+`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一无 Mail 服务镜像，但各自拥有独立 Issuer CA、10 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。默认双域不创建 PostgreSQL、不加载 Mail；服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
 
 - `D:\modelunion\kite\docker-deploy\agentid.pub`：引用固定 `data`，project 为 `kite-single`，应用容器为 `kite-app`。
 - `D:\modelunion\kite\docker-deploy\agentid.cn`：引用固定 `data-agentid-cn`，project 为 `kite-agentid-cn-local`，应用容器为 `kite-agentid-cn-local-app`。
-- `D:\modelunion\kite\docker-deploy\docker-compose.agentid-federation.yml`：只给两域 `kite` service 增加共享网络和 `{svc}.{issuer}` alias，不共享或代理 MySQL、Redis。
+- `D:\modelunion\kite\docker-deploy\docker-compose.agentid-federation.yml`：只给两域 `kite` service 增加共享网络和 `{svc}.{issuer}` alias，不共享或代理 MySQL、Redis，以及 Mail 专项才会创建的 PostgreSQL。
 - `docker-deploy/agentid.pub/online/go/` 与 `docker-deploy/agentid.cn/online/go/`：分别用于公网主机部署；线上机器不加载本地 federation overlay。
 
 本地 Docker 与公网服务器使用相同域名，但不是同一运行环境。测试证据必须记录目标层：本地以 Compose label、容器镜像 ID、mount 和 `docker logs` 为准；公网以实际 DNS/TLS、公网 RPC 结果及两域采集日志为准。不得因为域名相同，把本地成功写成线上成功。
@@ -501,7 +501,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 定位与验收边界
 
-这是当前真实域名的**本地双域 Docker 跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。
+这是当前真实域名的**本地双域 Docker 跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个无 Mail 的 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。
 
 本环境验证的是本地完整调用链：
 
@@ -517,7 +517,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 每轮执行顺序
 
-每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
+每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect，因此不得加载 `docker-compose.mail.yml`。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
 
 ### 材料校验与镜像构建
 
@@ -565,6 +565,8 @@ docker compose --env-file agentid.pub/local.env --env-file agentid.cn/local.env
   -f agentid.cn/docker-compose.yml @federation ps
 ```
 
+两套 `ps` 结果都只能包含各自的 `kite`、`mysql`、`redis`；不得出现 `*-mail-postgres`。两个应用容器都必须使用 `docker-deploy-kite:latest`，且 Compose 来源中不得包含 `docker-compose.mail.yml`。
+
 `agentid.cn` 的 Compose 命令必须先加载 `agentid.pub/local.env`，再加载 `agentid.cn/local.env`：前者提供经过本地准备的 OSS endpoint、bucket 和凭据，后者覆盖 cn 的 Issuer、project、端口、数据根和 `AUN_STORAGE_OSS_PREFIX=agentid-cn/`。`agentid.cn/local.env` 不重复保存 OSS 密钥；不要在日志或 `config` 输出中打印完整环境变量。
 
 `agentid.pub` 使用默认宿主端口；`agentid.cn` 使用 Gateway `42001`、AUN Console `42876`、NameService `42443`、Storage `42470`、Group `42480`、MySQL `8406`。这些 42xxx 端口只用于宿主机调试；服务发现和跨网关路由仍公布容器内标准端口与 `{svc}.{issuer}`，不得把 42xxx 写进 federation 内部 URL。
@@ -786,7 +788,7 @@ foreach ($container in 'kite-app','kite-agentid-cn-local-app') {
 
 ### 覆盖边界
 
-- Mail 和 reconnect 当前明确不测，不得把 `SKIPPED` 写成通过。
+- Mail 和 reconnect 当前明确不测；双域启动时不得加载 Mail overlay，也不得把 `SKIPPED` 写成通过。
 - Service Proxy 不属于 Gateway federation relay 白名单；它的双域功能测试验证 provider/proxy 业务路由，不计入 Gateway 联邦身份边界覆盖。
 - V2 加密、Thought 和加密 payload 与 Gateway 联邦身份绑定正交，由后文隔离 `dist-aid.*` 的 `e2e_encrypted.py`、`e2e_v2_cross_domain.py`、`test_e2ee_cross_domain.py` 覆盖；真实域 runner 不重复这些载荷组合。
 - `meta.*` 是 Gateway 本地诊断接口，没有独立跨域业务使用场景；不得为追求 namespace 数量制造无效 E2E。

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

@@ -25,7 +25,9 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 | 本地真实域名双域 Docker | 两套上述单节点 Compose 均叠加 `docker-compose.agentid-federation.yml` | `agentid.pub`、`agentid.cn` | 两域各自固定数据根 | 两个独立 project，共享 `kite-agentid-federation-net` | `kite-app`、`kite-agentid-cn-local-app` 及各自 MySQL/Redis |
 | 隔离双域 federation | `D:\modelunion\kite\docker-deploy\federation-test\docker-compose.yml` | `dist-aid.com`、`dist-aid.net` | `D:\modelunion\kite\docker-deploy\federation-test\data-dist` | `kite-main-dist-federation` / `kite-main-dist-federation_federation-net` | `main-dist-federation-*`、`main-dist-client-*` |
 
-`agentid.pub` 与 `agentid.cn` 使用不同 project、容器名、私有网络、CA、服务 AID、MySQL 和 workspace。`agentid.cn` 的宿主机入口已改为 42xxx、MySQL 为 8406，因此两域可以并行；跨域测试时必须让两域同时叠加 federation overlay。该 overlay 只把两个 Kite 业务节点接入共享网络，MySQL 和 Redis 始终留在各自域内。
+`agentid.pub` 与 `agentid.cn` 使用不同 project、容器名、私有网络、CA、服务 AID、MySQL 和 workspace。`agentid.cn` 的宿主机入口已改为 42xxx、MySQL 为 8406，因此两域可以并行；跨域测试时必须让两域同时叠加 federation overlay。该 overlay 只把两个 Kite 业务节点接入共享网络，MySQL、Redis，以及 Mail 专项测试才会创建的 PostgreSQL 始终留在各自域内。
+
+默认单域、集成、E2E、cross-SDK 和本地双域均不加载 `docker-compose.mail.yml`，因此不创建 PostgreSQL，也不启动 Mail。只有明确执行 Mail 专项验收时才额外加载该 overlay，并使用独立的 `docker-deploy-kite-mail:latest` 镜像；当前线上 Go Compose 同样不包含 PostgreSQL 或 Mail。
 
 Tester 和 cross-SDK 都不是服务端环境：
 
@@ -37,7 +39,7 @@ Tester 和 cross-SDK 都不是服务端环境：
 | 分布式四语言 Tester | `D:\modelunion\kite\docker-deploy\docker-compose.distributed-testers.yml` | `kite-main-dist-sdk-testers`，接入 `kite-main-dist-worktree_kite-distributed-net` | 三节点分布式 |
 | 分布式 cross-SDK | `D:\modelunion\kite\aun-sdk-core\tests\cross-sdk\docker-compose.cross-sdk.distributed.yml` | `kite-main-dist-cross-sdk`，接入分布式网络 | 三节点分布式 |
 
-根目录 `docker-compose.yml` 是两域共用的单节点分布式控制模型，域目录中的同名文件只做域与宿主端口覆盖。单域命令必须同时显式传入根文件和对应域覆盖文件；跨域命令还必须叠加 `docker-compose.agentid-federation.yml`。不能只启动覆盖文件，也不能启动历史的 `evolagent.cn` 或 `data-evolagent-cn/docker-compose.yml`。
+根目录 `docker-compose.yml` 是两域共用的单节点分布式控制模型，域目录中的同名文件只做域与宿主端口覆盖。单域命令必须同时显式传入根文件和对应域覆盖文件；跨域命令还必须叠加 `docker-compose.agentid-federation.yml`；Mail 专项才额外叠加 `docker-compose.mail.yml`。不能只启动覆盖文件，也不能启动历史的 `evolagent.cn` 或 `data-evolagent-cn/docker-compose.yml`。
 
 本机还存在以下 Compose 材料，但都不是默认集成测试入口：
 
@@ -93,6 +95,7 @@ Docker Desktop 可能把 Windows bind source 返回为 `/run/desktop/mnt/host/<
 | 文件 | 包含内容 | 使用场景 |
 | --- | --- | --- |
 | `docker-compose.yml` | `mysql`、`redis`、`kite` | 本地服务端和最小生产包的基础清单 |
+| `docker-compose.mail.yml` | Mail 专用 `postgres`、Mail 镜像和启用开关 | 仅显式 Mail 专项验收时叠加 |
 | `docker-compose.testers.yml` | Python、Go、TypeScript、JavaScript SDK Tester | 服务端启动后作为独立 Compose project 启动 |
 | `docker-compose.build.yml` | `kite`、`sdk-tester` 镜像构建定义 | 服务端或 Python Tester 镜像需要重建时 |
 
@@ -103,7 +106,7 @@ Docker Desktop 可能把 Windows bind source 返回为 `/run/desktop/mnt/host/<
 - 服务只有在 desired-state 为 `running` 且实际发送 `module.ready` 后才会注册；停止、未启动、未 ready 或不在 desired-state 中的服务不应出现在活动注册实例中。
 - 单实例不需要为每个服务或每次启动生成独立控制令牌。Compose 提供单节点控制面默认值，Launcher 负责本节点内服务生命周期与模块凭据。
 - 单实例共享同一个 MySQL 服务及 `host/port/user/password`，但每个持久化服务始终按自身历史库名确定默认数据库；`aun` 过去不是、以后也不会是公共默认库。Compose 不创建公共默认库，也不向应用注入 `KITE_DB_DATABASE` 或 `KITE_DB_DSN`；只有外部显式配置时才覆盖服务默认值。
-- `agentid.pub` overlay 会启动 Mail 专用 PostgreSQL；Mail 默认以 enabled 状态随 Kite 启动并注册 AUN `mail.*` RPC。服务端 SMTP 入站/出站默认关闭，SMTP bridge 通过独立开关验收；不启动 Mailpit、IMAP 或 SMTP Submission。
+- 默认域 overlay 不创建 PostgreSQL，也不向应用注入 Mail 环境变量；默认 `docker-deploy-kite:latest` 镜像不包含 Mail。只有叠加 `docker-compose.mail.yml` 时才改用独立 Mail 镜像、创建域内 PostgreSQL，并以 AUN RPC-only 模式启动 Mail；SMTP bridge 仍需单独显式开启。
 - 单实例 Storage 数据面默认使用原生 HTTPS：`https://storage.agentid.pub:9470`，复用既有证书与 CA bundle。
 - 不读取目录中的隐式 `.env`。本地域环境显式传入对应 `local.env`，无域基础命令使用 `--env-file NUL`；Linux 部署脚本只读取调用方显式导出的环境变量。
 - Python 广义全量验收仍跳过文件名包含 `mail` 或 `reconnect` 的测试；Mail 使用本指南定义的专用脚本单独验收。带 `if __name__ == "__main__"` 的脚本使用 `python <file>`，纯 pytest 文件使用 `python -m pytest -q <file>`；pytest 退出码 `5` 只表示未收集到用例，不能直接判定为服务失败。
@@ -189,13 +192,16 @@ docker compose --env-file NUL -f docker-compose.build.yml build kite sdk-tester
 
 `aun-sdk-tester` 镜像（`Dockerfile.sdk-tester`）已内置所有 Python 测试依赖，包括 SDK 依赖以及 Service Proxy/Name Service 集成测试所需的 FastAPI、uvicorn、PyYAML、requests 和 `httpx`。正常情况下，`kite-python-sdk-tester` 启动后即可直接运行测试，无需手动安装。当前 SDK 仅依赖标准库 `sqlite3`，不要再安装 `sqlcipher3` / `sqlcipher3-binary`。
 
-构建后分别校验服务端和 Tester Compose。第一条只能列出 `mysql`、`redis`、`kite`；第二条只能列出四个 Tester，不能包含服务端服务：
+构建后分别校验默认服务端和 Tester Compose。第一条只能列出 `mysql`、`redis`、`kite`；第二条只能列出四个 Tester，不能包含服务端服务。只有第三条 Mail 专项配置可以额外列出 `postgres`：
 
 ```powershell
 docker compose --env-file agentid.pub/local.env --project-directory . `
   -f docker-compose.yml -f agentid.pub/docker-compose.yml config --services
 docker compose --env-file agentid.pub/local.env --project-directory . `
   -f docker-compose.testers.yml config --services
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.yml -f agentid.pub/docker-compose.yml `
+  -f docker-compose.mail.yml config --services
 ```
 
 如果只是重启默认服务容器 `kite`，而没有重建 Tester，不需要重新安装依赖。使用预构建的 `aun-sdk-tester` 镜像时，即使重新创建 Python Tester 也无需手动补依赖，因为依赖已烘焙在镜像中；TS/JS Tester 仍必须遵守后文的离线依赖准备规则。
@@ -215,7 +221,7 @@ docker compose --env-file agentid.pub/local.env --project-directory . `
   -f docker-compose.yml -f agentid.pub/docker-compose.yml ps
 ```
 
-这一步会启动 `kite-mysql`、`kite-redis`、`kite-mail-postgres`、`kite-app`，不会启动任何 SDK Tester。`kite-app` 内部的 Launcher 按 desired-state defer 加载 AUN 服务，Mail 使用独立 PostgreSQL 并以 AUN RPC-only 模式启动。
+这一步只启动 `kite-mysql`、`kite-redis`、`kite-app`，不会创建 PostgreSQL、启动 Mail 或启动任何 SDK Tester。`kite-app` 内部的 Launcher 按 desired-state defer 加载当前默认 AUN 服务。
 
 单节点三中心与数据库默认值在基础 Compose 中，域名、数据根、project 和节点标识由 `agentid.pub/local.env` 固定：
 
@@ -230,12 +236,12 @@ docker compose --env-file agentid.pub/local.env --project-directory . `
 可以用以下命令检查服务发现、容器日志和默认 Go 进程：
 
 ```powershell
-curl.exe -k https://localhost/.well-known/aun-gateway
+docker exec kite-app curl -sk https://agentid.pub/.well-known/aun-gateway
 docker logs --tail 200 kite-app
-docker top kite-app | Select-String -Pattern "auth-go|ca-go|gateway-go|group-go|leaderboard-go|message-go|nameservice-go|service-proxy-go|storage-go|stream-go|mail-server"
+docker top kite-app | Select-String -Pattern "auth-go|ca-go|gateway-go|group-go|leaderboard-go|message-go|nameservice-go|service-proxy-go|storage-go|stream-go"
 ```
 
-发现结果必须返回 `gateway.agentid.pub`，不能返回 loopback 地址。活动注册实例应与 desired-state 和实际 ready 服务一致；Mail 应出现为 ready，并可通过 `mail.health` / `mail.status` 验证；SMTP bridge 未显式开启时不得出现 SMTP 入站/出站能力。
+发现结果必须返回 `gateway.agentid.pub`，不能返回 loopback 地址。活动注册实例应与 desired-state 和实际 ready 服务一致；默认环境不应存在 Mail 模块、Mail 环境变量或 PostgreSQL 容器。
 
 当前 `docker-compose.yml` 为 `kite` 服务配置的主要 network aliases 包括：
 
@@ -632,17 +638,25 @@ docker exec -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -w /workspace/js kite-js-test
 
 message / group WAL 与异步批量写入当前默认开启，跑上述回归前不需要额外设置开关。若本轮改动涉及 WAL replay、批量 flush、ack/cursor 合并或 group fanout，除了看测试结果，还应按“故障排查”章节确认 `kite-app` 日志里 writer 已启动且没有批量写入异常。
 
-### Mail 专项验收
+### Mail 专项验收（当前默认回归不运行）
+
+只有明确恢复 Mail 测试时才加载 `docker-compose.mail.yml`。该 overlay 会构建独立的
+`docker-deploy-kite-mail:latest`、创建域内 PostgreSQL，并启用 AUN RPC Mail；不得把
+Mail 构建结果覆盖为默认或线上使用的 `docker-deploy-kite:latest`。
 
 Mail 客户端只调用 AUN `mail.*` RPC。真实外发只开启 Mail 服务端的 SMTP 出站 relay，
 不得开启 SMTP Submission、IMAP 或入站 SMTP。163 账号必须先在网页设置中开启
 POP3/SMTP/IMAP 服务并生成独立的 SMTP 客户端授权码；网页登录密码不能替代授权码。
 
-服务端代码变更后先按“服务端代码变更”重建镜像。随后在同一个 PowerShell 会话中
-安全输入授权码并重建 `kite` 容器：
+服务端代码变更后先按“服务端代码变更”重建默认镜像，再单独构建 Mail 镜像。随后在
+同一个 PowerShell 会话中安全输入授权码并启动带 Mail 的 Compose：
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.yml -f agentid.pub/docker-compose.yml `
+  -f docker-compose.mail.yml build kite
+
 $relayCredential = Get-Credential -UserName 'readytogo@163.com' `
   -Message '请输入 163 SMTP 客户端授权码（不是网页登录密码）'
 $env:MAIL_SMTP_OUTBOUND_RELAY = 'smtp.163.com:465'
@@ -654,7 +668,7 @@ $env:MAIL_SMTP_OUTBOUND_ALLOW_INSECURE = 'false'
 
 docker compose --env-file agentid.pub/local.env --project-directory . `
   -f docker-compose.yml -f agentid.pub/docker-compose.yml `
-  up -d --force-recreate --no-deps kite
+  -f docker-compose.mail.yml up -d
 ```
 
 确认 Mail 已 ready、Python Tester 已启动后，通过 AUN RPC 发送一封幂等测试邮件：
@@ -671,8 +685,8 @@ docker exec `
 
 脚本只调用 `mail.status/send/get`，不读取 relay 凭据，也不连接 SMTP/IMAP。脚本输出
 `delivered` 只表示 163 MTA 已返回成功响应，仍需人工检查收件箱和垃圾箱；
-`accepted_unknown` 禁止自动重发。若这只是一次验收，结束后必须清除变量并重建 `kite`，
-恢复默认 AUN RPC-only 模式；只清除当前 PowerShell 变量不会改变已运行容器的环境：
+`accepted_unknown` 禁止自动重发。若这只是一次验收，结束后必须清除变量并恢复默认
+无 Mail Compose；只清除当前 PowerShell 变量不会改变已运行容器的环境：
 
 ```powershell
 $mailRelayVars = @(
@@ -689,7 +703,7 @@ $mailRelayVars | ForEach-Object {
 $relayCredential = $null
 docker compose --env-file agentid.pub/local.env --project-directory . `
   -f docker-compose.yml -f agentid.pub/docker-compose.yml `
-  up -d --force-recreate --no-deps kite
+  up -d --remove-orphans
 ```
 
 需要长期保留外发 bridge 时，不执行上述重建关闭步骤，但必须改由部署 secret 管理授权码，