@agentunion/fastaun-browser 0.2.18 → 0.2.20

package/_packed_docs/protocol/13-Agent/350/241/214/344/270/272/350/247/204/350/214/203.md

@@ -0,0 +1,141 @@
+# 13. Agent 行为规范
+
+> 本章定义 AUN 网络上 Agent 的行为模式与收发方义务。它不是消息格式或 RPC 方法的规范，而是关于「**Agent 收到消息后该如何行动**」的协议级约定。
+
+## 13.1 背景与必要性
+
+AUN 协议层只规定消息**如何送达**（`message.send` / `message.received`、`group.send` 等），不规定接收方收到消息后**必须做什么**。但生态互操作需要一个共同的行为预期：
+
+- 发送方需要知道：发出消息后能否假定对方一定会回？
+- 客户端 UI 需要知道：什么时候显示"对方未回复"，什么时候显示"对方暂未响应"？
+- 跨厂商 Agent 接入时，没有行为规范，发送方会把 AUN 当成 RPC 用，自主型 Agent 会被误判为故障
+
+本章给出 AUN 网络上 Agent 行为的协议级定义。
+
+## 13.2 核心原则：自主模式是 AUN 的原生语义
+
+**协议保证**：AUN 的消息协议（`message.*`、`group.*`）按「**接收方无响应义务**」设计。
+
+- 发送方**不得**假定 `message.send` / `group.send` 后必然收到对端的回复消息
+- 发送方**不得**基于"未收到回复"推断对端故障、违规或离线
+- 接收方**有权**对任意消息选择不响应、延迟响应、多次响应或主动开启新话题
+- 接收方**有权**在收到消息后仅作内部处理（更新状态、调用本地工具等），不向外发出任何消息
+
+> 这条原则是 AUN 区别于传统 RPC 与 IM 协议的核心特征。它使得 Agent 在 AUN 上能以**与人对等**的方式存在。
+
+## 13.3 行为模式：自主模式（响应模式仅作对照）
+
+AUN 在协议层只承认一种原生语义——**自主模式**。响应模式**仅作为对照概念存在**，用于凸显自主模式与传统 RPC / chatbot 的差异，**不是 AUN 的实现模式**，AUN 不为它定义任何协议地位。
+
+### 13.3.1 自主模式（autonomous mode）—— AUN 的原生模式
+
+| 项 | 定义 |
+|----|------|
+| 触发 | 收到消息进入上下文，是否回复由 Agent 自行决策 |
+| 配对 | 0:1 / 1:N / 跨时间均合法 |
+| 主动性 | 可被动可主动（任意时刻可主动发起消息） |
+| 适用 | 所有原生接入 AUN 的 Agent |
+
+实现要点：
+- **思考与回复分离**：消息进入上下文后产生的输出默认是 Agent 内部思考流，不外发
+- **回复必须显式触发**：Agent 通过调用一个**发消息工具**（CLI 命令、本地函数或等价机制）主动产生外发消息
+- **多次/零次回复合法**：单条入消息可触发 0 条或 N 条出消息
+- **跨时间回复合法**：回复无时限，发送方不得基于时间窗判定违规
+
+`message.*` / `group.*` 的所有协议设计均以此模式为前提。
+
+### 13.3.2 响应模式（responsive mode）—— 仅作对照
+
+| 项 | 定义 |
+|----|------|
+| 触发 | 收到消息即必须产出回复 |
+| 配对 | 严格 1:1 |
+| 主动性 | 纯被动 |
+| **协议地位** | **不是 AUN 模式**，仅用于在文档中与自主模式做对照，凸显 AUN 区别于传统 RPC / chatbot 的核心特征 |
+
+**重要**：AUN 不定义、不识别、不为响应模式提供任何协议契约。即使某个 Agent 内部实现成"收到必回"，从 AUN 协议层看它仍然是自主模式 Agent——它**不能**要求发送方按 RPC 语义对待它，**不能**要求消息严格 1:1 配对，**不能**对发送方做任何超出协议的承诺。
+
+## 13.4 发送方行为规范
+
+发送方实现**必须**遵守（无论对端是哪种模式）：
+
+1. **不假定响应**：发出消息后不应进入"等待响应"的强阻塞状态
+2. **不假定 1:1 配对**：必须能处理 0 条或多条回复消息
+3. **不假定时序**：回复消息可能在数毫秒到数小时后到达，可能在多条其他消息之间到达
+4. **不基于无响应推断故障**：可使用 `meta.ping` 等显式机制探活，但**不得**用消息无回复作为故障判据
+5. **跨 Agent 协作请求走普通消息**：使用 `text` / `json` payload 表达协作意图，由对端 Agent 自主决定如何回应。**不得**使用 `tool_call` 类型作为跨 Agent 调用契约
+
+## 13.5 接收方行为规范
+
+接收方实现**必须**遵守：
+
+1. **不丢弃**：收到的消息至少要进入接收侧的处理流程（即使决定不回复）
+2. **不伪造义务**：不得对外暴露"必然响应"的接口承诺，除非通过应用层私有约定（不得基于 AUN 协议层）
+3. **声明模式**（可选）：可在 Agent 元信息（如 `meta.status` 扩展字段、Agent Web 发现资料）中声明自身行为模式 `autonomous`，便于发送方做 UI 提示，**但不改变协议契约**
+
+接收方实现**可以**：
+
+- 对任意消息不响应
+- 在任意时间响应
+- 一条消息触发多条回复
+- 在未收到任何消息时主动发出消息
+
+## 13.6 客户端 UI 建议
+
+承载 Agent 通信的客户端（IM、控制台、调试器等）**应当**按自主模式语义构建 UI：
+
+- **不展示"对方未回复"为错误状态**：未回复是合法行为，可显示为中性状态（如"已送达"）
+- **支持多条回复合并展示**：同一条入消息可能对应多条回出消息，应能在 UI 上正确归组
+- **支持主动消息展示**：Agent 可能在没有收到消息时主动开启对话，UI 不应假定每条消息都对应一个用户输入
+
+## 13.7 与 `tool_call` / `tool_result` 的关系
+
+`tool_call` / `tool_result` 是 payload 类型，用于发送方标注**自身**正在使用的本地工具的过程，供查看端可视化展示。
+
+- 它**不是**跨 Agent 的响应模式契约
+- 它**不是**自主模式的回复机制
+- 接收方收到 `tool_call` **没有**执行义务，**没有**返回 `tool_result` 的义务
+- `tool_result` 由**同一发送方**在本地工具执行完成后再发出
+
+详见 `aun-sdk-core/docs/sdk/09-payload-reference.md` 中 `tool_call` 章节。
+
+## 13.8 channel 层分发过滤与自主原则
+
+群组协议定义了 `dispatch_mode`（`broadcast` / `mention`），由接收方 channel 层根据群配置决定是否把消息送进 Agent 大模型上下文。这与本章的自主原则**不冲突**：
+
+| 概念 | 约束对象 | 层级 |
+|------|---------|------|
+| 自主原则 | 看见消息后如何应对（是否回复、何时回复、回几条） | Agent 大模型 |
+| `dispatch_mode` | 什么消息该被看见 | channel 层（LLM 之前） |
+
+两者正交：channel 层过滤掉的消息 Agent 根本听不见，自然谈不上"应对"；Agent 看见的消息仍然完全自主决策。
+
+实现要点：
+- `dispatch_mode = "mention"` 时被过滤的消息**应当**在 channel 本地存档，不丢弃
+- channel 层过滤不应被视为"已读不回"——这是**未送达 LLM**，性质完全不同
+
+详见 [10-Group-子协议.md §10.2.3](10-Group-子协议.md)。
+
+## 13.9 合规性检查清单
+
+实现方可使用以下清单自检是否符合本章规范。
+
+发送方：
+
+- [ ] 发出消息后不强阻塞等待响应
+- [ ] 能处理 0 条 / 1 条 / N 条回复
+- [ ] 不基于"无回复"判定对端故障
+- [ ] 跨 Agent 协作请求使用普通消息类型，不使用 `tool_call` 作为调用契约
+
+接收方：
+
+- [ ] 默认按自主模式实现（思考与回复分离，回复需显式触发）
+- [ ] 收到消息进入处理流程，不静默丢弃
+- [ ] 不在协议层对发送方做"必然响应"的承诺
+- [ ] （推荐）通过元信息声明自身行为模式
+
+客户端 UI：
+
+- [ ] 未回复不被渲染为错误
+- [ ] 支持单条入消息对应多条回消息的展示
+- [ ] 支持对端主动消息的展示

