Skip to main content

Integração de IA em tupynambalucas.dev

A plataforma tupynambalucas.dev foi construída desde a base para dar suporte a workflows de engenharia nativos de IA. Em vez de tratar agentes de IA como ferramentas de chat externas, o monorepo fornece uma infraestrutura conteinerizada que monta ambientes de código diretamente em LLMs, conecta o hub de design aos agentes via Model Context Protocol (MCP) e garante paridade de sistema entre os runtimes do host e do container.

1. Visão Geral e Arquitetura​

Para uma visão de alto nível de como ferramentas de IA e sistemas de design se encaixam na estrutura global do monorepo, consulte a Visão Geral da Arquitetura Técnica.

Nossa integração de IA baseia-se especificamente em três pilares principais:

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

2. Ecossistema do Model Context Protocol (MCP)​

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

Componentes Arquiteturais​

  • Gateway de Ingress Fastify (agentgateway): Expõe endpoints HTTP internos representando cada servidor MCP. Ele coordena o roteamento entre redes na porta 8080 (host e rede de bridge interna).
  • Adaptadores SSE Sem Dependências: Servidores de entrada/saída padrão (stdio) são encapsulados em adaptadores Fastify personalizados (sse-adapter.ts) para transmitir mensagens JSON-RPC bidirecionalmente via HTTP Server-Sent Events.

Servidores Configurados​

  1. Servidor MCP do GitHub: Permite que os agentes coordenem branches, commits e pull requests diretamente a partir do workspace.
  2. Servidor MCP 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 Navegador (Playwright): Inicia um navegador Chrome sem interface gráfica para executar auditorias de UI, capturar screenshots e testar frontends.
  4. Servidor MCP do Docker Hub: Valida tags upstream do Docker e atualiza manifestos de containers.
Configuração Detalhada

Para registros completos de servidores, lógica personalizada de adaptadores Fastify SSE, roteamento de gateway e configurações técnicas, consulte o Guia de Configuração do Workspace do Cortex.

3. Agentes de IA Conteinerizados​

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

Paridade e Estratégia de Montagem​

Os containers dos agentes fazem a montagem de bind (bind-mount) de arquivos cruciais do desenvolvedor para garantir paridade do workspace sem vazar arquivos para os 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): O socket /var/run/docker.sock foi montado dentro dos containers para compilar e testar imagens em relação ao daemon do host. Em ambientes Podman, o socket do Podman do host (tipicamente /run/user/1000/podman/podman.sock para execução sem privilégios de root, ou /var/run/podman/podman.sock) é montado ou emulado para fornecer acesso de CLI compatível com o Docker.
  • Persistência de Sessão: O mapeamento de ./copilot/data/ e ./antigravity/data/ persiste credenciais OAuth, evitando deslogues de sessão em reconstruções de containers.
  • Skills Compartilhadas de Agentes: A pasta ./skills/ montada via bind propaga regras de contexto (como code-expert e docusaurus-kb-expert) para os agentes.
Requisito de Sequência de Inicialização

O gateway e a stack MCP devem estar em execução antes que a stack de agentes seja iniciada. Iniciar os agentes antes do gateway produzirá um erro de resolução de rede do Docker.

Instalação Detalhada

Para mapeamentos de montagem de bind de diretórios, instruções de persistência do 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 do Cortex.

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

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

Bridge de Comunicação​

O Aide opera dentro da rede isolada penpot-net por meio de WebSockets bidirecionais. Ele usa a porta 4402 para fazer interface com a API de Plugins 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 para código por IA deve respeitar as seguintes regras:

  • Design com Foco em Tokens: Elementos de cores exportados devem fazer referência a propriedades CSS personalizadas definidas em src/tokens/.
  • Otimização de SVG: SVGs vetoriais devem ser compilados no registro central de wrapper de componentes do Studio.
  • Reutilização de Componentes: Priorize componentes React existentes em @repo/hub/web antes de gerar novos elementos visuais.
Instalação Detalhada

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