Libretto

Libretto è un toolkit per costruire integrazioni web robuste. Fornisce al tuo agente di codifica un browser live e una CLI efficiente in termini di token per:

• Ispezionare pagine live con un overhead di contesto minimo
• Catturare il traffico di rete per fare reverse engineering delle API del sito
• Registrare le azioni dell'utente e riprodurle come script di automazione
• Fare debug di flussi di lavoro interrotti interagendo con il sito reale

Noi di Saffron Health abbiamo creato Libretto per aiutarci a mantenere le nostre integrazioni browser con i software sanitari comuni. Lo rendiamo open-source in modo che altri team possano fare lo stesso più facilmente.

https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18

Collegamenti rapidi

• Sito web: libretto.sh
• Documentazione: libretto.sh/docs
• Repository: github.com/saffron-health/libretto
• Discord: discord.gg/NYrG56hVDt

Installazione

# Aggiungi Libretto al tuo progetto. Richiede Node.js e npm.
npm install libretto

# Configurazione iniziale: installa le skill e scarica Chromium
npx libretto setup

# Verifica lo stato del workspace in qualsiasi momento
npx libretto status

setup crea la directory .libretto/, installa le skill dell'agente e scarica Chromium a meno che non si passi --skip-browsers.

Casi d'uso

Libretto è progettato per essere utilizzato come skill tramite il tuo agente di codifica. Ecco alcuni esempi di prompt:

Generazione di script monouso

Usa la skill Libretto. Vai su LinkedIn e recupera i primi 10 post per contenuto, autore, numero di reazioni, i primi 25 commenti e le prime 25 condivisioni.

Il tuo agente di codifica aprirà una finestra per farti accedere a LinkedIn, e poi inizierà automaticamente a esplorare.

Costruzione interattiva di script

Ti mostrerò un flusso di lavoro nell'EHR eClinicalWorks per ottenere l'ID assicurativo principale di un paziente. Usa la skill Libretto per trasformarlo in uno script Playwright che prende nome e data di nascita del paziente come input per restituire l'ID assicurativo. L'URL è ...

Libretto può leggere le azioni che esegui nel browser, quindi puoi eseguire un flusso di lavoro e poi chiedergli di ricostruire il flusso usando le tue azioni.

Convertire automazione browser in richieste di rete

Abbiamo uno script browser in ./integration.ts che automatizza l'accesso a Hacker News e il recupero dei primi 10 post. Convertilo in script di rete diretti. Usa la skill Libretto.

Libretto può leggere le richieste di rete dal browser, che può usare per fare reverse engineering dell'API e creare uno script che chiama direttamente quelle richieste. Effettuare chiamate API direttamente è più veloce e più affidabile dell'automazione dell'interfaccia utente. Puoi anche chiedere a Libretto di condurre un'analisi di sicurezza che esamina le richieste per individuare cookie di sicurezza comuni, in modo da capire se un approccio tramite richieste di rete sarà sicuro.

Riparare integrazioni danneggiate

Abbiamo uno script browser in ./integration.ts che dovrebbe andare su Availity ed eseguire un controllo di eleggibilità per un paziente. Ma quando lo eseguo ottengo un errore di selettore rotto. Riparalo. Usa la skill Libretto.

Gli agenti possono utilizzare Libretto per riprodurre il fallimento, mettere in pausa il flusso di lavoro in qualsiasi punto, ispezionare la pagina live e correggere i problemi, tutto in modo autonomo.

Utilizzo da riga di comando

Puoi anche usare Libretto direttamente dalla riga di comando. Tutti i comandi accettano --session <nome> per puntare a una sessione specifica.

npx libretto open <url>                    # avvia il browser e apre un URL
npx libretto run ./integration.ts --headless # esegue un flusso di lavoro e chiude al successo
npx libretto run ./integration.ts --headless --stay-open-on-success # mantiene aperta un'esecuzione riuscita per ispezione
npx libretto snapshot --session <nome>     # cattura uno screenshot e un albero di accessibilità compatto
npx libretto exec "<codice>"               # esegue Playwright TypeScript contro la pagina aperta
npx libretto close                         # chiude il browser

Le sessioni run sono ispezionabili tramite gli stessi comandi basati su demone delle sessioni open. Le esecuzioni riuscite chiudono il browser per impostazione predefinita; passa --stay-open-on-success per mantenere il browser aperto per pages, snapshot e exec. I flussi di lavoro falliti o messi in pausa mantengono il browser aperto in modo da poter ispezionare lo stato esatto della pagina prima di correggere o riprendere il flusso.

Esegui npx libretto help per l'elenco completo dei comandi.

Configurazione

Tutti gli stati di Libretto risiedono in una directory .libretto/ nella radice del progetto. Consulta la documentazione di configurazione per i dettagli su file di configurazione, sessioni e profili.

Telemetria

Libretto registra la telemetria CLI per capire l'utilizzo della CLI e aiutarci a prioritizzare i miglioramenti. Ogni comando risolto può inviare solo un ID di installazione, timestamp, nome dell'evento del comando (ad es. libretto run), booleano di errore, versione del pacchetto, canale di build (node_modules, source o unknown) e, quando si è connessi a Libretto Cloud, l'ID utente cloud configurato. Libretto non invia argomenti dei comandi, URL, percorsi di progetto, cookie di sessione, chiavi API, messaggi di errore o dettagli, o email.

L'ID di installazione è memorizzato nel file di telemetria in ~/.libretto/telemetry.json. L'implementazione risiede in packages/libretto/src/cli/core/telemetry.ts.

Per disabilitare la telemetria, imposta LIBRETTO_TELEMETRY_DISABLED=1, imposta DO_NOT_TRACK=1, esegui con CI=1, o modifica ~/.libretto/telemetry.json e imposta "enabled": false.

Unisciti alla community

Unisciti al nostro Discord per entrare in contatto con altri sviluppatori, ottenere aiuto e condividere ciò che hai costruito:

Per discussioni più lunghe, vai su GitHub Discussions. Hai trovato un bug? Apri una segnalazione.

Licenza

Licenza MIT — utilizzala liberamente in progetti commerciali e open-source.

Sviluppo

Per lo sviluppo locale in questo repository:

pnpm i
pnpm build
pnpm type-check
pnpm test

Struttura del sorgente:

• packages/libretto/src/cli/ — comandi CLI
• packages/libretto/src/runtime/ — runtime del browser (rete, ripristino, download)
• packages/libretto/src/shared/ — utilità condivise (configurazione, client LLM, logging, stato)
• packages/libretto/test/ — file di test (*.spec.ts)
• packages/libretto/README.template.md — sorgente di verità per i README del repository e dei pacchetti
• packages/libretto/skills/libretto/ — sorgente di verità per la skill Libretto

Esegui pnpm sync:mirrors dopo aver modificato packages/libretto/README.template.md o qualsiasi cosa in packages/libretto/skills/libretto/.

Per verificare che i README generati, i mirror delle skill e i metadati delle versioni delle skill siano sincronizzati senza correggerli, esegui pnpm check:mirrors. Per rilasciare, esegui pnpm prepare-release.

[!NOTE] Questo è un progetto in fase iniziale in fase di sviluppo attivo. Le API potrebbero cambiare prima della versione 1.0. Raccomandiamo di fissare versioni specifiche in produzione.

Costruito dal team di Saffron Health.