Escrever ficheiros do Aggrega
A autoria em Aggrega é um ciclo curto e repetível. Seja qual for a entidade que se escreve — o Aggregate de um programador, o Component de um arquiteto, uma Recipe de operações ou a Release de um operador —, os mesmos cinco passos levam de um ficheiro em branco a um ficheiro validado:
- Escolher a entidade que o seu papel detém.
- Aprender a sua forma a partir do JSON Schema e da página de referência.
- Partir de um esqueleto em vez de um ficheiro em branco.
- Preencher os campos que o seu papel detém, deixando os restantes aos respetivos donos.
- Validar e depois compilar.
Esta página percorre o ciclo uma vez, tanto para uma pessoa que escreve à mão como para um assistente de IA que escreve através do servidor Model Context Protocol. Os dois caminhos são o mesmo ciclo sobre as mesmas superfícies de referência. Ambos precisam do binário aggrega: Instalar o binário instala-o com um único comando.
1. Escolher a entidade que o seu papel detém
O Aggrega separa a autoria em quatro papéis colaborativos — a intenção do programador, o catálogo da plataforma, as receitas de infraestrutura e a ligação da implementação. Cada papel detém normalmente um conjunto específico de tipos de entidade. Quem já conhece o seu papel pode saltar para a entidade de que precisa; caso contrário, convém ler Personas para os quatro papéis e Entidades por papel para o mapa completo de tipos por papel.
A separação é uma orientação, não uma regra que o compilador imponha. Um autor individual é livre de assumir todos os papéis e escrever todas as entidades de uma só vez; o compilador aceita qualquer padrão de autoria que passe a validação de esquema. Os papéis existem para manter as preocupações claras, não para restringir o que se pode escrever.
2. Aprender a sua forma
Cada tipo de entidade tem um JSON Schema canónico e uma página de referência campo a campo. Convém ler ambos antes de escrever:
- O esquema é a estrutura exata: campos obrigatórios, valores permitidos e aninhamento. Na linha de comandos,
aggrega get-schema <kind>imprime-o;aggrega get-schema --listnomeia todos os tipos que se podem pedir. Um assistente lê os mesmos bytes a partir do recursoschema://<kind>. Ver a referência deaggrega get-schema. - A página de referência explica o que cada campo significa e como os campos se relacionam. As páginas de entidades estão em
language-reference/entities/— por exemplo component ou aggregate. Um assistente lê a mesma página a partir do recursolangref://entities/<kind>.
O esquema diz o que é estruturalmente válido; a referência diz o que é sensato. O esquema serve para evitar a rejeição no momento da validação, e a referência para escrever algo que faça o que se pretende.
3. Partir de um esqueleto
Partir de um esqueleto é mais rápido e menos propenso a erros do que um ficheiro em branco. Um assistente ligado ao servidor MCP chama a ferramenta scaffold com um tipo e um nome para obter um ponto de partida mínimo que contém todos os campos que o tipo exige, com um marcador de posição onde quer que ainda falte um valor. Ao escrever à mão, aggrega scaffold <kind> <name> imprime o mesmo ponto de partida na saída padrão, pelo que deve ser redirecionado para um ficheiro; ou copie o exemplo trabalhado mais próximo e reduza-o ao necessário.
Em qualquer dos casos, o esqueleto já contém os campos de nível superior obrigatórios (apiVersion, kind, metadata.name) na forma correta, pelo que a atenção vai para os campos que o seu papel detém e não para código repetitivo.
4. Preencher os campos que o seu papel detém
Preencha apenas os pilares pelos quais o seu papel é responsável e deixe os outros aos respetivos donos. Um programador fornece a intenção da aplicação e os valores; um arquiteto declara o contrato — os valores que um programador pode fornecer, os outputs que um componente fornece, os sockets que expõe; as operações mapeiam esse contrato para um provider específico sem alterar a superfície voltada para o programador; um operador liga a implementação. Entidades por papel indica que pilares pertencem a que papel, para cada tipo.
Manter cada valor no pilar que o seu dono controla é o que permite que a mesma intenção do programador vise infraestruturas diferentes em ambientes diferentes sem que o ficheiro do programador mude. É essa a razão de a superfície de autoria estar dividida.
Manter a descrição em poucos parágrafos curtos. O metadata.description de uma entidade é a prosa que um leitor encontra antes de a escolher: é publicado com a entidade como a sua descrição pesquisável, e o aggrega search compara uma consulta com ela. Deve ser escrita para esse momento, em parágrafos curtos — num bloco dobrado description: >, uma linha em branco inicia um novo — dizendo o que a entidade é, como um leitor a usa, onde é realizada e o que não faz. Um limite que um leitor tenha de conhecer antes de escolher a entidade também pertence aí, dito de forma breve. Tudo o resto — porque é que uma predefinição é a que é, como uma definição se comporta num destino, o que um valor significa em cada realização — vai para comentários YAML ao lado do campo ou bloco que explica, onde a pessoa que trabalha com esse campo os lerá. Nada no compilador limita o comprimento de uma descrição nem age sobre o que ela diz, pelo que mantê-la curta é para benefício do leitor.
5. Validar e depois compilar
Verifique o ficheiro antes de depender dele:
- Um assistente chama a ferramenta
validate, que reporta inline os erros de esquema e de referência para que possa corrigir o rascunho antes de o devolver. - À mão,
aggrega validate <file>verifica um único ficheiro de Component, Feature, Recipe, FeatureRecipe, Workload ou Plugin, eaggrega validate --release <release>verifica tudo o que uma Release alcança, incluindo o seu Aggregate e o seu Manifest.aggrega lintaplica as regras de disciplina de publicação a uma entidade de catálogo, eaggrega inspectresolve e mostra o que o compilador vê. Quando toda a topologia estiver pronta,aggrega pull --release <release>resolve as suas dependências e escreve o seu lockfile, eaggrega build --release <release>compila depois a Release em artefactos por fronteira — um build falhado nomeia exatamente o que corrigir.
Validar cedo é mais barato do que um build falhado tarde. Escrever, validar, corrigir e só depois compilar.
Autoria com um assistente de IA
O comando aggrega mcp executa um servidor Model Context Protocol que transforma qualquer cliente compatível com MCP num assistente de autoria que conhece o Aggrega. Uma vez ligado, o assistente pode:
- Assumir um papel através dos prompts de autoria incorporados — um por persona (programador, arquiteto, operações) mais um template focado por entidade. Cada prompt enquadra o papel e aponta o assistente para o esquema, a página de referência e este guia, para que as suas sugestões fiquem dentro dos pilares que o papel detém.
- Ler a referência através de recursos:
schema://<kind>para o JSON Schema de um tipo,langref://<path>para qualquer página de referência eauthoring://<topic>para este guia. - Agir sobre o workspace através de ferramentas:
scaffoldpara iniciar um esqueleto correto,validatepara verificar um rascunho,describepara inspecionar uma entidade de catálogo eget-schemapara obter um esquema por tipo.
Tudo o que o assistente lê é servido a partir da sua máquina: os esquemas estão integrados no binário, e as páginas do guia e da referência vêm do pacote de documentação mantido na cache da sua máquina, que o servidor obtém do registo quando arranca e não encontra aí nenhuma cópia. Ler uma página, criar um esqueleto e validar não acedem à rede; onde o pacote não pode ser obtido, os esquemas continuam a ser servidos e as páginas não. Para ligar um cliente, siga Ligar o servidor MCP; O que o seu assistente pode fazer com o Aggrega cobre o resto daquilo a que chega. Para o comando em si, consulte a referência do aggrega mcp.
Para onde ir a seguir
- Personas — compreender os quatro papéis antes de escolher uma entidade.
- Entidades por papel — o mapa completo de tipos por papel.
- Instalação — instalar o binário; Ligar o servidor MCP liga o seu assistente.
- Configurar o Aggrega com o seu assistente de IA — um único prompt que faz o seu assistente instalar e ligar o Aggrega sozinho.
- Visão geral da CLI — todos os subcomandos do
aggrega.