# bot-relay-mcp：多智能体工作流的本地优先协调原语

> bot-relay-mcp是一个基于TypeScript和SQLite的MCP（Model Context Protocol）协调工具，为AI编码代理和外部系统提供去中心化的消息中继和任务协调能力，支持25种工具，实现真正的本地优先多智能体协作。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-20T09:38:24.000Z
- 最近活动: 2026-04-20T09:56:12.952Z
- 热度: 163.7
- 关键词: MCP, 多智能体, AI编码代理, Claude Code, SQLite, 本地优先, 任务协调, 消息中继, TypeScript, 零基础设施
- 页面链接: https://www.zingnex.cn/forum/thread/bot-relay-mcp
- Canonical: https://www.zingnex.cn/forum/thread/bot-relay-mcp
- Markdown 来源: ingested_event

---

# bot-relay-mcp：多智能体工作流的本地优先协调原语

## 多智能体协调的基础设施挑战

随着AI编码代理（如Claude Code、Cursor、Cline等）的普及，开发者越来越需要在多个AI实例之间进行协调。然而，现有的解决方案往往依赖云服务、复杂的Service Mesh架构或特定的平台锁定，这带来了以下问题：

- **隐私与安全**：敏感代码和任务数据需要经过第三方服务器
- **基础设施复杂性**：需要部署和维护额外的服务组件
- **平台锁定**：特定于某个AI工具或云厂商的解决方案
- **网络依赖**：离线或受限网络环境下无法工作

**bot-relay-mcp**的出现正是为了解决这些痛点。

## 项目概述

bot-relay-mcp由Maxlumiere开发，是一个**本地优先的消息中继系统**，专为AI编码代理和外部系统的协调而设计。它采用极简架构：**两个接口，一个共享的SQLite数据库，零基础设施**。

当前版本v2.1已架构完整，提供25种工具，实现了智能路由、任务租约、会话感知读取、延迟健康监控、忙碌/勿扰状态、Webhook重试、频道功能等核心特性。

## 核心架构设计

### 双接口设计

bot-relay-mcp同时服务两类用户：

**1. AI编码代理（stdio MCP接口）**
- Claude Code、Cursor、Cline、Zed等工具通过stdio MCP连接
- 只需在`~/.claude.json`中添加一个配置项即可接入
- 无需守护进程，无需云服务

**2. 外部系统（HTTP+SSE接口）**
- n8n、Slack、Telegram、自定义脚本等通过HTTP+SSE连接
- 支持可选的Bearer Token认证
- 可触发代理动作或接收Webhook事件

### 本地优先的SQLite存储

所有数据都存储在本地SQLite文件`~/.bot-relay/relay.db`中：
- **无云服务**：数据不离开本地机器
- **无守护进程**：直接通过npx运行，无需安装服务
- **无Service Mesh**：简单的文件级共享

文件权限设置（v2.1）：
- `~/.bot-relay/`目录权限：0700（仅所有者）
- `relay.db`和备份文件权限：0600（仅所有者读写）
- config.json由操作员管理，启动时如果权限过于宽松会发出警告

## 功能详解：25种工具分类

### 代理管理工具

- **register_agent**：注册当前终端为命名代理，使用upsert机制可安全多次调用
- **unregister_agent**：从relay中移除代理，幂等操作，成功时触发webhook
- **discover_agents**：列出所有已注册代理及其状态（online/stale/offline）
- **spawn_agent**：生成预配置为relay代理的新Claude Code终端，支持跨平台（macOS、Linux、Windows）

### 消息传递工具

- **send_message**：向指定代理发送直接消息
- **get_messages**：检查邮箱，待处理消息自动标记为已读
- **broadcast**：向所有注册代理广播消息（可按角色过滤）

### 任务管理工具

- **post_task**：向指定代理分配任务
- **post_task_auto**：自动路由到负载最低且能力匹配的代理，无匹配时排队
- **update_task**：支持accept/complete/reject/cancel/heartbeat操作，带状态机和CAS保护
- **get_tasks**：查询任务队列（分配给我或我发布的）
- **get_task**：获取单个任务的完整详情

### 频道协调工具

- **create_channel**：创建多智能体协调的命名频道
- **join_channel**：加入公共频道
- **leave_channel**：离开频道
- **post_to_channel**：向成员频道发送消息
- **get_channel_messages**：读取自加入以来频道中的消息

### 状态与监控工具

- **set_status**：设置online/busy/away/offline状态，busy/away免除健康监控任务重新分配
- **health_check**：报告relay版本、运行时间和实时计数，无需认证

### Webhook工具

- **register_webhook**：通过HTTP POST订阅relay事件
- **list_webhooks**：列出所有注册的Webhook订阅
- **delete_webhook**：移除Webhook订阅

支持的事件类型包括：message.sent、message.broadcast、task.posted、task.accepted、task.completed、task.rejected、task.cancelled、task.auto_routed、task.health_reassigned、channel.message_posted、agent.unregistered、agent.spawned、webhook.delivery_failed等。

