| 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 经验教训文档，看是否需要补充新的经验。
何时使用本技能
触发词覆盖（中英关键词）
- 中文关键词：抓取网页、批量抓取、网页采集、反爬、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。
可判定触发条件
满足以下任一组合时，应该唤醒本技能：
- 站点 + 动作：用户给出 URL / 站点名，并要求抓取、采集、提取、汇总、分析、总结、追踪动态。
- 抓取 + 阻断：用户提到 403、被拦截、需要登录、Cloudflare、反爬、验证码、只有骨架屏、内容空白。
- 列表页 + 详情页：用户要先抓取列表，再递归抓取回答/文章/帖子详情并汇总。
- 时间范围 + 内容总结：用户要最近 1 周、1 个月、1 年、季度动态、近期文章、历史行为变化。
- 需要证据链：用户不仅要结论，还要 URL、抓取结果、结构化样本、证据等级或不确定性说明。
- 需要过程资产：用户要求保存 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 / 风控 / 登录受限）
按以下顺序执行，避免无效重试：
- 先证实是否真的被拦：
- 记录 URL、方法、状态码、页面关键特征（空白、登录页、骨架屏、验证码、need_force_login）。
- 保存一份原始 HTML 作为阻断证据。
- 先执行阻断判定（硬闸门）：
- 若命中
401/403/signin/login/need_force_login 任一信号，立即进入“向用户求助凭据”流程。
- 命中硬闸门后，不得继续同路径重试。
- 仅在未命中硬闸门时切换抓取方式：
stealthy → dynamic- 若页面需要加载更多内容，增加
--scroll N
- 若站点已知有正文选择器，优先加
--css
- 切换到浏览器态抓取：
- 遇 403、Cloudflare、空白 DOM 时，优先
stealthy 或 dynamic
- 需要更多列表数据时，优先浏览器滚动而不是直接调 API
- 加载现有 cookie：
- 自动查找
zhihu_cookies.json 等本地 cookie 资产
- 若已有 cookie，重试浏览器态抓取
- 最小可行替代：
- 若完整活动流不可得，退而抓取公开可见的回答页、文章页、主页首屏、搜索引擎快照或站内公开列表
- 明确标注覆盖范围不足、样本偏差和不确定性
- 最终阻断输出：
- 给出已尝试路径、阻断证据、下一步最小可行方案（例如用户提供完整 cookie 后继续）
常见阻断信号与动作
| 信号 | 可能原因 | 立即动作 |
|---|
| HTTP 401/403 | 风控 / 匿名访问受限 / 认证失败 | 保留 HTML 证据，立即转凭据求助 |
跳到 signin / login | 需要登录 | 终止重试，转凭据求助 |
| 页面只有导航/框架 | SPA 骨架 / 选择器不对 / 认证门槛 | 先判定是否命中认证阻断；命中则求助，否则改 dynamic 或加 --css |
API 返回 need_force_login | API 需要完整认证 | 停止 API 重试，转凭据求助 |
| 滚动后仍只有首屏少量内容 | 无限滚动请求被认证拦截 | 请求完整 cookie（含 z_c0）并停止盲重试 |
示例提示词（至少 10 条）
- 抓取这个知乎用户近 1 年动态并做主题总结：
https://www.zhihu.com/people/...
- 帮我批量采集这个专栏最近 30 篇文章，提取标题、时间、摘要，并输出中文报告。
- 这个站点直接访问 403，试试用浏览器隐身抓取并保存证据。
- Summarize the recent activity of this profile over the last year and show evidence links.
- Crawl this blog index plus all detail pages, then cluster topics into 5 categories.
- 把这个公众号最近一个月文章抓下来，按时间和主题整理成 JSON + Markdown。
- 这个页面是无限滚动，帮我加载更多内容并提取每条帖子链接。
- 抓取回答列表和文章列表，分析这个用户最近行为有没有变化趋势。
- 我需要网页证据链，不只要结论：请附 URL、抓取时间、证据等级和不确定性。
- If the site is login-gated, try accessible paths first and tell me the minimum cookie needed next.
- 帮我做一个站点调研：先抓列表页，再递归详情页，最后输出一页纸摘要。
- 提取这个 profile 的 answers / articles / thoughts / activity feed，并统计最近一年发文节奏。
执行产出模板
默认按以下结构组织最终输出；若用户要求更简短，可裁剪但不要丢掉证据等级与不确定性。
输出结构
- 任务概述：目标站点、时间范围、执行时间、抓取路径。
- 路径清单：尝试过的 URL / 方法 / 是否成功。
- 结构化样本：标题、时间、链接、内容摘要、来源类型。
- 分析结论：时间分布、主题聚类、高互动内容、行为变化趋势。
- 证据分级：A / B / C。
- 不确定性说明：缺失页面、登录限制、样本偏差、时间覆盖不足。
证据等级定义
| 等级 | 定义 | 典型例子 |
|---|
| A | 直接抓取到原始页面或官方公开页面，可复核 URL 与正文 | 公开回答页、公开文章页、抓到的活动流卡片 |
| B | 来自列表页摘要、站内搜索结果、页面片段或半结构化索引，信息较可靠但不完整 | 用户主页卡片、列表页标题+时间、公开摘要 |
| C | 间接线索或推断，需谨慎使用 | 页面骨架、搜索摘要、少量样本外推 |
不确定性模板
- 覆盖范围：本次仅覆盖公开可访问页面 / 首屏 / 部分列表，未必代表全部动态。
- 时间偏差：部分时间戳来自列表页展示，可能存在更新延迟或缺失。
- 互动偏差：若站点未公开完整赞同/评论数据，高互动判断只能基于可见指标。
- 结论强度：A 级证据支撑的结论可信度高；包含较多 B/C 级证据时，应视为趋势性判断。
前置条件
- Python 3.10+（推荐 Conda 环境）
- Scrapling：脚本会在首次运行时自动检测并安装（
pip install "scrapling[all]" + scrapling install）
- 如需手动安装或排查安装问题，请参考 快速部署指南
自动安装行为： fetch_page.py 启动时检测 import scrapling，若缺失则自动执行 pip install "scrapling[all]" 和 scrapling install（浏览器依赖）。无需人工干预。若自动安装失败，脚本会输出提示并退出，此时请按快速部署指南的踩坑记录排查。
📂 执行前确认：输出与资产管理
核心原则
在执行任何抓取、目录创建、过程资产保存或报告落盘之前，必须先确认输出和资产的保存方式。 不要假设用户需要创建文件夹、整理文件或生成报告目录——让用户决定。
确认时机
以下场景必须触发确认：
- 即将执行任何抓取任务，且会落盘文件
- 即将创建新目录、
过程资产/ 目录或报告目录
- 用户要求进行调研、批量收集、内容汇总、报告撰写
- 抓取结果将产生多个文件（HTML + Markdown + 数据 + 报告）
确认流程
在执行抓取之前，用一句话向用户确认以下四选一：
- 创建专用文件夹（推荐）
- 仅输出到当前目录
- 指定输出路径
- 仅输出到终端
若用户已有明确路径或已说明“不落盘”，则直接沿用，不必重复确认。
根据用户选择执行
跳过确认的情况
以下场景可直接执行：
- 用户已明确指定输出路径（如“保存到 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）
第二步： 询问用户并提供这四种获取方式：
- 浏览器
document.cookie（适合页面抓取）
- DevTools → Application → Cookies 导出（含 httpOnly，更完整）
- DevTools → Network → 复制请求头里的
Cookie
- 暂时跳过，接受受限样本继续分析
可直接复制的求助话术：
- 我这边已命中登录/鉴权阻断（
<401/403/signin/need_force_login>），继续重试会卡死。
- 请你提供
<Cookie/API Key/Token> 之一，我将继续抓取并给出完整总结。
- 推荐方式：DevTools → Application → Cookies（更完整，含 httpOnly）；或 DevTools → Network 复制请求头 Cookie。
- 如果暂时不方便提供，我可以按公开可见页面先给“受限样本版”结论，并明确不确定性。
第三步： 收到凭据后保存并继续：
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/zhihu_login.py" --import
特别提示
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：制定抓取计划
对于大量网页任务，先制定抓取计划，而不是直接逐页乱抓。典型顺序：
- 抓取列表页 / 机构主页 / 专栏主页
- 提取标题、链接、发布时间等索引信息
- 按时间范围或主题筛选目标文章
- 批量抓取详情页
- 保存原始 HTML、清洗文本和结构化数据
步骤 5：选择抓取执行方式
下面这些是抓取执行方式，属于步骤 4 的具体完成手段，而不是完整工作流。建议始终加 --save-html 保留原始证据。
方式 A：单页绕过抓取（stealthy / dynamic）
默认用 stealthy；页面需要 JS 执行才能呈现内容时，切 dynamic：
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
--url "<目标URL>" --method stealthy \
--save-html "过程资产/html/page.html" \
--output "过程资产/md/page.md"
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 可附加在任何命令上：
python "<workspace>/.github/skills/scrapling-web-fetch/scripts/fetch_page.py" \
--batch "<URL列表JSON>" --method stealthy \
--save-html "过程资产/html/" \
--output-dir "过程资产/md/"
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 文件格式：
[
{"url": "https://example.com/page1", "name": "page1"},
{"url": "https://example.com/page2", "name": "page2"}
]
步骤 6：结构化提取与清洗
抓取完成后，不要只保留原始网页内容。应继续提取并整理：
- 标题
- URL
- 发布时间
- 作者 / 来源（如能稳定提取）
- 正文摘要或前几段核心内容
- 主题标签（可按标题关键词或内容关键词粗分类）
常见结构化产物：
articles_raw.jsonarticles_filtered.jsonarticles_with_snippet.jsonarticles_last_30_days.json
必要时可以创建一次性脚本，对抓取结果做提取、过滤、去重、按时间筛选。
步骤 7：分析与归纳
当用户要求“总结”“分析”“调研”时，必须继续完成分析，而不是只交付数据。
如果需要分析的网页数量较多（例如数十到数百篇），在可用的情况下可使用 sub-agent 并行处理 来加速：
- 按主题、时间段或来源把数据切分为多个子任务
- 让不同 sub-agent 并行完成分类、摘要、关键信息提取
- 最后由主代理统一做去重、合并和一致性校验，形成单一结论
并行处理时要注意：
- 子任务输入口径一致（字段名、时间范围、分类标准）
- 输出格式统一（建议统一 JSON schema）
- 合并阶段必须做重复内容去重与冲突检查，避免“多代理多结论”
建议至少输出以下内容中的 2~4 项：
- 时间范围内的样本总量
- 主题分布
- 最新 / 最重要文章列表
- 高频趋势
- 重点公司 / 产品 / 技术方向
- 风险点 / 争议点 / 异常信号
步骤 8：撰写报告
当用户要求调研、总结、复盘、汇总时，应生成中文报告，而不只是贴数据。
推荐报告结构：
- 调研范围与数据来源
- 样本规模与时间范围
- 核心观察
- 主题分布 / 类别统计
- 代表性文章列表
- 内容摘要
- 结论与建议
- 方法说明与限制
如果用户需要更短版本，可继续生成：
步骤 9：交付与复核
交付前必须检查：
- 报告是否真正基于抓取结果，而不是空泛总结
- 结构化文件是否可复用
- 过程资产路径是否正确
- 是否遗漏用户要求的时间范围 / 来源范围 / 报告形式
对于“汇总近期文章”“分析某站点最近内容”“批量抓取并总结”等大量网页任务，最低交付标准应为：
- 一个结构化列表文件（JSON）
- 一个过程资产目录（若用户允许创建目录）
- 一份中文总结报告
不要只返回“网页抓取成功”或单个 Markdown 文件。
步骤 10：执行后检查清单
每次执行完技能后：
详细参考（参数 / 选择器 / 排障）
以下内容已迁移到独立文档，便于维护：
抓取方式选择指南
| 场景 | 方法 | 额外参数 |
|---|
| 未知站点（默认起步） | stealthy | — |
| Cloudflare 保护站点 | stealthy | --solve-cloudflare |
| JS 渲染页面 | dynamic | — |
| 需要登录的页面 | stealthy | --cookies（自动查找） |
| 无限滚动分页 | stealthy | --scroll N |
| 需要调试 | 任意 | --save-html 路径 |
执行后最低回复要求
执行本技能后，回复至少应包含：
- 做了哪些尝试（方法、URL、是否成功）
- 抓到哪些页面类型（列表页 / 详情页 / 活动流 / 公开首屏）
- 结构化结论（时间分布、主题、趋势、代表样本）
- 证据等级 A/B/C 和不确定性说明
- 若失败：阻断证据、失败回退已执行到哪一步、下一步最小可行方案
