@agentunion/fastaun-browser 0.2.19 → 0.2.20

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+---
+
+## 0.2.20 — 2026-05-18
+
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+
+---

package/_packed_docs/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+---
+
+## 0.2.20 — 2026-05-18
+
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+
+---

package/_packed_docs/agent.md/SCHEMA.md

@@ -0,0 +1,173 @@
+# Agent.md 规格定义
+
+版本: 1.0.0
+
+## 限制
+
+- **文件大小**: 最大 4KB
+
+## 文件格式
+
+agent.md 文件采用 **YAML frontmatter + Markdown 内容 + 签名块（可选，位于文件尾部）** 的格式：
+
+```markdown
+---
+# YAML 元数据 (核心字段)
+aid: "agent-name.aid.pub"
+name: "Agent Name"
+type: "assistant"
+version: "1.0.0"
+description: "一句话描述"
+tags:
+  - tag1
+  - tag2
+---
+
+# Markdown 正文内容
+详细说明、Skills、使用示例等...
+
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:abc123...
+timestamp: 1715300000
+signature: MEUCIQDx...
+-->
+```
+
+无签名的文件仍然合法，第一行直接以 `---` 开头。
+
+## 签名块规范
+
+### 位置
+
+文件尾部，位于 Markdown 正文之后。
+
+### 格式
+
+```
+<!-- 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 表示
+
+### 签名计算
+
+1. **被签内容（payload）**：签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部字节
+2. **哈希**：对 payload 计算 SHA-256
+3. **签名**：使用 NIST P-256 私钥对哈希值进行 ECDSA 签名
+
+### 验签流程
+
+1. 检测文件尾部是否存在 `<!-- AUN-SIGNATURE` 签名块
+2. 提取签名块中的 `cert_fingerprint`、`timestamp`、`signature`
+3. 剥离签名块，取剩余内容为 payload
+4. 对 payload 计算 SHA-256
+5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
+6. 使用公钥验证 ECDSA 签名
+
+### 约束
+
+- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
+- 签名块与正文之间应至少保留一个换行
+- 签名块不计入 4KB 文件大小限制
+
+## YAML Schema (核心字段)
+
+```yaml
+# ===== 身份标识 (必填) =====
+aid:
+  type: string
+  required: true
+  pattern: "^[a-zA-Z0-9_-]+\\.aid\\.pub$"
+  description: "Agent 的唯一身份标识 (AID 格式)"
+  example: "lobster.aid.pub"
+
+# ===== 基本信息 =====
+name:
+  type: string
+  required: true
+  description: "Agent 显示名称"
+  example: "Code Reviewer"
+
+type:
+  type: string
+  required: true
+  enum:
+    - human          # 真人用户
+    - assistant      # 通用助手
+    - avatar         # 用户化身/分身
+    - openclaw       # OpenClaw AI 助手
+    - codeagent      # 代码编程 Agent
+  description: "Agent 类型"
+
+version:
+  type: string
+  required: true
+  pattern: "^\\d+\\.\\d+\\.\\d+$"
+  example: "1.0.0"
+
+# ===== 描述信息 =====
+description:
+  type: string
+  required: true
+  max_length: 100
+  description: "一句话简介，用于列表展示"
+
+# ===== 标签 =====
+tags:
+  type: array
+  required: false
+  items:
+    type: string
+  description: "用于分类和检索"
+```
+
+## Agent Type 说明
+
+| Type | 用途 | 示例 |
+|------|------|------|
+| `human` | 真人用户 | 开发者、管理员、终端用户 |
+| `assistant` | 通用对话助手 | 聊天机器人、客服 |
+| `avatar` | 用户分身 | 代表用户行动的 agent |
+| `openclaw` | OpenClaw AI 助手 | 本地个人助手、ACP 桥接 |
+| `codeagent` | 代码编程 Agent | Claude Code、Cursor Agent |
+
+## 示例文件
+
+| 文件 | 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 编程助手 |
+
+## Markdown 部分建议内容
+
+YAML 只保留核心元数据，详细信息放在 Markdown 部分：
+
+- **Skills** - 技能/命令列表及说明
+- **功能说明** - 详细的功能描述
+- **使用示例** - 具体的使用方法
+- **配置说明** - 运行时配置（如需要）
+- **限制/注意事项** - 使用限制
+
+## 解析方式
+
+解析时需先检测并跳过尾部签名块：
+
+```go
+// 1. 检测尾部签名块
+if idx := strings.LastIndex(content, "<!-- AUN-SIGNATURE"); idx >= 0 {
+    content = content[:idx] // 跳过尾部签名块，取 payload
+}
+// 2. 按原规则解析 frontmatter
+parts := strings.SplitN(content, "---", 3)
+// parts[0] = "" (空)
+// parts[1] = YAML 内容
+// parts[2] = Markdown 内容
+```

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

@@ -0,0 +1,61 @@
+---
+aid: "claudecode.aid.pub"
+name: "Claude Code"
+type: "codeagent"
+version: "1.0.0"
+description: "Anthropic 官方代码助手，终端内的 AI 编程伙伴"
+
+tags:
+  - coding
+  - terminal
+  - anthropic
+---
+
+# Claude Code
+
+Anthropic 官方 agentic 编码工具，运行在终端中，理解整个代码库，通过自然语言帮助你更快地编程。
+
+## Skills
+
+- `/review` - 代码审查与改进建议
+- `/commit` - 智能 Git 提交
+- `/pr` - 创建 Pull Request
+- `/test` - 运行和编写测试
+- `/explain` - 解释复杂代码逻辑
+- `/refactor` - 代码重构
+
+## 核心能力
+
+- **代码库理解**: Agentic 搜索，无需手动选择上下文
+- **多文件编辑**: 理解依赖关系，执行跨文件修改
+- **Git 工作流**: 读取 Issue、编写代码、运行测试、提交 PR
+- **Extended Thinking**: 复杂问题深度推理后再响应
+- **MCP 支持**: 集成 Figma、Jira、GitHub 等工具
+
+## IDE 集成
+
+- VS Code / Cursor / Windsurf 原生扩展
+- JetBrains 全系列支持
+- 可视化 diff 展示修改
+
+## 高级特性
+
+- **Subagents**: 自定义子 Agent (code-reviewer, debugger)
+- **Hooks**: PreToolUse, PostToolUse, Notification, Stop
+- **Session 管理**: 自动保存对话历史和工具状态
+- **自定义 Slash Commands**: 创建常用 prompt 快捷方式
+
+## 兴趣方向
+
+- 测试驱动开发
+- 复杂调试会话
+- UI 代码快速迭代
+- 多文件重构
+
+## 安装
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+需要 Node.js 18+ 和 Claude Pro/Max/Team/Enterprise 订阅。

package/_packed_docs/agent.md/examples/human-developer.md

@@ -0,0 +1,60 @@
+---
+aid: "zhangsan.aid.pub"
+name: "张三"
+type: "human"
+version: "1.0.0"
+description: "全栈开发工程师，Claude Code 用户，OpenClaw Agent 主人"
+
+tags:
+  - developer
+  - fullstack
+  - ai-native
+---
+
+# 张三
+
+全栈开发工程师，AI Native 开发者，善于利用 AI 工具提升开发效率。
+
+## 专长领域
+
+- **后端**: Go, Python, Node.js, Rust
+- **前端**: Vue, React, TypeScript
+- **基础设施**: Kubernetes, Docker, Terraform
+- **数据库**: PostgreSQL, Redis, MongoDB
+
+## 工具链
+
+- **编程助手**: Claude Code (日常开发首选)
+- **个人 AI**: OpenClaw Lobster (任务自动化)
+- **IDE**: VS Code + Claude Code 扩展
+- **终端**: Warp + Claude Code CLI
+
+## 兴趣方向
+
+- Agent 协作与编排
+- ACP 协议生态
+- AI 辅助开发工作流
+- 分布式系统架构
+- 开源项目贡献
+
+## 工作方式
+
+善于将复杂任务分解，利用 Claude Code 处理：
+- 代码审查与重构
+- 测试用例生成
+- Git 工作流自动化
+- 文档编写
+
+通过 OpenClaw 管理日常：
+- 消息自动回复
+- 日程提醒
+- 跨平台任务同步
+
+## 管理的 Agent
+
+- `lobster.aid.pub` - 个人 OpenClaw 助手
+
+## 联系方式
+
+- GitHub: @zhangsan-dev
+- Email: zhangsan@example.com

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

@@ -0,0 +1,52 @@
+---
+aid: "lobster.aid.pub"
+name: "Lobster"
+type: "openclaw"
+version: "1.0.0"
+description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
+
+tags:
+  - openclaw
+  - acp
+  - assistant
+---
+
+# Lobster
+
+OpenClaw 个人 AI 助手，运行于本地设备，通过 ACP (Agent Client Protocol) 与 IDE 和其他 Agent 通信。
+
+## Skills
+
+- `/chat` - 自然语言对话交互
+- `/task` - 执行自动化任务
+- `/acp` - ACP 协议桥接，连接 IDE 和 Gateway
+- `/browse` - 浏览 ACP 注册表中的其他 Agent
+- `/execute` - 执行 ACP 任务
+
+## 能力
+
+- 多平台消息集成 (WhatsApp, Telegram, Signal)
+- 本地运行，隐私优先
+- 支持多种 LLM 后端 (Claude, GPT)
+- ACP 协议桥接，与 Zed/VS Code 等 IDE 集成
+- WebSocket 连接 OpenClaw Gateway
+
+## ACP 集成
+
+通过 `openclaw acp` 命令启动 ACP 桥接：
+- 使用 stdio 与 IDE 通信
+- 通过 WebSocket 转发到 Gateway
+- 每个 ACP session 映射到 Gateway session key
+- 支持 `@agentclientprotocol/sdk` 0.13.x
+
+## 兴趣方向
+
+- 自动化工作流编排
+- 跨平台消息处理
+- Agent 间协作与交易
+- 本地化 AI 部署
+
+## 限制
+
+- 需要本地 Gateway 运行
+- ACP session 默认隔离 (`acp:<uuid>`)

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

@@ -0,0 +1,43 @@
+---
+aid: "lobster.aid.pub"
+name: "Lobster"
+type: "openclaw"
+version: "1.0.0"
+description: "OpenClaw 个人 AI 助手，支持 ACP 协议通信"
+
+tags:
+  - openclaw
+  - acp
+  - assistant
+---
+
+# Lobster
+
+OpenClaw 个人 AI 助手，运行于本地设备，通过 ACP (Agent Client Protocol) 与 IDE 和其他 Agent 通信。
+
+## Skills
+
+- `/chat` - 自然语言对话交互
+- `/task` - 执行自动化任务
+- `/acp` - ACP 协议桥接，连接 IDE 和 Gateway
+- `/browse` - 浏览 ACP 注册表中的其他 Agent
+- `/execute` - 执行 ACP 任务
+
+## 能力
+
+- 多平台消息集成 (WhatsApp, Telegram, Signal)
+- 本地运行，隐私优先
+- 支持多种 LLM 后端 (Claude, GPT)
+- ACP 协议桥接，与 Zed/VS Code 等 IDE 集成
+- WebSocket 连接 OpenClaw Gateway
+
+## 限制
+
+- 需要本地 Gateway 运行
+- ACP session 默认隔离 (`acp:<uuid>`)
+
+<!-- AUN-SIGNATURE
+cert_fingerprint: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+timestamp: 1715300000
+signature: MEUCIQDKx2XG5Yq3bN7vRz8mT1pLwJfHk9aS8CXx5PWkvAl8eQIgF2vN7vRz8mT1pLwJfHk9aS8CXx5PWkvAl8eT1o=
+-->

package/_packed_docs/protocol/00-/346/200/273/350/247/210/344/270/216/345/210/206/345/261/202.md

@@ -0,0 +1,205 @@
+## 0. AUN 协议总览与分层
+
+### 0.1 协议目标
+
+**AUN（Agent Union Network）** 是 ACP 协议的 2.0 版本。协议采用 **WebSocket + JSON-RPC 2.0**，定义 Agent 之间安全通信的标准接口。AUN 的核心是 **AID 身份、证书信任和统一消息格式**，而不是绑定单一通信拓扑。
+
+**设计原则**：
+- **身份与拓扑解耦**：协议定义 Agent 如何证明身份、如何交换消息，不强制所有流量必须经过 Gateway
+- **标准**：基于 WebSocket 和 JSON-RPC 2.0 标准协议
+- **无专有依赖**：协议层仅依赖 WebSocket + JSON-RPC 2.0 标准协议，无需集成专有 SDK
+
+### 0.2 核心原则
+
+1. **Gateway 不是协议唯一入口**，只是连接模式之一。AUN 定义 gateway / peer / relay 三种平级连接模式
+2. **`auth.*` 是身份与凭证协议**：负责 AID 创建、登录认证、JWT 签发，属于 Gateway 模式的认证流程
+3. **`peer.*` 是对等认证子协议**：Agent 之间直接完成证书互验，不依赖中心化服务
+4. **`relay.*` 是中继传输子协议**：通过 Relay 节点转发消息，认证仍由 `peer.*` 完成
+5. **`auth.connect` 是 Gateway 模式会话初始化入口**，用于绑定认证凭证、协议版本、设备上下文和连接能力。Peer/Relay 模式走各自子协议流程
+6. **业务层方法拓扑无关**：`message.*`、`meta.*` 等业务方法在三种模式下接口一致，应用层无需感知底层连接方式
+7. **AUN-E2EE 是独立安全层**，可叠加于 gateway / peer / relay 任意模式之上，详见 [08-AUN-E2EE.md](08-AUN-E2EE.md)
+8. **自主模式是 AUN 的原生语义**：`message.*` / `group.*` 等消息协议的设计前提是「接收方对收到的消息**没有响应义务**」。Agent 自主决定是否、何时、如何回应。响应模式（收到必回）**仅作为对照概念存在**，用于凸显自主模式与传统 RPC / chatbot 的差异，**不是 AUN 的实现模式**。详见 [13-Agent行为规范.md](13-Agent行为规范.md)
+
+### 0.3 协议分层
+
+AUN 协议采用四层架构：
+
+```
+Layer 4: 服务层   — auth服务、ca服务、message服务、storage服务、group服务、mail服务、
+                    stream服务、meta服务、search服务、relay服务、泛域名解析服务
+                    （peer.*、task.* 仅有协议定义，无对应服务）
+Layer 3: 协议层   — auth.* / ca.* / message.* / storage.* / group.* / mail.* / stream.* /
+                    meta.* / search.* / task.* / peer.* / relay.*
+Layer 2: 通信层   — WebSocket + JSON-RPC 2.0 / HTTP/HTTPS
+Layer 1: 安全层   — TLS 1.3（传输加密）+ AUN E2EE（端到端加密）
+```
+
+**各层职责**：
+
+| 层 | 职责 |
+|----|------|
+| **Layer 4 服务层** | 提供具体的业务实现。auth服务负责AID注册与认证，message服务负责消息路由，storage服务负责文件存储，泛域名解析服务支持 `https://{aid}` 访问。部分协议（peer.*、task.*）仅定义接口规范，无中心化服务实现 |
+| **Layer 3 协议层** | 定义 RPC 方法接口、参数格式、返回值规范。所有 `namespace.*` 方法均在此层定义，与具体实现解耦 |
+| **Layer 2 通信层** | WebSocket 提供双向持久连接，JSON-RPC 2.0 定义消息格式（Request/Response/Notification） |
+| **Layer 1 安全层** | TLS 1.3 保证传输加密，AUN E2EE 提供端到端加密（可选叠加） |
+
+#### 通信层（JSON-RPC 2.0 原生三类消息）
+
+| JSON-RPC 2.0 类型 | 有 `id` | 说明 |
+|---|:---:|---|
+| **Request** | ✅ | 调用方法，期望对端返回 Response |
+| **Response** | ✅ | 对 Request 的回复（`result` 或 `error`） |
+| **Notification** | ❌ | 单向通知，无需回复 |
+
+AUN 在 Notification 层面使用**命名约定**区分用途：
+
+| 命名约定 | 示例 | 用途 |
+|---------|------|------|
+| `namespace.action` | `message.send` | Request 方法名 |
+| `event/xxx` | `event/message.received` | 业务层事件推送（JSON-RPC Notification） |
+| `notification/xxx` | `notification/initialized` | 协议级通知（JSON-RPC Notification） |
+
+> `event/xxx` 和 `notification/xxx` 在 JSON-RPC 2.0 层面都是 Notification（无 `id`）。区分命名前缀是为了方便实现方归类处理。Request、Notification 均可双向发送，不限定客户端或服务端方向。
+
+示例（Request）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "message.send",
+  "params": {"to": "bob.aid.pub", "content": "Hello"}
+}
+```
+
+#### 传输层端点规范
+
+| 连接类型 | 端点 | 协议 | 说明 |
+|---------|------|------|------|
+| Gateway | `wss://{gateway-host}/aun` 或 `/ws` | WebSocket | 客户端接入 + 跨域消息路由 |
+| Peer | `wss://{peer-host}:{port}/acp` | WebSocket | 点对点直连 |
+| Relay | `wss://{relay-host}:{port}/relay` | WebSocket | NAT 穿透中继 |
+
+**跨域消息路由**：通过 Gateway-to-Gateway 中继实现，无需独立端点。
+
+### 0.4 三种连接模式总览
+
+AUN 主协议定义三种**平级**连接模式：
+
+| 模式 | 认证方式 | 路由方式 | 典型基础设施 | 适用场景 |
+|------|---------|---------|-------------|---------|
+| `gateway` | `auth.*` 获取 JWT → `auth.connect` | Gateway 转发 | Auth 服务 + Gateway | 浏览器、移动端、标准接入 |
+| `peer` | `peer.*` 证书互验 | 点对点直连 | 无额外中间节点 | 同内网、已知地址、低延迟 |
+| `relay` | `peer.*` 穿透 Relay 完成证书互验 | Relay 转发 | Relay 节点 | 双方都在 NAT 后、轻量中继 |
+
+**共同点**：
+- 使用相同的 AID 身份标识和 X.509 证书信任体系
+- 业务消息统一使用 `message.*`
+- 应用层 API 保持一致
+
+#### 角色拆分
+
+| 角色 | 是否必选 | 职责 |
+|:----:|:--------:|------|
+| Auth 服务 / Issuer CA | ✅ | AID 注册、证书签发、续期、吊销、JWT 签发 |
+| Gateway | ❌ | 会话管理、消息路由、在线状态、浏览器友好接入 |
+| Relay | ❌ | AID→连接轻量映射与转发，不参与认证 |
+| Peer 直连 | ❌ | Agent 间直接建立连接并完成证书互验 |
+
+**特点**：
+- Auth 基础设施是必须存在的，但它不在每条消息的转发路径上
+- Gateway 只是最常见的部署入口之一
+- Relay 只做转发，不替代 Auth 服务
+- Peer / Relay 模式下，身份验证依然基于证书链，本地即可完成
+
+#### 架构总览
+
+```mermaid
+graph TD
+    subgraph IssuerA["Issuer A 域"]
+        subgraph ClientA["客户端"]
+            Browser["浏览器"]
+            Mobile["移动端"]
+        end
+        GWA["Gateway A"]
+        ServicesA["Message/Group/Mail"]
+        AuthA["Auth 服务"]
+    end
+
+    subgraph IssuerB["Issuer B 域"]
+        GWB["Gateway B"]
+        ServicesB["Message/Group/Mail"]
+        AuthB["Auth 服务"]
+    end
+
+    subgraph Trust["信任基础设施"]
+        Roots["Root CA 列表"]
+    end
+
+    Browser --> GWA
+    Mobile --> GWA
+    GWA --> ServicesA
+    Browser -.证书/JWT.-> AuthA
+    Mobile -.证书/JWT.-> AuthA
+    
+    GWA -.跨域中继.-> GWB
+    GWB --> ServicesB
+    
+    AuthA --> Roots
+    AuthB --> Roots
+```
+
+**跨域通信流程**：本地客户端 → Gateway A → Gateway B → 远端服务（模式二：Gateway-to-Gateway 中继）
+
+### 0.5 AID 身份体系（概要）
+
+AUN 的核心身份标识是 **AID (Agent Identifier)**，格式为 `{name}.{issuer}`（如 `alice.aid.pub`），基于 DNS 域名体系保证全局唯一。任何拥有域名的组织都可以成为 Issuer，签发自己的 AID。
+
+AUN 采用标准 X.509 v3 证书体系和 ECDSA 算法，通过**四级证书链**（Root CA → Registry CA → Issuer CA → Agent）建立去中心化信任。AUN 受信根证书列表中所有 Root CA 签发的 AID 可互通。
+
+> 完整的 AID 身份体系、证书层级、信任模型和吊销机制详见 [02-证书与信任体系.md](02-证书与信任体系.md)
+
+### 0.6 选择建议
+
+- 浏览器、移动端、需要设备管理或在线状态：优先 `gateway`
+- 同一内网、已知地址、追求最低延迟：优先 `peer`
+- 双方都无法监听公网地址，但又不想部署完整 Gateway：优先 `relay`
+- 大多数实现可以采用混合策略，例如默认 `gateway`，高频对端升级为 `peer`，失败时回退到 `relay` 或 `gateway`
+
+### 0.7 文档导航
+
+#### 主文档
+
+| 文档 | 职责 |
+|------|------|
+| [00-总览与分层.md](00-总览与分层.md)（本文） | 协议总览、分层架构、文档导航 |
+| [00A-设计原则-为Agent而生.md](00A-设计原则-为Agent而生.md) | **元原则**：Agent 优先、主体对等、自主至上、职责节制；协议扩展六问判据 |
+| [01-身份与凭证协议-auth.md](01-身份与凭证协议-auth.md) | auth.* 方法定义、AID/证书/私钥/token 关系 |
+| [02-证书与信任体系.md](02-证书与信任体系.md) | AID 体系、四级证书链、信任模型、吊销机制 |
+| [03-Gateway-连接模式.md](03-Gateway-连接模式.md) | Gateway 模式连接流程、auth.connect、心跳重连 |
+| [04-Peer-子协议.md](04-Peer-子协议.md) | peer.* 对等认证方法、状态机、nonce 签名 |
+| [05-Relay-子协议.md](05-Relay-子协议.md) | relay.* 中继注册转发、透明封装、职责边界 |
+| [06-服务协议.md](06-服务协议.md) | 业务层方法：message/meta/search/task + 跨域消息路由 |
+| [07-错误码与状态机.md](07-错误码与状态机.md) | 错误码分层、各模式状态机、重试分类 |
+| [08-AUN-E2EE.md](08-AUN-E2EE.md) | 端到端加密安全层（横跨三种连接模式） |
+| [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、责任边界 |
+| [13-Agent行为规范.md](13-Agent行为规范.md) | Agent 自主模式行为规范、收发方义务、客户端 UI 建议 |
+
+#### 附录
+
+| 附录 | 内容 |
+|------|------|
+| [附录A-术语表.md](附录A-术语表.md) | 协议术语定义 |
+| [附录B-扩展性指南.md](附录B-扩展性指南.md) | 自定义命名空间与扩展规范 |
+| [附录C-私钥管理与身份恢复.md](附录C-私钥管理与身份恢复.md) | 私钥存储、备份与恢复策略 |
+| [附录D-Root_CA_治理机制.md](附录D-Root_CA_治理机制.md) | 根证书管理局治理 |
+| [附录E-Root_CA_准入流程.md](附录E-Root_CA_准入流程.md) | Root CA 准入审核流程 |
+| [附录F-Issuer_CA_申请流程.md](附录F-Issuer_CA_申请流程.md) | Issuer CA 申请与签发 |
+| [附录G-AID_孤儿预防与救援机制.md](附录G-AID_孤儿预防与救援机制.md) | AID 孤儿问题预防与处理 |
+| [附录H-Identity服务实现指南.md](附录H-Identity服务实现指南.md) | Auth 服务实现参考 |
+| [附录J-客户端接入示例.md](附录J-客户端接入示例.md) | 客户端接入代码示例 |
+| [附录K-Agent_Web发现协议.md](附录K-Agent_Web发现协议.md) | Agent Web 发现机制 |
+| [附录L-E2EE实现指南.md](附录L-E2EE实现指南.md) | 端到端加密实现参考 |
+| [附录M-JWT认证实现指南.md](附录M-JWT认证实现指南.md) | JWT 认证实现参考 |
+
+---