Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Extensibilidade

Extensibilidade do ecossistema e salvaguardas do compilador

1. A interface universal WebAssembly (Wasm)

Para garantir simetria arquitetural em todo o ecossistema, o Aggrega utiliza um contrato de execução padronizado que se aplica uniformemente a cada socket Wasm no pipeline do compilador.

A interface YAML para invocar qualquer plugin se baseia em duas palavras-chave escolhidas explicitamente: function e with.

  • function: O Aggrega incorpora um runtime Wasm (o toolkit Extism sobre o motor Wazero), executando Wasm diretamente na memória, de modo que nenhum processo do sistema operacional é iniciado. function nomeia o export que o host Go invoca: uma função explicitamente exportada pelo módulo Wasm.
  • with: as entradas próprias do plugin, mantidas separadas dos values do desenvolvedor e dos parameters que uma Release atende. A palavra-chave segue a convenção do GitHub Actions (with:); quando um plugin declara um JSON Schema para suas entradas, o host as valida contra ele antes da execução.

Os tipos de Plugins Wasm: Esta interface universal de function e with oferece suporte a cada socket programável do compilador:

Tipo de PluginOnde é executadoFinalidadeSaída esperada
Provider (provider)Renderização (geração)Traduz a IR final em memória em arquivos físicos serializados como strings para um formato de destino (Helm, Terraform, Compose).Um array de arquivos serializados como strings.
Etapa de pipeline de FeatureRecipe (pipeline-step)O pipeline de plugins de uma Recipe ou de uma FeatureRecipeEtapas sequenciais que buscam segredos ou injetam sidecars em ASTs base.patches RFC 6902 sobre o conjunto de documentos indexado por chave, além de side_effects (emitir um novo documento ou arquivo), diagnostics e outputs que uma etapa posterior pode ler. A entrada da etapa carrega esse conjunto de documentos indexado por chave e a entrada with renderizada da etapa.
Governança (governance)Antes da expansão de anotações, construção da topologia, análise estática ou estágio de renderizaçãoDesempenha os papéis de governança do pipeline de build. Antes da expansão de anotações, injeta anotações nos componentes resolvidos e, na construção da topologia, aplica automaticamente aos nós labels de conformidade ou de ambiente (um operador habilita um explicitamente para um ou outro papel). Na análise estática ou no estágio de renderização, atua como Loud Guardrail: avalia arestas, caminhos e labels do grafo — ou os artefatos renderizados — em relação aos limites de segurança. É o papel ao qual está anexado, e não o seu tipo, que define o que ele pode emitir.Antes da expansão de anotações, injeções de anotações. Na construção da topologia, um array de JSONPatches direcionados a metadata.labels. Na análise estática ou no estágio de renderização, veredictos de severidade halt, warn ou info (uma política Rego os reúne em deny, warn e audit); um halt interrompe o build.
Linter (linter)Fora de bandaVerificações opcionais de FinOps ou de higiene (por exemplo, estimativa de custos de nuvem a partir de .infra) e disciplina no momento da publicação.Strings de aviso ou interrupções fatais.
Extensão da CLI (cli)Runtime (aggrega <command>)Um comando de nível superior pronto para uso, fornecido por um plugin assinado e executado em sandbox, sem nenhum código Go por comando no host.Saída padrão e erro padrão transmitidos em streaming, além do código de saída do convidado.
Parser (parser)Sob demanda, onde quer que um formato externo seja lidoTransforma texto-fonte externo (HCL, TOML, YAML, JSON, JSON com comentários) em uma árvore JSON canônica.tree mais diagnostics, e spans de origem opcionais.
Importer (importer)Sob demanda, fora de qualquer build (aggrega import, o editor e a ferramenta import do assistente)Transforma uma fonte externa de infraestrutura ou de definição de agentes (Langflow, Flowise, n8n, uma configuração MCP, uma aplicação Compose, uma aplicação Dify, os agentes declarados de um projeto CrewAI, a configuração de uma aplicação LangGraph, as configurações de agentes de uma aplicação Google ADK, um agente declarativo do Agent Framework) em rascunhos de arquivos de autoria do Aggrega, anunciando os formatos que trata como capabilities import:<format>.Rascunhos de entidades Aggregate / Component / Release, ou referências aos Components do catálogo que reutiliza, as decisões de mapeamento por trás deles, diagnósticos e os arquivos de scaffold a serem gravados.

O runtime host: uma sandbox que nega capabilities. O Aggrega incorpora o host Wasm como o toolkit Extism em execução sobre o motor Wazero; o binário host continua sendo Go puro, sem dependência de toolchain nativa, de modo que aggrega faz compilação cruzada sem problemas. Cada socket é executado atrás de um firewall de pureza AOT: o host se recusa a conceder a um plugin qualquer capability de acesso em tempo de execução — nada de rede, nada de sistema de arquivos, nada de relógio de parede, nada de ambiente, nada de E/S padrão —, de modo que uma chamada que usaria uma delas falha, e um plugin que importa de uma superfície do host que o host não fornece é rejeitado no carregamento. Um plugin que não consegue acessar a rede nem ler o relógio não pode quebrar a garantia ahead-of-time do compilador de que a mesma entrada produz a mesma saída. Runtimes de linguagem que precisam de alguns imports de inicialização inofensivos são executados com uma configuração desses imports que nega capabilities: o host fixa o relógio observável, fornece entropia real, descarta a E/S padrão e não concede acesso a sistema de arquivos, argumentos ou ambiente — de modo que um plugin não consegue alcançar nenhuma capability do host que varie entre builds. A entropia é deliberadamente deixada real em vez de fixada: fixá-la estabilizaria a semente de hash interna e a ordem de iteração de mapas do runtime de uma linguagem convidada, e assim esconderia um plugin cuja própria saída não é reproduzível, em vez de deixar isso aparecer como saída divergente. Um plugin cujo resultado depende de entropia tem um problema de determinismo no nível da autoria, e esta configuração foi construída para revelá-lo em vez de mascará-lo.

