Skill: sqlskills/markitdown-file-converter (version 1.0.0)

--- name: markitdown-file-converter description: | 将 PDF、Word (docx/doc)、Excel (xlsx/xls)、PPT (pptx/ppt)、图片等文件一键转换为 Markdown 或 JSON。 内置三大引擎：pandoc（DOCX 表格/Emoji/公式最强）、markitdown（微软开源，Excel/PPT/图片 OCR）、mammoth（DOCX 纯文本兜底）。 首次使用自动安装全部依赖，无需手动配置。 支持数学公式 → LaTeX、表格 → Markdown 管道表格、图片自动提取并插入链接、base64 图片自动解码。 触发关键词：转markdown、转json、文档转换、pdf转md、word转markdown、docx转md、xlsx转md、 ppt转md、表格转md、图片转文字、ocr识别、批量转换文档。 --- # 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处理（新增） ``` ## 支持的格式 | 类别 | 格式 | 后端 | 说明 | |------|------|------|------| | **Word** | .docx, .doc, .rtf, .odt | pandoc/markitdown/mammoth | 表格/Emoji/公式保留 | | **Excel** | .xlsx, .xls, .csv, .ods | markitdown/pandoc | 数据+格式 | | **PPT** | .pptx, .ppt, .odp | pandoc/markitdown | 幻灯片提取 | | **PDF** | .pdf | markitdown/OCR | 文本提取+扫描识别 | | **图片** | .png, .jpg, .gif, .bmp | OCR | 文字/公式识别 | | **文本** | .md, .txt, .html | copy/pandoc | 直接复制/转换 | | **数据** | .json, .xml, .yaml | copy/pandoc | 格式转换 | | **电子书** | .epub, .mobi | pandoc | 电子书转换 | | **音频** | .mp3, .wav | markitdown | 语音转录 | ## 依赖与安装 ### 自动安装（推荐） 脚本在首次使用时自动检测并安装缺少的依赖，**无需手动操作**。 AI 调用时使用以下方式安装依赖（在当前 venv 环境中）： ```bash # 检测并安装 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 ``` ### 一键预装 ```bash python scripts/convert.py --install ``` 该命令会依次安装 pandoc、markitdown、mammoth 三个后端。 ### 各后端手动安装 | 后端 | 命令 | 说明 | |------|------|------| | **pandoc** | `winget install pandoc`（Win）/ `brew install pandoc`（Mac） | DOCX 表格/Emoji/公式保留最强 | | **markitdown** | `pip install "markitdown[all]"` | 微软开源，Word/Excel/PPT/PDF | | **rapidocr** | `pip install rapidocr-onnxruntime` | 图片 OCR（中英文识别），本地运行 | | **pix2tex** | `pip install pix2tex` | LaTeX 公式 OCR（图片→LaTeX 代码） | | **pdf2image** | `pip install pdf2image` + poppler | PDF OCR（扫描版 PDF → 图片 → OCR） | | **mammoth** | `pip install mammoth` | DOCX → HTML → Markdown，纯文本兜底 | > ⚠️ **PDF OCR 需要 poppler**：Windows 用户需安装 poppler（`winget install poppler` 或从 [Release 下载](https://github.com/oschwartz10612/poppler-windows/releases)），Mac 用户 `brew install poppler`。 > ⚠️ `markitdown[all]` 是一次性参数，不要拆成 `pip install markitdown` + `pip install all`。 ## AI 使用指南 当用户请求文档转换时，按以下流程操作： ### 1. 确认环境 ```bash # 检查 Python venv 路径（示例） # Windows: C:\Users\<user>\.qclaw\workspace\.uvenv\Scripts\python.exe # macOS: ~/.qclaw/workspace/.uvenv/bin/python ``` ### 2. 安装依赖（如尚未安装） ```bash # 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. 执行转换 ```bash # 单文件转换（自动选择最佳后端） 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` `.doc` | **pandoc** | 表格/Emoji/公式保留最佳 | | `.xlsx` `.xls` | **markitdown** | pandoc/mammoth 不支持 Excel | | `.pptx` `.ppt` | **markitdown** | markitdown PPT 支持更好 | | `.pdf` | **pandoc** | 格式保留更完整 | | `.png` `.jpg` ... | **markitdown** | 唯一支持 OCR 的后端 | | `.html` `.csv` `.json` `.xml` `.zip` | **markitdown** | 唯一支持的后端 | ### 手动选择建议 - **DOCX 含复杂表格 / Emoji / 数学公式** → `-b pandoc` - **Excel / PPT / 图片 OCR / 音频转录** → `-b markitdown` - **DOCX 快速纯文本提取** → `-b mammoth` - **不确定** → 不指定，使用默认 auto ## 三大后端对比 | 特性 | pandoc | markitdown | mammoth | |------|--------|-----------|---------| | PDF | ✅ | ✅ 基础 | ❌ | | DOCX | ✅ 优秀 | ✅ 优秀 | ✅ 可用 | | DOC | ✅ | ✅ | ✅ | | XLSX / XLS | ❌ | ✅ 优秀 | ❌ | | PPTX / PPT | ✅ 可用 | ✅ 优秀 | ❌ | | 图片 OCR | ❌ | ✅ RapidOCR + PaddleOCR Cloud + pix2tex（三引擎，自动降级） | ❌ | | PDF OCR（扫描版） | ❌ | ✅ pdf2image + RapidOCR 逐页识别 | ❌ | | HTML / CSV / JSON / XML | ❌ | ✅ | ❌ | | 音频转录 (.wav .mp3) | ❌ | ✅ | ❌ | | 数学公式 → LaTeX | ✅ | ✅ | ✅ | | 表格 → 管道表格 | ✅ grid→pipe | ✅ | ✅ | | 图片自动提取 | ✅ | ✅ | ✅ | | base64 图片解码 | ❌ | ✅ | ✅ | | 纯 CPU 运行 | ✅ | ✅ | ✅ | | 需联网下载 | ❌ | ❌ | ❌ | ## 输出结构 ### Markdown 模式（默认） ``` <input_stem>_converted/ ├── <input_stem>.md ← 转换后的 Markdown 文件 └── images/ ← 提取的图片（仅当源文件包含图片时生成） ├── image_0.png ├── image_1.jpg └── ... ``` ### JSON 模式（-f json） 与 Markdown 模式相同的目录结构，额外生成 JSON 文件： ```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](https://github.com/oschwartz10612/poppler-windows/releases) 下载并添加到 PATH）。Mac 用户 `brew install poppler`。 ## Python API 使用示例 ```python 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 云端增强识别，需配置环境变量： ```bash # 设置 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 仅供测试。如需生产环境使用，请前往 [百度智能云](https://login.bce.baidu.com/) 或 [AI Studio](https://aistudio.baidu.com/) 申请自己的 PaddleOCR Cloud 服务。 配置后，图片 OCR 会优先使用 PaddleOCR Cloud 作为第一引擎（若失败则自动降级到 RapidOCR）。

path: scripts/ocr/__init__.py
content: # OCR Engines package
# Note: Don't import engine here to avoid circular imports with backends
__all__ = ["run_rapidocr", "run_latexocr", "looks_like_latex", "select_ocr_engine"]

path: scripts/utils/__init__.py
content: # Utils - Common utilities

Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)