3 个递进任务跑通 Stagehand：自然语言浏览器自动化上手指南

3 个递进任务跑通 Stagehand自然语言浏览器自动化上手指南【免费下载链接】stagehandThe SDK to extract data and interact with any site on the web. Get started with Claude Code, Codex, Eve, Mastra, and more.项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand我要让程序自己去商品详情页把商品名和价格读回来再顺手点一下Add to Cart。这就是 Stagehand 要解决的事你用一句自然语言描述意图定位元素和执行动作由它完成你只负责给指令、收结构化的结果。先建立心智模型谁在决策数据怎么流Stagehand 走的路径是你的指令 当前页面快照一起发给模型 → 模型决定要在 DOM 上做什么操作 → SDK 在浏览器里执行 → 结果按你给的 schema 校验后交还给你。说白了CSS 选择器这类定位工作从你的代码里消失了换成了每次调用里的一次模型推理。这意味着两点写起来短了但每次extract/act/observe都有推理开销调用次数直接决定脚本的速度和成本设计任务时先想清楚要问模型几轮。你的脚本(自然语言指令 schema) │ ▼ Stagehand SDK ──快照指令──▶ 模型 │ │ │◀───── 决定的 DOM 操作 ────┘ ▼ 本地 Chrome(Chrome DevTools Protocol) │ ▼ 结构化数据 / 动作列表回到你的脚本跑起来 本地浏览器最短可运行配置mkdir my-stagehand-app cd my-stagehand-app pnpm init -y pnpm add browserbasehq/stagehand zod~4.4.3zod 钉在 4.4.x更新的小版本会把extract()的 schema 参数报出类型错。它通过 Chrome DevTools Protocol 驱动浏览器所以先确认本机装了 Chrome。模型 key 不放进任何配置SDK 不读环境变量你在代码里显式传给Stagehand.create()。import { localBrowser, Stagehand } from browserbasehq/stagehand; const browser await localBrowser.launch(); const stagehand 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://example.com); console.log(Stagehand session started); await stagehand.close(); await browser.close();pnpm dlx tsx index.ts执行。跑通的标志几秒内弹出一个 Chrome 窗口地址栏落到目标页控制台先打印Stagehand session started。如果不想依赖本机 Chrome把localBrowser.launch()换成browserbase.launch({ apiKey })浏览器跑在云上不指定模型时由 Model Gateway 自动选一个。任务 1读回一个结果extract 拿结构化对象目标不写任何选择器把详情页的商品名和价格读回成类型化对象。import { z } from zod/v4; const { data } await stagehand.extract( Extract the product name and price from this page, z.object({ name: z.string(), price: z.number() }), ); console.log(data); // { name: Example T-Shirt, price: 19.99 }与传统做法对比xpath 定位、取文本、再parseFloat清洗格式这一串现在压缩成一句话 一个 schema返回的就是按 schema 校验过的对象不是要你二次加工的字符串。顺带一提extract的完整返回里还有metadata同一页面重复同样的指令时第三参数传{ cache: { threshold: 1 } }可命中服务端缓存、直接省掉模型调用需配合browserbase浏览器。任务 2触发一个页面操作act 要查 success目标点击Add to Cart并确保脚本知道点没点成。const r await stagehand.act(Click the Add to Cart button); console.log(r.data); if (!r.data.success) throw new Error(act failed: ${r.data.message});运行结果点击后页面角落的商品数 1r.data形如{ success: true, message: ... }。关键认知act失败不会抛异常而是把原因放在message里所以调用了不等于成功了生产脚本里这一行检查建议留着。任务 3让程序自己判断下一步observe 先看后动目标不再写死点哪里让程序先列清单再自己挑一个执行。const { data: actions } await stagehand.observe( Find the clickable buttons on the page, ); if (actions.length 0) throw new Error(no actions found); await stagehand.act(actions[0]);actions是一组Action对象每个都带instruction和selector。第二个act传入的是 observe 的产物而非自然语言走的是确定性重放跳过模型推理也跳过页面快照执行快且可复现。进阶用法把 observe 拿到的selector用page.locator(selector)圈出子树再传给extract它只看那部分 DOMtoken 用量随排除的范围同比下降。踩坑与经验本地浏览器没有免费模型localBrowser连不了 Model Gatewaymodel配置模型名 API key是必填项缺了会在create()时报错这是新手最常见的第一次失败。zod 版本漂移pnpm add zod~4.4.3别用最新版schema 类型对不上会在编译期就拦住你。重放失败时别急着重写指令对 Action 重放加selfHeal: true记录的选择器失效时会重新推理一次并重试站点小改版不至于报废整条脚本。observe 可能返回空列表指令和页面对不上时data.length 0喂给act之前先判长度否则拿到的是运行时报错而不是可读日志。边界两种场景别用它选择器长期稳定的固定 E2E 流程用 Playwright 的 locator 加断言即可模型推理只会拖慢每次运行还给断言引入不确定性。页面结构不变的大批量高频采集走固定解析管道更经济每次调用都含模型请求成本和延迟在批量场景下不划算。下一步三处官方资料快速入门从建项目到首次运行的完整脚本与三种语言对照第一次跑通跟着它抄即可。act 基础文档act / extract / observe 的完整参数、selfHeal与缓存机制调用失败时先翻这里。官方示例目录13 个可直接改着跑的脚本覆盖文件上传、自定义模型、服务端缓存等场景。回到开场那个任务商品页的数据已经读回来了Add to Cart也点掉了。下一个页面换成竞品的把第一段的指令改成一个字脚本就能再跑一遍。【免费下载链接】stagehandThe SDK to extract data and interact with any site on the web. Get started with Claude Code, Codex, Eve, Mastra, and more.项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考