把网页变干净Markdown:Union-search-skill的defuddle正文提取完全教程

原创2026-10-29 13:40:061,419 阅读

把网页变干净Markdown:Union-search-skill的defuddle正文提取完全教程

union-search-skill 是一款面向 AI 工作流的多平台搜索技能,除了"一次搜索 51 个渠道"之外,它还内置了 defuddle 正文提取 能力:把任意网页 URL 变成只含正文的干净 Markdown,自动移除导航栏、广告、侧边栏等干扰元素,并提取标题、作者、发布时间等元数据。本文带你从零安装到批量处理,5 分钟上手这个本地运行的网页转 Markdown 工具。

为什么需要网页正文提取

把网页喂给大模型或知识库时,原始 HTML 里混杂着大量"噪音":

  • 🧩 导航菜单、页脚、相关推荐
  • 📢 广告与悬浮按钮
  • 🎨 样式脚本与无关图片

噪音会让模型上下文白白膨胀。defuddle 引擎会识别页面的正文区域,输出 LLM 友好的 Markdown,同时保留结构化元数据,是"搜索 → 阅读原文"流程中的关键一环。

defuddle 在 union-search-skill 中的定位

正文提取模块采用双引擎架构(详见 scripts/url_to_markdown/README.md):

引擎 类型 优先级 特点
Jina AI 在线 API 首选 快速、稳定、支持动态页面,免费版有 20 RPM 限流
Defuddle 本地运行 备选 完全免费、无速率限制、隐私友好,需 Node.js

两者的自动降级逻辑是:先尝试 Jina,失败后自动切换到本地 Defuddle 兜底,保证高频批量处理不会卡在线程限流上。

一键安装:只需 2 条命令

defuddle 需要 Node.js 18+ 和 npm,依赖通过 npm 包固定版本(defuddle@0.10.0),新克隆后执行一次即可恢复完整运行时。

先获取项目(若你还没有本地副本):

git clone https://gitcode.com/gh_mirrors/un/union-search-skill

然后在仓库根目录执行:

npm install
npm --prefix scripts/url_to_markdown/engines/defuddle-node ci

第二条命令会从 package-lock.json 安装锁定版本的 Defuddle CLI。验证是否就绪:

node scripts/url_to_markdown/engines/defuddle-node/node_modules/defuddle/dist/cli.js --version

能打印版本号,说明安装成功 ✅

最快上手:一条命令提取正文

统一 CLI 入口是 union_search_cli.py,defuddle 是专门的正文提取子命令:

# 提取正文,保存为 Markdown 文件
python union_search_cli.py defuddle "https://example.com" --format markdown -o out/article.md

# 查看 JSON 结果(含完整元数据)
python union_search_cli.py defuddle "https://example.com" --json --pretty

保存文件时,-o 会自动创建目标目录;提取失败会返回 PLATFORM_FAILURE 并以退出码 4 结束,方便脚本判断。

常用参数速查表

参数 作用
url(位置参数)或 --url 要提取的网页地址,同时提供时位置参数优先
--json 让提取引擎返回完整元数据(作者、发布时间、favicon 等)
--format json|markdown|text 控制外层输出格式,Markdown 模式下只呈现标题和正文
-o FILE 结果写入文件
--timeout N 超时秒数,默认 60,应用于每次子进程调用

成功结果的 data 字段包含 url、title、content、markdown、description、domain 和 adapter_timing_ms;加 --json 后还会返回 favicon、image、author、published、meta_tags。

进阶:用 Python API 启用双引擎自动降级

命令行 defuddle 直接调用本地引擎;如果你希望"Jina 优先、失败自动降级",可以用 scripts/url_to_markdown/url_to_markdown.py 提供的高级接口:

from scripts.url_to_markdown import UrlToMarkdown

# 自动模式:优先 Jina,失败时用 Defuddle 兜底
client = UrlToMarkdown()
result = client.fetch("https://example.com/article")
print(result["title"])
print(result["_engine_used"])  # 实际使用的引擎:"jina" 或 "defuddle"

# 高频批量处理场景:只用 Defuddle,彻底告别速率限制
client_def = UrlToMarkdown(prefer_engine="defuddle", enable_fallback=False)

fetch 还支持 with_images、target_selector(只提取指定区域)、no_cache 等参数,完整说明见 scripts/url_to_markdown/README.md。

Defuddle 引擎本身也可以独立调用,核心实现在 scripts/url_to_markdown/engines/defuddle_engine.py,它通过子进程执行 Node.js 版的 Defuddle CLI 完成解析,并自带 fetch_batch 批量方法,单个 URL 失败会记录错误而不中断整个批次:

from scripts.url_to_markdown.engines.defuddle_engine import DefuddleEngine

client = DefuddleEngine()
results = client.fetch_batch(["https://a.com", "https://b.com"])

故障排查:3 个常见报错一次讲清

报错 原因 解决办法
Defuddle CLI not found npm 依赖未安装 在根目录重新执行 npm --prefix scripts/url_to_markdown/engines/defuddle-node ci
Node.js not found 系统缺少 Node 运行时 安装 Node.js 18+(macOS 可用 brew install node,Linux 用 apt install nodejs npm)
All engines failed 双引擎全部失败 检查网络、确认 URL 可访问、验证 Node.js 是否就绪

更多诊断建议可参考 references/troubleshooting.md,CLI 全局约定(JSON 信封、退出码)见 scripts/cli/README.md。

相关文件导航

文件 说明
union_search_cli.py 统一命令行入口
scripts/url_to_markdown/README.md 双引擎架构与批量处理最佳实践
scripts/url_to_markdown/engines/defuddle/README.md Defuddle 引擎说明与版本更新方法
scripts/url_to_markdown/engines/defuddle/defuddle_cli.py 可独立运行的 Defuddle CLI 包装器
scripts/cli/README.md defuddle 子命令完整参数与机器契约
README.md 项目总览,含依赖安装与渠道一览

掌握以上命令后,"搜索 → 定位文章 → 提取干净正文"的完整闭环就搭好了:先用 search 命令多渠道找资料,再用 defuddle 把原文链接变成干净的 Markdown,直接交给大模型精读。

登录后查看全文
union-search-skill