Collusion
Motor de orquestração de soluções técnicas de colaboração multiobjeto. Três Agentes de IA propõem em paralelo, realizam revisão cruzada, convergem a viabilidade e votam para gerar o Top 3 de soluções.
Documentação
Collusion (共谋)
Um mecanismo MCP que, na fase de design de soluções, previne over-engineering e perda de intenção por meio da colaboração entre múltiplos agentes. Em avaliação cega com projetos reais, venceu o grupo de controle por 16:1 (5 domínios × 5 dimensões).
English | Início Rápido | Roadmap | Guia de Contribuição
Por que o Collusion?
Você já passou por situações como:
- A solução proposta pela IA parece perfeita, mas ao implementar, descobre-se que viola restrições essenciais?
- A descrição do requisito omite etapas críticas (como segurança, conformidade), e a IA nunca pergunta proativamente?
- Existe apenas uma solução, sem alternativas, e você não sabe se há um caminho técnico melhor?
O Collusion foi criado exatamente para esses problemas.
Não é outra ferramenta de "projetar primeiro, codificar depois". Modos Plan, Spec e Superpowers também conseguem "projetar primeiro". O Collusion faz o que eles não fazem: na fase de design da solução, permite que múltiplos agentes de IA proponham em paralelo a partir de diferentes perspectivas profissionais, revisem uns aos outros e imponham convergência.
Mecanismo Central
| Fase | Mecanismo | Descrição |
|---|---|---|
| 🔍 Consenso de Etapas | Revisão Multi-Agente | Identifica e preenche automaticamente etapas ausentes (como segurança, conformidade, migração) |
| 📝 Propostas em Paralelo | 3 Porta-vozes de Objetos | As perspectivas de valor de negócio, arquitetura técnica e segurança/conformidade geram soluções de forma independente |
| 🔄 Revisão Cruzada | Edição Alternada | Cada agente revisa a solução dos outros; cada alteração é marcada |
| 🛑 Convergência de Viabilidade | Redutor de Velocidade Obrigatório | O porta-voz do objeto de engenharia reduz o over-engineering |
| 📊 Integração do Owner | Duas Rodadas de Refinamento | Rascunho inicial com modelo Flash + revisão final com modelo Strong |
| 🗳️ Votação e Pontuação | Pontuação em 5 Dimensões | Correção, completude, viabilidade, inovação, alinhamento com o negócio |
| 🏆 Saída Top 3 | Soluções Diferenciadas | Acompanhadas de justificativa da pontuação e indicação de complexidade |
Comparação em Avaliação Cega com Projetos Reais
Tarefa de teste: Projetar uma solução técnica para uma plataforma de blog open source (exigência: deploy com um único comando Docker, sem depender de serviços em nuvem pagos).
Grupo de controle: Solução gerada por uma única chamada de LLM (1 tarefa em cada um dos 5 domínios, total de 25 dimensões comparadas).
| Dimensão | Collusion venceu | Controle venceu | Empate |
|---|---|---|---|
| Completude | 5 | 0 | 0 |
| Inovação | 5 | 0 | 0 |
| Alinhamento com o negócio | 4 | 0 | 1 |
| Viabilidade | 2 | 1 | 2 |
| Correção | 0 | 0 | 5 |
| Total | 16 | 1 | 8 |
Especificamente na tarefa da plataforma de blog, a comparação entre a solução do Collusion e a do Superpowers:
| Item de Comparação | Collusion | Superpowers |
|---|---|---|
| Forma de deploy | Binário único Go+SQLite | Next.js + 5 contêineres |
| Dependências externas | 0 (SQLite+Bleve integrados) | PostgreSQL + Redis + Meilisearch |
| Filosofia de arquitetura | Monolito + modular, minimalista | Microsserviços, complexidade empresarial |
| Performance de primeira tela | HTML estático puro, sem bloqueio de JS | Hydration do Next.js com tela branca |
| Barreira para self-hosting | Um comando Docker | Requer orquestração de vários serviços |
| Completude da solução | 11 módulos técnicos, incluindo definições SQL | Conceitos de arquitetura claros, poucos detalhes de implementação |
| Experiência do editor | Edição Markdown básica | Design detalhado do CodeMirror 6 |
📝 Nota importante: Neste teste, o Collusion operou em modo totalmente automático. A filosofia de design do Superpowers é colaboração manual em múltiplas rodadas; com supervisão humana próxima, a qualidade de sua solução pode ser maior. Esta comparação visa demonstrar a diferença entre os dois paradigmas, não uma competição abrangente de desempenho.
Comentário principal do avaliador:
"A solução usa deploy minimalista com Docker de comando único e SQLite, arquitetura pragmática e desempenho adequado; a solução comparada depende de muitos serviços, é complexa e tem alta barreira de deploy."
Capacidades por Cenário
Complemento de Requisitos
Quando os requisitos do usuário omitem etapas críticas, o Collusion as identifica e preenche proativamente.
Exemplo: O usuário informa "Preciso de uma solução de seleção de framework front-end; o time usa principalmente React. Só me importo com biblioteca de componentes e stack tecnológico."
O mecanismo complementou automaticamente na fase de consenso de etapas:
| Etapa Original | Complemento do Mecanismo |
|---|---|
| Comparação de bibliotecas de componentes | → Estratégia de segurança front-end (XSS/CSP/varredura de vulnerabilidades de dependências) |
| Recomendação de combinação de stack | → Design da API back-end e da camada de dados |
| Configuração de engenharia (build/empacotamento) | → Experiência do desenvolvedor e guia de integração |
| → Solução de deploy e CI/CD |
Outro exemplo: O usuário informa "Quero criar uma plataforma de ferramentas para desenvolvedores", e o mecanismo complementou automaticamente:
- Experiência do desenvolvedor e guia de integração
- Migração de dados e importação/exportação
- Modelagem de ameaças e avaliação de riscos de segurança
Guardião de Restrições
Quando a solução se desvia das restrições centrais, a fase de convergência de viabilidade corrige o rumo de forma obrigatória.
Exemplo: A restrição da tarefa da plataforma de blog era "não depender de serviços em nuvem pagos, deploy com um único comando Docker". Uma solução propôs uma arquitetura complexa com PostgreSQL + Redis + vários microsserviços; na fase de convergência de viabilidade, o porta-voz do objeto de engenharia a classificou como "over-engineering", a pontuação de complexidade foi forçada para abaixo do limite e a solução ficou em terceiro lugar.
Início Rápido
Pré-requisitos
- Python 3.10+
- Chave de API DeepSeek (registro gratuito)
Instalação
# 方式一：pip 安装（推荐）
pip install collusion-mcp
# 方式二：从源码安装
git clone https://github.com/anthropics/Collusion.git
cd Collusion
pip install -e .
# 配置 API Key（三选一）
# 方式一：环境变量（推荐）
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
# 方式二：复制示例配置并填入 Key
cp config.example.json config.json
# 编辑 config.json，填入 api_key
# 方式三：零配置（Reasonix 用户无需额外配置，自动读取已保存的 Key）
Integração com Cliente MCP
Claude Code — adicione em .mcp.json:
{
"mcpServers": {
"brainstorm": {
"command": "python",
"args": ["src/mcp_server.py", "--stdio"],
"cwd": "/path/to/Collusion"
}
}
}
Trae Solo / outros clientes MCP — inicie o modo SSE:
python src/mcp_server.py --sse --port 8020
Em seguida, adicione http://localhost:8020/sse na configuração do MCP.
Exemplo de Uso
# 在 Claude Code 中直接调用
请用 brainstorm_orchestrate 工具设计一个高并发短链接服务
# 调整 Agent 数量
brainstorm_orchestrate(task="设计一个RESTful API", agents=1) # 快速模式
brainstorm_orchestrate(task="设计一个开源博客平台", agents=3) # 完整模式
# 查询进度
brainstorm_status(task_id="task_xxxxxxxxxxxx")
# 获取结果
brainstorm_result(task_id="task_xxxxxxxxxxxx")
Referência de Custo
| Número de Agentes | Tokens por Tarefa | Custo por Tarefa |
|---|---|---|
| 1 | ~15.000 | ~¥0,03 |
| 2 | ~35.000 | ~¥0,07 |
| 3 | ~50.000-65.000 | ~¥0,08-0,15 |
Com base nos preços da API DeepSeek; o custo real varia com a complexidade da tarefa. A meta da v0.5.0 é reduzir para ¥0,05-0,10.
Limitações Atuais
- Suporta apenas a API DeepSeek: usa um adaptador DeepSeek na base; outros provedores de LLM ainda não são suportados (DeepSeek é compatível com o protocolo OpenAI; contribuições da comunidade para outros adaptadores são bem-vindas)
- Gera soluções apenas do zero: ainda não suporta aprimoramento incremental com base em soluções existentes (já está no roadmap de médio prazo)
- Papéis de agente fixos: atualmente há 3 papéis integrados (valor de negócio, arquitetura técnica, segurança/conformidade); papéis personalizados estão em desenvolvimento
- Suporta apenas transporte stdio: o modo de transporte HTTP/SSE está em desenvolvimento
- Formato de saída é Markdown: relatórios visuais em HTML estão em desenvolvimento (incluindo gráfico radar, diagrama de arquitetura, cartões de marcação de risco)
Roadmap
Consulte ROADMAP.md para detalhes.
Planos de curto prazo (v0.4.0 - v0.5.0):
- Relatórios visuais em HTML (gráfico radar + diagrama de arquitetura Mermaid + cartões de risco)
- Blueprint JSON executável (integração direta com writing-plans)
- Ciclo de feedback do usuário (modificações incrementais + revisão multi-perspectiva)
- Controle de custos (¥0,05-0,10/tarefa)
Planos de médio prazo (v0.6.0 - v0.8.0):
- Modo de aprimoramento incremental (revisão multi-perspectiva e otimização com base em soluções existentes)
- Agendamento dinâmico de agentes
- Expansão de papéis de agentes
- Deploy remoto HTTP + SSE
Troubleshooting
Chave de API não configurada
O Collusion detecta automaticamente as variáveis de ambiente, com a seguinte prioridade: DEEPSEEK_API_KEY → OPENAI_API_KEY → LLM_API_KEY → configuração do Reasonix.
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
Usuários do Reasonix têm ~/.reasonix/config.json lido automaticamente, sem configuração adicional.
Falha ao iniciar o serviço MCP
# 确认 mcp 包已安装
python -c "import mcp; print(mcp.__version__)"
# 检查端口占用 (Windows)
netstat -ano | findstr :8020
# 检查端口占用 (macOS/Linux)
lsof -i :8020
O merge do blackboard retorna ranking vazio
Verifique o status antes do merge:
collusion_blackboard_status(task_id="bb_xxxx")
Confirme se todos os agentes exibem _done. Se um agente estiver travado em proposal_start, aguarde 2-3 minutos antes do merge. Se exibir _error, verifique o campo error no status.
Licença
Licença MIT — consulte LICENSE
Contribuição
Issues, PRs e Discussions são bem-vindos! Consulte CONTRIBUTING.md
English
What is Collusion?
A multi-agent MCP engine for technical design orchestration. Give it a task, and three AI agents — each representing a different perspective (Business Value, Technical Architecture, Security & Compliance) — independently generate proposals, cross-review each other's work, enforce feasibility checks, and produce a ranked Top 3.
Collusion beat single-shot LLM generation 16:1 (8 ties) in blind evaluations across 5 domains, 25 total dimensions.
Key differentiators
- Gap detection: Automatically identifies and fills missing components (security, deployment, migration)
- Multi-perspective review: Three agents critique each other's work, not just generate
- Feasibility brake: Engineering agent enforces real-world constraints and simplification
- Ranked Top 3: Multi-dimensional scoring with reasoning, not just one answer
Quick Start
pip install -r requirements.txt
export DEEPSEEK_API_KEY="your-api-key"
# Then configure your MCP client with src/mcp_server.py --stdio
Note: Collusion currently only supports DeepSeek API. DeepSeek uses an OpenAI-compatible protocol, so other compatible providers may work with a custom adapter. Community contributions for additional LLM backends are welcome.
Roadmap
See ROADMAP.md for the full public roadmap covering v0.4.0 through v1.0.0+.