AccediPrenota un briefing

Capitolo 2.18

Il modello di estensione

I sei modi per estendere Nexus, da un'impostazione a un pacchetto di dominio, i limiti di ciascuno e come i livelli di fiducia e isolamento decidono dove viene eseguito il vostro codice. Leggetelo prima di aprire il software development kit (SDK).

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

16 minuti di lettura

La prima cosa che ho costruito su Nexus presso Corrán Orbital non è stata un plugin. Il nostro team di dinamica del volo voleva che l'assistente rispondesse alla domanda "quali passaggi sulla stazione di terra perdiamo se l'antenna delle Svalbard va fuori servizio per manutenzione?" sempre nello stesso formato, con la tabella dei passaggi per prima e il costo in minuti di contatto sotto. Ho passato mezza giornata a leggere il software development kit (SDK) prima che un collega mi facesse notare che ciò che mi serviva era una skill: una cartella contenente un SKILL.md, caricata nello Skills Engine e pubblicata una volta superati i test e ottenuta l'approvazione di un revisore. Ci sono voluti quaranta minuti.

Due plugin e un domain pack dopo, questo è ancora il primo consiglio che do. Nexus offre sei modi per essere esteso, disposti su una scala di impegno crescente. I gradini più economici fanno più di quanto ci si aspetti, mentre quelli più costosi comportano obblighi facili da sottovalutare. Questo capitolo illustra la scala. Scelga il gradino più basso in grado di svolgere il lavoro. I capitoli successivi approfondiscono ciascuno di essi: capitolo 2.19, Le regole che ogni estensione eredita; capitolo 2.20, Le skill; capitolo 2.21, Il Plugin SDK; capitolo 2.22, Il runtime dei plugin; e capitolo 2.23, I domain pack.

I sei blocchi costitutivi

Eccoli nell'ordine in cui dovrebbe prenderli in considerazione.

  1. Impostazioni e policy. Sono valori che un amministratore imposta nella console per l'organizzazione, un'unità o una singola persona, entro i limiti consentiti dalla licenza. Non si scrive alcun codice.
  2. Skill dello Skills Engine. Un pacchetto SKILL.md che contiene le istruzioni e gli strumenti che la skill può richiamare, affiancato da file e script opzionali. L'assistente, gli agenti, i workflow e i pulsanti di IA (intelligenza artificiale) sulle schermate eseguono tutti le stesse skill, e così fa il Suo IDE (integrated development environment).
  3. Plugin. Il Suo codice, dichiarato tramite un manifest e compilato con gli strumenti dell'SDK. Un plugin si presenta in uno di tre livelli: skills-only, ui-only o full-service.
  4. Domain pack. Le lenti e i modelli di un settore specifico, le sue skill e il suo modello di conoscenza, i suoi connettori e le sue schermate per telefono, concessi in licenza come un'unica unità. Adverant ne fornisce dieci; Lei può creare i Suoi.
  5. Lenti. Ciò che un singolo ruolo vede all'interno di un pack o di una piattaforma. Una lente restringe una lente di base e non la amplia mai.
  6. Connessioni MCP e connettori. Gli strumenti Model Context Protocol (MCP) che un plugin pubblica o attraverso cui si connette uno strumento di programmazione basato sull'IA, e i connettori di sola lettura che importano record dai sistemi che già utilizza.

Due termini vengono spesso sovrapposti, quindi è bene chiarirli subito. Una skill dello Skills Engine è un pacchetto SKILL.md nella libreria. Una skill del manifest è una riga tipizzata nell'array skills[] di un plugin, compilata nel registro delle skill della piattaforma ed eseguita tramite UNO, il motore di workflow. Entrambe sono chiamate skill a schermo. Sono scritte e governate in modo diverso, e questa documentazione specifica sempre a quale delle due si riferisce.

