Stagehand - AI 驱动的浏览器自动化框架

项目概述

Stagehand 是一个生产就绪的 AI 浏览器自动化框架，由 Browserbase 公司开发。它解决了现有浏览器自动化工具的痛点：要么需要编写低级代码（如 Selenium、Playwright、Puppeteer），要么使用高级代理但在生产环境中不可预测。

核心特性

1. 灵活的控制方式

• 代码与自然语言结合：开发者可以选择何时使用代码，何时使用自然语言
• AI 导航：在不熟悉的页面上使用 AI 进行导航
• 精确控制：在明确知道要做什么时使用代码（Playwright）

2. 预览和缓存功能

• 操作预览：在执行之前预览 AI 操作
• 缓存机制：轻松缓存可重复的操作，节省时间和令牌消耗

3. 一键集成计算机视觉模型

• SOTA 模型支持：一行代码即可集成 OpenAI 和 Anthropic 的最新计算机视觉模型
• 无缝集成：引入 stagehand.agent：一种强大的新方法，只需一行代码即可将 SOTA 计算机视觉模型或 Browserbase 的 Open Operator 集成到 Stagehand 中

快速开始

安装

npx create-browser-app

本地开发

git clone https://github.com/browserbase/stagehand.git
cd stagehand
npm install
npx playwright install
npm run build
npm run example # 运行 ./examples/example.ts 中的示例脚本

环境配置

cp .env.example .env
nano .env # 编辑 .env 文件添加 API 密钥

使用示例

基本用法

// 使用 Playwright 函数操作页面对象
const page = stagehand.page;
await page.goto("https://github.com/browserbase");

// 使用 act() 执行单个操作
await page.act("click on the stagehand repo");

// 使用计算机视觉代理执行更大的操作
const agent = stagehand.agent({
  provider: "openai",
  model: "computer-use-preview",
});
await agent.execute("Get to the latest PR");

// 使用 extract() 从页面读取数据
const { author, title } = await page.extract({
  instruction: "extract the author and title of the PR",
  schema: z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
});

核心方法

1. act() 方法

• 执行单个浏览器操作
• 支持自然语言指令
• 适用于点击、输入、导航等操作

2. extract() 方法

• 从页面提取结构化数据
• 集成 Zod 模式验证
• 支持复杂的数据提取任务

3. observe() 方法

• 观察页面状态和变化
• 用于条件判断和状态监控

4. agent() 方法（V2 新特性）

• 集成先进的计算机视觉模型
• 支持多步骤工作流
• 适用于复杂交互场景

版本 2.0 新特性

Stagehand V2 引入了多项重大改进：

性能提升

• 闪电般的 act 和 extract：重大性能改进，使自动化运行更快
• 基于 a11y-tree 的优化：更快的可访问性树基础的 act/extract 方法

增强的日志记录

• 更好的自动化过程可见性
• 改进的日志记录和调试功能

全面的文档

• 完全重新设计的文档站点
• 更好的示例、指南和最佳实践

错误处理改进

• 更稳定的错误处理机制
• 更好的错误信息和调试支持

技术架构

依赖关系

• Playwright：作为网页自动化的核心骨干
• Zod：用于数据结构验证
• TypeScript：主要开发语言

多语言支持

除了 TypeScript/JavaScript 版本，项目还提供：

• Python 版本

与 Browserbase 的集成

Browserbase 是您的云浏览器提供商，使用 Stagehand 构建更强大的功能，包括会话回放、提示可观察性和验证码解决等高级功能。

总结

Stagehand 是一个革命性的浏览器自动化框架，它完美融合了传统代码控制的精确性和 AI 自然语言处理的灵活性。无论是简单的网页操作还是复杂的数据提取任务，Stagehand 都能提供生产级的解决方案。其 2.0 版本的性能提升和新特性使其成为现代浏览器自动化的首选工具。