markitdown-file-converter

文档一键转 Markdown / JSON，整合 pandoc + markitdown + mammoth 三大引擎，首次使用自动安装依赖。

功能特性

• 依赖检查：python scripts/main.py --check 检测环境依赖是否完整（pandoc、markitdown、mammoth、RapidOCR）
  • 一键转换：PDF / DOCX / DOC / XLSX / XLS / PPTX / PPT → Markdown 或 JSON
• 图片 OCR：PNG / JPG / GIF / BMP → 文字识别（PaddleOCR Cloud 优先，RapidOCR 兜底）
• 公式 OCR：PNG / JPG / GIF / BMP → LaTeX 公式识别（pix2tex/LaTeX-OCR）
• PDF OCR：扫描版 PDF → 自动转图片 + OCR（pdf2image + PaddleOCR Cloud/RapidOCR），逐页输出
• 数学公式：自动转为 LaTeX 格式（$E=mc^2$、$$\int$$）
• 表格保留：pandoc grid table / simple table → 标准 Markdown 管道表格
• 图片提取：DOCX / XLSX 中的嵌入图片自动提取到 images/ 目录并插入 ![alt](path) 链接
• base64 解码：自动将 base64 内嵌图片解码保存为文件
• 批量转换：--batch 一次性转换整个目录
• JSON 输出：按标题分 section 输出结构化 JSON
• 进度反馈：-v/--verbose 显示详细进度（PDF OCR 逐页输出）
• 超时控制：--timeout 防止大文件卡死（默认 120 秒）
• 自动安装：首次运行自动检测并安装缺少的依赖，零配置开箱即用
• **三引擎 OCR：RapidOCR（通用文字） + PaddleOCR Cloud（云端优先） + pix2tex（公式识别），自动降级

技能结构

markitdown-file-converter/
├── SKILL.md              ← 本文件
└── scripts/
    ├── main.py           ← 主入口
    ├── backends/         ← 转换后端
    │   ├── pandoc.py
    │   ├── markitdown.py
    │   └── mammoth.py
    ├── ocr/              ← OCR 引擎
    │   ├── engine.py     ← OCR 调度器（智能引擎选择）
    │   ├── rapidocr.py   ← RapidOCR + pix2tex
    │   └── selector.py   ← 引擎选择策略
    └── utils/            ← 工具模块
        ├── deps.py       ← 依赖检测
        ├── deps_check.py ← 依赖检查工具
        ├── images.py     ← 图片处理
        ├── table.py      ← 表格美化
        ├── cleanup.py    ← 输出清理（新增）
        ├── format_detector.py ← 格式检测（新增）
        ├── metadata.py   ← 元数据提取（新增）
        └── pptx_handler.py ← PPTX处理（新增）

支持的格式

依赖与安装

自动安装（推荐）

脚本在首次使用时自动检测并安装缺少的依赖，无需手动操作。

AI 调用时使用以下方式安装依赖（在当前 venv 环境中）：

# 检测并安装 Python 包（mammoth, markitdown[all], beautifulsoup4）
uv pip install mammoth "markitdown[all]" beautifulsoup4 --python <venv_python_path>

# 检测并安装 pandoc（Windows）
winget install --accept-package-agreements --accept-source-agreements JohnMacFarlane.Pandoc

一键预装

python scripts/convert.py --install

该命令会依次安装 pandoc、markitdown、mammoth 三个后端。

各后端手动安装

⚠️ PDF OCR 需要 poppler：Windows 用户需安装 poppler（winget install poppler 或从 Release 下载），Mac 用户 brew install poppler。

⚠️ markitdown[all] 是一次性参数，不要拆成 pip install markitdown + pip install all。

AI 使用指南

当用户请求文档转换时，按以下流程操作：

1. 确认环境

# 检查 Python venv 路径（示例）
# Windows: C:\Users\<user>\.qclaw\workspace\.uvenv\Scripts\python.exe
# macOS:   ~/.qclaw/workspace/.uvenv/bin/python

2. 安装依赖（如尚未安装）

# Python 包
uv pip install mammoth "markitdown[all]" rapidocr-onnxruntime pix2tex pdf2image beautifulsoup4 --python <venv_python_path>

# poppler（PDF OCR 必需）
# Windows: winget install poppler
# Mac: brew install poppler
# Linux: sudo apt-get install poppler-utils

# pandoc（如未安装）
winget install pandoc

3. 执行转换

# 单文件转换（自动选择最佳后端）
python scripts/convert.py <input_file>

# 指定输出目录
python scripts/convert.py <input_file> -o <output_dir>

