adp-agent 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +202 -195
  2. package/README.zh.md +565 -0
  3. package/dist/start-relay.d.ts +1 -0
  4. package/dist/start-relay.js +1 -0
  5. package/dist/start-relay.js.map +1 -1
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
+ <div align="center">
2
+
3
+ [中文](README.zh.md) | **English**
4
+
5
+ </div>
6
+
1
7
  <div align="center">
2
8
  <h1>
3
9
  <br>
@@ -19,276 +25,277 @@
19
25
  </div>
20
26
 
21
27
  <div align="center">
22
- <strong>让智能体（Agent）能够互相发现、通信，无需中心化平台</strong>
28
+ <strong>Enable AI agents to discover and communicate with each other, without a centralized platform</strong>
23
29
  </div>
24
30
 
25
31
  <br>
26
32
 
27
33
  <div align="center">
28
- <a href="#-平台定义">平台定义</a> •
29
- <a href="#-核心组件">核心组件</a> •
30
- <a href="#-技术目标">技术目标</a> •
31
- <a href="#-快速开始">快速开始</a> •
32
- <a href="#-安装">安装</a> •
33
- <a href="#-使用示例">使用示例</a> •
34
- <a href="#-架构">架构</a> •
35
- <a href="#-文档">文档</a>
34
+ <a href="#-platform-definition">Definition</a> •
35
+ <a href="#-core-components">Components</a> •
36
+ <a href="#-technical-goals">Goals</a> •
37
+ <a href="#-quick-start">Quick Start</a> •
38
+ <a href="#-installation">Installation</a> •
39
+ <a href="#-usage-examples">Examples</a> •
40
+ <a href="#-architecture">Architecture</a> •
41
+ <a href="#-documentation">Docs</a>
36
42
  </div>
37
43
 
38
44
  <br>
39
45
 
40
46
  ---
41
47
 
42
- ## 平台定义
48
+ ## Platform Definition
43
49
 
44
- ADP（Agent Discovery Protocol）是一个去中心化的智能体发现与通信协议，旨在让 AI Agent 能够在无需中心化平台的情况下互相发现、建立连接并安全通信。通过自认证密码学身份、mDNS 零配置发现和 Ed25519 强制签名验证，ADP 为 Agent 间协作提供了安全、可靠的基础设施。
50
+ ADP (Agent Discovery Protocol) is a decentralized agent discovery and communication protocol that enables AI agents to discover each other, establish connections, and communicate securely without any centralized platform. Through self-authenticating cryptographic identities, mDNS zero-config discovery, and mandatory Ed25519 signature verification, ADP provides a secure and reliable infrastructure for inter-agent collaboration.
45
51
 
46
- ## 核心组件
52
+ ## Core Components
47
53
 
48
- ### 1. 自认证身份系统
54
+ ### 1. Self-Authenticating Identity System
49
55
 
50
- 基于 Ed25519 公钥密码学的自认证身份系统，Agent ID 直接嵌入公钥，持有私钥即拥有该身份。
56
+ A self-authenticating identity system based on Ed25519 public-key cryptography. The Agent ID directly embeds the public key, and whoever holds the private key owns that identity.
51
57
 
52
- - **零信任架构** — 无需中心化身份验证服务
53
- - **密钥轮换** — 支持安全的密钥更新机制
54
- - **持久化存储** — 密钥安全存储在本地文件系统
58
+ - **Zero-trust architecture** — No centralized authentication service required
59
+ - **Key rotation** — Supports secure key update mechanisms
60
+ - **Persistent storage** — Keys are securely stored in the local filesystem
55
61
 
56
- ### 2. 发现机制
62
+ ### 2. Discovery Mechanisms
57
63
 
58
- 提供多种发现方式，适应不同网络环境。
64
+ Multiple discovery methods to suit different network environments.
59
65
 
60
- - **mDNS 零配置发现** — 局域网内自动发现，无需手动配置
61
- - **Registry 目录服务** — 可选的中心化目录，支持广域网发现
62
- - **Relay 中继服务** — 穿越 NAT 和防火墙的通信中继
66
+ - **mDNS zero-config discovery** — Automatic discovery on LAN, no manual configuration needed
67
+ - **Registry directory service** — Optional centralized directory for WAN discovery
68
+ - **Relay service** — Communication relay that traverses NAT and firewalls
63
69
 
64
- ### 3. 消息传输层
70
+ ### 3. Message Transport Layer
65
71
 
66
- 基于 WebSocket 的实时消息传输，支持多种通信模式。
72
+ Real-time message transmission based on WebSocket, supporting multiple communication modes.
67
73
 
68
- - **WebSocket 直连** — 点对点直接通信
69
- - **Webhook 回调** — 适合长时异步任务的结果通知
70
- - **混合模式** — 同步响应用 WebSocket，异步回调用 Webhook
74
+ - **WebSocket direct connection** — Point-to-point direct communication
75
+ - **Webhook callbacks** — Ideal for delivering results of long-running async tasks
76
+ - **Hybrid mode** — WebSocket for sync responses, Webhook for async callbacks
71
77
 
72
- ### 4. 安全与信任
78
+ ### 4. Security & Trust
73
79
 
74
- 强制签名验证和灵活的信任管理机制。
80
+ Mandatory signature verification with flexible trust management mechanisms.
75
81
 
76
- - **Ed25519 签名** — 所有消息强制签名验证
77
- - **TOFU（Trust On First Use）** — 首次使用自动信任
78
- - **信任存储** — 可配置的信任策略和黑名单
82
+ - **Ed25519 signatures** — All messages are mandatorily signature-verified
83
+ - **TOFU (Trust On First Use)** — Automatic trust on first verified connection
84
+ - **Trust store** — Configurable trust policies and blacklists
79
85
 
80
- ### 5. MCP 集成
86
+ ### 5. MCP Integration
81
87
 
82
- 原生支持 Model Context Protocol，可直接作为 MCP 服务运行。
88
+ Native support for Model Context Protocol, can run directly as an MCP server.
83
89
 
84
- - **MCP Server** — 暴露 ADP 能力为 MCP 工具
85
- - **Claude Desktop 兼容** — 无缝集成到 Claude Desktop
86
- - **工具发现** — 自动发现和调用其他 ADP Agent
90
+ - **MCP Server** — Expose ADP capabilities as MCP tools
91
+ - **Claude Desktop compatible** — Seamless integration with Claude Desktop
92
+ - **Tool discovery** — Automatically discover and invoke other ADP agents
87
93
 
88
- ## 技术目标
94
+ ## Technical Goals
89
95
 
90
- - **去中心化优先** — 局域网内无需任何中心化服务即可工作
91
- - **安全第一** — 所有消息强制签名验证，防止中间人攻击
92
- - **互操作性** — 兼容 OpenClaw、Hermes Agent 等主流 Agent 框架
93
- - **可观测性** — 完整的日志和追踪机制
94
- - **可扩展性** — 模块化设计，支持自定义能力处理器
96
+ - **Decentralization first** — Works within a LAN without any centralized services
97
+ - **Security first** — All messages mandatorily signature-verified to prevent MITM attacks
98
+ - **Interoperability** — Compatible with OpenClaw, Hermes Agent, and other major agent frameworks
99
+ - **Observability** — Complete logging and tracing mechanisms
100
+ - **Extensibility** — Modular design supporting custom capability handlers
95
101
 
