Stagehand：自然语言驱动的浏览器自动化框架

Stagehand：自然语言驱动的浏览器自动化框架

当你在写一个需要登录、翻页、抓取数据的脚本时，最烦人的不是逻辑，而是那些该死的 #id、.class 选择器和 waitForSelector 的调试。Stagehand 直接解决了这个问题：用自然语言描述操作，它自动解析 DOM 并执行。你不再需要手写 XPath 或 CSS 选择器，只需要说“点击搜索框，输入‘Python 教程’，然后按回车”。

项目背景

Stagehand 由 Browserbase 团队开发，他们之前做的是云端无头浏览器服务。在实际服务中，他们发现大量用户反馈：“我的脚本总是因为页面结构变化而崩溃”，“写选择器太痛苦了”，“我只想抓个数据，为什么要学 Puppeteer 的 API？”

于是他们决定做一个 AI-first 的浏览器自动化框架：把 DOM 解析和操作决策交给大语言模型（LLM），开发者只需要描述“做什么”，而不是“怎么做”。这直接解决了传统自动化工具的两个核心痛点：选择器脆弱性和调试成本高。

核心功能解析

自然语言指令驱动

这是 Stagehand 最核心的能力。你传入一个字符串指令，框架自动分析当前页面 DOM，调用 LLM 生成操作序列并执行。不需要写 page.click('#submit-btn')，只需要写：

await page.act({ action: "点击页面上的'提交'按钮" });

框架会返回操作是否成功、执行了什么步骤、以及当前页面状态。对于多步操作，可以用 instructions 参数描述一个完整流程：

await page.act({
  action: "在搜索框输入 'machine learning'，然后点击搜索按钮",
  variables: { query: "machine learning" }
});

智能数据提取

传统抓取需要写 document.querySelectorAll('.item .title') 然后遍历。Stagehand 的 extract 方法可以直接用自然语言描述你要的数据结构：

const result = await page.extract({
  instruction: "提取页面上所有文章的标题和摘要",
  schema: {
    type: "object",
    properties: {
      title: { type: "string" },
      summary: { type: "string" }
    }
  }
});

框架会返回结构化的 JSON 数组，不需要你关心 DOM 结构。如果页面是动态加载的，它会自动等待内容渲染完成。

自动等待与重试

传统自动化中，waitForSelector 和 setTimeout 是调试噩梦。Stagehand 内置了 智能等待机制：当指令执行失败时，它会自动重试（默认 3 次），并在每次重试前重新分析 DOM。这意味着即使页面因为异步加载、动画或网络延迟导致元素暂时不可见，框架也能自动处理。

// 不需要手动等待，框架会自动处理
await page.act({ action: "点击'加载更多'按钮，直到没有更多内容" });

快速上手

安装并运行一个 Stagehand 脚本只需要 3 步。确保你已经有 Node.js 18+ 和 OpenAI API Key（或其他兼容的 LLM 服务）。

# 1. 创建项目并安装
mkdir stagehand-demo && cd stagehand-demo
npm init -y
npm install @browserbasehq/stagehand

# 2. 创建脚本文件 index.mjs
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL", // 使用本地浏览器
  apiKey: process.env.OPENAI_API_KEY,
});

await stagehand.init();
await stagehand.page.goto("https://news.ycombinator.com");
const stories = await stagehand.page.extract({
  instruction: "提取所有故事的标题和链接",
  schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        title: { type: "string" },
        url: { type: "string" }
      }
    }
  }
});
console.log(stories);
await stagehand.close();

# 3. 运行
export OPENAI_API_KEY="sk-xxx"
node index.mjs

技术亮点

Stagehand 最值得关注的设计决策是 “AI 作为运行时决策者”，而不是简单的“AI 生成代码然后执行”。这体现在两个关键架构选择上：

第一，分层 DOM 表示。Stagehand 不会把整个 HTML 文本丢给 LLM（那样 token 消耗巨大且容易超出上下文窗口），而是先对 DOM 进行简化：提取可见元素、计算元素位置和角色、生成一个轻量级的“语义快照”。这个快照只包含对用户可见的、可交互的元素，大小通常只有原始 HTML 的 5%-10%。然后 LLM 基于这个快照做出决策，比如“点击哪个按钮”或“输入什么内容”。

第二，操作验证与回退。每次 act 调用后，框架会检查页面状态是否发生了预期变化（比如 URL 变了、新元素出现了）。如果变化不符合预期，它会标记这次操作为“失败”，并让 LLM 重新分析当前 DOM 生成替代方案。这实际上形成了一个 感知-决策-执行-验证 的闭环，比传统 Puppeteer 脚本的线性执行要健壮得多。

另一个值得注意的点是 模型无关性。Stagehand 默认使用 OpenAI，但通过抽象接口可以切换到 Claude、Gemini 甚至本地模型。这意味着你可以根据成本、延迟和隐私需求灵活选择后端。

同类对比

注意：Stagehand 不适合对性能有极致要求的场景（比如每秒处理 1000 个页面），因为每次操作都需要一次 LLM 调用，延迟在 1-3 秒。但对于日常的数据抓取、表单填写、UI 测试，它的开发效率提升是碾压级的。

总结

如果你厌倦了调试选择器、维护脆弱的自动化脚本，或者需要快速抓取一个结构复杂的页面，Stagehand 是 2024 年最值得尝试的浏览器自动化工具。 它把“写代码”变成了“描述需求”，让非专业开发者也能够完成复杂的浏览器操作。适合数据工程师、QA 测试人员、以及任何需要和网页打交道的开发者。