Metadata-Version: 2.4
Name: vibespider
Version: 0.3.0
Summary: The Optical-Based Browser Agent
Author: vibespider contributors
License: MIT License
        
        Copyright (c) 2026 MXFP4
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/mx-fp4/vibespider
Project-URL: Repository, https://github.com/mx-fp4/vibespider
Keywords: browser,agent,playwright,vision,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright~=1.58.0
Requires-Dist: openai~=2.23.0
Dynamic: license-file

# 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 真正带入视觉智能时代。