Inizia qualcosa di nuovo
Inizia qualcosa di nuovo
Inizia qualcosa di nuovo offre sei percorsi ottimali, uno per ogni tipo di estensione. Ciascuno crea un repository da un modello versionato con un manifest che dichiara ciò di cui ha bisogno, e configura i test, uno spazio di sviluppo e i branch dei dati.

Cosa può fare ciascuno di essi e cosa non può fare

La tabella è la versione sintetica. Ho inserito di proposito la colonna "Cosa non può fare": ogni limite è una proprietà progettuale, e ciascuno di essi mi ha salvato da qualche problema.

Elemento costitutivo Cosa può fare Cosa non può fare Chi lo realizza
Impostazione o policy Modificare il comportamento di una funzionalità a qualsiasi livello, dall'organizzazione fino alla singola persona; bloccare un valore; delegarlo ai livelli inferiori; richiedere l'approvazione di una seconda persona per una modifica Aggiungere una schermata o una rotta, archiviare una nuova tabella o avviare un nuovo tipo di lavoro Un amministratore, nella console
Skill dello Skills Engine Fornire all'assistente, agli agenti, ai workflow e ai pulsanti di IA un modo ripetibile per svolgere un compito, con le proprie istruzioni e i propri casi di test Conservare una credenziale; richiamare uno strumento al di fuori dell'elenco degli elementi consentiti della persona che la esegue (SKILL_CANNOT_WIDEN_TOOLS); entrare in produzione senza i test e l'approvazione Chiunque disponga del permesso, nel creator o dal proprio IDE
Plugin, skills-only Pubblicare skill del manifest che vengono eseguite sulla piattaforma: callback verso l'host, lavoro in coda, mappature su un elenco e, al livello di attendibilità core o verified, skill basate su modelli Servire pagine proprie Uno sviluppatore, con l'SDK
Plugin, ui-only Aggiungere un'interfaccia frontend all'interno della shell Archiviare dati propri o eseguire calcolo Uno sviluppatore, con l'SDK
Plugin, full-service Un proprio backend e frontend, uno schema Postgres, una tabella di routing con permessi, oltre a skill e strumenti MCP Richiamare un fornitore di modelli; conservare una chiave del modello; leggere le righe di un'altra organizzazione se non tramite un'autorizzazione registrata; eseguire calcolo al di fuori del dispatch di UNO Uno sviluppatore, con l'SDK
Domain pack Portare le lenti e i modelli di un settore, le sue skill e i suoi workflow, un modello di conoscenza, una mappa delle evidenze e schermate per telefono nelle unità scelte da un amministratore Modificare la shell o i suoi componenti, o le regole di scrittura; funzionare senza che sia incluso nella licenza dell'organizzazione Adverant, o i Suoi sviluppatori sull'edizione Enterprise
Lente Scegliere le schede e i campi che un ruolo vede all'interno di un pack o della piattaforma, e le azioni che offre Mostrare qualsiasi elemento nascosto dalla sua lente di base (LENS_CANNOT_WIDEN); modificare ciò che un ruolo è autorizzato a fare L'autore di un pack la costruisce; un amministratore la assegna per unità
Strumenti MCP e connettori Esporre gli strumenti di un plugin agli agenti e agli strumenti di programmazione; leggere i record da un sistema di gestione delle polizze o da un archivio di telemetria nel modello di conoscenza Scrivere nel sistema di origine tramite un connettore; agire oltre i permessi della persona che ha effettuato l'accesso Uno sviluppatore dichiara gli strumenti MCP; un amministratore configura i connettori

Alcune di queste celle meritano una frase in più.

Le impostazioni sono un framework, e ogni plugin utilizza lo stesso. Un plugin che dichiara un blocco settings nel proprio manifest ottiene i livelli (piattaforma, organizzazione, pack, unità, gruppo, repository, persona), i blocchi e la delega, un registro delle modifiche e l'approvazione di una seconda persona, il tutto senza scrivere una tabella delle impostazioni. Ecco perché il gradino più economico è spesso sufficiente: se il comportamento desiderato esiste già e richiede solo un valore diverso per l'unità di Rotterdam, si tratta di un'impostazione.

