用途
Stagehand Automation 是一个基于 Stagehand v3 与 Claude 的 AI 浏览器自动化技能，适用于构建自愈测试、AI 智能体、动态网页自动化，以及传统自动化方式难以应对的场景。Stagehand v3 是构建在 Chrome DevTools Protocol（CDP）之上的 AI 浏览器自动化框架，据资料称比 v2 快 44%，并与 Claude 无缝集成。其核心创新是：当 DOM 发生变化时，由 AI 自适应调整，而不是让测试失败。
主要能力
Stagehand v3 提供三个核心 API：
- act()：使用自然语言执行操作，例如点击元素、填写表单、导航、执行复杂动作。资料给出的示例包括点击登录按钮、填写邮箱字段、输入密码、滚动到定价区域、从下拉框选择套餐并点击继续等。自愈能力体现在：如果按钮 ID 从 #login-btn 变为 #auth-signin，Stagehand 会自动适应。
- extract()：从页面提取结构化数据，并支持 schema 校验。示例包括提取主页面标题、提取所有产品的名称/价格/库存状态、提取购物车条目与总价等。
- observe()：分析页面状态，识别元素与页面状态。示例包括查找页面上所有可点击按钮、判断用户是否已登录、识别所有表单输入字段及其标签。
使用方式
安装：
npm install @browserbase/stagehand zod
配置 Claude API：在 .env 中添加 ANTHROPIC_API_KEY=your_api_key_here。
编写第一个自动化脚本（资料示例）：
import { Stagehand } from "@browserbase/stagehand"; import { z } from "zod";
async function main() { const stagehand = new Stagehand({ env: "LOCAL", modelName: "claude-sonnet-4-20250514", modelClientOptions: { apiKey: process.env.ANTHROPIC_API_KEY, }, });
await stagehand.init(); await stagehand.page.goto("https://news.ycombinator.com");
await stagehand.act({ action: "click on the first story link" });
const data = await stagehand.extract({ instruction: "extract the story title and author", schema: z.object({ title: z.string(), author: z.string(), }), });
console.log(data); await stagehand.close(); }
main();
运行：npx ts-node your-script.ts
自愈模式
资料对比了传统 Playwright 与 Stagehand 的差异：传统方式如 page.click('#submit-btn-v2') 或 page.click('.btn-primary:nth-child(2)') 在 ID 或顺序变化时会失败；而 Stagehand 使用 stagehand.act({ action: "click the submit button" }) 可始终工作并自适应。自愈会在以下情况激活：ID/Class 变化、结构变化（元素在 DOM 树中移动）、文本变化（按钮文字从 Submit 变为 Send）、样式变化（CSS 类重组）。
缓存
Stagehand v3 会缓存已发现的元素：首次调用时 AI 分析页面并查找元素（较慢），第二次调用使用缓存选择器（较快），当页面发生显著变化时缓存失效。
混合方式：Playwright + Stagehand
资料提供了混合测试示例：使用 Playwright 处理稳定、快速的操作（如 goto、fill、断言），使用 Stagehand 处理动态/脆弱元素（如点击登录按钮、关闭 cookie 横幅）以及复杂提取。
Claude 集成与模型选择
资料列出可选模型：claude-sonnet-4-20250514（推荐，速度与质量平衡）、claude-opus-4-20250514（质量最高，较慢）、claude-3-5-haiku-20241022（最快，适合简单任务）。成本优化建议：简单动作用 Haiku，复杂提取用 Sonnet。资料给出的估算成本为：简单 act() 用 Haiku 约 $0.001，复杂 act() 用 Sonnet 约 $0.005，简单 extract() 用 Haiku 约 $0.002，复杂 extract() 用 Sonnet 约 $0.01。
MCP 集成
可通过 Model Context Protocol 在 Claude Desktop 中使用 Stagehand：
import { StagehandMCPServer } from "@browserbase/stagehand/mcp";
const server = new StagehandMCPServer(); server.start();
之后 Claude 可调用 stagehand.act()、stagehand.extract()、stagehand.observe()。
错误处理
资料提供 try/catch 示例，处理 timeout（元素未在超时内找到）与 multiple（找到多个匹配元素，需更具体）等情况，并给出重试模式 actWithRetry。
最佳实践
- 指令要具体：避免 "click button"，改用 "click the blue 'Add to Cart' button below the product image"。
- 使用上下文：如 "in the navigation menu, click on 'Settings'"。
- 结合 Playwright 提升速度：对 data-testid 元素用 Playwright，对动态元素用 Stagehand。
- 使用 Zod schema 校验以保证类型安全。
适用场景
资料列出的用例包括：自愈式端到端测试（可经受 UI 重设计的测试）、网页抓取（从任意网站提取数据）、表单自动化（自动填写复杂表单）、测试 AI 聊天机器人（与对话式 UI 交互）、跨站点工作流（自动化多站点流程）。
限制
资料未明确列出该技能的限制条件。使用前需配置 ANTHROPIC_API_KEY，且操作会产生按模型计费的 API 成本（资料给出估算值）。具体平台支持范围、并发限制、浏览器环境要求等资料暂未提供。
参考资料
资料提及以下参考文件：references/stagehand-v3-guide.md（完整 API 参考）、references/claude-integration.md（API 设置与模型选择）、references/self-healing-patterns.md（高级模式）。