---
name: stealth-browser
description: |
  反检测浏览器操作指南 — 使用 DrissionPage 进行反自动化检测的浏览器操作。
  专用于需要登录的网站（Google/X.com/微博/抖音/微信公众号/139邮箱等）。
  每个网站使用独立 Profile，登录一次后 Cookie 自动保持，无需重复登录。
metadata:
  category: browser_stealth
  version: "1.30.0"
---

# 反检测浏览器 (Stealth Browser)

## 概述

当你需要操作需要登录的网站时，使用 **stealth browser（反检测浏览器）** 而不是普通 browser。
反检测浏览器基于 DrissionPage，能自动隐藏自动化特征，避免被网站识别为机器人。

## 两套浏览器的区别

| | browser (ChromeDev MCP) | stealth browser (DrissionPage) |
|---|---|---|
| **用途** | 通用浏览、信息获取 | 需要登录的网站操作 |
| **反检测** | 无（会被识别为自动化） | 有（隐藏 webdriver 等标记） |
| **Profile** | 无状态 | 每个网站独立 Profile |
| **Cookie** | 不持久化 | 自动保存/恢复 |
| **适合场景** | 搜索、读公开网页 | 登录 Google/微博/抖音等 |

## 预置网站 Profile

以下网站有预置配置，可以直接使用 Profile 名称：

| Profile 名称 | 网站 | 登录页 |
|---|---|---|
| `google` | Google 账号 | https://accounts.google.com/ |
| `gmail` | Gmail | https://mail.google.com/ |
| `x_com` | X.com (Twitter) | https://x.com/i/flow/login |
| `weibo` | 微博 | https://passport.weibo.com/sso/signin |
| `wechat_mp` | 微信公众号 | https://mp.weixin.qq.com/ |
| `douyin` | 抖音 | https://www.douyin.com/ |
| `mail139` | 139邮箱 | https://mail.10086.cn/ |
| `bilibili` | 哔哩哔哩 | https://passport.bilibili.com/login |
| `github` | GitHub | https://github.com/login |

## 操作流程

### 1. 登录网站（首次）

```
stealth-open <profile>           # 启动反检测浏览器
stealth-navigate <login_url> -p <profile>  # 导航到登录页
stealth-screenshot -p <profile>  # 截图查看页面状态
stealth-fill <selector> <value> -p <profile>  # 填写用户名/密码
stealth-click <selector> -p <profile>  # 点击登录按钮
stealth-wait-manual 验证码 -t 300 -p <profile>  # 如果遇到验证码，等待用户手动操作
stealth-cookies save -p <profile>  # 登录成功后保存 Cookie
```

### 2. 使用已登录状态操作（后续访问）

```
stealth-open <profile>           # 启动（自动加载 Profile 中的 Cookie）
stealth-cookies load -p <profile>  # 确保加载已保存的 Cookie
stealth-navigate <url> -p <profile>  # 导航到目标页面
stealth-content -p <profile>     # 读取页面内容
stealth-screenshot -p <profile>  # 截图
```

### 3. 处理验证码/2FA

当遇到验证码、短信验证等需要人工干预的场景时：

```
stealth-wait-manual 验证码 -t 300 -p <profile>
```

这会暂停自动化流程，等待用户通过 VNC 远程桌面或 Web Control 面板手动完成操作。
系统会检测 URL 变化来判断用户是否已完成操作（最长等待 300 秒）。

### 4. 登出/清除登录状态

```
stealth-cookies clear -p <profile>  # 清除 Cookie
stealth-close <profile>             # 关闭浏览器
```

## 常用命令参考

### 浏览器控制

- `stealth-open [profile] [--no-headless]` — 启动反检测浏览器
- `stealth-close [profile]` — 关闭浏览器
- `stealth-navigate <url> [-p profile]` — 导航到 URL
- `stealth-screenshot [-o path] [-p profile]` — 截图
- `stealth-content [-p profile]` — 获取页面文本内容
- `stealth-eval <script> [-p profile]` — 执行 JavaScript

### 页面交互

- `stealth-click <selector> [-p profile]` — 点击元素
- `stealth-fill <selector> <value> [-p profile]` — 填写输入框
- `stealth-wait <selector> [-t timeout] [-p profile]` — 等待元素出现
- `stealth-wait-manual [reason] [-t timeout] [-p profile]` — 等待用户手动操作

### Cookie 管理

- `stealth-cookies save [-p profile]` — 保存当前 Cookie
- `stealth-cookies load [-p profile]` — 加载已保存的 Cookie
- `stealth-cookies get [-p profile]` — 查看当前 Cookie
- `stealth-cookies clear [-p profile]` — 清除 Cookie

### Profile 管理

- `profile-list` — 列出所有 Profile
- `profile-create <name> [--display name] [--login-url url]` — 创建 Profile
- `profile-delete <name>` — 删除 Profile

## 选择器语法

DrissionPage 支持多种选择器语法：

- **CSS 选择器**: `#id`, `.class`, `tag`, `[attr=value]`
- **文本匹配**: `text=登录`, `text:登录` (模糊), `text=exact:登录` (精确)
- **XPath**: `xpath://div[@class="login"]`
- **组合**: `@class=item@text=确定` (class 为 item 的文本为"确定"的元素)

## 重要提示

1. **首次使用**需要手动登录一次，之后 Cookie 会自动保持
2. **有头模式**（`--no-headless`）在登录场景中更可靠，配合 VNC 使用
3. **遇到验证码**时使用 `stealth-wait-manual`，不要尝试绕过
4. **定期保存 Cookie**（`stealth-cookies save`），防止 Session 过期
5. 每个网站使用**独立 Profile**，不要混用
