技能介绍

它解决什么问题

抓取脚本最常见的失败不是「取不到数据」，而是取到的数据悄悄变样：列表改成无限滚动、class 随构建哈希变化、分页参数换了字段名。一次性脚本要么在第三版页面布局上静默产出空数组，要么把嵌套 div 选择器写得比业务逻辑还长，下次改版直接崩。本技能针对的是这类「脆弱采集」：无路由策略、无配额核算、无交付前校验。

它如何工作

技能按三种模式智能路由，执行前先读 project-context.md 确认目标格式、数据规模与部署环境。

Mode 1 · API 驱动（Firecrawl）：公开 URL、JS/SPA 重渲染、搜索优先发现或整域批量爬取。Firecrawl 采用 BYOK，密钥只经 os.getenv('FIRECRAWL_API_KEY') 读取。
Mode 2 · 本地 Python：PDF/Excel/CSV 等本地文件，敏感数据不出域，或简单的静态 HTML 页面。
Mode 3 · 混合流水线：Firecrawl 负责发现与抽取，Pandas 负责清洗、归一化与结构化。

执行序列固定为：明确声明路由理由 → 预估 Firecrawl 配额或 token 预算 → 以可编辑模板起步（scripts/firecrawl_example.py 或 scripts/local_bs4_example.py），先跑 --sample 离线预览摘要结构 → 多页任务加 checkpointing，优雅处理分页与动态布局 → 交付前运行 python3 scripts/validate_extraction.py output.json --json，退出码 0（{"status": "ok"}）才允许交付；warning 或 error 一律重抽。

输出按结构选格式：表格数据默认 CSV，嵌套结构用 JSON，清洗文本用 Markdown。

适用边界与注意点

API 密钥不得硬编码：发现明文 key 应立即改写为环境变量读取。
隐私优先：用户想把本地敏感文件发给外部 API 时，应提示风险并建议切到 Mode 2。
分页缺失需拦截：目标暗示数百条记录却没写分页逻辑时，先补 checkpointing 再动手。
反模式：不要用 div > span > ul > li:nth-child(3) 这类高嵌套选择器，改用 data-* 属性或稳定结构锚点；不检查 robots.txt、不限速就抓；不校验空数组或缺失字段就直接落盘。

相关技能：data-cleaning 用于统计归一化与去重，browser-automation 用于需点击、登录等用户模拟的高交互场景，Firecrawl 不足以覆盖时应转向后者。