Una skill dello Skills Engine viene eseguita con l'identità della persona. Non conserva mai una chiave, può raggiungere solo gli strumenti presenti nell'elenco degli elementi consentiti di chi la esegue e può leggere solo ciò che quella persona è autorizzata ad aprire. Una skill che aggiunge uno strumento di scrittura viene trattenuta finché due persone non la approvano, dopodiché entra in produzione in modalità shadow, poi in canary e infine per tutti.

Un plugin skills-only è il gradino intermedio. Serve quando il lavoro consiste in codice di Sua proprietà: un calcolo deterministico, un worker di coda, una distribuzione (fan-out) su un elenco. La piattaforma richiama il Suo codice; il Suo codice non richiama mai un modello.

Un plugin full-service è un piccolo prodotto. Possiede uno schema Postgres, una tabella di routing con un registro dei permessi, un frontend, un set di ruoli del database e tutti gli obblighi di isolamento descritti nel capitolo 2.19, Le regole che ogni estensione eredita. È la risposta giusta più spesso di quanto si tema e la risposta sbagliata più spesso di quanto si speri.

Di quale ho bisogno?

Inizi dalla cima di questa tabella e si fermi alla prima riga adatta alle Sue esigenze.

Se desidera… Usi Perché non qualcosa di più leggero
Modificare un valore o un limite, o chi può fare qualcosa Un'impostazione o una policy Non esiste nulla di più leggero
Far svolgere all'assistente un compito sempre nello stesso modo Una skill dello Skills Engine Un'impostazione non può contenere istruzioni
Inserire un "pulsante di IA" su una schermata che esegua quel compito Una skill dello Skills Engine associata al pulsante Un pulsante esegue solo skill; non c'è nulla da sviluppare
Consentire a uno strumento di programmazione basato sull'IA di raggiungere Nexus Una connessione MCP tramite il Workbench Non c'è nulla da scrivere; la persona accede tramite il proprio browser
Leggere record da un sistema esistente nel modello di conoscenza Un connettore di sola lettura Un connettore non scrive nulla nel sistema di origine, quindi non comporta rischi di scrittura
Eseguire codice deterministico di Sua proprietà secondo la pianificazione della piattaforma Un plugin skills-only con una skill host_callback o plugin_queue Una skill dello Skills Engine non può eseguire il Suo codice
Aggiungere una o due schermate all'interno della shell Un plugin ui-only Solo i plugin aggiungono schermate
Conservare i propri record dietro le proprie rotte e i propri permessi Un plugin full-service Solo questo livello possiede uno schema
Fornire a un ruolo una vista più ristretta delle schermate di un settore Una lente su un pack esistente Una lente è costituita da dati, non da codice
Portare il modello di conoscenza e le lenti di un settore, con schermate per telefono, in più unità Un domain pack Un plugin da solo non ha lenti né controlli di licenza

Presso Corrán Orbital la domanda sulla pianificazione dei passaggi è rimasta una skill dello Skills Engine. La propagazione orbitale necessaria è diventata un plugin skills-only con una skill host_callback, poiché il calcolo numerico è nostro e deve dare due volte la stessa risposta. La nostra commissione di revisione delle anomalie è diventata un plugin full-service, perché conserva i propri record su chi ha esaminato quale anomalia telemetrica e cosa ha deciso. Il pack è arrivato per ultimo, quando una seconda unità ha richiesto la stessa cosa.

Come si combinano gli elementi

