web-scraping

通过智能策略选择进行网页抓取

此技能的触发条件

在用户提出以下请求时自动触发：

• “抓取 [website]”
• “从 [site] 提取数据”
• “从 [URL] 获取产品信息”
• “查找 [site] 上的所有链接/页面”
• “我被拦截了”或“出现 403 错误”（加载 strategies/anti-blocking.md）
• “将其制作成 Apify Actor”（加载 apify/ 子目录）
• “让这个抓取器达到生产级别”

输入解析

根据用户请求确定侦察深度：

用户的说法	模式	运行阶段
“快速侦察”“只检查一下”“是什么框架”	快速	仅阶段 0
“抓取 X”“从 X 提取数据”（默认）	标准	阶段 0-3 和 5；仅在检测到防护信号时运行阶段 4
“全面侦察”“深度扫描”“生产级抓取”	完整	所有阶段（0-5），包括防护测试

默认使用标准模式。如果任一阶段出现防护信号，则升级为完整模式。

自适应侦察工作流

此技能采用带质量关卡的自适应分阶段工作流。每个关卡都会询问**“信息够了吗？”**——只有答案是否定的，才继续。

参见：strategies/framework-signatures.md，其中包含下文引用的框架检测表。

阶段 0：快速评估（curl，无需浏览器）

以最低成本收集尽可能多的信息——只需发送一个 HTTP 请求。

步骤 0a：获取原始 HTML 和标头

curl -s -D- -L "https://target.com/page" -o response.html

步骤 0b：检查响应标头

• 将标头与 strategies/framework-signatures.md →“响应标头特征”表进行匹配
• 记录 Server、X-Powered-By、X-Shopify-Stage、Set-Cookie（防护标记）
• 检查 HTTP 状态码（200 = 可访问，403 = 受保护，3xx = 重定向）

步骤 0c：检查“已知主要网站”表

• 将域名与 strategies/framework-signatures.md →“已知主要网站”进行匹配
• 如果匹配：使用指定的数据策略，跳过通用模式扫描

步骤 0d：从 HTML 检测框架

• 在原始 HTML 中搜索 strategies/framework-signatures.md →“HTML 特征”表中的特征
• 查找 __NEXT_DATA__、__NUXT__、ld+json、/wp-content/、data-reactroot

步骤 0e：搜索目标数据点

• 对用户需要的每个数据点：在原始 HTML 中搜索相应内容
• 记录已找到和缺失的数据点
• 检查站点地图：curl -s https://[site]/robots.txt | grep -i Sitemap

步骤 0f：记录防护信号

• 403/503 状态码、Cloudflare 验证页面 HTML、CAPTCHA 元素、cf-ray 标头
• 记录下来，以供阶段 4 决策时使用

参见：strategies/cheerio-vs-browser-test.md，了解 Cheerio 可行性评估

质量关卡 A：原始 HTML 中是否找到了所有目标数据点，且没有防护信号？ → 是：跳至阶段 3（验证发现结果）。无需浏览器。 → 否：继续阶段 1。

阶段 1：浏览器侦察（仅在阶段 0 需要时）

仅当原始 HTML 中缺少数据点或需要 JavaScript 渲染时，才启动浏览器。

步骤 1a：初始化浏览器会话

• proxy_start() → 启动流量拦截代理
• interceptor_chrome_launch(url, stealthMode: true) → 启动具有反检测功能的 Chrome
• interceptor_chrome_devtools_attach(target_id) → 附加 DevTools 桥接
• interceptor_chrome_devtools_screenshot() → 捕获视觉状态

步骤 1b：捕获流量和渲染后的 DOM

• proxy_list_traffic() → 查看页面加载期间的所有流量
• proxy_search_traffic(query: "application/json") → 查找 JSON 响应
• interceptor_chrome_devtools_list_network(resource_types: ["xhr", "fetch"]) → 查看 XHR/fetch 调用
• interceptor_chrome_devtools_snapshot() → 获取无障碍树（渲染后的 DOM）

