关于 stagehand-expert
用于使用 Stagehand 进行浏览器自动化和端到端测试的技能，涵盖自然语言操作、结构化提取、决策缓存，以及处理复杂界面的 Agent 策略。
主要功能
- 01使用 Act、Observe 和 Extract 原语
- 02创建经 Zod 验证的结构化提取
- 03缓存决策以运行确定性 CI 测试
- 04处理 Shadow DOM 和 iframe 界面
- 05通过安全回调使用视觉 CUA
适用场景
- 01构建浏览器自动化测试
- 02从网页提取结构化数据
- 03在 CI 中运行缓存测试
- 04自动化操作含复杂框架或画布的界面
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/stagehand-expert确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/advanced-agent-caching.mdcdp-direct-communication.mdshadow-dom-iframe-mastery.md详细介绍
🎭 技能：Stagehand 专家（v4.1.0）
执行摘要
stagehand-expert 是浏览器自动化和高精度 Agent 编排领域的顶尖专家。到了 2026 年，网页自动化已从脆弱的选择器转向自然语言原语和直接 CDP 通信。这项技能专注于掌握 Stagehand V3、利用决策缓存实现零成本 CI/CD，以及以快 44% 的速度处理复杂的 Shadow DOM/iframe 结构。
📋 目录
🔍 主动调查协议
编写任何测试之前，专家都必须进行深入探索：
- 路由映射：从
page.tsx或路由配置中识别用户流程。 - UI 组件审计：阅读源代码，查找 ID、标签和加载状态。
- 体验检查：使用 CDP“体验评分”衡量布局稳定性。
- 架构推断：分析现有后端/DB 类型，创建 100% 兼容的
extract()Zod 架构。
🚫 “切勿”清单（反模式）
| 反模式 | 为什么在 2026 年会失败 | 现代替代方案 |
|---|---|---|
| 手动切换 Frame | 脆弱且缓慢。 | 使用 DeepLocator (>>) 和 CDP。 |
| 硬编码 Wait(2000) | 不可靠且会导致卡顿。 | 使用 domSettleTimeout。 |
| 缺少 finally { close() } | 会留下僵尸进程。 | 必须使用 try...finally。 |
| 在 CI 中调用 LLM | 缓慢且昂贵。 | 使用持久化决策缓存。 |
| 忽略 CSS 动画 | 过渡期间交互会失败。 | 使用感知 Reanimated 的等待器。 |
⚡ 掌握核心原语
- Act：使用映射变量的精确自然语言指令。
- Observe：单轮识别页面中的所有元素，降低 70% 的成本。
- Extract：经过 Zod 验证的结构化数据提取，并进行语义扁平化。
💾 高级决策缓存
将 E2E 测试转变为确定性资产：
- 本地开发：由实时 LLM 生成缓存。
- 提交缓存：将 DOM 快照和结果存储在 Git 中。
- 零成本 CI：以“仅缓存”模式运行测试。
详情请参阅参考资料：Agent 缓存。
🤖 自主 Agent 与 CUA
针对最复杂的 UI（跨域 iframe、动态画布）：
- 计算机使用 Agent（CUA）：通过纯视觉推理处理无法解析的元素。
- 安全回调：涉及金融或破坏性操作时，必须有人类参与审核。
📖 参考资料库
深入了解 Stagehand 卓越实践：
- 直接 CDP 通信：速度与深度访问。
- Agent 缓存：确定性与成本节省。
- Shadow DOM 精通指南：跨越文档边界。
- 安装与设置：Bun/Playwright 技术栈。
更新于：2026 年 1 月 22 日 - 21:20
评论
支持 Markdown