1. 项目概述为AI Agent打造一个可靠的“对话规则”在AI Agent智能体协作的领域里我们常常面临一个基础但棘手的问题当多个具备不同能力的AI Agent需要通过文本通道比如Discord频道、Slack工作区或者Telegram群组进行协作时它们之间该如何高效、无歧义地沟通想象一下你手下的“运维专家”Agent需要向“系统监控”Agent查询服务器状态或者“内容创作”Agent需要向“代码审查”Agent请求帮助。如果只是让它们像人类一样发送自由文本很快就会陷入混乱——指令不明确、上下文丢失、任务状态难以追踪甚至可能出现无限循环的对话。这正是bot-protocol项目要解决的核心问题。它不是一个具体的AI模型而是一套结构化消息协议你可以把它理解为AI Agent之间的“TCP/IP协议”或“商务信函格式”。它为Bot-to-Bot机器人对机器人的通信定义了一套清晰的规则、字段和状态机确保消息可解析、任务可追踪、流程可控制。无论底层使用的是哪个聊天平台只要消息文本遵循这套协议参与协作的Agent就能准确理解彼此的意图和任务进展。对于任何正在构建或管理多AI Agent自动化工作流的开发者、运维工程师或技术负责人来说理解和实施这样一套协议是从“玩具Demo”走向“生产级可靠系统”的关键一步。2. 协议核心设计理念与架构拆解一套好的通信协议其价值远不止于定义几个字段。bot-protocol的设计背后蕴含着对分布式自动化系统常见痛点的深刻理解。我们来拆解其核心设计理念。2.1 通道无关性与结构化消息为什么是“通道无关”现代协作场景中工具链是异构的。团队可能用Slack进行日常沟通用Discord管理社区用Telegram作为备用通知渠道。一个健壮的Bot协议绝不能绑定在某个特定平台上。bot-protocol选择在应用层实现标准化所有消息最终都编码为一段带有特定标记和字段的纯文本。这意味着发送方无论通过哪个平台的API发送消息只需确保最终发出的文本符合协议格式。接收方无论从哪个平台接收到消息第一件事就是尝试用协议的解析器(parser.js)去解析这段文本。解析成功则进入协议处理流程解析失败则视为普通消息或无效消息。 这种设计将通信逻辑与传输层彻底解耦赋予了系统极大的灵活性和可移植性。结构化消息的价值自由文本是模糊的而结构化数据是精确的。协议定义了如[REQUEST → TargetBot]这样的固定头部以及From:、Task:、RequestId:等键值对字段。这带来了几个直接好处无歧义解析通过正则表达式或简单的分割规则可以100%准确地提取出目标机器人(to)、发送方(from)、任务内容(task)等核心信息无需依赖容易出错的自然语言理解(NLU)。机器可读下游的业务逻辑处理函数接收到的已经是一个结构化的JavaScript对象可以直接访问parsed.task来获取任务描述而不是去费力地从一段话中猜测意图。易于扩展协议设计为“向前兼容”未知的字段会被保留在metadata中。未来如果需要增加Deadline:或Budget:等新字段旧版本的解析器不会报错新版本的Builder可以生成包含新字段的消息实现了平滑升级。2.2 会话状态追踪与深度限制这是防止系统失控的两个核心安全机制。状态追踪(state.js)多轮对话是协作的常态。一个REQUEST可能引发一个CLARIFY澄清问题然后再继续。如果没有状态追踪每个消息都是孤立的Bot无法知道“我现在正在处理哪个任务”。state.js模块的核心职责就是维护一个会话状态表通常持久化到JSON文件。每当一个有效的协议消息被解析它就会被“追踪”。状态至少包括requestId: 会话的唯一标识符。status: 当前状态open,clarifying,done,failed,timeout。timestamp: 最后活动时间。depth: 当前对话深度。history: 该会话下所有消息的历史记录。有了这个状态机Bot就能回答“用户问的那个关于服务器状态的任务requestId:audit-xyz我已经向监控Bot发出了请求目前正在等待它的回应status:open。” 这为实现任务查询、进度汇报和故障恢复提供了基础。深度限制对抗循环依赖的防火墙无限循环是分布式系统的噩梦。Bot A 问 Bot BBot B 又 HANDOFF 给 Bot CBot C 发现需要 Bot A 的信息于是又发回一个REQUEST…… 如果没有干预它们会永远聊下去。bot-protocol引入了严格的深度限制默认最大为5。depth字段格式为当前深度/最大深度。规则非常简单却有效消息每被转发或接力一次当前深度加1。当当前深度 最大深度即达到5/5时协议强制该消息必须是一个RESPONSE响应而不能是新的REQUEST、CLARIFY或HANDOFF。这相当于在协议层面宣告“此对话链已到达思考极限必须在此给出最终答案或失败结论不得再往下传递。”这个设计迫使开发者在设计Bot能力时必须考虑任务的闭环性从根源上避免了因逻辑缺陷或依赖闭环导致的系统死锁。2.3 超时处理与错误恢复即使有深度限制一个会话也可能因为网络问题、下游服务宕机或Bot自身bug而“卡住”。bot-protocol为不同类型的消息设定了不同的超时时间例如REQUEST为30分钟CLARIFY为10分钟。state.checkTimeouts()函数就像一个后台的看门狗定期扫描状态表将长时间没有更新的会话标记为timeout。超时机制带来了两个层面的好处资源清理避免状态表被陈旧的会话无限占用。失败反馈触发超时后系统可以自动发送一个失败响应或者通知管理员从而让上游请求方知道任务未能完成而不是无限期等待。3. 五大消息类型详解与应用场景协议定义了五种核心消息类型覆盖了Bot协作的基本交互模式。理解每一种类型的用途和规则是正确使用协议的关键。3.1 REQUEST发起协作的起点REQUEST 是最常用、最基础的消息类型用于一个Bot向另一个Bot发起一个具体的任务请求。核心字段to:必填。目标Bot的名称或标识符。解析器会严格检查此字段确保消息不会被无关的Bot处理。from:必填。发送方标识。requestId:必填。全局唯一的会话ID。通常建议采用{发送方}-{简短描述}-{随机数或时间戳}的格式如lotbot-system-audit-abc123。这是状态追踪的基石。task:必填。清晰、明确的任务描述。好的task描述应包含“动作”和“目标”例如“检查/home目录的磁盘使用率如果超过80%则返回警告信息”。depth:必填。格式为{ current: 1, max: 5 }。发起新请求时current通常为1。priority(可选): 如normal,high,low。接收方Bot可根据此调整处理队列。context(可选): 提供任务背景信息帮助接收方更好地理解意图。应用场景示例LotBot一个调度Bot需要每周检查一次服务器补丁情况。它会向Mantis一个运维Bot发送如下REQUEST[REQUEST → Mantis] From: LotBot RequestId: lotbot-weekly-patch-check-20231027 Task: 检查所有生产服务器上Ubuntu系统的可用安全更新数量并按服务器名称列出清单。 Context: 每周安全审计例行任务。 Depth: 1/5 Priority: normal3.2 RESPONSE任务的闭环RESPONSE 是对 REQUEST、CLARIFY 或 HANDOFF 的正式回复标志着某个处理环节的结束。核心字段to: 原消息的from字段。from: 当前发送响应的Bot。requestId:必须与原始消息的requestId一致。这是将响应与正确会话关联起来的唯一依据。status:必填。表示任务结果success、partial_success、failed。body:必填。响应的主要内容可以是数据、报告、错误信息等。结构应尽量机器可读如JSON字符串便于后续自动化处理。depth: 继承自原始消息的深度不应增加。应用场景示例Mantis完成检查后向LotBot回复[RESPONSE → LotBot] From: Mantis RequestId: lotbot-weekly-patch-check-20231027 Status: success Body: {server1: 5, server2: 0, server3: 12} Depth: 1/5注意RESPONSE是唯一在深度达到最大值5/5时允许且必须发送的消息类型。这是强制结束对话链的机制。3.3 CLARIFY消除模糊精准协作当接收方Bot无法理解或执行REQUEST时它不是直接失败而是应该发送CLARIFY消息请求发送方提供更多信息或澄清模糊点。核心字段除了to,from,requestId,depth深度1等标准字段外关键字段是question:必填。一个具体、明确的问题。避免“我不明白”这种表述而应是“请指定要检查的具体端口号”或“请确认‘尽快’是指1小时内还是今天下班前”。应用场景示例LotBot发送任务“监控数据库性能”。Mantis可能回复[CLARIFY → LotBot] From: Mantis RequestId: lotbot-db-perf-xyz789 Question: 请明确需要监控的数据库性能指标是CPU使用率、内存占用、查询延迟(QPS)还是磁盘IO请至少指定一项。 Depth: 2/5CLARIFY消息有独立的较短超时如10分钟因为它期待一个快速的澄清响应来推动任务继续。3.4 HANDOFF职责的接力与流转HANDOFF 用于将当前任务完全转移给另一个更合适的Bot处理。发送HANDOFF后原发送方通常不再跟踪此任务后续由新的接收方负责到底。核心字段to: 新的目标Bot。from: 当前正在处理、但决定转交的Bot。originalFrom:重要。记录最初始的任务发起方。这样最终RESPONSE可以正确地回复给最初的请求者。requestId: 保持不变。task: 可以重新表述或细化任务描述以适配新Bot的能力。depth:当前深度1。这是深度计数增加的主要场景之一。应用场景与规则假设一个“通用助手Bot”收到任务“优化网站首页的图片”它发现自己没有图像处理能力但知道一个专门的“图像优化Bot”。它可以发送[HANDOFF → ImageOptimizerBot] From: GeneralHelperBot OriginalFrom: User123 RequestId: user123-image-opt-aaa111 Task: 将位于 https://example.com/homepage-banner.jpg 的图片进行无损压缩目标文件大小小于200KB。 Depth: 2/5重要规则进行HANDOFF的Bot必须确保originalFrom字段被正确传递这是保证任务链路可追溯、最终结果能送达正确对象的关键。同时HANDOFF意味着责任转移转交后不应再对同一requestId发送其他指令。3.5 BROADCAST一对多的通告BROADCAST 用于向所有监听该协议的Bot发送通知或公告通常不期待直接的、针对性的响应。核心字段to: 通常为*all*或broadcast。announcement:必填。通告内容。expires(可选): 通告的有效期。应用场景示例系统维护Bot在计划进行维护时可以广播一条消息[BROADCAST → *all*] From: SysMaintenanceBot Announcement: 主数据库将于北京时间今晚02:00-04:00进行维护期间相关写操作API可能间歇性不可用。 Expires: 2023-10-28T04:00:00Z Depth: 1/5接收广播的Bot可以根据自身逻辑决定是否记录日志、暂停相关任务或通知人类用户。4. 实战从零实现一个基于bot-protocol的协作流程理解了理论我们来看如何在实际代码中运用。假设我们要实现一个简单的“服务器健康检查”工作流SchedulerBot调度器定期触发向InfraCheckBot基础设施检查员发送检查请求后者如果需要特定服务状态则向ServiceProbeBot服务探针咨询最后汇总结果回复。4.1 环境搭建与项目初始化首先我们需要一个工作空间。假设你使用OpenClaw框架或其类似的多Agent环境。# 1. 进入你的工作空间或项目目录 cd ~/my-ai-agent-workspace # 2. 为bot-protocol技能创建目录并初始化 mkdir -p skills/bot-protocol cd skills/bot-protocol # 3. 初始化Node.js项目如果尚未有package.json npm init -y # 4. 安装bot-protocol假设它已发布为npm包或从源码安装 # 这里我们演示从源码集成。将提供的bot-protocol源码复制到当前目录的lib下。 # 假设目录结构如下 # bot-protocol/ # ├── lib/ # │ ├── parser.js # │ ├── builder.js # │ └── state.js # ├── package.json # └── SKILL.md # 5. 安装可能的依赖例如用于状态持久化的文件操作库协议本身可能无外部依赖 # npm install some-storage-library4.2 构建与解析消息builder.js 和 parser.js 实战每个需要参与协议的Bot都需要集成消息构建和解析能力。在 SchedulerBot 中发起请求// schedulerBot.js const { buildRequest } require(./skills/bot-protocol/lib/builder.js); const state require(./skills/bot-protocol/lib/state.js); async function triggerHealthCheck() { const requestId scheduler-health-${Date.now()}; // 构建一个REQUEST消息 const healthCheckRequest buildRequest({ to: InfraCheckBot, // 目标Bot名称 from: SchedulerBot, requestId: requestId, task: 执行全面的服务器健康检查包括CPU、内存、磁盘和网络连通性。, depth: { current: 1, max: 5 }, priority: normal, context: 每日凌晨例行检查 }); console.log(构建的协议消息:); console.log(healthCheckRequest); // 输出类似 // [REQUEST → InfraCheckBot] // From: SchedulerBot // RequestId: scheduler-health-1698403200000 // Task: 执行全面的服务器健康检查包括CPU、内存、磁盘和网络连通性。 // Depth: 1/5 // Priority: normal // Context: 每日凌晨例行检查 // 发送消息这里模拟通过某个平台API发送 // await discordClient.sendMessage(#bot-channel, healthCheckRequest); // 或 await slackClient.postMessage(channel-id, { text: healthCheckRequest }); // 记录状态SchedulerBot 需要追踪自己发出的请求 await state.track({ ...JSON.parse(JSON.stringify(healthCheckRequest)), // 存储消息对象 status: open, timestamp: new Date().toISOString() }); } // 解析收到的RESPONSE async function handleIncomingMessage(rawText) { const { parse } require(./skills/bot-protocol/lib/parser.js); const parsed parse(rawText); if (!parsed) { // 不是有效的协议消息可能是普通聊天忽略或按其他逻辑处理 console.log(无法解析为协议消息忽略。); return; } if (parsed.to SchedulerBot) { console.log(收到发给我的消息类型: ${parsed.type}, requestId: ${parsed.requestId}); // 更新状态 await state.update(parsed.requestId, { status: parsed.status, // 例如 success lastResponse: parsed.body, updatedAt: new Date().toISOString() }); // 根据消息类型和处理结果执行业务逻辑 if (parsed.type RESPONSE parsed.status success) { console.log(任务 ${parsed.requestId} 成功完成结果:, parsed.body); // 例如将健康报告写入数据库或发送通知 } } }在 InfraCheckBot 中处理并可能转发请求// infraCheckBot.js const { parse, buildClarify, buildHandoff, buildResponse } require(./skills/bot-protocol/lib/builder.js); const state require(./skills/bot-protocol/lib/state.js); async function processMessage(rawText) { const parsed parse(rawText); if (!parsed || parsed.to ! InfraCheckBot) return; // 追踪此会话 await state.track(parsed); switch (parsed.type) { case REQUEST: await handleRequest(parsed); break; // ... 处理其他消息类型 } } async function handleRequest(req) { console.log(处理请求: ${req.requestId}, 任务: ${req.task}); // 假设InfraCheckBot能自己检查CPU、内存、磁盘但需要专门Bot检查网络服务 const needsServiceCheck req.task.includes(网络连通性); if (needsServiceCheck) { // 深度检查如果已达上限必须直接回复失败不能继续HANDOFF if (req.depth.current req.depth.max) { const errorResponse buildResponse({ to: req.from, from: InfraCheckBot, requestId: req.requestId, status: failed, body: 任务深度已达上限无法继续委托检查网络服务。, depth: req.depth // 深度不变 }); // 发送 errorResponse... return; } // 深度未超限将网络检查部分HANDOFF给专家Bot const handoffMsg buildHandoff({ to: ServiceProbeBot, from: InfraCheckBot, originalFrom: req.from, // 关键记录最初发起者 requestId: req.requestId, task: 检查服务器对以下外部服务的网络连通性api.github.com:443, aws.amazon.com:80。, depth: { current: req.depth.current 1, max: req.depth.max } // 深度1 }); // 发送 handoffMsg... // 注意发送HANDOFF后InfraCheckBot可以等待最终RESPONSE或者由ServiceProbeBot直接回复给originalFrom // 这里假设协议设计为HANDOFF后责任转移ServiceProbeBot会直接回复给SchedulerBot。 } else { // 自己能处理直接执行并回复RESPONSE const cpu await checkCPU(); const mem await checkMemory(); const disk await checkDisk(); const response buildResponse({ to: req.from, from: InfraCheckBot, requestId: req.requestId, status: success, body: { cpu, mem, disk }, depth: req.depth }); // 发送 response... } }4.3 状态管理与超时检查state.js 的集成状态管理是可靠性的基石。你需要一个后台进程或定时任务来运行超时检查。// stateManager.js 或 在Bot主循环中 const state require(./skills/bot-protocol/lib/state.js); async function periodicStateMaintenance() { // 1. 检查超时的会话 const timedOutSessions await state.checkTimeouts(); for (const session of timedOutSessions) { console.warn(会话超时: ${session.requestId}); // 可选自动发送一个超时RESPONSE给原始请求者 // const timeoutResponse buildResponse({...}); // sendMessage(timeoutResponse); // 清理本地状态 await state.remove(session.requestId); } // 2. 持久化状态到文件如果state.js不是自动持久化 await state.persist(); } // 每5分钟运行一次 setInterval(periodicStateMaintenance, 5 * 60 * 1000);5. 高级主题、常见陷阱与最佳实践在实际部署中你会遇到一些设计决策点和常见问题。5.1 RequestId 的设计与冲突避免requestId必须是全局唯一的否则状态管理会混乱。简单的方案是使用UUID或时间戳随机数发送方标识的组合。function generateRequestId(botName) { const timestamp Date.now(); const random Math.floor(Math.random() * 10000); return ${botName}-${timestamp}-${random}; // 示例: SchedulerBot-1698403200000-42 }陷阱避免使用可能重复的ID如简单的递增计数器或在分布式环境中可能冲突的ID。如果多个Bot实例独立生成ID加入机器标识符是更安全的选择。5.2 深度限制策略的权衡默认最大深度5是一个经验值。你需要根据你的Bot网络拓扑来调整链式调用如果你的工作流是严格的A-B-C线性链深度可以设置得小一些如3。星型调用如果是一个中心Bot协调多个专家Bot专家Bot之间不互相调用深度需求可能只有2。设置过大如20失去防循环保护的意义。设置过小如2可能阻碍合理的多步协作。最佳实践在协议初始化或每个REQUEST中允许自定义max值但系统应设置一个绝对上限例如10。5.3 错误处理与边缘情况协议库本身parser.js,builder.js会抛出错误或返回null你的Bot必须有相应的容错处理。// 解析时的错误处理 try { const parsed parse(incomingText); if (parsed null) { // 不是协议消息按普通文本处理或忽略 return; } // 继续处理parsed对象... } catch (error) { console.error(解析协议消息时发生意外错误:, error); // 不要因为单个消息解析失败而崩溃整个Bot } // 构建消息时的错误处理 try { const msg buildRequest({ to: SomeBot, from: Me, /* 缺少必填字段... */ }); } catch (error) { console.error(构建协议消息失败:, error.message); // 例如可能缺少必填字段或深度违规。这里应该记录日志并可能向操作员报警。 } // 处理“自己发给自己”的消息 if (parsed.to parsed.from) { console.log(警告收到自己发出的消息。可能是循环或配置错误。); // 根据策略决定忽略、记录、或发送一个错误RESPONSE打断循环。 }5.4 协议扩展与向前兼容未来你可能需要增加新字段比如sla服务等级协议、callbackUrl异步回调地址。遵循向前兼容原则在builder.js中新字段应作为可选参数。在parser.js中未知字段应被收集到parsed.metadata对象中而不是被丢弃。新版本的Bot在读取旧版本消息时应能优雅地处理缺失的新字段提供默认值或跳过相关功能。// 假设v0.2增加了 sla 字段 // builder.js (新版) function buildRequest(options) { const base { /* 基础字段 */ }; const extended { ...base, ...options }; // 序列化时sla字段会被包含进去 } // parser.js (新版) function parse(text) { // ... 解析逻辑 const knownFields { to, from, requestId, task, depth /*, ...*/ }; const metadata {}; // 遍历其他行将未知的键值对存入metadata // 例如如果消息来自v0.1的Bot没有sla字段metadata就是空的 return { ...knownFields, metadata, type: REQUEST }; } // 业务逻辑中 if (parsed.metadata.sla) { // 新功能根据SLA调整优先级 } else { // 旧消息使用默认SLA }5.5 测试策略对于此类基础协议全面的测试至关重要。单元测试针对parser.js和builder.js的每个函数测试正常情况、边界情况深度5、错误情况缺失字段、格式错误。集成测试模拟两个Bot之间完整的对话流程包括REQUEST - CLARIFY - RESPONSE以及REQUEST - HANDOFF - RESPONSE。模糊测试向解析器输入随机文本确保其不会崩溃并能正确返回null。状态持久化测试模拟进程重启验证状态是否能正确从文件恢复。// 一个简单的单元测试示例 (使用类似Jest的框架) const { parse } require(./lib/parser); test(解析器应正确解析标准REQUEST, () { const msg [REQUEST → TestBot]\nFrom: Sender\nRequestId: test-123\nTask: Do something\nDepth: 1/5; const result parse(msg); expect(result).not.toBeNull(); expect(result.type).toBe(REQUEST); expect(result.to).toBe(TestBot); expect(result.requestId).toBe(test-123); }); test(解析器应拒绝缺少RequestId的消息, () { const msg [REQUEST → TestBot]\nFrom: Sender\nTask: Do something\nDepth: 1/5; const result parse(msg); expect(result).toBeNull(); });6. 性能考量与部署建议当你的Bot网络规模增长时以下几点需要关注状态存储后端示例中使用的是本地JSON文件(~/.openclaw/workspace/bot-protocol-state.json)。这对于单个实例、低频率的Bot是可行的。但在高并发或分布式部署多个Bot实例时你需要将状态存储迁移到共享的、支持原子操作的后端如Redis或数据库。你需要重写state.js中的持久化部分。消息序列化开销协议消息是纯文本在Bot内部流转时可以保持为解析后的对象格式只在通过外部通道如Discord API发送前序列化为文本。避免频繁的序列化/反序列化。解析性能parser.js应尽可能高效因为它会对每一条流入的消息调用。使用编译好的正则表达式避免在循环中重复编译。监控与可观测性记录关键指标每秒处理的消息数、各类型消息的比例、平均对话深度、超时会话数、解析失败率。这些指标能帮助你发现瓶颈如某个Bot成为热点或异常模式如深度经常达到上限可能预示逻辑缺陷。部署拓扑对于复杂的协作网络考虑引入一个轻量级的“协议路由器”或“消息总线”Bot。所有其他Bot只与这个路由器通信由路由器负责根据to字段将消息转发给正确的目标Bot。这可以简化每个Bot的连接管理并提供一个中心点进行监控、审计和流量控制。将bot-protocol这样的结构化通信层引入你的AI Agent系统初期会带来一些额外的工作量——需要为每个Bot集成解析和构建逻辑。但从长远看它带来的清晰性、可靠性和可维护性是巨大的。它迫使你明确Bot之间的契约让调试从“猜谜游戏”变成“查看状态机和日志”为构建真正复杂、健壮的自动化协作系统打下了坚实的基础。