MarkCrawl 是一个用 Python 编写的网页爬取与结构化引擎，目标是把网页内容转化为适合 LLM 流水线使用的干净 Markdown。它可以在一条命令内抓取单个页面或爬取整个网站，剥离导航、脚本、样板内容，输出 Markdown 文件并附带结构化的 JSONL 索引，每页都包含带访问日期的引用。核心爬取与嵌入功能无需 API 密钥。
主要能力
- 抓取单个页面或整站，输出干净的 Markdown 和 pages.jsonl 索引。
- 内置本地嵌入器（自 v0.10.1 起默认），安装即带 torch + transformers + sentence-transformers，嵌入无需 API 密钥，可用参数切回 OpenAI。
- 遵循 robots.txt，支持 sitemap 优先爬取、并发抓取与代理、断点续爬与自动恢复。
- URL 过滤：--exclude-path、--include-path、--dry-run 预览；v0.11.1 默认过滤聚合器页面（如 mdBook /print.html、Hugo /_print/）。
- 提取后端可选默认 BS4、trafilatura、ensemble、ReaderLM-v2；可保留图片 alt 文本。
- 二进制下载：v0.11.0 起支持 download_types=["pdf","docx"]，可预取过滤回调；另支持下载图片。
- 截图：全页或裁剪，PNG 或 JPEG。
- 文本分块（可配置重叠与语义分块）、跨爬取去重（--cross-dedup）、按预测内容产出排序链接（--prioritize-links）、模板化 URL 簇智能采样（--smart-sample）。
- JavaScript 渲染：安装 markcrawl[js] 后使用 --render-js 处理 React/Vue/Angular 初始渲染内容。
- HTTP 重试：基于 tenacity 的全抖动指数退避（2 秒到 30 秒，5 次尝试），429 时遵循 Retry-After 头。
可选附加组件
- LLM 结构化提取：用 LLM 从每页抽取指定字段，支持 OpenAI、Anthropic (Claude)、Google Gemini、xAI (Grok)，可通过 --provider 选择；支持跨多个站点自动发现字段。
- Supabase 向量检索：分块、生成嵌入并上传到 Supabase pgvector，需要 SUPABASE_URL、SUPABASE_KEY 和 OPENAI_API_KEY。
- 智能体集成：提供 MCP 服务器、LangChain 工具、OpenClaw 技能；工具包括 crawl_site、list_pages、read_page、search_pages、extract_data。另有 docs/LLM_PROMPT.md 系统提示，可让 LLM 自动生成正确的 MarkCrawl 命令。
- 提供 Python API（result.pages）和页面类型提取、内容区域启发式。
使用方式 安装或升级：pip install markcrawl。如需 Playwright，安装后还要运行 playwright install chromium。精简安装（跳过本地嵌入器依赖栈）需设置 OPENAI_API_KEY 并传入 embedding_model="text-embedding-3-small"。快速开始后可获得含 pages.jsonl 的 ./demo 目录，每行包含页面各字段。常用模式包括单页抓取、整站爬取、URL 过滤、提取后端、二进制下载、截图以及端到端用例（竞品分析、RAG 聊天机器人、API 文档转代码生成）。完整命令见 docs/RECIPES.md。核心爬虫免费；提取与上传两个可选功能有 API 成本。
适用场景 适合聚焦范围、几百到低几千页的 RAG 数据摄入，例如文档站、博客、产品站，追求 LLM 可用 Markdown 且垃圾内容少、嵌入成本低。基准测试显示其导航污染最低（53 词，其他 500+ 词），速度 2.7 页/秒，总块数 27,193（比最多者少 2.2 倍）。
限制（官方明确列出）
- 不支持登录/鉴权站点，无 cookie 或会话支持。
- 无对抗机器人检测（Cloudflare、Akamai）的反规避能力。
- 不适合数百万页面规模，设计面向几百到低几千页，超大规模建议用 Scrapy。
- 仅支持 HTML，PDF 内容支持在路线图中。
- JavaScript SPA 需要加装 markcrawl[js] 并使用 --render-js。
- 无限滚动页面：--render-js 只渲染首次加载，不滚动，只能拿到首屏内容（例如 82 个 YouTube 视频中约 28 个）；完整列表需结合平台 API 或 RSS。
基准表现（官方披露，截至 bench v1.4，2026-05-11） 独立 llm-crawler-benchmarks v1.4 覆盖 7 款爬虫。MarkCrawl 成本排名第 1（10 万页规模约 $4,505/年），但答案质量 3.77/5 排第 7，检索准确率 MRR 0.341（领先者 0.76）。v0.11.1 过滤 /print.html 与 /_print/ 后，预计文档密集站点 MRR 提升 +0.02 到 +0.04。基准自身也在改进，v1.5 将改为从各站 sitemap 独立取题。以上为单次试验数据，多试验测量在 v1.5.1 路线图中。
其他 本地运行，无遥测、无分析、不发送数据；许可证为 MIT；有 647 个自动化测试、GitHub Actions CI（Python 3.10-3.13）和 ruff 检查。最新版本 v0.11.1（2026-05-12）。
