Web Content Extraction

Web Content Extraction Skill（网页内容提取技能）

一个完整的网页内容获取方案矩阵，针对不同类型网页提供最优提取策略。新增 Brave Search 支持：搜索发现 + 快速摘要。

🚀 快速开始（推荐）

现在本技能包含可执行脚本，无需手动编写代码：

方法1：使用 extract.py（自动选择最佳策略）

# ===== 提取模式（URL → 内容）=====

# 自动提取（智能降级：brave → jina → defuddle → requests → curl → playwright）
python scripts/extract.py "https://example.com/article"

# 使用 Brave 快速摘要（需 BRAVE_API_KEY，速度最快）
python scripts/extract.py "https://example.com/article" --method brave

# Markdown 输出（保存到 ~/Downloads/，自动根据标题生成文件名）
python scripts/extract.py "https://example.com/article" --format md

# Markdown 输出 + 指定路径
python scripts/extract.py "https://example.com/article" --format md -o ~/Documents/my-article.md

# ===== 搜索模式（关键词 → URL 列表）=====

# Brave Search 搜索发现（需 BRAVE_API_KEY）
python scripts/extract.py --search "Claude Code 最佳实践"

# 搜索并保存结果
python scripts/extract.py --search "AI Agent 架构" -o search_results.json

环境变量配置：

# 配置 Brave API Key（用于 L0 摘要和搜索模式）
export BRAVE_API_KEY="your-brave-api-key"

输出格式（JSON）：

{
  "success": true,
  "method": "requests",
  "title": "文章标题",
  "author": "作者名",
  "content": "正文内容...",
  "url": "最终URL"
}

输出格式（Markdown）：

# 文章标题

**作者**: 作者名 | **来源**: https://example.com/article | **提取方式**: requests

---

正文内容...

方法2：安装依赖（首次使用）

bash scripts/setup.sh

📋 使用决策流程

🔧 可用脚本

9层提取策略详解

各层适用场景与实战指南

选择策略

场景1：你有具体 URL

• 配置 BRAVE_API_KEY → 优先 L0（最快）
• 未配置 → 从 L1 开始自动降级

场景2：只有主题/关键词

• 使用 --search 搜索发现，获取 URL 后再进入提取流程

场景3：特定网站

• GitHub/Reddit/YouTube → L2 defuddle（有专用提取器）
• 微信公众号 → L1 jina.ai（最强）
• 知乎 → L0 Brave（索引已收录）或 L5 Playwright
• 小红书/抖音 → L5 Playwright（截图+视觉提取）
• 付费内容（Every.to/Substack）→ L1 jina.ai（绕过付费墙）

快速决策表

提取模式（URL → 内容）

搜索模式（关键词 → URL 列表）

其他工具

使用顺序建议

自动模式（配置 BRAVE_API_KEY 后）：

尝试内置工具（WebFetch）
    ↓ 失败或受限
使用 Brave（L0 - 快速摘要，适合热门网页）
    ↓ 未收录或摘要不足
使用 jina.ai（L1 - 免费快速，绕过付费墙）
    ↓ jina 失败或内容不完整
使用 defuddle（L2 - 智能正文识别，GitHub/Reddit/YouTube 等有专用提取器）
    ↓ defuddle 失败（JS 渲染页面等）
使用 requests（L3 - 本地解析，最灵活）
    ↓ 简单备用方案
使用 curl（L4 - 轻量快速）
    ↓ 需要执行JS
使用 Playwright（L5 - 动态渲染兜底）

未配置 BRAVE_API_KEY：

从 L1 jina.ai 开始自动降级

执行步骤

Step 1: 尝试 WebFetch（最简单）

如果用户提供 URL，首先尝试 WebFetch 获取内容。

成功？ → 完成任务 失败（安全限制）？ → 进入 Step 2

Step 2: 使用 extract.py 脚本（推荐）

直接调用封装好的提取脚本：

# 自动模式（推荐）- 按 L0→L1→L2→L3→L4→L5 自动降级
python scripts/extract.py "<URL>" -o result.json

# 指定使用 jina.ai（最快，适合大多数网页）
python scripts/extract.py "<URL>" --method jina

# 指定使用 requests（需要结构化信息时）
python scripts/extract.py "<URL>" --method requests

脚本特点：

• ✅ 9层自动降级：brave → jina → defuddle → requests → curl → playwright
• ✅ L0 Brave 摘要：配置 API key 后速度最快，适合热门网页
• ✅ 搜索发现模式：--search 关键词直接获取相关 URL 列表
• ✅ L1 jina.ai：免费、免 API key、绕过付费墙
• ✅ 双输出格式：JSON（结构化数据）或 Markdown（可读文档）
• ✅ Markdown 模式自动保存到 ~/Downloads/（基于文章标题生成文件名）
• ✅ 自动处理编码问题（UTF-8/GBK）
• ✅ 内置多种正文提取策略（含微信公众号优化选择器）

解析结果：

# 读取结果
cat result.json

