# Agent Stealth Browser

[![PyPI version](https://badge.fury.io/py/agent-stealth-browser.svg)](https://badge.fury.io/py/agent-stealth-browser)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> 🕵️ 通用的 AI 浏览器自动化 MCP 工具，让 AI Agent 能够以 **Stealth 模式** 智能地操作任意网站。

**Agent Stealth Browser** 是 [agent-browser](https://github.com/AierLab/agent-browser) 的 Stealth 增强版本，提供完全兼容的 API 接口，但具备绕过反爬检测的能力。

## ✨ 特性

- 🔄 **完全兼容 agent-browser API** - 无缝替换，相同的工具名和参数格式
- 🕵️ **Stealth 模式** - 绕过 Cloudflare、reCAPTCHA 等反爬检测
- 🌍 **跨平台支持** - Windows、macOS、Linux 自动适配
- 🍪 **Cookie 持久化** - 保存登录状态，跨会话使用
- 📸 **截图能力** - 支持全页面或指定元素截图
- 🎯 **@ref 元素定位** - 与 agent-browser 一致的元素引用格式

## 📦 安装

### 方式 1: uvx (推荐)

```bash
uvx agent-stealth-browser
```

### 方式 2: pip

```bash
pip install agent-stealth-browser

# 安装 Playwright 浏览器
playwright install chromium

# 可选: 安装 stealth 增强
pip install playwright-stealth
```

### 方式 3: npx

```bash
npx agent-stealth-browser
```

## 🔧 MCP 配置

### Claude Desktop / Cursor

在 MCP 配置文件中添加:

```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "uvx",
      "args": ["agent-stealth-browser"]
    }
  }
}
```

或使用 npx:

```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "npx",
      "args": ["agent-stealth-browser"]
    }
  }
}
```

## 🛠️ 可用工具

| 工具名 | 描述 | 对应 agent-browser 命令 |
|--------|------|------------------------|
| `browser_navigate` | 导航到指定 URL | `open <url>` |
| `browser_snapshot` | 获取页面交互元素快照 | `snapshot -i` |
| `browser_click` | 点击元素 | `click @e1` |
| `browser_fill` | 填写输入框（先清空） | `fill @e1 "text"` |
| `browser_type` | 逐字输入（模拟真人） | `type @e1 "text"` |
| `browser_press` | 按下键盘按键 | `press Enter` |
| `browser_scroll` | 滚动页面 | `scroll down 500` |
| `browser_hover` | 悬停在元素上 | `hover @e1` |
| `browser_select` | 选择下拉框选项 | `select @e1 "value"` |
| `browser_get` | 获取元素/页面信息 | `get text @e1` |
| `browser_eval` | 执行 JavaScript | `eval "code"` |
| `browser_screenshot` | 页面截图 | `screenshot` |
| `browser_wait` | 等待时间或元素 | `wait` |
| `browser_cookies_save` | 保存 cookies | - |
| `browser_cookies_load` | 加载 cookies | - |
| `browser_close` | 关闭浏览器 | `close` |

## 📝 使用示例

### 基础浏览

```
1. browser_navigate: {"url": "https://example.com"}
2. browser_snapshot: {}
3. browser_click: {"target": "@e1"}
```

### 表单填写

```
1. browser_navigate: {"url": "https://example.com/login"}
2. browser_snapshot: {}
3. browser_fill: {"target": "@e3", "text": "username"}
4. browser_fill: {"target": "@e4", "text": "password"}
5. browser_click: {"target": "@e5"}
```

### 保持登录状态

```
# 登录后保存 cookies
browser_cookies_save: {"domain": "example"}

# 下次启动时加载
browser_navigate: {"url": "https://example.com"}
browser_cookies_load: {"domain": "example"}
browser_navigate: {"url": "https://example.com"}  # 刷新页面应用 cookies
```

## 🌍 跨平台支持

Agent Stealth Browser 自动检测运行平台并适配：

| 平台 | User-Agent | 浏览器参数 |
|------|------------|-----------|
| macOS | Macintosh; Intel Mac OS X | 标准参数 |
| macOS (Apple Silicon) | Macintosh; Apple M1 | 标准参数 |
| Windows | Windows NT 10.0; Win64 | `--disable-gpu` |
| Linux | X11; Linux x86_64 | `--no-sandbox` 等 |

## 🔒 Stealth 模式

默认启用以下反检测措施：

- ✅ 隐藏 `navigator.webdriver` 属性
- ✅ 模拟真实 Chrome 环境
- ✅ 隐藏自动化特征
- ✅ 支持 `playwright-stealth` 插件（可选增强）

### 增强 Stealth 模式

安装 `playwright-stealth` 获得更强的反检测能力：

```bash
pip install playwright-stealth
```

## 📁 数据存储

- **Cookies**: `~/.agent_stealth_browser/cookies/`

## 🔄 与 agent-browser 的区别

| 特性 | agent-browser | agent-stealth-browser |
|------|---------------|----------------------|
| Stealth 模式 | ❌ | ✅ |
| 反爬绕过 | ❌ | ✅ |
| Cookie 持久化 | ❌ | ✅ |
| 跨平台适配 | ✅ | ✅ |
| API 兼容性 | - | 100% 兼容 |

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 License

MIT License - 详见 [LICENSE](LICENSE) 文件