Skip to content

CyanXLab/BrowserAI

BranchesTags

Repository files navigation

BrowserAI 🤖

你只管用嘴说，剩下的交给 AI。

AI-Browser 是一款生产级智能浏览器助手。它摒弃了传统自动化繁琐的 DOM 定位与脚本编写，深度集成大语言模型（LLM）。你只需输入自然语言指令，AI 便能自主分析页面、拆解任务、执行点击与输入。

独创的 人机协作机制，让 AI 在遇到登录、验证码等复杂风控场景时主动暂停交由你接管，完美平衡了"自动化效率"与"真人环境安全"。

Python 3.9+ License: MIT PRs Welcome

🎬 它是怎么工作的？(一分钟看懂)

传统方式 (Playwright 脚本)： 人类写代码 → 定位按钮ID → 处理等待 → 遇到滑块报错崩溃 ❌

AI-Browser 方式： 人类说："帮我去 GitHub 找前5个热门 Python 项目并记录 Star 数" → AI 自动打开网页 🌐 → AI 自己看页面并点击 Trending 🖱️ → AI 提取数据并总结 ✅ → 中间遇到登录框？AI 暂停："主人，需要你扫个码" ⏸️

✨ 核心特性

🧠 智能决策引擎

  • 自主分析页面 - 实时获取 DOM 结构、可见元素、页面内容
  • 任务自动分解 - 将复杂任务拆解为可执行步骤
  • 自我纠正机制 - 操作失败时智能尝试替代方案
  • 多步骤执行 - 自动完成复杂的序列化操作

🤝 人机协作

  • 智能询问系统 - AI 在不确定时主动暂停询问用户
  • 登录检测 - 自动识别需要登录的场景并等待用户操作
  • 验证码处理 - 遇到验证码时暂停，由用户完成
  • 选择确认 - 关键操作前征求用户意愿

🌐 浏览器支持

  • 本地浏览器 - 使用你的 Edge/Chrome，保留 Cookie 和登录状态
  • 内置浏览器 - Playwright 内置 Chromium/Firefox/WebKit
  • 持久化会话 - 自动保存浏览数据，下次启动无需重新登录
  • 多浏览器切换 - 灵活配置，支持指定浏览器路径

💬 自然语言交互

  • 对话式任务 - 用自然语言描述任务，AI 自动理解执行
  • 上下文理解 - 记住对话历史，支持多轮对话
  • 命令模式 - 支持快捷命令（/help, /clear, /interactive 等）

🚀 快速开始

1. 环境要求

  • Python 3.9 或更高版本
  • Windows 10/11（推荐）或 Linux/macOS
  • Edge 或 Chrome 浏览器（可选，使用本地浏览器模式时需）

2. 安装步骤

# 克隆或下载项目
cd browserai

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install chromium

# （可选）安装其他浏览器内核
playwright install firefox
playwright install webkit

3. 配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，配置以下参数：

# ModelScope API 配置（支持所有openai格式的api）推荐ChatGLM
MODELSCOPE_API_KEY=your_api_key_here
MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
MODELSCOPE_MODEL=Qwen/Qwen3.5-397B-A17B

# 浏览器配置
USE_LOCAL_BROWSER=true          # 使用本地浏览器（Edge/Chrome）
HEADLESS=false                  # 是否无头模式（调试时建议关闭）
SLOW_MO=100                     # 操作延迟（毫秒），便于观察

4. 运行程序

# 方式 1: 直接运行
python main.py

# 方式 2: 使用启动脚本
# Windows
run.bat
# Linux/macOS
./run.sh

📖 使用示例

基础浏览任务

🤖 BrowserAI v0.2.3
智能浏览器助手 · 自主决策 · 人机协作

> 打开百度并搜索 Python 教程，打开第一个结果
[Step 1] {"action": "navigate", "url": "https://baidu.com"}
结果：导航到 https://baidu.com

[Step 2] {"action": "type", "text": "Python 教程", "submit": true}
结果：输入：Python 教程

[Step 3] {"action": "find_and_click", "keywords": ["Python 教程", "菜鸟教程"]}
结果：找到并点击：Python 教程

✅ 已完成！已为您搜索并打开 Python 教程页面。

复杂任务示例

> 帮我查看 GitHub 上最火的 Python 项目，并记录前 5 个的 star 数

[Step 1] 导航到 GitHub Trending
[Step 2] 提取页面内容
[Step 3] 分析并记录前 5 个项目
[Step 4] 总结返回结果

✅ 已完成！以下是 GitHub 上最火的 5 个 Python 项目：
1. public-apis/public-apis - 285k stars
2. system-design-primer - 277k stars
3. yt-dlp - 256k stars
...

人机协作场景

> 登录知乎并查看我的收藏

[Step 1] 导航到知乎
⚠️ 检测到可能需要登录
请在打开的浏览器窗口中完成登录，然后在此输入 "继续"

（用户在浏览器中完成登录操作）

