Skill: yuyonghao-123/a2a-server (version 0.1.0)

# a2a-server **Agent-to-Agent (A2A) Communication Server** - 基于 WebSocket 的多智能体 P2P 通信系统 ## 描述 实现 AI Agent 之间的实时通信和协作： - **P2P 消息转发** - Agent 间直接通信，低延迟（~10ms） - **RPC 调用** - 请求/响应模式，支持超时控制 - **发布/订阅** - 频道广播，支持多订阅者 - **能力发现** - 按能力搜索 Agent，动态路由 - **离线消息** - 支持离线 Agent，消息队列存储 - **心跳机制** - 自动检测离线，自动清理 ## 功能 - ✅ **Agent 注册与发现** - 动态注册、能力公告、元数据管理 - ✅ **P2P 消息转发** - WebSocket 双向通信、低延迟 - ✅ **RPC 调用** - correlationId 追踪、超时控制、错误处理 - ✅ **发布/订阅** - 频道管理、多订阅者支持 - ✅ **能力发现** - 按能力/元数据筛选、实时查询 - ✅ **离线消息队列** - 内存存储、大小限制（100 条）、自动投递 - ✅ **心跳机制** - 定期心跳、超时检测（90 秒）、自动清理 - ✅ **自动重连** - 指数退避、最大尝试次数、连接恢复 - ⏳ **信任链授权** - 待实现 - ⏳ **消息签名** - 待实现 ## 安装 ```bash # 从 ClawHub 安装（待发布） clawhub install a2a-server # 或手动克隆 git clone https://github.com/YOUR_GITHUB/skills/a2a-server cd skills/a2a-server npm install ``` ## 快速开始 ### 1. 启动服务器 ```bash npm start # 或 node src/server.js # 环境变量 # A2A_PORT=8080 # A2A_HOST=localhost # A2A_VERBOSE=true ``` ### 2. 客户端连接 ```javascript const { A2AClient } = require('./src/client'); const client = new A2AClient('ws://localhost:8080', { agentId: 'my-agent', capabilities: ['search', 'analyze'], metadata: { version: '1.0.0' }, verbose: true, }); await client.connect(); console.log('✅ 已连接并注册'); ``` ### 3. RPC 调用 ```javascript // 调用远程 Agent const result = await client.call('remote-agent', { action: 'search', query: 'AI trends' }); console.log(result); ``` ### 4. 发布/订阅 ```javascript // 订阅频道 await client.subscribe('notifications'); client.on('message', (payload, from) => { console.log(`收到 ${from}:`, payload); }); // 发布消息 await client.publish('notifications', { type: 'task-complete', taskId: '123' }); ``` ### 5. 能力发现 ```javascript // 发现所有 Agent const agents = await client.discover(); // 按能力发现 const searchAgents = await client.discover({ capability: 'search' }); console.log(`找到 ${searchAgents.length} 个搜索 Agent`); ``` ## 配置选项 ### Server 配置 | 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `port` | number | `8080` | WebSocket 端口 | | `host` | string | `'localhost'` | 监听地址 | | `verbose` | boolean | `false` | 详细日志 | | `heartbeatInterval` | number | `30000` | 心跳间隔（毫秒） | ### Client 配置 | 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `agentId` | string | `自动生成` | Agent 唯一标识 | | `capabilities` | array | `[]` | 能力列表 | | `metadata` | object | `{}` | 元数据 | | `callTimeout` | number | `30000` | 调用超时（毫秒） | | `maxReconnectAttempts` | number | `10` | 最大重连次数 | | `reconnectDelay` | number | `1000` | 重连延迟（毫秒） | | `verbose` | boolean | `false` | 详细日志 | ## API 参考 ### A2AServer #### `constructor(options)` 创建服务器实例。 #### `start()` 启动服务器，返回 Promise。 #### `stop()` 停止服务器，关闭所有连接。 #### `getStats()` 获取统计信息： ```javascript { totalConnections: 100, totalMessages: 500, activeAgents: 10, uptime: 3600, memoryUsage: {...} } ``` #### `getAgents()` 获取已注册 Agent 列表： ```javascript [ { agentId: 'agent-1', capabilities: ['search'], metadata: {...}, registeredAt: Date, lastHeartbeat: Date } ] ``` #### `broadcast(payload, exclude)` 广播消息给所有 Agent。 ### A2AClient #### `constructor(serverUrl, options)` 创建客户端实例。 #### `connect()` 连接服务器，自动注册。 #### `disconnect()` 断开连接。 #### `call(targetAgentId, payload, options)` RPC 调用： - `targetAgentId` - 目标 Agent - `payload` - 调用参数 - `options.timeout` - 超时（默认 30s） - 返回：Promise<result> #### `publish(channel, payload)` 发布消息到频道。 #### `subscribe(channel)` 订阅频道。 #### `unsubscribe(channel)` 取消订阅。 #### `discover(options)` 能力发现： - `options.capability` - 按能力筛选 - `options.filter` - 按元数据筛选 - 返回：Promise<Agent[]> #### `heartbeat()` 发送心跳。 #### `getStatus()` 获取连接状态： ```javascript { connected: true, registered: true, agentId: 'my-agent', reconnectAttempts: 0 } ``` #### `on(event, listener)` 事件监听： - `connected` - 连接成功 - `disconnected` - 断开连接 - `registered` - 注册成功 - `reconnecting` - 重连中 - `reconnected` - 重连成功 - `message` - 收到频道消息 ## 使用场景 ### 场景 1: 多智能体协作 ```javascript // Planner Agent const planner = new A2AClient('ws://localhost:8080', { agentId: 'planner', capabilities: ['planning', 'analysis'] }); await planner.connect(); // Executor Agent const executor = new A2AClient('ws://localhost:8080', { agentId: 'executor', capabilities: ['execution', 'tool-use'] }); await executor.connect(); // Planner 调用 Executor const result = await planner.call('executor', { action: 'execute', task: 'analyze code' }); ``` ### 场景 2: 分布式搜索 ```javascript // Search Agent 注册 const searchAgent = new A2AClient('ws://localhost:8080', { agentId: 'search-001', capabilities: ['web-search', 'tavily'] }); await searchAgent.connect(); // 发现搜索 Agent const agents = await client.discover({ capability: 'web-search' }); // 调用搜索 const result = await client.call(agents[0].agentId, { query: 'AI trends 2026' }); ``` ### 场景 3: 通知系统 ```javascript // 订阅通知 await client.subscribe('system-alerts'); client.on('message', (payload, from) => { if (payload.type === 'alert') { console.log(`⚠️ 告警：${payload.message}`); } }); // 发布告警 await client.publish('system-alerts', { type: 'alert', level: 'warning', message: 'High CPU usage detected' }); ``` ## 与现有系统集成 ### 集成 Multi-Agent ```javascript const { MultiAgentOrchestrator } = require('../multi-agent'); const { A2AClient } = require('../a2a-server'); const a2a = new A2AClient('ws://localhost:8080', { agentId: 'planner-agent', capabilities: ['planning'] }); await a2a.connect(); const orchestrator = new MultiAgentOrchestrator(); // 注册远程工具 orchestrator.registerTool('remote-execute', async (params) => { const agents = await a2a.discover({ capability: 'execution' }); return await a2a.call(agents[0].agentId, params); }, { description: '远程执行', keywords: ['执行', '远程'] } ); ``` ### 集成 ReAct Orchestrator ```javascript const { ReActOrchestrator } = require('../react-orchestrator'); const { A2AClient } = require('../a2a-server'); const orchestrator = new ReActOrchestrator(); const a2a = new A2AClient('ws://localhost:8080', { agentId: 'react-agent', capabilities: ['reasoning'] }); await a2a.connect(); // 注册远程工具 orchestrator.registerTool('remote-search', async (params) => { const agents = await a2a.discover({ capability: 'search' }); return await a2a.call(agents[0].agentId, params); }, { description: '远程搜索', keywords: ['搜索', '远程'] } ); ``` ## 测试 ```bash # 运行所有测试 npm test # 运行测试并监视 npm run test:watch # 调试模式运行 npm run test:debug ``` ### 测试框架 - **测试运行器**: Jest v29.7.0 - **覆盖率目标**: >80% - **测试超时**: 30秒（可配置） ### 测试覆盖 - ✅ 服务器基础功能（启动/停止/统计） - ✅ Agent 注册/注销/心跳 - ✅ RPC 调用/响应（在线/离线/超时） - ✅ 发布/订阅（单订阅者/多订阅者） - ✅ 能力发现（全部/按能力/按元数据） - ✅ 离线消息队列 - ✅ 错误处理 - ✅ 并发连接 ### 测试文件 - `test/a2a.test.js` - 完整 Jest 测试套件 - `TEST-STATUS.md` - 详细测试状态 ## 消息协议 ### 注册消息 ```json { "type": "register", "agentId": "planner-001", "capabilities": ["planning", "analysis"], "metadata": { "version": "1.0.0" } } ``` ### RPC 调用 ```json { "type": "call", "from": "planner-001", "to": "executor-001", "correlationId": "uuid-123", "payload": { "action": "execute", "task": "..." } } ``` ### RPC 响应 ```json { "type": "response", "to": "planner-001", "correlationId": "uuid-123", "payload": { "result": "success" } } ``` ### 发布消息 ```json { "type": "publish", "channel": "notifications", "from": "system", "payload": { "type": "alert", "message": "..." } } ``` ## 性能基准 ### 延迟（本地） | 操作 | 延迟 | |------|------| | 连接建立 | ~5ms | | Agent 注册 | ~10ms | | RPC 调用 | ~15ms | | 发布/订阅 | ~10ms | | 能力发现 | ~20ms | ### 并发 | Agent 数量 | 消息/秒 | CPU | 内存 | |-----------|---------|-----|------| | 10 | 1000 | 5% | 50MB | | 50 | 5000 | 15% | 100MB | | 100 | 10000 | 30% | 200MB | ## 已知限制 - ⚠️ **离线消息** - 内存存储，重启丢失（未来用 Redis） - ⚠️ **认证授权** - 尚未实现（信任链待开发） - ⚠️ **消息签名** - 尚未实现（防止伪造） - ⚠️ **集群支持** - 单服务器（未来支持多节点） ## 依赖 - Node.js >= 18.0.0 - ws ^8.16.0 - uuid ^9.0.0 ## 版本历史 ### v0.1.0 (2026-03-18) - ✅ 初始版本 - ✅ WebSocket 服务器 - ✅ A2A Client - ✅ RPC 调用 - ✅ 发布/订阅 - ✅ 能力发现 - ✅ 心跳机制 ## 许可证 MIT ## 作者 小蒲萄 (Clawd) 🦞 ## 贡献 欢迎提交 Issue 和 PR！ ## 参考资料 - `README.md` - 使用指南 - `IMPLEMENTATION-NOTES.md` - 实施笔记 - `A2A-RESEARCH.md` - 调研报告


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)