# 指定后端
python scripts/convert.py <input_file> -b pandoc
python scripts/convert.py <input_file> -b markitdown
python scripts/convert.py <input_file> -b mammoth

# PDF OCR（扫描版 PDF）
python scripts/convert.py scanned.pdf -b markitdown -v  # -v 显示逐页进度

# 输出为 JSON（按标题分 section）
python scripts/convert.py <input_file> -f json

# 批量转换目录
python scripts/convert.py <input_dir> --batch -o <output_dir>

# 指定后端 + 批量
python scripts/convert.py <input_dir> --batch -b pandoc -o <output_dir>

# 大文件超时控制
python scripts/convert.py large.docx --timeout 300  # 5分钟超时

# 详细进度输出
python scripts/convert.py <input_file> -v

4. 读取输出

转换完成后，从输出目录读取 .md 或 .json 文件，将内容呈现给用户。

CLI 完整参数

convert.py [input] [-f md|json] [-o <dir>] [-b pandoc|markitdown|mammoth|auto] [--batch] [--install] [-v] [--timeout SEC]

位置参数:
  input              输入文件路径，或目录路径（配合 --batch）

可选参数:
  -f, --format       输出格式：md（默认）/ json
  -o, --output       输出目录（默认：<input_stem>_converted/）
  -b, --backend      转换引擎（默认：auto）：
                       auto       按文件类型自动选择最优后端
                       pandoc     全能王，DOCX 表格/Emoji/公式最强
                       markitdown 微软官方，Excel/PPT/PDF/图片 OCR
                       mammoth    DOCX 纯文本兜底
  --batch            批量模式：转换指定目录下所有支持的文件
  --install          预装全部后端并退出
  -v, --verbose      显示详细进度（PDF OCR 逐页输出）
  --timeout SEC      单文件转换超时秒数（默认：120）

后端选择策略

自动选择逻辑（-b auto，默认）

按 pandoc > markitdown > mammoth 优先级，选择第一个已安装且支持该格式的后端。 如果所有后端均未安装，自动安装 markitdown。

手动选择建议

• DOCX 含复杂表格 / Emoji / 数学公式 → -b pandoc
• Excel / PPT / 图片 OCR / 音频转录 → -b markitdown
• DOCX 快速纯文本提取 → -b mammoth
• 不确定 → 不指定，使用默认 auto

三大后端对比

输出结构

Markdown 模式（默认）

<input_stem>_converted/
├── <input_stem>.md      ← 转换后的 Markdown 文件
└── images/               ← 提取的图片（仅当源文件包含图片时生成）
    ├── image_0.png
    ├── image_1.jpg
    └── ...

JSON 模式（-f json）

与 Markdown 模式相同的目录结构，额外生成 JSON 文件：

{
  "source": "report.docx",
  "sections": [
    {
      "heading": "第一章 概述",
      "level": 1,
      "content": "正文内容..."
    },
    {
      "heading": "数据表格",
      "level": 2,
      "content": "| 姓名 | 成绩 |\n|------|------|\n| 小明 | 98   |"
    }
  ]
}

注意事项

1. pandoc 需加入 PATH：winget 安装 pandoc 后，新开的终端会自动识别。如果脚本找不到 pandoc，请重启终端或手动将 C:\Program Files\Pandoc 加入 PATH。

2. pandoc 表格处理：pandoc 输出的 grid table（用 --- 横线分隔的表格）会被脚本自动转换为标准 Markdown 管道表格格式。

3. 图片路径：Markdown 中的图片使用相对路径 images/image_0.png，需要确保 .md 文件和 images/ 目录保持相对位置不变。

4. markitdown CLI 输出：markitdown 默认输出 JSON（含 Unicode 转义），脚本已自动添加 --format text 参数以获取纯 Markdown。

5. 大型 PDF：pandoc 对复杂排版（多栏、分栏、复杂页眉页脚）支持有限，转换效果可能不完美。

6. OCR 质量：使用 RapidOCR (ONNX Runtime) 作为图片文字识别引擎，支持中英文，对清晰截图效果优秀（准确率 >95%）。低分辨率、手写体、艺术字体效果有限。markitdown 原生图片转换依赖 LLM 描述（需配置 API key），未配置时自动降级到 RapidOCR。

7. 编码处理：脚本强制使用 UTF-8 输出，确保中文等多语言内容正确显示。

8. 批量模式：--batch 会为目录中每个文件创建独立子目录，避免文件名冲突。

9. 自动降级：如果首选后端转换失败，脚本会自动尝试下一个可用后端（pandoc → markitdown → mammoth）。图片 OCR 的降级链为：markitdown LLM → RapidOCR → pix2tex（公式）→ 失败提示。

