Iniciar sessãoAgendar apresentação

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

16 minutos de leitura

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.

  1. 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.
  2. Competências do Skills Engine. Um pacote SKILL.md que 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).
  3. 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-only ou full-service.
  4. 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.
  5. 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.
  6. 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.

Começar algo novo
Começar algo novo
A opção Começar algo novo oferece seis caminhos-padrão, um por cada tipo de extensão. Cada um cria um repositório a partir de um modelo versionado com um manifesto que declara o que necessita, e configura testes, um espaço de desenvolvimento e ramos de dados.

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.
Desenhe uma pilha de faixas horizontais. Na base, «Funcionalidades principais do Nexus» (assistente, ficheiros, memória, tarefas) e, ao lado, «Despacho UNO» e «AI Provider Router». Acima, uma faixa «Plugins» com duas caixas, «skills-only» e «full-service», e uma faixa «Competências do Skills Engine». Acima destas, uma caixa larga «Pacote de domínio» contendo quatro caixas mais pequenas: «Modelo de conhecimento», «Lentes», «Modelos e fluxos de trabalho», «Sobreposição móvel». À esquerda do pacote, uma caixa «Conectores só de leitura» com uma seta a apontar para «Modelo de conhecimento». No topo, três caixas de unidades («Rotterdam», «Felixstowe», «Sede») com setas a descer a partir do pacote com a legenda «lente concedida por função». Um cadeado na extremidade do pacote tem a legenda «licença: domain_packs».
Como um pacote de domínio agrupa os outros blocos de construção.

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.

Pacotes de domínio
Pacotes de domínio
A página Pacotes de domínio lista todos os dez pacotes com o que cada um necessita e onde é executado. Um pacote que a licença não inclua permanece listado e a cinzento, com a indicação do que seria necessário.

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-service possui 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.

Instalar um plugin de terceiros
Instalar um plugin de terceiros
A instalação de um plugin de terceiros funciona como as permissões de aplicações. Cada âmbito que o respetivo manifesto declara é concedido ou recusado por unidade, e uma chamada para qualquer elemento que não tenha declarado é recusada com 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.

Sincronização de plugins e MCP
Sincronização de plugins e MCP
A Sincronização de plugins e MCP mostra que plugins fornecem competências, que sincronizações foram recusadas na totalidade e as treze ferramentas MCP que o Claude Code e os agentes utilizam para aceder à biblioteca.

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.