agent-comm-hub

让 AI Agent 不再各自为战
实时消息 · 任务调度 · 共享记忆 · 信任进化 · Web 仪表盘
58 个 MCP 工具 · 零外部服务 · 5 分钟部署

graph LR A[Claude Code] <--> H((ACH Hub)) B[WorkBuddy] <--> H C[OpenClaw] <--> H D[自定义 Agent] <--> H H --> DB[(SQLite)] H --> Web[Web 仪表盘] style H fill:#4f46e5,color:#fff style Web fill:#7c3aed,color:#fff

任何 MCP 兼容的 AI Agent→ 连接 Hub → 立即获得：消息总线、任务队列、共享记忆、进化引擎。

🚀5 分钟启动：docker run -d -p 3100:3100 ghcr.io/liuboacean/agent-comm-hub

多个 AI Agent（Claude Code、WorkBuddy、OpenClaw、Hermes 等）天然是信息孤岛：

Agent Communication Hub（ACH）是它们的共享神经中枢——一条消息总线 + 任务调度器 + 团队记忆库 + 经验进化引擎。

# 0. 安装 Python SDK（可选） pip install agent-comm-hub # 1. 启动 Hub（一行命令） docker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub # 2. 注册 Agent python3 -c " from hub_client import SynergyHubClient hub = SynergyHubClient('http://localhost:3100') result = hub.register(invite_code='INVITE-001', name='my-agent') hub.set_token(result['api_token']) print(f'✅ Agent 注册成功，ID: {result[\"agent_id\"]}') " # 3. 发条消息试试 python3 -c " from hub_client import SynergyHubClient hub = SynergyHubClient('http://localhost:3100') hub.set_token('your-token') hub.send_message(to='other-agent', content='收到，任务完成。') print('✅ 消息已发送') "

🔗 然后打开http://localhost:3100/dashboard查看实时仪表盘

启动 Hub 后打开 http://localhost:3100/dashboard，即可实时管理你的Agent 集群：

┌─────────────────────────────────┐ │ Agent Communication Hub │ │ localhost:3100 │ │ │ ┌─────────┐ SSE/MCP │ ┌──────┐ ┌──────┐ ┌────────┐ │ SSE/MCP ┌─────────┐ │ Claude │◄─────────►│ │Auth │ │Msg │ │Memory │ │◄─────────►│WorkBuddy│ │ Code │ │ │RBAC │ │Bus │ │FTS5 │ │ │ │ └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘ │ ┌──────┐ ┌──────┐ ┌────────┐ │ ┌─────────┐ │ │Task │ │Orch │ │Evol │ │ ┌─────────┐ │OpenClaw │◄─────────►│ │Sched │ │Str │ │Engine │ │◄─────────►│ Hermes │ └─────────┘ │ └──────┘ └──────┘ └────────┘ │ └─────────┘ └────────────┬────────────────────┘ │ ┌──────▼──────┐ ┌─────────────┐ │ SQLite │ │ Web Panel │ │ (WAL 模式) │ │ /dashboard │ └─────────────┘ └─────────────┘

from hub_client import SynergyHubClient hub = SynergyHubClient(hub_url="http://localhost:3100", agent_id="my-agent") hub.set_token("your-api-token") hub.send_message(to="other-agent", content="任务完成，交接。") # 发消息 hub.store_memory(content="用户偏好 JSON", scope="collective") # 存记忆 task = hub.create_task(title="评审 PR #42", assignee="claude-code") # 派任务 hub.share_experience(title="修复方案", content="...", category="debug") # 分享经验 hub.on_message = lambda msg: print(f"收到: {msg}") hub.connect_sse() # 实时监听

import { AgentClient } from "./client-sdk/agent-client.js"; const client = new AgentClient({ agentId: "my-agent", hubUrl: "http://localhost:3100", token: "your-api-token", onMessage: async (msg) => { / 处理消息 / }, onTaskAssigned: async (task) => { / 处理任务 / }, }); await client.start(); await client.sendMessage({ to: "other-agent", content: "搞定了！" });

docker run -d -p 3100:3100 --name ach ghcr.io/liuboacean/agent-comm-hub

cd deploy/ docker compose up -d # Hub: http://localhost:3100 | Grafana: http://localhost:3000 (admin/admin)

git clone https://github.com/liuboacean/agent-comm-hub.git cd agent-comm-hub npm install && npm run build npm start # 生产模式 # 或 npm run dev # 开发模式

# ClawHub claw install agent-comm-hub # SkillHub（30+ 平台） skillhub install agent-comm-hub

{ "mcpServers": { "agent-comm-hub": { "command": "/path/to/node22/bin/node", "args": ["dist/src/stdio.js"], "env": { "HUB_AUTH_TOKEN": "your-key", "DB_PATH": "./comm_hub.db" } } } }

⚠️必须用 Node 22 二进制启动（例如绝对路径/path/to/node22/bin/node），不要用 Node 24。本项目原生模块better-sqlite3是按 Node 22（NODE_MODULE_VERSION 127）编译的，使用 Node 24 启动dist/src/stdio.js或dist/src/server.js会立即ERR_DLOPEN_FAILEDABI 崩溃。

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

agent-comm-hub/ ├── web/dist/index.html # Web 管理面板（零前端框架） ├── src/ # 核心源码（TypeScript） │ ├── server.ts # Express + SSE + MCP 入口 │ ├── db.ts # SQLite WAL 数据库 │ ├── backup.ts # 自动备份模块 │ ├── identity.ts # 注册 / 心跳 / RBAC │ ├── memory.ts # 三级记忆 + FTS5 搜索 │ ├── orchestrator.ts # 依赖链 / Pipeline │ ├── evolution.ts # 经验共享 / 策略审批 │ └── security.ts # Token / 审计 / CORS ├── client-sdk/ │ ├── hub_client.py # Python SDK（68 方法，零依赖） │ └── agent-client.ts # TypeScript SDK（35 方法） ├── deploy/ # Docker Compose + 监控 ├── tests/ # 288 个测试 └── docs/ # 完整文档

