Stagehand 自愈式浏览器自动化实操指南【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是面向浏览器代理browser agent的 SDK用自然语言驱动 act、observe、extract 三个原语操作网页网站改版后动作可自动自愈。本文面向要落地浏览器自动化的开发者按装、配、跑、调的路径讲清如何跑通首个脚本再用缓存与模型参数压低成本。安装与配置两条命令搭好 Stagehand 开发环境安装本身很快但配置一步做对浏览器来源、缓存开关能避免后面反复返工因为 act、extract、observe 的调用方式都依赖这个实例。准备依赖与 Browserbase API keyTypeScript 项目只需装两个包再导出一个环境变量。Stagehand 不会替你读环境变量key 要在代码里显式传入。key 在 Browserbase 控制台获取下面这段命令完成安装并设置 key# 在现有 TS 项目里安装 SDK 和 schema 库 pnpm install browserbasehq/stagehand zod # Stagehand 不自动读环境变量key 由代码显式传入 export BROWSERBASE_API_KEYbb_live_...最小配置一个 browser 对象加缓存开关创建实例只需一个 browser 对象不配 model 时请求走 Model Gateway由 Browserbase 自动选模型不需要各家模型商的账号import { browserbase, Stagehand } from browserbasehq/stagehand; // 不配 model 时走 Model Gateway由 Browserbase 自动选模型 const browser await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY }); const stagehand await Stagehand.create({ browser, cache: true, // 服务端缓存重复操作不再消耗 LLM token }); const [page] await browser.context.pages(); await page.goto(https://stagehand.dev);配置完成后act、extract、observe 立即可用。本地开发调试时可把browserbase.launch()换成localBrowser.launch()省去云端会话费用。跑observe 先规划act 再执行extract 收数据直接把一句话丢给 act 能跑通但先用 observe 看一眼模型打算做什么能省掉试错也避免误点提交、误发订单这类带副作用的操作。observe 规划动作act 回放执行observe 只规划、不触碰页面把它的结果交回 act 执行时跳过推理属于确定性回放// observe 只规划不触碰页面返回带 selector 的动作列表 const { data: actions } await stagehand.observe(click the login button); // 把 observe 的 Action 交回 act跳过推理确定性回放 await stagehand.act(actions[0]);多步流程用一次 observe 规划多个动作、再逐个回放整个流程只付一次 LLM 调用。extract 按 schema 拿结构化数据extract 同时接收指令和输出形状TypeScript 用 Zod返回值先按 schema 校验再交给业务代码字段类型是确定的import { z } from zod/v4; // schema 决定返回形状结果先校验再返回 const { data } await stagehand.extract( extract the author and title of the PR, z.object({ author: z.string(), title: z.string() }), );调缓存、模型与超时三个参数压成本提速度脚本能跑之后账单和耗时才是日常痛点。这三个参数是官方文档里改动最小、收益最直接的部分。服务端缓存重复调用直接回放缓存由 Browserbase 在服务器侧管理键由指令、页面内容和调用选项构成模型配置不参与键所以换模型不会让缓存失效// threshold 控制连续多少次相同结果后开始命中1 表示首次成功即可复用 const stagehand await Stagehand.create({ browser, cache: { threshold: 1 } }); const result await stagehand.act(click the sign in button); console.log(result.metadata.cache.status); // HIT | MISS | DISABLED注意两点带 locator 或 ignoreLocators 的调用会绕过缓存状态显示 DISABLED缓存只对有 Browserbase 会话的实例生效本地浏览器上 cache 选项不起作用。按任务难度切模型日常操作用便宜模型个别难任务用单次调用覆盖换强模型比整体升级模型省得多// 默认走便宜模型这一条难提取单独指定强模型 const terms z.object({ summary: z.string() }); await stagehand.extract(summarize the contract terms, terms, { model: { modelName: anthropic/claude-sonnet-4-6, apiKey: process.env.ANTHROPIC_API_KEY }, });速度侧同样有一行改法页面稳定的场景把domSettleTimeoutMs从默认 5000ms 调小每次 act 前等待 DOM 稳定的时间都会缩短。验证用 metadata 和 metrics 确认调优生效调参不看数据等于盲调。Stagehand 把缓存命中和 token 用量直接挂在每次调用的结果上不用额外接监控系统。读缓存状态与 token 指标每次调用的 metadata 带缓存状态命中时还能看到省下的 token实例级的 metrics 汇总整个会话的用量const result await stagehand.act(click the login button); console.log(result.metadata.cache.status); // HIT 说明这次没有 LLM 开销 const metrics await stagehand.metrics(); console.log(metrics.totalPromptTokens, metrics.totalCompletionTokens);metrics 报的是 token 数而非金额乘上模型商定价页的输入、输出单价就是成本。跑在 Browserbase 上时会话的录屏回放、网络请求、CPU 内存占用都在控制台可见排查卡住的流程比读日志直观。小结Stagehand 把浏览器自动化拆成三个原语加一组可调参数observe 规划、act 执行、extract 取数再用缓存、模型覆盖和超时参数控制成本与速度。按装、配、跑、调的顺序过一遍脚本从能跑到省钱就是一组参数的事。资源索引快速开始act 参考observe 参考extract 参考缓存最佳实践成本优化速度优化模型配置与 Model GatewayTypeScript 官方示例脚本【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考