| name | mineru-converter |
| description | PDF转Markdown工具,基于MinerU和方案A++策略,完全封装的CLI工具+Skill,自动清理临时文件,支持单文件和批量处理 |
MinerU PDF转换器
快速开始
使用方式1:Claude自然语言调用
用户: "处理这个PDF文件"
Claude: [自动调用mineru-cli,处理完成后清理临时文件]
使用方式2:直接命令行调用
/Users/CS/.claude/skills/mineru-converter/bin/mineru-cli convert file.pdf -o output/
mineru-cli convert file.pdf -o output/
核心特性
✅ 完全封装:CLI工具集成在Skill目录内,零外部依赖
✅ 方案A++策略:每文件独立进程,自动内存释放
✅ 自动清理:只保留最终MD文件,临时文件自动删除
✅ 灵活输出:可指定输出目录,默认为PDF所在目录
✅ 错误重试:自动重试3次,提高成功率
✅ 进度监控:实时反馈处理状态和性能指标
技术架构
- Skill位置:
/Users/CS/.claude/skills/mineru-converter/
- CLI工具:
bin/mineru-cli(集成在skill内)
- 核心库:
lib/*.sh(processor.sh, cleanup.sh, validator.sh, logger.sh)
- 虚拟环境:
env/mineru_venv/(封装在skill内)
- 参考脚本:
scripts/*.sh(封装在skill内)
- 处理策略: 方案A++(单文件独立进程 + GPU加速1GB)
目录结构
mineru-converter/
├── SKILL.md # 本文件
├── README.md # 详细使用文档
├── bin/
│ └── mineru-cli # CLI主入口
├── lib/ # 核心库
│ ├── processor.sh # 核心处理逻辑
│ ├── cleanup.sh # 清理工具
│ ├── validator.sh # 文件验证
│ └── logger.sh # 日志管理
├── env/
│ └── mineru_venv/ # Python虚拟环境(封装)
├── scripts/ # 参考脚本(封装)
│ ├── batch_mineru_safe.sh
│ ├── batch_mineru_medium.sh
│ └── batch_mineru_mild.sh
├── config/
│ └── default.conf # 默认配置
└── references/ # 参考资料
└── mineru-official-docs.md
一键安装
ln -s /Users/CS/.claude/skills/mineru-converter/bin/mineru-cli \
/usr/local/bin/mineru-cli
mineru-cli --version
CLI工具使用
命令格式
mineru-cli <command> [options]
主要命令
1. convert(核心命令)
mineru-cli convert path/to/file.pdf
mineru-cli convert path/to/file.pdf -o path/to/output/
mineru-cli convert path/to/*.pdf
mineru-cli convert path/to/file.pdf \
--output path/to/output/ \
--gpu \
--vram 1024 \
--cleanup \
--retry 3 \
--verbose
2. batch(批量处理)
mineru-cli batch path/to/pdfs/
mineru-cli batch path/to/pdfs/ --resume
mineru-cli batch path/to/pdfs/ --jobs 2
3. clean(清理工具)
mineru-cli clean --all
mineru-cli clean --workspace 20260201_143022
mineru-cli clean --logs-only
4. status(状态查看)
mineru-cli status
mineru-cli status --resources
参数说明
| 参数 | 说明 | 默认值 |
|---|
-o, --output | 输出目录 | PDF文件所在目录 |
--gpu | 启用GPU加速 | 关闭 |
--vram | GPU显存(MB) | 1024 |
--cleanup | 自动清理临时文件 | 开启 |
--retry | 失败重试次数 | 3 |
--verbose | 详细日志输出 | 关闭 |
--jobs | 批量并发数 | 1(推荐) |
方案A++策略说明
核心特点:
- 每个PDF文件使用独立进程处理
- 处理完成后进程自动退出,释放内存
- 启用GPU加速(1GB显存),速度提升2-3倍
- 自动清理临时文件,保持目录整洁
性能数据:
- 处理速度:100-150页/分钟
- 内存峰值:8-10GB(自动释放)
- GPU显存:1GB
- 稳定性:⭐⭐⭐⭐⭐
与原串行方案对比:
| 指标 | 原串行方案 | 方案A++ | 提升 |
|---|
| 处理速度 | 51页/分钟 | 150页/分钟 | 3x |
| 总耗时(20文件) | 218分钟 | 70-75分钟 | -65% |
| 内存释放 | 手动重启 | 自动释放 | ∞ |
| 目录整洁度 | 临时文件残留 | 自动清理 | ∞ |
使用示例
场景1:快速处理单个PDF
mineru-cli convert report.pdf
mineru-cli convert report.pdf -o ~/Documents/markdown/
场景2:批量处理整个目录
mineru-cli batch /path/to/pdfs/ --resume
场景3:查看处理状态
mineru-cli status
mineru-cli status --resources
场景4:清理临时文件
mineru-cli clean --all
错误处理
工具内置智能错误处理:
- 文件损坏:自动尝试修复或提供明确错误提示
- 处理失败:自动重试3次,每次间隔指数退避
- 资源不足:提前检查内存,提供优化建议
- GPU错误:自动降级到CPU模式
故障排查
问题1:处理速度异常慢
top -l 1 | grep mineru
mineru-cli convert file.pdf --no-gpu
问题2:临时文件未清理
du -sh .mineru_temp/
mineru-cli clean --all
问题3:批量处理部分失败
mineru-cli convert failed_file.pdf --retry 5
mineru-cli batch /path/to/pdfs/ --resume
健康检查
mineru-cli healthcheck
输出示例:
=== MinerU工具健康检查 ===
1️⃣ 虚拟环境: ✅ 存在
2️⃣ CLI工具: ✅ 已安装
3️⃣ 临时目录: ✅ 干净
4️⃣ 系统资源:
- 可用内存: 18GB
- CPU使用率: 12%
5️⃣ 运行进程: ✅ 无(已清理)
=== 检查完成 ===
版本信息
- 版本: v5.0(完全独立封装版)
- 更新日期: 2026-02-01
- 核心特性: 虚拟环境+参考脚本完全封装在skill内,零外部依赖
技术支持
- 参考文档:
references/mineru-official-docs.md
- 参考脚本:
scripts/batch_mineru_safe.sh(方案A++)
- 配置文件:
config/default.conf