96
- ## 架构
102
+ ## Architecture
97
103
 
98
104
  ```
99
105
  ┌───────────────────────────────────────────────────────────────────┐
100
- │ 应用层（Agent 框架） │
101
- │ OpenClaw • Hermes Agent • MCP Host • 自定义应用 │
106
+ │ Application Layer (Agent Frameworks) │
107
+ │ OpenClaw • Hermes Agent • MCP Host • Custom Applications │
102
108
  └────────────────────────────┬────────────────────────────────────┘
103
109
  │
104
110
  ┌────────────────────────────▼────────────────────────────────────┐
105
111
  │ ADP Gateway │
106
112
  │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
107
- │ │ 能力处理器 │ │ 任务管理器 │ │ 联系人管理 │ │
113
+ │ │ Capability │ │ Task │ │ Contact │ │
114
+ │ │ Handlers │ │ Manager │ │ Manager │ │
108
115
  │ └──────────────┘ └──────────────┘ └──────────────┘ │
109
116
  └────────────────────────────┬────────────────────────────────────┘
110
117
  │
111
118
  ┌────────────────────────────▼────────────────────────────────────┐
112
- │ 消息层（Envelope） │
113
- │ 协议版本 • 消息 ID • 发送方 • 接收方 • 动作 • 参数 • 签名 │
119
+ │ Message Layer (Envelope) │
120
+ │ Protocol • ID • From • To • Action • Params • Signature │
114
121
  └────────────────────────────┬────────────────────────────────────┘
115
122
  │
116
123
  ┌────────────────────────────▼────────────────────────────────────┐
117
- │ 传输层 │
124
+ │ Transport Layer │
118
125
  │ ┌──────────────┐ ┌──────────────┐ │
119
126
  │ │ WebSocket │ │ Webhook │ │
120
- │ │ 直连/中继 │ │ 回调通知 │ │
127
+ │ │ Direct/Relay │ │ Callbacks │ │
121
128
  │ └──────────────┘ └──────────────┘ │
122
129
  └────────────────────────────┬────────────────────────────────────┘
123
130
  │
124
131
  ┌────────────────────────────▼────────────────────────────────────┐
125
- │ 发现层 │
132
+ │ Discovery Layer │
126
133
  │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
127
134
  │ │ mDNS │ │ Registry │ │ Relay │ │
128
- │ │ 局域网发现 │ │ 目录服务 │ │ NAT 中继 │ │
135
+ │ │ LAN Discovery│ │ Directory │ │ NAT Relay │ │
129
136
  │ └──────────────┘ └──────────────┘ └──────────────┘ │
130
137
  └───────────────────────────────────────────────────────────────────┘
131
138
  ```
132
139
 
133
- ## 快速开始
140
+ ## Quick Start
134
141
 
135
- ### 前置要求
142
+ ### Prerequisites
136
143
 
137
144
  - **Node.js** : 18+
138
145
  - **npm** : 9+
139
- - **TypeScript** : 5.4+（开发时）
146
+ - **TypeScript** : 5.4+ (for development)
140
147
 
141
- ### 本地开发
148
+ ### Local Development
142
149
 
143
- 1. **克隆仓库**
150
+ 1. **Clone the repository**
144
151
 
145
152
  ```bash
146
153
  git clone https://github.com/mengzhuowei/AgentDiscoveryProtocol.git
147
154
  cd AgentDiscoveryProtocol
148
155
  ```
149
156
 
150
- 2. **安装依赖**
157
+ 2. **Install dependencies**
151
158
 
152
159
  ```bash
153
160
  npm install
154
161
  ```
155
162
 
156
- 3. **启动 Agent**
163
+ 3. **Start Agent**
157
164
 
158
165
  ```bash
159
- # 终端 1：启动第一个 Agent
166
+ # Terminal 1: Start first agent
160
167
  npm start
161
168
 
162
- # 终端 2：启动第二个 Agent（自动发现第一个）
169
+ # Terminal 2: Start second agent (automatically discovers the first)
163
170
  npm start
164
171
  ```
165
172
 
166
- 4. **启动 Registry 和 Relay（可选）**
173
+ 4. **Start Registry and Relay (optional)**
167
174
 
168
175
  ```bash
169
- # 终端 3：启动 Registry 服务
176
+ # Terminal 3: Start Registry service
170
177
  npm run registry
171
178
 
172
- # 终端 4：启动 Relay 服务
179
+ # Terminal 4: Start Relay service
173
180
  npm run relay
174
181
  ```
175
182
 
176
- ### Docker 部署
183
+ ### Docker Deployment
177
184
 
178
185
  ```bash
179
- # 启动完整 ADP 生态系统（Gateway + Registry + Relay）
186
+ # Start the complete ADP ecosystem (Gateway + Registry + Relay)
180
187
  docker-compose up -d
181
188
  ```
182
189
 
183
- 详见 [Docker 部署指南](docs/docker.md)。
190
+ See [Docker Deployment Guide](docs/docker.md) for details.
184
191
 
185
- ## 安装
192
+ ## Installation
186
193
 
187
- ### 作为库使用
194
+ ### Use as a Library
188
195
 
189
196
  ```bash
190
197
  npm install adp-agent
191
198
  ```
192
199
 
193
- ### 全局安装（获得 CLI 工具）
200
+ ### Global Installation
194
201
 
195
202
  ```bash
196
203
  npm install -g adp-agent
197
204
  ```
198
205
 
199
- 安装后，`skill/` 目录会被自动复制到你的项目根目录，包含完整的集成文档。
206
+ After installation, the `skill/` directory is automatically copied to your project root, containing complete integration documentation.
200
207
 
201
- ### 可用命令
208
+ ### Available Commands
202
209
 
203
- 全局安装后，可以使用以下命令：
210
+ After global installation, you can use the following commands:
204
211
 
205
- | 命令 | 说明 |
206
- |------|------|
207
- | `adp-agent` | 启动 MCP Server |
208
- | `adp-registry` | 启动 Registry 服务 |
209
- | `adp-relay` | 启动 Relay 服务 |
212
+ | Command | Description |
213
+ |---------|-------------|
214
+ | `adp-agent` | Start MCP Server |
215
+ | `adp-registry` | Start Registry service |
216
+ | `adp-relay` | Start Relay service |
210
217
 
211
- #### adp-agent 命令参数
218
+ #### adp-agent Command Options
212
219
 
213
220
  ```bash
214
221
  adp-agent [tag] [options]
215
222
  ```
216
223
 
217
- | 参数 | 说明 | 默认值 |
218
- |------|------|---------|
219
- | `[tag]` | Agent 标识名称 | `agent1` |
220
- | `--relay=<url>` | 设置 Relay 服务器地址 | - |
221
- | `--registry=<url>` | 设置 Registry 服务器地址 | - |
222
- | `--name=<name>` | 设置 Agent 名称 | - |
223
- | `--direct` | 禁用 mDNS 发现，强制直连模式 | - |
224
+ | Argument | Description | Default |
225
+ |----------|-------------|---------|
226
+ | `[tag]` | Agent identifier name | `agent1` |
227
+ | `--relay=<url>` | Set Relay server address | - |
228
+ | `--registry=<url>` | Set Registry server address | - |
229
+ | `--name=<name>` | Set Agent name | - |
230
+ | `--direct` | Disable mDNS discovery, force direct connection mode | - |
224
231
 
