Markdown 转换

将任意支持的来源——文件、目录或 URL——转换为干净的 Markdown。每个输入生成一个 .md 文件（默认会一并提取图片到 <stem>_files/）。

标准化输出契约

本技能的输出是面向下游 PPT / Word / 学习笔记等流程的“可读 Markdown 层”，而不是原始文件的版式复刻。所有转换器遵循同一套约定：

格式边界：

• Markdown 层优先服务“内容理解”和“再生成”，不承诺保留原始页边距、动画、主题、版式坐标。
• Office 向量资源（如 EMF / WMF）如果被后端抽取，应作为资产保留；不应默认栅格化为 PNG。
• 网页下载图片的版权 / 授权状态不由转换器判断；正式交付前需要单独审查来源。

设计理念：两个正交维度

维度 A：还原力度
  默认       = 自然转换（应用合理的清理：网页正文识别、PDF 页眉页脚去重、字幕段落锚点）
  --raw      = 完美还原（关闭所有启发式清理，保留原始结构）

维度 B：图片处理（互斥三选一）
  默认           = 全部保留
  --filter-images = 过滤装饰图（logo、追踪像素、母版背景、低信息密度色块、重复图）
  --no-images    = 完全不抽图，Markdown 里也不留 ![](...) 引用

两个维度可自由组合。没有套装预设——每个旗只管一件事，组合可叠加。

快速开始

统一调度器会自动识别输入类型，可一次传入一个或多个文件 / URL / 目录：

python3 scripts/convert.py <文件或URL> [<文件或URL> ...]

默认输出：<输入目录>/<文件名>.md。 本地单文件可用 -o <output.md> 指定输出路径；多输入或目录输入时，-o 为输出目录。 调度器成功后会打印 OUTPUT: /绝对路径/output.md。

# 默认：自然转换 + 图全保留（最常用）
python3 scripts/convert.py paper.pdf                       # PDF（本地 PyMuPDF）
python3 scripts/convert.py paper.pdf --mineru              # PDF（MinerU 云端 OCR）
python3 scripts/convert.py report.docx                     # Word
python3 scripts/convert.py data.xlsx                       # Excel
python3 scripts/convert.py deck.pptx                       # PowerPoint
python3 scripts/convert.py book.epub                       # EPUB
python3 scripts/convert.py https://example.com/post        # 网页（trafilatura 正文识别）
python3 scripts/convert.py paper.pdf report.docx deck.pptx # 多来源批量
python3 scripts/convert.py ./course_dir -t sub             # 字幕批量（含段落锚点）
python3 scripts/convert.py ./mixed_docs                    # 目录批量
python3 scripts/convert.py report.docx --json              # 额外打印机器可读 JSON 结果

# 完美还原（关闭启发式清理）
python3 scripts/convert.py paper.pdf --raw                 # 保留页眉页脚，不识别标题层级
python3 scripts/convert.py https://example.com --raw       # 保留导航/侧栏/footer
python3 scripts/convert.py lecture.srt --raw               # 字幕回到单行拼接

# 图片处理
python3 scripts/convert.py paper.pdf --filter-images       # 过滤装饰图（保留信息图）
python3 scripts/convert.py paper.pdf --no-images           # 纯文本

# 组合
python3 scripts/convert.py paper.pdf --raw --no-images     # 完美还原 + 纯文本

各后端的"清理"具体指什么

批量目录转换

convert.py 接受目录参数，转换其中所有支持的文件（一层深度）。每个文件由对应转换器处理，输出为 <文件名>.md（或写入 -o 指定目录）。

python3 scripts/convert.py ./mixed_docs               # 原位转换每个文件
python3 scripts/convert.py ./mixed_docs -o ./out      # 所有 .md 写入 ./out/

批量模式在单文件失败后继续运行，最后打印成功 / 失败 / 跳过计数。

超大 PDF（书籍/长报告）可先用 pdftk、qpdf 或 PyPDF2 拆分再转换——单个 PDF 超过约 200 页时转换器也会提示。