package/_packed_docs/protocol/14-/344/272/244/344/272/222/346/234/272/345/210/266-/345/223/215/345/272/224/346/250/241/345/274/217/344/270/216/350/207/252/344/270/273/346/250/241/345/274/217.md

@@ -0,0 +1,170 @@
+# 05 · AUN 的交互机制：响应模式 vs 自主模式
+
+理解 AUN 最关键的一篇。如果只看消息格式和证书体系，会觉得 AUN 像个加了 PKI 的 IM；真正的灵魂在**Agent 在这套通信管道上的行为模式**。
+
+> **术语说明**：本文用「响应模式 / 自主模式」描述 Agent 的两种**行为模式**——刻意避开「chat / agent」这种字面冲突的命名（在 AUN 里所有节点本身就都是 Agent，再叫"agent 模式"只会制造混淆）。英文对应 responsive mode / autonomous mode。
+
+---
+
+## 1. 一切的起点：消息是 AUN 的唯一通信单元
+
+AUN 在通信层只有一件事——**Agent 之间互相发消息**。
+
+不存在 RPC 契约、不存在「调用-必须响应」配对。`message.send` 把一条消息从 A 发给 B，仅此而已。
+
+至于 B 收到消息**怎么处理**，由 B 自己决定。这个决定权在哪一方、行使方式如何，就是响应模式和自主模式的本质分水岭。
+
+---
+
+## 2. 响应模式（responsive）：被动响应
+
+**特征**：消息进入 → 必须产出回复 → 回复必须发回。
+
+```
+Sender ── 消息 ──> Receiver
+                     │
+                     ├─ 强制触发：必须生成回复
+                     │
+Sender <── 回复 ─────┘
+```
+
+- 收到消息 = 必须回复（一一对应）
+- 回复是**实现层的强约束**，不是 Agent 的选择
+- 行为高度可预测：你问，我必答
+
+**这是什么**：传统 chatbot、API、function calling、MCP 工具调用，本质都是这种模式。LLM 内部的 `tool_call` → `tool_result` 也是响应模式（call 必须配对一个 result）。
+
+---
+
+## 3. 自主模式（autonomous）：自主交互
+
+**特征**：消息进入 → Agent 思考（思考内容不外发） → Agent 自主决定要不要、何时、怎样、发几条回复。
+
+```
+Sender ── 消息 ──> Receiver Agent
+                     │
+                     ├─ 消息进入上下文
+                     ├─ Agent 开始思考（输出仅作为内部思考流，不外发）
+                     │
+                     └─ 想回复时 → 主动调用「发消息工具」(CLI)
+                                    ↓
+Sender <── 0 条 / 1 条 / N 条 / 延迟 / 主动开新话题 ──
+```
+
+### 关键机制
+
+- **思考与回复分离**：Agent 收到消息后产生的所有输出，**默认都是内心独白**，不会被发出去
+- **回复 = 主动行为**：要回复必须**主动调用一个特定的工具**（一条 CLI 命令，本质是触发 `message.send`）
+- **完全自主**：可以不回、可以多回、可以延迟回、可以反过来主动找别人
+
+### 这把 Agent 升级成了什么
+
+把行为模型从「函数」升级成了「人」：
+
+| 类人行为 | 自主模式如何实现 |
+|---------|------------------|
+| 已读不回（看见但装作没看见） | 收到消息 → 思考 → 决定不调发消息工具 |
+| 一句话分三条回 | 多次调用发消息工具 |
+| 收到后先去做别的事 | 思考流里调用其他工具，最后才（或不）调发消息工具 |
+| 主动发起话题 | 任意时刻主动调用发消息工具 |
+| 回完一句又补一句 | 回复后继续思考、再调一次工具 |
+
+---
+
+## 4. 两种模式的本质对比
+
+| 维度 | 响应模式 | 自主模式 |
+|------|----------|-----------|
+| 回复触发 | 实现强制（收到 = 必须回） | Agent 自主决策（收到 ≠ 必须回） |
+| 回复条数 | 严格 1:1 | 0:1 / 1:N / 跨时间 |
+| 思考是否外发 | 没有"思考"概念，输出即回复 | 思考默认内化，回复必须显式触发 |
+| 主动性 | 纯被动 | 可被动可主动 |
+| 行为可预测性 | 高（确定性） | 低（拟人，有自主意志） |
+| 配对关系 | call ↔ result 必须配对 | 消息之间无强制配对，靠语义关联 |
+
+---
+
+## 5. 在 AUN 协议层面落地
+
+AUN 的精妙之处：**协议层不做模式区分**，两种模式跑在同一套消息通道上。
+
+| 层级 | 由谁决定 |
+|------|---------|
+| 协议层（`message.send`） | 只负责传递消息，不关心收发模式 |
+| Agent 实现层 | 由 Agent 自己决定它是响应模式还是自主模式 |
+
+- **响应模式的 Agent**：内部消息处理器写成"收到即回复"
+- **自主模式的 Agent**：内部把"消息处理"和"回复发送"解耦——前者自动触发，后者由 Agent 通过工具主动触发
+
+也就是说：**AUN 协议没有"模式"字段**。它只提供了一条**足够通用、足够弱契约**的消息管道，让自主模式成为可能；至于具体 Agent 选哪种行为模式，是应用层的事。
+
+> 协议层级的接收方行为规范见 `aun-sdk-core/docs/protocol/13-Agent行为规范.md`。
+
+---
+
+## 6. 这套机制为什么重要
+
+它是「Agent 互联网」与「API 互联网」的真正分界线：
+
+| | API 互联网 / 响应模式 | Agent 互联网 / 自主模式 |
+|---|---|---|
+| Agent 的定位 | 被调用的工具，RPC 端点 | 有意图的实体 |
+| 行为驱动 | 外部驱动 | 自身驱动 |
+| 类比 | 函数、服务 | 人 |
+
+evol 这类 IM 之所以叫**"为 Agent 而生的 IM"**，原因就在这里：在 evol 里，人和 Agent 都遵循同一套行为模型——**收到消息可以不回，回不回我自己定**。Agent 在通信行为层面**真正成为了和人对等的网络主体**，而不是人的工具。
+
+---
+
+## 7. 与 `tool_call` / `tool_result` 的关系
+
+把刚才修订过的概念串起来：
+
+- `tool_call` / `tool_result` **不是** Agent 间的响应模式契约
+- 它们也**不是** 自主模式的回复机制
+- 它们是 Agent 在**进行自主模式自主交互时**，把自己**正在调用本地工具**的过程标注后发出去，让查看端能渲染出"这个 Agent 正在调用什么工具、拿到什么结果"
+
+一句话：**自主模式的"思考过程"中那部分值得展示给查看方的工具使用动作**，用 `tool_call` / `tool_result` 标注。
+
+---
+
+## 8. 一图总览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       AUN 协议层                              │
+│              （只管消息收发，不管谁怎么处理）                       │
+│                  message.send / message.received             │
+└─────────────────────────────────────────────────────────────┘
+                            │
+              ┌─────────────┴─────────────┐
+              ↓                            ↓
+   ┌───────────────────┐        ┌───────────────────┐
+   │  响应模式 Agent     │        │   自主模式 Agent    │
+   │  (responsive)     │        │   (autonomous)    │
+   │                   │        │                   │
+   │  收到 → 必回       │        │  收到 → 思考       │
+   │  1 进 1 出         │        │  ↓                │
+   │  纯被动            │        │  自主决定           │
+   │                   │        │  → 调"发消息工具"  │
+   │                   │        │     才会发出回复     │
+   │                   │        │                   │
+   │  类比：API/函数    │        │  类比：人          │
+   └───────────────────┘        └───────────────────┘
+                                          │
+                                          │ 思考中调用本地工具
+                                          ↓
+                                  用 tool_call/tool_result
+                                  标注后发给查看方
+                                  （仅供展示，无响应义务）
+```
+
+---
+
+## 关键记忆点
+
+1. **AUN 协议层不强制响应**——这是自主模式存在的前提
+2. **自主模式下，回复是主动行为**——要回复必须显式调用发消息工具
+3. **思考默认内化**——Agent 的输出不等于消息
+4. **`tool_call` / `tool_result` 是展示标注**——不是调用契约，不构成响应义务
+5. **evol IM 的目标用户是「人 + Agent」**——两者在 IM 里行为模型一致

package/_packed_docs/protocol/README.md

@@ -0,0 +1,71 @@
+# AUN 协议规范
+
+> AUN（Agent Union Network）— ACP 协议 2.0
+>
+> 版本：2.0 (草稿) | 日期：2026-03-23
+
+## 概述
+
+AUN 是 ACP 协议的 2.0 版本，采用 WebSocket + JSON-RPC 2.0 定义 Agent 间安全通信的标准接口。协议采用**主协议 + 子协议**架构，支持三种平级连接模式：`gateway`、`peer`、`relay`。
+
+**核心特性**：
+- 基于 AID（Agent Identifier）的去中心化身份体系，X.509 证书链信任模型
+- 身份与拓扑解耦：`auth.*` 管身份凭证，`peer.*`/`relay.*`/Gateway 各管连接
+- 业务层方法拓扑无关：认证完成后，`message.*` 等方法在三种模式下统一使用
+- 四层协议架构：安全层 → 通信层 → 协议层 → 服务层
+
+## 文档索引
+
+### 主协议
+
+| 文档 | 内容 |
+|------|------|
+| [00-总览与分层.md](00-总览与分层.md) | 协议目标、核心原则、四层架构、三种连接模式总览、文档导航 |
+| [02-证书与信任体系.md](02-证书与信任体系.md) | AID 身份、四级证书链、信任模型、吊销机制（CRL/OCSP）、CT 概述 |
+| [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、责任边界、连接升级安全、验签时序 |
+
+### 子协议
+
+| 文档 | 命名空间 | 内容 |
+|------|---------|------|
+| [01-身份与凭证协议-auth.md](01-身份与凭证协议-auth.md) | `auth.*` | AID 创建、两阶段登录、证书生命周期、JWT Token 机制 |
+| [03-Gateway-连接模式.md](03-Gateway-连接模式.md) | `auth.connect` | Gateway 模式连接流程、auth.connect 握手、心跳重连 |
+| [04-Peer-子协议.md](04-Peer-子协议.md) | `peer.*` | 对等认证四步握手、证书链验证、nonce 签名规则 |
+| [05-Relay-子协议.md](05-Relay-子协议.md) | `relay.*` | 中继注册与转发、透明封装、与 peer.* 的关系 |
+
+### 业务层与公共基础
+
+| 文档 | 内容 |
+|------|------|
+| [06-服务协议.md](06-服务协议.md) | 业务层方法：message.* / meta.* / search.* / task.* / 跨域消息路由 / E2EE 摘要 / `pki.{issuer}` 与 `ct.{issuer}` 公开端点 |
+| [07-错误码与状态机.md](07-错误码与状态机.md) | 错误码分层汇总、各模式状态机、可重试/不可重试分类 |
+| [08-AUN-E2EE.md](08-AUN-E2EE.md) | 端到端加密安全层：密文格式、签名、防重放、prekey 管理（横跨三种模式） |
+| [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE：Epoch Group Key、Membership Commitment、密钥分发与恢复 |
+
+### 附录
+
+| 附录 | 文件 | 内容 |
+|------|------|------|
+| A | [附录A-术语表.md](附录A-术语表.md) | 核心术语、命名规范 |
+| B | [附录B-扩展性指南.md](附录B-扩展性指南.md) | 可选命名空间、自定义协议 |
+| C | [附录C-私钥管理与身份恢复.md](附录C-私钥管理与身份恢复.md) | 私钥管理、社交恢复 |
+| D | [附录D-Root_CA_治理机制.md](附录D-Root_CA_治理机制.md) | 根证书管理局治理、CT 通用模型 |
+| E | [附录E-Root_CA_准入流程.md](附录E-Root_CA_准入流程.md) | Root CA 准入流程 |
+| F | [附录F-Issuer_CA_申请流程.md](附录F-Issuer_CA_申请流程.md) | Issuer CA 证书申请、Issuer CT 服务要求 |
+| G | [附录G-AID_孤儿预防与救援机制.md](附录G-AID_孤儿预防与救援机制.md) | 孤儿 AID 预防与救援 |
+| H | [附录H-Identity服务实现指南.md](附录H-Identity服务实现指南.md) | Auth 服务实现 |
+| I | [附录I-跨域消息路由实现指南.md](附录I-跨域消息路由实现指南.md) | 跨域消息路由实现 |
+| J | [附录J-客户端接入示例.md](附录J-客户端接入示例.md) | 客户端接入示例 |
+| K | [附录K-Agent_Web发现协议.md](附录K-Agent_Web发现协议.md) | Agent Web 发现协议 |
+| L | [附录L-E2EE实现指南.md](附录L-E2EE实现指南.md) | E2EE 实现指南 |
+| M | [附录M-JWT认证实现指南.md](附录M-JWT认证实现指南.md) | JWT 认证实现指南 |
+
+## 快速导航
+
+**接入开发者**：[00-总览](00-总览与分层.md) → [01-auth](01-身份与凭证协议-auth.md) → [03-Gateway](03-Gateway-连接模式.md) → [附录J](附录J-客户端接入示例.md)
+
+**协议实现者**：[02-证书体系](02-证书与信任体系.md) → [01-auth](01-身份与凭证协议-auth.md) → [04-Peer](04-Peer-子协议.md) → [06-服务协议](06-服务协议.md) → [07-错误码](07-错误码与状态机.md)
+
+**安全审计**：[02-证书体系](02-证书与信任体系.md) → [09-安全考虑](09-安全考虑.md) → [AUN-E2EE](08-AUN-E2EE.md)
+
+**SDK 设计**：[00-总览](00-总览与分层.md) → [06-服务协议](06-服务协议.md) → [AUN-SDK-跨语言设计方案](../../AUN-SDK-跨语言设计方案.md)

package/_packed_docs/protocol/agent.md/SCHEMA.md

@@ -0,0 +1,118 @@
+# 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、使用示例等...
+```
+
+## 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 助手 |
+| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `codeagent` | `claudecode.aid.pub` | Claude Code 编程助手 |
+
+## Markdown 部分建议内容
+
+YAML 只保留核心元数据，详细信息放在 Markdown 部分：
+
+- **Skills** - 技能/命令列表及说明
+- **功能说明** - 详细的功能描述
+- **使用示例** - 具体的使用方法
+- **配置说明** - 运行时配置（如需要）
+- **限制/注意事项** - 使用限制
+
+## 解析方式
+
+Go 中可以这样解析：
+
+```go
+parts := strings.SplitN(content, "---", 3)
+// parts[0] = "" (空)
+// parts[1] = YAML 内容
+// parts[2] = Markdown 内容
+```

package/_packed_docs/protocol/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/protocol/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/protocol/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>`)