mineru-converter

MinerU PDF Converter

Quick Start

Usage 1: Claude natural language invocation

User: "Process this PDF file" Claude: [automatically invokes mineru-cli, cleans up temporary files after processing is complete]

Usage 2: Direct command-line invocation

# 直接调用Skill中的CLI
/Users/CS/.claude/skills/mineru-converter/bin/mineru-cli convert file.pdf -o output/

# 或创建符号链接后简化调用
mineru-cli convert file.pdf -o output/

Core Features

✅ Fully encapsulated: CLI tool integrated within the Skill directory, zero external dependencies ✅ Plan A++ strategy: Independent process per file, automatic memory release ✅ Automatic cleanup: Only the final MD file is kept, temporary files are automatically deleted ✅ Flexible output: Output directory can be specified, defaults to the directory where the PDF is located ✅ Error retry: Automatically retries 3 times, improving the success rate ✅ Progress monitoring: Real-time feedback on processing status and performance metrics

Technical Architecture

• Skill location: /Users/CS/.claude/skills/mineru-converter/
• CLI tool: bin/mineru-cli(integrated within the skill)
• Core library: lib/*.sh（processor.sh, cleanup.sh, validator.sh, logger.sh）
• Virtual environment: env/mineru_venv/(encapsulated within the skill)
• Reference script: scripts/*.sh(encapsulated within the skill)
• Processing strategy: Plan A++ (independent process per single file + GPU acceleration 1GB)

Directory Structure

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

One-click Installation

# 创建符号链接到PATH（推荐）
ln -s /Users/CS/.claude/skills/mineru-converter/bin/mineru-cli \
      /usr/local/bin/mineru-cli

# 验证安装
mineru-cli --version

CLI Tool Usage

Command Format

mineru-cli <command> [options]

Main Commands

1. convert (core command)

# 单文件处理
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 (batch processing)

# 处理整个目录
mineru-cli batch path/to/pdfs/

# 自动跳过已完成文件
mineru-cli batch path/to/pdfs/ --resume

# 并发处理（谨慎使用）
mineru-cli batch path/to/pdfs/ --jobs 2

3. clean (cleanup tool)

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

# 清理指定工作空间
mineru-cli clean --workspace 20260201_143022

# 只清理日志
mineru-cli clean --logs-only

4. status (status check)

# 查看处理进度
mineru-cli status

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

Parameter Description

Parameter	Description	Default Value
-o, --output	Output directory	Directory where the PDF file is located
--gpu	Enable GPU acceleration	Off
--vram	GPU memory (MB)	1024
--cleanup	Automatically clean up temporary files	On
--retry	Number of retries on failure	3
--verbose	Verbose log output	Off
--jobs	Batch concurrency count	1 (recommended)

Plan A++ Strategy Description

Core Features：

• Each PDF file is processed using an independent process
• The process automatically exits after processing is complete, releasing memory
• GPU acceleration is enabled (1GB GPU memory), speed increased by 2-3 times
• Automatically cleans up temporary files, keeping the directory tidy

Performance Data：

• Processing speed: 100-150 pages/minute
• Peak memory: 8-10GB (automatically released)
• GPU memory: 1GB
• Stability: ⭐⭐⭐⭐⭐

Comparison with the original serial approach：

Metric	Original serial approach	Plan A++	Improvement
Processing speed	51 pages/minute	150 pages/minute	3x
Total time (20 files)	218 minutes	70-75 minutes	-65%
Memory release	Manual restart	Automatic release	∞
Directory cleanliness	Temporary file residue	Automatic cleanup	∞

Usage Examples

Scenario 1: Quickly process a single PDF

# 最简单用法（输出到当前目录）
mineru-cli convert report.pdf

# 输出到指定目录
mineru-cli convert report.pdf -o ~/Documents/markdown/

Scenario 2: Batch process an entire directory

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

Scenario 3: Check processing status

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

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

Scenario 4: Clean up temporary files

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

Error Handling

The tool has built-in intelligent error handling:

• Corrupted file: Automatically attempts repair or provides a clear error message
• Processing failure: Automatically retries 3 times, with exponential backoff between each attempt
• Insufficient resources: Checks memory in advance and provides optimization suggestions
• GPU error: Automatically downgrades to CPU mode

Troubleshooting

Issue 1: Processing speed is abnormally slow

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

# 解决方案：关闭GPU加速
mineru-cli convert file.pdf --no-gpu

Issue 2: Temporary files are not cleaned up

# 检查临时目录大小
du -sh .mineru_temp/

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

Issue 3: Partial failure in batch processing

# 单独重试失败文件
mineru-cli convert failed_file.pdf --retry 5

# 使用--resume继续处理
mineru-cli batch /path/to/pdfs/ --resume

Health Check

# 一键健康检查脚本
mineru-cli healthcheck

Example output:

=== MinerU工具健康检查 ===
1️⃣ 虚拟环境: ✅ 存在
2️⃣ CLI工具: ✅ 已安装
3️⃣ 临时目录: ✅ 干净
4️⃣ 系统资源:
   - 可用内存: 18GB
   - CPU使用率: 12%
5️⃣ 运行进程: ✅ 无（已清理）
=== 检查完成 ===

Version Information

• Version: v5.0 (Fully Standalone Packaged Edition)
• Update date: 2026-02-01
• Core features: The virtual environment and reference scripts are fully packaged within the skill, with zero external dependencies

Technical Support

• Reference documentation: references/mineru-official-docs.md
• Reference script: scripts/batch_mineru_safe.sh(Solution A++)
• Configuration file: config/default.conf