📌文档同步说明（B 层为权威源）：服务端仓库（agent-comm-hub-src）是文档的单一权威来源。当前package.json的docs:sync脚本依赖scripts/sync-docs.ts，该文件尚未提供，因此 A 层 Skill 分发包（~/.workbuddy/skills/agent-comm-hub/）需手动同步：将本仓库的docs/、SKILL.md、README.md复制到 A 层对应位置。后续若补充scripts/sync-docs.ts，可用npm run docs:sync自动同步。

- ⚡真实宿主执行器（HostExecutor）— 新增client-sdk/adapters/host-executor.ts，提供LlmHostExecutor/HttpHostExecutor参考实现，defaultHostExecutor()按环境变量自动选择；AbstractHostTaskBridge新增可注入executor字段
- 🔧消灭 setTimeout 占位— WorkBuddy / Hermes 桥runTask()委托this.executor.execute()，任务到达即触发宿主真实能力，自主执行闭环真正打通
- 📝文档—docs/HOST_INTEGRATION.md§4 重写，含 HostExecutor 注入模型与自定义执行器示例

- 🤖Feature A：Agent 自主执行闭环— 新增AgentRuntime（client-sdk/runtime.ts），自动驱动in_progress → execute() → completed/failed，含 inFlight 去重 / 崩溃恢复 / loopGuard，消灭人工「传话」
- 🔐Feature B：人在环授权队列— 新增操作级授权（auth_requests表 +request_authorization/resolve_authorization工具，deny-by-default，TTL 10min）+ WebAuthQueue面板，敏感操作一键批准/拒绝
- 🧹清理陈旧产物— 移除client-sdk/下 3 个 5 月旧编译.js（agent-client.js/hermes-integration.js/workbuddy-integration.js）及其.map，修正client-sdk/package.json入口引用

- 🟢在线状态统一判定— 新增isAgentOnline()=（存在 SSE 实时连接）或（心跳 90s 内）；get_online_agents、派单候选排序、/health/detailed、/api/agents、指标全部改用统一判定，SSE 连着即在线、可派单
- 💓心跳监控不再误杀 SSE 在线 Agent— 仍有 SSE 连接的 Agent 不因心跳陈旧误标离线、不再广播离线通知；SSE 连接建立即同步agents.status
- 🗂️audit_log行数上限自动归档— 超AUDIT_LOG_MAX_ROWS（默认 3000，env 可调）自动将最旧溢出行镜像到audit_log_archive（WORM 安全，不删源表）；新增启动即跑 + 每小时维护调度器
- 📦备份路径稳定化—backup.ts的BACKUP_DIR由process.cwd()/backups（易失 workspace）改为~/agent-comm-hub/backups，与 launchd 备份脚本同目录，支持BACKUP_DIR覆盖

- 🔌P1-1 SSE 重连竞态—registerClient/removeClient增连接级connId校验，旧 socket 的close不再误删当前实时连接，重连后消息/任务不再静默丢失
- 💾P1-2 并发写SQLITE_BUSY—busy_timeout=5000+foreign_keys+ WAL 自动检查点，消除并发写静默丢数据
- 🛡️P1-3 限流绕过— 认证前置单 IP / 全局限流（防令牌爆破与未认证/mcp耗尽资源）；/mcp增并发在途上限（默认 50）防 DoS
- 🔍P1-4/5 FTS 值碰撞—memories_fts增memory_id精确关联键（启动迁移旧表），内容相同的两条记忆不再互相串台
- 🔐P2 质量— 信任分按target列计吊销（管理员不再误扣）；受保护端点仅接受Bearer，移除?token=与x-api-key令牌泄漏面

- 🏗️构建产物固化—dist/package.json生成写入build脚本与启动脚本，消除「安装即崩溃」（version.ts启动依赖../package.json）

- 📝文档工具数统一为 58— 与src/security.ts的TOOL_PERMISSIONS矩阵一致，修正 README/SKILL.md 残留的 56/53
- 📚新建docs/API_REFERENCE.md— 准确的 HTTP/SSE/MCP 端点速查（含 Bearer 鉴权与 SSELast-Event-ID断线重连）；修正 README 三处死链
- 🏷️SKILL.md 文件传输工具名更正—send_file/receive_file→upload_file/download_file

- 🔒修复 ClawScan 审计 67 findings— fail-closed 权限矩阵 + stdio 强制认证
- 🛡️IDOR 对象级授权加固—assertOwns+HUB_2004防越权访问
- 🧩版本单一真相源— 抽离src/version.ts；/health收敛

- 📄同步中英文 README— 对齐 v2.5.1（Node 22 约束锁定 + 测试计数）
- 🧹测试卫生— 修复 unit 测试在仓库根生成undefined游离文件

- 🐛get_db_stats修复— ESM 模块误用require("fs")导致require is not defined，改import as fs
- 🔄DB 路径容错—resolveDbPath新增空库自动回退，修复误连空库导致的记忆库/进化引擎"数据归零"假象
- 🔒Node 22 锁定— 启动脚本固定 Node 22，匹配 better-sqlite3 原生模块（Node 24 会 ABI 崩溃）
- 🧪防护测试— 新增 stdio/Hub 必须用 Node 22 的契约测试，防止被误改回 Node 24
- 🧹测试卫生— 修复 unit 测试在仓库根生成undefined游离文件（isValidDbPath守卫）

A bridge server connecting Model Context Protocol (MCP) with Agent-to-Agent (A2A) protocol.