Libretto

Libretto 是一个开源工具包，旨在解决现代软件开发中一个日益棘手的问题：如何稳健地构建和维护基于浏览器的 Web 集成。它为你的编码代理（如 Claude Code, Cursor, Copilot）提供了一个“眼睛”和“双手”，使其能够以极低的 Token 开销检查实时页面、逆向工程 API、录制自动化脚本并交互式调试故障。

由 Saffron Health 开发并开源，Libretto 最初用于维护复杂的医疗保健软件浏览器集成，现在已开放给所有需要与动态 Web 应用交互的开发团队。

核心功能

1. Token 高效的实时页面检查

• 智能快照：Libretto 捕获页面的 PNG 截图和精简后的 HTML DOM，并通过 LLM 进行结构化分析。
• 低上下文开销：相比发送完整的原始 HTML，Libretto 提供的摘要信息更少但更精准，大幅降低 AI 代理的 Token 消耗，同时保持对页面状态的准确理解。

2. API 逆向工程

• 流量捕获：自动记录浏览器中的网络请求（Network Traffic）。
• 脚本转换：可以将基于 UI 自动化（如 Playwright/Selenium）的脚本转换为直接调用后端 API 的代码。这不仅提高了执行速度，还增强了稳定性，因为 API 通常比 UI 元素更少变动。
• 安全分析：辅助分析请求中的 Cookie 和 Header，评估直接 API 调用的安全性。

3. 操作录制与重放

• 工作流捕捉：你在浏览器中手动执行的操作会被 Libretto 记录。
• 自动生成代码：代理可以根据你的操作序列，自动生成可重放的 Playwright TypeScript 脚本，实现“演示即编程”。

4. 交互式调试与自愈

• 故障重现：当自动化脚本失败时，代理可以使用 Libretto 重新打开浏览器，复现错误现场。
• 实时检查：在失败点暂停，检查当前的 DOM 结构和视觉状态，自主修复选择器错误或逻辑缺陷。

快速开始

1. 安装

npm install libretto

2. 初始化设置

运行 setup 命令，Libretto 会自动检测环境变量中的 API Key（如 OPENAI_API_KEY），下载 Chromium 浏览器，并配置默认模型。

npx libretto setup

3. 检查状态

随时确认工作区是否就绪：

npx libretto status

4. 切换 AI 提供商（可选）

如果需要更换模型提供商（如从 OpenAI 切换到 Anthropic 或 Gemini）：

npx libretto ai configure anthropic

典型使用场景

Libretto 最强大的地方在于它与 AI 编码代理 的结合。以下是几个通过自然语言指令即可完成的复杂任务：

场景一：从零生成爬虫脚本

提示词：“使用 Libretto 技能。前往 LinkedIn，登录我的账户，然后抓取前 10 条帖子的内容、发布者、反应数、前 25 条评论和转发。”

• 过程：Libretto 打开浏览器让你手动登录一次，随后代理自动接管，探索页面结构并生成抓取脚本。

场景二：将 UI 操作转化为 API 调用

提示词：“我们在 ./integration.ts 中有一个通过浏览器自动化获取 Hacker News 前 10 条帖子的脚本。请使用 Libretto 将其转换为直接的网络请求脚本，并分析其安全性。”

• 过程：Libretto 运行旧脚本，捕获背后的 XHR/Fetch 请求，代理据此编写更高效、更稳定的 API 调用代码。

场景三：交互式工作流录制

提示词：“我要演示如何在 eClinicalWorks EHR 系统中获取患者的主保险 ID。请观察我的操作，并将其转换为一个接受姓名和出生日期、返回保险 ID 的 Playwright 脚本。”

• 过程：你在 Libretto 控制的浏览器中操作，Libretto 记录每一步，代理随后将其编译为可复用的函数。

场景四：自动修复失败的集成

提示词：“我们的 Availity 资格检查脚本报错了。请使用 Libretto 重现该错误，检查页面状态，并修复选择器问题。”

• 过程：代理重启浏览器，运行脚本直到失败点，利用 Libretto 的快照功能“看”到当前的页面变化，更新代码中的选择器，并验证修复是否成功。

CLI 命令参考

除了作为 Agent 技能，Libretto 也提供独立的 CLI 命令：

配置与存储

• 本地化状态：所有配置、会话数据和快照均存储在 project root 的 .libretto/ 目录中。
• 多提供商支持：原生支持 OpenAI, Anthropic, Gemini, Vertex AI 等主流模型。
• 会话管理：支持通过 --session <name> 参数管理多个并行的浏览器会话。