Extensibilidade
Extensibilidade do ecossistema e salvaguardas do compilador
1. A interface universal WebAssembly (Wasm)
Para garantir simetria arquitetónica em todo o ecossistema, o Aggrega utiliza um contrato de execução normalizado que se aplica uniformemente a cada socket Wasm do pipeline do compilador.
A interface YAML para invocar qualquer plugin assenta 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 em memória, pelo que nenhum processo do sistema operativo é iniciado.functionnomeia o export que o host Go invoca: uma função exportada explicitamente pelo módulo Wasm.with: as entradas próprias do plugin, mantidas à parte dosvaluesdo programador e dosparametersque uma Release satisfaz. A palavra-chave segue a convenção do GitHub Actions (with:); quando um plugin declara um JSON Schema para as suas entradas, o host valida-as face a esse esquema antes da execução.
Os tipos de Plugins Wasm: Esta interface universal function e with suporta todos os sockets programáveis do compilador:
| Tipo de Plugin | Onde é executado | Finalidade | Saída esperada |
|---|---|---|---|
Provider (provider) | Renderização (geração) | Traduz o IR final em memória em ficheiros físicos serializados como texto para um formato de destino (Helm, Terraform, Compose). | Um array de ficheiros serializados como texto. |
Passo de pipeline de FeatureRecipe (pipeline-step) | O pipeline de plugins de uma Recipe ou de uma FeatureRecipe | Passos sequenciais que obtêm segredos ou injetam sidecars em ASTs base. | patches RFC 6902 sobre o conjunto de documentos com chave, mais side_effects (emitir um novo documento ou ficheiro), diagnostics e outputs que um passo posterior pode ler. A entrada do passo transporta esse conjunto de documentos com chave e a entrada with renderizada do passo. |
Governação (governance) | Antes da expansão de anotações, construção da topologia, análise estática ou fase de renderização | Serve os papéis de governação do pipeline de build. Antes da expansão de anotações, injeta anotações nos componentes resolvidos e, na construção da topologia, etiqueta automaticamente os nós com etiquetas de conformidade ou ambientais (um operador ativa-o explicitamente para um ou outro papel). Na análise estática ou na fase de renderização, atua como o Loud Guardrail: avalia arestas, caminhos e etiquetas do grafo — ou os artefactos renderizados — face a fronteiras de segurança. É o papel a que está associado, e não o seu tipo, que fixa o que pode emitir. | Antes da expansão de anotações, injeções de anotações. Na construção da topologia, um array de JSONPatches dirigidos a metadata.labels. Na análise estática ou na fase de renderização, veredictos de gravidade halt, warn ou info (uma política Rego reúne-os em deny, warn e audit); um halt interrompe o build. |
Linter (linter) | Fora de banda | Verificações opcionais de FinOps ou de higiene (por exemplo, estimativa de custos de cloud a partir de .infra) e disciplina no momento da publicação. | Cadeias de aviso ou interrupções fatais. |
Extensão de CLI (cli) | Em tempo de execução (aggrega <command>) | Um comando de nível superior pronto a usar, contribuído por um plugin assinado e isolado em sandbox, sem qualquer código Go por comando no host. | Saída padrão e erro padrão em streaming, mais o código de saída do guest. |
Parser (parser) | A pedido, onde quer que seja lido um formato externo | Converte texto de origem externo (HCL, TOML, YAML, JSON, JSON com comentários) numa árvore JSON canónica. | tree mais diagnostics, e spans de origem opcionais. |
Importador (importer) | A pedido, fora de qualquer build (aggrega import, o editor e a ferramenta import do assistente) | Converte uma origem 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 ficheiros de autoria Aggrega em rascunho, anunciando os formatos que trata como capacidades import:<format>. | Entidades Aggregate / Component / Release em rascunho, ou referências aos Components do catálogo que reutiliza, as decisões de mapeamento por trás delas, diagnósticos e os ficheiros de scaffold a escrever. |
O runtime do host: uma sandbox que nega capacidades. O Aggrega incorpora o host Wasm como o toolkit Extism a correr sobre o motor Wazero; o binário do host continua a ser Go puro, sem dependência de toolchain nativa, pelo que o aggrega faz compilação cruzada sem problemas. Cada socket corre por trás de uma firewall de pureza AOT: o host recusa conceder a um plugin qualquer capacidade de acesso em tempo de execução — sem rede, sem sistema de ficheiros, sem relógio de parede, sem ambiente, sem E/S padrão —, pelo que uma chamada que usaria uma delas falha, e um plugin que importe de uma superfície do host que o host não fornece é rejeitado no carregamento. Um plugin que não consegue chegar à 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. Os runtimes de linguagem que precisam de algumas importações benignas no arranque correm contra uma configuração dessas importações com capacidades negadas: o host fixa o relógio de parede observável, fornece entropia real, descarta a E/S padrão e não concede acesso ao sistema de ficheiros, a argumentos nem ao ambiente — pelo que um plugin não consegue chegar a nenhuma capacidade 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 da linguagem do guest, e assim esconderia um plugin cuja própria saída não é reprodutível, em vez de deixar que isso se manifeste como saída diferente. Um plugin cujo resultado depende da entropia é um problema de determinismo ao nível da autoria, e esta configuração foi construída para o revelar e não para o mascarar.
Autoria contra o host: o PDK. Os autores de plugins não escrevem à mão o ABI de memória Wasm. O Aggrega disponibiliza um Plugin Development Kit em três linguagens — Go, Rust e TypeScript —, wrappers finos 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 é a base sobre a qual constrói um autor de plugins.
Onde corre cada socket. Todos os sockets correm através do mesmo host: o linter de publicação com aggrega lint; os papéis de governação, os providers de renderização e os passos de pipeline da Recipe e da FeatureRecipe durante o aggrega build; os parsers onde quer que seja lido um formato externo; os importadores com aggrega import; e os plugins de CLI como comandos de nível superior. Consulte Estado da linguagem para a prontidão de cada socket.
Que plugins ficam fixados e quais o ambiente escolhe. O Aggrega divide os plugins consoante alterem ou não a saída que se entrega. Os plugins que moldam a saída — os providers de renderização, os plugins de governação associados a um papel de transformação (label-transform, annotation-transform) e os passos de pipeline da FeatureRecipe e da Recipe — são fixados no lockfile da release quando se executa aggrega pull, e reproduzidos byte a byte em aggrega build e aggrega serve apenas a partir desse lockfile. Dois tipos não são fixados, porque um build lê cada um do mesmo sítio de todas as vezes: um provider de renderização servido a partir do próprio binário do compilador, e um provider ou passo de pipeline cuja entidade Plugin é escrita num dos diretórios de catálogo do próprio utilizador. Para mudar o plugin que molda a saída que se aplica, é necessário voltar a fazer pull; uma alteração à configuração do workspace depois de um pull não altera a saída de um build até ao pull seguinte. Os plugins de gate — política e lint — julgam um build sem alterar os seus bytes, pelo que são guardados em cache no pull (para que um build ainda os possa executar offline; um que o binário do compilador transporte, ou um escrito num diretório de catálogo do próprio utilizador, é lido daí) mas não fixados: o gate que corre é escolhido pelo ambiente no momento do build, pelo que uma divisão dev-permissiva / CI-estrita é uma escolha comum de configuração e não um novo pull, e trocar de gates nunca altera a saída que um build bem-sucedido emite. Os plugins que atuam apenas sobre a entrada de autoria, como importadores e extensões de CLI, não moldam nenhuma saída de build e não são nem fixados nem parte do conjunto em cache do build.
2. Pipelines de Plugin de FeatureRecipe
As FeatureRecipes associam intenções operacionais abstratas (como a associação de um proxy de segurança ou a injeção de um sidecar) a pipelines de plugins WebAssembly (Wasm) versionados. A equipa de Ops declara aquilo de que uma Feature precisa num destino de provider concreto; o compilador executa o pipeline declarado sobre o grafo IR plano.
Esta associação tem três consequências para o ecossistema:
- Evolução desacoplada. O vocabulário de infraestrutura cresce através 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 disponibilizados como binários Wasm independentes sobre o ABI Wasm estável.
- Versionamento semântico. As FeatureRecipes referenciam plugins Wasm por versão — exata (
:1.0.0) ou um intervalo com acento circunflexo (:^1.0.0, a versão mais alta compatível com ela). Com o intervalo com acento circunflexo, a equipa de Ops fixa uma versão major, recebendo as suas versões minor e patch sempre que o lockfile é resolvido novamente comaggrega pull --upgrade. - Descarregar a complexidade. A geração de CRDs específicos de fornecedores ou a renderização complexa (objetos de política específicos de fornecedores, recursos de encaminhamento nativos do provider) vive em plugins Wasm puros que operam sobre o grafo IR plano, em vez de atravessar declarações de esquema ou lógica de templates dentro das definições de componentes.
Encadeamento de pipelines — separar responsabilidades entre plugins. Um pipeline de FeatureRecipe pode encadear vários plugins Wasm sequencialmente, cada um a receber do compilador o mesmo contexto de nó IR. O esquema habitual divide a responsabilidade para que um único plugin não carregue simultaneamente a intenção semântica de uma feature e o mecanismo físico de interceção de tráfego de um ambiente de destino específico.
Uma cadeia canónica de dois plugins tem este aspeto:
- Um plugin de configuração que emite as regras semânticas da feature (regras de política de segurança, padrões de auditoria, limiares de limitação de taxa). Compreende a intenção da feature; não compreende a malha de interceção de tráfego do ambiente de destino.
- Um plugin de encaminhamento que emite a configuração física da malha que transporta essas regras (CRDs de gateway, patches de injeção de sidecars, regras de firewall). Compreende a malha do ambiente de destino; não compreende a intenção semântica da feature.
Ambos os plugins recebem do compilador, em sequência, o mesmo contexto de nó IR, pelo que se compõem de forma limpa sem acoplamento direto entre si. O compilador orquestra o pipeline; os plugins transportam o conhecimento do domínio.
3. Interceção de tráfego: o destino HTTPRoute
O modelo de extensibilidade do Aggrega tem como alvo a norma HTTPRoute da Gateway API do Kubernetes como artefacto transversal aos providers para a interceção de tráfego ao nível da malha. A biblioteca padrão emite objetos HTTPRoute através da Feature core/http-route, cuja FeatureRecipe helm renderiza uma rota por cada componente anexado; os ambientes de destino que consomem a Gateway API traduzem o HTTPRoute para as suas malhas nativas.
4. Autonomia do Plugin: resolução de etiquetas
Quando os plugins Wasm geram recursos físicos a partir do grafo IR, os SREs precisam de rastrear um Pod do Kubernetes ou um recurso de cloud em execução até à intenção semântica do programador no Aggregate. O modelo de extensibilidade do Aggrega coloca essa tradução inteiramente sob o controlo do autor do plugin Wasm.
O compilador passa o dicionário labels completo do grafo IR para a sandbox Wasm sem o interpretar. O autor do plugin — a equipa de Platform Ops — decide a lógica de mapeamento a partir daí: passar todas as etiquetas literalmente, filtrar por prefixos de domínio específicos (*.aggrega.ai/*) ou mapear as etiquetas do grafo diretamente para os esquemas de etiquetagem nativos do provider (traduzindo uma etiqueta IR em tags da AWS, annotations do Kubernetes ou num mecanismo de metadados específico da cloud). O compilador não impõe restrições sobre a forma como os artefactos gerados são etiquetados.
Esta autonomia mantém a inteligência específica do domínio — que etiquetas importam para a observabilidade, quais correspondem a convenções de etiquetagem nativas, quais são internas à plataforma — dentro da camada de plugins Wasm, onde o ecossistema evolui independentemente da cadência de versões do compilador Go.
5. Extensões de CLI: comandos de runtime
Os sockets acima correm dentro de um build — o compilador despacha-os à medida que analisa, transforma, valida e renderiza um Aggregate. O socket de extensão de CLI é de natureza diferente: corre no terminal, fora de qualquer build, quando um operador escreve aggrega <command>. É assim que a própria superfície de comandos do aggrega cresce sem uma nova versão do núcleo.
O que é uma extensão de CLI. Uma extensão de CLI é um aggrega <command> pronto a usar, contribuído por um plugin Wasm assinado e isolado em sandbox. Adota a mesma postura drop-in, detida pelo guest, que o socket de renderização adota: a lógica de domínio vive inteiramente no guest, e o host Go não contribui com qualquer código por comando. Acrescentar um novo comando de nível superior requer apenas três coisas — um binário .wasm, uma entidade Plugin que declare pluginType: cli (ver Plugin) e um aggrega plugin add cli explícito. O host descobre o comando a partir do autorrelato do plugin instalado; nenhum comando é compilado no binário.
Porque é que um socket de runtime pode fazer o que um socket de build não pode. Como os sockets de tempo de compilação correm durante um build, permanecem com capacidades negadas e determinísticos: o Aggrega é um compilador ahead-of-time, e a mesma entrada tem sempre de produzir a mesma saída (ver Invariantes arquitetónicas). Um plugin de renderização ou de política não pode, por isso, chegar à rede, ler o relógio ou fazer streaming para o terminal — qualquer coisa que varie entre execuções quebraria essa garantia. Uma extensão de CLI corre depois e fora dessa fronteira, conduzida por uma pessoa num prompt e não pelo pipeline determinístico. É precisamente por isso que um plugin de CLI pode fazer streaming da saída padrão e do erro padrão enquanto corre e devolver um código de saída do processo: não há nenhum artefacto de build cuja estabilidade byte a byte esses efeitos possam ameaçar.
Instalar, executar e descobrir. aggrega plugin add cli <query> procura no registo configurado um plugin cli correspondente, verifica-o face à política de confiança do registo e instala-o como comando de nível superior — imprimindo primeiro as capacidades declaradas do plugin, para que o operador confirme exatamente o que o comando está autorizado a fazer antes de ser instalado. Uma vez instalado, aggrega <command> executa-o como qualquer comando incorporado. Um plugin de CLI declara os seus comandos e as respetivas flags no seu autorrelato describe(), e o host apresenta as flags de cada comando em aggrega help <command> exatamente como o faz para um comando incorporado, pelo 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 registos configurados — --kind plugin --plugin-type cli restringe os resultados a plugins de CLI instaláveis, e uma pesquisa sem filtro abrange entidades de 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 de CLI parte de uma base fixa que todos os comandos recebem sem declaração nem confirmação:
| Capacidade de base | Concedida |
|---|---|
| Argumentos da linha de comandos (entrada) | Sempre |
| Saída padrão e erro padrão em streaming | Sempre |
| Código de saída do processo (saída) | Sempre |
Tudo o que vai além da base está desativado por predefinição. Um plugin que precise de mais declara explicitamente cada capacidade adicional, e o host só a concede depois de a mostrar no momento da instalação para que o operador a confirme. Uma classe de capacidades acrescentada para além da base — acesso ao ambiente, ao sistema de ficheiros ou à rede, entrada interativa — é concedida por trás da mesma barreira de declarar e confirmar, para que um comando nunca possa adquirir silenciosamente um alcance que o operador não aprovou.
Os comandos incorporados prevalecem sempre. Um plugin instalado nunca pode sobrepor-se a um comando incorporado. Uma proteção de nomes reservados, apoiada numa lista de recusa, protege os comandos incorporados e um conjunto de nomes reservados para comandos incorporados, e uma colisão é recusada na instalação em vez de lhe ser permitido substituir o comportamento do núcleo. A superfície de comandos de que um operador depende mantém-se estável independentemente do que for instalado por cima.
6. Plugins de parser: ler formatos externos
O compilador precisa regularmente de ler texto escrito num formato que não foi ele a produzir — um módulo Terraform em HCL, um ficheiro de configuração em TOML, um manifesto em YAML ou JSON. O socket de parser fornece essa capacidade de leitura sem ensinar ao núcleo do compilador nenhum formato em particular. Um parser é um plugin sem estado que converte um texto de origem externo numa árvore JSON estruturada: entregam-se-lhe os bytes de um ficheiro HCL e devolve o mesmo conteúdo como um objeto JSON que o resto do pipeline já sabe percorrer. Qualquer parte do compilador que precise de ler um formato que não analisa nativamente pede uma árvore analisada e trabalha a partir daí.
Um formato é uma capacidade, não uma funcionalidade do compilador. Um parser anuncia os formatos que trata como capacidades — parse:hcl, parse:toml, e assim por diante — e o host resolve um parser pelo formato pedido, executa-o e devolve a árvore. É o mesmo modelo drop-in, de capacidades anunciadas, que adotam os providers de renderização e os plugins de CLI: o núcleo do compilador não contém nenhuma lista incorporada de formatos, pelo que acrescentar um é disponibilizar um novo plugin de parser, nunca uma nova versão do núcleo. Os parsers para HCL, TOML, YAML, JSON e JSON com comentários vêm dentro do binário como conjunto inicial; uma empresa que precise de outro formato disponibiliza um plugin de parser que o anuncie.
A seleção do formato é declarativa, nunca adivinhada. O host nunca inspeciona o conteúdo de um ficheiro para decidir o que ele é. Escolhe um formato através de sinais declarados, numa ordem de preferência fixa. Um provider de renderização pode declarar o formato de cada ficheiro que emite, e o host prefere sem mais esse formato declarado pelo produtor — o provider que escreveu os bytes é a autoridade sobre como os ler. Para um ficheiro que o produtor não marcou, o recurso é um mapa fixo de extensões de ficheiro — .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 para o mesmo parser, e um operador consegue saber que parser vai correr sem conhecer os bytes dentro do ficheiro. A deteção pelo conteúdo faria a escolha depender da carga útil, e o Aggrega não o faz.
Um parser é puramente sintático. A saída é uma árvore JSON mais diagnósticos e, opcionalmente, as localizações de origem de onde veio cada nó. Um parser não transporta nenhum significado Aggrega — relata o que o texto diz estruturalmente, nada sobre o que significa como Component, Recipe ou qualquer outra entidade. Converter uma árvore analisada em entidades Aggrega é uma questão separada que vive noutro lugar; a única função do parser é uma tradução fiel de sintaxe para JSON. A direção de leitura é unidirecional no mesmo espírito: um parser lê um formato para uma árvore, não volta a escrever um formato.
Um consumidor: política sobre HCL do Terraform. Uma política da fase de renderização que precise de inspecionar o Terraform que um build produz não aprende HCL por si. O host analisa o artefacto HCL através do socket de parser e entrega ao plugin de política a árvore JSON que este já lê, pelo que a política raciocina sobre dados estruturados no formato que todos os outros sockets recebem. Novos leitores de formatos externos compõem-se da mesma forma — pedir a árvore ao host e depois trabalhar em JSON — pelo que a capacidade do compilador de compreender um formato cresce acrescentando plugins de parser e não fazendo crescer o núcleo.
7. Plugins importadores: rascunhar ficheiros de autoria a partir de origens externas
Uma equipa raramente parte de uma página em branco. A sua arquitetura de agentes muitas vezes já existe noutro lugar — um fluxo Langflow ou Flowise, um workflow n8n, uma aplicação Dify, os servidores MCP com que um cliente está configurado, uma aplicação Compose, os agentes que a configuração de um framework declara. O socket importador converte essa origem externa num ponto de partida para a autoria em Aggrega: lê a origem e cria 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 reveja e conclua, de modo que uma equipa leve o que já tem para o Aggrega em vez de o reescrever à mão. Um importador mapeia o significado — lê o que um nó de origem é e propõe a entidade Aggrega que o representa, ou deixa-o dentro do fluxo que a plataforma rascunhada transporta; o compilador encaminha as entidades emitidas de forma opaca, tal como se mantém 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 trata 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 pedido, executa-o e recebe de volta as entidades que rascunhou. É o mesmo modelo drop-in, de capacidades anunciadas, que o socket de parser adota com parse:<format>: o núcleo do compilador não contém nenhuma lista incorporada de formatos importáveis, pelo que suportar um novo é disponibilizar um plugin importador que o anuncie, nunca uma nova versão do núcleo.
Um importador lê através do socket de parser; não volta a analisar. Um importador precisa da forma estruturada da sua origem, mas não reimplementa a leitura de um formato que o ecossistema já analisa. Quando precisa da árvore, pede ao host que execute o parser correspondente — aquele que o catálogo do workspace serve para a sintaxe da origem ou, quando o catálogo não serve nenhum, aquele que o próprio compilador transporta — através da mesma capacidade de análise mediada pelo host que o resto do pipeline usa, e trabalha a partir da árvore JSON devolvida. A leitura (de sintaxe para árvore) continua a ser função do parser; o mapeamento (de árvore para entidades Aggrega) é do importador. Os dois sockets compõem-se sem se duplicarem: um importador acrescenta a inteligência de mapeamento para uma origem e apoia-se no parser existente para os bytes.
Um formato é reconhecido a partir do que o seu importador declara, nunca adivinhado. Uma importação pode nomear explicitamente o formato da sua origem. Quando não o faz, o formato é reconhecido a partir das assinaturas que cada importador declara no seu autorrelato e que a sua entidade Plugin regista: a sintaxe em que uma origem é lida, os nomes de ficheiro a que uma assinatura se aplica e os caminhos que a árvore analisada tem ou não de conter. O host não conhece nenhum formato próprio. Analisa a origem através do parser que o catálogo do workspace serve para cada sintaxe que uma assinatura nomeia — ou o do próprio compilador, quando o catálogo não serve nenhum —, avalia os predicados declarados sobre a árvore devolvida e lê a origem como o formato do único importador cuja assinatura corresponde. As assinaturas declaradas ocupam o lugar que um mapa fixo de extensões de ficheiro ocupa para o socket de parser, porque os formatos que uma importação lê podem partilhar uma extensão — uma exportação Langflow, uma exportação Flowise e um workflow n8n são todos ficheiros JSON. Uma origem a que nenhuma assinatura corresponde é recusada, pedindo o formato e nomeando os formatos que os importadores anunciam — ou, no caso de um diretório, pedindo um dos seus ficheiros isoladamente ou um formato cujo importador declara padrões de ficheiro, nomeando apenas esses; uma origem a que correspondem assinaturas de mais do que um formato é recusada, nomeando-os. O reconhecimento não lê nada além da origem e não acede a nenhuma rede, pelo que reconhecer um novo formato é uma declaração que o novo importador disponibiliza, nunca uma alteração ao host. As regras para escrever uma assinatura estão em O socket importador.
Um diretório é lido através dos ficheiros que o seu importador declara. Uma origem é um ficheiro ou um diretório. Um ficheiro é entregue inteiro ao importador. Um diretório é lido em origens nomeadas — exatamente os ficheiros dele que os padrões de ficheiro das assinaturas do importador selecionam, cada um nomeado pelo seu caminho dentro do diretório, por ordem — e nenhum outro ficheiro do diretório é aberto; uma ligação que levaria a leitura para fora do diretório é recusada antes de qualquer leitura. Um importador que não declara padrões de ficheiro lê um único ficheiro e recusa um diretório, e um diretório que não contenha nenhum ficheiro que os padrões de um importador selecionem também é recusado. Os importadores Langflow, Flowise, n8n, Dify e Agent Framework do compilador não declaram nenhum, pelo que cada um lê um único ficheiro de fluxo, workflow ou aplicação exportado, ou um único agente declarativo; o seu importador MCP declara os nomes de ficheiro das configurações de clientes MCP que lê, pelo que o diretório de um projeto é lido através das configurações que contém; o seu importador Compose declara os nomes de ficheiro que o Compose lê por predefinição, pelo que o diretório de um projeto é lido através do seu ficheiro Compose e do ficheiro de override que o Compose funde por cima dele; e o seu importador CrewAI declara os nomes de ficheiro sob os quais um projeto CrewAI declara os seus agentes e tarefas, pelo que o diretório de um projeto é lido através dessas declarações e o seu programa nunca é lido; e o seu importador LangGraph declara langgraph.json, pelo que o diretório de uma aplicação é lido apenas através da sua configuração, sem nunca ler o seu código nem os seus ficheiros de ambiente, e um ficheiro de ambiente que a configuração nomeie só chega ao importador quando o with.sources da sua associação lho entrega, e então apenas para os nomes das variáveis; e o seu importador Google ADK declara root_agent.yaml, pelo que o diretório de uma aplicação é lido apenas através da configuração do seu agente raiz, as configurações que os seus subagentes nomeiam só chegam ao importador quando o with.sources da sua associação lhas entrega, e nem o seu código nem o seu ficheiro de ambiente são alguma vez lidos.
O mapeamento é determinístico, pontuado por confiança e ponderado face ao catálogo do próprio utilizador. O host entrega ao importador uma vista dos Components que o próprio catálogo do workspace contém — o catálogo de onde o importador foi selecionado — as pastas de catálogo do workspace ou, quando este não indica nenhuma, o instantâneo do catálogo que o seu registo predefinido publica — os Components de um catálogo empresarial exatamente como os da biblioteca padrão. A vista transporta o nome, a versão e as etiquetas de cada Component, os nomes das chaves que os seus values e provides declaram e os seletores dos seus sockets, e nunca um valor, uma predefinição ou um segredo; nada é obtido para ela além desse instantâneo, e a sua ordem é fixa, pelo que um catálogo produz uma única vista. Um importador construído sobre o pacote de importadores do PDK de Go — entre eles os próprios importadores Langflow, Flowise, n8n e Compose do compilador — pondera cada nó da origem face a esses Components e a nada mais, com um modelo de confiança determinístico que não usa nenhum modelo, e regista a decisão — os candidatos que ponderou, o nível de correspondência que atribuiu e a escolha que fez — como sugestões revisíveis que um autor pode ler e rever. Um Component que o catálogo ganhe é um candidato na importação seguinte, sem reconstruir nenhum importador. A predefinição é apenas sugestões: a importação propõe e o autor decide. Uma correspondência de alta confiança pode ser escrita como referência a um componente existente do catálogo em vez de um corpo rascunhado de raiz, mas apenas quando o operador o ativa explicitamente — sempre como sugestão explícita e reversível que o autor controla, nunca como reescrita silenciosa. Como a pontuação não envolve nenhum modelo nem nenhuma consulta em tempo de execução, a mesma origem pontuada face ao mesmo catálogo produz sempre as mesmas sugestões.
Um fluxo é rascunhado como a plataforma que o executa. Um fluxo Langflow, um chatflow Flowise e um workflow n8n correm numa plataforma, e por predefinição uma importação rascunha essa plataforma em vez dos nós do fluxo: 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 transporta o fluxo tal como foi exportado no seu valor flow_definition, que a plataforma carrega na implementação. Cada parte do fluxo que um socket da plataforma aceita — nas plataformas da biblioteca padrão, um modelo, um servidor MCP ou outra ferramenta acedida por HTTP, e um armazenamento vetorial — torna-se um Component próprio, referenciado ou rascunhado conforme o mapeamento decidir, e é ligado a esse socket sob o uses da plataforma. Assim, cada chamada que o fluxo faz a um modelo, a uma ferramenta ou a um armazenamento é uma ligação que o Aggregate declara: um plugin de governação que avalia o grafo vê-a como vê qualquer outra aresta, e a allowlist de egress da biblioteca padrão, que a definição attach_egress_allowlist associa à plataforma, permite à plataforma ligar-se apenas ao que as suas ligações alcançam, aos seus próprios pods e ao DNS do cluster. Onde o formato o permite, o rascunho escreve no fluxo transportado aquilo que faz o fluxo chegar a cada parte através da sua ligação. Todos os outros nós — um agente, uma chain, um trigger — ficam dentro do fluxo transportado e não se tornam Component, registando a sua decisão os candidatos face aos quais foi ponderado. Uma aplicação Dify é rascunhada da mesma forma, na forma que uma instalação completa assume: uma entrada da instalação Dify que a biblioteca padrão monta, core/dify, que transporta a aplicação no seu parâmetro app_definition, ligando a instalação as suas próprias ligações. A definição layout da associação do importador escolhe o rascunho: platform, a predefinição, ou nodes, que rascunha cada nó da origem como um Component próprio, cada aresta do fluxo uma ligação uses, e não transporta nenhum fluxo. A plataforma que transporta o fluxo explica que nós se tornam partes e onde cada um é ligado.
Um framework code-first é lido através da sua configuração declarada, nunca do seu programa. CrewAI, LangGraph, Google ADK e Agent Framework guardam o comportamento de uma aplicação no seu programa e declaram os seus agentes, grafos e modelos em configuração ao lado dele. Os seus importadores leem apenas essas declarações — os ficheiros 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, ligado ao que as declarações nomeiam: o modelo que um agente pede, onde o socket model do agente o aceita, e o datastore em que um checkpointer LangGraph guarda o estado. Um servidor MCP que um agente do Agent Framework nomeia é acedido pelo fornecedor do modelo, como ferramenta alojada, pelo que o rascunho o nomeia em comentários e não lhe liga nada. O programa corre na imagem que a Release nomeia. Aquilo que só o programa diz — a lógica de uma tarefa, uma ferramenta que o seu código define, um agente que o seu código constrói — é nomeado nos comentários e decisões do rascunho e não se torna Component; levá-lo para ficheiros de autoria é trabalho do autor, à mão ou com um assistente de IA que escreve em nome do autor através de aggrega mcp, que lê a referência e cria e valida entidades.
O que uma origem declara sobre como as suas partes correm vai parar a um rascunho de Release. Cabe à Release fornecer as entradas operacionais, pelo que os importadores MCP, Compose, CrewAI, LangGraph, Google ADK e Agent Framework rascunham uma Release ao lado do Aggregate, cujo spec.aggregate o nomeia: a Release transporta o que a origem declara — a linha de comandos 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 origem declara e nenhuma chave do Component rascunhado aceita, como os volumes de um serviço ou o ambiente de uma configuração. O que nenhuma origem declara — a imagem que executa o programa de um framework, a credencial que uma ligação apresenta, o metadata.environment e o spec.manifest da Release — é nomeado num comentário no sítio a que pertence, para o operador fornecer, e o build interrompe-se nomeando aquele de entre a imagem, o ambiente e o manifesto que ainda não esteja 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 executa ou a sua conta de proprietário, o endereço de cada servidor MCP ligado e a credencial que cada ligação apresenta.
Um valor de credencial que uma origem contém é transportado tal como está escrito, a menos que se peça a sua remoção. Um importador localiza todos os valores da sua origem que podem transportar 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 sendo credencial mas que pode ainda assim transportar uma, como os cabeçalhos de um pedido. Por predefinição, nenhum é escrito vazio: cada valor que contenha algo é transportado tal como está escrito — no fluxo ou na aplicação que a plataforma transporta, ou no rascunho de Release — e nomeado num aviso credential-carried pelo sítio onde está — o seu nó, servidor, serviço ou agente, e o seu campo — nunca pelo seu valor, juntamente com o valor da definição que o escreve vazio. A definição empty_credentials ativa a remoção, uma classe de cada vez: marked escreve vazio o que um formato marca como credencial e todos os membros da configuração de um servidor MCP, e all também as entradas marcadas como não sendo credencial, sendo cada valor escrito vazio reportado com credential-emptied. O que o rascunho escreve para que um fluxo chegue à sua ligação é cablagem, escrita independentemente do que a definição diga, e uma ligação no rascunho não transporta nenhuma credencial: a Release associa aquela que cada ligação apresenta. Um ficheiro para o qual uma origem apenas aponta, como um ficheiro de ambiente, é lido apenas para os nomes das suas variáveis, quando chega a ser lido, e um rascunho feito nó a nó não lê nenhum valor. O que fica fora dos sítios que um importador localiza — o código de um componente personalizado, um prompt — cabe ao autor rever antes de partilhar um rascunho, como explica Valores de credenciais que o fluxo 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 através do pedido aggrega/import da sua sessão, e um assistente de IA através da ferramenta import de 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 do núcleo do compilador: aquele que uma associação plugins.importer nomeia, quando nomeia um que anuncie 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 nenhum associado, interrompem a importação, nomeando ambos, como explica Que importador converte uma origem em rascunhos. Os três reportam as decisões de mapeamento ao lado dos rascunhos. O comando imprime no erro padrão uma linha por nó mapeado, nomeando o Component ou o rascunho escolhido para ele, se é referenciado ou rascunhado, o nível de correspondência e, quando o importador ponderou 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 transportam cada decisão na íntegra. Assim, um autor vê onde a importação fez suposições, em qualquer superfície que a tenha executado, sem abrir os rascunhos. --format nomeia explicitamente o formato da origem — 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 ficheiros de scaffold que a importação produziu sob a raiz do workspace, ou sob o diretório que --output-dir nomeia; --dry-run faz tudo o que o comando faz exceto escrever, devolvendo os ficheiros rascunhados como conteúdo e nomeando o ficheiro a que cada um se destina, para que um autor possa rever o scaffold antes de enviar o que quer que seja para a árvore de trabalho.
Os importadores do núcleo. Os importadores do núcleo que o compilador disponibiliza leem estes formatos, um importador para cada:
- Langflow — um fluxo exportado do Langflow, rascunhado como a plataforma Langflow da biblioteca padrão que transporta o fluxo, com cada parte dele que um socket aceita ligada a esse socket.
- Flowise — um chatflow ou um agentflow exportado do Flowise, rascunhado como a plataforma Flowise da biblioteca padrão que o transporta, com cada parte dele que um socket aceita ligada a esse socket.
- n8n — um workflow exportado do n8n, rascunhado como a plataforma n8n da biblioteca padrão que o transporta, com cada parte dele que um socket aceita ligada a esse socket.
- Dify — uma aplicação exportada do Dify, rascunhada como a instalação Dify que a biblioteca padrão monta, que transporta a aplicação, com os modelos, ferramentas e bases de conhecimento que nomeia reportados como configurados dentro do Dify.
- MCP — a configuração de um cliente MCP ou a descrição de servidor de um registo MCP, com cada servidor rascunhado como uma instância da ferramenta MCP da biblioteca padrão, e uma
Releaseque transporta a linha de comandos, 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 a que a sua imagem corresponde — através de uma tabela que o importador transporta, gerada a partir das Recipes e dos Components Compose do catálogo padrão quando é construído — ou como um servidor genérico que executa a sua imagem, com uma
Releaseque transporta a imagem e a porta de cada servidor genérico e, em comentários, as portas, volumes e ambiente que cada serviço declara. - CrewAI — os agentes que um projeto CrewAI declara nos seus ficheiros de configuração, cada um rascunhado como o agente CrewAI da biblioteca padrão que transporta o seu papel, objetivo e história de fundo e ligado ao modelo que nomeia, com as tarefas e ferramentas do projeto reportadas como pertencentes ao seu programa, o próprio programa nunca lido, e uma
Releaseque deixa a imagem que o executa para o operador nomear. - 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 transporta o caminho de importação do seu grafo e ligado ao datastore em que o seu checkpointer guarda o estado, com uma
Releaseque indica, num 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 ligado ao modelo que nomeia quando o ADK envia os pedidos desse modelo à API Gemini, sendo um modelo alcançado de qualquer outra forma — através de uma string de modelo LiteLLM, por exemplo — nomeado num comentário e a sua ligação deixada ao autor, com uma
Releaseque deixa a imagem que executa a aplicação para o operador nomear, 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 ligado ao modelo OpenAI que nomeia, com cada servidor MCP que nomeia escrito em comentários, uma vez que o fornecedor do modelo acede a ele como ferramenta alojada, com uma
Releaseque transporta o endpoint do modelo e, num comentário, o endereço de cada servidor, e o código da aplicação nunca lido.
São plugins importadores como quaisquer outros — a inteligência de mapeamento específica do formato vive neles, não no núcleo —, construídos a partir do código-fonte do compilador e publicados com cada versão do compilador, com o número dessa versão. Nenhum é compilado no binário: o binário transporta a entidade Plugin de cada um e o digest do único módulo que aceita, pelo que cada um serve o seu formato em todos os workspaces sem entrada de catálogo. A primeira importação que precise de um que a máquina não tenha obtém-no a partir do registo predefinido do workspace, confronta-o com esse digest, verifica-o tal como um pull verifica um plugin que obtém — a sua assinatura segundo a política de confiança desse registo e as funções de host que usa — e guarda-o na cache de conteúdos do workspace; todas as importações posteriores leem-no daí, sem acederem à rede para ele. Uma importação não fixa nenhum importador: nada mais é escrito para ele — nenhuma entrada de lockfile e nenhum registo de plugins de confiança — e nenhum pull o guarda em cache e nenhum build o lê. Um módulo que não passe a verificação é recusado, e nada é guardado. Quando o módulo não pode ser obtido — o workspace está offline, o seu registo não está acessível, ou o registo não o contém — a importação interrompe-se, nomeando o importador, a sua versão e o que coloca o seu módulo na máquina. A escolha continua a ser do workspace: um importador que o seu catálogo contenha sob outro nome para um destes formatos corre quando uma associação plugins.importer o nomeia, e um com o mesmo nome e versão que um importador do núcleo corre no seu lugar.
Semear e fazer crescer um catálogo
Um catálogo não tem de 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 origem externa para ficheiros de autoria em rascunho. aggrega import <file or directory> lê uma origem declarativa de definição de agentes — um fluxo Langflow ou Flowise, um workflow n8n, ou a configuração de um cliente MCP ou a descrição de servidor de um registo — 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 cria YAML de Aggregate e Component em primeiro rascunho e, a partir de uma origem MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework, um rascunho de Release, para que um autor reveja e conclua, de modo que uma equipa leve consigo o que já tem em vez de o reescrever à mão. Para cada nó de um fluxo, e cada serviço de uma aplicação Compose, pontua os Components do próprio catálogo do workspace — os de um catálogo empresarial tanto como os da biblioteca padrão — com um modelo de confiança determinístico que não usa nenhum modelo, e regista a decisão — os candidatos que ponderou, o nível que atribuiu e a escolha que fez — como sugestões revisíveis, que o comando, o editor e o assistente reportam; uma correspondência de alta confiança pode ser escrita como referência de catálogo quando o operador o ativa explicitamente, sempre como sugestão explícita e reversível que o autor controla e não como reescrita silenciosa. Cada Component que um catálogo ganha é um candidato que a importação seguinte pondera. A inteligência de mapeamento específica do formato vive num plugin importador: os próprios importadores Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK e Agent Framework do compilador servem esses formatos em todos os workspaces, obtidos e verificados na primeira utilização, e um catálogo acrescenta um formato contendo um plugin importador que o anuncie. Uma origem em diretório é lida através dos padrões de ficheiro que o seu importador declara; os importadores Langflow, Flowise, n8n, Dify e Agent Framework não declaram nenhum, e cada um lê um único ficheiro exportado ou agente declarativo, enquanto o importador MCP lê as configurações de cliente que um diretório contém, o importador Compose os seus ficheiros Compose, fundidos como o Compose os funde, o importador CrewAI as declarações de um projeto, nunca o seu programa, o importador LangGraph a configuração de uma aplicação, nunca o seu código nem um ficheiro de ambiente — cujos nomes só lê quando a sua associação lhe entrega o ficheiro — e o importador Google ADK a configuração do agente raiz de uma aplicação, nunca o seu código nem o seu ficheiro de ambiente, sendo as configurações dos seus subagentes lidas quando a sua associação lhas entrega — uma configuração que o ADK declara ser experimental, cujos agentes usam por predefinição um modelo Gemini e chegam pelo nome aos modelos de outros fornecedores através de classes do próprio ADK, ou através de uma string de modelo LiteLLM.
A maior parte do trabalho com plugins são templates, não código compilado. Uma grande parte das features apenas injeta um sidecar, uma variável de ambiente ou uma etiqueta estáticos — um simples JSONPatch sem lógica condicional. Um único plugin patcher configurável, escrito uma vez para receber um template JSONPatch declarativo como entrada with, pode cobrir esse caso comum sem um binário compilado único por feature: o autor escreve um template e, para muitos destinos do tipo CRD, um template valuesMapping (muitas vezes a referenciar fragmentos partilhados numa entrada de MappingLibrary) basta por si só. Os plugins PDK escritos de propósito destinam-se ao restante verdadeiramente condicional.
Tomar como referência ferramentas estabelecidas. Ao escrever nova lógica de plugins, os autores podem consultar as formas de saída publicamente documentadas de ferramentas open source estabelecidas — a estrutura dos CRDs, patches ou templates que essas ferramentas reconhecidamente emitem — como referência para a forma de destino que um novo plugin tem de produzir, respeitando a licença de cada projeto. Webhooks de injeção de sidecars, bibliotecas de constructs de nível superior, geradores de CRDs de operadores e catálogos de traits ou de composição publicam todos estruturas de saída que correspondem de perto ao que uma FeatureRecipe ou um plugin comparável precisa de emitir. O objetivo é corresponder a um contrato de saída bem compreendido, não copiar a implementação de nenhum projeto.