通用爬虫架构

universal-scraping-architect

分类编程

作者Alireza Rezvani

许可MIT

评分4.50/5

使用4.2K

通用抓取架构师 (Universal Scraping Architect)

设计完整且健壮的数据提取流水线，具备智能路由、验证和 Token 预算跟踪能力，而非脆弱的一次性脚本。

依赖项通知： Firecrawl 采用 BYOK（自带密钥）模式；API 密钥必须仅通过环境变量加载。各脚本依赖项如下：

| 脚本 | 依赖项 | 精确 CLI 命令 |
|---|---|---|
| scripts/validate_extraction.py | 仅标准库 | python3 scripts/validate_extraction.py output.json --json |
| scripts/firecrawl_example.py | firecrawl, requests (模板；--sample 离线运行) | python3 scripts/firecrawl_example.py --sample |
| scripts/local_bs4_example.py | beautifulsoup4, pandas (模板；--sample 离线运行) | python3 scripts/local_bs4_example.py --sample |

开始之前

优先检查上下文： 如果存在 project-context.md，请在提问前阅读。在编写任何代码之前，先确定目标数据格式、提取规模和部署环境。

此技能的工作原理

本技能支持基于智能路由的三种提取模式：

模式 1：API 驱动 (Firecrawl)

适用于源地址为公开 URL、高度动态（JS/SPA）、需要先搜索再发现，或涉及跨域大规模爬取的情况。

模式 2：本地 Python (传统)

适用于从本地文件（PDF, Excel, CSV）提取、数据私密/敏感，或目标为简单的静态 HTML 页面（使用 Firecrawl 过其）的情况。

模式 3：混合流水线

适用于由 Firecrawl 处理 URL 发现/网页提取，但需要本地 Python (Pandas) 在保存前对输出进行清洗、规范化和结构化处理的情况。

提取流水线

执行抓取任务时，请始终遵循以下顺序：
1. 确定路由方案： 明确说明使用的是 Firecrawl 还是本地 Python 及其原因。
2. 跟踪预算： 在执行大规模任务前，预估 Firecrawl API 配额或 LLM Token 上下文限制。
3. 安全提取： 为多页任务实现检查点机制。优雅地处理分页和动态布局。从可编辑的运行模板开始 —— scripts/firecrawl_example.py (模式 1) 或 scripts/local_bs4_example.py (模式 2)；首先使用 --sample 运行，以便在无需网络访问的情况下查看预期的摘要形状。
4. 验证与清洗： 在交付每个提取结果前，运行 python3 scripts/validate_extraction.py extracted_output.json --json。仅在 {"status": "ok"} 时退出码为 0；warning（输出为空）或 error（JSON 格式错误）退出码为 1 —— 此时应修复并重新提取，绝不要交付未经验证的数据。除此结构化关卡外，在交付前还需根据流水线规范检查必填字段和重复项。
5. 格式化： 表格数据默认使用 CSV，嵌套结构使用 JSON，纯文本使用 Markdown。

主动触发机制

当你在上下文中注意到以下问题时，无需被询问即可主动提出：

硬编码 API 密钥 $\rightarrow$ 立即标记并重写为使用 os.getenv('FIRECRAWL_API_KEY')。

私有数据泄露 $\rightarrow$ 如果用户要求将本地敏感文件发送到外部 API，请标记隐私风险并建议使用模式 2 (本地 Python)。

缺失分页逻辑 $\rightarrow$ 如果目标暗示有数百条记录但未要求分页逻辑，请标记并提示。

添加检查点（checkpointing）。

输出产物

| 当你要求... | 你将获得... |
|---------------------|------------|
| “抓取此网站” | 一个经过完整验证的 Python 提取脚本，包含路由逻辑和错误处理。 |
| “获取此表中的数据” | 一个干净的 CSV/JSON 数据集，以及包含行数和空值统计的摘要日志。 |
| “爬取这些文档” | 针对 LLM Token 限制进行分块处理的 Markdown 交付物。 |

反模式

脆弱的选择器： 绝不要使用高度嵌套的 CSS 选择器（例如 div > span > ul > li:nth-child(3)）。请使用数据属性或稳健的结构锚点。

忽视礼仪： 在未检查 robots.txt 或未实施合理的频率限制之前，绝不要进行抓取。

缺乏验证： 在未检查数组是否为空或是否缺失关键键值之前，绝不要盲目地将抓取的数据写入文件。