你的自动化脚本又双叒叕崩了？

如果你正在寻找一种兼具传统代码的稳定可靠 与AI 的超强适应性 的自动化方案，那么 Stagehand 正是你的答案。

它开辟出一条绝妙的"中间道路"，让你能精准地掌控自动化流程。话不多说，让我们一探究竟！👇

换个思路玩 AI 自动化 💡

自动化的两难：在"脆弱"与"失控"之间

长期以来，浏览器自动化开发者一直在两个极端之间摇摆：

1. 传统工具的"脆弱"：我们依赖的 Selenium 或 Playwright，功能强大，却被**选择器（Selector）**牢牢捆绑。前端稍作调整，脚本立刻崩溃。维护那些与页面结构"写死"的选择器，就像一场永无止境的噩梦。
2. AI 智能体的"失控"：新兴的 AI Agent 仅需自然语言指令便能工作，看似美好。但它们的行为往往难以预测，决策过程如同"黑箱"。对于要求稳定、可复现的生产环境而言，这种不确定性是致命的。

那么，有没有一种方法，既能摆脱脆弱的选择器，又能让 AI 的行为完全受我们掌控？

Stagehand 的答案：代码与 AI 的完美融合

Stagehand 给出的答案是：把最终控制权还给开发者！

它没有在两个极端中做取舍，而是走出了一条优雅的"中间道路"，巧妙地将代码的稳定可控 和AI的灵活强大结合起来。你可以像驾驶一辆拥有顶级辅助驾驶功能的汽车，自由决定何时自己掌控，何时让 AI 接管。

• 对于固定不变的操作：比如打开某个网址，你完全可以沿用 Playwright 的原生代码，稳定可靠！

  await page.goto('https://github.com');

• 对于那些总在变化、不想硬编码的部分：比如点击一个按钮，直接交给 AI 一句自然语言指令就行了！

  await page.act('点击购买按钮');

这样一来，你再也不用二选一了。可以在每个操作的粒度上，精确控制 AI 的介入程度。这正是成熟的 AI 工程思想：从"完全自主"进化到"受控自主"，实现了稳定性与灵活性的完美平衡。

Stagehand 是如何"看见"网页的？

基于 Playwright：坚实可靠的骨架

Stagehand 没有重复造轮子，而是明智地站在了巨人------微软 Playwright 的肩膀上。这意味着：

• 性能卓越：继承了 Playwright 强大的跨浏览器能力和执行效率。
• 无缝兼容 ：完全兼容 Playwright 的 API！你已有的知识和代码可以无缝迁移，随时能回退使用原生 API，安全感满满。

智能大脑：LLM + 更聪明的页面"地图"

Stagehand 的智能源于其集成的大语言模型（LLM）。但它给 LLM 阅读的页面"地图"，并非杂乱的原始 DOM 代码。

这里的点睛之笔是：Stagehand 主要使用 Chrome 可访问性树 (Accessibility Tree)。

这是什么？你可以把它想象成一个为屏幕阅读器等辅助工具准备的、网页内容的"精华摘要"。它剥离了所有复杂的布局细节，只保留页面的核心语义信息，比如：这是一个"按钮"，它的名字是"登录"。

将这种更接近人类理解方式的信息喂给 LLM，效果出奇地好。自动化逻辑从此与脆弱的 HTML 结构解耦。无论按钮外面嵌套了多少层 div，class 名怎么变，只要它在语义上依然是那个"登录按钮"，Stagehand 就能大概率找到它！这就是它高鲁棒性的核心秘诀。

✨ 四大核心"法术"：掌控 AI 的指令集

Stagehand 提供了四个核心"法术"，构成了一个从手动到自动的完整控制光谱。

