Skip to content

LeoYeAI/agent-master-skills / skills/agent-comm-hub

agent-comm-hub

Flagged

多智能体协同通信基础设施——基于 MCP+SSE 的实时消息、任务调度、记忆共享与进化引擎。支持 WorkBuddy、Hermes、QClaw 及任意 MCP 兼容 Agent 接入。53 个 MCP 工具、4 级权限、零外部依赖 Python SDK。触发词:agent通信、智能体通信、hub通信、多智能体、跨agent通信、任务调度、assign_task、send_message、hermes通信、workbuddy通信、agent hub、通信hub、mcp通信、记忆共享、进化引擎、策略共享、经验分享、共享记忆,共同进化

FileKindSize
.clawhub/origin.jsonconfig146 B
API_REFERENCE.mdmarkdown18.4 KB
HERMES-SETUP.mdmarkdown5.5 KB
README.mdmarkdown8.8 KB
SKILL.mdskill md16.4 KB
_meta.jsonconfig133 B
client-sdk/agent-client.d.tsscript11.6 KB
client-sdk/agent-client.jsscript28.6 KB
client-sdk/agent-client.tsscript29.8 KB
client-sdk/hermes-integration.d.tsscript785 B
client-sdk/hermes-integration.jsscript6.3 KB
client-sdk/hermes-integration.tsscript6.1 KB
client-sdk/hub_client.pyscript50.8 KB
client-sdk/workbuddy-integration.d.tsscript11 B
client-sdk/workbuddy-integration.jsscript4.3 KB
client-sdk/workbuddy-integration.tsscript4.2 KB
deploy/docker-compose.ymlconfig2.0 KB
deploy/grafana/dashboard.jsonconfig16.4 KB
deploy/grafana/provisioning/dashboards/dashboards.ymlconfig258 B
deploy/grafana/provisioning/datasources/prometheus.ymlconfig186 B
deploy/prometheus.ymlconfig408 B
docs/advanced-orchestration-guide.mdmarkdown11.8 KB
docs/evolution-engine-guide.mdmarkdown16.6 KB
docs/hermes-integration-guide.mdmarkdown22.3 KB
package-lock.jsonmanifest139.0 KB
package.jsonmanifest861 B
scripts/hub_task_runner.pyscript6.0 KB
scripts/hub_watcher.pyscript13.9 KB
scripts/install.shscript549 B
scripts/migrate_evolution_db.pyscript6.5 KB
scripts/migrate_from_agent.jsscript2.5 KB
scripts/wb_task_trigger.pyscript2.2 KB
src/db.d.tsscript3.7 KB
src/db.jsscript34.0 KB
src/db.tsscript37.4 KB
src/dedup.d.tsscript2.4 KB
src/dedup.jsscript8.5 KB
src/dedup.tsscript8.7 KB
src/errors.tsscript3.4 KB
src/evolution.d.tsscript6.6 KB
src/evolution.jsscript26.4 KB
src/evolution.tsscript31.0 KB
src/identity.d.tsscript3.4 KB
src/identity.jsscript15.9 KB
src/identity.tsscript17.1 KB
src/logger.d.tsscript1.1 KB
src/logger.jsscript2.8 KB
src/logger.tsscript3.5 KB
src/memory.d.tsscript2.1 KB
src/memory.jsscript13.0 KB
src/memory.tsscript14.3 KB
src/metrics.d.tsscript1.8 KB
src/metrics.jsscript8.4 KB
src/metrics.tsscript9.1 KB
src/orchestrator.d.tsscript6.1 KB
src/orchestrator.jsscript30.4 KB
src/orchestrator.tsscript33.4 KB
src/repo/interfaces.d.tsscript3.6 KB
src/repo/interfaces.jsscript49 B
src/repo/interfaces.tsscript4.2 KB
src/repo/sqlite-impl.d.tsscript225 B
src/repo/sqlite-impl.jsscript7.7 KB
src/repo/sqlite-impl.tsscript8.8 KB
src/repo/types.d.tsscript1021 B
src/repo/types.jsscript116 B
src/repo/types.tsscript1.6 KB
src/security.d.tsscript3.7 KB
src/security.jsscript15.0 KB
src/security.tsscript16.4 KB
src/server.d.tsscript11 B
src/server.jsscript24.7 KB
src/server.tsscript24.7 KB
src/sse.d.tsscript1.6 KB
src/sse.jsscript3.3 KB
src/sse.tsscript3.6 KB
src/stdio.d.tsscript11 B
src/stdio.jsscript1.7 KB
src/stdio.tsscript1.6 KB
src/tokenizer.d.tsscript1.3 KB
src/tokenizer.jsscript3.4 KB
src/tokenizer.tsscript3.2 KB
src/tools.d.tsscript474 B
src/tools.jsscript1.1 KB
src/tools.tsscript1.3 KB
src/tools/consumed.d.tsscript361 B
src/tools/consumed.jsscript5.5 KB
src/tools/consumed.tsscript5.3 KB
src/tools/evolution.d.tsscript660 B
src/tools/evolution.jsscript19.3 KB
src/tools/evolution.tsscript17.6 KB
src/tools/file.d.tsscript348 B
src/tools/file.jsscript7.1 KB
src/tools/file.tsscript6.5 KB
src/tools/identity.d.tsscript438 B
src/tools/identity.jsscript9.8 KB
src/tools/identity.tsscript9.3 KB
src/tools/memory.d.tsscript410 B
src/tools/memory.jsscript11.9 KB
src/tools/memory.tsscript10.8 KB
src/tools/message.d.tsscript467 B
src/tools/message.jsscript17.2 KB
src/tools/message.tsscript15.8 KB
src/tools/orchestrator.d.tsscript746 B
src/tools/orchestrator.jsscript27.8 KB
src/tools/orchestrator.tsscript24.3 KB
src/tools/security.d.tsscript386 B
src/tools/security.jsscript9.0 KB
src/tools/security.tsscript7.8 KB
src/types.tsscript5.9 KB
src/utils.d.tsscript421 B
src/utils.jsscript1.3 KB
src/utils.tsscript3.0 KB
tsconfig.jsonconfig337 B
vitest.config.tsscript1.2 KB
---
name: agent-comm-hub
description: "多智能体协同通信基础设施——基于 MCP+SSE 的实时消息、任务调度、记忆共享与进化引擎。支持 WorkBuddy、Hermes、QClaw 及任意 MCP 兼容 Agent 接入。53 个 MCP 工具、4 级权限、零外部依赖 Python SDK。触发词:agent通信、智能体通信、hub通信、多智能体、跨agent通信、任务调度、assign_task、send_message、hermes通信、workbuddy通信、agent hub、通信hub、mcp通信、记忆共享、进化引擎、策略共享、经验分享、共享记忆,共同进化"
version: 2.4.2
category: autonomous-ai-agents
---