Gli elementi costitutivi si compongono verso l'alto. Un domain pack è l'esempio più chiaro, poiché è un pacchetto che racchiude gli altri elementi più un controllo di licenza:

  • un modello di conoscenza, ossia i tipi di entità che il settore conosce e il modo in cui si collegano, spesso costruito su un modello di base di un altro pack;
  • lenti, una per ruolo, ciascuna delle quali restringe una lente di base;
  • modelli e workflow, e le skill dello Skills Engine che essi richiamano;
  • plugin, laddove il pack necessiti di codice proprio;
  • connettori di sola lettura verso i sistemi che già detengono i record;
  • un livello mobile che definisce quali schede e passaggi di acquisizione appaiono sui telefoni;
  • e le autorizzazioni (entitlement): i gruppi di funzionalità che la licenza deve includere prima che qualsiasi elemento si attivi.
Disegnare una pila di fasce orizzontali. In basso, "Funzionalità principali di Nexus" (assistente, file, memoria, job) e accanto "Dispatch UNO" e "AI Provider Router". Sopra, una fascia "Plugin" con due riquadri, "skills-only" e "full-service", e una fascia "Skill dello Skills Engine". Sopra queste, un ampio riquadro "Domain pack" contenente quattro riquadri più piccoli: "Modello di conoscenza", "Lenti", "Modelli e workflow", "Livello mobile". A sinistra del pack, un riquadro "Connettori di sola lettura" con una freccia che punta verso "Modello di conoscenza". In alto, tre riquadri di unità ("Rotterdam", "Felixstowe", "Head office") con frecce che scendono dal pack etichettate "lente concessa per ruolo". Un lucchetto sul bordo del pack porta l'etichetta "licenza: domain_packs".
Come un domain pack raggruppa gli altri elementi costitutivi.

Nulla di tutto ciò richiede un'infrastruttura specifica per singola app. Il pack non fornisce alcun codice di isolamento proprio, né client per i modelli, né controlli di licenza: eredita quelli della piattaforma. Questo è l'argomento del prossimo capitolo, ed è il motivo per cui l'autore di un pack in una banca e uno in un porto scrivono la stessa quantità di codice di sicurezza, ovvero nessuna.

Pacchetti di dominio
Pacchetti di dominio
La pagina dei Domain pack elenca tutti i dieci pack indicando ciò di cui ciascuno ha bisogno e dove viene eseguito. Un pack non incluso nella licenza rimane elencato e disattivato in grigio, con l'indicazione di ciò che richiederebbe.

Livelli di fiducia

Ogni plugin dichiara un livello trust nel proprio manifest. L'attendibilità (trust) non è un controllo che l'SDK possa aggirare. Si tratta di metadati consultivi che la piattaforma legge per decidere con quale grado di isolamento vengono eseguiti i contributi di un plugin e quali sono i dati più sensibili che le sue skill possono toccare. I controlli attivi (classificazione e residenza dei dati, esportazione e spesa) rimangono esattamente dove sono.

Attendibilità A chi si rivolge Postura di isolamento Tetto di classificazione
core Codice di prima parte fornito nella piattaforma none: stessa origine (same-origin), nessun isolamento aggiuntivo restricted
verified Una terza parte revisionata, un editore verificato Superficie same-origin, skill mediate (brokered) restricted
community Una terza parte non revisionata; l'impostazione predefinita per un nuovo plugin Superficie sandboxed, skill mediate (brokered) tenant
untrusted Qualsiasi elemento proveniente da una fonte sconosciuta strict: superficie in sandbox, solo skill mediate, nessuna attendibilità sull'host public

Da quella tabella derivano due regole, e create-nexus-plugin validate le applica entrambe prima che qualsiasi cosa venga compilata.

In primo luogo, il classification di una skill non può superare il tetto massimo del suo plugin. Le classificazioni sono ordinate come public, poi tenant, infine restricted. Un plugin community che dichiara una skill restricted non supera la compilazione.