**Webhook重试机制（v2.0）**：失败投递在60s/300s/900s后重试（共3次），CAS声明每行数据防止重复投递。

## 实际使用示例

### 场景：协调器-工作者模式

**终端A - 协调器（Orchestrator）**：
```
1. register_agent("orchestrator", "planner", ["delegation", "review"])
2. discover_agents() → 发现"worker"在线
3. post_task(from: "orchestrator", to: "worker",
   title: "编写认证测试",
   description: "覆盖登录、登出、token刷新，使用vitest",
   priority: "high")
4. send_message(from: "orchestrator", to: "worker",
   content: "任务已发布，请检查你的队列")
```

**终端B - 工作者（Worker）**：
```
1. register_agent("worker", "builder", ["testing", "backend"])
2. get_messages("worker") → 收到来自协调器的消息
3. get_tasks("worker", role: "assigned", status: "posted") → 获取认证测试任务
4. update_task(task_id, "worker", "accept")
5. ...执行任务...
6. update_task(task_id, "worker", "complete", result: "12个测试通过")
7. send_message(from: "worker", to: "orchestrator",
   content: "认证测试完成，全部通过")
```

## 安全特性

### v2.1安全增强

- **显式auth_state状态机**：支持revoke/recovery流程
- **managed-agent轮换**：优雅的密钥轮换机制
- **keyring-based加密**：支持在线密钥轮换
- **统一relay CLI**：提供recover、re-encrypt、doctor、init、test、generate-hooks、backup、restore等命令

### 认证与签名

当提供secret时，每个Webhook投递包含X-Relay-Signature: sha256=... HMAC头，确保消息完整性。filter可选限制触发条件，如from_agent或to_agent匹配。

## 安装与配置

### 通过npm安装（推荐）

```json
{
  "mcpServers": {
    "bot-relay": {
      "command": "npx",
      "args": ["-y", "bot-relay-mcp"],
      "type": "stdio"
    }
  }
}
```

首次调用会自动获取包并启动服务器，后续启动即时完成。

### 本地开发安装

```bash
git clone https://github.com/Maxlumiere/bot-relay-mcp.git
cd bot-relay-mcp
npm install
npm run build
```

然后配置`~/.claude.json`指向本地构建文件。

## 跨平台支持

spawn_agent工具支持跨平台终端生成：
- **macOS**：iTerm2 / Terminal.app
- **Linux**：gnome-terminal / konsole / xterm / tmux（回退链，tmux覆盖无头服务器）
- **Windows**：wt.exe / powershell.exe / cmd.exe

## 与现有方案的对比

| 特性 | bot-relay-mcp | 云协调服务 | Service Mesh |
|------|--------------|-----------|--------------|
| 数据隐私 | 完全本地 | 经过第三方 | 经过基础设施 |
| 基础设施 | 零 | 需要部署 | 复杂 |
| 离线支持 | 是 | 否 | 否 |
| 平台锁定 | 无 | 通常有 | 通常有 |
| 设置复杂度 | 极低 | 中等 | 高 |

## 应用场景

### 1. 多代理并行开发

在大型项目中，多个Claude Code实例可以分别负责不同模块，通过bot-relay-mcp协调任务分配和进度同步。

### 2. CI/CD集成

通过Webhook和HTTP接口，将AI编码代理集成到现有的CI/CD流程中，实现自动化代码审查、测试生成等。

### 3. 人机协作

人类开发者可以通过Slack/Telegram与AI代理交互，发布任务并接收结果，而AI代理之间通过MCP协调。

### 4. 复杂工作流编排

利用频道功能，实现多智能体的复杂工作流，如：需求分析→架构设计→代码实现→测试→审查的完整pipeline。

## 局限性与未来方向

### 当前局限

1. **单点存储**：SQLite文件是单点，虽然简单但不支持多机共享
2. **无持久化队列**：重启后消息状态依赖SQLite，无外部消息队列
3. **POSIX权限**：Windows上chmod调用为no-op，依赖ACL

### 未来方向

1. **分布式存储**：可选的分布式后端支持
2. **更多平台支持**：扩展至更多AI编码工具
3. **可视化监控**：Web UI实时查看代理状态和任务流
4. **插件系统**：支持自定义工具扩展

## 总结

bot-relay-mcp代表了多智能体协调的一种**极简主义哲学**——用最小的复杂度解决实际问题。它不追求功能最全，而是追求**刚刚好**的解决方案：

- 对于需要云规模协调的场景，可以选择更重的方案
- 对于需要快速启动、隐私优先、本地运行的场景，bot-relay-mcp提供了恰到好处的功能集

其25种工具覆盖了代理管理、消息传递、任务管理、频道协调、状态监控和Webhook集成等核心需求，而整个系统仅依赖一个SQLite文件和简单的配置。

对于正在使用Claude Code、Cursor等AI编码工具的开发者，bot-relay-mcp提供了一个立即可用的协调层，让多代理协作变得像单代理一样简单。这种**本地优先、零基础设施**的设计理念，可能预示着AI工具链的下一个演进方向。