• act：行动指令。用自然语言指挥浏览器执行一个原子操作（如点击、输入）。
• extract：提取指令。用自然语言告诉它你想从页面上"抓取"什么数据，并定义好格式。
• observe：观察指令。让 AI "侦察"页面，告诉你它计划执行哪些操作，但先不动手。
• agent：代理指令。给它一个宏观目标，让它自己规划步骤去完成一个复杂任务。

这四个指令的组合，能让你玩出各种自动化花样。

生态系统：从本地到云端

Stagehand 采用"开源核心 + 商业云"的模式，覆盖从开发到部署的全流程。

• 本地开发：框架本身开源免费，可在本地自由使用。
• 云端部署 ：当需要大规模运行时，官方云平台 Browserbase 提供海量浏览器实例、会话录像、反爬虫等企业级功能，实现无缝扩展。

---

上手实战 💪

🛠️ 马上动手：你的第一个 Stagehand 脚本

理论说了这么多，让我们一起动手，编写一个 Stagehand 脚本！

3.1 环境准备

确保你的电脑上已安装 Node.js 或 Python。

• Node.js 项目:

  npm install @browserbasehq/stagehand zod

• Python 项目:

  pip install stagehand

一键生成项目：

如果你不想手动配置，官方提供了一个便捷的脚手架，一个命令就能生成完整的项目模板：

npx create-browser-app

3.2 🔑 配置你的 API Key

要驱动 LLM，你需要一个 API Key。可以从 OpenAI、Anthropic (Claude) 或 Google (Gemini) 官网申请。

如果你想体验云端执行，也请到 Browserbase官网 注册，获取你的 API Key 和 Project ID。

然后，在项目根目录创建一个 .env 文件，将这些 Key 填入其中：

#.env
# 选择一个你偏好的 LLM 并填入 Key
OPENAI_API_KEY="sk-..."
# ANTHROPIC_API_KEY="sk-ant-..."
# GOOGLE_API_KEY="..."

# 如果需要使用云端服务，请填入下面两项
BROWSERBASE_API_KEY="bb-..."
BROWSERBASE_PROJECT_ID="..."

3.3 举个例子: "Hello, Stagehand!"

让我们来编写一个脚本，自动打开 Stagehand 的 GitHub 页面，找到它的仓库，并提取项目描述。

TypeScript/JavaScript 版本 (index.ts)

import { Stagehand } from '@browserbasehq/stagehand';
import { z } from 'zod';
import 'dotenv/config'; // 加载环境变量

async function main() {
  // 1. 初始化 Stagehand
  const stagehand = new Stagehand();
  await stagehand.init();
  const { page } = stagehand;

  try {
    // 2. 使用 Playwright 的原生方法进行导航
    console.log('正在前往 GitHub...');
    await page.goto('https://github.com/browserbase');

    // 3. 用自然语言指挥点击！
    console.log('正在点击 Stagehand 仓库链接...');
    await page.act('click on the stagehand repo');

    // 4. 用自然语言和 Zod schema 提取数据
    console.log('正在提取仓库描述...');
    const { description } = await page.extract({
      instruction: 'extract the repository description',
      schema: z.object({
        description: z.string().describe('The short description of the GitHub repository'),
      }),
    });

    // 5. 打印成果
    console.log('\n--- 提取完毕 ---');
    console.log(`仓库描述: ${description}`);

  } finally {
    console.log('关闭会话.');
    await stagehand.close();
  }
}

main();

运行它！你会看到一个浏览器窗口自动弹出，行云流水地完成所有操作，最后在控制台打印出结果。

3.4 🚀 本地开发 vs 云端部署：一键切换

想把脚本部署到服务器上运行？很简单，在初始化 Stagehand 的时候加个参数就行。

• 本地执行 (默认):

  const stagehand = new Stagehand({ env: 'LOCAL', /*...*/ });

• 云端执行 (用 Browserbase):

  const stagehand = new Stagehand({
    env: 'BROWSERBASE',
    apiKey: process.env.BROWSERBASE_API_KEY,
    projectId: process.env.BROWSERBASE_PROJECT_ID,
    /*...*/
  });

