mineru-converter

name	mineru-converter
description	PDF转Markdown工具，基于MinerU和方案A++策略，完全封装的CLI工具+Skill，自动清理临时文件，支持单文件和批量处理

MinerU PDF转换器

快速开始

使用方式1：Claude自然语言调用

用户: "处理这个PDF文件" Claude: [自动调用mineru-cli，处理完成后清理临时文件]

使用方式2：直接命令行调用

# 直接调用Skill中的CLI
/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

一键安装

# 创建符号链接到PATH（推荐）
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：批量处理整个目录

# 处理目录下所有PDF（自动跳过已完成的）
mineru-cli batch /path/to/pdfs/ --resume

场景3：查看处理状态

# 查看当前处理进度
mineru-cli status

# 查看系统资源使用
mineru-cli status --resources

场景4：清理临时文件

# 清理所有临时文件
mineru-cli clean --all

错误处理

工具内置智能错误处理：

• 文件损坏：自动尝试修复或提供明确错误提示
• 处理失败：自动重试3次，每次间隔指数退避
• 资源不足：提前检查内存，提供优化建议
• GPU错误：自动降级到CPU模式

故障排查

问题1：处理速度异常慢

# 检查CPU使用率
top -l 1 | grep mineru

# 解决方案：关闭GPU加速
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

# 使用--resume继续处理
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