Scrapling Web Fetch

---
name: scrapling-web-fetch
description: '使用 Scrapling 抓取、清洗、分析网页并生成结构化数据或中文报告。适用于 scrape / crawl / fetch / extract / summarize 网站内容、profile/activity feed、回答/文章/帖子列表、近 1 年动态、批量网页调研，以及用户明确提到 401/403、反爬、Cloudflare、登录受限、signin/login、need_force_login、需要 cookies/token、动态渲染、滚动加载、批量抓取、站点主题分析、网页证据收集等场景。特别适合知乎、专栏、公众号、博客、列表页+详情页链路。核心使用场景：批量采集多页/多站内容、突破访问受限（403/Cloudflare/反爬屏蔽）、抓取需要鉴权（login/cookie/token）的页面。'
---

## Scrapling 网页抓取与分析技能

使用 Scrapling 框架完成**网页抓取 → 内容清洗 → 结构化提取 → 主题分析 → 报告撰写**的完整流程。当 VS Code 内置抓取能力遇到 403、Cloudflare、登录限制或动态页面时，优先切换到本技能。

**重要：** 本技能的目标不只是“抓到网页”，而是交付**可复用过程资产、结构化数据和最终报告**。除非用户明确只要原始网页内容，否则不要在“抓取完成”后停下。

**重要：** 执行完本技能后，请检查 [LESSONS.md](./LESSONS.md) 经验教训文档，看是否需要补充新的经验。

## 何时使用本技能

### 触发词覆盖（中英关键词）

- 中文关键词：抓取网页、批量抓取、网页采集、反爬、403、风控、登录后可见、动态渲染、滚动加载、活动流、主页动态、近一年动态、回答汇总、文章汇总、站点调研、网页证据、专题分析、结构化提取、列表页详情页、内容聚类、用户画像。
- English keywords: scrape website, web crawl, fetch page, extract content, summarize posts, recent activity, profile timeline, activity feed, article list, answer list, protected site, anti-bot, blocked by 403, Cloudflare, login required, cookies, dynamic rendering, infinite scroll, evidence collection, topic clustering.
- 站点/对象信号：知乎、专栏、公众号、博客、门户站、profile、people、column、org、feed、posts、answers、articles、thoughts、activity。

### 可判定触发条件

满足以下任一组合时，应该唤醒本技能：

1. **站点 + 动作**：用户给出 URL / 站点名，并要求抓取、采集、提取、汇总、分析、总结、追踪动态。
2. **抓取 + 阻断**：用户提到 403、被拦截、需要登录、Cloudflare、反爬、验证码、只有骨架屏、内容空白。
3. **列表页 + 详情页**：用户要先抓取列表，再递归抓取回答/文章/帖子详情并汇总。
4. **时间范围 + 内容总结**：用户要最近 1 周、1 个月、1 年、季度动态、近期文章、历史行为变化。
5. **需要证据链**：用户不仅要结论，还要 URL、抓取结果、结构化样本、证据等级或不确定性说明。
6. **需要过程资产**：用户要求保存 HTML、Markdown、JSON、CSV、报告或中间数据。

### When NOT to use

以下情况**不要**优先使用本技能：

- 只是读取一个完全可公开访问的静态网页，且无需批量抓取、结构化提取或总结。
- 用户只要一段代码示例，不需要真实抓取执行。
- 任务与网页抓取无关，例如本地文件处理、数据库查询、纯代码重构。
- 任务核心是浏览器 UI 测试、截图、交互回放，而不是内容采集与分析。
- 用户只要求“看看这个网页大概写了什么”，内置抓取已可满足且没有 403 / 登录限制。

### 快速判定口诀

- **有 URL + 要内容/总结** → 倾向使用。
- **有 403 / 登录 / 动态渲染 / 滚动加载** → 直接使用。
- **要近一年动态、活动流、回答/文章汇总** → 直接使用。
- **只要单页简读且内置抓取可用** → 不必切换。

## 🚨 立即求助优先（认证阻断硬闸门）

命中以下任一信号时，必须先向用户求助凭据，不得继续同路径重试：

