Versão 1.0.0-alpha.1mais recente
Capítulo 2.18
O modelo de extensões
As seis formas de estender o Nexus, desde uma definição até um pacote de domínio, os limites de cada uma e como os níveis de confiança e isolamento decidem onde o seu código é executado. Leia isto antes de abrir o kit de desenvolvimento de software (SDK).
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

A primeira coisa que construí no Nexus na Corrán Orbital não foi um plugin. A nossa equipa de dinâmica de voo queria que o assistente respondesse «que passagens de estações terrestres perdemos se a antena de Svalbard ficar inoperacional para manutenção?» sempre no mesmo formato, primeiro com a tabela de passagens e por baixo o custo em minutos de contacto. Passei meio dia a ler o kit de desenvolvimento de software (SDK) antes de um colega me alertar que o que eu queria era uma competência (skill): uma pasta com um SKILL.md lá dentro, carregada no Skills Engine e publicada assim que os testes passassem e um revisor a aprovasse. Demorou quarenta minutos.
Dois plugins e um pacote de domínio depois, esse continua a ser o primeiro conselho que dou. O Nexus tem seis formas de ser expandido, organizadas numa escada de esforço. Os degraus mais económicos fazem mais do que as pessoas esperam, e os mais dispendiosos acarretam obrigações que são fáceis de subestimar. Este capítulo apresenta essa escada. Escolha o degrau mais baixo que resolva o problema. Os capítulos seguintes aprofundam cada um deles: capítulo 2.19, As regras que todas as extensões herdam; capítulo 2.20, Competências (Skills); capítulo 2.21, O SDK de Plugins; capítulo 2.22, O tempo de execução dos plugins; e capítulo 2.23, Pacotes de domínio.
Os seis blocos de construção
Aqui estão eles, pela ordem em que os deve considerar.
- Definições e políticas. São valores que um administrador configura na consola para a organização, para uma unidade ou para uma pessoa, dentro do que a licença permite. Não escreve qualquer código.
- Competências do Skills Engine. Um pacote
SKILL.mdque contém instruções e as ferramentas que a competência pode invocar, acompanhado de ficheiros e scripts opcionais. O assistente, os agentes, os fluxos de trabalho e os botões de IA (inteligência artificial) nos ecrãs executam todos as mesmas competências, tal como o seu IDE (ambiente de desenvolvimento integrado). - Plugins. O seu próprio código, declarado por um manifesto e compilado com as ferramentas do SDK. Um plugin apresenta-se num de três níveis:
skills-only,ui-onlyoufull-service. - Pacotes de domínio. As lentes e os modelos de um setor, as suas competências e modelo de conhecimento, os seus conectores e os seus ecrãs de telemóvel, licenciados como uma unidade. A Adverant disponibiliza dez; pode construir o seu próprio.
- Lentes. O que uma função vê dentro de um pacote ou de uma plataforma. Uma lente restringe uma lente base e nunca a alarga.
- Ligações e conectores MCP. As ferramentas do Model Context Protocol (MCP) que um plugin publica ou através das quais uma ferramenta de programação de IA se liga, e os conectores só de leitura que importam registos a partir de sistemas que já utiliza.
Há duas expressões que se confundem facilmente, pelo que convém clarificá-las já. Uma competência do Skills Engine é um pacote SKILL.md na biblioteca. Uma competência de manifesto é uma linha tipada na matriz skills[] de um plugin, compilada no registo de competências da plataforma e executada através do UNO, o motor de fluxos de trabalho. Ambas são designadas por competências (skills) no ecrã. São escritas e geridas de forma diferente, e esta documentação especifica sempre a qual delas se refere.
O que cada um pode fazer e o que não pode
A tabela é a versão resumida. Incluí a coluna «O que não pode fazer» de propósito: cada limite é uma propriedade da arquitetura, e cada um deles já me salvou de algum problema.
| Bloco de construção | O que pode fazer | O que não pode fazer | Quem o cria |
|---|---|---|---|
| Definição ou política | Alterar o comportamento de uma funcionalidade a qualquer nível, desde a organização até uma pessoa; bloquear um valor; delegá-lo em níveis inferiores; exigir uma segunda pessoa numa alteração | Adicionar um ecrã ou uma rota, armazenar uma nova tabela ou iniciar um novo tipo de trabalho | Um administrador, na consola |
| Competência do Skills Engine | Dar ao assistente e aos agentes, aos fluxos de trabalho e aos botões de IA uma forma repetível de executar uma tarefa, com as suas próprias instruções e casos de teste | Guardar uma credencial; invocar uma ferramenta fora da lista de permissões da pessoa que a executa (SKILL_CANNOT_WIDEN_TOOLS); entrar em produção sem os respetivos testes e aprovação |
Qualquer pessoa com a devida permissão, no criador ou a partir do seu IDE |
Plugin, skills-only |
Publicar competências de manifesto que são executadas na plataforma: callbacks do anfitrião, trabalho em fila, mapeamentos sobre uma lista e, no nível de confiança core ou verified, competências suportadas por modelos |
Servir páginas próprias | Um programador, com o SDK |
Plugin, ui-only |
Adicionar uma superfície de frontend dentro da shell | Armazenar dados próprios ou executar processamento | Um programador, com o SDK |
Plugin, full-service |
O seu próprio backend e frontend, um esquema Postgres, uma tabela de rotas com permissões, bem como competências e ferramentas MCP | Invocar um fornecedor de modelos; guardar uma chave de modelo; ler linhas de outra organização, exceto através de uma concessão registada; executar processamento fora do despacho do UNO | Um programador, com o SDK |
| Pacote de domínio | Disponibilizar as lentes e os modelos de um setor, as suas competências e fluxos de trabalho, um modelo de conhecimento, um mapa de evidências e ecrãs de telemóvel às unidades que um administrador escolher | Alterar a shell ou os seus componentes, ou as regras de escrita; ser executado sem que a licença da organização o inclua | A Adverant, ou os seus próprios programadores na edição Enterprise |
| Lente | Escolher os cartões e os campos que uma função vê dentro de um pacote ou plataforma, e as ações que disponibiliza | Mostrar qualquer elemento que a sua lente base oculte (LENS_CANNOT_WIDEN); alterar o que uma função tem permissão para fazer |
O autor de um pacote constrói-a; um administrador concede-a por unidade |
| Ferramentas e conectores MCP | Expor as ferramentas de um plugin a agentes e ferramentas de programação; ler registos de um sistema de apólices ou de um arquivo de telemetria para o modelo de conhecimento | Escrever de volta no sistema de origem através de um conector; agir para além das permissões da própria pessoa com sessão iniciada | Um programador declara ferramentas MCP; um administrador configura conectores |
Algumas destas células merecem uma frase adicional.
As definições são uma estrutura (framework), e todos os plugins utilizam a mesma. Um plugin que declare um bloco settings no seu manifesto obtém os níveis (plataforma, organização, pacote, unidade, grupo, repositório, pessoa), bloqueios e delegação, um registo de alterações e aprovação por uma segunda pessoa, tudo sem necessidade de escrever uma tabela de definições. É por isso que o degrau mais económico é muitas vezes suficiente: se o comportamento que pretende já existe e apenas precisa de um valor diferente para a unidade de Rotterdam, trata-se de uma definição.
Uma competência do Skills Engine é executada em nome da pessoa. Nunca guarda uma chave, apenas pode aceder a ferramentas dentro da lista de permissões de quem a executa e ler apenas o que essa pessoa tem permissão para abrir. Uma competência que adicione uma ferramenta de escrita fica retida até que duas pessoas a aprovem, entrando depois em produção em modo sombra (shadow), de seguida em modo canário (canary) e, por fim, para todos.
Um plugin skills-only é o degrau intermédio. Precisa dele quando o trabalho consiste em código próprio: um cálculo determinístico, um worker de fila, uma distribuição (fan-out) sobre uma lista. A plataforma invoca o seu código; o seu código nunca invoca um modelo.
Um plugin full-service é um pequeno produto. Possui um esquema Postgres, uma tabela de rotas com um registo de permissões, um frontend, um conjunto de funções de base de dados e todas as obrigações de isolamento descritas no capítulo 2.19, As regras que todas as extensões herdam. É a resposta certa mais vezes do que as pessoas receiam e a resposta errada mais vezes do que as pessoas esperam.
De qual preciso?
Comece no topo desta tabela e pare na primeira linha que se adequar.
| Pretende… | Utilize | Por que não algo mais simples |
|---|---|---|
| Alterar um valor ou um limite, ou quem pode fazer algo | Uma definição ou uma política | Não existe nada mais simples |
| Fazer com que o assistente execute uma tarefa sempre da mesma forma | Uma competência do Skills Engine | Uma definição não pode conter instruções |
| Colocar um «botão de IA» num ecrã que execute essa tarefa | Uma competência do Skills Engine associada ao botão | Um botão apenas executa competências; não há nada para desenvolver |
| Permitir que uma ferramenta de programação de IA aceda ao Nexus | Uma ligação MCP através do Workbench | Não há nada para escrever; a pessoa inicia sessão através do navegador |
| Ler registos de um sistema existente para o modelo de conhecimento | Um conector só de leitura | Um conector não escreve nada de volta, pelo que não acarreta risco de escrita |
| Executar código determinístico próprio no agendamento da plataforma | Um plugin skills-only com uma competência host_callback ou plugin_queue |
Uma competência do Skills Engine não pode executar o seu código |
| Adicionar um ou dois ecrãs dentro da shell | Um plugin ui-only |
Apenas os plugins adicionam ecrãs |
| Manter os seus próprios registos protegidos pelas suas próprias rotas e permissões | Um plugin full-service |
Apenas este nível possui um esquema próprio |
| Dar a uma função uma vista mais restrita dos ecrãs de um setor | Uma lente num pacote existente | Uma lente consiste em dados, não em código |
| Disponibilizar o modelo de conhecimento e as lentes de um setor, com ecrãs de telemóvel, a várias unidades | Um pacote de domínio | Um plugin isolado não tem lentes nem controlo de licença |
Na Corrán Orbital, a questão do planeamento de passagens manteve-se como uma competência do Skills Engine. A propagação orbital de que necessita tornou-se num plugin skills-only com uma competência host_callback, porque o cálculo numérico é nosso e tem de dar a mesma resposta duas vezes. O nosso comité de revisão de anomalias tornou-se num plugin full-service, porque mantém os seus próprios registos de quem analisou cada desvio de telemetria e o que foi decidido. O pacote surgiu em último lugar, quando uma segunda unidade quis a mesma coisa.
Como as peças se combinam
Os blocos de construção compõem-se de forma ascendente. Um pacote de domínio é o exemplo mais claro, porque é um conjunto dos outros blocos mais um controlo de licença:
- um modelo de conhecimento, os tipos de elementos que o setor conhece e a forma como se interligam, muitas vezes construído sobre um modelo base de outro pacote;
- lentes, uma por função, cada uma restringindo uma lente base;
- modelos e fluxos de trabalho, bem como as competências do Skills Engine que invocam;
- plugins nos casos em que o pacote necessita de código próprio;
- conectores só de leitura para os sistemas que já detêm os registos;
- uma sobreposição móvel que define que cartões e passos de recolha aparecem nos telemóveis;
- e a atribuição de direitos (entitlement): os grupos de funcionalidades que a licença tem de incluir antes que qualquer um destes elementos seja ativado.
Nada disto é infraestrutura específica de cada aplicação. O pacote não inclui código de isolamento próprio, nem cliente de modelo, nem verificação de licença: herda os da plataforma. Esse é o tema do próximo capítulo, e é a razão pela qual o autor de um pacote num banco e outro num porto escrevem a mesma quantidade de código de segurança, que é nenhuma.
Níveis de confiança
Cada plugin declara um nível trust no seu manifesto. A confiança não é uma barreira que o SDK consiga contornar. Trata-se de metadados consultivos que a plataforma lê para decidir o grau de isolamento com que as contribuições de um plugin são executadas e os dados mais sensíveis em que as suas competências podem tocar. Os controlos ativos (classificação e residência, exportação e despesa) permanecem exatamente onde estão.
| Confiança | A quem se destina | Postura de isolamento | Limite máximo de classificação |
|---|---|---|---|
core |
Código próprio (first-party) fornecido com a plataforma | none: mesma origem (same-origin), sem isolamento adicional |
restricted |
verified |
Um terceiro revisto, um editor verificado | Superfície same-origin, competências intermediadas |
restricted |
community |
Um terceiro não revisto; a predefinição para um novo plugin | Superfície sandboxed, competências intermediadas |
tenant |
untrusted |
Qualquer elemento de uma origem desconhecida | strict: superfície em sandbox, apenas competências intermediadas, sem confiança no anfitrião |
public |
Dessa tabela decorrem duas regras, e o create-nexus-plugin validate aplica ambas antes de qualquer compilação.
Em primeiro lugar, a classification de uma competência não pode exceder o limite máximo do seu plugin. As classificações ordenam-se como public, depois tenant e depois restricted. Um plugin community que declare uma competência restricted falha na compilação.
Em segundo lugar, apenas os plugins core e verified podem declarar competências que acedam ao AI Provider Router. Esses são os níveis tool_using e llm_only. Um plugin community ou untrusted negoceia trabalho determinístico (host_callback, plugin_queue e map sobre estes) e pede à plataforma que faça tudo o que necessite de um modelo. O meu primeiro plugin era community, e perdi uma tarde a tentar declarar uma competência de resumo llm_only antes de perceber que a recusa era mesmo o objetivo.
Se omitir trust, o SDK trata o plugin como community. Um campo omitido nunca pode resultar numa promoção.
Níveis de isolamento 1 a 4
Separadamente da confiança, o bloco runtime do manifesto indica como o plugin é executado. isolationLevel é um número inteiro de 1 a 4, e o modo de execução decorre dele. Não escolhe os dois de forma independente: o validador deriva um do outro e recusa um manifesto cujo par esteja em desacordo.
isolationLevel |
executionMode |
O que significa |
|---|---|---|
| 1 | external_https |
O plugin é executado fora da instalação e é acedido através de HTTPS |
| 2 | mcp_container |
Um contentor que expõe ferramentas MCP |
| 3 | hardened_docker |
Um contentor reforçado (hardened) nos próprios pods do plugin; a predefinição do modelo |
| 4 | firecracker |
Uma microVM, a separação mais forte |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}entrypoint é obrigatório. Os pontos de entrada são artefactos fornecidos no pacote e nunca são obtidos em tempo de execução: o SDK não tem qualquer caminho de importação dinâmica ou carregamento remoto, pelo que a confiança é escrita e verificada uma vez, sendo depois congelada e nunca transferida.
Com o que se compromete em cada patamar
Cada degrau acima das definições tem um custo de manutenção. Eis o que cada um lhe custa.
- Uma competência do Skills Engine precisa de casos de teste, de um revisor que não seja o próprio autor e de um histórico de versões sobre o qual será questionado quando a competência se comportar de forma inadequada. Os mesmos bytes nunca são publicados duas vezes (
CONTENT_HASH_ALREADY_PUBLISHED), pelo que «basta voltar a carregar» não resolve o problema. - Um plugin precisa de um manifesto cuja tabela de rotas corresponda às rotas que o seu código regista, em ambos os sentidos. Uma rota que exista mas não seja declarada constitui uma falha de conformidade, tal como uma rota declarada que o código nunca registe.
- Um plugin
full-servicepossui um esquema com cinco funções de base de dados, segurança ao nível da linha (row-level security) forçada em todas as tabelas e um arranque que se recusa a escutar até que a base de dados prove que a barreira está ativa. Também reafirma as três leis da plataforma no seu manifesto, palavra por palavra. - Um pacote de domínio é licenciado. É ativado uma unidade de cada vez, através de um piloto, e a licença da organização tem de o incluir. Não lhe cabe a si decidir que um cliente o possui.
- Uma lente apenas pode retirar elementos. Se uma função precisar de ver mais, a lente base tem de mudar, o que implica uma conversa com quem quer que seja o proprietário dessa base.
Nenhum destes custos pode ser negociado por aplicação, o que constitui o compromisso. Abdica de alguma liberdade no primeiro plugin e recupera-a em todos os que se seguirem.
CONNECTION_SCOPE_EXCEEDED.Ferramentas e ligações MCP
O MCP aparece em três locais, que são fáceis de confundir.
Um plugin pode publicar ferramentas MCP declarando-as em mcpTools[]: um name, uma description e um inputSchema. A única regra que o validador adiciona é que um inputSchema não pode utilizar um oneOf, allOf ou anyOf de nível superior, porque um combinador no topo do esquema faz com que todos os clientes MCP que importam a ferramenta falhem com um erro 400. Um plugin em isolationLevel 2 é executado como um mcp_container.
A biblioteca do Skills Engine está acessível através de MCP. O Claude Code e os agentes utilizam treze ferramentas MCP para encontrar e fazer corresponder competências, executá-las e registar a execução, bem como para as criar, importar ou sincronizar, sendo cada chamada executada em nome da pessoa que a iniciou, dentro da respetiva lista de permissões.
E uma ferramenta de programação de IA liga-se através do Workbench: um endereço por instalação, um início de sessão através do navegador da pessoa, um passe de uma hora em vez de uma chave armazenada, e apenas as ferramentas que essa pessoa selecionar. O Capítulo 2.26, Construir com ferramentas de programação de IA, explica este processo passo a passo.
Os conectores são o vizinho mais discreto. O modelo de conhecimento de um pacote de domínio é alimentado por conectores só de leitura ligados a sistemas como a administração de apólices ou um sistema de sinistros, cada um com um agendamento e um botão de teste. Nada é escrito de volta na origem.
Do seu ramo (branch) até aos ecrãs das pessoas
Qualquer que seja o degrau em que se encontre, o caminho para a produção é o mesmo. Cada lançamento passa do seu espaço de desenvolvimento para o ambiente de preparação (staging), depois para uma unidade piloto e, por fim, para todas as unidades, e cada passo tem controlos: testes, um manifesto que não tenha alargado o seu âmbito, uma execução de teste (dry run) numa cópia mascarada e revisores nomeados que não sejam o autor. Uma promoção que tente saltar um passo é recusada com GATE_CANNOT_BE_SKIPPED. Cada ambiente mantém a versão anterior durante 30 dias, e reverter uma unidade é uma alteração revista que demora cerca de um minuto.
A implementação propriamente dita processa-se exclusivamente através dos canais de lançamento da instalação. As unidades escolhem o seu canal e o respetivo administrador concorda com cada transição. Na página Canais e instalações, vê contagens e taxas de erro por unidade, mas nunca o que alguém fez com a sua extensão. O Capítulo 2.28, Lançar a sua extensão, aborda o processo de lançamento de ponta a ponta.
Uma nota sobre as edições
A maior parte desta escada existe em ambas as edições. A edição Community inclui definições e competências do Skills Engine, plugins em todos os níveis e os mesmos caminhos-padrão num único servidor com código no seu próprio anfitrião Git. A edição Enterprise adiciona a promoção desde o espaço de desenvolvimento, passando pelo ambiente de preparação (staging), até uma unidade piloto com os respetivos controlos, além de clusters de editores e cópias mascaradas de dados reais. Adiciona também o seu próprio catálogo privado e pacotes de domínio. O Capítulo 2.25, Construir para cada edição, apresenta os detalhes.
O próximo capítulo é o que deve ler antes de escrever qualquer código. Tem poucas opções e muitas regras, e as regras são as mesmas para a primeira e para a milésima extensão.



