🤖 Protocolo Gitea Swarm (PGS): Coordenação de Multi-Agentes em Ambiente Multi-VPS

Este documento estabelece o protocolo de comunicação padrão, obrigatório e imutável para todos os Agentes de Inteligência Artificial (IAs) que atuarem no gerenciamento, desenvolvimento ou manutenção da infraestrutura multi-tenant (múltiplos projetos) distribuída em múltiplos servidores.

Como a arquitetura adota segurança Zero-Trust de movimentação lateral (impedindo que agentes em uma VPS acessem outras máquinas via SSH automático), o Gitea atua como o Orquestrador de Estado Assíncrono do enxame de agentes.

🧭 REGRA MESTRE DE ROTEAMENTO (DISPATCHER PROTOCOL)

ATENÇÃO AGENTE DE IA: Esta infraestrutura hospeda múltiplos projetos independentes (Multi-Tenant). Antes de tomar qualquer ação, você deve ler a arquitetura e as regras específicas do projeto solicitado.

Se a tarefa envolver um projeto específico (ex: Mercado, ScoreOdonto), você DEVE:
- Ler a Wiki do repositório para entender a arquitetura e regras de negócio específicas.
- Ler a Issue para entender o problema ou tarefa atual.
- Consultar a pasta global/ para protocolos de segurança e deploy.
Jamais presuma que a arquitetura de um projeto se aplica ao outro. Mantenha os contextos estritamente isolados via Wiki.

⚠️ Regras Cruciais de Governança e Codificação (Obrigatório)

Comunicação Prévia e Autorização: Qualquer alteração na estrutura, infraestrutura ou lógica core do sistema deve ser obrigatoriamente comunicada de antemão. As mudanças somente devem ser aplicadas após a autorização explícita do Administrador.
Idioma Obrigatório: Todas as informações da codificação, incluindo comentários no código, commits, documentações e discussões de desenvolvimento devem ser feitas obrigatoriamente em português.

📋 Regras de Engajamento para Agentes

Sempre que um agente for invocado para resolver uma Issue ou realizar uma implementação, ele deve obrigatoriamente seguir os 4 passos de ciclo de vida abaixo:

graph TD
    A[1. Autocognição: Onde estou?] --> B[2. Leitura de Histórico na Issue]
    B --> C[3. Execução Local na VPS Atual]
    C --> D[4. Comentário de Hand-off e Status]

🔍 Passo 1: Autocognição e Sincronização (Onde estou?)

Toda IA, ao iniciar sua execução, deve identificar em qual máquina física ou container está rodando (ex: hostname ou IP da VPN 10.99.0.x).

IMEDIATAMENTE APÓS, o agente DEVE OBRIGATORIAMENTE executar um git pull no diretório de instruções (/home/deploy/instrucoes/) e verificar a versão ativa da Doutrina Swarm registrada no Gitea Wiki (ex: buscando a versão v1.x.x ativa indicada na página Home.md).

Important

Versionamento de Wiki Obrigatório: Trabalhar com documentação local desatualizada ou desalinhada com a versão da Wiki é um risco crítico de SecOps. A verificação do versionamento garante que o agente siga rigorosamente as diretrizes, firewalls, logs e políticas da release atualizada do Swarm.

Exemplo: "Identificado que estou na VPS 3. Realizado git pull em /instrucoes/ e verificado alinhamento com a Doutrina Swarm v1.0.3 na Wiki para garantir contexto atualizado."

📖 Passo 2: Leitura do Histórico da Issue

Antes de fazer qualquer alteração no código ou nos servidores, o agente deve ler a Issue no Gitea de baixo para cima, analisando o histórico de comentários de outros agentes para entender o que já foi feito e onde o processo parou.

🛠️ Passo 3: Execução Local Estrita

O agente deve realizar apenas as alterações correspondentes à VPS onde ele está ativamente rodando. Ele nunca deve tentar forçar conexões ou invasões a outras VPSs que não estejam documentadas ou autorizadas.

💬 Passo 4: Comentário de Hand-off (O Passe de Bastão)

Ao concluir sua tarefa local, o agente não deve simplesmente fechar a tarefa, caso ela dependa de ações em outros servidores. Ele deve postar um comentário estruturado seguindo o modelo abaixo:

📝 Modelo Padrão de Comentário de Hand-off ( PGS )

O comentário de encerramento do agente na Issue deve conter obrigatoriamente os seguintes blocos:

### 🖥️ [VPS ATUAL]: [Nome da VPS, ex: VPS 3 (Data Appliance)]
* **O que foi realizado localmente:** [Lista clara de arquivos modificados, bancos criados ou serviços configurados].
* **Impacto na Rede:** [Portas abertas na VPN, novas credenciais disponíveis, ex: 'Banco criado com a senha X'].

### ⏭️ [AÇÃO REQUERIDA NA VPS DESTINO]: [Nome da VPS, ex: VPS 1 (App Server)]
* **Instruções passo a passo para o próximo agente:** [Instruções exatas do que deve ser feito na outra VPS, códigos YAML, bash ou edições de arquivo].
* **Como se conectará à VPS atual:** [Mostrar a URL de conexão, ex: 'DATABASE_URL=postgresql://...'].

### 🚦 [STATUS]: [Escolha uma das tags abaixo]
* `[Aguardando Agente na VPS X]` - Quando o trabalho local acabou e agora outro agente precisa agir na VPS X.
* `[Aguardando Homologação do Usuário]` - Quando todo o cluster foi configurado e o Humano precisa testar e aprovar.

🎯 Exemplo de Aplicação Real (Issue #2 - newwhats)

Agente A (na VPS 3 - Banco):
- Cria o banco newwhats e configura DragonflyDB.
- Comenta na Issue:
  
  [VPS 3 - Data Appliance]: Banco newwhats restaurado com sucesso. [REQUERIDO NA VPS 1]: Próximo agente, edite o docker-compose.yml da aplicação apontando para 10.99.0.3 usando a senha X. Comente quando terminar. [STATUS]: [Aguardando Agente na VPS 1]
Agente B (na VPS 1 - Frontend):
- Inicia na VPS 1, lê o comentário acima, altera o docker-compose.yml local e sobe o container.
- Comenta na Issue:
  
  [VPS 1 - App Server]: docker-compose.yml atualizado e container reiniciado. Conexão com VPS 3 validada e healthy. [STATUS]: [Aguardando Homologação do Usuário]

Este protocolo garante consistência, segurança máxima e clareza absoluta na comunicação humana e de inteligência artificial em nosso ecossistema.

6.1 KiB Raw Blame History