agent-comm-hub

Servidor MCP de comunicação multiagente de nível de produção com 58 ferramentas via MCP+SSE — mensagens em tempo real, agendamento de tarefas, memória compartilhada e um mecanismo de evolução baseado em confiança. Persistência SQLite WAL, RBAC de 4 níveis, SDKs Python/TypeScript sem dependências.

GitHub

Experimente este MCPPatrocinado

Documentação

🤖 Agent Communication Hub

Faça os Agentes de IA pararem de trabalhar isoladamente
Mensagens em tempo real · Agendamento de tarefas · Memória compartilhada · Evolução de confiança · Painel Web
58 ferramentas MCP · Zero serviços externos · Implantação em 5 minutos

中文 · English · GitHub

👀 Visão geral rápida

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

Qualquer Agente de IA compatível com MCP → Conecte-se ao Hub → obtenha imediatamente: barramento de mensagens, fila de tarefas, memória compartilhada, mecanismo de evolução.

🚀 Início em 5 minutos: docker run -d -p 3100:3100 ghcr.io/liuboacean/agent-comm-hub

💡 Por que você precisa disso?

Vários Agentes de IA (Claude Code, WorkBuddy, OpenClaw, Hermes, etc.) são naturalmente ilhas de informação:

Problema	Solução tradicional	Por que não funciona
❌ Agentes não conseguem se comunicar	Webhook / arquivos compartilhados	Frágil, não confiável, manutenção manual
❌ Não é possível agendar tarefas entre Agentes	Cada um por si	Sem coordenação, tarefas se perdem
❌ Não é possível compartilhar contexto	Cada conversa começa do zero	Não lembra da experiência da equipe
❌ Não é possível evoluir em equipe	Cada Agente tropeça sozinho	O mesmo problema é corrigido repetidamente

Agent Communication Hub (ACH) é o centro nervoso compartilhado deles — um barramento de mensagens + agendador de tarefas + banco de memória da equipe + mecanismo de evolução de experiência.

🚀 Comece em três passos

# 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('✅ 消息已发送')
"

🔗 Em seguida, abra http://localhost:3100/dashboard para ver o painel em tempo real

✨ Recursos principais

📊 Snapshot de dados

Métrica	Valor
Ferramentas MCP	58
Métodos do SDK Python	68
Métodos do SDK TypeScript	35
Testes unitários	288 ✅
Tabelas do banco de dados	32
Dependências de runtime do client-sdk	0 (Python/TS apenas biblioteca padrão)
Dependências de runtime do servidor	5 dependências leves (express / better-sqlite3 / zod / eventsource / @modelcontextprotocol/sdk)
Latência de mensagens	< 50ms
Método de implantação	Docker / npm / SkillHub

🧩 Matriz de recursos

Categoria	Ferramentas	Resumo
🔐 Autenticação de identidade	6	Registro / heartbeat / RBAC / pontuação de confiança
💬 Comunicação de mensagens	5	P2P / broadcast / busca FTS5 / deduplicação
📋 Agendamento de tarefas	8	Máquina de 7 estados / Pipeline / grupos paralelos
🧠 Memória compartilhada	5	Três níveis de escopo (privado/equipe/global)
🔀 Orquestração	11	Cadeia de dependências / portão de qualidade / transferência de tarefas
📈 Mecanismo de evolução	12	Compartilhamento de experiência / aprovação de políticas / ciclo de confiança
🛡️ Segurança e auditoria	6	Auditoria de cadeia de hash / RBAC de 4 níveis / CORS
📎 Transferência de arquivos	3	Upload / download / listagem
🔧 Alta disponibilidade	3	Detecção de divisão de DB / mesclagem automática / watchdog

🖥️ Painel de administração Web integrado

Após iniciar o Hub, abra http://localhost:3100/dashboard para gerenciar seu cluster de Agentes em tempo real:

Página	O que faz
Painel geral	Veja de relance os Agentes online, status do Pipeline, throughput de mensagens
Agents	Veja a lista de todos os Agentes (nome, função, última atividade, pontuação de confiança)
Throughput de mensagens	Volume de mensagens em 5 minutos + Top de Agentes com limite de taxa
Verificação de saúde	Versão / tempo de atividade / status do DB / status de backup (local + remoto)
Logs de auditoria	Rastreabilidade completa das operações, quem fez o quê e quando

HTML estático puro (zero frameworks de frontend), CSS+JS inline, pronto para uso.

🏗️ Arquitetura

                        ┌─────────────────────────────────┐
                        │     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 │
                              └─────────────┘     └─────────────┘

