---
slug: "mineru-converter-skill"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/CSlawyer1985/mineru-converter-skill@main/SKILL.md"
repo: "https://github.com/CSlawyer1985/mineru-converter-skill"
source_file: "SKILL.md"
branch: "main"
---
---
name: mineru-converter
description: PDF转Markdown工具，基于MinerU和方案A++策略，完全封装的CLI工具+Skill，自动清理临时文件，支持单文件和批量处理
---

# MinerU PDF转换器

## 快速开始

### 使用方式1：Claude自然语言调用
用户: "处理这个PDF文件"
Claude: [自动调用mineru-cli，处理完成后清理临时文件]

### 使用方式2：直接命令行调用
```bash
# 直接调用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
```

## 一键安装

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

# 验证安装
mineru-cli --version
```

## CLI工具使用

### 命令格式
```bash
mineru-cli <command> [options]
```

### 主要命令

#### 1. convert（核心命令）
```bash
# 单文件处理
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（批量处理）
```bash
# 处理整个目录
mineru-cli batch path/to/pdfs/

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

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

#### 3. clean（清理工具）
```bash
# 清理所有临时文件
mineru-cli clean --all

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

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

#### 4. status（状态查看）
```bash
# 查看处理进度
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
```bash
# 最简单用法（输出到当前目录）
mineru-cli convert report.pdf

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

### 场景2：批量处理整个目录
```bash
# 处理目录下所有PDF（自动跳过已完成的）
mineru-cli batch /path/to/pdfs/ --resume
```

### 场景3：查看处理状态
```bash
# 查看当前处理进度
mineru-cli status

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

### 场景4：清理临时文件
```bash
# 清理所有临时文件
mineru-cli clean --all
```

## 错误处理

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

## 故障排查

### 问题1：处理速度异常慢
```bash
# 检查CPU使用率
top -l 1 | grep mineru

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

### 问题2：临时文件未清理
```bash
# 检查临时目录大小
du -sh .mineru_temp/

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

### 问题3：批量处理部分失败
```bash
# 单独重试失败文件
mineru-cli convert failed_file.pdf --retry 5

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

## 健康检查

```bash
# 一键健康检查脚本
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`