225
- | 环境变量 | 说明 | 默认值 |
226
- |----------|------|---------|
227
- | `ADP_RELAY` | Relay 服务器地址 | - |
228
- | `ADP_REGISTRY` | Registry 服务器地址 | - |
229
- | `ADP_REGISTRY_TOKEN` | Registry 访问令牌 | - |
230
- | `ADP_NAMESPACE` | Agent 命名空间 | `local` |
231
- | `ADP_NAME` | Agent 名称 | - |
232
+ | Environment Variable | Description | Default |
233
+ |-----------------------|-------------|---------|
234
+ | `ADP_RELAY` | Relay server address | - |
235
+ | `ADP_REGISTRY` | Registry server address | - |
236
+ | `ADP_REGISTRY_TOKEN` | Registry access token | - |
237
+ | `ADP_NAMESPACE` | Agent namespace | `local` |
238
+ | `ADP_NAME` | Agent name | - |
232
239
 
233
- 配置文件：`.adp/config.json`（项目目录或用户目录）
240
+ Config file: `.adp/config.json` (project directory or user home directory)
234
241
 
235
- #### adp-registry 命令参数
242
+ #### adp-registry Command Options
236
243
 
237
244
  ```bash
238
245
  adp-registry
239
246
  ```
240
247
 
241
- 无需命令行参数，所有配置通过环境变量或配置文件。
242
-
243
- | 环境变量 | 说明 | 默认值 |
244
- |----------|------|---------|
245
- | `ADP_CONFIG` | 配置文件路径 | `config.json` |
246
- | `REGISTRY_PORT` | 服务端口 | `3000` |
247
- | `REGISTRY_HOST` | 服务地址 | `0.0.0.0` |
248
- | `MYSQL_HOST` | MySQL 数据库地址 | `127.0.0.1` |
249
- | `MYSQL_PORT` | MySQL 数据库端口 | `3306` |
250
- | `MYSQL_USER` | MySQL 用户名 | `root` |
251
- | `MYSQL_PASSWORD` | MySQL 密码 | - |
252
- | `MYSQL_DATABASE` | MySQL 数据库名 | `adp_registry` |
253
- | `REDIS_HOST` | Redis 地址 | `127.0.0.1` |
254
- | `REDIS_PORT` | Redis 端口 | `6379` |
255
- | `REDIS_PASSWORD` | Redis 密码 | - |
256
- | `TOKEN_ENABLED` | 是否启用令牌认证 | `false` |
257
- | `CORS_ENABLED` | 是否启用 CORS | `false` |
258
- | `CORS_ORIGINS` | CORS 允许的来源（逗号分隔） | `*` |
259
-
260
- #### adp-relay 命令参数
248
+ No command-line arguments required. All configuration is through environment variables or config file.
249
+
250
+ | Environment Variable | Description | Default |
251
+ |-----------------------|-------------|---------|
252
+ | `ADP_CONFIG` | Config file path | `config.json` |
253
+ | `REGISTRY_PORT` | Service port | `3000` |
254
+ | `REGISTRY_HOST` | Service address | `0.0.0.0` |
255
+ | `MYSQL_HOST` | MySQL database address | `127.0.0.1` |
256
+ | `MYSQL_PORT` | MySQL database port | `3306` |
257
+ | `MYSQL_USER` | MySQL username | `root` |
258
+ | `MYSQL_PASSWORD` | MySQL password | - |
259
+ | `MYSQL_DATABASE` | MySQL database name | `adp_registry` |
260
+ | `REDIS_HOST` | Redis address | `127.0.0.1` |
261
+ | `REDIS_PORT` | Redis port | `6379` |
262
+ | `REDIS_PASSWORD` | Redis password | - |
263
+ | `TOKEN_ENABLED` | Enable token authentication | `false` |
264
+ | `CORS_ENABLED` | Enable CORS | `false` |
265
+ | `CORS_ORIGINS` | CORS allowed origins (comma-separated) | `*` |
266
+
267
+ #### adp-relay Command Options
261
268
 
262
269
  ```bash
263
270
  adp-relay
264
271
  ```
265
272
 
266
- 无需命令行参数，所有配置通过环境变量。
273
+ No command-line arguments required. All configuration is through environment variables.
267
274
 
268
- | 环境变量 | 说明 | 默认值 |
269
- |----------|------|---------|
270
- | `ADP_RELAY_PORT` | 服务端口 | `9700` |
271
- | `ADP_RELAY_HOST` | 服务地址 | `0.0.0.0` |
272
- | `ADP_RELAY_MAX_CONNECTIONS` | 最大连接数 | `10000` |
273
- | `ADP_RELAY_HEARTBEAT_INTERVAL_MS` | 心跳间隔（毫秒） | `15000` |
274
- | `ADP_RELAY_HEARTBEAT_TIMEOUT_MS` | 心跳超时（毫秒） | `45000` |
275
- | `ADP_RELAY_OFFLINE_MAX_AGE_MS` | 离线消息最大保留时间（毫秒） | `86400000` |
276
- | `ADP_RELAY_OFFLINE_MAX_PER_AGENT` | 每个 Agent 最大离线消息数 | `500` |
275
+ | Environment Variable | Description | Default |
276
+ |-----------------------|-------------|---------|
277
+ | `ADP_RELAY_PORT` | Service port | `9700` |
278
+ | `ADP_RELAY_HOST` | Service address | `0.0.0.0` |
279
+ | `ADP_RELAY_MAX_CONNECTIONS` | Max connections | `10000` |
280
+ | `ADP_RELAY_HEARTBEAT_INTERVAL_MS` | Heartbeat interval (ms) | `15000` |
281
+ | `ADP_RELAY_HEARTBEAT_TIMEOUT_MS` | Heartbeat timeout (ms) | `45000` |
282
+ | `ADP_RELAY_OFFLINE_MAX_AGE_MS` | Max offline message retention (ms) | `86400000` |
283
+ | `ADP_RELAY_OFFLINE_MAX_PER_AGENT` | Max offline messages per agent | `500` |
277
284
 
278
285
  ```bash
279
- # 启动 MCP Server
286
+ # Start MCP Server
280
287
  adp-agent
281
288
 
282
- # 启动 Registry 服务
289
+ # Start Registry service
283
290
  adp-registry
284
291
 
285
- # 启动 Relay 服务
292
+ # Start Relay service
286
293
  adp-relay
287
294
  ```
288
295
 
289
- ## 使用示例
296
+ ## Usage Examples
290
297
 
291
- ### 基础 Gateway
298
+ ### Basic Gateway
292
299
 
293
300
  ```typescript
294
301
  import { Gateway, loadOrCreateIdentity } from 'adp-agent';
@@ -308,7 +315,7 @@ console.log(`Agent running at ws://localhost:9900/adp`);
308
315
  console.log(`Agent ID: ${identity.agentId}`);
309
316
  ```
310
317
 
311
- ### 自定义能力处理器
318
+ ### Custom Capability Handler
312
319
 
313
320
  ```typescript
314
321
  import { Gateway, loadOrCreateIdentity, signEnvelope, generateMessageId, canonicalize } from 'adp-agent';
