Stagehand AI 浏览器自动化实战指南5 个真实场景让脚本更稳更省【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是一个为浏览器 Agent 而生的 SDK它把网页的无障碍树交给大模型理解让你用一句自然语言就能完成点击、填表和数据提取同时提供 TypeScript、Python、Go 三套官方 SDK。这篇文章不罗列功能而是按真实项目里最常遇到的五个问题——重复执行烧钱、多步流程慢、多页面并行、成本失控、何时让 AI 自主浏览——逐一给出 Stagehand 的官方做法。每个方案都能在官方文档里找到对应实现照着做即可验证。先用 10 行脚本建立手感第一次接触 Stagehand只需要认识三个核心方法。安装后用 Browserbase 云端浏览器启动一个会话本地调试可换成localBrowser.launch()无需 API keypnpm install browserbasehq/stagehand zodimport { browserbase, Stagehand } from browserbasehq/stagehand; const browser await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY }); const app await Stagehand.create({ browser }); const page (await browser.context.pages())[0]; await page.goto(https://example.com/search); // 1. 操作页面自然语言即可 await app.act(type 手机壳 into the search box); // 2. 提取结构化数据用 zod 描述你要的形状 const { data } await app.extract( extract the first three product titles, z.object({ items: z.array(z.string()) }), ); // 3. 探测页面不执行只列出可执行的动作 const { data: actions } await app.observe(find the filter buttons);三个方法各管一摊后面所有技巧都是围绕它们展开的方法做什么关键特点act()执行一个操作点击、输入、滚动、拖拽等传自然语言会触发推理传observe()的Action则直接回放observe()只读探测返回一组Action含选择器、方法、参数不触碰页面可用来做计划和校验extract()按 schema 提取结构化数据TypeScript 用 zod、Python 用 Pydantic 校验后返回完整入门步骤见 quickstart 文档可运行的示例代码在 packages/sdk-ts/examples/。场景一同一流程天天跑如何不再重复付推理费问题一个登录流程或固定报表采集每天都在执行页面没变但每次都完整调用大模型费用随运行次数线性增长。做法Stagehand 在服务端缓存act()、observe()、extract()的结果。开启方式是在初始化时加一个选项const app await Stagehand.create({ browser, cache: true, // 服务端缓存也可写成 cache: { threshold: 2 } 控制生效门槛 });threshold命中门槛浏览器端需要看到多少次相同结果后才开始直接回放。设为1时第二次相同调用即命中。如何验证每次调用的metadata.cache.status会返回HIT、MISS或DISABLED命中时还会记录节省的 token 数效果可直接量化。自愈机制缓存回放是确定性的。如果页面改版导致记录的选择器失效Stagehand 会自动退回完整推理并把新结果写入缓存流程不会中断。注意缓存依赖 Browserbase 会话本地浏览器下该选项不生效。详细的键构成指令 页面内容 参数、动态值处理与失效边界见 caching 最佳实践。场景二多步流程太慢先 observe 做计划再批量回放问题填一个 8 个字段的形式如果写 8 次act(填写 xx 字段)就要做 8 次模型推理既慢又贵。做法利用observe()的只规划不执行特性一次推理拿到全部字段的Action再循环回放。回放传入的是Action对象而非自然语言Stagehand 会直接按记录的选择器和方法执行不再推理// 一次推理规划所有字段 const { data: fields } await app.observe(find all input fields in the signup form); // 逐个回放后续步骤零推理开销 for (const field of fields) { await app.act(field); }官方基准测试中一个填表 → 提交 → 确认的三步流程用这种模式从约 8 秒降到约 0.5 秒推理次数从 3 次变为 1 次。进阶动态值不要写进指令。账号、密码这类值如果拼在指令字符串里会随每次运行变化而破坏缓存还可能进入模型上下文。用variables占位符模型只看到%password%真实值在执行前本地替换await app.act(fill the login form, { variables: { username: aliceexample.com, password: process.env.USER_PASSWORD, }, });该模式的完整讲解与耗时对比见 speed-optimization 文档。场景三多个页面同时处理用多标签页并行问题需要同时采集两个竞品页面或对比多个搜索结果串行执行把总时长翻倍。做法在同一个浏览器上下文里开多个标签页每个调用通过page选项指定目标页再用Promise.all并发const pageA await browser.context.newPage(); const pageB await browser.context.newPage(); await Promise.all([pageA.goto(urlA), pageB.goto(urlB)]); const [resA, resB] await Promise.all([ app.extract(extract the pricing table, PriceSchema, { page: pageA }), app.extract(extract the pricing table, PriceSchema, { page: pageB }), ]);两个容易踩的坑页面对象是固定的点击后如果浏览器打开了新标签页之前持有的page仍指向旧标签要么重新读取活动页要么为每个标签显式持有引用。locator 属于创建它的页一个标签页上生成的 locator 不能拿去另一个标签页解析。多标签页的完整模式包括setActivePage切换默认目标见 using-multiple-tabs 文档。场景四成本账单怎么控住三个可量化的旋钮问题任务量上来后模型调用费 浏览器会话费开始可见地增长。Stagehand 提供的控制手段可以归纳为三个旋钮旋钮配置位置效果模型选择model选项 / 单次调用覆盖简单步骤用轻量模型难步骤临时升级会话生命周期browserbase.launch的timeout、keepAlive缩短空闲计费时间跨任务复用会话用量监控app.metrics()拿到 prompt / completion / 缓存 token 数模型选择不配置model时Model Gateway 会为每次调用自动选模型一个 key 出账单想精细控制时可以在单次调用上覆盖// 默认轻量模型处理绝大多数步骤 const app await Stagehand.create({ browser, model: { modelName: google/gemini-2.5-flash }, }); // 只在关键的一次提取上升级到强模型 await app.extract(summarize the contract terms, TermsSchema, { model: { modelName: anthropic/claude-sonnet-4-6 }, });会话复用把timeout从默认的 1 小时调短如 30 分钟并对连续任务开启keepAlive复用会话避免每次冷启动。用完记得await app.close()和await browser.close()。用量监控metrics()返回 token 计数不直接返回金额乘以供应商的输入/输出单价即可换算成本其中totalCachedInputTokens单独列出方便确认缓存命中带来了多少折扣。模型路由规则、会话参数与预算控制的完整参考见 models 配置 和 cost-optimization 文档。场景五什么时候该让 AI 自主浏览整个任务问题任务不是固定流程而是打开 Hacker News找出今天最有争议的帖子总结前三条评论这种需要 AI 自己看屏幕、自己决策的步骤。现状说明以仓库内文档为准v3 时代Stagehand 内置agent()支持mode: cua对接 Google、Anthropic、OpenAI 的 Computer Use 模型一行execute({ instruction, maxSteps })即可让模型自主操作浏览器详见 computer-use 文档。v4 时代官方移除了内置 agentv3 → v4 迁移指南 中agent({ mode: cua })标注为无等价物回归act / observe / extract三个原语把多步规划交还给你的代码或外部编排层。这也意味着自主浏览能力现在由你在三个原语之上实现——observe()看一步、act()走一步、失败时换模型重试——每一步都可控、可缓存、可回放。简单选型建议流程固定且重复→ 三个原语 缓存成本最低、最稳定任务开放、步骤不定→ v3 的 cua agent 或在你自己的编排层里用observe 规划 act 执行循环配合maxSteps类限制防止跑飞。延伸阅读文档与源码地图想做什么去哪里看安装与第一个脚本quickstart三个核心 API 详解act / observe / extract缓存键、门槛与失效规则caching提速技巧与基准speed-optimization成本控制与预算守卫cost-optimization跨运行保留登录态user-data本地用userDataDir云端用 persist context三语言可运行示例TypeScript / Python / Go掌握以上五个场景后基本覆盖了一个生产级浏览器自动化项目的全部关键决策点用缓存消除重复推理、用 observe 回放压缩多步流程、用多标签页换并行、用模型与旋钮控制账单、在流程开放时再引入自主浏览。建议下一步直接从 quickstart 跑一个脚本然后按自己项目里最先痛的那个场景深入对应章节。【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考