Stagehand 评测：给浏览器智能体用的 SDK，而不是又一套测试框架

它解决的是智能体写浏览器脚本的痛点

Selenium、Playwright、Puppeteer 这类工具要求你写低层代码，每个选择器、每次等待都要手动处理。另一类高层的 AI 代理则不可预测，生产环境里经常失败。Stagehand 的定位是夹在两者之间：保留 Playwright 风格的方法名，比如 goto、click、locator、screenshot，同时提供 act、observe、extract 这三个自然语言原语。目标用户很明确，是那些想让大模型驱动浏览器、但又不想放弃确定性和可观测性的工程团队。它不是一个测试框架，README 里直接说 Playwright 是为测试而建，Stagehand 是为智能体而建。这个区分决定了它的设计重心，比如 token 效率、自愈、对复杂 DOM 的支持，这些对测试工具来说都不是首要问题。

核心机制：混合可访问性树裁剪与浏览器内扩展

Stagehand 对页面上下文的处理是它最值得注意的部分。文档描述为 hybrid accessibility tree trimming，即混合可访问性树裁剪，目的是只给模型理解页面所需的信息，减少 token 消耗。具体做法是把可访问性树和 DOM 结构结合，去掉对决策无用的节点。这个机制不是可选的装饰，而是 act、observe、extract 能工作的基础。另一个关键设计是 Stagehand 以扩展形式运行在浏览器旁边，而不是像传统自动化那样通过远程协议来回通信。README 说这缩短了距离，降低了所有页面操作的往返延迟。这意味着每次动作不需要把整个页面状态发给模型再等响应，部分处理在浏览器本地完成。对于需要连续操作多个元素的智能体任务，这种架构能明显减少等待时间，但代价是部署复杂度更高，你得接受一个浏览器扩展作为运行时依赖。

自愈原语 act、observe、extract 的实际含义

这三个原语是 Stagehand 与普通 Playwright 脚本的分水岭。act 接受自然语言指令，比如点击某个按钮，observe 让模型描述页面上发生了什么，extract 则按 schema 抽取结构化数据。示例代码里用到了 z 库定义 schema，说明 extract 的输出是强类型的。自愈的机制是当网站结构变化导致原有选择器失效时，Stagehand 会检测到并自动刷新动作的执行方式。这不是魔法，它依赖模型对页面的重新理解。所以自愈的可靠性直接绑定到所选模型的质量，以及混合可访问性树能否提供足够的上下文。如果模型理解错了新结构，自愈可能选错元素。README 没有给出自愈失败时的降级策略，这一点在生产环境里需要你自己补上重试和告警逻辑。

运行方式：从安装到第一个 act 示例

仓库是 TypeScript、Python、Go 的 monorepo，用 just 命令驱动 pnpm、uv 和 go。克隆后执行 just install、just generate、just build 即可完成构建。示例代码展示了 TypeScript 的用法：先通过 browserbase.launch 启动浏览器，需要 BROWSERBASE_API_KEY，然后调用 Stagehand.create 传入浏览器实例和模型配置，模型名是 openai/gpt-5.4-mini，需要 OPENAI_API_KEY。之后用 page.goto 导航，再调用 act 之类的原语。注意这个例子隐含了一个前提，浏览器由 Browserbase 云服务提供，而不是本地 Chromium。如果你想在本地跑，文档里没有给出替代方案，只能从仓库布局推测可能支持，但 README 明确说最好有 Browserbase 凭证。这意味着评估 Stagehand 时，你不能只测 SDK 本身，还得把 Browserbase 的计费和网络延迟算进去。

多语言支持与复杂 DOM 处理

