Versione 1.0.0-alpha.1ultima
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

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.
- 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.
- Skill dello Skills Engine. Un pacchetto
SKILL.mdche 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). - 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-onlyofull-service. - 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.
- 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.
- 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.
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.
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.
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-servicepossiede 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.
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.
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.