环境切换就是这么简单，业务代码无需任何改动。

玩转三大核心指令

4.1 act(): 指哪打哪的交互核心

act() 是你和网页互动最直接的方式。使用时记住一个原则：保持指令的原子性。

不要给它 await page.act("帮我订个披萨") 这种复合指令，AI 可能会"困惑"。你应该把它拆解成一步步的清晰指令：

await page.act("点击'榴莲芝士披萨'");
await page.act("选择'大号'尺寸");
await page.act("添加到购物车");
await page.act("进入结算页面");

这样不仅成功率更高，也更容易调试。

安全提示：输入密码怎么办？Stagehand 已经考虑到了这一点。你可以使用变量替换，LLM 只会看到一个占位符，你的真实密码完全不会离开本地环境，安全感十足。

const userPassword = "super-secret-password";
await page.act({
  action: "在密码输入框中输入 %password%",
  variables: { password: userPassword },
});

4.2 observe(): 预判操作的侦察兵

observe() 是 Stagehand 的一个非常聪明的创新。它就像一个侦察兵，你给它一个指令，它会告诉你它打算怎么做，但不会真的执行。

它真正的威力在于和 act() 组合，形成 observe-act 黄金搭档模式。

1. 观察 (Observe) ：让 AI 去侦察，比如 page.observe("点击'快速开始'链接")。它会返回一个精确的、可执行的行动计划。
2. 行动 (Act) ：把这个行动计划直接交给 page.act()去执行。

// 1. 侦察兵出动！
const [quickstartAction] = await page.observe("点击'快速开始'链接");

// 2. 拿到精确计划，执行！
// 这一步是 100% 确定的，不走 AI 推理，速度飞快，省钱！
await page.act(quickstartAction);

终极玩法：加上缓存！

observe() 返回的行动计划是可以被缓存的！这意味着什么？

• 可靠性飙升：每次都执行完全相同的操作，告别 AI 的不确定性。
• 速度起飞：无需等待 AI 思考，执行起来和原生 Playwright 一样快。
• 成本骤降：只在第一次侦察时消耗 LLM token，后续无数次执行都是免费的！

这等于是把 AI 的一次性"探索"能力，固化成了你自己的、可靠的自动化资产。当页面改版导致缓存失效了怎么办？很简单，删掉缓存，让它重新"侦察"一遍，脚本就实现了自我修复！

4.3 extract(): 要啥有啥的智能提取

有了 extract()，网页抓取不再是体力活。extract() 将数据抓取的逻辑从"怎么找"转变为"要什么"，这让你的脚本变得异常坚固且易于维护。

你不用再写那些繁琐的选择器，只需要做两件事：

1. 用自然语言告诉它你要抓什么。
2. 用 Zod (TS) 或 Pydantic (Python) 定义好你想要的数据结构（schema）。

小试牛刀：假设我们要从一个电商页面上抓取所有商品的名称、价格和商家。

// 用 Zod 定义一个清晰的数据模板
const productSchema = z.object({
  products: z.array(
    z.object({
      name: z.string().describe("商品名称"),
      price: z.string().describe("商品价格，带货币符号"),
      vendor: z.string().describe("商家名称"),
    })
  ),
});

// 一句话，让 AI 帮你完成数据填充
const { products } = await page.extract({
  instruction: "提取页面上所有商品的名称、价格和供应商",
  schema: productSchema,
});

console.log(products); // 得到一个格式完美的结构化数据数组！

---

进阶之路 🚀

终极指令 agent，让它自己"想办法"

当你的任务超级复杂，无法用固定的指令序列描述时，agent 就该登场了！

5.1 什么时候召唤 Agent？

当你需要的是一个宏观目标，而不是具体步骤时。比如：

• "在这个网站上，找到贡献最多的那个人的用户名。"
• "帮我把这个工作岗位的申请表填完。"
• 当网站流程有多个分支，需要 Agent 根据上下文自主判断时。