步骤 1c：在渲染后的 DOM 中搜索缺失的数据点

• 对于阶段 0 中未找到的每个数据点：搜索渲染后的 DOM
• 使用 strategies/framework-signatures.md → 框架 → 搜索策略表中的特定框架搜索策略
• 仅搜索与检测到的框架相关的模式

步骤 1d：检查发现的端点

• proxy_get_exchange(exchange_id) → 获取有潜力的端点的完整请求/响应
• 记录：方法、标头、身份验证、响应结构、分页

质量关卡 B：现在是否已涵盖所有目标数据点（原始 HTML + 渲染后的 DOM + 流量）？ → 是：跳至阶段 3（验证发现）。无需深度扫描。 → 否：继续阶段 2，仅查找缺失的数据点。

阶段 2：深度扫描（仅针对缺失的数据点）

针对尚未找到的数据点进行定向调查。仅搜索缺失的内容。

步骤 2a：测试交互以查找缺失数据

• 每次操作前运行 proxy_clear_traffic() → 隔离 API 调用
• humanizer_click(target_id, selector) → 触发动态内容加载
• humanizer_scroll(target_id, direction, amount) → 触发延迟加载/无限滚动
• humanizer_idle(target_id, duration_ms) → 等待延迟内容
• 每次操作后：运行 proxy_list_traffic() → 检查是否有新的 API 调用

步骤 2b：嗅探 API（适配框架）

• 仅搜索与检测到的框架相关的模式：
  • Next.js → proxy_list_traffic(url_filter: "/_next/data/")
  • WordPress → proxy_list_traffic(url_filter: "/wp-json/")
  • GraphQL → proxy_search_traffic(query: "graphql")
  • 通用 → proxy_list_traffic(url_filter: "/api/") + proxy_search_traffic(query: "application/json")
• 跳过与检测到的框架无关的模式

步骤 2c：测试分页和筛选

• 仅当分页数据是缺失的数据点或评估覆盖范围所需时
• proxy_clear_traffic() → 点击下一页 → proxy_list_traffic(url_filter: "page=")
• 记录分页类型（基于 URL、API 偏移量、游标、无限滚动）

质量关卡 C：是否已涵盖足够的数据点，以生成有用的报告？ → 是：前往阶段 3。 → 否：记录缺口，仍然前往阶段 3（报告将在自我批判中注明缺失的数据）。

阶段 3：验证发现结果

必须验证每种声称的提取方法。只有明确指定并测试提取路径后，数据点才算「已找到」。

参见：strategies/cheerio-vs-browser-test.md，了解验证方法

步骤 3a：验证 CSS 选择器

• 对于每种基于 Cheerio/选择器的方法：确认选择器与实际 HTML 匹配
• 使用原始 HTML（curl 输出）或渲染后的 DOM（快照）进行测试
• 确认选择器提取的是正确值，而非其他元素的值

步骤 3b：验证 JSON 路径

• 对于每种 JSON 提取方式（例如 __NEXT_DATA__、API 响应）：确认路径可解析
• 解析 JSON，沿路径查找，并确认返回的是预期的数据类型和值

步骤 3c：验证 API 端点

• 对于每个发现的 API：重放请求（curl 或 proxy_get_exchange）
• 确认：响应状态为 200、数据结构符合预期、值正确
• 如果声称支持分页，则测试分页（至少测试第 1 页和第 2 页）

步骤 3d：降低置信度或重新调查失败项

• 如果选择器不匹配：尝试其他选择器，或将置信度降至「部分」
• 如果 API 返回 403：注明存在防护要求，并标记以便在阶段 4 处理
• 如果 JSON 路径错误：重新检查 JSON 结构并修正路径

阶段 4：防护测试（有条件执行）

参见：strategies/proxy-escalation.md，了解完整的跳过/执行决策逻辑

满足以下所有条件时，跳过阶段 4：

