Agent Comm Hub

Agent Communication Hub

多智能体消息转发与上下文共享中间件 — v2.4.5

让两个或多个独立 AI 智能体之间实现实时双向通信和上下文自动同步。基于 MCP 协议 + stdio 模式，消息本地持久化，延迟 < 50ms。

架构概览

┌──────────────┐         ┌──────────────────────────────┐         ┌──────────────┐
│   Agent A    │  SSE    │   Agent Communication Hub    │  SSE    │   Agent B    │
│  (Hermes)    │◄───────►│  (stdio)                    │◄───────►│ (WorkBuddy)  │
│              │  MCP    │                              │  MCP    │              │
└──────────────┘◄───────►│  SQLite WAL + 30 表          │◄───────►└──────────────┘
                          │  53 MCP 工具 + 4 级权限     │
                          │  上下文暂存 + 建议闭环       │
                          └──────────────┬──────────────┘
                                         │
                                    SQLite (WAL)

三层协议：

快速上手 (5 分钟)

从零到完成第一次 Agent 间通信的编号流程：

Step 1: 确认 Hub 运行状态

确认 Agent Communication Hub 服务器正在运行。如果通过 stdio 模式接入，检查 MCP 配置是否正确加载：

调用: get_online_agents()
期望: 返回在线 Agent 列表（至少含自己）
失败: Hub 未运行 → 先启动 Hub 服务器

[检查点] 用户确认：如果 Hub 未运行，询问用户是否要启动 Hub 服务器。

Step 2: 注册或确认身份

检查自己是否已在 Hub 注册，如果没有则注册：

1. 调用: query_agents(status='all') → 查看所有 Agent
2. 如果自己的 Agent ID 不在列表中
   → register_agent(invite_code, name, capabilities)
3. 如果已注册 → 记下自己的 agent_id 供后续使用

[检查点] 用户确认：注册新 Agent 需要 invite_code，先问用户是否有可用的邀请码。

Step 3: 维持在线状态

启动心跳维持在线，确保能接收实时消息推送：

调用: heartbeat(agent_id='你的ID')
频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）

Step 4: 检查未读消息

上线后第一时间检查是否有离线期间缓存的消息：

1. 调用: search_messages(query='你的ID', limit=20)
2. 筛选 status='unread' 的消息
3. 按时间顺序处理，先 acknowledge_message 确认收到，再回复

[检查点] 用户确认：找到未读消息后，逐条向用户摘要汇报，请用户确认如何处理。

Step 5: 发送第一条消息

向另一个 Agent 发送消息，验证双向通信：

调用: send_message(from='你的ID', to='目标AgentID', content='通信链路确认畅通')
检查返回: delivered_realtime — true=对方在线, false=对方离线

[检查点] 用户确认：发送前向用户确认消息内容和目标 Agent。broadcast_message 必须逐条确认。

完整闭环示例

场景：Hub 在线 → 检查 WorkBuddy 是否有未读消息 → 处理并回复

1. get_online_agents()                    # 确认自己和对方在线
2. search_messages(limit=10)              # 查最近消息
3. acknowledge_message(msg_id, agent_id)  # 标记已读
4. send_message(to='workbuddy', content='已收到，正在处理')  # 回复
5. mark_consumed(resource=msg_id, action='replied')  # 消费水位线

核心能力

53 个 MCP 工具（v2.4.0）

Identity 身份 (6)

Message 消息 (5)

File 文件 (3)

Task 任务 (3)

Context 上下文暂存 (5)

经验记录

经验记录和策略管理需特定权限配置。

任务协同

运维工具 (4)

消费水位线 (2)

所有工具内置 try-catch + 3 次指数退避重试（100ms → 200ms → 400ms）。v2.4.0 统一错误格式：HubError 错误码 + mcpError()/mcpFail() 标准返回。check_consumed 查询失败时降级返回 consumed=false（不阻塞业务）。

任务状态机

inbox → assigned → [waiting] → in_progress → completed / failed / cancelled

用户确认检查点

以下操作必须在执行前暂停，向用户摘要说明并等待确认：

规则：LLM 遇到上表操作时，先向用户输出摘要说明，明确询问"是否继续？"，得到肯定答复后再执行。用户可随时跳过检查点。

数据隔离与安全边界

接入配置（stdio 模式）

在 MCP 配置文件中添加 Hub 为 stdio 服务器，提供 HUB_KEY 环境变量进行认证。Hub 通过 stdio 传输 MCP 协议，Agent 的 LLM 可直接调用 Hub 工具。

{
  "mcpServers": {
    "agent-comm-hub": {
      "command": "node",
      "args": ["<hub-install-path>/stdio.js"],
      "env": {
        "HUB_KEY": "your-connection-key"
      }
    }
  }
}

资源索引

此 skill 目录下已有 Hub 完整源码，可直接参考：

本地源文件

参考链接

• GitHub 仓库: https://github.com/liuboacean/agent-comm-hub
• MCP 协议规范: https://spec.modelcontextprotocol.io

权限说明（4 级）

部分管理类工具仅特定权限可调用，具体以实际角色配置为准。

初始分数 50，公式：base(50) + verified_capabilities*3 + approved_strategies*2 + positive_feedback*1 - negative_feedback*2，clamp(0,100)。

v2.4.0 更新要点

踩坑经验速查

安全配置

环境变量

技术依赖

Hub 服务器：

• Node.js 18+
• @modelcontextprotocol/sdk ^1.10.2（支持 StdioServerTransport）
• express ^4.19
• better-sqlite3 ^11.9
• zod ^3.23

Python 客户端（零外部依赖）：

• Python 3.9+（纯标准库：http.client / json / asyncio）