# Mineru Skill

> MinerU 文档处理技能。将 PDF、DOCX、PPTX、图片、HTML 文件通过 MinerU API 转换为 Markdown。 当用户需要处理文档、转换文档格式、提取文档内容、检查 MinerU Token 状态、 续期 Token、或批量处理文档目录时使用此技能。 触发关键词：MinerU、处理文档、转换PDF、文档转Markdown、Token状态、批量处理文档。

- Skill: `lucent-snow/mineru-skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add lucent-snow/mineru-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucent-snow/mineru-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lucent-snow (https://skillmd.com/u/lucent-snow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucent-snow/mineru-skill

---


# MinerU 文档处理技能

通过 MinerU API 将 PDF/DOCX/PPTX/图片/HTML 转换为 Markdown + 图片。

## 目录约定

- skill 根目录: 当前 `SKILL.md` 所在目录
- 脚本目录: `<skill-root>/scripts`
- Python 虚拟环境: `<skill-root>/scripts/.venv`
- 默认数据目录: `~/.mineru`
- 可选环境变量: `MINERU_DATA_DIR`，可覆盖默认数据目录

如果你是在仓库根目录直接使用本 skill，下面命令可以直接运行：

```bash
python scripts/setup_env.py
```

环境初始化完成后，Python 解释器位于：

```text
Windows: scripts\.venv\Scripts\python.exe
Unix:    scripts/.venv/bin/python3
```

以下用 `$PY` 代指该解释器，`$SD` 代指脚本目录。

## 环境准备

首次使用需完成以下步骤：

```bash
# 1. 初始化环境（创建 venv、安装依赖、安装 Playwright 浏览器）
python $SD/setup_env.py

# 2. 编辑账户配置（填入 MinerU 账号密码）
#    默认文件位置: ~/.mineru/accounts.yaml
#    如果设置了 MINERU_DATA_DIR，则位于 $MINERU_DATA_DIR/accounts.yaml

# 3. 批量登录获取 Token
$PY $SD/batch_login.py
```

## 核心工作流

**处理文档前必须先检查 Token 有效性。** 完整流程:

1. 运行 `check_tokens.py`，根据退出码判断:
   - 退出码 0 → Token 有效，继续处理
   - 退出码 1 → Token 过期，先运行 `batch_login.py` 续期
2. Token 有效后，运行 `process_document.py` 或 `process_batch.py` 处理文档

## 各脚本用法

### check_tokens.py — 检查 Token 状态

```bash
$PY $SD/check_tokens.py
```

退出码: 0=全部有效，1=有过期或缺失。

### batch_login.py — Token 续期

```bash
# headless 模式（默认，无需显示器）
$PY $SD/batch_login.py

# 调试模式（打开浏览器界面）
$PY $SD/batch_login.py --headed
```

自动完成: 登录 MinerU → 删除旧 Token → 创建新 Token → 保存到 `~/.mineru/all_tokens.json`。

### process_document.py — 单文档处理

```bash
# 处理本地文件（输出到源文件同目录）
$PY $SD/process_document.py <文件路径>

# 指定输出目录
$PY $SD/process_document.py <文件路径> --output-dir <目录>

# 指定模型
$PY $SD/process_document.py <文件路径> --model vlm

# 处理 URL
$PY $SD/process_document.py https://example.com/doc.pdf
```

支持格式: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML。
输出: `{文件名}.md` + `{文件名}_images/` 目录。

### process_batch.py — 批量处理

```bash
# 处理目录下所有 PDF
$PY $SD/process_batch.py <目录>

# 指定文件类型
$PY $SD/process_batch.py <目录> --pattern "*.docx"

# 控制并发数
$PY $SD/process_batch.py <目录> --max-workers 3

# 递归扫描子目录
$PY $SD/process_batch.py <目录> --recursive
```

## 常见场景

| 用户请求 | 操作 |
|----------|------|
| "帮我处理这个 PDF" | check_tokens → process_document.py |
| "转换这个目录下所有文档" | check_tokens → process_batch.py |
| "查看 Token 状态" | check_tokens.py |
| "续期/刷新 Token" | batch_login.py |
| "处理这个网页/URL" | check_tokens → process_document.py URL |

## 注意事项

- 文件大小限制 200MB，超过会报错
- 模型自动选择: PDF/DOC/PPT/图片 → vlm，HTML → MinerU-HTML
- Token 有效期约 90 天，过期需运行 batch_login.py 续期
- 数据目录默认是 `~/.mineru/`，可通过 `MINERU_DATA_DIR` 自定义
- 详细 API 参数和错误排查参考 `references/api-reference.md`