Libretto

Libretto — это набор инструментов для создания надёжных веб-интеграций. Он предоставляет вашему агенту кодирования живой браузер и эффективный CLI с минимальным потреблением токенов, позволяющий:

• Проверять живые страницы с минимальными накладными расходами на контекст
• Захватывать сетевой трафик для обратного проектирования API сайтов
• Записывать действия пользователя и воспроизводить их в виде скриптов автоматизации
• Отлаживать неработающие рабочие процессы в интерактивном режиме на реальном сайте

Мы в Saffron Health создали Libretto, чтобы поддерживать наши браузерные интеграции с распространённым медицинским ПО. Мы открываем его исходный код, чтобы другим командам было проще сделать то же самое.

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

Быстрые ссылки

• Веб-сайт: libretto.sh
• Документация: libretto.sh/docs
• Репозиторий: github.com/saffron-health/libretto
• Discord: discord.gg/NYrG56hVDt

Установка

# Добавьте Libretto в свой проект. Требуется Node.js и npm.
npm install libretto

# Первоначальная настройка: установка навыков и загрузка Chromium
npx libretto setup

# Проверка готовности рабочего пространства в любое время
npx libretto status

setup создаёт каталог .libretto/, устанавливает навыки агента и загружает Chromium, если не указан флаг --skip-browsers.

Варианты использования

Libretto предназначен для использования в качестве навыка вашего агента кодирования. Вот несколько примеров запросов:

Однократная генерация скрипта

Используй навык Libretto. Зайди на LinkedIn и собери первые 10 постов: содержание, кто опубликовал, количество реакций, первые 25 комментариев и первые 25 репостов.

Ваш агент кодирования откроет окно для входа в LinkedIn, а затем автоматически начнёт исследование.

Интерактивное создание скрипта

Я покажу тебе рабочий процесс в EHR eclinicalworks для получения первичного ID страховки пациента. Используй навык libretto, чтобы превратить его в скрипт Playwright, который принимает имя и дату рождения пациента и возвращает ID страховки. URL: ...

Libretto может считывать ваши действия в браузере, поэтому вы можете выполнить рабочий процесс, а затем попросить его восстановить его на основе ваших действий.

Преобразование автоматизации браузера в сетевые запросы

У нас есть браузерный скрипт в ./integration.ts, который автоматизирует переход на Hacker News и получает первые 10 постов. Преобразуй его в скрипты прямых сетевых запросов. Используй навык Libretto.

Libretto может считывать сетевые запросы из браузера, что позволяет обратно спроектировать API и создать скрипт, который напрямую вызывает эти запросы. Прямые вызовы API быстрее и надёжнее, чем автоматизация пользовательского интерфейса. Вы также можете попросить Libretto провести анализ безопасности, который анализирует запросы на предмет распространённых куки безопасности, чтобы понять, будет ли безопасным подход с сетевыми запросами.

Исправление сломанных интеграций

У нас есть браузерный скрипт в ./integration.ts, который должен зайти на Availity и выполнить проверку права на получение услуги для пациента. Но при выполнении возникает ошибка сломанного селектора. Исправь его. Используй навык Libretto.

Агенты могут использовать Libretto для воспроизведения сбоя, приостановки рабочего процесса в любой точке, проверки живой страницы и исправления проблем — всё автономно.

Использование через CLI

Вы также можете использовать Libretto напрямую из командной строки. Все команды принимают --session <name> для указания конкретной сессии.

npx libretto open <url>                    # запустить браузер и открыть URL
npx libretto run ./integration.ts --headless # выполнить рабочий процесс и закрыть при успехе
npx libretto run ./integration.ts --headless --stay-open-on-success # оставить успешный запуск для проверки
npx libretto snapshot --session <name>     # сделать снимок экрана и компактное дерево доступности
npx libretto exec "<code>"                 # выполнить Playwright TypeScript на открытой странице
npx libretto close                         # закрыть браузер

Сессии run можно проверять с помощью тех же команд, работающих через демон, что и сессии open. Успешные запуски по умолчанию закрывают браузер; укажите --stay-open-on-success, чтобы оставить браузер открытым для команд pages, snapshot и exec. Неудачные или приостановленные рабочие процессы оставляют браузер открытым, чтобы вы могли проверить точное состояние страницы перед исправлением или возобновлением.

Выполните npx libretto help для получения полного списка команд.

Конфигурация

Всё состояние Libretto хранится в каталоге .libretto/ в корне вашего проекта. См. документацию по конфигурации для подробностей о файлах конфигурации, сессиях и профилях.

Телеметрия

Libretto записывает телеметрию CLI, чтобы понимать использование CLI и помогать нам расставлять приоритеты в улучшениях. Каждая выполненная команда может отправлять только идентификатор установки, временную метку, имя события команды (например, libretto run), флаг ошибки, версию пакета, канал сборки (node_modules, source или unknown), а при входе в Libretto Cloud — идентификатор пользователя облака. Libretto не отправляет аргументы команд, URL, пути проектов, куки сессий, ключи API, сообщения об ошибках или их детали, а также электронные письма.

Идентификатор установки хранится в файле телеметрии ~/.libretto/telemetry.json. Реализация находится в packages/libretto/src/cli/core/telemetry.ts.

Чтобы отключить телеметрию, установите LIBRETTO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, запустите с CI=1 или отредактируйте ~/.libretto/telemetry.json и установите "enabled": false.

Присоединяйтесь к сообществу

Присоединяйтесь к нашему Discord, чтобы общаться с другими разработчиками, получать помощь и делиться тем, что вы создали:

Для более длинных обсуждений заходите на GitHub Discussions. Нашли ошибку? Откройте issue.

Лицензия

MIT License — свободно используйте в коммерческих проектах и проектах с открытым исходным кодом.

Разработка

Для локальной разработки в этом репозитории:

pnpm i
pnpm build
pnpm type-check
pnpm test

Структура исходников:

• packages/libretto/src/cli/ — команды CLI
• packages/libretto/src/runtime/ — среда выполнения браузера (сеть, восстановление, загрузки)
• packages/libretto/src/shared/ — общие утилиты (конфигурация, LLM-клиент, логирование, состояние)
• packages/libretto/test/ — тестовые файлы (*.spec.ts)
• packages/libretto/README.template.md — источник истины для README репозитория и пакета
• packages/libretto/skills/libretto/ — источник истины для навыка Libretto

Запускайте pnpm sync:mirrors после редактирования packages/libretto/README.template.md или всего, что находится в packages/libretto/skills/libretto/.

Чтобы проверить, что сгенерированные README, зеркала навыков и метаданные версии навыка синхронизированы без исправления, выполните pnpm check:mirrors. Для релиза выполните pnpm prepare-release.

[!NOTE] Это проект на ранней стадии активной разработки. API могут измениться до версии 1.0. Рекомендуем закреплять конкретные версии в продакшене.

Создано командой Saffron Health.