# 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)
```

**三层协议**:

| 层 | 协议 | 用途 | 延迟 |
|----|------|------|------|
| MCP 工具层 | stdio / HTTP POST + JSON-RPC | 结构化操作(发消息、分配任务、查状态) | <50ms |
| SSE 推送层 | Server-Sent Events | 实时事件通知(新消息、新任务、策略审批) | <50ms |
| REST API 层 | HTTP GET/PATCH | 轻量查询(运维监控、自动化脚本) | <50ms |

## 核心能力

### 53 个 MCP 工具(v2.4.2)

#### Identity 身份 (6)

| 工具 | 功能 |
|------|------|
| `register_agent` | 注册新 Agent,获取 agent_id 和 API token(public,无需认证) |
| `heartbeat` | Agent 心跳上报,维持在线状态,每 3 次连续心跳 trust_score +1 |
| `query_agents` | 查询 Agent 列表,支持状态/角色筛选 |
| `revoke_token` | 吊销指定 Agent 的 API token(admin) |
| `set_trust_score` | 调整 Agent 信任分数(admin) |
| `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)

| 工具 | 功能 |
|------|------|
| `upload_file` | 上传文件附件(Base64,10MB 限制),关联到消息 |
| `download_file` | 下载附件,返回 Base64 编码内容 |
| `list_attachments` | 列出附件,支持按消息/Agent 筛选 |

#### Task 任务 (3)

| 工具 | 功能 |
|------|------|
| `assign_task` | 创建并分配任务,支持上下文传递 |
| `update_task_status` | 更新任务状态(inbox→assigned→in_progress→completed/failed) |
| `get_task_status` | 查询任务详情,含依赖、Pipeline、Handoff 信息 |

#### Memory 记忆 (5)

| 工具 | 功能 |
|------|------|
| `store_memory` | 存储记忆,支持 private/team/global 可见范围 |
| `recall_memory` | 语义搜索记忆 |
| `list_memories` | 列出记忆,支持范围和标签筛选 |
| `delete_memory` | 删除记忆 |
| `search_memories` | FTS5 全文搜索记忆,支持多关键词和短语搜索 |

#### Evolution 进化 (12)

| 工具 | 功能 |
|------|------|
| `share_experience` | 分享经验(无需审批,直接发布) |
| `propose_strategy` | 提议策略(需 admin 审批) |
| `propose_strategy_tiered` | 提议策略(4 级自动分级审批:auto/peer/admin/super) |
| `list_strategies` | 列出策略,支持标签和类型筛选 |
| `search_strategies` | 全文搜索策略内容 |
| `apply_strategy` | 采纳策略,自动创建 feedback 占位,7 天无反馈自动降分 |
| `feedback_strategy` | 为已采纳策略提供反馈(positive/negative/neutral) |
| `approve_strategy` | 审批通过策略(admin) |
| `get_evolution_status` | 查看进化状态仪表盘 |
| `score_applied_strategies` | 自动评分已采纳策略:7 天前 neutral 反馈自动降为 negative(admin) |
| `check_veto_window` | 检查策略否决窗口状态 |
| `veto_strategy` | 在窗口期内撤回策略(admin) |