• 阶段 0 至 2 未检测到任何防护信号
• 所有数据点均有经过验证的提取方法
• 用户未要求「完整侦察」

满足以下任一条件时，执行阶段 4：

• 任一阶段观察到 403/挑战页面
• 已知是高防护域名
• 访问量较大或用于生产环境
• 用户明确提出要求

如果执行：

步骤 4a：测试原始 HTTP 访问

curl -s -o /dev/null -w "%{http_code}" "https://target.com/page"

• 200 → Cheerio 可行；对于可访问的端点，无需使用浏览器
• 403/503 → 升级为隐身浏览器

步骤 4b：使用隐身浏览器测试（如有需要）

• 阶段 1 已启动 — 检查页面是否在没有挑战的情况下加载
• interceptor_chrome_devtools_list_cookies(domain_filter: "cloudflare") → 防护 Cookie
• interceptor_chrome_devtools_list_storage_keys(storage_type: "local") → 指纹标记
• proxy_get_tls_fingerprints() → TLS 指纹分析

步骤 4c：使用上游代理测试（如有需要）

• proxy_set_upstream("http://user:pass@proxy-provider:port")
• 通过代理重新测试被拦截的端点
• 记录每个数据点所需的最低访问级别

步骤 4d：记录防护配置

• 记录存在哪些防护、哪些方法成功绕过防护，以及生产环境的抓取程序需要什么

第 5 阶段：报告 + 自我批判

生成情报报告，然后对其进行批判性审查，找出遗漏。

参见：reference/report-schema.md，了解完整的报告格式

第 5a 步：生成报告

• 遵循 reference/report-schema.md 架构（第 1-6 节）
• 为每种策略注明 Validated? 状态（YES / PARTIAL / NO）
• 列出所有已发现的端点及其完整规格

第 5b 步：自我批判

• 按照 reference/report-schema.md 编写第 7 节（自我批判）：
  • 遗漏项：未找到的数据点——说明原因，以及如何找到这些数据点
  • 跳过的步骤：跳过了哪些阶段，以及质量门控方面的理由
  • 未验证的声明：任何标记为 PARTIAL 或 NO 的内容
  • 假设：未经验证的事项（例如，“不同类别的布局一致”）
  • 时效性风险：依赖地理位置的价格、A/B 布局、会话专属内容
  • 建议：有针对性的后续步骤（而不是“全部重新运行”）

第 5c 步：通过有针对性的重新调查弥补遗漏

• 如果自我批判发现了可弥补的遗漏：返回具体阶段/步骤，而不是从头完整重跑
• 示例：“价格选择器未经测试” → 执行一次 curl 并解析，不要重新启动浏览器
• 根据结果更新报告

第 5d 步：记录会话（如果使用了浏览器）

• proxy_session_start(name) → proxy_session_stop(session_id) → proxy_export_har(session_id, path)
• HAR 文件会记录所有流量，以便重放。参见 strategies/session-workflows.md

---

实现（侦察之后）

侦察报告获批后，迭代实现抓取器。

核心流程：

1. 实现推荐的方法（尽量精简代码）
2. 使用小批量数据（5-10 个项目）进行测试
3. 验证数据质量
4. 扩展到完整数据集，或改用备用方案
5. 遇到拦截时进行处理
6. 提高稳健性（错误处理、重试、日志记录）

参见：workflows/implementation.md，了解完整的实现模式和代码示例

产品化（按需）

将抓取器转换为可用于生产环境的 Apify Actor。

触发条件：“Make this an Apify Actor”、“Productionize this”、“Deploy to Apify”

核心流程：

1. 确认是否首选 TypeScript（强烈推荐）
2. 使用 apify create 命令初始化（至关重要）
3. 将抓取逻辑移植为 Actor 格式
4. 在本地测试并部署

注意：开发期间，proxy-mcp 用于侦察和流量分析。对于生产环境中的 Actor，请在 Apify 基础设施上使用 Crawlee 爬虫（CheerioCrawler/PlaywrightCrawler）。