- HTTP 401 / 403
- 跳转到 `signin` / `login` / `passport`
- API 返回 `need_force_login` 或同类认证错误
- 页面仅骨架、仅导航、内容明显与目标不符

阻断应对规则：

- **明确认证阻断**（401/403/signin/need_force_login）→ **一次即求助，不等重试**
- 同 URL + 同 method 重试 **≤ 1**（仅适用于非鉴权类阻断，如偶发网络抖动）
- 阻断判定窗口 **≤ 90 秒**（超时仍无有效内容，视为阻断，立即求助）

禁止动作：

- 认证阻断已成立后，继续轮询同 URL
- 在未向用户求助前，反复切换 method 进行盲试
- 不记录证据直接宣称“站点无法抓取”

标准求助模板（可直接发给用户）：

- 我当前遇到认证阻断：`<401/403/login/need_force_login>`。
- 为继续抓取，请提供：`<Cookie / API Key / Token>`。
- 推荐获取方式：`DevTools → Application → Cookies 导出`（含 httpOnly）或 `Network 请求头 Cookie`。
- 如果你暂时不方便提供，我可以按“受限样本”继续，但会明确覆盖不足与不确定性。

## 使用场景

- 从任意 URL 获取网页内容
- 绕过反爬保护（Cloudflare、登录限制、动态渲染）
- 批量抓取机构主页、专栏、文章列表页、详情页
- 提取标题、发布时间、链接、正文摘要等结构化信息
- 汇总“最近 1 周 / 1 个月 / 某时间段”的文章内容
- 按主题聚类并输出观察结论
- 基于大量网页内容撰写调研报告、摘要或一页纸

## 交付目标

执行本技能时，默认目标应包括以下至少一项：

- `过程资产/html/`：原始 HTML
- `过程资产/md/`：提炼后的 Markdown 或纯文本
- `过程资产/data/`：结构化 JSON / CSV / 中间数据
- `报告.md`：中文调研报告 / 摘要 / 一页纸

如果用户明确只要网页正文或只要原始内容，可缩减交付物。

## 失败回退策略（403 / 风控 / 登录受限）

按以下顺序执行，避免无效重试：

1. **先证实是否真的被拦**：
  - 记录 URL、方法、状态码、页面关键特征（空白、登录页、骨架屏、验证码、need_force_login）。
  - 保存一份原始 HTML 作为阻断证据。
2. **先执行阻断判定（硬闸门）**：
  - 若命中 `401/403/signin/login/need_force_login` 任一信号，立即进入“向用户求助凭据”流程。
  - 命中硬闸门后，不得继续同路径重试。
3. **仅在未命中硬闸门时切换抓取方式**：
  - `stealthy` → `dynamic`
  - 若页面需要加载更多内容，增加 `--scroll N`
  - 若站点已知有正文选择器，优先加 `--css`
4. **切换到浏览器态抓取**：
  - 遇 403、Cloudflare、空白 DOM 时，优先 `stealthy` 或 `dynamic`
  - 需要更多列表数据时，优先浏览器滚动而不是直接调 API
5. **加载现有 cookie**：
  - 自动查找 `zhihu_cookies.json` 等本地 cookie 资产
  - 若已有 cookie，重试浏览器态抓取
6. **最小可行替代**：
  - 若完整活动流不可得，退而抓取公开可见的回答页、文章页、主页首屏、搜索引擎快照或站内公开列表
  - 明确标注覆盖范围不足、样本偏差和不确定性
7. **最终阻断输出**：
  - 给出已尝试路径、阻断证据、下一步最小可行方案（例如用户提供完整 cookie 后继续）

### 常见阻断信号与动作

| 信号 | 可能原因 | 立即动作 |
|------|----------|----------|
| HTTP 401/403 | 风控 / 匿名访问受限 / 认证失败 | 保留 HTML 证据，立即转凭据求助 |
| 跳到 `signin` / `login` | 需要登录 | 终止重试，转凭据求助 |
| 页面只有导航/框架 | SPA 骨架 / 选择器不对 / 认证门槛 | 先判定是否命中认证阻断；命中则求助，否则改 `dynamic` 或加 `--css` |
| API 返回 `need_force_login` | API 需要完整认证 | 停止 API 重试，转凭据求助 |
| 滚动后仍只有首屏少量内容 | 无限滚动请求被认证拦截 | 请求完整 cookie（含 `z_c0`）并停止盲重试 |

