Il pacchetto
Un’app è un pacchetto dipendente con un manifest.json che lo indica come app e una cartella ui/ con la pagina.
<data>/user/agents/deal-board/
├── manifest.json # marks the employee as an app
├── AGENT.md # the employee behind the page
├── agent.json # optional: sidecar tools, workflows
└── ui/
├── index.html
└── app.js {
"id": "<minted UUID>",
"name": "deal-board",
"version": "1.0.0",
"type": "app",
"window": { "title": "Deal Board", "width": 900, "height": 700, "resizable": true },
"permissions": ["storage:readwrite"]
} | Campo | Significato |
|---|---|
type | "app". Rende il dipendente un’app. Nebo legge anche il vecchio artifact_type. |
id | Un UUID generato quando l’app viene creata. La pagina è servita su /apps/<id>/ui/. |
name, version | Il nome del dipendente e la versione del pacchetto. |
window | title, width, height, resizable, fullscreen, orientation. Valori predefiniti: 1024 × 768, ridimensionabile, non a schermo intero, verticale, con il titolo del dipendente. |
permissions | Cosa può fare la pagina. Predefinito ["storage:readwrite"]. |
Permessi
| Permesso | Concede |
|---|---|
storage:readwrite | L’archivio chiave-valore dell’app. |
subagent:<employee-id> | Fare domande a un altro dipendente dalla pagina. Il dipendente dell’app non ha bisogno di alcun permesso. |
network:<host> o network:* | Richieste verso host esterni tramite il proxy di Nebo. |
device:motion | Il giroscopio e l’accelerometro solo per questa pagina. Su iPhone la pagina chiama anche DeviceMotionEvent.requestPermission() dopo un tocco. |
Ogni permesso ha la forma prefix:scope. Chiedi il minimo di cui l’app ha bisogno.
Schermo intero, orientamento e inclinazione
Giochi e film possono occupare tutto lo schermo. Imposta fullscreen e, per l’app mobile, un orientation: portrait (il valore predefinito), landscape o any. Qualsiasi altro orientamento viene rifiutato quando si scrive il manifest.
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - Su desktop l’app si apre in una finestra a schermo intero.
- Nell’app mobile non c’è la barra dell’app, le barre di sistema sono nascoste, lo schermo resta acceso e il trascinamento per aggiornare è disattivato. Un piccolo pulsante Chiudi si trova nell’angolo in alto a sinistra e svanisce dopo qualche secondo; un tocco vicino al bordo superiore lo fa ricomparire. Lo scorrimento dal bordo di iOS è disattivato, e il tasto Indietro di Android ripercorre la cronologia della pagina prima di chiuderla.
- Aggiungi margini alla pagina con
env(safe-area-inset-*)eviewport-fit=cover, e tieni i controlli lontani dall’angolo in alto a sinistra.
Il controllo vocale
Ogni app aperta nell’app desktop di Nebo o nell’app mobile mostra un piccolo controllo vocale nell’angolo in basso a destra, così il titolare può parlare con il dipendente dell’app mentre lavora sulla pagina. Il controllo sta fuori dalla tua pagina, quindi ricaricare la pagina non interrompe mai la chiamata.
- Su desktop è una barra di circa 300 × 48 pixel, a 16 pixel dall’angolo in basso a destra della finestra.
- Nell’app mobile è un pulsante rotondo da 48 punti all’interno dell’area sicura, che il titolare può trascinare su entrambi i lati. In un’app a schermo intero, dopo qualche secondo di chiamata torna a essere quel pulsante.
- Tieni i controlli importanti lontani dall’angolo in basso a destra.
- Durante un’attività lunga in chiamata, il dipendente dà brevi aggiornamenti come «Sto modificando.» e non legge mai ad alta voce nomi di file o comandi.
Crea un’app
Un dipendente può creare un’app in due modi, e sceglie in base a ciò che dice il titolare. «Creami un’app per i miei ordini» crea un nuovo dipendente app. «Sei tu l’app» o «creati un gioco» trasforma in app il dipendente con cui il titolare sta parlando: conserva chat, memoria e persona, e la sua pagina si ricarica mentre il titolare gli parla. Funziona anche per un dipendente assunto in conversazione. Quando non è chiaro cosa intenda il titolare, il dipendente chiede una volta.
update_employee(
name: "<the employee's own name>",
app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
ui: { "index.html": "<!doctype html>..." }
) Gli strumenti di tutti i giorni (un tracker, un modulo, una piccola dashboard) si creano con la skill per le app integrata in Nebo. Una pagina che deve sembrare progettata e non generata, come una landing page cinematografica, un film guidato dallo scorrimento, arte generativa o un gioco, si crea con la skill App Studio del marketplace.
Per una nuova app, il modo più semplice è chiederla a un dipendente. Nebo include una skill integrata per creare app, e il dipendente usa create_employee, che scrive la cartella, il manifest, la persona e la pagina in una sola chiamata. L’app compare nel personale del titolare in pochi secondi.
create_employee(
name: "deal-board",
description: "A board of open deals, sorted by close date.",
app: {
window: { title: "Deal Board", width: 900, height: 700, resizable: true },
permissions: ["storage:readwrite"]
},
ui: { "index.html": "<!doctype html>..." }
) update_employee accetta gli stessi argomenti ui, app e agent_md. Un percorso in ui sostituisce solo quel file. La pagina viene letta dal disco a ogni richiesta, quindi ricaricando la finestra si vede la modifica.
Una pagina minima
Questa pagina carica l’SDK, chiede chi è il suo dipendente e stampa la risposta. Se mostra l’ID e il nome del dipendente, i collegamenti sono corretti.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Deal Board</title>
</head>
<body>
<h1>Deal Board</h1>
<pre id="who">loading...</pre>
<script src="/sdk/nebo.global.js"></script>
<script>
NeboAppSDK.nebo.identity.get()
.then(me => { document.getElementById('who').textContent = JSON.stringify(me, null, 2); })
.catch(err => { document.getElementById('who').textContent = String(err); });
</script>
</body>
</html> L’SDK ricava l’ID dell’app dall’indirizzo della pagina. Una pagina servita da qualsiasi altro posto ha bisogno di <meta name="nebo-app-id" content="<id>">. Tieni lo stato nello storage dell’app, non nella pagina: la finestra si chiude, lo storage resta.
Come viene servita la pagina
- Nebo serve
ui/su/apps/<id>/ui/e la apre in una finestra dedicata. - Un percorso senza un file corrispondente ricade su
index.html, quindi il routing lato client funziona. - Le pagine HTML ricevono i meta tag
nebo-app-idenebo-base-url. - Ogni file viene inviato con il suo vero tipo di contenuto, compresi video, audio, font,
wasme modelli 3D (glb,gltf). Un file con un’estensione sconosciuta viene inviato comeapplication/octet-streame il browser non lo userà. - I file rispondono alle richieste di intervallo (
206, oppure416per un intervallo oltre la fine), così video e audio possono essere riprodotti da qualsiasi punto. Nell’app mobile, i video si riproducono sul posto senza bisogno di toccarli:<video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video> - Un file il cui nome contiene un hash del contenuto, come
main-0a8ksftt.js, viene tenuto in cache per un anno. Tutto il resto,index.htmlcompreso, viene verificato a ogni apertura e risponde304se non è cambiato. Compila con nomi con hash invece di rinominare i file a mano. - Ogni file della pagina può essere al massimo di 10 MB.
- Eliminare la cartella disattiva il dipendente;
delete_employeelo rimuove del tutto.
Aggiungi un sidecar
Quando la pagina ha bisogno di logica lato server, di dati propri o di strumenti che il dipendente può chiamare, aggiungi un sidecar: un binario che Nebo esegue accanto all’app. La pagina lo raggiunge con neboFetch e un percorso relativo. Vedi Sidecar delle app.
Pubblica da Nebo
Un’app creata dal titolare può pubblicarsi da sola. Il titolare dice «pubblicati», oppure tocca Publish nella chat dell’app o nella schermata dell’app nell’app mobile (nella barra in alto, o come pulsante accanto a Chiudi per un’app a schermo intero), oppure sceglie Publish This App… dal menu del desktop (il menu File su macOS quando una finestra dell’app è in primo piano; il menu App della finestra dell’app su Windows e Linux). Il dipendente prepara la scheda a partire dall’app, fa da 3 a 5 screenshot e mostra la scheda nella chat, da rifinire parlando. Non viene inviato nulla finché il titolare non risponde Submit for review sulla scheda, con un tocco o a voce.
Un’app creata dal titolare ha sempre i propri strumenti per sviluppatori: ricarica, stato, console, screenshot e pubblicazione. La modalità App Developer (impostazioni del bot, Sviluppatore) permette ad altri dipendenti di lavorare su qualsiasi app del titolare, aggiunge una console mobile alla pagina e disattiva la cache. Le app installate dal marketplace non hanno mai strumenti per sviluppatori né un pulsante Publish.
Pubblica un’app da solo
Un’app composta solo da una pagina si pubblica come un unico bundle con lo strumento agent. Il frontmatter di AGENT.md deve dire artifact_type: app, altrimenti il marketplace crea un semplice dipendente senza pagina. Metti tra virgolette ogni valore che contiene due punti seguiti da uno spazio: senza virgolette, il frontmatter non può essere letto e l’app diventa in silenzio un semplice dipendente.
--- name: deal-board description: "A board of open deals: sorted by close date, with a chat that knows each deal." artifact_type: app metadata: version: "1.0.0" --- # Deal Board You work beside the Deal Board app. ...
agent(action: "create", name: "deal-board", version: "1.0.0",
description: "A board of open deals, sorted by close date.",
manifestContent: "<contents of AGENT.md>")
agent(action: "bundle-token", id: "<app id>")
zip -r deal-board.zip deal-board -x '*/.git/*' '*/node_modules/*' '*/src/*'
curl -X POST "https://neboai.com/api/v1/skills/<app id>/bundle" \
-H "Authorization: Bearer <token>" \
-F file=@deal-board.zip
agent(action: "submit", id: "<app id>", version: "1.0.0") | Nello zip | Cosa succede |
|---|---|
AGENT.md | La persona e il manifest della scheda. |
agent.json | La configurazione del dipendente. Va bene anche {}. |
manifest.json | Mantenuto come manifest dell’app: finestra e permessi arrivano all’app installata. Deve essere JSON valido. |
ui/ | La pagina. Consentiti: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, immagini (png, jpg, gif, svg, webp, avif, ico, bmp), font (woff, woff2, ttf, otf), audio (mp3, wav, ogg, m4a, aac, flac, opus), video (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. I file che iniziano con un punto e node_modules/ vengono scartati. |
skills/<name>/ | Le skill proprie del dipendente, verificate come una skill caricata da sola: SKILL.md mantenuto, scripts/ e bin/ di qualsiasi tipo, tutto il resto secondo l’elenco consentito delle skill. |
- Limiti: 10 MB per file e 50 MB per bundle. Un file oltre i 10 MB viene saltato (controlla
filesSkippedeuiFilesStorednel risultato); un bundle oltre i 50 MB viene rifiutato. - Il token di caricamento dura 5 minuti. Un’unica cartella principale nello zip viene rimossa.
- Per un’app privata o solo per i canali, ogni caricamento ricrea subito il pacchetto installabile e Nebo avvisa i bot che hanno installato l’app. Un bot online mette subito al suo posto il pacchetto ricreato; uno offline lo fa alla connessione successiva. Non serve aumentare la versione, e le impostazioni, le pianificazioni e i dati del titolare per l’app vengono conservati. Le app pubbliche, non elencate e solo su invito mantengono il pacchetto approvato finché una nuova versione non supera la revisione.
- Una nuova versione segue l’impostazione degli aggiornamenti automatici che ogni titolare ha scelto per l’app. È disattivata finché il titolare non la attiva, quindi per impostazione predefinita il bot mostra «Aggiornamento disponibile» e il titolare lo applica da Impostazioni, poi Aggiornamenti, oppure dalla Posta in arrivo. Un aggiornamento non concede mai nuovi permessi; un permesso aggiunto dalla nuova versione viene chiesto quando l’app ne ha bisogno la prima volta.
- Se NeboAI ritira un’app dal marketplace, ogni bot che l’ha installata la disattiva e avvisa il titolare. Non viene eliminato nulla: tutto ciò che l’app ha salvato viene conservato.
- Un’app con un sidecar carica invece il binario di ogni piattaforma con
binary-token, e la pagina come archivioui. Vedi Sidecar delle app e Pubblicazione.