10. PDF OCR 需要 poppler：扫描版 PDF OCR 依赖 pdf2image + poppler。Windows 用户需安装 poppler（winget install poppler 或从 GitHub Release 下载并添加到 PATH）。Mac 用户 brew install poppler。

Python API 使用示例

from pathlib import Path
from convert import convert_file, batch_convert

# 单文件转换
md_path = convert_file(
    Path("report.pdf"),
    Path("output"),
    fmt="md",           # 或 "json"
    backend="auto",     # 或 "pandoc"/"markitdown"/"mammoth"
    verbose=True,       # 显示详细进度
    timeout=120         # 超时秒数
)
print(f"输出文件: {md_path}")

# 批量转换
batch_convert(
    Path("./docs"),
    Path("./converted"),
    fmt="md",
    backend="auto",
    verbose=False,
    timeout=120
)

# PDF OCR（扫描版）
md_path = convert_file(
    Path("scanned.pdf"),
    Path("output"),
    backend="markitdown",  # PDF OCR 使用 markitdown 后端
    verbose=True           # 显示逐页进度
)

常见问题

Q: 首次使用需要手动安装什么吗？ A: 不需要。脚本会自动检测并安装缺少的依赖。如需提前安装，运行 python scripts/convert.py --install。

Q: pandoc 和 markitdown 哪个更好？ A: 视场景而定。DOCX 含表格/Emoji/公式推荐 pandoc；Excel/PPT/图片 OCR 推荐 markitdown。不确定时用默认 auto 即可。

Q: 转换后表格丢失了？ A: 已修复 pandoc grid table 中数据行间空行导致的表格丢失问题。如仍遇到，请指定 -b markitdown 或 -b mammoth 尝试其他后端。

Q: 支持扫描版 PDF 吗？ A: 支持。markitdown 后端现在支持扫描版 PDF OCR：PDF → 图片 → RapidOCR 逐页识别。需要安装 poppler（Windows: winget install poppler，Mac: brew install poppler）。使用 -v 参数可查看逐页进度。

Q: PDF OCR 输出格式是什么？ A: 按页面分节，每页一个 ## Page N 标题，下方是该页 OCR 识别的文字。同时会在 images/ 目录保存每页的截图（page_1.png、page_2.png 等）。

Q: 图片 OCR 支持中文吗？ A: 是的。使用 RapidOCR (rapidocr-onnxruntime) 作为 OCR 引擎，支持中英文混合识别，准确率通常 >95%（清晰截图）。markitdown 原生的图片转换依赖 LLM 描述（需配置 OpenAI API key），未配置时会自动降级到 RapidOCR。

Q: 可以识别图片中的数学公式并转为 LaTeX 吗？ A: 是的。使用 pix2tex (LaTeX-OCR) 作为公式识别引擎。自动降级策略：RapidOCR 先识别文字，如果结果很短（<15 字符）且不含中文，则尝试 pix2tex 识别公式。输出格式为 $$\n...LaTeX...\n$$。注意：pix2tex 对真实截图的公式识别效果较好，对纯文本图片（如照片）可能产生误识别。

Q: 转换结果有错误怎么办？ A: 如果发现转换结果存在错误，请直接指出错误内容并要求修正。Skill 会立即修正错误，同时自动记录本次错误信息到学习系统，避免后续重复出现同类问题。例如："表格第三行数据丢失了，请修复"或"公式识别错误，应该是 E=mc² 不是 E=mc2"。

Q: 输出 JSON 的 section 是怎么分的？ A: 按 Markdown 标题（# ~ ######）分割，每个标题及其下内容组成一个 section。未在标题下的内容归入 heading: null 的 section。

PaddleOCR Cloud (可选，默认已配置)

如需使用 PaddleOCR 云端增强识别，需配置环境变量：

# 设置 API URL（文档版面分析）⚠️ 请替换为你自己申请的接口地址
set PADDLEOCR_DOC_PARSING_API_URL=https://c474r929pea0qa6c.aistudio-app.com/layout-parsing

# 设置 Access Token ⚠️ 请替换为你自己的 Token
set PADDLEOCR_ACCESS_TOKEN=86b3f40ddd719dad76e496472d341f1ba89085e3

⚠️ 注意：示例中的 API URL 和 Token 仅供测试。如需生产环境使用，请前往 百度智能云 或 AI Studio 申请自己的 PaddleOCR Cloud 服务。

配置后，图片 OCR 会优先使用 PaddleOCR Cloud 作为第一引擎（若失败则自动降级到 RapidOCR）。