stagehand

用途

Stagehand 是 Browserbase 的浏览器智能体 SDK，提供 TypeScript、Python 和 Go 版本（v4）。它把常见的 Chromium 页面/定位器 API 与三个模型辅助原语结合，用于构建可维护的浏览器自动化流程。仓库另附独立的 browse CLI，面向终端优先的浏览器会话和 Browserbase 资源操作。

主要能力

observe()：发现页面上的可操作元素，返回可执行动作，便于检查后重放。
act()：执行单条自然语言动作，或重放已观察到的动作而不再调用模型。
extract()：按 Zod、Pydantic 或 Go schema 校验并返回抽取数据。
支持页面注册的 WebMCP 工具（含 schema 与只读、不可信内容、自动提交等注解）。
提供 Browserbase 云端 search() 与 fetch() 辅助方法。
browse CLI 支持 snapshot 驱动的导航、云会话、Fetch/Search、网络诊断、Functions、模板等操作。

使用方式

安装前先运行只读预检脚本，确认工具、运行时版本、浏览器和项目清单情况（只报告密钥是否存在，不输出密钥值）：

node scripts/stagehand-preflight.mjs --json
node scripts/stagehand-preflight.mjs --language ts --local --model --json
node scripts/stagehand-preflight.mjs --language cli --remote --json

按需安装一种运行面：

pnpm add @browserbasehq/stagehand@4.1.0 'zod@~4.4.3'
pip install stagehand
go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0
npm install -g browse

TypeScript SDK 需 Node.js >=22.18.0，Python 需 >=3.11，Go 需 >=1.26；browse CLI 接受 Node.js ^20.19.0 || >=22.12.0。

浏览器执行面三选一：本地 Chromium（localBrowser.launch()）、Browserbase 云端（browserbase.launch()）、或通过 localBrowser.connect({ cdpUrl }) 连接已有 CDP 端点。

驱动页面时建议小步推进：导航、检查、执行一个动作、验证、再抽取。稳定 DOM 用显式 page.locator() 与等待；敏感值走真实定位器或环境变量，不进入自然语言指令。每个改变状态的动作后验证 URL、可见状态或类型化抽取结果。

CLI 示例：

browse open https://example.com --local
browse snapshot
browse click @0-5
browse stop

适用场景

在 TypeScript、Python 或 Go 中构建或维护 Stagehand v4 流程。
在本地 Chromium、Browserbase 云会话或已有 CDP 连接之间做选择。
用有界的 observe()/act() 或类型化 extract() 替代脆弱选择器，同时对敏感字段保留确定性定位器。
发现并调用页面的 WebMCP 工具。
将 Playwright 流程迁移到 Stagehand v4 并识别不支持的假设。

限制

Stagehand v4 通过 CDP 驱动 Chromium，不接受 Playwright Page，无直接互操作；Playwright 的自动等待、getBy*、expect() Web 断言、路由拦截、trace viewer 和 codegen 没有直接对应物。
在 Aside 会话沙箱内，Chrome 二进制可见但从会话 shell 启动会立即中止（SIGABRT，退出码 134），包括 --headless=new；此时需用 Browserbase 云端或沙箱外启动的 CDP 端点。
Stagehand 无法附着到 Aside 自身浏览器标签页，需改用 Aside 原生 repl 工具。
若需复用用户已打开且已认证的浏览器配置和实时标签页，应使用 playwriter。
当任务只是解析优先抓取、有界爬取或简单渲染获取，或只需要普通 Playwright 测试运行器时，不宜使用本技能。
安装、启动远程会话、使用已存上下文、提交表单或消耗付费配额等动作，需在相应动作处获得明确批准；本地模型/提供商调用、Browserbase 会话时间、Model Gateway、Search/Fetch、代理等可能产生费用。

技能介绍

用途

主要能力

使用方式

适用场景

限制