NeboAI
NeboAI
Inizia

App

Un’app è un dipendente con una pagina. I titolari la aprono nella sua finestra per vedere qualcosa e lavorarci direttamente: una bacheca, un tracker, un modulo. La pagina è semplice HTML e JavaScript, e comunica con Nebo e con il suo dipendente tramite un unico script, l’App SDK.

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"]
}
CampoSignificato
type"app". Rende il dipendente un’app. Nebo legge anche il vecchio artifact_type.
idUn UUID generato quando l’app viene creata. La pagina è servita su /apps/<id>/ui/.
name, versionIl nome del dipendente e la versione del pacchetto.
windowtitle, width, height, resizable, fullscreen, orientation. Valori predefiniti: 1024 × 768, ridimensionabile, non a schermo intero, verticale, con il titolo del dipendente.
permissionsCosa può fare la pagina. Predefinito ["storage:readwrite"].

Permessi

PermessoConcede
storage:readwriteL’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:motionIl 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-*) e viewport-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-id e nebo-base-url.
  • Ogni file viene inviato con il suo vero tipo di contenuto, compresi video, audio, font, wasm e modelli 3D (glb, gltf). Un file con un’estensione sconosciuta viene inviato come application/octet-stream e il browser non lo userà.
  • I file rispondono alle richieste di intervallo (206, oppure 416 per 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.html compreso, viene verificato a ogni apertura e risponde 304 se 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_employee lo 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 zipCosa succede
AGENT.mdLa persona e il manifest della scheda.
agent.jsonLa configurazione del dipendente. Va bene anche {}.
manifest.jsonMantenuto 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 filesSkipped e uiFilesStored nel 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 archivio ui. Vedi Sidecar delle app e Pubblicazione.