# smart-mimic-browser

**Repository Path**: seagull312_admin/smart-mimic-browser

## Basic Information

- **Project Name**: smart-mimic-browser
- **Description**: smart-mimic-browser
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Mimic Browser · 智能浏览器自动化

一款**会自我进化**的浏览器自动化工具。基于 Playwright + Python，AI 驱动的浏览器操作助手，支持 126 邮箱、AI 对话（豆包/千问/元宝/DeepSeek）等场景。

---

## 安装

### 方式一：ClawHub 一键安装（推荐）

确保已安装 [OpenClaw](https://openclaw.ai) 和 ClawHub CLI：

```bash
# 安装
clawhub install smart-mimic-browser

# 安装 Playwright 浏览器
cd skills/smart-mimic-browser/scripts
bash setup.sh
# 或手动：
pip install playwright
playwright install chromium

# 重启 OpenClaw 后即可使用
```

安装完成后，在 OpenClaw 中直接说：

> "帮问豆包 xxx"
> "查一下126最新邮件"

### 方式二：手动安装

```bash
# 1. 将 smart-mimic-browser 目录放到 OpenClaw 的 skills/ 目录下
cp -r smart-mimic-browser ~/.openclaw/workspace/skills/

# 2. 安装依赖
cd ~/.openclaw/workspace/skills/smart-mimic-browser/scripts
bash setup.sh

# 3. 重启 OpenClaw
```

**注意**：手动模式需自行安装 Playwright 和 Chromium。OpenClaw 集成模式下 daemon 由系统自动管理。

---

## 亮点

- **🤖 AI 驱动，自然语言操作** — 你只需说"登录邮箱查最新邮件"，剩下交给 AI
- **🧬 自我进化** — 首次执行需 AI 分析页面，成功后自动固化为预设，下次秒级完成
- **🔐 扫码登录优先** — 检测到微信/App 扫码登录自动截图，你扫码即完成
- **🔄 自修正循环** — 代码执行失败会自动诊断、重试，最多 3 轮
- **⚡ 省 Token 模式** — 固化的预设直接通过 socket 调用，无需再走 LLM
- **📦 场景保存** — 可保存当前页面状态（多标签页），随时恢复

## 快速开始

```bash
# 1. 安装依赖
cd scripts/
bash setup.sh

# 2. 启动 daemon（看到浏览器窗口）
PLAYWRIGHT_HEADLESS=false python3 browser_daemon.py start

# 3. 查看状态
python3 browser_agent.py current

# 4. 打开网页
python3 browser_agent.py goto https://www.baidu.com

# 5. 截图
python3 browser_agent.py screenshot https://example.com
```

## 一句话示例

| 你想做的事 | 执行命令 |
|-----------|---------|
| 问豆包一个问题 | `python3 browser_agent.py preset ai_chat doubao question="量子计算是什么？"` |
| 问 DeepSeek | `python3 browser_agent.py preset ai_chat deepseek question="用Python写个排序"` |
| 登录 126 邮箱看收件箱 | `python3 browser_agent.py preset scene_126 read_mail email=xxx@126.com password=xxx` |
| 提取文章正文 | `python3 browser_agent.py preset article_extract extract url=https://example.com/article` |
| 保存当前场景 | `python3 browser_agent.py exec --code 'result = save_scene("工作台")'` |

## 核心机制

### 首次 vs 固化

```
首次执行某操作                   已固化的操作
───────                          ──────────
用户说"登录邮箱"                 用户说"登录邮箱"
  ↓                                 ↓
打开页面，提取 HTML              直接调用预设（秒级）
  ↓                                 ↓
交给 AI 分析页面结构              自动填写账号密码
  ↓                                 ↓
AI 生成 Playwright 代码           登录完成 ✅
  ↓
执行代码
  ↓ 成功
询问"要存成预设吗？"
  ↓ 用户确认
固化为预设 ← 这就是"自我进化"
```

### 自修正循环

生成的代码在真实浏览器中可能失败，系统会自动诊断修复：

```
生成代码 → 执行
  ├─ 成功 → 继续
  └─ 失败 → 分析错误原因 + 截图 + HTML
        ├─ selector 不对 → 根据当前 HTML 修正
        ├─ 元素未加载 → 增加等待
        ├─ 按钮不可点 → 检查 disabled / 滚动到可见
        └─ 其他 → 分析 traceback
        ↓
        修正代码 → 重新执行（最多 3 次）
```

## 安全机制

### 登录状态检测

**每次访问带登录的站点前，自动检测登录是否过期。**

```
1. 调用站点的 check_login 函数
   ├─ logged_in=False → 引导登录（扫码优先）
   └─ logged_in=True  → 直接执行操作
```

为什么重要：
- 站点 cookie 可能因浏览器重启、daemon 重启、长时间空闲而过期
- 不过期检测直接操作会触发跳转到登录页，导致预设执行失败
- worker 进程可能因登录未初始化而静默崩溃

### 登录策略

```
检测到需要登录
  ├─ 有扫码入口 → 截图整个页面发给用户，用户扫码完成
  ├─ 无扫码入口 → 询问用户提供账号密码
  └─ 登录后出现验证码 → 返回 need_verify_code，不自动填入
```

### 密码安全

- **密码不存储在预设代码中**。代码片段通过 `args.get("username","")` / `args.get("password","")` 从调用方传递，不在代码中硬编码
- **提供凭据加密存储模块**（`credential_manager.py`），密码经加密后存储到本地文件，仅在用户授权后使用
- **验证码不做任何存储或自动回填**
- **用户密钥存在于 ~/.playwright_browser/credentials/ 目录**，加密存储

### 数据隐私

- 所有浏览器操作在本机执行，页面 HTML 和截图仅在本地处理
- cookies 持久化在 `~/.playwright_browser/user_data/`，不发送到外部
- 预设生成的代码片段保存在本地，不上传任何云端

## 内置预设

| 预设 | 原子操作 | 功能 |
|------|----------|------|
| `ai_chat` | `doubao` | 向豆包提问 |
| `ai_chat` | `qwen` | 向千问提问 |
| `ai_chat` | `yuanbao` | 向元宝提问 |
| `ai_chat` | `deepseek` | 向 DeepSeek 提问 |
| `mail_126` | `login` | 126 邮箱登录 |
| `mail_126` | `list` | 获取邮件列表 |
| `scene_126` | `read_mail` | 一键登录→收件箱 |
| `article_extract` | `extract` | 智能提取文章正文 |
| `login_account` | `login` | 通用账号登录 |
| `save_cookies` / `load_cookies` | `save` / `load` | Cookie 导出/导入 |
| `analyze_page` | `analyze` | 分析页面结构 |
| `save_scene` / `list_scenes` | `save` / `list` | 场景保存/列表 |

## 架构概览

```
browser/
├── README.md                    ← 本文档
├── SKILL.md                     ← AI 自我描述（预设清单，每次进化后更新）
├── scripts/
│   ├── browser_daemon.py        ← 核心：进程管理 + socket 服务 + CLI
│   ├── browser_agent.py         ← 命令行交互接口
│   ├── worker.py                ← 浏览器子进程（Playwright 操作）
│   ├── credential_manager.py    ← 凭据加密存储
│   ├── preset_manager.py        ← 预设管理
│   ├── setup.sh                 ← 一键安装
│   └── presets/                 ← 内置预设
│       ├── ai_chat.py           ← AI 对话（登录处理 + 提问 + 提取）
│       ├── mail126.py           ← 126 邮箱
│       ├── scene_126.py         ← 126 邮箱场景
│       ├── article.py           ← 文章提取
│       ├── account.py           ← 通用登录
│       ├── cookies.py           ← Cookie 管理
│       ├── learner.py           ← 页面分析
│       └── self_learn.py        ← 场景管理
└── runtime/ (~/.playwright_browser/)
    ├── presets/                 ← 用户自生成的预设
    ├── scenes/                  ← 保存的场景
    ├── user_data/               ← 浏览器持久化数据
    └── logs/                    ← 运行日志
```

## 应用场景

### 1. AI 对话聚合

豆包、千问、元宝、DeepSeek 一站式访问。自动处理登录（扫码优先），你只需说：

```bash
python3 browser_agent.py preset ai_chat doubao question="帮我解释量子纠缠"
python3 browser_agent.py preset ai_chat qwen question="写一篇关于AI的短文"
```

### 2. 邮件自动化

登录 126 邮箱、查收邮件、提取内容：

```bash
python3 browser_agent.py preset scene_126 read_mail email=you@126.com password=xxx count=5
```

### 3. 网页内容提取

智能提取文章正文，自动过滤导航、广告：

```bash
python3 browser_agent.py preset article_extract extract url=https://example.com/article
```

### 4. 通用登录

任何需要登录的网站，自动检测表单字段：

```bash
python3 browser_agent.py preset login_account login url=https://example.com/login username=xxx password=xxx
```

### 5. 多标签场景

保存一组工作标签页，随时恢复：

```bash
# 保存当前所有标签为"工作台"
python3 browser_agent.py exec --code 'result = save_scene("工作台")'

# 恢复
python3 browser_agent.py exec --code 'result = load_scene("工作台")'
```

## 省 Token 模式

AI Agent 内部直接通过 socket 调用预设，无需再走 LLM：

```json
{"action": "preset", "preset": "ai_chat", "sub": "doubao", "args": {"question": "什么是量子计算？"}}
{"action": "preset", "preset": "scene_126", "sub": "read_mail", "args": {"email": "...", "password": "...", "count": 5}}
```

## 为什么不用 Selenium？

| 对比项 | Smart Mimic Browser | Selenium |
|--------|-------------------|----------|
| 上手速度 | 说人话即可 | 需要写代码 |
| 自我进化 | ✅ 执行成功自动固化为预设 | ❌ 无 |
| 自修正 | ✅ 失败自动分析和重试 | ❌ 需手动调 |
| 扫码登录 | ✅ 自动截图给用户 | ❌ 无 |
| 场景保存 | ✅ 多标签一键保存/恢复 | ❌ 无 |
| AI 对话预设 | ✅ 内置登录流+容错 | ❌ 需自己写 |

## 资源管理

自动检测浏览器页签数量和内存使用，超过阈值会提醒你关闭不必要的页签，避免系统过载。

---

**联系作者**: yuebin616@126.com  
**QQ**: 554146205