Pular para o conteúdo principal

Integração de IA no Elo Orgânico

A plataforma Elo Orgânico é construída desde o início para suportar fluxos de trabalho de engenharia nativos de IA. Em vez de tratar os agentes de IA como ferramentas de chat externas, o monorepo fornece uma infraestrutura conteinerizada que monta ambientes de código diretamente para os LLMs, conecta o hub de design aos agentes via Model Context Protocol (MCP) e garante a paridade do sistema entre os runtimes do host e dos containers.

1. Visão Geral e Arquitetura​

Nossa integração de IA compreende três pilares principais:

  1. Ecossistema MCP (tools/mcp): Expõe a base de código e ferramentas críticas do host (GitHub, navegador, documentação de dependências) para sessões ativas de LLM por meio de gateways Server-Sent Events (SSE).
  2. Terminais de Desenvolvedor Conteinerizados (tools/agents): Nós de CLI independentes executando Google Antigravity CLI (agy) e GitHub Copilot CLI em Docker. Eles se comunicam com o gateway MCP internamente.
  3. Automação do Design System (studio/penpot/aide): Uma instância self-hosted do Penpot acoplada ao serviço de IA aide. Isso permite automatizar componentes de design-to-code e a geração de ativos vetoriais.

2. Ecossistema Model Context Protocol (MCP)​

O ecossistema MCP fornece um gateway unificado e seguro que permite aos agentes de LLM executar ações e buscar contexto em tempo real.

Componentes Arquiteturais​

  • Fastify SSE Gateway (elo-mcp-gateway): Expõe endpoints HTTP internos que representam cada servidor MCP. Ele coordena o roteamento de rede na porta 3005 (host) e na porta 3000 (rede de bridge interna).
  • Adaptores SSE Zero-Dependency: Servidores padrão baseados em entrada/saída padrão (stdio) são envelopados em adaptadores Fastify customizados (sse-adapter.ts) para transmitir mensagens JSON-RPC bidirecionalmente através de HTTP Server-Sent Events.

Servidores Configurados​

  1. Servidor MCP do GitHub: Permite que os agentes coordenem branches, commits e pull requests diretamente do workspace.
  2. Servidor MCP do Context7: Consulta documentação externa em tempo real para dependências do projeto (Fastify 5, React 19) para garantir precisão.
  3. Servidor MCP do Browser (Playwright): Inicia uma instância de Chrome headless para executar auditorias de UI, capturar screenshots e testar frontends.
  4. Servidor MCP do Docker Hub: Valida tags do Docker upstream e atualiza manifestos de containers.
Configuração Detalhada

Para obter o registro completo de servidores, lógica de adaptadores Fastify SSE personalizados, roteamento de gateway e configurações técnicas, consulte o Guia de Configuração do Workspace Tools (Automação e MCP).

3. Agentes de IA Conteinerizados​

Para evitar instalações manuais complexas e corrupção de estado nos sistemas host dos desenvolvedores, executamos terminais de IA de longa duração dentro de containers Docker dedicados.

Paridade & Estratégia de Montagem​

Os containers de agentes montam arquivos cruciais de desenvolvimento por meio de bind-mounts para garantir a paridade de workspace sem vazar arquivos para diretórios globais do sistema host:

  • Diretório de Trabalho do Monorepo: Montado em /workspace para geração de código com latência zero.
  • Docker-out-of-Docker (DooD): Monta o socket /var/run/docker.sock dentro dos containers para compilar e testar imagens contra o daemon do host.
  • Persistência de Sessão: O mapeamento de ./copilot/data/ e ./antigravity/data/ persiste credenciais OAuth, evitando deslogar da sessão ao recriar containers.
  • Shared Agent Skills (Habilidades Compartilhadas): A pasta ./skills/ montada propaga regras de contexto (como code-expert e doc-expert) para os agentes.
Requisito de Sequência de Inicialização

A stack do MCP deve estar em execução antes que a dos agentes seja iniciada. Iniciar os agentes antes do MCP produzirá um erro de resolução de rede do Docker.

Instalação Detalhada

Para mapeamentos de volumes (bind mounts) de diretórios, instruções de persistência de credenciais por fluxo de dispositivo de autenticação e configurações de integração de tarefas do VS Code, consulte o Guia de Configuração do Workspace Tools (Automação e MCP).

4. Integração de IA com Penpot e Aide​

Nosso estúdio de design colaborativo self-hosted integra o serviço do assistente de IA Aide para sincronizar os ativos criativos da marca com a implementação de código.

Canal de Comunicação​

O Aide opera dentro da rede isolada penpot-net por meio de WebSockets bidirecionais. Ele utiliza a porta 4402 para fazer interface com a Plugin API do Penpot, permitindo que agentes de IA realizem auditorias de design e manipulação de camadas.

Protocolo de Sincronização Código-Design​

A geração de design-to-code por IA deve respeitar as seguintes regras:

  • Design Baseado em Tokens: Elementos de cores exportados devem referenciar propriedades CSS personalizadas definidas em src/tokens/.
  • Otimização de SVGs: SVGs vetoriais devem ser compilados no registro central de wrappers de componentes do Studio.
  • Reuso de Componentes: Priorize componentes React existentes em @elo-instance/web antes de gerar novos elementos visuais.
Instalação Detalhada

Para obter as etapas detalhadas de instalação, diagramas de arquitetura, listas de comandos e regras obrigatórias de reutilização de componentes e tokens, consulte o Guia de Configuração do Workspace Studio (Ativos Criativos e Penpot).