Python Web Scraping：构建生产级 Python 网页抓取系统的知识库，覆盖从目标评估到生产可观测性的完整技术栈。
首要工具调用原则 在本技能激活时，你的下一个非提问类工具调用必须启动一个带捕获面的可见浏览器，而不是先写 pyproject.toml、models.py，也不是先规划架构。浏览器优先，然后才是代码。若目标属于下方“内置目标”列表，其 Discovery Gate 已执行且捕获已记录，此时阅读对应参考并运行脚本即可，无需重新打开浏览器。未列入该列表的目标一律先开浏览器。默认路径是用户驱动导航加实时捕获，而非由 Claude 自行点击：先只问最基本的信息（目标 URL、所需数据、是否需要登录），然后立即打开浏览器，让用户登录并导航到数据页面、应用日常使用的筛选条件，随后导出捕获并基于真实端点推理。只有当无登录、无 2FA 且无界面知识缺口时，才采用 Claude 自行点击的变体。
何时使用 评估目标站点的防护等级并选择合适工具；通过网络流量拦截（Playwright/Patchright）发现 API 端点；在没有 API 时从渲染页面提取数据；绕过反机器人系统（Cloudflare、DataDome、PerimeterX）；配置 TLS/HTTP 指纹模拟（curl_cffi、primp）；搭建隐身浏览器自动化（Patchright、Camoufox、Nodriver）；设计带分层升级的代理架构；以编程方式解决验证码（CapSolver、2Captcha、playwright-captcha）；构建生产级抓取流水线（Scrapy、Crawlee）；为抓取系统加入速率限制与可观测性。
Discovery Gate（写任何代码前必读） 阶段一（目标评估）与阶段二（数据发现）是阻塞性关卡，必须在搭建任何项目文件之前亲自执行并拿到具体产出。发现阶段的交付物不是交给用户的脚本，而是你自己观看的实时捕获。捕获面需从页面启动时全部挂载：request/response 事件捕获 XHR 与 fetch（URL、方法、状态码、请求头、Cookie、请求体、JSON 或文本响应体）；websocket 事件的帧收发；对 text/event-stream（SSE）与分块传输的响应内容类型嗅探；worker 事件捕获 service worker 与专用 worker 发起的请求；GraphQL 检测（URL 以 /graphql 结尾，请求体含 operationName / variables / extensions.persistedQuery.sha256Hash）；登录后调用 context.cookies() 及反机器人 Cookie（cf_clearance、__cf_bm、datadome、_px3、ak_bmsc、incap_ses）；framenavigated 过滤主框架以记录重定向后的落点 URL。写入磁盘的内容需对 Authorization、Cookie 和密码字段做脱敏。
搭建项目前必须收集的发现产出（逐项核对，若仍为猜测则未完成发现）：每个承载目标数据页面的真实 URL；真实 XHR/fetch 端点 URL、方法、状态码、请求头、Cookie；至少一个捕获 JSON 响应中的真实字段名与结构；页面打开的 WebSocket 的握手 URL、子协议、双向首批帧（认证与订阅）及循环消息模式；SSE/EventSource 流的端点 URL、事件类型、载荷结构；GraphQL 的确切 operationName 与 variables 及持久查询 SHA；service worker/专用 worker 的 URL 与其发出的请求；反机器人指纹检查结果；API 发现失败需 DOM 回退时的 SPA 框架与 DOM 结构。
反模式（禁止）：在观察到目标一个真实网络请求前就搭建 pyproject.toml 与模块骨架；根据“常见模式”推断端点 URL；用正则或“常见字段名”列表替代真实端点名；用“意英可能名称”的 Pydantic alias 元组代替 API 实际返回的字段名；在能自己打开浏览器时却把 discover.py 脚本交给用户作为第一步发现；把阶段一/二标记为“跳过，稍后细化”却继续写代码。
核心工作流
- 目标评估（由你执行）：在浏览器加载目标 URL，识别静态 HTML 还是 JS 渲染、反机器人服务、所需数据量与更新频率，捕获重定向后的真实落点 URL、SPA 框架、反机器人 Cookie 的有无。
- 数据发现（API 优先，由你执行）：亲自导航，拦截所有网络流量，筛选返回 JSON、GraphQL 或结构化数据的 XHR/fetch 请求，分类为 REST 端点、WebSocket 流、GraphQL 查询、SSE 源，记录而非猜测 URL、方法、请求头、Cookie、响应结构与真实字段名。若找到结构化 API，生成 curl_cffi 重放代码，完全跳过浏览器。
- DOM 回退（仅当无 API）：若数据仅存在于渲染 HTML，用 CSS/XPath 选择器提取；解析 DOM 前先检查 JSON-LD、microdata 或内联 script JSON；DOM 不稳定时用基于 LLM 的提取（Crawl4AI、ScrapeGraphAI）作为最终回退；混合模式为稳定字段用 CSS 选择器、不稳定字段用 LLM 修复。
- 隐身与规避（最小化分层）：无防护用 curl_cffi impersonate="chrome"；基础 Cloudflare 用 Patchright 持久化上下文加真实 Chrome 通道；重度 Cloudflare/Turnstile 用隐身浏览器加验证码解决器加住宅代理；DataDome 用 Camoufox 加 ghost-cursor 行为模拟加住宅代理；PerimeterX 用自然导航模式加会话预热加住宅代理。
- 生产加固：速率限制用 pyrate-limiter v4 配 Redis 后端支持分布式；代理轮换采用分层升级（数据中心→ISP→住宅→移动）；可观测性用 structlog + Prometheus + Grafana；错误处理含退避重试、代理故障转移、会话轮换。
工具选择速查：无 JS 无防护用 curl_cffi，无浏览器，Scrapy/httpx；JS 渲染无防护用 Playwright，Crawlee；基础 Cloudflare 用 curl_cffi 加 cf_clearance，Patchright 取 Cookie，Scrapy；重度 Cloudflare 用 Patchright 持久化，Crawlee；DataDome 用 Camoufox 加 ghost-cursor；PerimeterX 用 Nodriver/Patchright；需要 AI 提取用 Crawl4AI/Firecrawl。
代理层级速查：0 无代理（免费，用于无防护目标与开发）；1 数据中心（$0.10-0.50/GB，轻度防护、大批量）；2 ISP 静态住宅（$0.53-1.47/IP，账号管理、登录流程）；3 住宅（$0.49-8.00/GB，反机器人绕过、地理定位）；4 移动（$4-13/GB，最高信任、最后手段）。
内置目标：Instagram 个人资料媒体——参考 references/instagram-media.md 与 scripts/instagram_grab.py，以全分辨率下载某资料的每张照片、轮播图和 reel。匿名访问已关闭（两个 web_profile_info 端点均返回 401 require_login），因此驱动已登录浏览器，捕获一次真实的 PolarisProfilePostsTabContentQuery_connection 请求并用替换游标的方式重放。需注意的陷阱：最新 24 条帖子在初始页面载荷中返回，永不出现在该查询里，因此被动网络监听会返回看似完整实则被截断的归档。
参考资料：field-guide.md 为 2025-2026 Python 网页抓取实地指南，涵盖浏览器隐身、TLS 指纹、行为生物识别、反机器人绕过、验证码解决、代理格局、框架、AI 辅助抓取、GraphQL 逆向工程、速率限制与可观测性；instagram-media.md 为捕获的 Instagram 表面，含已关闭的匿名路由、2026 登录选择器、欧盟付费或同意墙、grid 查询及其节点结构与下载阶段。