网页秒变Markdownpi-skills内容提取管线Readability、JSDOM与Turndown原理解密【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skillspi-skills 是面向 pi coding agent 的技能集合兼容 Claude Code 与 Codex CLI其中的内容提取管线可以用一句话概括把任意网页秒变干净、结构化的 Markdown 文本。它由三大开源引擎接力完成——Mozilla 的 Readability 负责找出正文JSDOM 提供无浏览器的 HTML 环境Turndown 负责把 HTML 翻译成 Markdown。本文带你完整拆解这条管线的原理与实现。三大引擎各司其职管线全景内容提取的核心代码位于 browser-tools/browser-content.js无浏览器场景的实现则在 brave-search/content.js。整个管线像一条流水线三个工具各有分工工具角色一句话原理JSDOM环境底座在 Node.js 中模拟浏览器 DOM让纯 JS 库可以读懂网页Readability正文猎手用启发式评分算法从整页 HTML 中剥离出正文内容Turndown格式翻译官将 HTML 节点逐层转换为 Markdown 语法网页 HTML ──▶ JSDOM构建 DOM──▶ Readability提取正文──▶ Turndown转 Markdown │ └─ 失败 ──▶ 兜底策略选择 main/article 主容器依赖版本可在 browser-tools/package.json 中查看例如mozilla/readability ^0.6.0、jsdom ^27.0.1、turndown ^7.2.2。第一步JSDOM——在 Node 里造一个浏览器网页是 HTML 文本但 Readability 需要的是一个活的 DOM 树。JSDOM 的作用就是这一步const doc new JSDOM(outerHTML, { url: finalUrl });相关实现见 browser-content.js 第58-61行。传入 HTML 字符串和原始 URL用于解析相对链接后JSDOM 在内存中构建出完整的文档对象模型doc.window.document就是一个可直接操作的标准 DOM。为什么需要它因为 Readability 原本是 Firefox 浏览器内的原生算法而 pi-skills 的脚本运行在无头 Node 环境JSDOM 就是连接两者的桥梁。第二步Readability——正文猎手的评分算法网页上除了正文还塞满了导航栏、侧边栏、广告、评论区……Readability 的核心任务是只留下正文。它的思路是启发式评分按块切割把p、div、section等元素切成候选块综合打分文字密度高的块加分类名/ID 含comment、footer、sidebar的块减分含article、content、body的块加分选出最优祖先取得分最高块所在的公共祖先容器整体输出为article.content。在 content.js 第51-60行 可以看到调用方式极其简洁——三行代码就拿到正文 HTML 和文章标题const reader new Readability(dom.window.document); const article reader.parse();第三步Turndown——HTML 到 Markdown 的精确翻译拿到正文 HTML 后Turndown 接管翻译工作。它不是简单的正则替换而是遍历 DOM 树、按节点类型匹配规则h1变#、strong变**、table变 GFM 表格……项目中的转换配置见 browser-content.js 第64-79行有几个值得注意的细节GFM 插件turndown.use(gfm)让表格、删除线等 GitHub 风格语法正确转换ATX 标题headingStyle: atx输出# 标题而非老式标题 围栏代码块codeBlockStyle: fenced使用风格自定义清理规则空链接a无文字直接移除避免产生[]()噪声正则后处理压缩多余空格、合并三连换行让输出更紧凑。容错设计Readability 失败时的兜底策略并不是每个网页都有标准正文——落地页、SPA 页面常让 Readability 返回空。pi-skills 为此设计了两级兜底逻辑见 browser-content.js 第84-96行级别策略效果一级Readability 解析适用于绝大多数文章页二级移除script/nav/footer等噪声节点按main article [rolemain] .content优先级找主容器覆盖非文章结构的页面三级若主容器文字少于 100 字符输出(Could not extract content)明确失败不产生垃圾输出这种优雅降级让 Agent 在网页格式千变万化的真实场景下依然稳定工作。两种调用场景带浏览器 vs 纯抓取pi-skills 用同一套三件套实现了两条管线应对不同需求场景一需要 JavaScript 渲染的页面browser-tools/SKILL.md 中的browser-content.js命令流程是browser-start.js启动带远程调试端口的 Chrome:9222通过 CDP 协议导航到目标 URL 并等待networkidle2JS 渲染完成用DOM.getOuterHTML拿到渲染后的完整 HTML再进入 JSDOM → Readability → Turndown 管线。这正是网页秒变 Markdown对动态页面也有效的原因——先让浏览器把 JS 跑完再提取。场景二轻量静态抓取brave-search/search.js 的--content模式则直接fetch网页带 10 秒超时不启动浏览器速度快得多每条结果还截断到 5000 字符方便喂给 AI 上下文。brave-search/SKILL.md 给出了完整用法说明。上手体验三步跑通提取管线如果你想在 pi-skills 中体验这条管线只需三步安装依赖进入 browser-tools/ 目录执行npm install一次性启动浏览器可选动态页面才需要运行browser-start.js执行提取运行browser-content.js 网页URL几秒后终端就会输出标题 干净的 Markdown 正文。⚡ 小技巧对静态文档页如技术文档、博客直接使用 brave-search/content.js 更快——无需浏览器一次 HTTP 请求即可完成提取。总结为什么这条管线值得学习pi-skills 的内容提取管线是一个教科书级的小而美设计三条经验值得借鉴组合优于自研JSDOM Readability Turndown 三个成熟引擎各司其职核心逻辑不足百行永远要有兜底Readability 失败时的降级策略是真实场景稳定性的关键为 AI 输出而格式化ATX 标题、GFM 表格、空行压缩——每一步后处理都为了让 Markdown 更贴近 AI 的阅读习惯。下次你需要把网页喂给大模型时不妨参考这套管线先渲染、再定位正文、最后翻译成 Markdown三步走又快又干净。【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考