参见：workflows/productionization.md，了解完整工作流；另请参阅 apify/ 中的 Actor 开发指南

快速参考

任务	模式/命令	文档
侦察	自适应阶段 0-5	workflows/reconnaissance.md
框架检测	标头 + HTML 特征匹配	strategies/framework-signatures.md
Cheerio 与浏览器	三项测试 + 提前退出	strategies/cheerio-vs-browser-test.md
流量分析	proxy_list_traffic() + proxy_get_exchange()	strategies/traffic-interception.md
防护测试	按条件升级	strategies/proxy-escalation.md
报告格式	第 1-7 节，并进行自我批评	reference/report-schema.md
查找站点地图	RobotsFile.find(url)	strategies/sitemap-discovery.md
筛选站点地图 URL	RequestList + regex	reference/regex-patterns.md
发现 API	流量捕获（自动）	strategies/api-discovery.md
DOM 抓取	DevTools bridge + humanizer	strategies/dom-scraping.md
HTTP 抓取	CheerioCrawler	strategies/cheerio-scraping.md
混合方式	站点地图 + API	strategies/hybrid-approaches.md
处理拦截	隐身模式 + 上游代理	strategies/anti-blocking.md
会话录制	proxy_session_start() / proxy_export_har()	strategies/session-workflows.md
Proxy-MCP 工具	完整参考	reference/proxy-tool-reference.md
指纹配置	隐身 + TLS 预设	reference/fingerprint-patterns.md
创建 Apify Actor	apify create	apify/cli-workflow.md
模板选择	Cheerio 与 Playwright	workflows/productionization.md
输入架构	.actor/input_schema.json	apify/input-schemas.md
部署 Actor	apify push	apify/deployment.md

常见模式

模式 1：基于站点地图的抓取

import { RobotsFile, CheerioCrawler, Dataset } from 'crawlee';

// Auto-discover and parse sitemaps
const robots = await RobotsFile.find('https://example.com');
const urls = await robots.parseUrlsFromSitemaps();

const crawler = new CheerioCrawler({
    async requestHandler({ $, request }) {
        const data = {
            title: $('h1').text().trim(),
            // ... extract data
        };
        await Dataset.pushData(data);
    },
});

await crawler.addRequests(urls);
await crawler.run();

完整示例请参见 examples/sitemap-basic.js。

模式 2：基于 API 的抓取

import { gotScraping } from 'got-scraping';

const productIds = [123, 456, 789];

for (const id of productIds) {
    const response = await gotScraping({
        url: `https://api.example.com/products/${id}`,
        responseType: 'json',
    });

    console.log(response.body);
}

完整示例请参见 examples/api-scraper.js。

模式 3：混合方式（站点地图 + API）

// Get URLs from sitemap
const robots = await RobotsFile.find('https://shop.com');
const urls = await robots.parseUrlsFromSitemaps();

// Extract IDs from URLs
const productIds = urls
    .map(url => url.match(/\/products\/(\d+)/)?.[1])
    .filter(Boolean);

// Fetch data via API
for (const id of productIds) {
    const data = await gotScraping({
        url: `https://api.shop.com/v1/products/${id}`,
        responseType: 'json',
    });
    // Process data
}

完整示例请参见 examples/hybrid-sitemap-api.js。

目录导航

此技能采用渐进式披露——详细信息按子目录组织，仅在需要时加载。

工作流（实施模式）

适用场景：每个阶段的分步工作流指南

• workflows/reconnaissance.md - 阶段 1 交互式侦察（关键）
• workflows/implementation.md - 阶段 4 迭代实施模式
• workflows/productionization.md - 阶段 5 Apify Actor 创建工作流

策略（深入指南）

适用场景：针对特定抓取方式的详细指南