## 示例提示词（至少 10 条）

1. 抓取这个知乎用户近 1 年动态并做主题总结：`https://www.zhihu.com/people/...`
2. 帮我批量采集这个专栏最近 30 篇文章，提取标题、时间、摘要，并输出中文报告。
3. 这个站点直接访问 403，试试用浏览器隐身抓取并保存证据。
4. Summarize the recent activity of this profile over the last year and show evidence links.
5. Crawl this blog index plus all detail pages, then cluster topics into 5 categories.
6. 把这个公众号最近一个月文章抓下来，按时间和主题整理成 JSON + Markdown。
7. 这个页面是无限滚动，帮我加载更多内容并提取每条帖子链接。
8. 抓取回答列表和文章列表，分析这个用户最近行为有没有变化趋势。
9. 我需要网页证据链，不只要结论：请附 URL、抓取时间、证据等级和不确定性。
10. If the site is login-gated, try accessible paths first and tell me the minimum cookie needed next.
11. 帮我做一个站点调研：先抓列表页，再递归详情页，最后输出一页纸摘要。
12. 提取这个 profile 的 answers / articles / thoughts / activity feed，并统计最近一年发文节奏。

## 执行产出模板

默认按以下结构组织最终输出；若用户要求更简短，可裁剪但不要丢掉证据等级与不确定性。

### 输出结构

1. **任务概述**：目标站点、时间范围、执行时间、抓取路径。
2. **路径清单**：尝试过的 URL / 方法 / 是否成功。
3. **结构化样本**：标题、时间、链接、内容摘要、来源类型。
4. **分析结论**：时间分布、主题聚类、高互动内容、行为变化趋势。
5. **证据分级**：A / B / C。
6. **不确定性说明**：缺失页面、登录限制、样本偏差、时间覆盖不足。

### 证据等级定义

| 等级 | 定义 | 典型例子 |
|------|------|----------|
| A | 直接抓取到原始页面或官方公开页面，可复核 URL 与正文 | 公开回答页、公开文章页、抓到的活动流卡片 |
| B | 来自列表页摘要、站内搜索结果、页面片段或半结构化索引，信息较可靠但不完整 | 用户主页卡片、列表页标题+时间、公开摘要 |
| C | 间接线索或推断，需谨慎使用 | 页面骨架、搜索摘要、少量样本外推 |

### 不确定性模板

- **覆盖范围**：本次仅覆盖公开可访问页面 / 首屏 / 部分列表，未必代表全部动态。
- **时间偏差**：部分时间戳来自列表页展示，可能存在更新延迟或缺失。
- **互动偏差**：若站点未公开完整赞同/评论数据，高互动判断只能基于可见指标。
- **结论强度**：A 级证据支撑的结论可信度高；包含较多 B/C 级证据时，应视为趋势性判断。

## 前置条件

- Python 3.10+（推荐 Conda 环境）
- Scrapling：脚本会在首次运行时**自动检测并安装**（`pip install "scrapling[all]"` + `scrapling install`）
- 如需手动安装或排查安装问题，请参考 [快速部署指南](./快速部署指南.md)

> **自动安装行为：** `fetch_page.py` 启动时检测 `import scrapling`，若缺失则自动执行 `pip install "scrapling[all]"` 和 `scrapling install`（浏览器依赖）。无需人工干预。若自动安装失败，脚本会输出提示并退出，此时请按快速部署指南的踩坑记录排查。

---

## 📂 执行前确认：输出与资产管理

### 核心原则

**在执行任何抓取、目录创建、过程资产保存或报告落盘之前，必须先确认输出和资产的保存方式。** 不要假设用户需要创建文件夹、整理文件或生成报告目录——让用户决定。

### 确认时机

