Stagehand 快速上手指南4 个真实场景搭出自愈式浏览器自动化 Agent【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是一个面向浏览器 Agent 的浏览器自动化 SDK。给它一句自然语言它就能替你完成网页上的点击、填表和取数。和测试框架不一样它的动作可以“自愈”喂给模型的页面上下文事先裁剪过TypeScript、Python、Go 三套 SDK 都能跑。全文按 4 个真实场景走场景之间互相独立从离你最近的那个开始就行。准备工作两步完成 Stagehand 环境配置 ✅先解决“跑不起来”的问题全程只要两分钟。在项目目录里安装 SDK要求 Node.js 22.18pnpm add browserbasehq/stagehand zod即可npm、yarn 同理。v4 通过 CDP 协议直连浏览器不用再单独装 Playwright想用自己的本地 Chrome 跑就先在本机装好 Chrome。然后把密钥放进环境变量云浏览器需要BROWSERBASE_API_KEYOPENAI_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