agent 会像一个真人一样，自己观察、思考、使用工具 （调用 act、extract 等），一步步循环直到完成你的最终目标。

5.2 示例：让 Agent 帮你找信息

// 初始化 Agent
const agent = stagehand.agent();

// 给它一个大目标
const { message } = await agent.execute(
  "提取这个仓库头号贡献者的用户名"
);

// Agent 会告诉你它的执行结果
console.log(message);

5.3 终极用法：多维自愈

agent 最强大的用法之一，是作为常规脚本的"超级备胎"，实现"多维自愈"。

想象一下，你写好的脚本 act("点击'申请'按钮") 因为按钮文字被改成了"立即申请"而失败了。传统脚本就直接挂了。

但你可以这样设计：一旦 act 失败，就捕获异常，然后召唤 agent 并给它一个更宏观的目标："完成这个工作岗位的申请"。

Agent 会重新审视整个页面，发现那个新的按钮，然后规划出一条全新的路径来帮你完成任务！

这种自愈能力，已经从"找到挪了位置的按钮"（动作层面） ，跃升到了"换条路达成目标"（目标层面）！这才是构建未来超高鲁棒性系统的关键。

生产环境三要素：快、省、稳

6.1 性能优化：让脚本飞起来

• 最重要的原则：缓存！ 这是最关键的性能优化，将 observe 的结果存起来，一劳永逸。
• 上云执行：把任务部署到 Browserbase，享受全球优化的网络和秒开的浏览器。
• 并行处理 ：能同时干的活（比如抓取100个页面），就别让它们排队，用 Promise.all 或 asyncio.gather 一起上！

6.2 成本优化：把钱花在刀刃上

LLM API 是有成本的。如何节省？记住这个优先级：

1. 首选 Playwright 原生代码：零成本，最省！
2. 次选 observe-act + 缓存：一次成本，无数次免费使用，性价比极高。
3. 巧选模型 ：简单的任务用便宜的小模型（如 GPT-4o mini），复杂的 agent 任务再上昂贵的大模型。
4. 谨慎使用 agent：它的 token 消耗最大，要用在最关键的地方。

6.3 可靠性构建：打造"打不垮"的脚本

• 利用自然语言 ：act 本身就不怕 CSS 类名这种小改动。
• 多维自愈 ：关键流程一定要有 agent 作为备用容错方案。
• 自动等待：Stagehand 继承了 Playwright 强大的自动等待能力，能有效避免因页面加载慢导致的各种奇怪的失败。
• 强化监控 ：善用日志，特别是 Browserbase 的会话录制功能，任何问题都能被完整"回放"，让调试 Bug 从未如此轻松！

---

生态、局限与未来 🔭

• 生态与工具 ：Stagehand 可作为"工具包"无缝接入 LangChain ，支持 Cursor 等 AI 编辑器，并允许你自由切换 OpenAI, Anthropic, Google, Ollama 等多种 LLM 模型。
• 已知局限 ：处理复杂的 Shadow DOM 和 iframe 仍有挑战，此时可回退至 Playwright 原生 API 解决。
• 社区与愿景 ：项目在 GitHub 上非常活跃，团队秉持可靠性 > 速度 > 成本 的开发理念。Stagehand 的目标是将浏览器打造为 AI 智能体的核心操作系统，未来可期！

---

好了，轮到你了！

Stagehand 的强大之处和它背后的愿景，我们已经聊得差不多了。它不仅仅是一个工具，更是一种全新的、更智能、更具弹性的自动化思维方式。

那么，准备好升级你的自动化工作流了吗？今天就用 Stagehand 把那些脆弱的脚本改造一下，亲自感受"AI 加持"的开发体验吧！

如果你在实践中发现了什么有趣的用法，或者遇到了什么问题，欢迎在评论区留言~