Desenvolvendo para o host: o PDK. Os autores de plugins não escrevem à mão a ABI de memória Wasm. O Aggrega fornece um Plugin Development Kit em três linguagens — Go, Rust e TypeScript —, wrappers leves que apresentam a entrada e a saída tipadas de cada socket para que o autor escreva funções comuns. A interface function / with acima é o que um Aggregate ou uma FeatureRecipe usa para invocar um plugin; o PDK é aquilo sobre o qual um autor de plugins desenvolve.

Onde cada socket é executado. Todo socket é executado por meio do mesmo host: o publishing linter em aggrega lint; os papéis de governança, os providers de renderização e as etapas de pipeline de Recipe e FeatureRecipe durante aggrega build; os parsers onde quer que um formato externo seja lido; os importadores em aggrega import; e os plugins de CLI como comandos de nível superior. Consulte Status da linguagem para ver a prontidão de cada socket.

Quais plugins são fixados e quais o seu ambiente escolhe. O Aggrega divide os plugins conforme alterem ou não a saída que você entrega. Plugins que moldam a saída — os providers de renderização, os plugins de governança anexados em um papel de transformação (label-transform, annotation-transform) e as etapas de pipeline de FeatureRecipe e Recipe — são fixados no lockfile da release quando você executa aggrega pull, e reproduzidos byte a byte em aggrega build e aggrega serve somente a partir desse lockfile. Dois tipos não são fixados, porque um build lê cada um do mesmo lugar todas as vezes: um provider de renderização servido de dentro do binário do compilador, e um provider ou etapa de pipeline cuja entidade Plugin é escrita em um dos seus próprios diretórios de catálogo. Para mudar qual plugin que molda a saída se aplica, você faz o pull novamente; uma alteração na configuração do seu workspace após um pull não altera a saída de um build até o próximo pull. Plugins de controle — política e lint — julgam um build sem alterar seus bytes, por isso são armazenados em cache no pull (para que um build ainda possa executá-los offline; um que o binário do compilador carrega, ou um escrito no seu próprio diretório de catálogo, é lido de lá em vez disso), mas não são fixados: qual controle é executado é escolhido pelo seu ambiente no momento do build, de modo que uma divisão dev permissivo / CI rigoroso é uma escolha de configuração comum, e não um novo pull, e trocar de controle nunca altera a saída que um build aprovado emite. Plugins que atuam apenas sobre a entrada de autoria, como importadores e extensões da CLI, não moldam nenhuma saída de build e não são fixados nem fazem parte do conjunto em cache do build.

2. Pipelines de Plugin de FeatureRecipe

As FeatureRecipes vinculam intenções operacionais abstratas (como o acoplamento de um proxy de segurança ou a injeção de um sidecar) a pipelines versionados de plugins WebAssembly (Wasm). Ops declara o que uma Feature precisa em um alvo de provider concreto; o compilador executa o pipeline declarado sobre o grafo IR plano.

Esse vínculo traz três consequências para o ecossistema:

  • Evolução desacoplada. O vocabulário de infraestrutura cresce por meio de plugins Wasm externos, sem exigir uma nova versão do núcleo do compilador Aggrega. Novos providers, novos sidecars e novas integrações de segurança são distribuídos como binários Wasm independentes sobre a ABI Wasm estável.
  • Versionamento semântico. As FeatureRecipes referenciam plugins Wasm por versão — exata (:1.0.0) ou um intervalo com circunflexo (:^1.0.0, a versão mais alta compatível com ela). Com o intervalo com circunflexo, Ops trava uma versão principal enquanto incorpora suas versões secundárias e de correção sempre que o lockfile é resolvido novamente com aggrega pull --upgrade.
  • Descarregamento da complexidade. A geração de CRDs específicas de fornecedor ou a renderização complexa (objetos de policy específicos de fornecedor, recursos de roteamento nativos do provider) ficam em plugins Wasm puros que operam sobre o grafo IR plano, em vez de passar por declarações de schema ou lógica de template dentro das definições de componentes.

Encadeamento de pipelines — separando responsabilidades entre plugins. Um pipeline de FeatureRecipe pode encadear vários plugins Wasm em sequência, cada um recebendo do compilador o mesmo contexto de nó IR. O padrão usual divide a responsabilidade para que um único plugin não carregue ao mesmo tempo a intenção semântica de uma funcionalidade e o mecanismo físico de interceptação de tráfego de um ambiente de destino específico.

Uma cadeia canônica de dois plugins tem esta forma:

  • Um plugin de configuração que emite as regras semânticas da funcionalidade (regras de policy de segurança, padrões de auditoria, limites de taxa). Ele entende a intenção da funcionalidade; não entende a malha de interceptação de tráfego do ambiente de destino.
  • Um plugin de roteamento que emite a configuração física da mesh que transporta essas regras (CRDs de gateway, patches de injeção de sidecar, regras de firewall). Ele entende a malha do ambiente de destino; não entende a intenção semântica da funcionalidade.

Os dois plugins recebem em sequência do compilador o mesmo contexto de nó IR, de modo que se compõem de forma limpa, sem acoplamento direto entre eles. O compilador orquestra o pipeline; os plugins carregam o conhecimento do domínio.

3. Interceptação de tráfego: o alvo HTTPRoute

O modelo de extensibilidade do Aggrega tem como alvo o padrão HTTPRoute da Kubernetes Gateway API como artefato comum a todos os providers para a interceptação de tráfego no nível da mesh. A biblioteca padrão emite objetos HTTPRoute por meio da Feature core/http-route, cuja FeatureRecipe helm renderiza uma rota por componente anexado; os ambientes de destino que consomem a Gateway API traduzem HTTPRoute para suas malhas nativas.

