Agent Comm Hub

Agent Communication Hub

多智能体实时通信与任务调度基础设施 — v2.4.2

让两个或多个独立 AI 智能体之间实现实时双向通信、任务自动调度、记忆共享和策略进化。基于 MCP 协议 + SSE 推送，消息零丢失，延迟 < 50ms。

架构概览

┌──────────────┐         ┌──────────────────────────────┐         ┌──────────────┐
│   Agent A    │  SSE    │   Agent Communication Hub    │  SSE    │   Agent B    │
│  (Hermes)    │◄───────►│  (stdio / HTTP:3100)       │◄───────►│ (WorkBuddy)  │
│              │  MCP    │                              │  MCP    │              │
└──────────────┘◄───────►│  SQLite WAL + 30 表          │◄───────►└──────────────┘
                          │  53 MCP 工具 + 4 级权限      │
                          │  进化引擎 + 策略闭环          │
                          └──────────────┬──────────────┘
                                         │
                                    SQLite (WAL)

三层协议：

核心能力

53 个 MCP 工具（v2.4.2）

Identity 身份 (6)

Message 消息 (5)

File 文件 (3)

Task 任务 (3)

Memory 记忆 (5)

Evolution 进化 (12)

Orchestration 进阶编排 (16)

Security 运维安全 (4)

Consume 消费水位线 (2)

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

运维 REST API

任务状态机

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

快速开始

1. 启动 Hub 服务器

git clone https://github.com/liuboacean/agent-comm-hub.git
cd agent-comm-hub
npm install
npm run build
npm start      # HTTP 模式（port 3100）
# 或
npm run stdio  # stdio 模式（用于 MCP stdio transport）

2. 配置 Agent 接入

方式 A：MCP stdio 模式（推荐，适用于本地 Agent）

{
  "mcpServers": {
    "agent-comm-hub": {
      "command": "node",
      "args": ["./src/stdio.js"],
      "env": {
        "HUB_AUTH_TOKEN": "your-api-token",
        "DB_PATH": "./comm_hub.db"
      }
    }
  }
}

方式 B：MCP HTTP 模式（适用于远程 Agent）

{
  "mcpServers": {
    "agent-comm-hub": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

方式 C：SDK 接入

TypeScript Agent：

import { AgentClient } from "./client-sdk/agent-client.js";
const client = new AgentClient({
  agentId: "my-agent",
  hubUrl: "http://localhost:3100",
  onTaskAssigned: async (task) => { /* 处理任务 */ },
  onMessage: async (msg) => { /* 处理消息 */ },
});
await client.start();

Python Agent（零外部依赖）：

import asyncio
from hub_client import HubClient

client = HubClient(
    agent_id="my-agent",
    hub_url="http://localhost:3100",
    task: print(f"收到任务: {task['description']}"),
)
await client.start()

文件结构

agent-comm-hub/
├── SKILL.md                          # 本文件
├── README.md                         # 完整文档（GitHub 级别）
├── LICENSE                           # MIT 许可证
│
├── src/                              # Hub 服务器核心（TypeScript）
│   ├── server.ts                     # 主入口：Express + MCP + SSE
│   ├── stdio.ts                      # stdio 传输入口点（MCP v1.10+）
│   ├── db.ts                         # SQLite 持久化层（WAL 模式，30 表）
│   ├── tools.ts                      # MCP 工具注册入口（~30 行，调度 8 模块）
│   ├── tools/                        # 工具模块（Phase A 拆分）
│   │   ├── identity.ts               #   身份工具（6）
│   │   ├── message.ts                #   消息工具（5）
│   │   ├── memory.ts                 #   记忆工具（5）
│   │   ├── file.ts                   #   文件工具（3）
│   │   ├── evolution.ts              #   进化工具（12）
│   │   ├── orchestrator.ts           #   编排工具（16）
│   │   ├── security.ts               #   安全工具（4）
│   │   └── consumed.ts              #   消费工具（2）
│   ├── errors.ts                     # HubError 统一错误码（Phase D）
│   ├── utils.ts                      # 工具函数：mcpError/mcpFail + dedup + hash
│   ├── types.ts                      # 全局类型定义（Phase D）
│   ├── identity.ts                   # Agent 身份 + trust_score + resolveAgentId
│   ├── evolution.ts                  # 进化引擎（策略 + feedback）
│   ├── security.ts                   # RBAC + 权限矩阵
│   ├── sse.ts                        # SSE 连接管理
│   ├── logger.ts                     # 结构化 JSON 日志
│   ├── metrics.ts                    # Prometheus 指标
│   ├── dedup.ts                      # 消息去重（sha256）
│   └── tokenizer.ts                  # N-gram 分词器（FTS5）
│
├── client-sdk/                       # SDK（Python 68 方法 + TypeScript 35 方法）
│
├── deploy/                           # 部署配置
│   ├── docker-compose.yml            # Prometheus + Grafana 监控栈
│   ├── prometheus.yml                # Prometheus 采集配置
│   └── grafana/                      # Grafana 仪表盘 JSON
│
├── .github/workflows/                # CI/CD（Phase C）
│   └── ci.yml                        # typecheck + test + coverage
│
├── scripts/
│   ├── migrate_from_agent.js         # 历史数据迁移（from_agent 规范化）
│   └── migrate_evolution_db.py       # Evolution DB 迁移
│
├── tests/                            # 单元测试（vitest 100 用例）+ Python 集成测试
│
└── docs/
    ├── SETUP_GUIDE.md               # 详细配置指南
    ├── API_REFERENCE.md              # API 参考
    ├── evolution-engine-guide.md     # 进化引擎使用指南
    └── TROUBLESHOOTING.md            # 常见问题与踩坑经验

权限矩阵（4 级）

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

v2.4.2 更新要点

安全说明

🔐 鉴权与访问控制

• 所有 MCP 工具调用（除 register_agent 外）均需 Bearer Token 认证，Token 在注册时通过 register_agent 返回
• MCP HTTP 客户端必须在请求头中携带 Authorization: Bearer <token>
• 4 级 RBAC 权限矩阵严格隔离操作范围：public（仅注册） → member（通信/记忆） → group_admin（编排） → admin（系统管理）
• 建议：将 Hub 部署在受信网络内，不要暴露到公网；生产环境启用 CORS 白名单

⚠️ 高风险操作确认

以下操作建议要求人工确认（可通过 quality_gate 实现）：

• revoke_token / set_trust_score / set_agent_role（admin 级）
• approve_strategy / veto_strategy（策略审批）
• delete_memory / archive_data（数据删除）
• Task / Pipeline 中的破坏性操作

🛡️ 记忆与数据安全

• 建议默认使用 scope=private 存储记忆，仅必要时升级到 group/collective
• 所有记忆和策略操作记录在审计日志中（SHA-256 哈希链防篡改）
• Memory/Strategy 操作均关联 agent_id，支持溯源
• 建议：定期审查共享记忆和策略内容，使用 list_memories / list_strategies 审计

📋 安全配置清单

踩坑经验速查

环境变量

技术依赖

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）