mineru-skill

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

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 有效性。 完整流程:

1. 运行 check_tokens.py，根据退出码判断:
   • 退出码 0 → Token 有效，继续处理
   • 退出码 1 → Token 过期，先运行 batch_login.py 续期
2. 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