vibespider 0.1.0__tar.gz

vibespider-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

vibespider-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: vibespider
+Version: 0.1.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
+Dynamic: license-file
+
+# vibespider
+
+> The Optical-Based Browser Agent  
+> 纯视觉驱动的浏览器智能体
+
+**核心哲学：I don't read code, I just look.（我不读代码，我只看屏幕）**
+
+vibespider 的目标不是“解析网页源码”，而是像人一样“看页面、做判断、再操作”。
+
+它基于 Playwright 驱动浏览器，把页面截图交给多模态大模型（如 Qwen-VL、GPT-4o）理解，再执行点击、输入、滚动、切页等拟人动作。
+
+这种方式对前端混淆、动态渲染、复杂 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（含兼容视觉推理接口）
+	- GPT-4o（含图像输入能力）
+
+---
+
+## 安装
+
+### 方式一：PyPI 安装（推荐）
+
+```bash
+pip install vibespider
+playwright install
+```
+
+### 方式二：从源码安装（开发中或本地调试）
+
+```bash
+cd /path/to/vibespider
+pip install -e .
+pip install -r requirements.txt
+playwright install
+```
+
+---
+
+## 示例调用
+
+> 以下示例展示典型 Agent 调用方式：给定目标，让智能体自行决策并调度操作。
+
+```python
+from vibespider import SpiderAgent
+
+agent = SpiderAgent(
+	model_provider="qwen",          # 或 "openai"
+	model_name="qwen-vl-max",       # 或 "gpt-4o"
+	api_key="YOUR_API_KEY",
+	headless=False,
+)
+
+result = agent.run(
+	task="打开某电商搜索页，搜索无线鼠标，提取前10条商品标题和价格",
+	start_url="https://example.com",
+	output_schema={
+		"items": [{"title": "str", "price": "str"}]
+	}
+)
+
+print(result)
+```
+
+> 当前 `0.1.x` 为最小可用骨架：已提供浏览器拉起、页面访问、全页截图与结果回传；完整的多轮决策调度（Observe → Think → Act）将在后续版本完善。
+
+---
+
+## 本地开发初始化（当前骨架）
+
+当前仓库处于早期阶段，建议按以下方式初始化你的实验环境：
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+playwright install
+```
+
+后续典型调用流程将是：
+1. 配置模型提供方（Qwen-VL / GPT-4o）与 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
+
+- [ ] Agent 循环核心（Observe → Think → Act）
+- [ ] Qwen-VL / GPT-4o 统一模型适配层
+- [ ] 动作 DSL（点击、输入、滚动、等待、重试）
+- [ ] 截图与决策日志回放
+- [ ] 失败恢复与自纠错策略
+- [ ] 结构化提取器（JSON Schema 输出）
+
+---
+
+## 注意事项
+
+- 请遵守目标网站的服务条款、robots 协议与当地法律法规。
+- 本项目用于自动化研究与工程实践，不鼓励滥用。
+- 涉及账号、支付、隐私数据时，请开启最小权限与审计日志。
+
+---
+
+## 项目愿景
+
+让网页自动化从“写选择器”进化到“看屏幕做决策”，
+把浏览器 Agent 真正带入视觉智能时代。
+

vibespider-0.1.0/README.md

@@ -0,0 +1,205 @@
+# vibespider
+
+> The Optical-Based Browser Agent  
+> 纯视觉驱动的浏览器智能体
+
+**核心哲学：I don't read code, I just look.（我不读代码，我只看屏幕）**
+
+vibespider 的目标不是“解析网页源码”，而是像人一样“看页面、做判断、再操作”。
+
+它基于 Playwright 驱动浏览器，把页面截图交给多模态大模型（如 Qwen-VL、GPT-4o）理解，再执行点击、输入、滚动、切页等拟人动作。
+
+这种方式对前端混淆、动态渲染、复杂 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（含兼容视觉推理接口）
+	- GPT-4o（含图像输入能力）
+
+---
+
+## 安装
+
+### 方式一：PyPI 安装（推荐）
+
+```bash
+pip install vibespider
+playwright install
+```
+
+### 方式二：从源码安装（开发中或本地调试）
+
+```bash
+cd /path/to/vibespider
+pip install -e .
+pip install -r requirements.txt
+playwright install
+```
+
+---
+
+## 示例调用
+
+> 以下示例展示典型 Agent 调用方式：给定目标，让智能体自行决策并调度操作。
+
+```python
+from vibespider import SpiderAgent
+
+agent = SpiderAgent(
+	model_provider="qwen",          # 或 "openai"
+	model_name="qwen-vl-max",       # 或 "gpt-4o"
+	api_key="YOUR_API_KEY",
+	headless=False,
+)
+
+result = agent.run(
+	task="打开某电商搜索页，搜索无线鼠标，提取前10条商品标题和价格",
+	start_url="https://example.com",
+	output_schema={
+		"items": [{"title": "str", "price": "str"}]
+	}
+)
+
+print(result)
+```
+
+> 当前 `0.1.x` 为最小可用骨架：已提供浏览器拉起、页面访问、全页截图与结果回传；完整的多轮决策调度（Observe → Think → Act）将在后续版本完善。
+
+---
+
+## 本地开发初始化（当前骨架）
+
+当前仓库处于早期阶段，建议按以下方式初始化你的实验环境：
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+playwright install
+```
+
+后续典型调用流程将是：
+1. 配置模型提供方（Qwen-VL / GPT-4o）与 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
+
+- [ ] Agent 循环核心（Observe → Think → Act）
+- [ ] Qwen-VL / GPT-4o 统一模型适配层
+- [ ] 动作 DSL（点击、输入、滚动、等待、重试）
+- [ ] 截图与决策日志回放
+- [ ] 失败恢复与自纠错策略
+- [ ] 结构化提取器（JSON Schema 输出）
+
+---
+
+## 注意事项
+
+- 请遵守目标网站的服务条款、robots 协议与当地法律法规。
+- 本项目用于自动化研究与工程实践，不鼓励滥用。
+- 涉及账号、支付、隐私数据时，请开启最小权限与审计日志。
+
+---
+
+## 项目愿景
+
+让网页自动化从“写选择器”进化到“看屏幕做决策”，
+把浏览器 Agent 真正带入视觉智能时代。
+