4. Autonomia do Plugin: resolução de rótulos

Quando plugins Wasm geram recursos físicos a partir do grafo IR, os SREs precisam rastrear um Pod Kubernetes em execução ou um recurso de nuvem até a intenção semântica do desenvolvedor no Aggregate. O modelo de extensibilidade do Aggrega coloca essa tradução inteiramente sob o controle do autor do plugin Wasm.

O compilador passa o dicionário labels completo do grafo IR para a sandbox Wasm sem interpretá-lo. A partir daí, o autor do plugin — Platform Ops — decide a lógica de mapeamento: repassar todos os rótulos literalmente, filtrar por prefixos de domínio específicos (*.aggrega.ai/*) ou mapear os rótulos do grafo diretamente para os esquemas de tagging nativos do provider (traduzindo um rótulo IR em tags da AWS, annotations do Kubernetes ou um mecanismo de metadados específico da nuvem). O compilador não impõe nenhuma restrição sobre como os artefatos gerados são marcados.

Essa autonomia mantém a inteligência específica do domínio — quais rótulos importam para a observabilidade, quais correspondem a convenções de tagging nativas, quais são internos à plataforma — dentro da camada de plugins Wasm, onde o ecossistema evolui independentemente do ritmo de lançamento do compilador Go.

5. Extensões da CLI: comandos em tempo de execução

Os sockets acima são executados dentro de um build — o compilador os aciona enquanto analisa, transforma, valida e renderiza um Aggregate. O socket de extensões da CLI é de natureza diferente: ele é executado no terminal, fora de qualquer build, quando um operador digita aggrega <command>. É assim que a própria superfície de comandos de aggrega cresce sem uma nova versão do núcleo.

O que é uma extensão da CLI. Uma extensão da CLI é um aggrega <command> pronto para uso fornecido por um plugin Wasm assinado e executado em sandbox. Ela adota a mesma abordagem drop-in, com a lógica no convidado, que o socket de renderização adota: a lógica de domínio fica inteiramente no convidado, e o host Go não contribui com nenhum código por comando. Adicionar um novo comando de nível superior exige apenas três coisas — um binário .wasm, uma entidade Plugin que declare pluginType: cli (veja Plugin) e um aggrega plugin add cli explícito. O host descobre o comando a partir da autodescrição do plugin instalado; nenhum comando é compilado no binário.

Por que um socket de tempo de execução pode fazer o que um socket de build não pode. Como os sockets de tempo de compilação são executados durante um build, eles permanecem sem capacidades e determinísticos: o Aggrega é um compilador ahead-of-time, e a mesma entrada deve sempre produzir a mesma saída (veja Invariantes arquiteturais). Por isso, um plugin de renderização ou de policy não pode acessar a rede, ler o relógio nem transmitir para o terminal — qualquer coisa que varie entre execuções quebraria essa garantia. Uma extensão da CLI é executada depois e fora desse limite, conduzida por uma pessoa em um prompt em vez do pipeline determinístico. É exatamente por isso que um plugin da CLI pode transmitir a saída padrão e o erro padrão durante a execução e retornar um código de saída de processo: não há nenhum artefato de build cuja estabilidade byte a byte esses efeitos possam ameaçar.

Instalar, executar e descobrir. aggrega plugin add cli <query> procura no registry configurado um plugin cli correspondente, verifica-o em relação à política de confiança do registry e o instala como um comando de nível superior — exibindo primeiro as capacidades declaradas do plugin, para que o operador confirme exatamente o que o comando tem permissão para fazer antes de ser instalado. Depois de instalado, aggrega <command> o executa como qualquer comando integrado. Um plugin da CLI declara seus comandos e as flags deles em sua autodescrição describe(), e o host exibe as flags de cada comando em aggrega help <command> exatamente como faz para um comando integrado, de modo que um operador descobre as --flags de um comando instalado da mesma forma. Para encontrar comandos instaláveis e conteúdo de catálogo, aggrega search consulta o índice local dos registries configurados — --kind plugin --plugin-type cli restringe os resultados aos plugins da CLI instaláveis, e uma pesquisa sem filtro abrange as entidades do catálogo; aggrega plugin list mostra o que já está instalado. As flags e os formatos de saída de cada comando estão nessas páginas de referência.

O modelo de capacidades. Uma extensão da CLI parte de uma base fixa que todo comando recebe sem nenhuma declaração e sem nenhuma solicitação de confirmação:

Capacidade básicaConcedida
Argumentos de linha de comando de entradaSempre
Saída padrão e erro padrão transmitidosSempre
Código de saída do processo retornadoSempre

Tudo o que vai além da base fica desativado por padrão. Um plugin que precisa de mais declara explicitamente cada capacidade adicional, e o host só a concede depois de exibi-la no momento da instalação para que o operador a confirme. Uma classe de capacidades adicionada além da base — acesso ao ambiente, ao sistema de arquivos ou à rede, entrada interativa — é concedida atrás do mesmo controle de declaração e confirmação, de modo que um comando nunca possa adquirir silenciosamente um alcance que o operador não aprovou.

Os comandos integrados sempre prevalecem. Um plugin instalado nunca pode encobrir um comando integrado. Uma proteção de nomes reservados, apoiada em uma lista de bloqueio, protege os comandos integrados e um conjunto de nomes reservados para comandos integrados, e uma colisão é recusada na instalação em vez de poder sobrescrever o comportamento do núcleo. A superfície de comandos da qual um operador depende permanece estável, independentemente do que for instalado sobre ela.

6. Plugins de análise: leitura de formatos externos

O compilador precisa ler com frequência texto escrito em um formato do qual não é autor — um módulo Terraform em HCL, um arquivo de configuração em TOML, um manifesto em YAML ou JSON. O socket de analisadores fornece essa capacidade de leitura sem ensinar nenhum formato específico ao núcleo do compilador. Um analisador é um plugin sem estado que transforma um texto de origem externo em uma árvore JSON estruturada: entregue a ele os bytes de um arquivo HCL e ele retorna o mesmo conteúdo como um objeto JSON que o restante do pipeline já sabe percorrer. Qualquer parte do compilador que precise ler um formato que não analisa nativamente solicita uma árvore analisada e trabalha a partir dela.

Um formato é uma capacidade, não uma funcionalidade do compilador. Um analisador anuncia os formatos que processa como capacidades — parse:hcl, parse:toml e assim por diante — e o host resolve um analisador pelo formato solicitado, executa-o e devolve a árvore. É o mesmo modelo drop-in, baseado em capacidades anunciadas, que os providers de renderização e os plugins da CLI adotam: o núcleo do compilador não contém nenhuma lista integrada de formatos, então adicionar um significa distribuir um novo plugin de análise, nunca uma nova versão do núcleo. Analisadores para HCL, TOML, YAML, JSON e JSON com comentários vêm dentro do binário como conjunto inicial; uma empresa que precisa de outro formato distribui um plugin de análise que o anuncie.

A seleção de formato é declarativa, nunca adivinhada. O host nunca inspeciona o conteúdo de um arquivo para decidir o que ele é. Ele escolhe um formato por meio de sinais declarados, em uma ordem de preferência fixa. Um provider de renderização pode declarar o formato de cada arquivo que emite, e o host prefere sem ressalvas esse formato declarado pelo produtor — o provider que escreveu os bytes é a autoridade sobre como lê-los. Para um arquivo que o produtor não marcou, um mapa fixo de extensões de arquivo é a alternativa — .tf seleciona HCL, .toml seleciona TOML, .yaml seleciona YAML, .json seleciona JSON. Escolher por um formato declarado ou por uma extensão fixa mantém a análise determinística e legível: a mesma entrada sempre é encaminhada ao mesmo analisador, e um operador consegue saber qual analisador será executado sem conhecer os bytes do arquivo. Inspecionar o conteúdo faria a escolha depender do payload, e o Aggrega não faz isso.

Um analisador é puramente sintático. A saída é uma árvore JSON mais diagnósticos e, opcionalmente, as posições no código-fonte de onde veio cada nó. Um analisador não carrega nenhum significado do Aggrega — ele relata o que o texto diz estruturalmente, nada sobre o que significa como Component, Recipe ou qualquer outra entidade. Transformar uma árvore analisada em entidades do Aggrega é uma questão separada, tratada em outro lugar; a única tarefa do analisador é uma tradução fiel de sintaxe para JSON. A direção de leitura é de mão única, no mesmo espírito: um analisador lê um formato para uma árvore, não escreve um formato de volta.

Um consumidor: policy sobre HCL do Terraform. Uma policy da etapa de renderização que precisa inspecionar o Terraform produzido por um build não aprende HCL por conta própria. O host analisa o artefato HCL por meio do socket de analisadores e entrega ao plugin de policy a árvore JSON que ele já lê, de modo que a policy raciocina sobre dados estruturados no formato que todo outro socket recebe. Novos leitores de formatos externos se compõem da mesma maneira — pedir a árvore ao host e depois trabalhar em JSON —, de modo que a capacidade do compilador de entender um formato cresce com a adição de plugins de análise, e não com o crescimento do núcleo.

7. Plugins de importação: rascunhos de arquivos de autoria a partir de fontes externas

Uma equipe raramente começa do zero. Sua arquitetura de agentes muitas vezes já existe em outro lugar — um flow do Langflow ou do Flowise, um workflow do n8n, uma aplicação do Dify, os servidores MCP com os quais um cliente está configurado, uma aplicação Compose, os agentes que a configuração de um framework declara. O socket de importadores transforma essa fonte externa em um ponto de partida concreto para a autoria no Aggrega: ele lê a fonte e gera entidades Aggregate e Component em primeiro rascunho e, a partir de uma configuração MCP, de uma aplicação Compose ou da configuração declarada de um framework, um rascunho de Release, para que um autor revise e conclua, de modo que uma equipe leve para o Aggrega o que já tem, em vez de reescrevê-lo à mão. Um importador mapeia significado — ele lê o que um nó da fonte é e propõe a entidade do Aggrega que o representa, ou o deixa dentro do flow que a plataforma em rascunho carrega; o compilador repassa as entidades emitidas de forma opaca, exatamente como permanece agnóstico em relação ao que qualquer plugin produz.

Um formato é uma capacidade, não uma funcionalidade do compilador. Um importador anuncia os formatos que processa como capacidades — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework e assim por diante — e o host resolve um importador pelo formato solicitado, executa-o e recebe de volta as entidades que ele rascunhou. É o mesmo modelo drop-in, baseado em capacidades anunciadas, que o socket de analisadores adota com parse:<format>: o núcleo do compilador não contém nenhuma lista integrada de formatos importáveis, então dar suporte a um novo significa distribuir um plugin de importação que o anuncie, nunca uma nova versão do núcleo.

Um importador lê por meio do socket de analisadores; ele não reanalisa. Um importador precisa da forma estruturada de sua fonte, mas não reimplementa a leitura de um formato que o ecossistema já analisa. Quando precisa da árvore, ele pede ao host que execute o analisador correspondente — aquele que o catálogo do workspace fornece para a sintaxe da fonte ou, quando o catálogo não fornece nenhum, aquele que o próprio compilador traz — por meio da mesma capacidade de análise mediada pelo host que o restante do pipeline usa, e trabalha a partir da árvore JSON retornada. Ler (de sintaxe para árvore) continua sendo tarefa do analisador; mapear (de árvore para entidades do Aggrega) é tarefa do importador. Os dois sockets se compõem sem duplicar um ao outro: um importador acrescenta a inteligência de mapeamento para uma fonte e se apoia no analisador existente para os bytes.

Um formato é reconhecido pelo que seu importador declara, nunca adivinhado. Uma importação pode nomear diretamente seu formato de origem. Quando não o faz, o formato é reconhecido por assinaturas que cada importador declara em sua autodescrição e que sua entidade Plugin registra: a sintaxe em que uma fonte é lida, os nomes de arquivo aos quais uma assinatura se aplica e os caminhos que a árvore analisada deve ou não deve conter. O host não conhece nenhum formato próprio. Ele analisa a fonte por meio do analisador que o catálogo do workspace fornece para cada sintaxe que uma assinatura nomeia — ou o do compilador, quando o catálogo não fornece nenhum —, avalia os predicados declarados sobre a árvore retornada e lê a fonte como o formato do único importador cuja assinatura corresponde. As assinaturas declaradas ocupam o lugar que um mapa fixo de extensões de arquivo ocupa para o socket de analisadores, porque os formatos que uma importação lê podem compartilhar uma extensão — uma exportação do Langflow, uma exportação do Flowise e um workflow do n8n são todos arquivos JSON. Uma fonte com a qual nenhuma assinatura corresponde é recusada, pedindo o formato e nomeando os formatos que os importadores anunciam — ou, no caso de um diretório, pedindo um de seus arquivos isoladamente ou um formato cujo importador declara padrões de arquivo, nomeando apenas esses; uma fonte com a qual correspondem assinaturas de mais de um formato é recusada, nomeando-os. O reconhecimento não lê nada além da fonte e não acessa nenhuma rede, então reconhecer um novo formato é uma declaração que o novo importador distribui, nunca uma alteração no host. As regras para escrever uma assinatura estão em O socket de importadores.

Um diretório é lido por meio dos arquivos que seu importador declara. Uma fonte é um arquivo ou um diretório. Um arquivo é entregue inteiro ao importador. Um diretório é lido como fontes nomeadas — exatamente os arquivos dele que os padrões de arquivo das assinaturas do importador selecionam, cada um nomeado pelo seu caminho dentro do diretório, em ordem classificada — e nenhum outro arquivo do diretório é aberto; um link que levaria a leitura para fora do diretório é recusado antes que qualquer coisa seja lida. Um importador que não declara padrões de arquivo lê um único arquivo e recusa um diretório, e um diretório que não contém nenhum arquivo selecionado pelos padrões de um importador também é recusado. Os importadores de Langflow, Flowise, n8n, Dify e Agent Framework do compilador não declaram nenhum, então cada um lê um único arquivo exportado de flow, workflow ou aplicação, ou um único agente declarativo; seu importador de MCP declara os nomes de arquivo das configurações de cliente MCP que lê, de modo que o diretório de um projeto é lido por meio das configurações que contém; seu importador de Compose declara os nomes de arquivo que o Compose lê por padrão, de modo que o diretório de um projeto é lido por meio de seu arquivo Compose e do arquivo de override que o Compose mescla sobre ele; e seu importador de CrewAI declara os nomes de arquivo sob os quais um projeto CrewAI declara seus agentes e tarefas, de modo que o diretório de um projeto é lido por meio dessas declarações e seu programa nunca é lido; e seu importador de LangGraph declara langgraph.json, de modo que o diretório de uma aplicação é lido apenas por meio de sua configuração, sem que seu código e seus arquivos de ambiente jamais sejam lidos, e um arquivo de ambiente que a configuração nomeia só chega ao importador onde o with.sources de seu acoplamento o entrega, e então apenas para os nomes das variáveis; e seu importador de Google ADK declara root_agent.yaml, de modo que o diretório de uma aplicação é lido apenas por meio da configuração de seu agente raiz, as configurações que seus subagentes nomeiam só chegam ao importador onde o with.sources de seu acoplamento as entrega, e nem seu código nem seu arquivo de ambiente jamais são lidos.

O mapeamento é determinístico, pontuado por confiança e avaliado em relação ao seu próprio catálogo. O host entrega ao importador uma visão dos Components que o próprio catálogo do workspace contém — o catálogo do qual o importador foi selecionado — as pastas de catálogo do workspace ou, quando ele não nomeia nenhuma, o snapshot do catálogo que seu registry padrão publica — os Components de um catálogo corporativo exatamente como os da biblioteca padrão. A visão traz o nome, a versão e os rótulos de cada Component, os nomes de chave que seus values e provides declaram e os seletores de seus sockets, e nunca um valor, um padrão ou um segredo; nada é buscado para construí-la além desse snapshot, e sua ordem é fixa, de modo que um catálogo produz uma única visão. Um importador construído sobre o pacote importer do PDK Go — entre eles os próprios importadores de Langflow, Flowise, n8n e Compose do compilador — avalia cada nó da fonte em relação a esses Components e a nada mais, com um modelo de confiança determinístico e sem modelos de IA, e registra a decisão — os candidatos avaliados, o nível de correspondência atribuído e a escolha feita — como dicas revisáveis que um autor pode ler e alterar. Um Component que o catálogo ganha é um candidato na próxima importação, sem que nenhum importador seja reconstruído. O padrão é apenas dicas: a importação propõe, e o autor decide. Uma correspondência de alta confiança pode ser escrita como uma referência a um componente existente do catálogo em vez de um corpo recém-rascunhado, mas apenas quando o operador habilita isso explicitamente — sempre como uma sugestão explícita e reversível que o autor aprova, nunca como uma reescrita silenciosa. Como a pontuação não usa nenhum modelo nem nenhuma consulta em tempo de execução, a mesma fonte avaliada em relação ao mesmo catálogo sempre produz as mesmas dicas.

Um flow é rascunhado como a plataforma que o executa. Um flow do Langflow, um chatflow do Flowise e um workflow do n8n são executados em uma plataforma, e por padrão uma importação rascunha essa plataforma em vez dos nós do flow: uma instância do Component de plataforma da biblioteca padrão — core/ai-agent/langflow, core/ai-agent/flowise ou core/ai-agent/n8n — que carrega o flow como foi exportado em seu valor flow_definition, que a plataforma carrega no deploy. Cada parte do flow que um socket da plataforma aceita — nas plataformas da biblioteca padrão, um modelo, um servidor MCP ou outra ferramenta acessada por HTTP, e um vector store — torna-se um Component próprio, referenciado ou rascunhado conforme o mapeamento decidir, e é conectada a esse socket sob o uses da plataforma. Assim, cada chamada que o flow faz a um modelo, uma ferramenta ou um store é uma conexão que o Aggregate declara: um plugin de governança que julga o grafo a enxerga como enxerga qualquer outra aresta, e a allowlist de egress da biblioteca padrão, que a configuração attach_egress_allowlist acopla à plataforma, permite que a plataforma se conecte apenas ao que suas conexões alcançam, aos próprios pods e ao DNS do cluster. Onde o formato permite, o rascunho escreve no flow carregado o que faz o flow alcançar cada parte por meio de sua conexão. Todo outro nó — um agente, uma chain, um gatilho — permanece dentro do flow carregado e não se torna nenhum Component, e sua decisão registra os candidatos em relação aos quais foi avaliado. Uma aplicação do Dify é rascunhada da mesma maneira, na forma que uma instalação inteira assume: uma entrada da instalação do Dify que a biblioteca padrão monta, core/dify, que carrega a aplicação em seu parâmetro app_definition, com a instalação conectando suas próprias conexões. A configuração layout do acoplamento do importador escolhe o rascunho: platform, o padrão, ou nodes, que rascunha cada nó da fonte como um Component próprio, cada aresta do flow como uma conexão uses, e não carrega nenhum flow. A plataforma que carrega o flow descreve quais nós se tornam partes e onde cada um é conectado.

Um framework code-first é lido por meio de sua configuração declarada, nunca de seu programa. CrewAI, LangGraph, Google ADK e Agent Framework mantêm o comportamento de uma aplicação em seu programa e declaram seus agentes, grafos e modelos em uma configuração ao lado dele. Seus importadores leem apenas essas declarações — os arquivos de agentes e tarefas de um projeto CrewAI, o langgraph.json de uma aplicação LangGraph, as configurações de agentes de uma aplicação Google ADK, um agente declarativo do Agent Framework — e rascunham o agente da biblioteca padrão para o framework em torno de um programa que nunca abrem, conectado ao que as declarações nomeiam: o modelo que um agente solicita, onde o socket model do agente o aceita, e o datastore em que um checkpointer do LangGraph mantém o estado. Um servidor MCP que um agente do Agent Framework nomeia é acessado pelo provedor do modelo, como ferramenta hospedada, então o rascunho o nomeia em comentários e não conecta nada a ele. O programa é executado na imagem que a Release nomeia. O que só o programa diz — a lógica de uma tarefa, uma ferramenta que seu código define, um agente que seu código constrói — é nomeado nos comentários e nas decisões do rascunho e não se torna nenhum Component; levá-lo para arquivos de autoria é trabalho do autor, à mão ou com um assistente de IA que escreve em nome do autor por meio de aggrega mcp, que lê a referência e gera e valida entidades.

O que uma fonte declara sobre como suas partes são executadas vai para um rascunho de Release. Fornecer as entradas operacionais cabe à Release, então os importadores de MCP, Compose, CrewAI, LangGraph, Google ADK e Agent Framework rascunham uma Release ao lado do Aggregate, que seu spec.aggregate nomeia: a Release carrega o que a fonte declara — a linha de comando ou o endereço de um servidor, a imagem e a porta de um servidor genérico, o endpoint de um modelo — e, em comentários acima de cada entrada, o que a fonte declara mas nenhuma chave do Component rascunhado aceita, como os volumes de um serviço ou o ambiente de uma configuração. O que nenhuma fonte declara — a imagem que executa o programa de um framework, a credencial que uma conexão apresenta, o metadata.environment e o spec.manifest da Release — é nomeado em um comentário no lugar a que pertence, para que o operador o forneça, e o build é interrompido nomeando qual dentre a imagem, o ambiente e o manifesto ainda não está definido. Um rascunho de plataforma não escreve nenhuma Release: o comentário acima da instância da plataforma nomeia o que a Release fornece — as entradas próprias da plataforma, como a imagem que ela executa ou sua conta proprietária, o endereço de cada servidor MCP conectado e a credencial que cada conexão apresenta.

Um valor de credencial que uma fonte contém é carregado como está escrito, a menos que sua remoção seja solicitada. Um importador localiza cada valor em sua fonte que pode carregar uma credencial, cada um de uma classe: o que o formato marca como credencial, um membro da configuração de um servidor MCP, ou uma entrada que o formato marca como não credencial mas que ainda assim pode carregar uma, como os cabeçalhos de uma requisição. Por padrão, nenhum é escrito vazio: cada valor que contém algo é carregado como está escrito — no flow ou na aplicação que a plataforma carrega, ou no rascunho de Release — e nomeado em um aviso credential-carried pelo lugar onde está — seu nó, servidor, serviço ou agente, e seu campo —, nunca pelo seu valor, junto com o valor de configuração que o escreve vazio. A configuração empty_credentials ativa a remoção, uma classe de cada vez: marked escreve vazio o que um formato marca como credencial e cada membro da configuração de um servidor MCP, e all também as entradas marcadas como não credenciais, cada valor escrito vazio sendo relatado com credential-emptied. O que o rascunho escreve para que um flow alcance sua conexão é cabeamento, escrito independentemente do que a configuração diga, e uma conexão no rascunho não carrega nenhuma credencial: a Release acopla aquela que cada conexão apresenta. Um arquivo para o qual uma fonte apenas aponta, como um arquivo de ambiente, é lido apenas para os nomes de suas variáveis, quando é lido, e um rascunho feito nó a nó não lê nenhum valor. O que está fora dos lugares que um importador localiza — o código de um componente personalizado, um prompt — cabe ao autor revisar antes de compartilhar um rascunho, conforme descrito em Valores de credencial que o flow contém.

O comando, o editor e o assistente executam uma mesma importação. aggrega import <file or directory> executa uma importação a partir do terminal; o editor executa a mesma operação pela requisição aggrega/import da sua sessão, e um assistente de IA pela ferramenta import exposta pelo aggrega mcp. Os três selecionam o importador da mesma forma, entre os importadores que o catálogo do workspace contém e os importadores básicos do compilador: aquele que um vínculo plugins.importer nomeia, quando nomeia um que anuncia o formato, e, caso contrário, a versão mais alta do único importador que o anuncia — importadores de dois nomes para um mesmo formato, sem que nenhum esteja vinculado, interrompem a importação, que nomeia ambos, como expõe Qual importador transforma uma fonte em rascunhos. Os três relatam as decisões de mapeamento ao lado dos rascunhos. O comando imprime na saída de erro padrão uma linha por nó mapeado, nomeando o Component ou o rascunho escolhido para ele, se ele é referenciado ou gerado como rascunho, o nível de correspondência e, quando o importador avaliou um candidato, a pontuação do melhor candidato; o editor mostra as mesmas linhas, e o resultado da sessão do editor e a resposta do assistente trazem cada decisão por completo. Assim, um autor vê onde a importação fez suposições, em qualquer superfície que a tenha executado, sem abrir os rascunhos. --format informa explicitamente o formato da fonte — por exemplo langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk ou agent-framework — em vez do reconhecimento. O comando grava as entidades e quaisquer arquivos de scaffold que a importação produziu sob a raiz do workspace, ou sob o diretório que --output-dir indica; --dry-run faz tudo o que o comando faz, exceto gravar, devolvendo os arquivos gerados como conteúdo e indicando o arquivo a que cada um se destina, para que um autor possa revisar o scaffold antes de fazer commit de qualquer coisa na árvore de trabalho.

Os importadores do núcleo. Os importadores do núcleo que o compilador distribui leem estes formatos, um importador para cada:

  • Langflow — um flow exportado do Langflow, rascunhado como a plataforma Langflow da biblioteca padrão que carrega o flow, com cada parte dele que um socket aceita conectada a esse socket.
  • Flowise — um chatflow ou um agentflow exportado do Flowise, rascunhado como a plataforma Flowise da biblioteca padrão que o carrega, com cada parte dele que um socket aceita conectada a esse socket.
  • n8n — um workflow exportado do n8n, rascunhado como a plataforma n8n da biblioteca padrão que o carrega, com cada parte dele que um socket aceita conectada a esse socket.
  • Dify — uma aplicação exportada do Dify, rascunhada como a instalação do Dify que a biblioteca padrão monta e que carrega a aplicação, com os modelos, ferramentas e bases de conhecimento que ela nomeia relatados como configurados dentro do Dify.
  • MCP — a configuração de um cliente MCP ou a descrição de servidor de um registry MCP, com cada servidor rascunhado como uma instância da ferramenta MCP da biblioteca padrão, e uma Release que carrega a linha de comando, o endereço ou a imagem de cada servidor.
  • Compose — um formato de infraestrutura, com cada serviço de uma aplicação Compose rascunhado como o Component do catálogo ao qual sua imagem corresponde — por meio de uma tabela que o importador carrega, gerada a partir das Recipes e dos Components Compose do catálogo padrão quando ele é construído — ou como um servidor genérico que executa sua imagem, com uma Release que carrega a imagem e a porta de cada servidor genérico e, em comentários, as portas, os volumes e o ambiente que cada serviço declara.
  • CrewAI — os agentes que um projeto CrewAI declara em seus arquivos de configuração, cada um rascunhado como o agente CrewAI da biblioteca padrão que carrega seu papel, seu objetivo e sua história de fundo e está conectado ao modelo que ele nomeia, com as tarefas e ferramentas do projeto relatadas como pertencentes ao seu programa, o próprio programa nunca lido, e uma Release que deixa para o operador nomear a imagem que o executa.
  • LangGraph — os grafos que a configuração de uma aplicação LangGraph declara, cada um rascunhado como o agente LangGraph da biblioteca padrão que carrega o caminho de importação de seu grafo e está conectado ao datastore em que seu checkpointer mantém o estado, com uma Release que informa, em um comentário, o ambiente que a configuração declara, e o código dos grafos nunca lido.
  • Google ADK — as árvores de agentes que as configurações de agentes de uma aplicação Google ADK declaram, cada uma rascunhada como o agente ADK da biblioteca padrão conectado ao modelo que nomeia quando o ADK envia as requisições desse modelo à API do Gemini, sendo um modelo acessado de qualquer outra forma — por meio de uma string de modelo do LiteLLM, por exemplo — nomeado em um comentário e sua conexão deixada para o autor, com uma Release que deixa para o operador nomear a imagem que executa a aplicação, e o código da aplicação nunca lido.
  • Agent Framework — um agente declarativo do Agent Framework, rascunhado como o agente Agent Framework da biblioteca padrão conectado ao modelo da OpenAI que ele nomeia, com cada servidor MCP que ele nomeia escrito em comentários, já que o provedor do modelo o acessa como ferramenta hospedada, com uma Release que carrega o endpoint do modelo e, em um comentário, o endereço de cada servidor, e o código da aplicação nunca lido.

Eles são plugins de importação como qualquer outro — a inteligência de mapeamento específica de cada formato fica neles, não no núcleo —, construídos a partir do código-fonte do compilador e publicados com cada versão do compilador, na versão desse lançamento. Nenhum é compilado no binário: o binário carrega a entidade Plugin de cada um e o digest do único módulo que aceita, de modo que cada um atende ao seu formato em todo workspace sem nenhuma entrada de catálogo. A primeira importação que precisa de um que a máquina não possui o busca no registry padrão do workspace, vincula-o a esse digest, verifica-o como um pull verifica um plugin que busca — sua assinatura conforme a política de confiança desse registry e as funções de host que ele usa — e o guarda no cache de conteúdo do workspace; cada importação posterior o lê de lá, sem acessar a rede para ele. Uma importação não fixa nenhum importador: nada mais é escrito para ele — nenhuma entrada de lockfile e nenhum registro de plugins confiáveis —, nenhum pull o coloca em cache e nenhum build o lê. Um módulo que não passa na verificação é recusado, e nada é guardado. Quando o módulo não pode ser buscado — o workspace está offline, seu registry não pode ser acessado ou o registry não o contém —, a importação é interrompida, nomeando o importador, sua versão e o que coloca seu módulo na máquina. A escolha continua sendo do workspace: um importador que seu catálogo contém com outro nome para um desses formatos é executado onde um acoplamento plugins.importer o nomeia, e um com o mesmo nome e a mesma versão de um importador do núcleo é executado no lugar dele.

Semear e expandir um catálogo

Um catálogo não precisa ser construído do zero. A maior parte do trabalho de semear Recipes e plugins para um novo ambiente é scaffolding e reutilização, e não escrever cada binário à mão.

Importar uma fonte externa para rascunhos de arquivos de autoria. aggrega import <file or directory> lê uma fonte declarativa de definição de agentes — um flow do Langflow ou do Flowise, um workflow do n8n, ou a configuração de um cliente MCP ou a descrição de um servidor de um registro MCP —, uma aplicação Compose, uma aplicação Dify, os agentes que um projeto CrewAI declara, os grafos que a configuração de uma aplicação LangGraph declara, os agentes que as configurações de agentes de uma aplicação Google ADK declaram, ou um agente declarativo do Agent Framework, e gera um primeiro rascunho de YAML Aggregate e Component e, a partir de uma fonte MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework, um rascunho de Release, para um autor revisar e concluir, de modo que uma equipe leve adiante o que já tem em vez de reescrevê-lo à mão. Para cada nó de um flow, e cada serviço de uma aplicação Compose, ele pontua os Components do próprio catálogo do workspace — o de um catálogo corporativo tanto quanto o da biblioteca padrão — com um modelo de confiança determinístico e sem modelo, e registra a decisão — os candidatos que avaliou, o nível que atribuiu e a escolha que fez — como dicas revisáveis, que o comando, o editor e o assistente relatam; uma correspondência de alta confiança pode ser gravada como referência ao catálogo quando o operador habilita essa opção, sempre como uma sugestão explícita e reversível que o autor aprova, e não como uma reescrita silenciosa. Cada Component que um catálogo ganha é um candidato que a próxima importação avalia. A inteligência de mapeamento específica de cada formato fica em um plugin importador: os importadores Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK e Agent Framework do compilador atendem esses formatos em todo workspace, baixados e verificados no primeiro uso, e um catálogo adiciona um formato ao conter um plugin importador que o anuncia. Uma fonte de diretório é lida pelos padrões de arquivo que seu importador declara; os importadores Langflow, Flowise, n8n, Dify e Agent Framework não declaram nenhum, e cada um lê um único arquivo exportado ou agente declarativo, enquanto o importador MCP lê as configurações de cliente que um diretório contém, o importador Compose seus arquivos Compose, mesclados como o Compose os mescla, o importador CrewAI as declarações de um projeto, nunca seu programa, o importador LangGraph a configuração de uma aplicação, nunca seu código nem um arquivo de ambiente — cujos nomes ele lê apenas quando seu vínculo lhe entrega o arquivo —, e o importador Google ADK a configuração do agente raiz de uma aplicação, nunca seu código nem seu arquivo de ambiente, com as configurações de seus subagentes lidas quando seu vínculo as entrega — uma configuração que o ADK declara experimental, cujos agentes usam um modelo Gemini por padrão e alcançam pelo nome os modelos de outros provedores por meio de classes do próprio ADK, ou por meio de uma string de modelo LiteLLM.

A maior parte do trabalho com plugins é feita de templates, não de código compilado. Uma grande parte das funcionalidades apenas injeta um sidecar estático, uma variável de ambiente ou um label — um JSONPatch simples, sem lógica condicional. Um único plugin patcher configurável, escrito uma vez para receber um template JSONPatch declarativo como sua entrada with, pode cobrir esse caso comum sem um binário compilado exclusivo por funcionalidade: o autor escreve um template e, para muitos destinos no estilo CRD, um template valuesMapping (muitas vezes referenciando fragmentos compartilhados em uma entrada de MappingLibrary) basta por si só. Plugins PDK escritos sob medida são para o restante, de fato condicional.

Tomar ferramentas consolidadas como referência. Ao escrever nova lógica de plugin, os autores podem consultar as formas de saída documentadas publicamente de ferramentas open source consolidadas — a estrutura dos CRDs, patches ou templates que essas ferramentas sabidamente emitem — como referência para a forma de destino que um novo plugin deve produzir, respeitando a licença de cada projeto. Webhooks de injeção de sidecar, bibliotecas de constructos de nível mais alto, geradores de CRD de operadores e catálogos de traits ou de composição publicam estruturas de saída que correspondem de perto ao que uma FeatureRecipe ou um plugin comparável precisa emitir. O objetivo é corresponder a um contrato de saída bem compreendido, não copiar a implementação de nenhum projeto.