# Browser Automation

> 当用户要控制浏览器完成需要 JavaScript 渲染、登录态或交互操作的网页任务时使用。

- Skill: `ntygod/browser-automation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ntygod/browser-automation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntygod/browser-automation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ntygod (https://skillmd.com/u/ntygod)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntygod/browser-automation

---


# 浏览器自动化指南

`browser` 工具基于 Playwright，做需要 JS 渲染、登录态或交互的网页任务。**核心约束：能 web_fetch 搞定的不用 browser；不能交互的用 web_fetch。**

## 适用场景

- 动态页面抓取（SPA、电商搜索结果、需要 JS 渲染）
- 登录后才能访问的页面
- 表单填写与提交
- 网页截图 / 视觉验证
- 多步交互流程（点 → 等加载 → 再点）

## 不适用场景

- 静态页面抓取（文档 / 博客 / 新闻）→ `web_fetch`
- API 接口测试 → api-debugger
- 桌面应用操作 → desktop-automation
- 多源搜索 → `web_search`

## 工作流

1. **先判**：能 `web_fetch` 拿到正文 → 用 fetch；JS 渲染 / 登录 / 多步交互 → 用 `browser`
2. **navigate 开会话**：同一任务用相同 `sessionId` 复用 cookie，避免每次重登
3. **快照定位**：`snapshot` 一次拿截图 + 可交互元素编号；后续 `click` / `input` / `hover` 优先用 `index` 而非 `selector`（layout 抖动也稳）
4. **页面变化后重新 snapshot**：导航 / 弹窗 / 异步渲染会让旧 index 失效，必须重新拿
5. **失败 2 次切策略**：`index` 失败 → 改 `selector`；selector 失败 → 退 `web_fetch`；fetch 失败 → 让用户接管
6. **登录墙 / 验证码**：观察到 password input、login URL 或人机验证截图时，调 `requestHumanTakeover` 让用户接管，**不要让 LLM 假装填密码**
7. **结束**：关键产出 `file_write` 落盘后 `close` 释放浏览器资源

## 详细参考

- 完整 action 清单（snapshot / requestHumanTakeover）、index/selector fallback、登录墙触发条件、会话模式（LAUNCH/CDP/PERSISTENT）、常见错误：`{skill_dir}/references/browser-actions.md`