mcpField
C
crawler

crawler

github.com/gn00678465数据与数据库1130 次安装33 周前更新
代码仓库

关于 crawler

Crawler 是一个将网页 URL 转换为整洁 Markdown 的抓取 skill，适用于需要提取网页文本的工作流。它依次尝试 Firecrawl、Jina Reader 和 Scrapling，并验证抓取内容后再返回。

主要功能

  1. 01将网页内容转换为 Markdown
  2. 02按顺序尝试三种抓取方式
  3. 03按域名跳过不兼容的方式
  4. 04验证内容并检测错误页面
  5. 05支持将结果保存到文件

适用场景

  1. 01提取网页正文供后续处理
  2. 02将文档页面保存为 Markdown
  3. 03在抓取方式失败时尝试备用方案

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gn00678465/crawler-skill --skill crawler

安装后在 Claude Code 中输入/crawler确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
scripts/
crawl.py
pyproject.toml
uv.lock
scripts/src/
domain_router.py
firecrawl_scraper.py
jina_reader.py
scrapling_scraper.py
tests/
test_crawl.py

详细介绍

爬虫技能

使用可靠的三级回退链，将任意 URL 转换为简洁的 Markdown。

快速开始

uv run scripts/crawl.py --url https://example.com --output reports/example.md

Markdown 会保存到 --output 指定的文件中。进度和错误会输出到 stderr。成功时退出代码为 0，所有爬虫均失败时退出代码为 1。

工作原理

脚本按顺序尝试各层，并返回第一个成功结果：

层级模块要求
1Firecrawl（firecrawl_scraper.py）FIRECRAWL_API_KEY 环境变量（可选；缺少时会回退）
2Jina Reader（jina_reader.py）无 — 免费，无需密钥
3Scrapling（scrapling_scraper.py）本地无头浏览器（通过 pip 自动安装）

文件布局

crawler-skill/
├── SKILL.md            ← this file
├── scripts/
│   ├── crawl.py               ← main CLI entry point (PEP 723 inline deps)
│   └── src/
│       ├── domain_router.py       ← URL-to-tier routing rules
│       ├── firecrawl_scraper.py   ← Tier 1: Firecrawl API
│       ├── jina_reader.py         ← Tier 2: Jina r.jina.ai proxy
│       └── scrapling_scraper.py   ← Tier 3: local headless scraper
└── tests/
    └── test_crawl.py          ← 70 pytest tests (all passing)

使用示例

# Basic fetch — tries Firecrawl, falls back to Jina, then Scrapling
# Always prefer using --output to avoid terminal encoding issues
uv run scripts/crawl.py --url https://docs.python.org/3/ --output reports/python_docs.md

# If no --output is provided, markdown goes to stdout (not recommended on Windows)
uv run scripts/crawl.py --url https://example.com

# With a Firecrawl API key for best results
FIRECRAWL_API_KEY=fc-... uv run scripts/crawl.py --url https://example.com --output reports/example.md

URL 要求

仅接受 http:// 和 https:// URL。传入任何其他方案（ftp://、file://、javascript:、纯路径等）都会以代码 1 退出并打印清晰的错误信息 — 不会尝试抓取。

保存报告

当用户要求将抓取的内容或摘要保存到文件时，始终使用 --output 参数，并将文件保存到项目根目录下的 reports/ 目录中（例如 {project_root}/reports）。如果该目录不存在，脚本会自动创建。

示例： 如果用户要求“保存到 result.md”，你应运行： uv run scripts/crawl.py --url <URL> --output reports/result.md

指向自托管的 Firecrawl 实例

FIRECRAWL_API_URL=http://localhost:3002 uv run scripts/crawl.py --url https://example.com

内容验证

每个爬虫都会在返回成功前验证其输出：

  • 内容至少 100 个字符（拒绝空页面或错误页面）
  • 检测 CAPTCHA / 机器人验证页面（Firecrawl）
  • 检测 Cloudflare 中间页（Scrapling — 会升级为 StealthyFetcher）
  • 检测 Jina 错误页面标识（Error:、Access Denied 等）

域名路由

某些主机名会跳过一个或多个爬虫层，以避免已知的兼容性问题。 相关逻辑位于 scripts/src/domain_router.py。

域名跳过的层级启用的链路
medium.com（及其子域名）firecrawljina → scrapling
mp.weixin.qq.comfirecrawl + jina仅 scrapling
其他所有域名—firecrawl → jina → scrapling

子域名匹配遵循后缀规则：blog.medium.com 会匹配 medium.com 规则，因为其主机名以 .medium.com 结尾。像 other.weixin.qq.com 这样的精确子域名则不会匹配 mp.weixin.qq.com。

运行测试

uv run pytest tests/ -v

全部 70 项测试均使用模拟 — 无需网络请求，也无需 API 密钥。

依赖项（由 uv run 自动安装）

  • firecrawl-py>=2.0 — Firecrawl Python SDK
  • httpx>=0.27 — Jina Reader 的 HTTP 客户端
  • scrapling>=0.2 — 支持隐身模式的无头抓取
  • html2text>=2024.2.26 — HTML 转 Markdown

何时调用此技能

每当需要获取网页的文本内容时，调用 crawl.py：

result = subprocess.run(
    ["uv", "run", "scripts/crawl.py", "--url", url],
    capture_output=True, text=True
)
if result.returncode == 0:
    markdown = result.stdout

或者按照上面的“快速开始”所示，直接在终端中运行。

评论

支持 Markdown