💬 你的回答：继续

[Step 2] 等待用户登录后继续...
[Step 3] 点击"我的"菜单
[Step 4] 点击"收藏"标签

✅ 已完成！已打开您的知乎收藏页面。

🛠️ 可用命令

命令 说明
/help 显示帮助信息
/quit 退出程序
/clear 清除对话历史
/interactive 切换人机协作模式
/smart 切换智能决策模式
/mode 查看当前模式配置
/browser 查看浏览器配置

⚙️ 配置选项

环境变量 (.env)

变量名 说明 默认值
MODELSCOPE_API_KEY ModelScope API 密钥 必填
MODELSCOPE_BASE_URL API 基础 URL https://api-inference.modelscope.cn/v1
MODELSCOPE_MODEL 使用的模型 Qwen/Qwen3.5-397B-A17B
USE_LOCAL_BROWSER 使用本地浏览器 true
HEADLESS 无头模式 false
SLOW_MO 操作延迟（毫秒） 100
LOCAL_BROWSER_PATH 手动指定浏览器路径 自动检测

浏览器配置说明

使用本地浏览器（推荐）：

USE_LOCAL_BROWSER=true
  • ✅ 保留 Cookie 和登录状态
  • ✅ 使用浏览器插件
  • ✅ 使用保存的密码
  • ✅ 更真实的浏览环境

使用内置浏览器：

USE_LOCAL_BROWSER=false
  • ✅ 无需安装浏览器
  • ✅ 更干净的测试环境
  • ✅ 每次启动都是全新会话

🔧 高级用法

1. 自定义浏览器路径

# 在 .env 中指定
LOCAL_BROWSER_PATH=C:\Program Files\Microsoft\Edge\Application\msedge.exe

2. 无头模式运行

HEADLESS=true

适合服务器环境或自动化脚本。

3. 调整操作速度

# 加快操作速度
SLOW_MO=50

# 减慢便于观察
SLOW_MO=500

4. 修改 AI 模型

# 使用其他 ModelScope 模型
MODELSCOPE_MODEL=Qwen/Qwen2.5-72B-Instruct

📁 项目结构

browserai/
├── main.py              # 程序入口
├── cli.py               # 命令行交互界面
├── browser_agent.py     # 智能浏览器代理（核心）
├── llm_client.py        # LLM API 客户端
├── config.py            # 配置管理
├── requirements.txt     # Python 依赖
├── .env.example         # 环境变量示例
├── .gitignore           # Git 忽略配置
├── README.md            # 项目文档
├── CHANGELOG.md         # 更新日志
├── RELEASE_GUIDE.md     # 发布指南
├── cleanup.bat          # 清理脚本（Windows）
├── run.bat              # 启动脚本（Windows）
├── run.sh               # 启动脚本（Linux/macOS）
└── browser_data/        # 浏览器数据目录
    └── .gitkeep         # 保持目录的空文件

🐛 常见问题

1. 找不到浏览器

问题： Error: Could not find browser

解决方案：

# 方式 1: 使用内置浏览器
USE_LOCAL_BROWSER=false

# 方式 2: 安装 Playwright 浏览器
playwright install chromium

# 方式 3: 手动指定浏览器路径
LOCAL_BROWSER_PATH=C:\Program Files\Microsoft\Edge\Application\msedge.exe

2. API 连接失败

问题： API request failed

解决方案：

  • 检查 .env 文件中的 MODELSCOPE_API_KEY 是否正确
  • 检查网络连接是否正常
  • 检查 API URL 是否正确

3. 操作速度太慢

问题： 浏览器操作很慢

解决方案：

# 在 .env 中调整
SLOW_MO=50  # 减少延迟时间

4. 验证码/登录卡住

问题： AI 在验证码或登录页面停止

解决方案：

  • 这是正常的人机协作机制
  • 在打开的浏览器窗口中手动完成验证码/登录
  • 在命令行中输入 "继续" 或按回车键继续

5. 内存占用过高

问题： 浏览器内存占用很大

解决方案：

# 使用无头模式（更轻量）
HEADLESS=true

# 使用内置 Chromium（比 Edge/Chrome 更轻量）
USE_LOCAL_BROWSER=false

🔄 更新日志

查看 CHANGELOG.md 了解详细的版本更新记录。

最新版本 v0.2.3 (2026-04-18):

  • ✅ 修复 AI 重复询问问题（5个根本原因）
  • ✅ 添加 API 限速保护（1秒延迟）
  • ✅ 扩展自然语言关键词（35+关键词）
  • ✅ 完善发布流程文档
  • ✅ 添加清理脚本和安全指南

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

📮 联系方式

如有问题或建议，请提交 Issue。

用自然语言控制浏览器，让 AI 成为你最得力的助手！ 🚀

About

用自然语言控制浏览器。基于大模型自主决策、任务拆解与人机协作的智能浏览器自动化工具。支持本地 Cookie 环境，遇到疑问自动暂停等你接管。

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages