Libretto

Libretto 是一个用于构建健壮 Web 集成的工具包。它为你的编码智能体提供了一个实时浏览器和一个令牌高效的 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，然后自动开始探索。

交互式脚本构建

我将向你展示在 eclinicalworks EHR 中获取患者主要保险 ID 的工作流。使用 libretto 技能将其转换为一个 Playwright 脚本，该脚本接受患者姓名和出生日期作为输入，返回保险 ID。URL 是...

Libretto 可以读取你在浏览器中执行的操作，因此你可以执行一个工作流，然后要求它使用你的操作重新构建该工作流。

将浏览器自动化转换为网络请求

我们在 ./integration.ts 中有一个浏览器脚本，用于自动化访问 Hacker News 并获取前 10 篇帖子。将其转换为直接网络脚本。使用 Libretto 技能。

Libretto 可以从浏览器读取网络请求，从而逆向工程 API，并创建一个直接调用这些请求的脚本。直接调用 API 比 UI 自动化更快、更可靠。你还可以要求 Libretto 进行安全分析，分析请求中常见的安全 cookie，从而了解网络请求方式是否安全。

修复损坏的集成

我们在 ./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 使用情况并优先改进。每个已执行的命令仅可发送安装 ID、时间戳、命令事件名称（如 libretto run）、错误布尔值、包版本、构建渠道（node_modules、source 或 unknown），以及在登录 Libretto Cloud 时配置的云用户 ID。Libretto 不会发送命令参数、URL、项目路径、会话 cookie、API 密钥、错误消息或详细信息，或电子邮件。

安装 ID 存储在遥测文件 ~/.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。发现 bug？请提交 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 技能的真正来源

在编辑 packages/libretto/README.template.md 或 packages/libretto/skills/libretto/ 下的任何内容后，运行 pnpm sync:mirrors。

要检查生成的 README、技能镜像和技能版本元数据是否同步而不修复，运行 pnpm check:mirrors。要发布，运行 pnpm prepare-release。

[!NOTE] 这是一个早期阶段的项目，正在积极开发中。API 在 1.0 版本之前可能会发生变化。建议在生产环境中锁定特定版本。

由 Saffron Health 团队构建。