• strategies/framework-signatures.md - 框架检测查找表（阶段 0/1）
• strategies/cheerio-vs-browser-test.md - Cheerio 与浏览器的选择测试，支持提前退出
• strategies/proxy-escalation.md - 防护测试的跳过/执行条件（阶段 4）
• strategies/traffic-interception.md - 通过 MITM 代理拦截流量
• strategies/sitemap-discovery.md - 完整的站点地图指南（4 种模式）
• strategies/api-discovery.md - 查找和使用 API
• strategies/dom-scraping.md - 通过 DevTools bridge 抓取 DOM
• strategies/cheerio-scraping.md - 仅使用 HTTP 的抓取
• strategies/hybrid-approaches.md - 组合多种策略
• strategies/anti-blocking.md - 多层反检测（隐身、humanizer、代理、TLS）
• strategies/session-workflows.md - 会话录制、HAR 导出与重放

示例（可运行代码）

用途：供参考或执行的可运行代码

JavaScript 学习示例（简单的独立脚本）：

• examples/sitemap-basic.js - 简单的站点地图抓取工具
• examples/api-scraper.js - 纯 API 方案
• examples/traffic-interception-basic.js - 基于代理的侦察
• examples/hybrid-sitemap-api.js - 组合方案
• examples/iterative-fallback.js - 依次尝试流量拦截→站点地图→API→DOM 抓取

TypeScript 生产示例（完整的 Actor）：

• apify/examples/basic-scraper/ - 站点地图 + Playwright
• apify/examples/anti-blocking/ - 指纹识别 + 代理
• apify/examples/hybrid-api/ - 站点地图 + API（最佳方案）

参考资料（快速查阅）

用途：快速了解常用模式并排查问题

• reference/report-schema.md - 情报报告格式（第 1–7 节 + 自我批判）
• reference/proxy-tool-reference.md - Proxy-MCP 工具参考（全部 80 多种工具）
• reference/regex-patterns.md - 常见 URL 正则表达式模式
• reference/fingerprint-patterns.md - 隐身模式 + TLS 指纹预设
• reference/anti-patterns.md - 禁忌做法

Apify（生产部署）

用途：创建生产环境中的 Apify Actor

• apify/README.md - 何时以及如何使用 Apify
• apify/typescript-first.md - 为何 Actor 使用 TypeScript
• apify/cli-workflow.md - apify create 工作流（至关重要）
• apify/initialization.md - 完整设置指南
• apify/input-schemas.md - 输入验证模式
• apify/configuration.md - actor.json 设置
• apify/deployment.md - 测试与部署
• apify/templates/ - TypeScript 样板代码

注意：每个文件都包含完整内容，可独立阅读。Claude 会根据需要查阅特定文件。

核心原则

1. 评估后再投入资源

从低成本方式（curl）开始，仅在需要时升级：

• 先进行阶段 0（curl），再进行阶段 1（浏览器），最后进行阶段 2（深度扫描）
• 数据充足时，质量门槛会跳过相应阶段
• 如果 curl 已能获取全部所需内容，就不要启动浏览器

2. 先检测，再搜索相关模式

利用框架检测来聚焦搜索：

• 扫描前先与 strategies/framework-signatures.md 中的特征匹配
• 跳过不适用的模式（Amazon 上没有 __NEXT_DATA__）
• 对于已知的大型网站，直接查找对应策略

3. 验证，不要假设

每种声称的提取方法都必须经过测试：

• “在 HTML 中找到文本”还不够——必须有可用的选择器或路径
• 阶段 3 会在生成报告前验证每项发现
• 未经验证的说法会在报告中标记为 PARTIAL 或 NO

4. 迭代式实现

逐步构建：

• 先测试一小批（5–10 项）
• 验证质量
• 扩大规模或回退
• 最后再增强稳健性

5. 面向生产环境的代码

转为生产用途时：

• 使用 TypeScript（强烈推荐）
• 使用 apify create（切勿手动设置）
• 添加适当的错误处理
• 包含日志记录与监控

---

请记住：先拦截流量，其次使用站点地图，再其次使用 API，最后才进行 DOM 抓取！

有关任何主题的详细指南，请查阅上方列出的相关子目录文件。