vibespider-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vibespider"
+version = "0.1.0"
+description = "The Optical-Based Browser Agent"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "vibespider contributors" }]
+dependencies = ["playwright~=1.58.0"]
+keywords = ["browser", "agent", "playwright", "vision", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/mx-fp4/vibespider"
+Repository = "https://github.com/mx-fp4/vibespider"
+
+[tool.setuptools.packages.find]
+include = ["vibespider*"]

vibespider-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vibespider-0.1.0/vibespider/__init__.py

@@ -0,0 +1,4 @@
+from .agent import SpiderAgent
+
+__all__ = ["SpiderAgent"]
+__version__ = "0.1.0"

vibespider-0.1.0/vibespider/agent.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from playwright.sync_api import sync_playwright
+
+
+@dataclass
+class SpiderAgent:
+    model_provider: str = "openai"
+    model_name: str = "gpt-4o"
+    api_key: str | None = None
+    headless: bool = True
+    viewport_width: int = 1440
+    viewport_height: int = 900
+
+    def run(
+        self,
+        task: str,
+        start_url: str,
+        output_schema: dict[str, Any] | None = None,
+        screenshot_path: str = "artifacts/last.png",
+    ) -> dict[str, Any]:
+        output_file = Path(screenshot_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with sync_playwright() as playwright:
+            browser = playwright.chromium.launch(headless=self.headless)
+            context = browser.new_context(
+                viewport={"width": self.viewport_width, "height": self.viewport_height}
+            )
+            page = context.new_page()
+            page.goto(start_url, wait_until="domcontentloaded")
+            page.screenshot(path=str(output_file), full_page=True)
+            title = page.title()
+            current_url = page.url
+            browser.close()
+
+        return {
+            "status": "ok",
+            "task": task,
+            "model": {
+                "provider": self.model_provider,
+                "name": self.model_name,
+            },
+            "start_url": start_url,
+            "current_url": current_url,
+            "page_title": title,
+            "screenshot": str(output_file),
+            "output_schema": output_schema,
+            "note": "MVP skeleton: capture + observe only, decision loop will come in next versions.",
+        }

vibespider-0.1.0/vibespider.egg-info/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: vibespider
+Version: 0.1.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
+Dynamic: license-file
+
+# vibespider
+
+> The Optical-Based Browser Agent  
+> 纯视觉驱动的浏览器智能体
+
+**核心哲学：I don't read code, I just look.（我不读代码，我只看屏幕）**
+
+vibespider 的目标不是“解析网页源码”，而是像人一样“看页面、做判断、再操作”。
+
+它基于 Playwright 驱动浏览器，把页面截图交给多模态大模型（如 Qwen-VL、GPT-4o）理解，再执行点击、输入、滚动、切页等拟人动作。
+
+这种方式对前端混淆、动态渲染、复杂 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（含兼容视觉推理接口）
+	- GPT-4o（含图像输入能力）
+
+---
+
+## 安装
+
+### 方式一：PyPI 安装（推荐）
+
+```bash
+pip install vibespider
+playwright install
+```
+
+### 方式二：从源码安装（开发中或本地调试）
+
+```bash
+cd /path/to/vibespider
+pip install -e .
+pip install -r requirements.txt
+playwright install
+```
+
+---
+
+## 示例调用
+
+> 以下示例展示典型 Agent 调用方式：给定目标，让智能体自行决策并调度操作。
+
+```python
+from vibespider import SpiderAgent
+
+agent = SpiderAgent(
+	model_provider="qwen",          # 或 "openai"
+	model_name="qwen-vl-max",       # 或 "gpt-4o"
+	api_key="YOUR_API_KEY",
+	headless=False,
+)
+
+result = agent.run(
+	task="打开某电商搜索页，搜索无线鼠标，提取前10条商品标题和价格",
+	start_url="https://example.com",
+	output_schema={
+		"items": [{"title": "str", "price": "str"}]
+	}
+)
+
+print(result)
+```
+
+> 当前 `0.1.x` 为最小可用骨架：已提供浏览器拉起、页面访问、全页截图与结果回传；完整的多轮决策调度（Observe → Think → Act）将在后续版本完善。
+
+---
+
+## 本地开发初始化（当前骨架）
+
+当前仓库处于早期阶段，建议按以下方式初始化你的实验环境：
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+playwright install
+```
+
+后续典型调用流程将是：
+1. 配置模型提供方（Qwen-VL / GPT-4o）与 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
+
+- [ ] Agent 循环核心（Observe → Think → Act）
+- [ ] Qwen-VL / GPT-4o 统一模型适配层
+- [ ] 动作 DSL（点击、输入、滚动、等待、重试）
+- [ ] 截图与决策日志回放
+- [ ] 失败恢复与自纠错策略
+- [ ] 结构化提取器（JSON Schema 输出）
+
+---
+
+## 注意事项
+
+- 请遵守目标网站的服务条款、robots 协议与当地法律法规。
+- 本项目用于自动化研究与工程实践，不鼓励滥用。
+- 涉及账号、支付、隐私数据时，请开启最小权限与审计日志。
+
+---
+
+## 项目愿景
+
+让网页自动化从“写选择器”进化到“看屏幕做决策”，
+把浏览器 Agent 真正带入视觉智能时代。
+

vibespider-0.1.0/vibespider.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+vibespider/__init__.py
+vibespider/agent.py
+vibespider.egg-info/PKG-INFO
+vibespider.egg-info/SOURCES.txt
+vibespider.egg-info/dependency_links.txt
+vibespider.egg-info/requires.txt
+vibespider.egg-info/top_level.txt

vibespider-0.1.0/vibespider.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vibespider-0.1.0/vibespider.egg-info/requires.txt

@@ -0,0 +1 @@
+playwright~=1.58.0

vibespider-0.1.0/vibespider.egg-info/top_level.txt

@@ -0,0 +1 @@
+vibespider