以下场景必须触发确认：

- 即将执行任何抓取任务，且会落盘文件
- 即将创建新目录、`过程资产/` 目录或报告目录
- 用户要求进行调研、批量收集、内容汇总、报告撰写
- 抓取结果将产生多个文件（HTML + Markdown + 数据 + 报告）

### 确认流程

**在执行抓取之前**，用一句话向用户确认以下四选一：

- 创建专用文件夹（推荐）
- 仅输出到当前目录
- 指定输出路径
- 仅输出到终端

若用户已有明确路径或已说明“不落盘”，则直接沿用，不必重复确认。

### 根据用户选择执行

- **创建专用文件夹**：按以下结构创建，并将抓取、分析和报告全部放入该目录
  ```
  <主题名>/
  ├── 过程资产/
  │   ├── html/     # 原始 HTML
  │   ├── md/       # 提炼后的 Markdown / 文本
  │   └── data/     # JSON / CSV / 中间数据
  ├── <主题名>总结.md
  └── <主题名>一页纸.md
  ```
- **仅输出到当前目录**：不创建子目录，`--output` 和 `--save-html` 直接指向当前目录
- **指定输出路径**：使用用户明确提供的路径
- **仅输出到终端**：不创建目录，不使用 `--output` 和 `--save-html`

### 跳过确认的情况

以下场景可直接执行：

- 用户已明确指定输出路径（如“保存到 xxx 目录”）
- 用户明确说“不保存文件”“直接输出结果”
- 仅抓取单个页面且用户未提及保存、汇总、整理、分析或报告

---

## ⚠️ 凭据求助机制

### 核心原则

**当你需要任何凭据（Cookie、API Key、Token 等）且无法独立获取时，必须立即向用户求助，而不是反复重试。**

向用户说明需要什么凭据、为什么需要、如何获取，并提供可执行的获取步骤。

### 需要凭据的信号

出现以下任一情况时，**立即停止重试**，转而向用户求助：

- 页面重定向到登录页（URL 含 `signin`、`login`、`passport`）
- API 返回 `need_force_login: true` 或类似认证错误
- 页面内容为空或仅含框架代码（HTML < 1KB 有效内容）
- HTTP 401/403 状态码
- 抓取结果与预期内容完全不符（如只拿到导航栏）

防卡死上限（必须执行）：

- 单 URL 总尝试次数 **≤ 3**
- 同 URL + 同 method 重试 **≤ 1**
- 若 90 秒内仍无法获得有效正文，立即转入求助流程

### 求助流程

**第一步：** 识别需要的凭据类型（Cookie / API Key / Token）

**第二步：** 询问用户并提供这四种获取方式：

1. 浏览器 `document.cookie`（适合页面抓取）
2. DevTools → Application → Cookies 导出（含 httpOnly，更完整）
3. DevTools → Network → 复制请求头里的 `Cookie`
4. 暂时跳过，接受受限样本继续分析

可直接复制的求助话术：

- 我这边已命中登录/鉴权阻断（`<401/403/signin/need_force_login>`），继续重试会卡死。
- 请你提供 `<Cookie/API Key/Token>` 之一，我将继续抓取并给出完整总结。
- 推荐方式：DevTools → Application → Cookies（更完整，含 httpOnly）；或 DevTools → Network 复制请求头 Cookie。
- 如果暂时不方便提供，我可以按公开可见页面先给“受限样本版”结论，并明确不确定性。

**第三步：** 收到凭据后保存并继续：
```bash
# 如果是 document.cookie 格式的字符串
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/zhihu_login.py" --import
# 粘贴 cookie 字符串，按回车

# 或直接在代码中解析并保存到 JSON
```

### 特别提示

- `document.cookie` **不包含** httpOnly cookie（如知乎的 `z_c0`）。页面浏览足够，但 API 翻页可能不够。
- 如果需要 httpOnly cookie，引导用户使用 **DevTools → Application → Cookies** 导出。
- 优先使用浏览器渲染模式（stealthy/dynamic）而非直接调 API，因为浏览器模式可利用已有 cookie 自动完成认证。
- 若用户提供的 cookie 不足以完成任务，再次使用 `ask_questions` 说明具体缺少哪个 cookie 及获取方式。

