diff --git a/skills-dev/agent-browser-plugin/.claude-plugin/plugin.json b/skills-dev/agent-browser-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..3e66bf7 --- /dev/null +++ b/skills-dev/agent-browser-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "agent-browser-plugin", + "description": "浏览器自动化技能。用于网页交互、E2E冒烟测试、需求验收验证、前端开发验证、截图对比。基于 Vercel agent-browser CLI。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-dev/agent-browser-plugin/skills/SKILL.md b/skills-dev/agent-browser-plugin/skills/SKILL.md new file mode 100644 index 0000000..0aff31c --- /dev/null +++ b/skills-dev/agent-browser-plugin/skills/SKILL.md @@ -0,0 +1,186 @@ +--- +name: agent-browser +description: 浏览器自动化技能。用于网页交互、E2E冒烟测试、需求验收验证、前端开发验证、截图对比。基于 Vercel agent-browser CLI。 +--- + +# agent-browser + +浏览器自动化 CLI,专为 AI Agent 设计。当用户需要与网页交互时使用:导航页面、填写表单、点击按钮、截图、提取数据、测试 Web 应用、自动化浏览器任务。 + +当用户提到以下关键词时自动激活:浏览器自动化、打开网页、截图、网页测试、冒烟测试、E2E 验证、页面检查、agent-browser。 + +## 前置条件 + +```bash +npm i -g agent-browser # 安装 CLI +agent-browser install # 下载 Chrome +``` + +--- + +## 核心工作流(snapshot-ref 模式) + +1. **导航** 到 URL +2. **snapshot** 获取可交互元素(返回 `@e1`, `@e2` 等引用) +3. **交互** 使用元素引用 +4. **重新 snapshot** DOM 变化后刷新引用 + +```bash +agent-browser open https://example.com/form +agent-browser snapshot -i +agent-browser fill @e1 "user@example.com" +agent-browser click @e3 +agent-browser wait --load networkidle +``` + +--- + +## 命令参考 + +### 导航与控制 +- `open ` – 打开网页 +- `goto ` – 在会话内跳转 +- `close` – 关闭浏览器 +- `wait ` – 等待元素/网络/JS 条件 + +### 页面检查 +- `snapshot -i` – 获取可交互元素及引用(推荐) +- `snapshot` – 完整无障碍树 +- `get text|html|value @e1` – 提取元素内容 +- `get title|url` – 获取页面标题/URL +- `screenshot [path]` – 截图 +- `screenshot --annotate` – 带元素标注的截图 + +### 交互操作 +- `click @e1` / `dblclick @e1` – 单击/双击 +- `fill @e1 "text"` – 清空并输入 +- `type @e1 "text"` – 追加输入 +- `select @e1 "option"` – 下拉选择 +- `check @e1` – 勾选/取消勾选 +- `press Enter` – 按键 +- `hover @e1` – 悬停 +- `scroll down 500` – 滚动 +- `upload @e1 /path` – 上传文件 +- `drag @e1 @e2` – 拖放 + +### 高级功能 +- `eval 'code'` – 执行 JavaScript +- `diff snapshot` – 对比前后页面状态 +- `set viewport 1920 1080` – 设置视口 +- `set device "iPhone 14"` – 移动端模拟 +- `find role click --name "Label"` – 语义定位器 +- `network mock --body '...'` – 网络请求模拟 +- `cookies get/set/clear` – Cookie 管理 +- `storage get/set/clear` – localStorage 管理 + +--- + +## 认证与会话持久化 + +### Auth Vault(推荐) +```bash +agent-browser auth save myapp +agent-browser open https://myapp.com --auth myapp +``` + +### 持久化 Profile +```bash +agent-browser open https://site.com --profile ~/.myapp-profile +``` + +### 命名会话 +```bash +agent-browser open https://site.com --session-name myapp +``` + +### 状态文件 +```bash +agent-browser open https://site.com --state ./auth.json --save-state +``` + +--- + +## 命令链式调用 + +不需要中间输出时用 `&&` 串联: +```bash +agent-browser open https://example.com && \ + agent-browser wait --load networkidle && \ + agent-browser screenshot page.png +``` + +需要解析输出(如 snapshot 获取 ref)时分开执行。 + +--- + +## 与其他技能结合 + +### 结合 dev-test(E2E 冒烟测试) + +在 dev-test 的 Gate 4(E2E 冒烟测试)中使用: + +```bash +# 1. 打开本地前端 +agent-browser open http://localhost:3000 --session-name e2e-test + +# 2. 验证页面加载 +agent-browser snapshot -i +agent-browser screenshot /tmp/e2e-home.png + +# 3. 测试登录流程 +agent-browser fill @e1 "admin@example.com" +agent-browser fill @e2 "password" +agent-browser click @e3 +agent-browser wait --load networkidle + +# 4. 验证登录成功 +agent-browser get title # 应包含 "Dashboard" +agent-browser screenshot /tmp/e2e-dashboard.png + +# 5. 清理 +agent-browser close +``` + +### 结合 req(需求验收验证) + +PRD 评审后实际操作验证需求是否实现: + +```bash +# 根据 PRD 验收标准逐项检查 +agent-browser open http://localhost:3000/feature-page +agent-browser snapshot -i +# 按验收标准操作对应元素... +agent-browser screenshot /tmp/req-verify.png +``` + +### 结合 dev-coding(前端开发即时验证) + +开发完组件后立即打开页面验证: + +```bash +agent-browser open http://localhost:3000/new-page +agent-browser snapshot -i # 检查渲染的元素 +agent-browser screenshot --annotate /tmp/dev-check.png # 带标注截图 +``` + +### 结合 ops-tools(部署后验证) + +部署后快速检查页面是否正常: + +```bash +agent-browser open https://ai.pipexerp.com +agent-browser wait --load networkidle +agent-browser get title +agent-browser screenshot /tmp/deploy-check.png +agent-browser close +``` + +--- + +## 注意事项 + +- **Ref 生命周期**:导航或 DOM 变化后引用失效,必须重新 snapshot +- **超时**:默认 25 秒,通过 `AGENT_BROWSER_DEFAULT_TIMEOUT` 环境变量调整 +- **会话隔离**:用 `--session-name` 实现并行自动化 +- **安全**:支持域名白名单、操作策略、内容边界 +- **输出格式**:用 `--json` 获取机器可读输出