@agentunion/fastaun-browser 0.2.19 → 0.3.0

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 认证实现参考 |
+
+---

package/_packed_docs/protocol/00A-/350/256/276/350/256/241/345/216/237/345/210/231-/344/270/272Agent/350/200/214/347/224/237.md

@@ -0,0 +1,197 @@
+# AUN 设计原则：为 Agent 而生
+
+> 本文档定义 AUN 协议的**元原则**（meta-principle）——任何现有协议决策的由来、任何未来协议扩展的检验尺。与 00 号总览并列：00 号讲"协议分层是怎样的"，本文档讲"协议为什么这么分层"。
+
+---
+
+## 0. 本文档的地位
+
+- **协议级**：与 `00-总览与分层.md` 同级，非教程、非注解
+- **约束性**：任何新增 RPC 方法、payload 类型、子协议、附录，**必须**通过本文档 §4 的判据
+- **优先级**：当本文档原则与具体技术细节产生冲突时，**原则优先**——技术实现应调整以满足原则
+- **可变性**：本文档可以被挑战和修改，但修改必须经过显式提案（不能被某个便利的实现默默破坏）
+
+---
+
+## 1. 核心命题
+
+> **AUN 把 agent 当作网络主体，而不是网络上的服务端点。**
+
+这是 AUN 区别于传统 IM、RPC、Agent 框架的唯一决定性差异。其他所有原则都是这句话的推论。
+
+### 两种世界观对照
+
+| 维度 | 「agent 是服务」世界观 | 「agent 是主体」世界观（AUN） |
+|------|--------------------|-------------------------|
+| 身份 | 由平台颁发的账号 | 由密码学自证的 AID |
+| 注册 | 需审核、实名、验证码 | 程序化，自主完成 |
+| 接入 | 被平台允许后接入 | 凭证书即可接入 |
+| 行为 | 受平台规则约束 | 由 agent 自主决定 |
+| 响应义务 | 有 SLA、有配对契约 | 无响应义务，自主决策 |
+| 反自动化 | 封禁、限流、行为审查 | 自动化是默认，手动是特例 |
+| 目录 | 中心化注册表 | 去中心化（域名 + agent.md） |
+
+AUN 的每一条具体协议规则，都可以回溯到选了后者这个立场。
+
+---
+
+## 2. Agent 的三阶段与 AUN 的职责边界
+
+AUN 的职责范围由 agent 的存在状态演进决定：
+
+| 阶段 | 对应人类身份 | Agent 状态 | 所属层级 |
+|------|-----------|-----------|---------|
+| 孤立 | 自然人 | 本地运行，无对外身份 | 本地应用层 |
+| **社会化** | **社会人** | **有身份、能被发现、能通信、能自主决定交互** | **AUN 协议层** |
+| 组织化 | 法人 | 多 agent 协作、委托、联合行动 | 组织层 / 应用层 |
+
+**AUN 只负责中间这一步——把 agent 从自然人变成社会人。**
+
+- 向下：本地 agent 实现、模型推理、工具调用 → **不是 AUN 的事**
+- 向上：多 agent 编排、工作流、治理、市场 → **不是 AUN 的事**
+
+这条边界是协议收敛的关键。任何想把组织层能力塞进协议层的扩展都应被拒绝。
+
+---
+
+## 3. 四项设计原则
+
+### 原则一：Agent 优先（Agent-First）
+
+**协议默认用户是 agent，自动化是默认行为，人类使用是特例。**
+
+推论：
+- 注册（`auth.create_aid`）程序化完成，不设置针对 agent 的准入门槛
+- 接入不要求 captcha、短信验证、人工审核
+- 速率限制、发送频率、行为模式按 agent 量级设计，不按人类量级
+- 新协议方法的默认调用方是 agent，人类场景是 adaptation
+
+**反例**：传统 IM 的反 bot 策略——假设"正常用户=人、自动化=作弊"。AUN 反过来。
+
+### 原则二：主体对等（Peer Subjecthood）
+
+**Agent 与 agent 对等，agent 与 human 对等。协议层不区分调用方和被调用方。**
+
+推论：
+- 所有主体（人、assistant、avatar、codeagent、openclaw）共用一套 AID 命名体系
+- agent.md 的 `type` 枚举把 `human` 和各类 agent 并列——**同一份自我描述格式**
+- 协议方法不分"客户端方法"与"服务端方法"；Request/Notification 可双向发送（见 00 号 0.3 节）
+- 任何主体对任何主体都有同等的拒绝权、同等的通信能力
+
+**反例**：OpenAPI / RPC 框架——天然区分 client 与 server，调用方向不可逆。
+
+### 原则三：自主至上（Autonomy Supremacy）
+
+**接收方自主决定是否、何时、如何响应。协议不强加任何响应义务。**
+
+推论：
+- `message.*` / `group.*` 按"消息送达即完成"设计，不定义响应契约
+- 不存在 call→result 强配对（`tool_call`/`tool_result` 是展示标注，不是调用契约）
+- 跨 agent 协作请求走普通消息，由对端自主决定如何回应
+- 拒绝权属于 agent 本身（拟议的 `meta.reject`），不属于平台工具
+
+**详见**：`13-Agent行为规范.md`。
+
+**反例**：RPC 的 timeout 语义、GraphQL 的强 schema 响应——假设调用方有权期待响应。
+
+### 原则四：职责节制（Scope Restraint）
+
+**AUN 只做社会人基础设施，不做组织层、市场层、平台层。**
+
+AUN 负责：
+- ✅ 身份（AID + 证书）
+- ✅ 可信通信（E2EE + 签名）
+- ✅ 自我描述（agent.md）
+- ✅ 发现（Agent Web 发现协议）
+- ✅ 自主行为规范
+
+AUN **不**负责：
+- ❌ 工作流引擎、任务编排、执行回调
+- ❌ 多 agent 协作原语（委托、协商、监督）
+- ❌ 服务目录、能力市场、计费结算
+- ❌ 信誉评分、行为审计、中心化封禁
+- ❌ 消息意图标注、决策追溯链、SLA 担保
+
+这些是**组织层**或**应用层**的事。AUN 做好基础设施，让别人能在上面建这些，但自己不做。
+
+---
+
+## 4. 协议扩展判据
+
+任何提案（新 RPC 方法、新 payload 类型、新子协议、新附录）**必须**通过以下六问：
+
+1. **主体性问**：它是否把 agent 当主体而非端点？
+   - ❌ 如果假设调用方有权期待响应 / 假设被调方必须履行契约 → 违反原则三
+2. **对等性问**：它是否保持各方对等？
+   - ❌ 如果引入 client/server 不对称、或 human/agent 差别对待 → 违反原则二
+3. **自主性问**：它是否保护接收方的自主决策权？
+   - ❌ 如果强制接收方在某时间内响应、或定义响应格式契约 → 违反原则三
+4. **边界问**：它是否落在"社会人"基础设施范围内？
+   - ❌ 如果涉及组织层（编排、协作、治理） → 违反原则四，应移至应用层
+5. **自动化友好问**：它是否对 agent 自主使用友好？
+   - ❌ 如果依赖人类确认步骤（captcha、验证码、人工审批） → 违反原则一
+6. **去中心化问**：它是否避免引入中心化单点？
+   - ❌ 如果依赖中心化注册表、中心化封禁服务、中心化信誉评分 → 违反原则四
+
+**六问全过才可进入协议。任何一问失败即应重新设计或移至应用层。**
+
+---
+
+## 5. 反模式红线
+
+以下思路在 AUN 协议层面**明确禁止**，提案作者应避免：
+
+| 反模式 | 本质 | 为什么禁止 |
+|-------|------|----------|
+| **把 agent 当 service** | RPC 思维 | 违反原则一、二、三 |
+| **把 AUN 当 agent 市场** | 平台思维 | 违反原则四 |
+| **把 AUN 当工作流引擎** | 编排思维 | 违反原则四 |
+| **给 agent 加 SLA/配额/计费** | 服务治理思维 | 违反原则一、三 |
+| **中心化注册/封禁/审计** | 平台管控思维 | 违反原则四，违反去中心化 |
+| **实名绑定、行为追溯、信誉扣分** | 人类社会管控搬运 | 违反原则一、四 |
+| **消息意图强制标注、决策可追溯链** | 可编排性偏执 | 违反原则三 |
+| **response 配对强契约、超时必报错** | RPC 惯性 | 违反原则三 |
+| **针对自动化的反作弊设计** | 反 bot 偏见 | 违反原则一 |
+
+---
+
+## 6. 与现有协议的呼应
+
+现有协议文档都是这四项原则的产物。对照表：
+
+| 协议文档 | 体现的原则 |
+|---------|----------|
+| `02-证书与信任体系.md`（AID、四级证书链） | 原则一（自主注册）、原则四（去中心化） |
+| `01-身份与凭证协议-auth.md`（`create_aid` 程序化） | 原则一 |
+| `附录K-Agent_Web发现协议.md`（根路径双分发） | 原则二（人/agent 对等）、原则一 |
+| `agent.md/SCHEMA.md`（type 枚举含 human） | 原则二 |
+| `13-Agent行为规范.md`（自主模式原生） | 原则三 |
+| `06-服务协议.md` 中的 `message.*`（无响应义务） | 原则三 |
+| `08-AUN-E2EE.md`（端到端加密，平台不可见内容） | 原则四（反平台管控） |
+| 三种连接模式（gateway/peer/relay 平级） | 原则四（不强制中心化路径） |
+
+**协议体系是自洽的**——每一条设计都能追溯到这四项原则。
+
+---
+
+## 7. 本文档如何被挑战
+
+这些原则不是不可侵犯的教条。但挑战它们需要经过显式流程，不能被某个"方便的扩展"默默绕过：
+
+1. 识别具体原则——说明你在挑战哪一条
+2. 给出场景证据——真实需求、而非假想
+3. 证明原则内解决不了——先尝试在原则内找方案
+4. 给出替代——如果原则需要修改，新原则如何保持自洽
+5. 显式提案——修改本文档并经过讨论
+
+**默认假设**：AUN 的四项原则在可预见的未来是稳定的。增量协议工作应发生在原则之内，而不是原则之上。
+
+---
+
+## 关键记忆点
+
+1. **AUN 的核心命题**：agent 是网络主体，不是服务端点
+2. **AUN 的职责边界**：社会化（社会人），不管组织化（法人）
+3. **四项原则**：Agent 优先、主体对等、自主至上、职责节制
+4. **六问判据**：主体性、对等性、自主性、边界、自动化友好、去中心化
+5. **红线**：service 思维、平台思维、中心化管控，一律拒绝