支持的来源

.xls 和旧版 .ppt 不直接解析——请先另存为 .xlsx / .pptx。.doc 通过 pandoc 回退处理。

直接调用转换器

convert.py 是推荐入口，但每个后端也可作为独立 CLI 使用：

python3 scripts/pdf_to_md.py book.pdf                         # 默认自然转换
python3 scripts/pdf_to_md.py book.pdf --filter-images         # 过滤装饰图
python3 scripts/pdf_to_md.py book.pdf --raw                   # 完美还原
python3 scripts/pdf_to_md.py book.pdf --render-vector-figures # 显式渲染矢量图区域
python3 scripts/pdf_to_md_mineru.py scan.pdf                  # 需要 MINERU_API_TOKEN
python3 scripts/pdf_to_md_mineru.py scan.pdf --no-images
python3 scripts/doc_to_md.py paper.tex                        # 使用 pandoc
python3 scripts/doc_to_md.py report.docx --filter-images
python3 scripts/excel_to_md.py report.xlsm --max-rows 200 --max-cols 40
python3 scripts/ppt_to_md.py deck.pptx --filter-images        # 过滤母版背景/装饰
python3 scripts/web_to_md.py https://example.com              # 默认 trafilatura 正文识别
python3 scripts/web_to_md.py https://example.com --raw        # 关闭正文识别（保留 nav/footer）
python3 scripts/subtitle_to_md.py lecture.srt                 # 默认段落 + Block 锚点
python3 scripts/subtitle_to_md.py lecture.srt --raw           # 单行拼接（旧行为）

每个脚本输出 <输入>.md 及嵌入图片的 <输入>files/，Markdown 中使用相对路径引用。支持图片 manifest 的后端会额外写入 <输入>files/imagemanifest.json，用于下游判断图片尺寸、来源和出现位置。成功转换会写入 <stem>.conversionprofile.json；统一调度器还支持 --json 打印机器可读结果。 所有图片相关后端都支持 --no-images 和 --filter-images（互斥）；启发式清理可用 --raw 关闭。

选择 PDF 后端

始终先用本地解析器，检查输出后再决定是否切换。

MinerU 需要 MINERUAPITOKEN，或将 resources/config.example.json 复制为 gitignore 的 resources/config.json 并填入 token。

网页抓取

webtomd.py 支持所有 URL。安装 curl_cffi 后可模拟 Chrome TLS 指纹，能抓取微信公众号（mp.weixin.qq.com）等屏蔽 Python 默认指纹的站点——无需额外参数。未安装时回退到标准 requests（大多数公开网站够用）。

环境诊断

python3 scripts/check_env.py    # 按格式显示就绪状态：Python 依赖、pandoc、MinerU token

安装

pip install -r resources/requirements.txt
python3 scripts/check_env.py

check_env.py 打印按格式分类的就绪表——绿色表示可用，缺依赖项会指出所需包或二进制。

pandoc 可选——仅处理长尾文档格式（.doc / .odt / .rtf / .tex / .rst / .org / .typ）时需要。

trafilatura 推荐安装——webtomd.py 默认会用它做正文识别（剥离导航/广告/侧栏/评论）。未安装时回退到内置启发式并打印一行提示；--raw 模式不用它。

故障排查

输出约定

• 输入文件 → <输入目录>/<文件名>.md（除非指定 -o）
• 嵌入图片 → <输入目录>/<文件名>_files/，Markdown 中使用相对路径引用
• 图片 manifest → <输入目录>/<文件名>files/imagemanifest.json（后端支持且存在图片时生成）
• 网页图片来源 → <输入目录>/<文件名>files/imagesources.json（网页后端下载图片时生成，授权状态默认 unknown）
• 转换 profile → <stem>.conversion_profile.json（记录本次转换产物和结构统计）
• URL → 当前项目的 projects/（除非指定 -o）；经 MinerU 处理的 PDF URL 使用 MinerU 的输出目录行为
• 已是 Markdown / 纯文本的输入直接输出（或复制）不做转换