把网页变干净Markdown:Union-search-skill的defuddle正文提取完全教程
把网页变干净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,直接交给大模型精读。