In secondo luogo, solo i plugin core e verified possono dichiarare skill che raggiungono l'AI Provider Router. Questi sono i livelli tool_using e llm_only. Un plugin community o untrusted media il lavoro deterministico (host_callback, plugin_queue e map su di essi) e chiede alla piattaforma di eseguire tutto ciò che richiede un modello. Il mio primo plugin era community e ho perso un pomeriggio cercando di dichiarare una skill di riepilogo llm_only prima di capire che il rifiuto era proprio l'obiettivo del sistema.

Se omette trust, l'SDK tratta il plugin come community. Un campo omesso non può mai comportare una promozione a un livello superiore.

Livelli di isolamento da 1 a 4

Separatamente dall'attendibilità, il blocco runtime del manifest indica come viene eseguito il plugin. isolationLevel è un numero intero da 1 a 4 e la modalità di esecuzione ne consegue. Non è possibile scegliere i due valori in modo indipendente: il validatore deriva l'uno dall'altro e rifiuta un manifest la cui coppia non concorda.

isolationLevel executionMode Cosa significa
1 external_https Il plugin viene eseguito al di fuori dell'installazione ed è raggiunto tramite HTTPS
2 mcp_container Un container che espone strumenti MCP
3 hardened_docker Un container rinforzato (hardened) nei pod propri del plugin; l'impostazione predefinita del modello
4 firecracker Una microVM, la separazione più forte
"runtime": {
  "nodeVersion": "20",
  "executionMode": "hardened_docker",
  "isolationLevel": 3,
  "entrypoint": "dist/server.js",
  "healthCheck": "/health"
}

entrypoint è obbligatorio. Gli entrypoint sono artefatti rilasciati e non vengono mai recuperati a runtime: l'SDK non ha alcun percorso di importazione dinamica o caricamento remoto, quindi l'attendibilità viene scritta e verificata una sola volta, poi congelata, mai scaricata.

Cosa comporta ciascun livello

Ogni gradino al di sopra delle impostazioni comporta un costo di mantenimento. Ecco quanto Le costa ciascuno di essi.

  • Una skill dello Skills Engine richiede casi di test, un revisore diverso da Lei e una cronologia delle versioni di cui Le verrà chiesto conto in caso di malfunzionamento. Gli stessi byte non vengono mai pubblicati due volte (CONTENT_HASH_ALREADY_PUBLISHED), quindi "basta ricaricarla" non è una soluzione.
  • Un plugin richiede un manifest la cui tabella di routing corrisponda alle rotte registrate dal Suo codice, in entrambe le direzioni. Una rotta che esiste ma non è dichiarata costituisce un errore di conformità, così come una rotta dichiarata che il codice non registra mai.
  • Un plugin full-service possiede uno schema con cinque ruoli del database, la sicurezza a livello di riga (row-level security) forzata su ogni tabella e una procedura di avvio che rifiuta di mettersi in ascolto finché il database non dimostra che le barriere di isolamento tengono. Inoltre, ribadisce nel proprio manifest le tre leggi della piattaforma, parola per parola.
  • Un domain pack è soggetto a licenza. Si attiva un'unità alla volta, tramite un progetto pilota, e deve essere incluso nella licenza dell'organizzazione. Non spetta a Lei decidere se un cliente ne dispone.
  • Una lente può solo sottrarre elementi. Se un ruolo ha bisogno di vedere di più, deve cambiare la lente di base, il che richiede un confronto con chiunque sia il proprietario di quella base.

Nessuno di questi costi può essere negoziato per singola app: questo è il compromesso. Si rinuncia a un po' di libertà sul primo plugin e la si recupera su tutti quelli successivi.

Installa un plugin di terze parti
Installa un plugin di terze parti
L'installazione di un plugin di terze parti funziona come le autorizzazioni delle app. Ogni ambito (scope) dichiarato nel suo manifest viene concesso o negato per singola unità, e una chiamata per qualsiasi elemento non dichiarato viene rifiutata con CONNECTION_SCOPE_EXCEEDED.

Strumenti e connessioni MCP

MCP compare in tre punti, ed è facile confonderli.

