Rui
105 lines
6.9 KiB
Markdown
105 lines
6.9 KiB
Markdown
# 🤖 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.
|
|
|
|
1. 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.
|
|
2. **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)
|
|
|
|
1. **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**.
|
|
2. **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:
|
|
|
|
```mermaid
|
|
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 sincronizar e carregar seu contexto seguindo a **Relação de Prioridade de Acesso a Instruções**:
|
|
|
|
1. 🚀 **[PRIORIDADE MÁXIMA] Injeção Direta em Memória (API REST Gitea)**:
|
|
A IA deve prioritariamente requisitar suas instruções e a Doutrina atualizada via API REST do Gitea, mantendo todo o conteúdo estritamente na memória RAM da execução. Isso impede o vazamento de chaves e garante que o agente nunca trabalhe com instruções locais alteradas ou desatualizadas no disco.
|
|
2. 📁 **[FALLBACK 1] Disco Local (Filesystem)**:
|
|
Caso o Gitea esteja fora do ar ou inacessível, o agente deve ler o diretório local `/home/deploy/instrucoes/` (após efetuar um `git pull` local) como contingência temporária.
|
|
3. 🔐 **[TRANSPORTE E DEPLOY] Autenticação via Chaves SSH**:
|
|
Para qualquer operação de escrita, clonagem ou atualização remota de repositórios, a IA deve utilizar a chave SSH privada do usuário `deploy` (`~/.ssh/id_ed25519`), eliminando o uso de senhas ou chaves em texto plano.
|
|
|
|
> [!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**. Contexto carregado prioritariamente via **Injeção em Memória (API REST)** e alinhado com a **Doutrina Swarm v1.0.4** na Wiki."
|
|
|
|
### 📖 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:
|
|
|
|
```markdown
|
|
### 🖥️ [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)
|
|
|
|
1. **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]`
|
|
2. **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.*
|