AI驱动的浏览器自动化框架
阅读文档

如果您正在寻找 Python 实现，可以在这里找到： 点击此处

什么是 Stagehand？

Stagehand 是一个浏览器自动化框架，用于通过自然语言和代码控制网页浏览器。通过将人工智能的强大功能与代码的精确性相结合，Stagehand 使网页自动化变得灵活、易于维护且真正可靠。

为什么选择 Stagehand？

现有的大多数浏览器自动化工具要么要求您使用 Selenium、Playwright 或 Puppeteer 等框架编写低级代码，要么使用在生产环境中可能难以预测的高级代理。通过让开发者选择何时使用代码、何时使用自然语言（并在两者之间架起桥梁），Stagehand 成为生产环境中浏览器自动化任务的自然选择。

1. 自由选择代码或自然语言：当需要导航不熟悉的页面时使用 AI，而当您确切知道要做什么时则使用代码。

2. 从 AI 驱动过渡到可重复的工作流程：Stagehand 允许您在执行 AI 操作之前预览它们，并帮助您轻松缓存可重复的操作，从而节省时间和调用次数。

3. 一次编写，永久运行：Stagehand 的自动缓存功能结合自我修复机制，能够记住之前的操作，在无需 LLM 推理的情况下运行，并在网站发生变化导致自动化失效时自动启用 AI。

开始使用

只需一行代码即可开始使用 Stagehand，或者查看我们的快速入门指南以获取更多信息：

npx create-browser-app

示例

以下是如何使用 Stagehand 构建一个简单的浏览器自动化示例：

// Stagehand 的 CDP 引擎提供了一个针对自动化优化的底层浏览器接口
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");

// 使用 act() 执行单个动作
await stagehand.act("点击 stagehand 仓库");

// 使用 agent() 处理多步骤任务
const agent = stagehand.agent();
await agent.execute("前往最新的 PR");

// 使用 extract() 从页面中提取结构化数据
const { author, title } = await stagehand.extract(
  "提取 PR 的作者和标题",
  z.object({
    author: z.string().describe("PR 作者的用户名"),
    title: z.string().describe("PR 的标题"),
  }),
);

文档

访问 docs.stagehand.dev 查看完整文档。

从源码构建并运行

git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install
pnpm run build
pnpm run example # 运行 ./examples/example.ts 中的空白脚本

Stagehand 在拥有 LLM 提供商的 API 密钥以及 Browserbase 凭证时效果最佳。要将这些添加到您的项目中，请执行以下操作：

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

从分支安装

您可以使用 gitpkg 直接从 GitHub 分支安装并构建 Stagehand。

在您的项目 package.json 中设置：

"@browserbasehq/stagehand": "https://gitpkg.now.sh/browserbase/stagehand/packages/core?<branchName>",

贡献

[!NOTE] 我们非常重视对 Stagehand 的贡献！如有任何问题或需要支持，请加入我们的 Discord 社区。

总体而言，我们优先关注提升可靠性、可扩展性、速度和成本效益。如果您有兴趣参与贡献，修复 bug 和进行小幅改进是入门的最佳方式。对于更复杂的功能，我们强烈建议您在开始之前先联系我们的 Discord 社区 中的 Miguel Gonzalez 或 Paul Klein，以确保您的贡献符合我们的目标。

致谢

我们感谢以下人员对 Stagehand 的重大贡献：

• Paul Klein
• Sean McGuire
• Miguel Gonzalez
• Sameel Arif
• Thomas Katwan
• Filip Michalsky
• Anirudh Kamath
• Jeremy Press
• Navid Pour

许可证

根据 MIT 许可证授权。

版权所有 © 2025 Browserbase, Inc.

Stagehand 快速上手指南

Stagehand 是一个结合了 AI 能力与代码精度的浏览器自动化框架。它允许开发者通过自然语言或代码控制浏览器，既适合处理未知的页面导航，也能构建可重复、自愈的生产级工作流。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议安装最新 LTS 版本（v18+）。
• 包管理器: 推荐使用 pnpm（项目原生支持），也可使用 npm 或 yarn。
• API 密钥:
  • LLM Provider: 需要配置大模型 API Key（如 OpenAI, Anthropic 等）。
  • Browserbase (可选但推荐): 用于更稳定的云端浏览器执行环境。

安装步骤

方法一：一键创建项目（推荐）

使用官方提供的脚手架工具快速初始化项目：

npx create-browser-app

按照提示完成项目创建后，进入目录并安装依赖。

方法二：从源码构建

如果您希望直接基于源码开发或贡献代码：

git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install
pnpm run build

配置环境变量

Stagehand 运行需要 LLM 和 Browserbase 的凭证。在项目根目录下复制示例配置文件并填入您的密钥：

cp .env.example .env
# 使用您喜欢的编辑器编辑 .env 文件，填入 API_KEY 等必要信息
nano .env 

基本使用

Stagehand 的核心优势在于混合使用代码控制与 AI 指令。以下是一个典型的 TypeScript 使用示例：

1. 初始化与导航：使用标准代码控制浏览器跳转。
2. 执行动作 (act)：使用自然语言让 AI 执行单个操作（如点击）。
3. 多步任务 (agent)：让 AI 代理执行复杂的多步流程。
4. 数据提取 (extract)：利用 AI 从页面提取结构化数据。

// 获取当前页面上下文并导航
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");

// 使用 act() 执行单个自然语言指令
await stagehand.act("click on the stagehand repo");

// 使用 agent() 执行多步任务
const agent = stagehand.agent();
await agent.execute("Get to the latest PR");

// 使用 extract() 提取结构化数据
const { author, title } = await stagehand.extract(
  "extract the author and title of the PR",
  z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
);

运行示例脚本测试安装是否成功：

pnpm run example

提示：详细文档请访问 docs.stagehand.dev。如需 Python 版本，请参阅 stagehand-python 仓库。