Mille clienti finti prima del lancio

Cos'è e perché conta

Prima di un lancio, di solito tiri a indovinare. Il prezzo è giusto? La frase in cima alla pagina si capisce? L'annuncio incuriosisce o irrita? Lo scopri quando arrivano i primi clienti veri, e a quel punto hai già speso tempo e soldi.

MiroFish è un motore di simulazione con tanti agenti, gratuito e open source su GitHub, con più di 80.000 stelle. Un agente qui è un personaggio mosso da un modello di AI: ha un'età, un carattere, una memoria e le sue idee. Tu gli dai un materiale di partenza, che il progetto chiama seme: la pagina del tuo prodotto, il listino, un annuncio, una notizia. Lui ne ricava un piccolo mondo, lo riempie di agenti e li lascia parlare tra loro su due social simulati, uno a feed come Twitter e uno a comunità come Reddit. Alla fine scrive un rapporto, e puoi fare domande a ognuno di loro.

È per chi sta per lanciare qualcosa da solo. Non è una sfera di cristallo, è una prova generale: ti fa vedere dove la tua pagina potrebbe non piacere, e perché, prima che lo scopra un cliente vero.

1. Cosa ti serve

• Git, Node.js, Python e uv, un gestore di pacchetti per Python. Le versioni giuste sono nella tabella Prerequisites del README: per Python c'è anche un limite massimo, quindi la più recente potrebbe non andare. Oppure solo Docker.
• Una chiave API di un modello di linguaggio che usi il formato dell'SDK di OpenAI. Il README consiglia il modello qwen-plus sulla piattaforma Bailian di Alibaba, ma va bene qualsiasi servizio compatibile.
• Una chiave di Zep Cloud, il servizio che tiene la memoria del mondo simulato sotto forma di grafo, cioè una mappa di persone, cose e legami. Secondo il README la quota gratuita mensile basta per un uso semplice. MiroFish si collega solo a Zep Cloud.
• I testi da fargli leggere, in file PDF, Markdown o TXT.

Una cosa da sapere subito: il programma gira sul tuo computer, ma quello che carichi parte verso il servizio del modello e verso Zep Cloud. Non dargli documenti riservati né dati dei tuoi clienti.

2. Installalo e avvialo

1. Scarica il progetto con git clone https://github.com/666ghj/MiroFish ed entra nella cartella.
2. Copia il file di esempio con cp .env.example .env. Il file .env tiene le chiavi e resta solo sul tuo computer.
3. Apri .env e compila LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME e ZEP_API_KEY. In fondo ci sono tre righe LLM_BOOST, per un secondo modello più veloce e facoltativo: se non lo usi, cancellale. Lo dice il commento nel file, che è in cinese.
4. Installa tutto con npm run setup:all.
5. Avvia con npm run dev. L'interfaccia è su http://localhost:3000, il backend risponde su http://localhost:5001.

Con Docker, dopo il passo 3 basta docker compose up -d: legge lo stesso .env e usa le stesse porte. L'interfaccia si apre in cinese: dal menu delle lingue scegli English. Ci sono solo cinese e inglese, e la lingua scelta lì è anche quella del rapporto e delle risposte degli agenti.

Claude Code può fare quasi tutto il lavoro. L'unica cosa che faccio io sono le chiavi: le scrivo a mano nel .env e non le incollo mai in chat.