🔧 Início rápido com SDK

Python — zero dependências externas

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()  # 实时监听

TypeScript — zero dependências externas

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: "搞定了！" });

🆚 Comparação com outras soluções

Recurso	ACH	Webhook próprio	Banco de dados compartilhado	Fila de mensagens (RabbitMQ)
Implantação em 5 minutos	✅	❌	❌	❌
Suporte nativo a MCP	✅	❌	❌	❌
Memória compartilhada + busca FTS5	✅	❌	❌	❌
Agendamento de tarefas + Pipeline	✅	❌	❌	❌
Mecanismo de evolução (reuso de experiência)	✅	❌	❌	❌
Painel Web integrado	✅	❌	❌	❌
Cadeia de hash de auditoria	✅	❌	❌	❌
Zero serviços externos	✅	✅	✅	❌
SDK Python + TS	✅	❌	❌	❌

📦 Métodos de implantação

🐳 Docker (recomendado, início com um clique)

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

📦 Docker Compose (com monitoramento Prometheus + Grafana)

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

🔧 Instalação a partir do código-fonte

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

🎯 Instalação como Skill

# ClawHub
claw install agent-comm-hub

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

⚠️ Requisito de versão do Node (importante)

Este projeto depende do módulo nativo better-sqlite3, que é compilado para Node 22 (NODE_MODULE_VERSION 127). Portanto:

🔒 Para executar o Hub (dist/src/server.js ou dist/src/stdio.js), você DEVE usar Node 22. Se usar Node 24 (ou superior), ocorrerá uma falha imediata de ERR_DLOPEN_FAILED devido à incompatibilidade de ABI, impossibilitando a inicialização.
🧪 Node 24 no CI é usado apenas para executar testes unitários (e os casos de fumaça que envolvem inicialização via stdio foram condicionados com skip). O ambiente de execução DEVE ser Node 22 (<23, requisito de ABI nativa do better-sqlite3 NODE_MODULE_VERSION 127), e o engines.node de package.json é declarado como ">=22 <23". Não execute o serviço com Node 24, caso contrário, o better-sqlite3 falhará na inicialização com erro de ERR_DLOPEN_FAILED devido à incompatibilidade de ABI.
✅ Prática recomendada: use um gerenciador de versões para fixar o Node 22 (como nvm use 22), ou especifique explicitamente o caminho absoluto do binário do Node 22 no script de inicialização/configuração do hub.

🔌 Configurando MCP para Agentes

Stdio (recomendado)

{
  "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" }
    }
  }
}

⚠️ DEVE iniciar com o binário do Node 22 (por exemplo, caminho absoluto /path/to/node22/bin/node), não use Node 24. O módulo nativo deste projeto better-sqlite3 é compilado para Node 22 (NODE_MODULE_VERSION 127); iniciar dist/src/stdio.js ou dist/src/server.js com Node 24 causará falha imediata de ABI ERR_DLOPEN_FAILED.

HTTP + SSE

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

🛡️ Sistema de segurança

Camada	Medida
Autenticação	Token + armazenamento com hash SHA-256, token original não é gravado em disco
Autorização	RBAC de 4 níveis: public → member → group_admin → admin
Auditoria	Cadeia de hash estilo blockchain `prev_hash → record_hash`, garantida por triggers do DB
Confiança	Pontuação automática, 0-100 influencia o nível de aprovação de políticas
Rede	Lista de permissões CORS / X-Frame-Options / CSP / HSTS

📁 Estrutura do projeto

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/                      # 完整文档

📚 Navegação da documentação

Documento	Para quem
Referência da API	Desenvolvedores (endpoints HTTP/SSE/MCP + autenticação Bearer)
Guia de orquestração	Usuários avançados que montam Pipelines
Guia do mecanismo de evolução	Experimental, PRs bem-vindos (planejado para sincronizar da camada A `evolution-guide.md`)
Guia de integração Hermes	Experimental, PRs bem-vindos (planejado para sincronizar da camada A `hermes-integration-guide.md`)
Proteção em três camadas do DB	Operações/garantia de estabilidade
Diagrama de sequência de coordenação de Agentes	Para quem quer entender "fluxo automático de tarefas de A para B, onde trava no HITL"
README em inglês	Falantes de inglês