Un plugin può pubblicare strumenti MCP dichiarandoli in mcpTools[]: un name, un description e un inputSchema. L'unica regola aggiunta dal validatore è che un inputSchema non può utilizzare un oneOf, allOf o anyOf di primo livello, poiché un combinatore al livello superiore dello schema fa fallire con un errore 400 ogni client MCP che importa lo strumento. Un plugin a isolationLevel 2 viene eseguito come un mcp_container.

La libreria dello Skills Engine è raggiungibile tramite MCP. Claude Code e gli agenti utilizzano tredici strumenti MCP per trovare e abbinare le skill, eseguirle e registrarne l'esecuzione, nonché crearle, importarle o sincronizzarle; ogni chiamata viene eseguita con l'identità della persona che l'ha avviata, all'interno del suo elenco degli elementi consentiti.

Inoltre, uno strumento di programmazione basato sull'IA si connette tramite il Workbench: un indirizzo per installazione, un accesso tramite il browser della persona, un pass della durata di un'ora invece di una chiave memorizzata, e solo gli strumenti selezionati da quella persona. Il capitolo 2.26, Sviluppare con strumenti di programmazione basati sull'IA, illustra la procedura passo dopo passo.

I connettori sono i vicini più silenziosi. Il modello di conoscenza di un domain pack è alimentato da connettori di sola lettura verso sistemi quali l'amministrazione delle polizze o un sistema di gestione dei sinistri, ciascuno dotato di una pianificazione e di un pulsante di test. Nulla viene scritto nel sistema di origine.

Plugin e sincronizzazione MCP
Plugin e sincronizzazione MCP
Plugin e sincronizzazione MCP mostra quali plugin apportano skill, quali sincronizzazioni sono state rifiutate in blocco e i tredici strumenti MCP che Claude Code e gli agenti utilizzano per raggiungere la libreria.

Dal vostro branch agli schermi degli utenti

Qualunque sia il gradino su cui si trova, il percorso verso la produzione è lo stesso. Ogni rilascio passa dal Suo spazio di sviluppo allo staging, poi a un'unità pilota, infine a tutte le unità, e ogni passaggio prevede dei controlli (gate): test, un manifest che non si sia ampliato, un'esecuzione di prova (dry run) su una copia mascherata e revisori designati diversi dall'autore. Una promozione che tenta di saltare un passaggio viene rifiutata con GATE_CANNOT_BE_SKIPPED. Ogni ambiente conserva la versione precedente per 30 giorni, e il ripristino (rollback) di una singola unità è una modifica sottoposta a revisione che richiede circa un minuto.

Il deployment vero e proprio avviene esclusivamente attraverso i canali di rilascio dell'installazione. Le unità scelgono il proprio canale e il loro amministratore accetta ogni avanzamento. Nella pagina Canali e installazioni Lei vede i conteggi e i tassi di errore per unità, mai ciò che qualcuno ha fatto con la Sua estensione. Il capitolo 2.28, Rilasciare la propria estensione, copre l'intero processo di rilascio dall'inizio alla fine.

Una nota sulle edizioni

La maggior parte di questa scala esiste in entrambe le edizioni. L'edizione Community offre le impostazioni e le skill dello Skills Engine, i plugin a ogni livello e gli stessi percorsi ottimali su un unico server con il codice nel Suo host Git. L'edizione Enterprise aggiunge la promozione dallo spazio di sviluppo, attraverso lo staging, fino a un'unità pilota con i relativi controlli, oltre a cluster di editori e copie mascherate dei dati di produzione. Aggiunge inoltre il Suo catalogo privato e i domain pack. Il capitolo 2.25, Sviluppare per ciascuna edizione, contiene tutti i dettagli.

Il prossimo capitolo è quello da leggere prima di scrivere qualsiasi codice. Offre poche scelte e molte regole, e le regole sono le stesse per la prima estensione come per la millesima.