# 提取标题
python -c "import json; d=json.load(open('result.json')); print(d['title'])"

# 提取正文
python -c "import json; d=json.load(open('result.json')); print(d['content'])"

脚本失败？ → 进入 Step 3 手动处理

Step 3: 手动选择工具（备用方案）

当脚本无法满足需求时，根据网页类型选择工具：

技术判断：

• 网页是否需要登录？→ Python requests + Cookie
• 内容是否为 JavaScript 动态生成？
  • 源代码中没有 → Playwright
  • 源代码中有 → curl 或 Python requests
• 网页编码是什么？
  • GB2312/GBK → 需要 iconv -f gb2312 -t utf-8

具体命令和代码见 references/toolkit.md

Step 4: 特殊情况处理

扩展 extract.py： 如需添加新的提取策略，编辑 scripts/extract.py：

• 添加新方法函数（如 extract_with_new_method）
• 在 extract_url() 的 methods 列表中加入新方法
• 测试并提交更新

详细处理方案见 references/toolkit.md

工具选择速查

提取场景（URL → 内容）

搜索场景（关键词 → URL）

其他工具

失败处理流程

自动流程（使用 extract.py）

提取模式（URL → 内容）：

WebFetch 失败
    ↓
python scripts/extract.py "URL" --method auto
    ↓
├── brave 尝试 ──→ 成功 ✅ （L0：快速摘要，需 BRAVE_API_KEY）
│
├── jina.ai 尝试 ──→ 成功 ✅ （L1：免费快速，适合大多数网页）
│
├── defuddle 尝试 ──→ 成功 ✅ （L2：智能正文识别，GitHub/Reddit/YouTube 等有专用提取器）
│
├── requests 尝试 ──→ 成功 ✅ （L3：结构化提取，需作者/标题信息时）
│
├── curl 尝试 ──→ 成功 ✅ （L4：备用方案）
│
├── playwright 尝试 ──→ 成功 ✅ （L5：JS动态页面，兜底方案）
│
└── 全部失败 ──→ 返回错误信息 ❌

搜索模式（关键词 → URL 列表）：

python scripts/extract.py --search "关键词"
    ↓
└── Brave Search API ──→ 返回搜索结果列表 ✅

手动流程（extract.py 失败时）

extract.py 失败
    ↓
查看 result.json 中的 error 详情
    ↓
根据错误类型选择：
    - 编码问题 → 修改 extract.py 的 encoding 处理
    - 需要登录 → 添加 Cookie/Session
    - JS 渲染失败 → 调整 Playwright 等待时间
    - 反爬机制 → 添加代理/延时

参考资源

• 详细工具手册: references/toolkit.md - 包含 curl、Python、Playwright、wget 的完整命令和代码示例
• 实战案例: 见原技能文档 skills/web-content-extraction-cases.md（如存在）

更新日志

• 2026-02-03 v1.0: 初始版本，整合 curl/Python/Playwright/wget 方案
• 2026-02-03 v1.1: 添加内置工具和 MCP 工具，形成完整 7 层工具矩阵
• 2026-02-09 v1.2: 重构为渐进式披露结构，拆分详细内容到 references/
• 2026-02-15 v2.0: 🎉 重大更新 - 增加可执行脚本层
  • 新增 scripts/extract.py: 统一提取接口，自动策略降级
  • 新增 scripts/setup.sh: 一键安装依赖
  • 内置编码自动检测（UTF-8/GBK）
  • JSON 结构化输出，便于其他 skills 调用
  • 支持微信公众号等受限域名提取
• 2026-02-26 v2.1: 🚀 添加 jina.ai L0 层
  • 将 jina.ai Reader 作为第 0 层快速提取方案
  • 自动降级顺序：jina → requests → curl → playwright
  • 免费、免 API key、绕过付费墙、返回干净 Markdown
  • 对标 OpenClaw 中推荐的 jina.ai 配置方案
• 2026-02-26 v2.2: 📝 添加 Markdown 输出模式
  • 新增 --format md 参数，支持输出可读 Markdown 文件
  • 自动生成文件名（基于文章标题或域名）
  • Markdown 格式包含标题、元信息、正文，适合直接阅读
• 2026-02-26 v3.0: 🔍 集成 Brave Search API
  • 新增 L0 层 Brave 快速摘要：配置 API key 后速度最快
  • 新增 搜索发现模式：--search 参数从关键词获取 URL 列表
  • 自动降级链更新：brave → jina → requests → curl → playwright
  • 通过 BRAVE_API_KEY 环境变量配置
• 2026-03-09 v3.1: 🧠 集成 defuddle 智能提取层
  • 新增 L2 层 defuddle（npm CLI）：基于评分算法的正文识别
  • 内置站点专用提取器：GitHub/Reddit/Twitter/YouTube/ChatGPT/Claude/Gemini/HackerNews
  • 输出原生 Markdown + 丰富元数据（wordCount/image/published 等）
  • 降级链更新：brave → jina → defuddle → requests → curl → playwright
  • 前置条件：npm install -g defuddle jsdom