---

## 完整工作流（端到端）

> 当前技能的标准流程应理解为“完整调研工作流”。原先的“工作流 1~6”实际上只是其中的**抓取执行方式**，不应视为完整流程。

### 步骤 1：明确任务目标

先判断用户要的是哪一类结果：

- 只要单页内容
- 批量抓取多个网页
- 汇总某个机构 / 专栏 / 网站近期内容
- 对大量网页做主题分析
- 基于抓取结果撰写报告 / 摘要 / 一页纸

如果用户的时间范围、来源范围、输出格式不明确，应先澄清，再执行。

### 步骤 2：确认输出方式与目录策略

严格遵守上面的“执行前确认：输出与资产管理”。

**任何目录创建、过程资产保存、报告文件生成前，先确认。**

### 步骤 3：确认访问条件与凭据

判断目标站点是否：

- 有反爬保护
- 需要登录
- 需要滚动加载
- 需要 JavaScript 渲染
- 需要完整 Cookie 才能获取分页或详情

若需要凭据，按“凭据求助机制”执行，不要盲目重试。

硬门禁：

- 一旦命中认证阻断信号（401/403/login/need_force_login），立即停止抓取并求助用户。
- 在用户未提供凭据前，不得继续同 URL 抓取尝试。

### 步骤 4：制定抓取计划

对于大量网页任务，先制定抓取计划，而不是直接逐页乱抓。典型顺序：

1. 抓取列表页 / 机构主页 / 专栏主页
2. 提取标题、链接、发布时间等索引信息
3. 按时间范围或主题筛选目标文章
4. 批量抓取详情页
5. 保存原始 HTML、清洗文本和结构化数据

### 步骤 5：选择抓取执行方式

下面这些是**抓取执行方式**，属于步骤 4 的具体完成手段，而不是完整工作流。建议始终加 `--save-html` 保留原始证据。

#### 方式 A：单页绕过抓取（stealthy / dynamic）

默认用 `stealthy`；页面需要 JS 执行才能呈现内容时，切 `dynamic`：

```bash
# 默认：隐身抓取（适用于 Cloudflare / 反爬 / 鉴权站点）
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
  --url "<目标URL>" --method stealthy \
  --save-html "过程资产/html/page.html" \
  --output "过程资产/md/page.md"

# JS 重度渲染（stealthy 拿到的内容仍是骨架时改用）
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
  --url "<目标URL>" --method dynamic \
  --save-html "过程资产/html/page.html" \
  --output "过程资产/md/page.md"
```

#### 方式 B：批量 + 滚动抓取

批量多 URL、无限滚动分页、以及两者组合均用此方式；`--scroll N` 可附加在任何命令上：

```bash
# 批量抓取（JSON 列表提供 URL）
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
  --batch "<URL列表JSON>" --method stealthy \
  --save-html "过程资产/html/" \
  --output-dir "过程资产/md/"

# 单页无限滚动（加 --scroll N）
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
  --url "<目标URL>" --method stealthy --scroll 10 \
  --css "<选择器>" \
  --save-html "过程资产/html/page.html" \
  --output "过程资产/md/page.md"

# 批量 + 每页滚动（组合使用）
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
  --batch "<URL列表JSON>" --method stealthy --scroll 5 \
  --save-html "过程资产/html/" \
  --output-dir "过程资产/md/"
```

JSON 文件格式：
```json
[
  {"url": "https://example.com/page1", "name": "page1"},
  {"url": "https://example.com/page2", "name": "page2"}
]
```

### 步骤 6：结构化提取与清洗

抓取完成后，不要只保留原始网页内容。应继续提取并整理：

- 标题
- URL
- 发布时间
- 作者 / 来源（如能稳定提取）
- 正文摘要或前几段核心内容
- 主题标签（可按标题关键词或内容关键词粗分类）

常见结构化产物：

- `articles_raw.json`
- `articles_filtered.json`
- `articles_with_snippet.json`
- `articles_last_30_days.json`

