Libretto

Libretto é um kit de ferramentas para construir integrações web robustas. Ele dá ao seu agente de codificação um navegador ao vivo e uma CLI eficiente em tokens para:

• Inspecionar páginas ao vivo com sobrecarga mínima de contexto
• Capturar tráfego de rede para fazer engenharia reversa de APIs de sites
• Gravar ações do usuário e reproduzi-las como scripts de automação
• Depurar fluxos de trabalho quebrados interativamente contra o site real

Nós, da Saffron Health, construímos o Libretto para nos ajudar a manter nossas integrações de navegador para softwares de saúde comuns. Estamos disponibilizando como código aberto para que outras equipes tenham mais facilidade em fazer o mesmo.

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

Links Rápidos

• Site: libretto.sh
• Documentação: libretto.sh/docs
• Repositório: github.com/saffron-health/libretto
• Discord: discord.gg/NYrG56hVDt

Instalação

# Adicione Libretto ao seu projeto. Requer Node.js e npm.
npm install libretto

# Configuração inicial: instala habilidades e baixa o Chromium
npx libretto setup

# Verifique a prontidão do workspace a qualquer momento
npx libretto status

setup cria o diretório .libretto/, instala habilidades do agente e baixa o Chromium, a menos que você passe --skip-browsers.

Casos de uso

O Libretto foi projetado para ser usado como uma habilidade através do seu agente de codificação. Aqui estão alguns exemplos de prompts:

Geração de script único

Use a habilidade Libretto. Vá no LinkedIn e colete as primeiras 10 postagens: conteúdo, quem postou, número de reações, os primeiros 25 comentários e os primeiros 25 compartilhamentos.

Seu agente de codificação abrirá uma janela para você fazer login no LinkedIn e, em seguida, começará a explorar automaticamente.

Construção interativa de script

Vou te mostrar um fluxo de trabalho no EHR eClinicalWorks para obter o ID do seguro primário de um paciente. Use a habilidade libretto para transformá-lo em um script Playwright que receba nome e data de nascimento do paciente e retorne o ID do seguro. URL é ...

O Libretto pode ler as ações que você realiza no navegador, permitindo que você execute um fluxo de trabalho e depois peça para usar suas ações para reconstruí-lo.

Converter automação de navegador em requisições de rede

Temos um script de navegador em ./integration.ts que automatiza ir ao Hacker News e obter as primeiras 10 postagens. Converta-o para scripts de rede diretos. Use a habilidade Libretto.

O Libretto pode ler requisições de rede do navegador, que ele pode usar para fazer engenharia reversa da API e criar um script que chame essas requisições diretamente. Fazer chamadas de API diretamente é mais rápido e mais confiável do que automação de interface. Você também pode pedir ao Libretto para realizar uma análise de segurança que examina as requisições em busca de cookies de segurança comuns, para entender se uma abordagem via requisições de rede será segura.

Corrigir integrações quebradas

Temos um script de navegador em ./integration.ts que deveria ir ao Availity e realizar uma verificação de elegibilidade para um paciente. Mas estou recebendo um erro de seletor quebrado ao executá-lo. Corrija. Use a habilidade Libretto.

Os agentes podem usar o Libretto para reproduzir a falha, pausar o fluxo de trabalho em qualquer ponto, inspecionar a página ao vivo e corrigir problemas, tudo de forma autônoma.

Uso da CLI

Você também pode usar o Libretto diretamente da linha de comando. Todos os comandos aceitam --session <nome> para segmentar uma sessão específica.

npx libretto open <url>                    # abrir navegador e abrir uma URL
npx libretto run ./integration.ts --headless # executar um fluxo de trabalho e fechar em caso de sucesso
npx libretto run ./integration.ts --headless --stay-open-on-success # manter uma execução bem-sucedida inspecionável
npx libretto snapshot --session <nome>     # capturar uma captura de tela e árvore de acessibilidade compacta
npx libretto exec "<código>"               # executar Playwright TypeScript contra a página aberta
npx libretto close                         # fechar o navegador

Sessões run são inspecionáveis através dos mesmos comandos baseados em daemon que as sessões open. Execuções bem-sucedidas fecham o navegador por padrão; passe --stay-open-on-success para manter o navegador aberto para pages, snapshot e exec. Fluxos de trabalho falhos ou pausados mantêm o navegador aberto para que você possa inspecionar o estado exato da página antes de corrigir ou retomar o fluxo.

Execute npx libretto help para a lista completa de comandos.

Configuração

Todo o estado do Libretto reside em um diretório .libretto/ na raiz do seu projeto. Veja a documentação de configuração para detalhes sobre arquivos de configuração, sessões e perfis.

Telemetria

O Libretto registra telemetria da CLI para ajudar a entender o uso da CLI e priorizar melhorias. Cada comando resolvido pode enviar apenas um ID de instalação, timestamp, nome do evento do comando (como libretto run, booleano de erro, versão do pacote, canal de build (node_modules, source ou unknown) e, quando logado no Libretto Cloud, o ID de usuário configurado na nuvem. O Libretto não envia argumentos de comando, URLs, caminhos de projeto, cookies de sessão, chaves de API, mensagens ou detalhes de erro, ou e-mails.

O ID de instalação é armazenado no arquivo de telemetria em ~/.libretto/telemetry.json. A implementação está em packages/libretto/src/cli/core/telemetry.ts.

Para desativar a telemetria, defina LIBRETTO_TELEMETRY_DISABLED=1, defina DO_NOT_TRACK=1, execute com CI=1, ou edite ~/.libretto/telemetry.json e defina "enabled": false.

Junte-se à Comunidade

Entre no nosso Discord para se conectar com outros desenvolvedores, obter ajuda e compartilhar o que você construiu:

Para discussões mais longas, acesse GitHub Discussions. Encontrou um bug? Abra uma issue.

Licença

Licença MIT — use-a livremente em projetos comerciais e de código aberto.

Desenvolvimento

Para desenvolvimento local neste repositório:

pnpm i
pnpm build
pnpm type-check
pnpm test

Estrutura do código-fonte:

• packages/libretto/src/cli/ — comandos CLI
• packages/libretto/src/runtime/ — runtime do navegador (rede, recuperação, downloads)
• packages/libretto/src/shared/ — utilitários compartilhados (config, cliente LLM, logging, estado)
• packages/libretto/test/ — arquivos de teste (*.spec.ts)
• packages/libretto/README.template.md — fonte da verdade para os READMEs do repositório e pacote
• packages/libretto/skills/libretto/ — fonte da verdade para a habilidade Libretto

Execute pnpm sync:mirrors após editar packages/libretto/README.template.md ou qualquer coisa em packages/libretto/skills/libretto/.

Para verificar se os READMEs gerados, os espelhos de habilidades e os metadados de versão de habilidades estão sincronizados sem corrigi-los, execute pnpm check:mirrors. Para lançar uma versão, execute pnpm prepare-release.

[!NOTE] Este é um projeto em estágio inicial sob desenvolvimento ativo. As APIs podem mudar antes da versão 1.0. Recomendamos fixar versões específicas em produção.

Construído pela equipe da Saffron Health.