lucent-snow MinerU 文档处理技能
通过 MinerU API 将 PDF/DOCX/PPTX/图片/HTML 转换为 Markdown + 图片。
目录约定
- skill 根目录: 当前
SKILL.md所在目录 - 脚本目录:
<skill-root>/scripts - Python 虚拟环境:
<skill-root>/scripts/.venv - 默认数据目录:
~/.mineru - 可选环境变量:
MINERU_DATA_DIR，可覆盖默认数据目录
如果你是在仓库根目录直接使用本 skill，下面命令可以直接运行：
python scripts/setup_env.py
环境初始化完成后，Python 解释器位于：
Windows: scripts\.venv\Scripts\python.exe
Unix: scripts/.venv/bin/python3
以下用 $PY 代指该解释器，$SD 代指脚本目录。
环境准备
首次使用需完成以下步骤：
# 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 有效性。 完整流程:
- 运行
check_tokens.py，根据退出码判断:- 退出码 0 → Token 有效，继续处理
- 退出码 1 → Token 过期，先运行
batch_login.py续期
- Token 有效后，运行
process_document.py或process_batch.py处理文档
各脚本用法
check_tokens.py — 检查 Token 状态
$PY $SD/check_tokens.py
退出码: 0=全部有效，1=有过期或缺失。
batch_login.py — Token 续期
# headless 模式（默认，无需显示器）
$PY $SD/batch_login.py
# 调试模式（打开浏览器界面）
$PY $SD/batch_login.py --headed
自动完成: 登录 MinerU → 删除旧 Token → 创建新 Token → 保存到 ~/.mineru/all_tokens.json。
process_document.py — 单文档处理
# 处理本地文件（输出到源文件同目录）
$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 — 批量处理
# 处理目录下所有 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