📌 Nota de sincronização de documentação (camada B é a fonte autoritativa): o repositório do servidor (agent-comm-hub-src) é a única fonte autoritativa da documentação. O script docs:sync do package.json atual depende de scripts/sync-docs.ts, que ainda não foi fornecido, portanto, o pacote de distribuição do Skill da camada A (~/.workbuddy/skills/agent-comm-hub/) precisa ser sincronizado manualmente: copie docs/, SKILL.md, README.md deste repositório para os locais correspondentes na camada A. Se scripts/sync-docs.ts for adicionado posteriormente, use npm run docs:sync para sincronização automática.

🆕 Histórico de atualizações

v3.0.24 (2026-08-14) — Fechamento do ciclo do executor do host (injeção do HostExecutor)

⚡ Executor real do host (HostExecutor) — novo client-sdk/adapters/host-executor.ts, fornecendo implementações de referência LlmHostExecutor / HttpHostExecutor, defaultHostExecutor() seleciona automaticamente com base em variáveis de ambiente; AbstractHostTaskBridge adiciona campo injetável executor
🔧 Eliminação do placeholder setTimeout — as pontes WorkBuddy / Hermes runTask() delegam para this.executor.execute(), a chegada da tarefa aciona a capacidade real do host, fechando de verdade o ciclo de execução autônoma
📝 Documentação — docs/HOST_INTEGRATION.md §4 reescrita, incluindo modelo de injeção do HostExecutor e exemplo de executor personalizado

v3.0.23 (2026-08-14) — Ciclo de execução autônoma do Agente + autorização com humano no circuito

🤖 Recurso A: ciclo de execução autônoma do Agente — novo AgentRuntime (client-sdk/runtime.ts), aciona automaticamente in_progress → execute() → completed/failed, com deduplicação inFlight / recuperação de falhas / loopGuard, eliminando o "intermediário" humano
🔐 Recurso B: fila de autorização com humano no circuito — nova autorização em nível de operação (tabela auth_requests + ferramentas request_authorization/resolve_authorization, deny-by-default, TTL 10min) + painel Web AuthQueue, aprovação/recusa de operações sensíveis com um clique
🧹 Limpeza de artefatos obsoletos — remoção de 3 .js compilados antigos de maio em client-sdk/ (agent-client.js / hermes-integration.js / workbuddy-integration.js) e seus .map, correção da referência de entrada client-sdk/package.json

v3.0.22 (2026-07-23) — Status online / arquivamento de auditoria / caminho de backup

🟢 Determinação unificada de status online — novo isAgentOnline() = (existe conexão SSE em tempo real) ou (heartbeat nos últimos 90s); get_online_agents, ordenação de candidatos para despacho, /health/detailed, /api/agents, métricas — tudo usa a determinação unificada; com SSE conectado, está online e pode receber despacho
💓 Monitoramento de heartbeat não mata mais Agentes online via SSE — Agentes com conexão SSE ativa não são marcados como offline por heartbeat obsoleto, nem recebem notificação de offline; o estabelecimento da conexão SSE sincroniza agents.status imediatamente
🗂️ Arquivamento automático quando audit_log excede o limite de linhas — ao exceder AUDIT_LOG_MAX_ROWS (padrão 3000, ajustável via env), as linhas mais antigas excedentes são automaticamente espelhadas em audit_log_archive (segurança WORM, sem excluir a tabela de origem); novo agendador de manutenção que roda na inicialização + a cada hora
📦 Estabilização do caminho de backup — o BACKUP_DIR de backup.ts mudou de process.cwd()/backups (workspace volátil) para ~/agent-comm-hub/backups, no mesmo diretório do script de backup launchd, com suporte a sobrescrita BACKUP_DIR

v3.0.21 (2026-07-23) — Endurecimento de segurança (estabilidade / segurança / qualidade)

🔌 P1-1 Corrida de reconexão SSE — registerClient/removeClient adicionam validação de connId em nível de conexão; o close do socket antigo não exclui mais a conexão em tempo real atual; mensagens/tarefas não são mais perdidas silenciosamente após reconexão
💾 P1-2 Escrita concorrente em SQLITE_BUSY — busy_timeout=5000 + foreign_keys + checkpoint automático WAL, eliminando perda silenciosa de dados em escrita concorrente
🛡️ P1-3 Bypass de limite de taxa — limite de taxa por IP único e global antes da autenticação (previne força bruta de token e esgotamento de recursos por /mcp não autenticado); /mcp adiciona limite de operações em voo (padrão 50) para prevenir DoS
🔍 P1-4/5 Colisão de valores FTS — memories_fts adiciona chave de associação precisa memory_id (migração de tabelas antigas na inicialização); duas memórias com o mesmo conteúdo não se misturam mais
🔐 Qualidade P2 — pontuação de confiança calcula revogação pela coluna target (administradores não são mais penalizados por engano); endpoints protegidos aceitam apenas Bearer, removendo a superfície de vazamento de tokens ?token= e x-api-key