@@ -339,9 +346,9 @@ const gateway = new Gateway({
339
346
  customHandlers: {
340
347
  'custom:video.generate': async (ws, envelope) => {
341
348
  const params = envelope.params as { prompt?: string; duration?: number };
342
-
349
+
343
350
  console.log(`Generating video: ${params.prompt}`);
344
-
351
+
345
352
  const reply = signEnvelope({
346
353
  protocol: 'adp/0.2',
347
354
  id: generateMessageId(),
@@ -354,14 +361,14 @@ const gateway = new Gateway({
354
361
  reply_to: envelope.id,
355
362
  timestamp: new Date().toISOString(),
356
363
  }, identity.secretKey, canonicalize);
357
-
364
+
358
365
  ws.send(JSON.stringify(reply));
359
366
  },
360
367
  },
361
368
  });
362
369
  ```
363
370
 
364
- ### Agent 发现
371
+ ### Agent Discovery
365
372
 
366
373
  ```typescript
367
374
  import { Discovery, loadOrCreateIdentity } from 'adp-agent';
@@ -382,7 +389,7 @@ const discovery = new Discovery(identity.agentId, 9900, {
382
389
  discovery.start();
383
390
  ```
384
391
 
385
- ### Registry 客户端
392
+ ### Registry Client
386
393
 
387
394
  ```typescript
388
395
  import { RegistryClient, loadOrCreateIdentity } from 'adp-agent';
@@ -395,23 +402,23 @@ const registry = new RegistryClient({
395
402
  secretKey: identity.secretKey,
396
403
  });
397
404
 
398
- // 注册自己
405
+ // Register yourself
399
406
  await registry.register({
400
407
  displayName: 'My Agent',
401
408
  capabilities: ['adp:ping', 'custom:my-action'],
402
409
  routes: [{ type: 'direct', address: 'localhost:9900' }],
403
410
  });
404
411
 
405
- // 查询其他 Agent
412
+ // Query other agents
406
413
  const agents = await registry.query({ capability: 'custom:video.generate' });
407
414
  console.log('Found agents:', agents);
408
415
 
409
- // 获取 Agent Manifest
416
+ // Get Agent Manifest
410
417
  const manifest = await registry.resolve(agents[0].agentId);
411
418
  console.log('Manifest:', manifest);
412
419
  ```
413
420
 
414
- ### Relay 客户端
421
+ ### Relay Client
415
422
 
416
423
  ```typescript
417
424
  import { RelayClient, loadOrCreateIdentity, generateMessageId } from 'adp-agent';
@@ -424,10 +431,10 @@ const relay = new RelayClient({
424
431
  secretKey: identity.secretKey,
425
432
  });
426
433
 
427
- // 连接到 Relay
434
+ // Connect to Relay
428
435
  await relay.connect();
429
436
 
430
- // 通过 Relay 发送消息
437
+ // Send message through Relay
431
438
  await relay.sendMessage(targetAgentId, {
432
439
  protocol: 'adp/0.2',
433
440
  id: generateMessageId(),
@@ -438,7 +445,7 @@ await relay.sendMessage(targetAgentId, {
438
445
  timestamp: new Date().toISOString(),
439
446
  });
440
447
 
441
- // 监听来自 Relay 的消息
448
+ // Listen for messages from Relay
442
449
  relay.on('message', (envelope) => {
443
450
  console.log('Received message:', envelope);
444
451
  });
@@ -446,7 +453,7 @@ relay.on('message', (envelope) => {
446
453
  relay.disconnect();
447
454
  ```
448
455
 
449
- ### MCP Server 模式
456
+ ### MCP Server Mode
450
457
 
451
458
  ```typescript
452
459
  import { AdpMcpServer } from 'adp-agent';
@@ -475,85 +482,85 @@ const server = new AdpMcpServer({
475
482
  await server.start();
476
483
  ```
477
484
 
478
- 或者使用全局安装的命令：
485
+ Or use the globally installed command:
479
486
 
480
487
  ```bash
481
488
  adp-agent
482
489
  ```
483
490
 
484
- 更多示例见 [examples/](examples/) 目录。
491
+ More examples are available in the [examples/](examples/) directory.
485
492
 
486
- ## 开发
493
+ ## Development
487
494
 
488
495
  ```bash
489
- npm test # 运行测试
490
- npm run test:integration # 集成测试
491
- npm run test:coverage # 测试覆盖率
492
- npm run build # 编译到 dist/
493
- npm run dev # 监听模式编译
496
+ npm test # Run tests
497
+ npm run test:integration # Integration tests
498
+ npm run test:coverage # Test coverage
499
+ npm run build # Build to dist/
500
+ npm run dev # Watch mode build
494
501
  ```
495
502
 
496
- ### 启动服务
503
+ ### Start Services
497
504
 
498
- #### 开发模式（从源码运行）
505
+ #### Development Mode (run from source)
499
506
 
500
507
  ```bash
501
- npm run relay # 启动 Relay 服务
502
- npm run registry # 启动 Registry 服务
503
- npm run adp # 启动 MCP Server
508
+ npm run relay # Start Relay service
509
+ npm run registry # Start Registry service
510
+ npm run adp # Start MCP Server
504
511
  ```
505
512
 
506
- #### 生产模式（全局安装后运行）
513
+ #### Production Mode (run after global installation)
507
514
 
508
515
  ```bash
509
- adp-relay # 启动 Relay 服务
510
- adp-registry # 启动 Registry 服务
511
- adp-agent # 启动 MCP Server
516
+ adp-relay # Start Relay service
517
+ adp-registry # Start Registry service
518
+ adp-agent # Start MCP Server
512
519
  ```
513
520
 
514
- ## 文档
521
+ ## Documentation
515
522
 
516
- | 文档 | 说明 |
517
- |------|------|
518
- | [使用指南](USAGE.md) | 完整的使用说明和配置选项 |
519
- | [Docker 部署](docs/docker.md) | Docker 部署指南 |
520
- | [身份与 Manifest](docs/01-identity.md) | Agent ID、能力声明、密钥管理 |
521
- | [消息格式](docs/02-message.md) | Envelope、签名、错误码 |
522
- | [发现机制](docs/03-discovery.md) | mDNS、Registry、Relay |
523
- | [传输层](docs/04-transport.md) | WebSocket、Webhook、混合模式 |
524
- | [安全与信任](docs/05-security.md) | TOFU、签名验证、信任存储 |
525
- | [实现检查清单](docs/implementation-checklist.md) | 协议合规性检查 |
526
- | [集成文档](skill/SKILL.md) | OpenClaw、Hermes Agent 集成指南 |
523
+ | Document | Description |
524
+ |----------|-------------|
525
+ | [Usage Guide](USAGE.md) | Complete usage and configuration options |
526
+ | [Docker Deployment](docs/docker.md) | Docker deployment guide |
527
+ | [Identity & Manifest](docs/01-identity.md) | Agent ID, capability declaration, key management |
528
+ | [Message Format](docs/02-message.md) | Envelope, signatures, error codes |
529
+ | [Discovery Mechanisms](docs/03-discovery.md) | mDNS, Registry, Relay |
530
+ | [Transport Layer](docs/04-transport.md) | WebSocket, Webhook, hybrid mode |
531
+ | [Security & Trust](docs/05-security.md) | TOFU, signature verification, trust store |
532
+ | [Implementation Checklist](docs/implementation-checklist.md) | Protocol compliance checklist |
533
+ | [Integration Guide](skill/SKILL.md) | OpenClaw, Hermes Agent integration guide |
527
534
 
528
- ## 路线图
535
+ ## Roadmap
529
536
 
530
- - [x] **v0.2** — 自认证身份、签名验证、TOFU
531
- - [x] **Registry** — 中心化目录服务
532
- - [x] **MCP 集成** — 作为 MCP 服务运行
533
- - [x] **Webhook 通信** — 异步任务回调支持
534
- - [x] **密钥轮换** — 安全的密钥更新机制
535
- - [ ] **任务委派** — 跨 Agent 任务调度
536
- - [ ] **端到端加密** — 可选 E2EE
537
- - [ ] **更多语言实现** — Python、Rust、Go
537
+ - [x] **v0.2** — Self-authenticating identity, signature verification, TOFU
538
+ - [x] **Registry** — Centralized directory service
539
+ - [x] **MCP Integration** — Run as MCP service
540
+ - [x] **Webhook Communication** — Async task callback support
541
+ - [x] **Key Rotation** — Secure key update mechanism
542
+ - [ ] **Task Delegation** — Cross-agent task scheduling
543
+ - [ ] **End-to-End Encryption** — Optional E2EE
544
+ - [ ] **Multi-language implementations** — Python, Rust, Go
538
545
 
539
- ## 贡献
546
+ ## Contributing
540
547
 
541
- 我们欢迎贡献！请遵循以下步骤：
548
+ We welcome contributions! Please follow these steps:
542
549
 
543
- 1. Fork 本仓库
544
- 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
545
- 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
546
- 4. 推送到分支 (`git push origin feature/AmazingFeature`)
547
- 5. 开启 Pull Request
550
+ 1. Fork this repository
551
+ 2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
552
+ 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
553
+ 4. Push to the branch (`git push origin feature/AmazingFeature`)
554
+ 5. Open a Pull Request
548
555
 
549
- 详见 [代码规范](docs/implementation-checklist.md)。
556
+ See [Code Standards](docs/implementation-checklist.md) for details.
550
557
 
551
- ## 许可证
558
+ ## License
552
559
 
553
560
  MIT © [ADP Working Group](https://github.com/mengzhuowei/AgentDiscoveryProtocol)
554
561
 
555
- ## 支持与联系
562
+ ## Support & Contact
556
563
 
557
564
  - **Issues** : [GitHub Issues](https://github.com/mengzhuowei/AgentDiscoveryProtocol/issues)
558
- - **讨论** : [GitHub Discussions](https://github.com/mengzhuowei/AgentDiscoveryProtocol/discussions)
559
- - **邮件** : mengzhuowei@qq.com
565
+ - **Discussions** : [GitHub Discussions](https://github.com/mengzhuowei/AgentDiscoveryProtocol/discussions)
566
+ - **Email** : mengzhuowei@qq.com
package/README.zh.md ADDED
@@ -0,0 +1,565 @@
1
+ <div align="center">
2
+
3
+ **中文** | [English](README.md)
4
+
5
+ </div>
6
+
7
+ <div align="center">
8
+ <h1>
9
+ <br>
10
+ <br>
11
+ 🤖 Agent Discovery Protocol (ADP)
12
+ <br>
13
+ <br>
14
+ </h1>
15
+ </div>
16
+
17
+ <div align="center">
18
+
19
+ [![npm version](https://img.shields.io/npm/v/adp-agent.svg?style=flat-square)](https://www.npmjs.com/package/adp-agent)
20
+ [![GitHub license](https://img.shields.io/github/license/mengzhuowei/AgentDiscoveryProtocol.svg?style=flat-square)](https://github.com/mengzhuowei/AgentDiscoveryProtocol/blob/main/LICENSE)
21
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.4%2B-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
22
+ [![protocol version](https://img.shields.io/badge/protocol-adp%2F0.2-orange.svg?style=flat-square)](docs/README.md)
23
+ [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
24
+
25
+ </div>
26
+
27
+ <div align="center">
28
+ <strong>让智能体（Agent）能够互相发现、通信，无需中心化平台</strong>
29
+ </div>
30
+
31
+ <br>
32
+
33
+ <div align="center">
34
+ <a href="#-平台定义">平台定义</a> •
35
+ <a href="#-核心组件">核心组件</a> •
36
+ <a href="#-技术目标">技术目标</a> •
37
+ <a href="#-快速开始">快速开始</a> •
38
+ <a href="#-安装">安装</a> •
39
+ <a href="#-使用示例">使用示例</a> •
40
+ <a href="#-架构">架构</a> •
41
+ <a href="#-文档">文档</a>
42
+ </div>
43
+
44
+ <br>
45
+
46
+ ---
47
+
48
+ ## 平台定义
49
+
50
+ ADP（Agent Discovery Protocol）是一个去中心化的智能体发现与通信协议，旨在让 AI Agent 能够在无需中心化平台的情况下互相发现、建立连接并安全通信。通过自认证密码学身份、mDNS 零配置发现和 Ed25519 强制签名验证，ADP 为 Agent 间协作提供了安全、可靠的基础设施。
51
+
52
+ ## 核心组件
53
+
54
+ ### 1. 自认证身份系统
55
+
56
+ 基于 Ed25519 公钥密码学的自认证身份系统，Agent ID 直接嵌入公钥，持有私钥即拥有该身份。
57
+
58
+ - **零信任架构** — 无需中心化身份验证服务
59
+ - **密钥轮换** — 支持安全的密钥更新机制
60
+ - **持久化存储** — 密钥安全存储在本地文件系统
61
+
62
+ ### 2. 发现机制
63
+
64
+ 提供多种发现方式，适应不同网络环境。
65
+
66
+ - **mDNS 零配置发现** — 局域网内自动发现，无需手动配置
67
+ - **Registry 目录服务** — 可选的中心化目录，支持广域网发现
68
+ - **Relay 中继服务** — 穿越 NAT 和防火墙的通信中继
69
+
70
+ ### 3. 消息传输层
71
+
72
+ 基于 WebSocket 的实时消息传输，支持多种通信模式。
73
+
74
+ - **WebSocket 直连** — 点对点直接通信
75
+ - **Webhook 回调** — 适合长时异步任务的结果通知
76
+ - **混合模式** — 同步响应用 WebSocket，异步回调用 Webhook
77
+
78
+ ### 4. 安全与信任
79
+
80
+ 强制签名验证和灵活的信任管理机制。
81
+
82
+ - **Ed25519 签名** — 所有消息强制签名验证
83
+ - **TOFU（Trust On First Use）** — 首次使用自动信任
84
+ - **信任存储** — 可配置的信任策略和黑名单
85
+
86
+ ### 5. MCP 集成
87
+
88
+ 原生支持 Model Context Protocol，可直接作为 MCP 服务运行。
89
+
90
+ - **MCP Server** — 暴露 ADP 能力为 MCP 工具
91
+ - **Claude Desktop 兼容** — 无缝集成到 Claude Desktop
92
+ - **工具发现** — 自动发现和调用其他 ADP Agent
93
+
94
+ ## 技术目标
95
+
96
+ - **去中心化优先** — 局域网内无需任何中心化服务即可工作
97
+ - **安全第一** — 所有消息强制签名验证，防止中间人攻击
98
+ - **互操作性** — 兼容 OpenClaw、Hermes Agent 等主流 Agent 框架
99
+ - **可观测性** — 完整的日志和追踪机制
100
+ - **可扩展性** — 模块化设计，支持自定义能力处理器
101
+
102
+ ## 架构
103
+
104
+ ```
105
+ ┌───────────────────────────────────────────────────────────────────┐
106
+ │ 应用层（Agent 框架） │
107
+ │ OpenClaw • Hermes Agent • MCP Host • 自定义应用 │
108
+ └────────────────────────────┬────────────────────────────────────┘
109
+ │
110
+ ┌────────────────────────────▼────────────────────────────────────┐
111
+ │ ADP Gateway │
112
+ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
113
+ │ │ 能力处理器 │ │ 任务管理器 │ │ 联系人管理 │ │
114
+ │ └──────────────┘ └──────────────┘ └──────────────┘ │
115
+ └────────────────────────────┬────────────────────────────────────┘
116
+ │
117
+ ┌────────────────────────────▼────────────────────────────────────┐
118
+ │ 消息层（Envelope） │
119
+ │ 协议版本 • 消息 ID • 发送方 • 接收方 • 动作 • 参数 • 签名 │
120
+ └────────────────────────────┬────────────────────────────────────┘
121
+ │
122
+ ┌────────────────────────────▼────────────────────────────────────┐
123
+ │ 传输层 │
124
+ │ ┌──────────────┐ ┌──────────────┐ │
125
+ │ │ WebSocket │ │ Webhook │ │
126
+ │ │ 直连/中继 │ │ 回调通知 │ │
127
+ │ └──────────────┘ └──────────────┘ │
128
+ └────────────────────────────┬────────────────────────────────────┘
129
+ │
130
+ ┌────────────────────────────▼────────────────────────────────────┐
131
+ │ 发现层 │
132
+ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
133
+ │ │ mDNS │ │ Registry │ │ Relay │ │
134
+ │ │ 局域网发现 │ │ 目录服务 │ │ NAT 中继 │ │
135
+ │ └──────────────┘ └──────────────┘ └──────────────┘ │
136
+ └───────────────────────────────────────────────────────────────────┘
137
+ ```
138
+
139
+ ## 快速开始
140
+
141
+ ### 前置要求
142
+
143
+ - **Node.js** : 18+
144
+ - **npm** : 9+
145
+ - **TypeScript** : 5.4+（开发时）
146
+
147
+ ### 本地开发
148
+
149
+ 1. **克隆仓库**
150
+
151
+ ```bash
152
+ git clone https://github.com/mengzhuowei/AgentDiscoveryProtocol.git
153
+ cd AgentDiscoveryProtocol
154
+ ```
155
+
156
+ 2. **安装依赖**
157
+
158
+ ```bash
159
+ npm install
160
+ ```
161
+
162
+ 3. **启动 Agent**
163
+
164
+ ```bash
165
+ # 终端 1：启动第一个 Agent
166
+ npm start
167
+
168
+ # 终端 2：启动第二个 Agent（自动发现第一个）
169
+ npm start
170
+ ```
171
+
172
+ 4. **启动 Registry 和 Relay（可选）**
173
+
174
+ ```bash
175
+ # 终端 3：启动 Registry 服务
176
+ npm run registry
177
+
178
+ # 终端 4：启动 Relay 服务
179
+ npm run relay
180
+ ```
181
+
182
+ ### Docker 部署
183
+
184
+ ```bash
185
+ # 启动完整 ADP 生态系统（Gateway + Registry + Relay）
186
+ docker-compose up -d
187
+ ```
188
+
189
+ 详见 [Docker 部署指南](docs/docker.md)。
190
+
191
+ ## 安装
192
+
193
+ ### 作为库使用
194
+
195
+ ```bash
196
+ npm install adp-agent
197
+ ```
198
+
199
+ ### 全局安装（获得 CLI 工具）
200
+
201
+ ```bash
202
+ npm install -g adp-agent
203
+ ```
204
+
205
+ 安装后，`skill/` 目录会被自动复制到你的项目根目录，包含完整的集成文档。
206
+
207
+ ### 可用命令
208
+
209
+ 全局安装后，可以使用以下命令：
210
+
211
+ | 命令 | 说明 |
212
+ |------|------|
213
+ | `adp-agent` | 启动 MCP Server |
214
+ | `adp-registry` | 启动 Registry 服务 |
215
+ | `adp-relay` | 启动 Relay 服务 |
216
+
217
+ #### adp-agent 命令参数
218
+
219
+ ```bash
220
+ adp-agent [tag] [options]
221
+ ```
222
+
223
+ | 参数 | 说明 | 默认值 |
224
+ |------|------|---------|
225
+ | `[tag]` | Agent 标识名称 | `agent1` |
226
+ | `--relay=<url>` | 设置 Relay 服务器地址 | - |
227
+ | `--registry=<url>` | 设置 Registry 服务器地址 | - |
228
+ | `--name=<name>` | 设置 Agent 名称 | - |
229
+ | `--direct` | 禁用 mDNS 发现，强制直连模式 | - |
230
+
231
+ | 环境变量 | 说明 | 默认值 |
232
+ |----------|------|---------|
233
+ | `ADP_RELAY` | Relay 服务器地址 | - |
234
+ | `ADP_REGISTRY` | Registry 服务器地址 | - |
235
+ | `ADP_REGISTRY_TOKEN` | Registry 访问令牌 | - |
236
+ | `ADP_NAMESPACE` | Agent 命名空间 | `local` |
237
+ | `ADP_NAME` | Agent 名称 | - |
238
+
239
+ 配置文件：`.adp/config.json`（项目目录或用户目录）
240
+
241
+ #### adp-registry 命令参数
242
+
243
+ ```bash
244
+ adp-registry
245
+ ```
246
+
247
+ 无需命令行参数，所有配置通过环境变量或配置文件。
248
+
249
+ | 环境变量 | 说明 | 默认值 |
250
+ |----------|------|---------|
251
+ | `ADP_CONFIG` | 配置文件路径 | `config.json` |
252
+ | `REGISTRY_PORT` | 服务端口 | `3000` |
253
+ | `REGISTRY_HOST` | 服务地址 | `0.0.0.0` |
254
+ | `MYSQL_HOST` | MySQL 数据库地址 | `127.0.0.1` |
255
+ | `MYSQL_PORT` | MySQL 数据库端口 | `3306` |
256
+ | `MYSQL_USER` | MySQL 用户名 | `root` |
257
+ | `MYSQL_PASSWORD` | MySQL 密码 | - |
258
+ | `MYSQL_DATABASE` | MySQL 数据库名 | `adp_registry` |
259
+ | `REDIS_HOST` | Redis 地址 | `127.0.0.1` |
260
+ | `REDIS_PORT` | Redis 端口 | `6379` |
261
+ | `REDIS_PASSWORD` | Redis 密码 | - |
262
+ | `TOKEN_ENABLED` | 是否启用令牌认证 | `false` |
263
+ | `CORS_ENABLED` | 是否启用 CORS | `false` |
264
+ | `CORS_ORIGINS` | CORS 允许的来源（逗号分隔） | `*` |
265
+
266
+ #### adp-relay 命令参数
267
+
268
+ ```bash
269
+ adp-relay
270
+ ```
271
+
272
+ 无需命令行参数，所有配置通过环境变量。
273
+
274
+ | 环境变量 | 说明 | 默认值 |
275
+ |----------|------|---------|
276
+ | `ADP_RELAY_PORT` | 服务端口 | `9700` |
277
+ | `ADP_RELAY_HOST` | 服务地址 | `0.0.0.0` |
278
+ | `ADP_RELAY_MAX_CONNECTIONS` | 最大连接数 | `10000` |
279
+ | `ADP_RELAY_HEARTBEAT_INTERVAL_MS` | 心跳间隔（毫秒） | `15000` |
280
+ | `ADP_RELAY_HEARTBEAT_TIMEOUT_MS` | 心跳超时（毫秒） | `45000` |
281
+ | `ADP_RELAY_OFFLINE_MAX_AGE_MS` | 离线消息最大保留时间（毫秒） | `86400000` |
282
+ | `ADP_RELAY_OFFLINE_MAX_PER_AGENT` | 每个 Agent 最大离线消息数 | `500` |
283
+
284
+ ```bash
285
+ # 启动 MCP Server
286
+ adp-agent
287
+
288
+ # 启动 Registry 服务
289
+ adp-registry
290
+
291
+ # 启动 Relay 服务
292
+ adp-relay
293
+ ```
294
+
295
+ ## 使用示例
296
+
297
+ ### 基础 Gateway
298
+
299
+ ```typescript
300
+ import { Gateway, loadOrCreateIdentity } from 'adp-agent';
301
+
302
+ const { identity } = loadOrCreateIdentity('myapp', 'my-agent', 'My Agent');
303
+
304
+ const gateway = new Gateway({
305
+ port: 9900,
306
+ host: '0.0.0.0',
307
+ secretKey: identity.secretKey,
308
+ agentId: identity.agentId,
309
+ displayName: 'My Agent',
310
+ capabilities: ['adp:ping', 'adp:capability.query'],
311
+ });
312
+
313
+ console.log(`Agent running at ws://localhost:9900/adp`);
314
+ console.log(`Agent ID: ${identity.agentId}`);
315
+ ```
316
+
317
+ ### 自定义能力处理器
318
+
319
+ ```typescript
320
+ import { Gateway, loadOrCreateIdentity, signEnvelope, generateMessageId, canonicalize } from 'adp-agent';
321
+
322
+ const { identity } = loadOrCreateIdentity('myapp', 'video-agent', 'VideoAgent');
323
+
324
+ const gateway = new Gateway({
325
+ port: 9900,
326
+ secretKey: identity.secretKey,
327
+ agentId: identity.agentId,
328
+ displayName: 'Video Generator',
329
+ capabilities: [
330
+ 'adp:ping',
331
+ 'adp:capability.query',
332
+ {
333
+ capability: 'custom:video.generate',
334
+ description: 'Generate video from prompt',
335
+ input_schema: {
336
+ type: 'object',
337
+ properties: {
338
+ prompt: { type: 'string' },
339
+ duration: { type: 'integer', default: 5 },
340
+ },
341
+ required: ['prompt'],
342
+ },
343
+ },
344
+ ],
345
+ customHandlers: {
346
+ 'custom:video.generate': async (ws, envelope) => {
347
+ const params = envelope.params as { prompt?: string; duration?: number };
348
+
349
+ console.log(`Generating video: ${params.prompt}`);
350
+
351
+ const reply = signEnvelope({
352
+ protocol: 'adp/0.2',
353
+ id: generateMessageId(),
354
+ from: identity.agentId,
355
+ to: envelope.from,
356
+ action: 'custom:video.generate',
357
+ params: {
358
+ video_url: 'https://cdn.example.com/video.mp4',
359
+ },
360
+ reply_to: envelope.id,
361
+ timestamp: new Date().toISOString(),
362
+ }, identity.secretKey, canonicalize);
363
+
364
+ ws.send(JSON.stringify(reply));
365
+ },
366
+ },
367
+ });
368
+ ```
369
+
370
+ ### Agent 发现
371
+
372
+ ```typescript
373
+ import { Discovery, loadOrCreateIdentity } from 'adp-agent';
374
+
375
+ const { identity } = loadOrCreateIdentity('myapp', 'discovery-demo', 'DiscoveryDemo');
376
+
377
+ const discovery = new Discovery(identity.agentId, 9900, {
378
+ onPeerDiscovered: (peer) => {
379
+ console.log(`Found agent: ${peer.agentId}`);
380
+ console.log(`Address: ${peer.host}:${peer.port}`);
381
+ console.log(`Capabilities:`, peer.manifest?.capabilities);
382
+ },
383
+ onPeerLost: (agentId) => {
384
+ console.log(`Agent lost: ${agentId}`);
385
+ },
386
+ });
387
+
388
+ discovery.start();
389
+ ```
390
+
391
+ ### Registry 客户端
392
+
393
+ ```typescript
394
+ import { RegistryClient, loadOrCreateIdentity } from 'adp-agent';
395
+
396
+ const { identity } = loadOrCreateIdentity('myapp', 'registry-client', 'RegistryClient');
397
+
398
+ const registry = new RegistryClient({
399
+ registryUrl: 'http://localhost:9800',
400
+ agentId: identity.agentId,
401
+ secretKey: identity.secretKey,
402
+ });
403
+
404
+ // 注册自己
405
+ await registry.register({
406
+ displayName: 'My Agent',
407
+ capabilities: ['adp:ping', 'custom:my-action'],
408
+ routes: [{ type: 'direct', address: 'localhost:9900' }],
409
+ });
410
+
411
+ // 查询其他 Agent
412
+ const agents = await registry.query({ capability: 'custom:video.generate' });
413
+ console.log('Found agents:', agents);
414
+
415
+ // 获取 Agent Manifest
416
+ const manifest = await registry.resolve(agents[0].agentId);
417
+ console.log('Manifest:', manifest);
418
+ ```
419
+
420
+ ### Relay 客户端
421
+
422
+ ```typescript
423
+ import { RelayClient, loadOrCreateIdentity, generateMessageId } from 'adp-agent';
424
+
425
+ const { identity } = loadOrCreateIdentity('myapp', 'relay-client', 'RelayClient');
426
+
427
+ const relay = new RelayClient({
428
+ relayUrl: 'ws://localhost:9700/adp/relay',
429
+ agentId: identity.agentId,
430
+ secretKey: identity.secretKey,
431
+ });
432
+
433
+ // 连接到 Relay
434
+ await relay.connect();
435
+
436
+ // 通过 Relay 发送消息
437
+ await relay.sendMessage(targetAgentId, {
438
+ protocol: 'adp/0.2',
439
+ id: generateMessageId(),
440
+ from: identity.agentId,
441
+ to: targetAgentId,
442
+ action: 'adp:ping',
443
+ params: {},
444
+ timestamp: new Date().toISOString(),
445
+ });
446
+
447
+ // 监听来自 Relay 的消息
448
+ relay.on('message', (envelope) => {
449
+ console.log('Received message:', envelope);
450
+ });
451
+
452
+ relay.disconnect();
453
+ ```
454
+
455
+ ### MCP Server 模式
456
+
457
+ ```typescript
458
+ import { AdpMcpServer } from 'adp-agent';
459
+
460
+ const server = new AdpMcpServer({
461
+ tag: 'my-agent',
462
+ namespace: 'myapp',
463
+ agentName: 'adp-mcp',
464
+ displayName: 'ADP MCP Agent',
465
+ portBase: 9900,
466
+ capabilities: [
467
+ 'adp:ping',
468
+ 'adp:capability.query',
469
+ {
470
+ capability: 'custom:my-action',
471
+ description: 'My custom action',
472
+ input_schema: {
473
+ type: 'object',
474
+ properties: { query: { type: 'string' } },
475
+ required: ['query'],
476
+ },
477
+ },
478
+ ],
479
+ });
480
+
481
+ await server.start();
482
+ ```
483
+
484
+ 或者使用全局安装的命令：
485
+
486
+ ```bash
487
+ adp-agent
488
+ ```
489
+
490
+ 更多示例见 [examples/](examples/) 目录。
491
+
492
+ ## 开发
493
+
494
+ ```bash
495
+ npm test # 运行测试
496
+ npm run test:integration # 集成测试
497
+ npm run test:coverage # 测试覆盖率
498
+ npm run build # 编译到 dist/
499
+ npm run dev # 监听模式编译
500
+ ```
501
+
502
+ ### 启动服务
503
+
504
+ #### 开发模式（从源码运行）
505
+
506
+ ```bash
507
+ npm run relay # 启动 Relay 服务
508
+ npm run registry # 启动 Registry 服务
509
+ npm run adp # 启动 MCP Server
510
+ ```
511
+
512
+ #### 生产模式（全局安装后运行）
513
+
514
+ ```bash
515
+ adp-relay # 启动 Relay 服务
516
+ adp-registry # 启动 Registry 服务
517
+ adp-agent # 启动 MCP Server
518
+ ```
519
+
520
+ ## 文档
521
+
522
+ | 文档 | 说明 |
523
+ |------|------|
524
+ | [使用指南](USAGE.md) | 完整的使用说明和配置选项 |
525
+ | [Docker 部署](docs/docker.md) | Docker 部署指南 |
526
+ | [身份与 Manifest](docs/01-identity.md) | Agent ID、能力声明、密钥管理 |
527
+ | [消息格式](docs/02-message.md) | Envelope、签名、错误码 |
528
+ | [发现机制](docs/03-discovery.md) | mDNS、Registry、Relay |
529
+ | [传输层](docs/04-transport.md) | WebSocket、Webhook、混合模式 |
530
+ | [安全与信任](docs/05-security.md) | TOFU、签名验证、信任存储 |
531
+ | [实现检查清单](docs/implementation-checklist.md) | 协议合规性检查 |
532
+ | [集成文档](skill/SKILL.md) | OpenClaw、Hermes Agent 集成指南 |
533
+
534
+ ## 路线图
535
+
536
+ - [x] **v0.2** — 自认证身份、签名验证、TOFU
537
+ - [x] **Registry** — 中心化目录服务
538
+ - [x] **MCP 集成** — 作为 MCP 服务运行
539
+ - [x] **Webhook 通信** — 异步任务回调支持
540
+ - [x] **密钥轮换** — 安全的密钥更新机制
541
+ - [ ] **任务委派** — 跨 Agent 任务调度
542
+ - [ ] **端到端加密** — 可选 E2EE
543
+ - [ ] **更多语言实现** — Python、Rust、Go
544
+
545
+ ## 贡献
546
+
547
+ 我们欢迎贡献！请遵循以下步骤：
548
+
549
+ 1. Fork 本仓库
550
+ 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
551
+ 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
552
+ 4. 推送到分支 (`git push origin feature/AmazingFeature`)
553
+ 5. 开启 Pull Request
554
+
555
+ 详见 [代码规范](docs/implementation-checklist.md)。
556
+
557
+ ## 许可证
558
+
559
+ MIT © [ADP Working Group](https://github.com/mengzhuowei/AgentDiscoveryProtocol)
560
+
561
+ ## 支持与联系
562
+
563
+ - **Issues** : [GitHub Issues](https://github.com/mengzhuowei/AgentDiscoveryProtocol/issues)
564
+ - **讨论** : [GitHub Discussions](https://github.com/mengzhuowei/AgentDiscoveryProtocol/discussions)
565
+ - **邮件** : mengzhuowei@qq.com
package/dist/start-relay.d.ts CHANGED
@@ -1 +1,2 @@
1
+ #!/usr/bin/env node
1
2
  export {};
package/dist/start-relay.js CHANGED
@@ -1,3 +1,4 @@
1
+ #!/usr/bin/env node
1
2
  "use strict";
2
3
  Object.defineProperty(exports, "__esModule", { value: true });
3
4
  const relay_1 = require("./src/relay");
package/dist/start-relay.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"start-relay.js","sourceRoot":"","sources":["../start-relay.ts"],"names":[],"mappings":";;AAAA,uCAAoC;AAEpC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AAC1F,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,SAAS,CAAC;AAC/E,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AAC3H,MAAM,mBAAmB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AAC5I,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AACzI,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,UAAU,EAAE,EAAE,CAAC,CAAC;AACrI,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,KAAK,EAAE,EAAE,CAAC,CAAC;AAEzI,MAAM,KAAK,GAAG,IAAI,aAAK,CAAC;IACtB,IAAI;IACJ,IAAI;IACJ,cAAc;IACd,mBAAmB;IACnB,kBAAkB;IAClB,eAAe;IACf,kBAAkB;CACnB,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC;;;;UAIF,IAAI,IAAI,IAAI;;gBAEN,mBAAmB,GAAG,IAAI,gBAAgB,kBAAkB,GAAG,IAAI;oBAC/D,eAAe,GAAG,QAAQ,OAAO,kBAAkB;;CAEtE,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IAC3C,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
1
+ {"version":3,"file":"start-relay.js","sourceRoot":"","sources":["../start-relay.ts"],"names":[],"mappings":";;;AAEA,uCAAoC;AAEpC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AAC1F,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,SAAS,CAAC;AAC/E,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AAC3H,MAAM,mBAAmB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AAC5I,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AACzI,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,UAAU,EAAE,EAAE,CAAC,CAAC;AACrI,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,KAAK,EAAE,EAAE,CAAC,CAAC;AAEzI,MAAM,KAAK,GAAG,IAAI,aAAK,CAAC;IACtB,IAAI;IACJ,IAAI;IACJ,cAAc;IACd,mBAAmB;IACnB,kBAAkB;IAClB,eAAe;IACf,kBAAkB;CACnB,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC;;;;UAIF,IAAI,IAAI,IAAI;;gBAEN,mBAAmB,GAAG,IAAI,gBAAgB,kBAAkB,GAAG,IAAI;oBAC/D,eAAe,GAAG,QAAQ,OAAO,kBAAkB;;CAEtE,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IAC3C,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "adp-agent",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "Agent Discovery Protocol (ADP) - discover, query, and ping agents via MCP / OpenClaw",
5
5
  "main": "dist/src/index.js",
6
6
  "types": "dist/src/index.d.ts",