Stagehand 不是 TypeScript 专属，仓库里有 packages/sdk-python 和 packages/sdk-go，README 提供了对应的示例链接。这解决了智能体后端语言不统一的问题，一个团队可以在 Python 服务里用 Stagehand，另一个 Go 服务也能接入同样的浏览器驱动。对于复杂 DOM，README 特别提到支持 out-of-process iframes 和 closed Shadow DOM。这两类结构在普通自动化里经常导致选择器失效，因为 Shadow DOM 的封闭模式会隔离样式和事件，而 out-of-process iframe 有独立的渲染进程。Stagehand 声称原生支持，意味着它的可访问性树裁剪和自愈逻辑能穿透这些边界。但注意，这种支持的具体实现细节在 README 里没有展开，你需要查阅 docs.stagehand.dev 或源码确认它对 Shadow DOM 的穿透程度，是完整支持还是部分属性可见。

生产特性：WebMCP、剪贴板、批处理与 OTel

README 列了一组面向智能体的生产特性：WebMCP、剪贴板支持、批处理命令、深层定位器和 OTel 支持。WebMCP 听起来像是一种让浏览器与模型交互的协议，但 README 没有解释它的具体格式，只能从名字推测与 MCP 相关。剪贴板支持对自动化任务很实用，比如复制验证码或粘贴 token。批处理命令应该允许一次发送多个动作，减少模型往返次数。OTel 支持意味着可以导出追踪数据到可观测性平台，这对生产监控是刚需。这些特性组合起来，说明 Stagehand 不是玩具项目，它在认真解决智能体在生产环境的可观测性和效率问题。不过，特性列表不等于成熟度，比如 WebMCP 的稳定性、批处理在复杂页面上的错误处理，都需要看文档或实际测试才能判断。

局限性与误用场景

Stagehand 的局限首先体现在依赖上。没有 LLM API key，act、observe、extract 就无法工作，你只能用 Playwright 风格的底层方法，那不如直接用 Playwright。其次，官方示例默认使用 Browserbase 云浏览器，这意味着你的智能体任务会受制于云服务的可用性和配额，如果 Browserbase 出问题，你的自动化也会中断。本地运行的可能性存在，但 README 没有提供明确路径。另一个问题是 token 效率。混合可访问性树裁剪虽然减少输入，但每次 act 调用仍然需要模型推理，延迟和成本比纯脚本高一个数量级。对于确定性的、高频的 UI 测试，用 Stagehand 是过度设计。还有自愈的不确定性，它本质上依赖模型对页面变化的理解，如果网站改版幅度大，自愈可能产生错误动作，而错误动作在自动化里比失败更危险，因为可能提交表单或删除数据。

替代方案与维护成本

最直接的替代是 Playwright 本身，它提供 locator、auto-waiting 和网络拦截，适合确定性脚本，但没有自然语言原语，页面变化需要手动更新选择器。另一个方向是纯 LLM 代理框架，比如给 GPT 加浏览器工具，这类方案灵活但不可预测，Stagehand 的中间路线正好是它的差异化。维护成本方面，仓库更新频繁，最近一次 push 是 2026 年 8 月，有多个 v3.7.x 版本发布，说明项目处于活跃迭代期。这意味着你需要跟上版本变化，特别是 SDK 和 server 组件版本要匹配。许可证是 MIT，允许商用和修改，但 Stagehand 是 Browserbase 的商标，如果你的产品名包含它，会有商标风险。贡献指南提到优先改进可靠性、扩展性、速度和成本，这暗示当前版本在这些方面还有提升空间，你采用时应该预期会有破坏性变更。

编辑结论

Stagehand 适合已经在用 Playwright 做自动化、但需要让智能体以自然语言操作页面的团队，尤其是那些受困于页面结构频繁变动、token 成本敏感的 AI 代理项目。它不适合只想写确定性脚本、不打算接入 LLM 或 Browserbase 的开发者，因为核心的 act、observe、extract 都依赖模型调用，且官方示例默认绑定 Browserbase 云浏览器。采用前应验证三点：你的 LLM 提供商是否被 model 配置支持，Browserbase API key 是否必要（仓库示例中 browserbase.launch 是默认路径），以及自愈行为在目标站点的实际命中率。MIT 许可证允许商用和修改，但 Stagehand 商标归 Browserbase 所有，如果你的产品名里带 Stagehand 需要留意。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes