Skip to main content
Glama
universal-scraper

universal-scraper

by qqkkrr

universal-scraper

把“从这个网站拿数据”变成一句人话。

配置驱动 · 四级反爬降级 · 数据校验 · 86 个 Python 模块 · 21 个站点配方 · 738 项测试 · MIT

universal-scraper 工作流

30 秒验证它能跑

git clone https://github.com/qqkkrr/universal-scraper.git
cd universal-scraper
pip install -r requirements.txt
bash scripts/setup.sh          # 装依赖 + 环境体检

python -m universal_scraper.cli doctor
python -m universal_scraper.cli fetch "https://example.com"

看到 doctor 的“22/23 项通过”和 fetch 的 200 响应,就说明引擎跑通了。

doctor 自检

中文文档:安装与使用说明 · 使用说明书 · 使用者解决方案手册

Related MCP server: pulldown

它解决什么问题

需要的数据散在不同网站上:有的页面直接给,有的藏在接口里,有的要登录才看得到。人工复制粘贴慢,而且同一站点换一天再采,字段和口径可能就变了,结果不可复现。

现成的采集工具大多假设站点结构稳定、没有防护。真实情况恰好相反:同一个任务里,A 站一次就能拿到,B 站要过三道关。所以真正难的不是“发请求”,而是判断这一站属于哪一类,再选一条成本最低、又不越界的路线。

怎么工作

把“抓数据”拆成五步,每步有明确的通过条件,前一步不过就不进下一步。

步骤

做什么

通过条件

01 判型

轻量请求一次目标页,判断是静态页、JS 壳,还是数据在接口里

能说出这站属于哪一类

02 选路线

按反爬强度选层级,能走低层不走高层

取数成本最低

03 抓小样

先抓 5–10 条,字段摆出来给人看

字段对得上再全量

04 全量

限速、断点续跑、异常隔离

不中断、不重复

05 复核

字段完整率、唯一键、同页双抓比对

完整率 ≥ 90%

反爬的四级降级链

不预设“这站一定很强”,逐级试探,遇到拦截才升级。多数站点停在 L1,真正需要打开浏览器的不到两成。

层级

手段

适用

L1

HTTP 直连,带浏览器指纹与必要请求头

静态页、公开接口

L2

浏览器指纹模拟,绕开简单环境检测

轻中度防护

L3

无头浏览器渲染,等数据加载后取 DOM 或接口响应

JS 渲染的壳页

L4

复用使用者本人已登录的浏览器会话

登录后才可见的内容

L4 只做“复用登录态”:由使用者本人完成登录,工具不代填密码、不代过验证码。

验证到什么程度

判断标准只有一条:换一个站点,这套流程还成立吗。

类型

代表

难点

司法公开

中国裁判文书网

登录墙 + 强风控

政务服务

12306

会话校验

统计口径

国家统计局

多维查询、翻页结构

地方公开

各级政府门户

页面陈旧、编码混乱

仓库内置 21 个站点配方,覆盖公开 API、SSR、JS 壳和需登录调优四类:

站点配方

python -m universal_scraper.cli sites

引擎本体经 10 轮审计,当前 pytest 收集 738 项测试;77 个测试文件,另有独立 CI 脚本。

一个真实例子

采 A 股「算力 / 智算中心 / 东数西算 / 数据中心」相关公告时,标题里带 HTML 高亮标签,直接统计会把「计算机能力」「电力」误判成「算力」。按连续词过滤后剔除 402 条,671 条收敛为 269 条——如果不做这一步,结论会虚高 150%。

边界

  • 只采公开数据。不绕过登录墙获取非公开内容,不逆向签名算法,不破解付费/版权墙。

  • 默认单站每秒不超过 1 次请求;大任务开工前先估算总请求数。

  • 站点改版会让配置失效。工具能降低维护成本,但消不掉它——所以判型表和校验流程是核心资产,不是附件。

  • 数据是否可信、口径是否一致,仍要人来判断。工具负责把可疑处标出来,不替人下结论。

目录

路径

内容

SKILL.md

AI 读取的工作流程(五幕引导 + 铁律)

universal_scraper/

采集引擎本体(86 个 Python 模块)

references/

反爬升级手册 / 配置字段 / 站点配方

scripts/

环境安装、体检、调试 Chrome 启动器、浏览器桥

challenges/

挑战用例

webui/

本地可视化界面(cli webui)

docs/zh/

中文使用手册、安装说明、审查记录

docs/assets/

README 图片与 GIF

CLI 速览

fetch(侦察)· run(按配置/任务采集,支持断点续跑)· verify(结果复核)· snapshot(页面快照离线解析)· batch(批量队列)· pdf(PDF 下载与表格)· compliance(开工前合规预检)· budget(限速与封锁台账)· research(科研批量采集)

共 49 个 CLI 子命令,查看完整列表:

python -m universal_scraper.cli --help

作为 AI 技能安装

把仓库放进技能目录:

git clone https://github.com/qqkkrr/universal-scraper.git \
  ~/.agents/skills/universal-scraper
bash ~/.agents/skills/universal-scraper/scripts/setup.sh

之后直接用日常语言让 AI 干活,例如:

  • “把这个列表页的商品都抓下来,要名称、价格、链接,存桌面”

  • “帮我下载这 10 篇论文的 PDF”

  • “这个网站要登录,我扫码登录一次之后你接着抓”

  • “盯着这个页面,有更新就告诉我”

License

MIT

Available Tools

8 tools
autoA

用一句话描述爬虫任务,AI 自动生成配置、自动运行、失败自修复,返回结构化结果。适合:不会写选择器/配置的非技术用户。

Inputs: description (required), limit, rounds.

booksA

图书目录采集:按 ISBN 清单抓取豆瓣评分/作者/出版社、京东+当当聚合比价,导出 booklist.csv / booklist.md / books.json / crawl_log.md。只采集书目数据与公开封面,不下载电子书/PDF,不绕过登录或付费墙;0 条/部分失败会返回逐项诊断与行动方案(status=NO_DATA/PARTIAL),不会伪装成功。

Inputs: out, spec, interval, spec_path, +1 more.

bulk_scrapeA

批量抓取多个 URL(一次调用替代 N 次往返;逐 URL 隔离失败——单个 URL 出错不影响其余)。默认最多 10 个、上限 30(防爆)。每个 URL 有间隔(默认 1s)保持礼貌;返回每条的 url/status/摘要。

Inputs: urls (required), max, article, interval, +2 more.

checkB

引擎体检:返回版本、已通过测试(100+100+27)、能力矩阵、LLM 可用性、目录结构。

Inputs: no named parameters.

crawlA

从入口 URL 递归爬取整站/子目录,返回每页标题+正文+链接。适合:整站抓取、文档站镜像。

Inputs: url (required), deny, allow, depth, +3 more.

extractA

把 HTML 源码转成干净 Markdown/正文/表格,用于省 token 地阅读网页内容。默认先净化(剥离隐藏元素/注释/零宽字符等提示注入载体)再转换;main_only=true 时额外收窄到主内容容器(更适合阅读文章页)。

Inputs: html (required), raw, mode, base_url, +2 more.

scrapeA

一键抓取一个 URL,返回干净文本/Markdown/正文/表格/链接。适合:读网页内容、取正文、找表格、收集链接。

Inputs: url (required), links, proxy, table, +3 more.

screenshotA

对页面截图(浏览器渲染)并保存为图片文件,返回文件路径。用于人工核对渲染结果/排障;图片本身不内联返回。

Inputs: url (required), path, full_page, wait_selector.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation3/5

    Most tools have distinct roles (crawl, bulk_scrape, screenshot, check, books), but scrape and extract overlap heavily because both turn web content into clean Markdown/text/tables, differing mainly by URL vs HTML input. The auto tool also overlaps conceptually with scrape/crawl by generating and running scraping tasks, so agents may hesitate between auto, scrape, and extract.

    Naming Consistency2/5

    Names mix single verbs (scrape, crawl, check, extract), a noun-like tool (books), a vague automation label (auto), and one snake_case compound (bulk_scrape). The set is readable but has no predictable verb_noun or resource_action convention.

    Tool Count5/5

    Eight tools is well-scoped for a universal scraper, covering single-page scraping, batch scraping, recursive crawling, extraction, screenshots, diagnostics, AI-assisted automation, and a book-data specialization. Each tool has a plausible place in the workflow.

    Completeness4/5

    The surface covers the core scraping lifecycle: fetch one page, fetch many, crawl a site, extract from HTML, screenshot, diagnose, and automate configuration. Minor gaps exist around explicit session/cookie/proxy management or structured job status, but the main workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers