浏览器自动化

技能文档

---
name: atr-browser
title: 浏览器自动化
category: 开发工具
description: 控制浏览器执行自动化操作，支持导航网页、点击元素、填写表单、截图、检查页面内容等。当用户需要操作浏览器、自动化网页交互、填写表单、截取网页截图、测试网站时触发。触发词：浏览器操作、网页自动化、表单填写、网页截图
---

# 浏览器自动化

通过 ATR 浏览器服务器模式实现浏览器自动化控制。浏览器以可见（非无头）模式运行，便于调试和验证。

> **配套技能 — `atr-computer`** 控制操作系统桌面（鼠标、键盘、屏幕、窗口、应用启动）。当浏览器操作需要系统文件选择器、桌面拖拽或页面外的操作时，可同时加载两个技能。
>
> 浏览器守护进程监听端口 9333；桌面守护进程监听端口 9334。两者可同时运行。

## 架构

```
用户 --> atr CLI (客户端) --> ATR 服务器 + 浏览器
```

## 技能工作流

### 步骤1：检查浏览器状态并启动

在执行任何浏览器操作前，确认浏览器服务器正在运行：

```bash
atr browser status
```

如果服务器未运行，启动它：

```bash
atr browser start
```

服务器状态存储在 `~/.atr/browser.state`，后续命令可自动发现端点。

### 步骤2：导航到目标页面

```bash
atr browser navigate https://example.com
```

### 步骤3：检查页面元素

```bash
atr browser snapshot
```

返回带有唯一 ID（UID）的元素列表，如 `e0`、`e1` 等。

### 步骤4：与元素交互

可通过以下方式定位元素：
- 文本内容：`"Sign In"`
- 快照中的 UID：`e5`
- CSS 选择器：`.submit-button`

### 步骤5：验证结果

```bash
atr browser url
atr browser title
atr browser screenshot --file
```

### 步骤6：完成后清理

```bash
atr browser stop
```

## 命令分类

### 生命周期命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser start [--port PORT]` | 启动浏览器守护进程（默认端口：9333） |
| `atr browser stop` | 停止浏览器守护进程 |
| `atr browser status` | 检查浏览器运行状态 |

### 导航命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser navigate <url>` | 导航到 URL |
| `atr browser back` | 后退 |
| `atr browser forward` | 前进 |
| `atr browser reload` | 重新加载当前页面 |

### 页面管理命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser new-page [url]` | 打开新标签页 |
| `atr browser list-pages` | 列出所有标签页 |
| `atr browser select-page <index>` | 切换到标签页（从 0 开始） |
| `atr browser close-page <index>` | 关闭标签页 |

### 交互命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser click <target> [--double]` | 点击元素（--double 为双击） |
| `atr browser fill <target> <value>` | 在输入框中输入内容 |
| `atr browser hover <target>` | 悬停在元素上 |
| `atr browser press-key <key>` | 按键（如 Enter、Tab、Control+A） |
| `atr browser drag <from> <to>` | 拖拽元素 |
| `atr browser wait <selector> [--timeout] [--visible]` | 等待元素出现 |
| `atr browser scroll --selector "<sel>" [--y N] [--to-bottom]` | 在元素内滚动 |
| `atr browser download-images "<sel>" [--output-dir] [--fallback-screenshot]` | 下载/截图元素中的图片 |
| `atr browser viewport [W H] [--preset mobile\|tablet\|desktop\|wide]` | 获取或设置视口大小 |
| `atr browser batch [--file F] [--on-error stop\|continue\|retry:N]` | 从 stdin/文件批量执行命令 |

### 录制命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser record [--url URL] [-o FILE]` | 录制浏览器交互为行为测试文件 |

### 检查命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser snapshot [--verbose]` | 获取页面元素及 UID |
| `atr browser screenshot --file [--full] [-s SELECTOR]` | 截图（保存到 /tmp/） |
| `atr browser screenshot --file --selector-all "<sel>"` | 截图所有匹配元素 |
| `atr browser computed-styles "<selector>" [--properties]` | 获取单个元素的计算 CSS 样式 |
| `atr browser computed-styles --selector-all "<sel>"` | 获取所有匹配元素的计算 CSS 样式 |
| `atr browser computed-styles-diff "<sel>" --against N` | 比较页面间的样式差异 |
| `atr browser text "<selector>" [--flat\|--links\|--headings]` | 提取文本内容 |
| `atr browser font-check "<font-family>"` | 检查字体是否已加载并渲染 |
| `atr browser clean-snapshot "<selector>" [--depth N] [--max-length N]` | 获取清理后的 DOM 子树 |
| `atr browser html` | 获取页面 HTML |
| `atr browser url` | 获取当前 URL |
| `atr browser title` | 获取页面标题 |
| `atr browser eval <script>` | 执行 JavaScript |
| `atr browser ask "<question>"` | 对当前页面提问 |

