企业官网建设流程全解析

Stagehand 快速上手指南：4 个真实场景搭出自愈式浏览器自动化 Agent

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

Stagehand 是一个面向浏览器 Agent 的浏览器自动化 SDK。给它一句自然语言，它就能替你完成网页上的点击、填表和取数。和测试框架不一样：它的动作可以“自愈”，喂给模型的页面上下文事先裁剪过，TypeScript、Python、Go 三套 SDK 都能跑。全文按 4 个真实场景走，场景之间互相独立，从离你最近的那个开始就行。

准备工作：两步完成 Stagehand 环境配置 ✅

先解决“跑不起来”的问题，全程只要两分钟。

在项目目录里安装 SDK（要求 Node.js 22.18+）：pnpm add @browserbasehq/stagehand zod即可，npm、yarn 同理。v4 通过 CDP 协议直连浏览器，不用再单独装 Playwright；想用自己的本地 Chrome 跑，就先在本机装好 Chrome。

然后把密钥放进环境变量：云浏览器需要BROWSERBASE_API_KEY；OPENAI_API_KEY这类模型密钥只有在你想指定模型时才要配，不配的话会自动选一个。注意 Stagehand 不会替你读 env 文件，密钥要在代码里自己取出来显式传进去。

完整安装清单和各语言变体说明在 packages/docs/v4/first-steps/installation.mdx。环境就绪，下面进场。

场景一：说一句“点它”，页面就听话 —— act 自然语言操作

选择器写不稳、或者根本不想维护选择器？看这一节。

把 act 想象成一个有眼睛的临时工：你只用一句人话说“把搜索框填上‘机械键盘’”，不用关心要点哪个 div、哪个 class。Stagehand 自己定位元素并执行。

import "dotenv/config"; import { localBrowser, Stagehand } from "@browserbasehq/stagehand"; // 起一个本地浏览器，创建 Stagehand 实例 const browser = await localBrowser.launch({ headless: false }); const agent = await Stagehand.create({ browser, model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY, }, }); const [page] = await browser.context.pages(); await page.goto("https://shop.example.com"); await agent.act("fill the search box with 'mechanical keyboard'");

这段代码做了三件事：启动浏览器、打开一个页面、用自然语言执行一次填写。

两个小技巧：长流程拆成一条条 act，一句一步，比一句话塞满全流程更稳；滚动、下拉这类操作直接在句子里白话说就行。起步用 act 足够，等流程稳定了，再换成下一节的 observe 预览，会更稳。

场景二：把网页抓成一张表 —— extract 配 Zod 模式 📦

抓回来的东西是一团乱码文本？这一节就是治这个的。

extract 像一张表单：先填好栏目，模型只负责填格子。用 Zod schema 把返回结构写清楚——有哪些字段、什么类型——拿回来的是按 schema 校验过的类型化对象，直接落库或进表格。

import { z } from "zod/v4"; // 让模型找出页面上最便宜的商品，并按上面定义的结构返回 const { data: deal } = await agent.extract( "extract the cheapest product on the page", z.object({ name: z.string(), price: z.number(), inStock: z.boolean(), }), ); console.log(deal.name, deal.price);

这段代码做一件事：让 Stagehand 从页面里提取一个“商品”，保证 name / price / inStock 三个字段齐全地回来。

字段类型对不上会校验失败并重试，脏数据进不了下游流程。

场景三：先侦察再动手 —— observe 预览可点元素

模型点错了还不知道为什么？给它加一步“侦察”。

observe 什么都不点，只回答“这个页面上现在能干什么”。它返回一串候选动作，每条都带选择器、方法（click、fill……）和一句人话描述。妙处在于：你确认哪条，就把哪条原样丢回 act，它会直接重放那个动作——第二次模型调用都省了，完全确定。

// 先让模型把页面上所有可点目标列出来 const { data: candidates } = await agent.observe( "find every button on the page", ); const [first] = candidates; if (first?.method === "click") { // 重放：不做推理，直接执行 await agent.act(first); }

这段代码先侦察，再从侦察结果里挑第一条候选动作确定性地执行。

像侦察兵报点、执行人照着地图走。需要审计或缓存流程里每一步时，“先侦察再重放”就是标准姿势。

场景四：网站改版了，脚本不坏 —— 自愈与缓存 ⚡

“自动化脚本隔三差五就得重写”这个老毛病，Stagehand 给了三层保护。

第一层是自愈：记录的选择器失效时，Stagehand 会察觉并自动重新推断该怎么操作。第二层是服务端缓存：同样输入的动作重复执行时直接命中缓存、立刻返回，模型开销为零（需在 Browserbase 云浏览器上开启）。第三层是 token 瘦身：喂给模型的页面上下文按可访问性树裁剪过，Agent 只读到该读的部分，省 token 也更快。

流程里带密码的，用%password%这种变量占位符写进指令即可，值在本地替换，模型只能看到占位名。

这张图展示的是会话回放：每次浏览器自动化会话里，每个 extract、act、observe 调用都有时间线可查，流程跑挂时能直接定位到是哪一步出的问题。

小结：把自愈和缓存打开之后，“网站改版”这件事，就从“重写脚本”变成了“等它自己修好”。

跑通之后的两个动作：开缓存、接回放

四个场景都跑通后，再做两件事：把缓存打开，同一流程多跑几轮，第二轮起基本都是命中；再把会话接到回放上看。这两步做完，几句自然语言写出来的脚本，才算一个敢上生产的流程。

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand