从 PDF 到 Markdown：insane-search 内容救援管线的 6 种智能提取策略-港品优选

从 PDF 到 Markdown：insane-search 内容救援管线的 6 种智能提取策略

【免费下载链接】insane-searchAuto-bypass for blocked websites in Claude Code — Phase 0→3 adaptive scheduler, no API keys项目地址: https://gitcode.com/gh_mirrors/in/insane-search

当抓取工具拿到一个页面后，"拿到字节"只是第一步。insane-search（GitHub 加速计划 / in / insane-search）的内容救援管线会判断返回内容的真实形态——PDF 二进制、JSON-LD 结构化文章、广告堆砌的 HTML、还是空壳 SPA——并从6 种智能提取策略中选出最合适的一种，把原始字节变成干净、可用的 Markdown 文本，全程无需任何 API 密钥。

为什么需要"救援"？

默认抓取经常拿到"能访问但没法用"的结果：

服务器返回的是PDF 二进制，直接读只会看到乱码；
页面是SPA 空壳，可见文本只有几十个字符，真正的正文藏在 JSON-LD 里；
HTML 能读，但导航、侧栏、广告占了八成篇幅；
浏览器渲染出的innerText反而比原始 HTML 更完整。

insane-search 的救援逻辑集中在 fetch_chain.py 的_extract_response函数中：默认以原始正文为准，只有当某条救援路径能产出更优结果时才替换。每条路径都有严格边界（扫描前缀、页数上限、文本长度上限），防止超大文件拖垮流程。

6 种提取策略逐个拆解

策略 1｜`raw`：原始正文兜底

抓到的 HTML 文本先原样保留，这是最保守也最可靠的基线。所有救援策略都遵循同一个原则：产出的文本质量分不高于原始文本时，绝不替换。质量分由可见文本长度、主题相关性等信号综合得出。

策略 2｜`pdf`：双解析器抢救 PDF

这是从 PDF 到 Markdown 文本的核心路径（fetch_chain.py 的_extract_pdf）：

魔数检测：响应头说是 HTML、实际却是%PDF-开头？照样识别为 PDF；
pdfplumber 优先：多栏排版、表格还原效果更好；
pypdf 兜底：前者没产出文本时再试 pypdf；
边界保护：最多处理 80 页、文本总量封顶，扫描件会如实报告pdf_no_text_layer而不是假装成功。

v0.16.3 起 PDF 解析器还是延迟加载的——普通 HTML 抓取完全不会为此付出启动开销（见 CHANGELOG.md）。

策略 3｜`json_ld`：从 JSON-LD 里挖出正文

很多新闻站和博客把完整正文写进<script type="application/ld+json">的articleBody字段，而页面可见文本反而很短。_extract_json_ld_text会解析 Article / NewsArticle / BlogPosting 类型的块，提取articleBody或description。只有当 JSON-LD 文本明显长于可见文本时才启用，避免误伤正常页面。

策略 4｜`maincontent`：只留正文，剥离广告

通过可选的 resiliparse 库把导航、页脚、侧栏、广告等模板内容全部剥掉，同时保留列表和排版结构。结果太薄（达不到最小字符数）时自动放弃并保留原始 HTML。该策略需显式开启，且优先级高于 Markdown 转换。

策略 5｜`raw+md`：HTML 转结构保持的 Markdown

对原始 HTML 路径，markdownify 会把网页转成保留结构的 Markdown：标题变 ATX 格式、表格变管道表格、<pre>/代码块变围栏代码块，并预先清掉 script/style 等噪声。转换失败则回退原文——对调用方的契约永远是"至少拿回原始内容"。

策略 6｜`render-merge`：浏览器 innerText 合并

走到 Phase 3 真实无头浏览器时（见 fallback.md 的升级流程），渲染后的innerText往往比原始 HTML 的可见文本更完整。管线会把两者与可见文本长度对比（而不是与带标记的 HTML 比——那样标记版永远占优），浏览器版本更长时合并进正文，来源标记为xxx+inner_text。

一次抓取的完整标记

每次抓取结果都会携带三样"诊断信息"，无需重复抓取即可回溯：

字段	作用
`extraction_source`	标记正文由哪条路径产出：`raw`、`pdf`、`json_ld`、`maincontent`、`raw+md`、`…+inner_text`
`extraction_quality`	0–1 质量分，供上层判断内容是否够用
`trace`	每一次尝试（URL 变体 × TLS 指纹 × Referer × 执行器）的完整记录

所有相关行为都有对应测试保障，例如 PDF 延迟加载（test_lazy_pdf.py）、Markdown 转换（test_t3_markdown.py）、主内容剥离（test_t4_maincontent.py）与差分分类（test_t6_differential.py）。

企业官网建设流程全解析