#### Orchestration 进阶编排 (16)

| 工具 | 功能 |
|------|------|
| `add_dependency` | 添加任务依赖关系(DFS 环检测) |
| `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) |
| `set_agent_role` | 任命/撤销 Agent 角色,含 group_admin(admin) |
| `recalculate_trust_scores` | 手动触发信任分重算(admin) |
| `create_pipeline` | 创建 Pipeline 流水线 |
| `get_pipeline` | 查询 Pipeline 详情 |
| `list_pipelines` | 列出 Pipeline |
| `add_task_to_pipeline` | 向 Pipeline 添加任务 |

#### Security 运维安全 (4)

| 工具 | 功能 |
|------|------|
| `get_db_stats` | 数据库统计信息(表行数、大小、Agent 数等)(admin) |
| `archive_data` | 数据归档:将过期消息/审计日志移入归档表(admin) |
| (其余 2 个内部工具) | 权限验证与安全控制 |

#### Consume 消费水位线 (2)

| 工具 | 功能 |
|------|------|
| `mark_consumed` | 标记任务/消息为已消费,防止重复处理 |
| `check_consumed` | 查询资源是否已被消费 |

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

### 运维 REST API

| 端点 | 方法 | 功能 |
|------|------|------|
| `/health` | GET | 健康检查(返回版本、内存、DB、大小、活跃 SSE 连接数) |
| `/metrics` | GET | Prometheus 兼容指标(mcp_calls_total、message_delivery_total 等) |

### 任务状态机

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

## 快速开始

### 1. 启动 Hub 服务器

```bash
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)**

```json
{
  "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)**

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

**方式 C:SDK 接入**

TypeScript Agent:
```typescript
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(零外部依赖):
```python
import asyncio
from hub_client import HubClient

client = HubClient(
    agent_id="my-agent",
    hub_url="http://localhost:3100",
    on_task_assigned=lambda 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 级)

| 级别 | 说明 | 特殊权限 |
|------|------|----------|
| **public** | 无需认证 | register_agent |
| **member** | 已注册 Agent | 所有 Message/Task/Memory/File/Orchestration/Pipeline 工具 |
| **group_admin** | 并行组管理员 | 任务编排 + Pipeline 工具(不含 Memory/Evolution) |
| **admin** | 系统管理员 | revoke_token / set_trust_score / approve_strategy / veto_strategy / set_agent_role / recalculate_trust_scores / score_applied_strategies / get_db_stats / archive_data |

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

## v2.4.2 更新要点

| Phase | 内容 | 变更 |
|-------|------|------|
| **A** | tools.ts 拆分 | 2687 行 → 8 模块 + 30 行入口 + utils.ts |
| **B** | 单元测试 | 100 用例,security >= 70% / dedup branches≥60, functions≥70 / utils 100% |
| **C** | CI/CD | GitHub Actions:typecheck + test + coverage 3 Jobs |
| **D** | 类型安全 | any 归零 + HubError 统一错误码 + MCP 返回格式标准化 |
| **E** | 安全强化 | 新增安全说明章节,明确鉴权/人工确认/数据安全最佳实践 |

## 安全说明

### 🔐 鉴权与访问控制

- **所有 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_AUTH_TOKEN` | 必填 | stdio 模式认证 token,长度 ≥ 32 字符 |
| `CORS_ORIGINS` | 明确指定域名 | 不要留空或设为 `*`(生产环境) |
| `DB_PATH` | 非默认路径 | 生产环境使用独立数据目录 |
| trust_score | 首次验证后调整 | 新 Agent 初始值 50,验证后上调 |
| 心跳超时 | 30 秒 | 超 5 次未心跳自动离线 |

## 踩坑经验速查

| # | 场景 | 要点 |
|---|------|------|
| 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(),不要手动构造错误响应 |

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | 3100 | Hub 监听端口(HTTP 模式) |
| `HUB_URL` | http://localhost:3100 | Hub 地址(客户端用) |
| `HUB_AUTH_TOKEN` | — | stdio 模式认证 token(必填) |
| `DB_PATH` | ./comm_hub.db | SQLite 数据库路径 |
| `LOG_LEVEL` | info | 日志级别:debug / info / warn / error |
| `CORS_ORIGINS` | (空) | CORS 白名单(逗号分隔),空=拒绝所有跨域 |

## 技术依赖

**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)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall