Com’è fatta una Mini App

Questa pagina serve a chi deve correggere una Mini App con precisione, o capire perché una richiesta non è stata accolta. Non devi scrivere codice per usare Userbot, ma sapere com’è fatta una Mini App cambia il modo in cui la descrivi.

Un piccolo progetto web

Una Mini App nuova parte da uno scheletro già pronto: un progetto React costruito con Vite e Tailwind, con alcuni componenti di interfaccia inclusi. Da quel momento i file sono della Mini App, e l’AI li modifica come farebbe uno sviluppatore. Li vedi tutti nella scheda Codice del costruttore.

Le Mini App create prima di questo modello, fatte da un unico file HTML, continuano a funzionare.

Le tre funzioni che deve esporre

Una Mini App va usata da due parti diverse: una persona che compila i campi e un modello che la chiama come strumento. Perché entrambe funzionino, la Mini App espone tre funzioni. Nello scheletro sono run, getOutput e setInputs, esportate da src/App.tsx, e src/main.tsx le collega ai nomi che Userbot cerca.

Le regole che le tengono insieme sono poche e rigide:

• Le chiavi del risultato di run sono esattamente i campi di output, né uno in più né uno in meno.
• run deve funzionare senza che nessuno tocchi l’interfaccia.
• L’interfaccia e run devono usare la stessa logica. È questa regola a garantire che il numero che vedi a schermo e il numero che riceve l’AI siano lo stesso numero.
• Tutto quello che esce deve essere rappresentabile in JSON: numeri, testi, valori vero/falso, elenchi.

Senza run il codice viene rifiutato e non arriva mai in anteprima.

Lo schema: cosa entra e cosa esce

Lo schema è l’elenco dei campi di input e di output, ciascuno con un nome, un tipo, la nota se è obbligatorio e, per le scelte, i valori ammessi. Sta in miniapp.config.json, lo scrive l’AI insieme al codice, ed è quello che il modello legge per capire cosa passare alla Mini App.

{
  "entry": "index.html",
  "inputFields": [
    { "name": "quantita", "type": "number", "required": true },
    { "name": "categoria", "type": "enum", "options": ["Standard", "Premium", "Outlet"] }
  ],
  "outputFields": [{ "name": "totale", "type": "number" }],
  "serverFunctions": [],
  "allowedFetchDomains": [],
  "toolEntrypoint": null
}

I tipi disponibili sono quattro:

Il pulsante Parametri, nel menu ⋯ del costruttore, mostra lo schema in sola lettura.

Per cambiarlo lo chiedi in chat («il campo categoria deve essere una scelta fra Standard, Premium e Outlet», «la quantità è obbligatoria») e l’AI riscrive codice e schema insieme. Lo schema che usano gli agenti è quello della versione pubblicata.

Cosa può fare, e cosa no

Dentro il progetto può esserci tutto quello che si fa con React: moduli, tabelle, grafici, più pagine, calcoli su liste lunghe.

• Librerie: solo quelle ammesse. Oltre a React ci sono, fra le altre, React Router, react-hook-form, zod, Recharts per i grafici, date-fns, le icone Lucide e alcuni componenti Radix. Un pacchetto fuori da questo elenco fa fallire la costruzione dell’anteprima.
• Niente codice generato al volo. eval e new Function sono vietati, e bloccano la pubblicazione.
• Niente chiavi segrete nel codice. Una chiave o una password scritta in chiaro blocca la pubblicazione.
• Nessun accesso alle tue integrazioni, alla Libreria o alla conoscenza aziendale. Se il risultato dipende da informazioni che stanno lì, vanno passate come parametri o cercate da un agente.
• Internet e dati salvati, solo dal server. Una Mini App può chiamare un servizio web e conservare dati fra un uso e l’altro attraverso le funzioni server, e solo verso i domini che ha dichiarato.

La verifica automatica

Ogni volta che l’AI scrive o modifica il codice, Userbot non si fida della parola. Prima di mostrarti il risultato:

Nel riquadro delle azioni del costruttore questo passaggio compare come «Verifico RUN». Il codice che l’AI produce, quindi, è già stato eseguito almeno una volta. Quello che la verifica non può sapere è se il risultato è giusto: che il totale sia quello previsto dal tuo listino lo puoi dire solo tu.

Il controllo vale per quello che scrive l’AI. Quello che modifichi a mano nella scheda Codice viene salvato così com’è: se rompi qualcosa, te ne accorgi dall’anteprima, dove gli errori finiscono nel pannello Problemi.

I limiti

I limiti delle funzioni server e dei dati salvati sono in Funzioni server e dati.

Il limite di otto messaggi spiega un comportamento che altrimenti sorprende: se in una conversazione lunga torni su una richiesta di venti messaggi prima, il costruttore non la ricorda più. Riscrivila per esteso invece di dire «come dicevo prima».