# vibespider

> The Optical-Based Browser Agent  
> 纯视觉驱动的浏览器智能体

**核心哲学：I don't read code, I just look.（我不读代码，我只看屏幕）**

**构建理念：This library is 100% vibe coded.（这个库是纯 vibe coding 构建出来的）**

vibespider 不追求“先把所有规则设计完再动手”，而是通过快速试验、即时反馈和持续迭代，把可运行的智能体能力一点点生长出来。

vibespider 的目标不是“解析网页源码”，而是像人一样“看页面、做判断、再操作”。

它基于 Playwright 驱动浏览器，把页面截图交给多模态大模型（Qwen-VL）理解，再执行点击、输入、滚动、切页等拟人动作。

这种方式对前端混淆、动态渲染、复杂 SPA、反爬脚本更鲁棒：
- 不依赖脆弱的 CSS/XPath 规则
- 不依赖页面语义化标签质量
- 不怕 DOM 结构频繁改版

---

## 为什么是“视觉驱动”

传统爬虫/自动化常见路径：
- 读 HTML
- 写选择器
- 绑定规则

问题是：
- 页面一改版，规则就断
- JS 动态内容难稳定抓取
- 混淆与反自动化策略让维护成本飙升

vibespider 的路径：
1. 用 Playwright 打开并控制真实浏览器
2. 截图当前页面（或局部区域）
3. 把截图和任务目标发送给多模态模型
4. **由智能体（Agent）综合模型结果生成下一步“动作计划”**（如点击哪个区域、输入什么、是否翻页）
5. **由智能体调度执行动作并监控反馈**，进入下一轮观察-决策-行动循环

本质上是把“规则驱动”转成“认知驱动”。

---

## 智能体如何决策与调度

在 vibespider 中，多模态模型负责“看懂画面”，而 **Agent 才是控制中枢**：

- **目标分解**：把用户任务拆成可执行的阶段（进入页面、定位目标区、触发动作、校验结果）
- **动作决策**：结合截图语义、历史动作和当前状态，选择下一步最优操作
- **执行调度**：统一调度 Playwright 原子动作（click/type/scroll/wait/navigate/retry）
- **反馈闭环**：执行后重新截图，判断是否达成子目标；失败则重试、换策略或回退
- **安全约束**：对高风险动作（提交、支付、删除）设置确认策略与保护规则

可以理解为：
- 模型 = 感知与理解
- Agent = 决策与编排
- Playwright = 执行器

---

## 能力边界（设计原则）

- **看得见才操作**：只基于屏幕可见信息做决策
- **拟人化路径**：优先模拟真实用户交互，降低机械行为特征
- **任务导向**：围绕“完成目标”而不是“抓全站 DOM”
- **可解释动作链**：每一步都可以输出截图 + 推理 + 执行动作记录

---

## 技术栈

- Python 3.10+
- Playwright（浏览器控制与截图）
- Multimodal LLM（视觉理解与动作决策）
	- Qwen-VL（通过 OpenAI SDK + 阿里百炼兼容接口调用）

---

## 安装

### 方式一：PyPI 安装（推荐）

```bash
pip install vibespider
playwright install
```

### 方式二：从源码安装（开发中或本地调试）

```bash
cd /path/to/vibespider
pip install -r requirements.txt
pip install -e .
playwright install
```

### 环境变量（推荐）

```bash
export DASHSCOPE_API_KEY="你的阿里百炼API Key"
```

---

## 示例调用

> 以下示例展示典型 Agent 调用方式：给定目标，让智能体自行决策并调度操作。

```python
from vibespider import SpiderAgent

agent = SpiderAgent(
	model_provider="openai-compatible",
	model_name="qwen3.5-flash",
	api_key=None,  # 推荐使用环境变量 DASHSCOPE_API_KEY
	headless=False,
	max_steps=10,
)

agent.run(
	task="访问网站，浏览页面，提取相关信息，存储为JSON格式。",
	start_url="https://www.tmgxy.edu.cn",
	crawl_site=True,
	crawl_time_limit_seconds=600,
	crawl_explore_ratio=0.7,  # 前70%时间探索，后30%时间深挖正文
	save_result_file=True,
	result_output_path="artifacts/result.json",
	save_page_files=True,
	pages_output_dir="artifacts/pages",
)
```

> 当前 `0.3` 已具备最小闭环：浏览器拉起、截图观察、模型决策、动作执行、步骤日志回传（Observe → Think → Act）。

---

## 本地开发初始化（当前骨架）

当前仓库处于早期阶段，建议按以下方式初始化你的实验环境：

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install
```

后续典型调用流程将是：
1. 配置 Qwen-VL 模型与 API Key（DASHSCOPE_API_KEY）
2. 指定任务目标（例如“进入搜索页并提取前 10 条结果标题”）
3. 启动视觉循环（截图 → 推理 → 动作）
4. 输出结构化结果和过程日志

---

## 打包与发布（PyPI）

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine upload dist/*
```

发布前建议先检查包内容：

```bash
python -m twine check dist/*
```

---

## 适用场景

- 高动态页面的数据采集
- 经常改版站点的稳定自动化
- 复杂交互流程（登录后、多步跳转、弹窗/浮层）
- 需要“像人一样浏览”的任务编排

---

## 与传统方案对比

| 维度 | 传统规则爬虫 | vibespider（视觉智能体） |
|---|---|---|
| 依赖 | DOM/选择器 | 屏幕视觉 + 多模态推理 |
| 抗改版能力 | 较弱 | 较强 |
| 面对混淆 | 易失效 | 更鲁棒 |
| 维护方式 | 改规则 | 调任务策略与提示词 |

---

## Roadmap

- [x] Agent 循环核心（Observe → Think → Act）
- [x] Qwen-VL 兼容接口适配层（OpenAI SDK + DashScope base_url）
- [ ] 动作 DSL（点击、输入、滚动、等待、重试）
- [ ] 截图与决策日志回放
- [ ] 失败恢复与自纠错策略
- [ ] 结构化提取器（JSON Schema 输出）

---

## 注意事项

- 请遵守目标网站的服务条款、robots 协议与当地法律法规。
- 本项目用于自动化研究与工程实践，不鼓励滥用。
- 涉及账号、支付、隐私数据时，请开启最小权限与审计日志。

---

## 项目愿景

让网页自动化从“写选择器”进化到“看屏幕做决策”，
把浏览器 Agent 真正带入视觉智能时代。

