| name | pdf-converter |
| description | 本地 MinerU 将 PDF/Office/图片转为 Markdown（含 images/ 图文、表格与公式识别）。复杂版式、扫描件、长书须先确认页范围与后端。用户要转 PDF、提取表格、OCR、或问「这篇 PDF 讲了什么」时使用。 |
Document to Markdown (Local MinerU)
使用本机 MinerU CLI 将 PDF、图片、Office 转为 Markdown。全程离线（首次会下载数 GB 模型），无需 API Key。
语言规则
用与用户相同语言回复（本技能正文为中文时，对用户仍用中文）。
执行前确认（长文档 / 高成本）
收到转换任务后，若 PDF 超过约 50 页或体积 >10MB，先用简短列表确认再执行：
- 输入路径与输出目录（默认：与 PDF 同级的
mineru-output/，或用户指定）
- 是否全量转换，或仅指定页（
-s/-e，0 起算）
- 后端：
pipeline（默认，稳定）或 vlm-auto-engine（需完整 VLM 权重）
- 是否需要 bundle（
.md + images/ 打平目录，便于搬运）
未确认前不要对数百页 PDF 默认全量跑满。
核心流程
- Extract —
mineru 或 python3 scripts/convert.py 转为 Markdown
- Read & Process — 按需摘要、抽表、整理；MinerU 只负责 OCR/版面，理解由代理完成
图文：.md 与 images/ 必须一起保留；禁止只拷贝 .md。
推荐命令（复杂 PDF / 中文书）
python3 scripts/convert.py -p "/path/to/book.pdf" -o "./output" -b pipeline -l ch -m auto
python3 scripts/convert.py -p book.pdf -o ./output --start 0 --end 9
mineru -p book.pdf -o ./output -b pipeline --lang ch -m auto -t True -f True
打平为便于分享的 bundle：
python3 scripts/bundle_markdown.py ./output/书名
脚本通过 subprocess 调用已安装的 mineru CLI（与 uv tool install mineru 一致），本身无第三方 Python 依赖。
安装
uv tool install mineru
uv tool update-shell
mineru --version
Apple Silicon / 仅需稳定本地转换：默认使用 -b pipeline，不要假设 hybrid-auto-engine 一定可用。
若使用 VLM 后端（vlm-auto-engine / hybrid-auto-engine），在 mineru 的 uv 环境中安装 accelerate，并确保 HuggingFace 权重完整：
MINERU_PY="$(dirname "$(which mineru)")/../share/uv/tools/mineru/bin/python"
uv pip install --python "$MINERU_PY" accelerate
mineru-models-download
常用参数
| 场景 | 命令要点 |
|---|
| 中文 PDF、图文混排 | -l ch -m auto -b pipeline |
| 扫描件 | -m ocr |
| 仅文字层、无图 | -m txt（会弱化图片） |
| 表格/公式 | -t True -f True（默认开启） |
| 大书分段 | -s 0 -e 99 多次输出后合并 |
| 复用已启动的 API | mineru-api --port 8000 另开终端；mineru ... --api-url http://127.0.0.1:8000 |
完整参数：mineru --help。
输出结构（MinerU 3.x）
<output_dir>/
└── <文档名>/
└── auto/
├── <文档名>.md
├── <文档名>_middle.json
├── <文档名>_content_list.json
└── images/
读取路径：<文档名>/auto/<文档名>.md。表格/图表行为见 references/mineru-output-and-tables.md。
表格与图片
- 图片：
，文件在 auto/images/。
- 表格：简单表可能为 Markdown
| 表；复杂表、行情图、截图表格常为图片块——需在回答中说明，或结合 _content_list.json / 读图补全。
- 分享或入库：使用
python3 scripts/bundle_markdown.py 或打包整个 auto/ 目录。
模式速查
| 情况 | 建议 |
|---|
| 一般中文 PDF | pipeline + auto + ch |
| 扫描版 | --method ocr |
| 保留插图/版式 | 避免 --method txt |
| 内存不足 | pipeline，或分页 -s/-e |
| 最佳精度（环境完备） | hybrid-auto-engine 或 vlm-auto-engine |
不负责
- 不代装 uv/Python（仅给出命令）
- 不默认把数百页 PDF 全量转换（须确认）
- 不把云端 MinerU Open API 当作本技能默认路径（本技能以本地 CLI 为准）
故障排除
| 问题 | 处理 |
|---|
command not found: mineru | uv tool update-shell，重开终端 |
VLM：requires accelerate | 见上文 uv pip install accelerate |
VLM：缺 model.safetensors | mineru-models-download 或改用 pipeline |
| 首次极慢 | 模型初始化，同机再次运行会快很多 |
| 加密 PDF | 多数仍可解析；若失败提示用户解除复制限制或另存 |
| 乱码 | 显式 --lang ch 或 en |
调试：MINERU_LOG_LEVEL=DEBUG mineru ...
参考