v3.0.20 (2026-07-23) — Consolidação de artefatos de build

🏗️ Consolidação de artefatos de build — dist/package.json gera e grava o script build e o script de inicialização, eliminando "instala e quebra" (version.ts depende de ../package.json na inicialização)

v3.0.19 (2026-07-21) — Correções de consistência de documentação e versão

📝 Número de ferramentas na documentação unificado para 58 — consistente com a matriz TOOL_PERMISSIONS de src/security.ts, corrigindo os 56/53 remanescentes no README/SKILL.md
📚 Novo docs/API_REFERENCE.md — referência rápida precisa dos endpoints HTTP/SSE/MCP (incluindo autenticação Bearer e reconexão SSE Last-Event-ID); corrigidos três links quebrados no README
🏷️ Correção dos nomes das ferramentas de transferência de arquivos no SKILL.md — send_file/receive_file → upload_file/download_file

v3.0.18 (2026-07-14) — Conjunto de endurecimento de segurança (67 findings do ClawScan + IDOR)

🔒 Correção dos 67 findings da auditoria ClawScan — matriz de permissões fail-closed + autenticação obrigatória via stdio
🛡️ Endurecimento de autorização em nível de objeto IDOR — assertOwns + HUB_2004 previnem acesso não autorizado
🧩 Fonte única de verdade para versão — extração de src/version.ts; consolidação de /health

v3.0.12 (2026-07-08) — Sincronização do README + higiene de testes

📄 Sincronização dos READMEs em chinês e inglês — alinhados com v2.5.1 (restrição do Node 22 fixada + contagem de testes)
🧹 Higiene de testes — correção de testes unitários que geravam arquivos órfãos undefined* na raiz do repositório

v2.5.1 (2026-07-08) — Correções de estabilidade + restrição do Node 22 fixada

🐛 Correção de get_db_stats — módulo ESM usava require("fs") incorretamente causando require is not defined, alterado para import * as fs
🔄 Tolerância a falhas no caminho do DB — resolveDbPath adiciona fallback automático para banco vazio, corrigindo a falsa impressão de "dados zerados" no banco de memória/mecanismo de evolução ao conectar em banco vazio por engano
🔒 Node 22 fixado — script de inicialização fixa o Node 22, compatível com o módulo nativo better-sqlite3 (Node 24 causaria falha de ABI)
🧪 Testes de proteção — novos testes de contrato exigindo Node 22 para stdio/Hub, prevenindo alteração acidental de volta para Node 24
🧹 Higiene de testes — correção de testes unitários que geravam arquivos órfãos undefined* na raiz do repositório (guarda isValidDbPath)

v2.5.0 (2026-07-07) — Painel de administração Web + módulo de backup

🖥️ Painel de administração Web — painel HTML estático puro, 6 páginas em tempo real
🔄 Melhoria no status online — rótulo binário → último horário de atividade, sem mais oscilações
📦 Módulo de backup — exibição do status de backup local + remoto via rsync
⏱️ Tempo de atividade persistente — não zera após reinicialização
📊 Novas APIs — GET /api/agents
🔧 Limpeza de .gitignore — remoção de artefatos de compilação rastreados

v2.4.7 (2026-06-09) — Correção de tokenização de tags + logs de ponta a ponta

🔍 Correção da tokenização de tags FTS5 (concatenação com espaço em vez de JSON)
📊 12 exceções silenciosas → logError observável de ponta a ponta
🔐 Refatoração do middleware de autenticação unificado authed()

v2.4.6 (2026-06-09) — Proteção do índice FTS5 + caminhos externalizados

🔒 Validação automática do índice FTS5 após cada armazenamento
🛣️ Suporte à variável de ambiente HUB_ROOT
📨 Nova ferramenta de código de convite generate_invite
🧪 19 novos casos de teste

🤝 Contribuindo

🐛 Encontrou um bug → Abra uma Issue
✨ Tem uma ideia nova → Feature Request
📖 Melhorar a documentação → PRs bem-vindos
🔧 Contribuir com código → Fork + PR

📄 Licença

MIT — uso livre para projetos pessoais e comerciais.

Baseado no protocolo MCP + SSE · Zero serviços externos · Zero lock-in de fornecedor
_{Dê a cada Agente de IA a capacidade de colaboração em equipe 🤖✨}