用途：把 PDF 报告、论文或扫描件转换为带页面结构的 Markdown，保留每页标题（## Page XX）和图片链接，便于导航、制作 PPT、构建可追溯数据集或做轻量归档。
主要能力：提取 PDF 可选中文字并归一化段落（合并换行），用字号启发式识别标题；输出单一 Markdown 文件，包含文档标题 # <filename> 与每页章节。图片提取支持三种模式：segment（默认，按页渲染分段块，适合表格和插图）、embedded（提取内嵌图片）、page（整页渲染为单图）。可选过滤：--filter-text 通过 OCR 去除文字密集图片；--filter-match 去除与页面文字匹配的截图；--filter-pdf-text 无需 OCR，按 PDF 版式去除与文字块重叠的图片。
使用方式：先运行 python scripts/extract_pdf.py --help 验证环境，再执行脚本并传入 --input、--output、--image-dir、--image-mode 及过滤参数。例如：python scripts/extract_pdf.py --input input.pdf --output output.md --image-dir images --image-mode segment --filter-text on --text-threshold 0.25 --text-lang eng --filter-match on --match-lang eng --match-min-len 30 --filter-pdf-text on --pdf-text-threshold 0.1。输出图片链接形如 。
适用场景：需要文字与页面截图/图块并存的转换；审阅扫描件或混合型 PDF 并过滤纯文字截图；构建每页文字与图片可关联的数据集。
限制：依赖 pdfplumber、pymupdf，pytesseract 仅在开启 --filter-text 或 --filter-match 时需要（版本均未指定）。缺少源文件、标识符或凭据时不应使用；不应生成编造结果。输出文件名建议为 pdf_extract_result.md，并附验证摘要说明假设与限制。