Installa MiroFish (https://github.com/666ghj/MiroFish) in una cartella nuova, fuori dai miei progetti.
Leggi il README e il file .env.example, e controlla che Git, Node.js, Python e uv siano nelle versioni richieste. Se manca qualcosa, dimmi come installarlo prima di farlo.
Crea il .env dal file di esempio, togli le tre righe LLM_BOOST e lascia vuote le chiavi: le inserisco io.
Quando ti dico che ho finito, lancia npm run setup:all e poi npm run dev, e dimmi se frontend e backend partono senza errori.

3. Prepara il seme del tuo lancio

Il risultato dipende da cosa gli dai da leggere. Per provare un lancio io preparo un solo file Markdown con dentro:

• Il testo della landing page dall'alto in basso, com'è davvero.
• Il listino: i piani, cosa include ognuno, la prova gratuita se c'è.
• L'annuncio che vuoi far girare: il testo e cosa si vede nell'immagine o nel video.
• Due righe su chi pensi che siano i tuoi clienti. Aiutano a creare agenti credibili.

Leggi la mia landing page (<percorso o indirizzo>), il listino (<percorso>) e il testo dell'annuncio (<testo>).
Scrivi un file seme-lancio.md per MiroFish: il testo della pagina così com'è, il listino in una tabella, l'annuncio e due righe sui clienti a cui penso (<chi sono>).
Non migliorare niente e non aggiungere promesse che nella pagina non ci sono: deve essere la versione che pubblicherei domani.

Poi c'è il secondo campo, la richiesta: cosa vuoi sapere, in parole normali. Più è precisa, più il rapporto risponde alla tua domanda e non a un'altra. La mia, per un lancio:

Simula le reazioni di <freelance e piccoli team> alla pagina e all'annuncio nei primi giorni dopo il lancio. Voglio sapere: cosa non si capisce, quali obiezioni fanno sul prezzo, chi lo condividerebbe e perché, e quale frase della pagina viene citata di più, in bene o in male.

4. Fai girare la simulazione, con pochi giri

Carichi il file, scrivi la richiesta e premi Start Engine. Da lì MiroFish fa cinque passaggi, che vedi uno dopo l'altro:

1. Graph Build: legge il documento e costruisce il grafo su Zep.
2. Env Setup: crea gli agenti, ognuno con età, paese, carattere, una biografia e ricordi presi dal seme. Qui decidi anche quanti giri fare.
3. Run Simulation: i due social girano insieme. Ogni giro è un pezzo di tempo simulato in cui gli agenti pubblicano, commentano, mettono like e si seguono.
4. Report Generation: un agente apposta, il ReportAgent, ricostruisce cosa è successo e scrive il rapporto, sezione per sezione.
5. Deep Interaction: chatti con il ReportAgent o con qualunque agente del mondo, oppure mandi la stessa domanda a un gruppo.

I soldi si giocano sui giri. MiroFish ne propone un numero da solo, ma consuma parecchio: il README dice di provare prima con meno di 40 giri, e la schermata stessa consiglia di passare a Custom la prima volta. In Env Setup accendi Custom e abbassa il cursore, che parte da 10. Fai una prova piccola, controlla che tutto funzioni e che il rapporto abbia senso, e solo dopo allunga.

5. Leggi il rapporto e interroga i clienti finti

Il rapporto lo leggo come leggo i commenti sotto un post: non conto i voti, cerco le frasi che tornano. Tre domande: cosa non si è capito? Quale obiezione torna più spesso? Chi ha difeso il prodotto, e con quali parole?

Poi la parte più utile, Deep Interaction. Scegli un agente che ha criticato il prezzo e chiedigli perché, e cosa gli farebbe cambiare idea. Con Send survey selezioni un gruppo di agenti e mandi a tutti la stessa domanda. Le mie domande di sempre:

Hai visto la pagina: in una frase, cosa fa questo prodotto?
Cosa ti ha fatto dubitare di più?
A quale prezzo lo proveresti, e cosa ti aspetteresti di avere?
Cosa diresti a un amico che ti chiede se vale la pena?

Attenzione: simulazione e interviste funzionano solo mentre l'ambiente è acceso. Dalla cronologia puoi riaprire grafo, ambiente e rapporto, ma non la simulazione né le interviste. Fai le domande prima di chiudere.

Il rapporto finisce anche in un file, full_report.md, dentro backend/uploads/reports. Lì lo può leggere Claude Code, accanto alla tua pagina:

Leggi l'ultimo rapporto di MiroFish (il file full_report.md più recente in backend/uploads/reports) e la mia landing page.
Fai la lista delle obiezioni che tornano più spesso, ognuna con la frase della pagina che la provoca.
Per ognuna proponi una modifica alla pagina. Separa quello che sembra un problema vero da quello che potrebbe essere solo un'idea della simulazione: quello lo verifico con persone vere.

6. I limiti, detti chiari

• È una prova generale, non una previsione. Gli agenti sono modelli di linguaggio che recitano una parte: il rapporto ti dà ipotesi da controllare con persone vere, non numeri di vendita.
• Costa. Il programma è gratis, ma ogni giro sono tante chiamate al modello, che il tuo fornitore ti fa pagare a consumo. Più agenti e più giri, più spendi. Zep Cloud si paga se vai oltre la quota gratuita.
• I tuoi testi escono dal computer. Esiste un fork, MiroFish-Offline (github.com/nikmcfly/MiroFish-Offline), che sostituisce Zep Cloud con Neo4j e il modello in cloud con Ollama, così tutto resta in locale. Non è del team originale, e il suo README chiede una macchina robusta: almeno 16 GB di RAM, e una scheda video è consigliata.
• La licenza è la AGPL-3.0. Usarlo per te è libero. Se però modifichi il codice e fai usare la tua versione ad altri attraverso la rete, per esempio come servizio online, devi offrire a quegli utenti il codice sorgente della tua versione modificata.

Gli errori più comuni

• Lanciare la prima simulazione con i giri proposti da MiroFish. Accendi Custom e parti basso.
• Scrivere una richiesta vaga, tipo «cosa ne pensano?». Chiedi cose precise: cosa non si capisce, le obiezioni sul prezzo, chi lo condivide.
• Prendere il rapporto come una previsione e rifare tutto. Quello che esce dalla simulazione si verifica con qualche persona vera.
• Chiudere l'ambiente prima di aver fatto le domande agli agenti.

Checklist

• Nel .env le quattro voci del modello e di Zep, senza righe LLM_BOOST se non le uso
• Un file seme con pagina, listino e annuncio come li pubblicherò
• Una richiesta precisa, con le domande che contano per il lancio
• Prima prova in Custom, con pochi giri
• Domande ad almeno un critico e un sostenitore prima di chiudere l'ambiente
• Le obiezioni principali segnate, da verificare con persone vere

Domande frequenti