Agent Comm Hub
by @liuboacean
多智能体消息转发与上下文共享中间件 — 基于 MCP 协议实现 agent 间通信与任务协同。支持多 Agent 接入，提供标准 MCP 工具接口和本地 SQLite 存储。
clawhub install agent-comm-hub📖 About This Skill
name: agent-comm-hub description: "多智能体消息转发与上下文共享中间件 — 基于 MCP 协议实现 agent 间通信与任务协同。支持多 Agent 接入，提供标准 MCP 工具接口和本地 SQLite 存储。" version: "2.5.2" category: autonomous-ai-agents env: HUB_KEY: description: "stdio mode connection key for agent authentication" required: true secret: true
Agent Communication Hub
> 多智能体消息转发与上下文共享中间件 — v2.5.0
让两个或多个独立 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)
三层协议：
| 层 | 协议 | 用途 | 延迟 | |----|------|------|------| | MCP 工具层 | stdio JSON-RPC | 结构化操作（发消息、分配任务、查状态） | <50ms | | SSE 推送层 | Server-Sent Events | 实时事件通知（新消息、新任务、建议确认） | <50ms |
核心能力
53 个 MCP 工具（v2.4.0）
#### Identity 身份 (6)
| 工具 | 功能 |
|------|------|
| register_agent | 注册新 Agent，需提供 HUB_KEY 认证 |
| heartbeat | Agent 心跳上报，维持在线状态，每 3 次连续心跳记录 +1 |
| query_agents | 查询 Agent 列表，支持状态/角色筛选 |
| get_online_agents | 获取当前在线 Agent 列表 |
#### Message 消息 (5)
| 工具 | 功能 |
|------|------|
| send_message | Agent 间点对点消息，支持 Markdown，自动去重（sha256） |
| broadcast_message | 群发消息给多个 Agent |
| acknowledge_message | 确认已读消息，防止重复出现 |
| search_messages | 全文搜索消息历史 |
| batch_acknowledge_messages | 批量确认消息（1-500 条/次），用于清理消息积压 |
#### File 文件 (3)
| 工具 | 功能 |
|------|------|
| send_file | 发送文件附件（Base64，10MB 限制），关联到消息 |
| receive_file | 接收附件，返回 Base64 编码内容 |
| list_attachments | 列出附件，支持按消息/Agent 筛选 |
#### Task 任务 (3)
| 工具 | 功能 |
|------|------|
| assign_task | 创建并分配任务，支持上下文传递 |
| update_task_status | 更新任务状态（inbox→assigned→in_progress→completed/failed） |
| get_task_status | 查询任务详情，含依赖、Pipeline、交接信息 |
#### Context 上下文暂存 (5)
| 工具 | 功能 |
|------|------|
| store_memory | 临时暂存当前任务参考信息 |
| recall_memory | 检索已暂存的上下文 |
| list_memories | 列出当前 Agent 的暂存条目 |
| delete_memory | 删除暂存条目（仅 creator） |
| search_memories | 检索当前 Agent 的暂存内容 |
#### 经验记录
经验记录工具（share_experience/propose_strategy/apply_strategy 等）需 full 权限，详见 GitHub 源码。
#### 任务协同
| 工具 | 功能 |
|------|------|
| add_dependency | 添加任务依赖关系（依赖检查） |
| remove_dependency | 删除任务依赖关系 |
| get_task_dependencies | 查询任务上下游依赖 |
| create_parallel_group | 创建并行任务组（2-10 个任务） |
| request_handoff | 请求任务交接 |
| accept_handoff | 接受任务交接 |
| reject_handoff | 拒绝任务交接（含理由） |
| add_quality_gate | 在 Pipeline 中添加质量门 |
| evaluate_quality_gate | 评估质量门（passed/failed） |
| recalculate_trust_scores | 手动触发分数重算（完整权限） |
| create_pipeline | 创建 Pipeline 流水线 |
| get_pipeline | 查询 Pipeline 详情 |
| list_pipelines | 列出 Pipeline |
| add_task_to_pipeline | 向 Pipeline 添加任务 |
#### 运维工具 (4)
| 工具 | 功能 |
|------|------|
| get_db_stats | 数据库统计信息（表行数、大小、Agent 数等） |
| archive_data | 数据归档：将过期消息/审计日志移入归档表 |
| （其余 2 个内部工具） | 权限验证与控制 |
#### 消费水位线 (2)
| 工具 | 功能 |
|------|------|
| mark_consumed | 标记任务/消息为已消费，防止重复处理 |
| check_consumed | 查询资源是否已被消费 |
> 所有工具内置 try-catch + 3 次指数退避重试（100ms → 200ms → 400ms）。v2.4.0 统一错误格式：HubError 错误码 + mcpError()/mcpFail() 标准返回。check_consumed 查询失败时降级返回 consumed=false（不阻塞业务）。
任务状态机
inbox → assigned → [waiting] → in_progress → completed / failed / cancelled
数据隔离与安全边界
| 边界 | 实现方式 |
|------|---------|
| 接收方校验 | send_message/assign_task 中的 to_agent 必须为已注册 Agent，未注册 Agent 被拒绝 |
| Per-Agent 数据隔离 | 每个 Agent 仅可见自身消息、任务和暂存条目；跨 Agent 查询受 4 级权限控制 |
| 暂存内容保护 | store_memory 创建的条目仅 creator 可检索和删除，不会自动暴露给其他 Agent |
| 经验记录审批 | share_experience 提交的记录需经 full 权限确认后才对其他 Agent 可见 |
接入配置（stdio 模式）
在 MCP 配置文件中添加 Hub 为 stdio 服务器，提供 HUB_KEY 环境变量进行认证。Hub 通过 stdio 传输 MCP 协议，Agent 的 LLM 可直接调用 Hub 工具。
{
"mcpServers": {
"agent-comm-hub": {
"command": "node",
"args": ["/stdio.js"],
"env": {
"HUB_KEY": "your-connection-key"
}
}
}
}
工具详情
完整工具定义、参数 schema 和使用示例，请参考 GitHub 仓库源码： https://github.com/liuboacean/agent-comm-hub
权限说明（4 级）
| 级别 | 说明 | 可用工具范围 |
|------|------|----------|
| authenticated | 已认证（HUB_KEY） | register_agent（初始注册） |
| member | 已注册 Agent | 消息 send_message/acknowledge_message + 任务 assign_task/get_task_status |
| group_manager | 并行组管理 | 任务协同 + Pipeline 工具（不含暂存/经验） |
| full | 完整权限 | 全部工具（含运维与建议管理） |
> broadcast_message、archive_data、recalculate_trust_scores、apply_strategy 等变更全局状态的工具仅 full 权限可调用。
> 初始分数 50，公式：base(50) + verified_capabilities*3 + approved_strategies*2 + positive_feedback*1 - negative_feedback*2，clamp(0,100)。
v2.4.0 更新要点
| Phase | 内容 | 变更 | |-------|------|------| | A | tools.ts 拆分 | 2687 行 → 8 模块 + 30 行入口 + utils.ts | | B | 单元测试 | 100 用例，role-control >= 70% / dedup branches>=60, functions>=70 / utils 100% | | C | CI/CD | GitHub Actions：typecheck + test + coverage 3 Jobs | | D | 类型健壮 | any 归零 + HubError 统一错误码 + MCP 返回格式标准化 |
踩坑经验速查
| # | 场景 | 要点 |
|---|------|------|
| 1 | MCP 多 Client | 必须用 Stateless 模式，Stateful 只允许一个 Client |
| 2 | MCP Accept Header | 必须带 Accept: application/json, text/event-stream |
| 3 | MCP 响应格式 | SDK 返回 SSE 格式（data: {...}），不是纯 JSON |
| 4 | ESM 兼容 | 不能用 require()，用 import() 动态导入 |
| 5 | UTF-8 块读取 | httpx resp.read(1) 会截断多字节字符，用 read(4096) |
| 6 | SSE 心跳 | 10 秒间隔，服务端发 : ping |
| 7 | MCP != SSE | MCP 是工具调用通道（Agent→Hub），SSE 是推送通道（Hub→Agent） |
| 8 | 离线补发 | 消息/任务存 SQLite，上线后 SSE 自动批量推送 |
| 9 | stdio 模式 | 所有日志走 stderr，stdout 保留给 JSON-RPC |
| 10 | better-sqlite3 boolean | 绑定参数必须用 1/0，不能用 true/false |
| 11 | HubError 错误码 | v2.4.0 统一用 mcpError()/mcpFail()，不要手动构造错误响应 |
安全配置
| 配置项 | 说明 |
|--------|------|
| HUB_KEY | stdio 模式连接密钥，所有 Agent 接入必须提供，用于身份认证与消息完整性校验 |
| 4 级权限模型 | authenticated → member → group_manager → full，逐级授权 |
| CORS 白名单 | 默认拒绝跨域，通过 CORS_LIST 显式配置允许的来源 |
环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| HUB_KEY | — | stdio 模式连接密钥（必填） |
| DB_PATH | ./comm_hub.db | SQLite 数据库路径 |
| LOG_LEVEL | info | 日志级别：debug / info / warn / error |
| CORS_LIST | (空) | CORS 白名单（逗号分隔），空=拒绝所有跨域 |
技术依赖
Hub 服务器：
Python 客户端（零外部依赖）：