必要时可以创建一次性脚本，对抓取结果做提取、过滤、去重、按时间筛选。

### 步骤 7：分析与归纳

当用户要求“总结”“分析”“调研”时，必须继续完成分析，而不是只交付数据。

如果需要分析的网页数量较多（例如数十到数百篇），在可用的情况下可使用 **sub-agent 并行处理** 来加速：

- 按主题、时间段或来源把数据切分为多个子任务
- 让不同 sub-agent 并行完成分类、摘要、关键信息提取
- 最后由主代理统一做去重、合并和一致性校验，形成单一结论

并行处理时要注意：

- 子任务输入口径一致（字段名、时间范围、分类标准）
- 输出格式统一（建议统一 JSON schema）
- 合并阶段必须做重复内容去重与冲突检查，避免“多代理多结论”

建议至少输出以下内容中的 2~4 项：

- 时间范围内的样本总量
- 主题分布
- 最新 / 最重要文章列表
- 高频趋势
- 重点公司 / 产品 / 技术方向
- 风险点 / 争议点 / 异常信号

### 步骤 8：撰写报告

当用户要求调研、总结、复盘、汇总时，应生成中文报告，而不只是贴数据。

推荐报告结构：

1. 调研范围与数据来源
2. 样本规模与时间范围
3. 核心观察
4. 主题分布 / 类别统计
5. 代表性文章列表
6. 内容摘要
7. 结论与建议
8. 方法说明与限制

如果用户需要更短版本，可继续生成：

- `一页纸.md`
- `摘要.md`
- `观察清单.md`

### 步骤 9：交付与复核

交付前必须检查：

- 报告是否真正基于抓取结果，而不是空泛总结
- 结构化文件是否可复用
- 过程资产路径是否正确
- 是否遗漏用户要求的时间范围 / 来源范围 / 报告形式

对于“汇总近期文章”“分析某站点最近内容”“批量抓取并总结”等大量网页任务，最低交付标准应为：

- 一个结构化列表文件（JSON）
- 一个过程资产目录（若用户允许创建目录）
- 一份中文总结报告

不要只返回“网页抓取成功”或单个 Markdown 文件。

### 步骤 10：执行后检查清单

每次执行完技能后：

- [ ] 检查输出内容是否包含预期信息（非空、非框架代码）
- [ ] 如遇到 `401/403/signin/login/need_force_login`，必须按「凭据求助机制」求助用户，**不得继续重试**
- [ ] 如涉及目录或文件保存，确认已按用户选择执行，而不是擅自创建目录
- [ ] 确认过程资产已保存（HTML / Markdown / data）
- [ ] 如用户要求分析或总结，确认已产出结构化数据和最终报告
- [ ] 检查 [LESSONS.md](LESSONS.md) 是否需要补充新的经验教训
- [ ] 如发现新的站点 CSS 选择器，更新 `fetch_page.py` 中的 `SITE_CONTENT_SELECTORS`

---

## 详细参考（参数 / 选择器 / 排障）

以下内容已迁移到独立文档，便于维护：

- [参数、选择器与排障参考](./reference-params-troubleshooting.md)

## 抓取方式选择指南

| 场景 | 方法 | 额外参数 |
|------|------|----------|
| 未知站点（默认起步） | `stealthy` | — |
| Cloudflare 保护站点 | `stealthy` | `--solve-cloudflare` |
| JS 渲染页面 | `dynamic` | — |
| 需要登录的页面 | `stealthy` | `--cookies`（自动查找） |
| 无限滚动分页 | `stealthy` | `--scroll N` |
| 需要调试 | 任意 | `--save-html 路径` |

## 执行后最低回复要求

执行本技能后，回复至少应包含：

- 做了哪些尝试（方法、URL、是否成功）
- 抓到哪些页面类型（列表页 / 详情页 / 活动流 / 公开首屏）
- 结构化结论（时间分布、主题、趋势、代表样本）
- 证据等级 A/B/C 和不确定性说明
- 若失败：阻断证据、失败回退已执行到哪一步、下一步最小可行方案