**截图说明：** 使用 `--file` 将截图保存到 `/tmp/`，文件名带时间戳（如 `/tmp/atr-screenshot-20240105-103045.png`）。添加 `--full` 进行全页截图。使用 `--selector` / `-s` 对特定 CSS 选择器的元素截图。使用 `--selector-all` 对所有匹配元素截图。

### 调试命令

| 命令 | 说明 |
|---------|-------------|
| `atr browser console [--limit N]` | 获取控制台消息（默认：50） |
| `atr browser network [--limit N]` | 获取网络请求（默认：50） |
| `atr browser errors` | 获取失败的请求 |

## 页面提问

使用 `atr browser ask` 获取页面特定信息，避免大量原始数据占用上下文：

```bash
atr browser ask "这个页面的主标题是什么？"
atr browser ask "导航菜单中有多少个项目？"
atr browser ask "这个页面有登录表单吗？"
```

## 录制浏览器交互

使用 `atr browser record` 捕获用户交互并输出 `.test.txt` 行为测试文件：

```bash
# 在页面上录制交互
atr browser record --url https://example.com -o repro-steps.test.txt

# 在当前打开的页面上录制
atr browser record -o flow.test.txt
```

在终端按 Ctrl+C 或浏览器浮层中的"停止"按钮结束录制。

录制器捕获点击、表单填写、键盘快捷键、导航、滚动和选择变更。支持 Shadow DOM，生成稳定的 CSS 选择器。密码字段自动遮蔽。

输出的 `.test.txt` 文件可通过 `atr run --behavior repro-steps.test.txt` 回放。

## JSON 输出

添加 `--json` 标志获取结构化输出：

```bash
atr browser snapshot --json
atr browser list-pages --json
atr browser network --json
```

## 元素定位

`<target>` 参数支持以下定位方式：

1. **元素 UID**：`e0`、`e5`（来自快照输出）
2. **可见文本**：`"Sign In"`、`"Submit Form"`
3. **aria-label**：匹配的 aria-label 属性
4. **data-testid**：匹配的 data-testid 属性
5. **CSS 选择器**：`#login-button`、`.nav-link`、`header`、`footer`

建议先使用 `atr browser snapshot` 查看可用元素及其 UID。

## 键盘按键

`press-key` 命令支持：
- 命名键：`Enter`、`Tab`、`Escape`、`Backspace`
- 修饰键：`Control+a`、`Shift+Tab`、`Alt+Enter`
- 方向键：`ArrowUp`、`ArrowDown`、`ArrowLeft`、`ArrowRight`

## 故障排除

**浏览器无法启动：**
```bash
atr browser status
rm ~/.atr/browser.state  # 清除过期状态
atr browser start
```

**端口被占用：**
```bash
atr browser start --port 9334
```

**找不到元素：**
```bash
atr browser snapshot --verbose --json
```

使用说明

# 浏览器自动化

控制浏览器执行自动化操作，支持导航网页、点击元素、填写表单、截图、检查页面内容等。

## 功能概述

通过 ATR 浏览器服务器模式提供浏览器自动化能力：

- **页面导航**：导航到 URL、前进、后退、刷新
- **元素交互**：点击、填写表单、悬停、拖拽、按键
- **页面检查**：快照、截图、提取文本、执行 JavaScript
- **页面管理**：多标签页管理、视口大小调整
- **交互录制**：录制用户操作为可回放的行为测试文件
- **调试支持**：控制台消息、网络请求、错误日志

## 快速开始

```bash
atr browser start
atr browser navigate https://example.com
atr browser snapshot
atr browser screenshot --file
atr browser stop
```

## 配套技能

`atr-computer` 技能控制操作系统桌面。当需要系统文件选择器或桌面交互时可同时加载。

## 使用示例

```
请打开 https://example.com 并截图
帮我填写网页表单并提交
```

## 注意事项

- 浏览器守护进程默认监听端口 9333
- 操作前先执行 `atr browser status` 确认状态
- 使用 `atr browser snapshot` 获取元素 UID 后再交互

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。