PDF 论文解析 Skill
功能描述
这个 Skill 提供了强大的 PDF 文件解析能力，可以：
- 将 PDF 文件转换为高质量的 Markdown 格式
- 支持多种解析模型（pipeline、vlm、MinerU-HTML）
- 自动追踪每日 API 用量（每日限制2000页）
- 提供用量统计和配额检查
- 可选导出 DOCX、HTML、LaTeX 等格式
使用场景
当用户有以下需求时，应使用此 Skill：
- 需要将 PDF 论文转换为 Markdown 进行深度研读
- 想要提取 PDF 中的文本和图片
- 需要批量处理多个 PDF 文件（注意每日限额）
- 需要查看 API 用量统计
环境准备
本 Skill 使用 uv 管理 Python 依赖（通过 PEP 723 内联元数据）。首次使用前需安装 uv：
macOS / Linux：
brew install uv
Windows：
winget install uv
> uv run 会自动读取脚本中的 # /// script 元数据块，创建隔离的虚拟环境并安装依赖（requests），无需手动 pip install。
调用方式
基本命令格式
所有命令需在 Skill 根目录下执行。请将 <SKILL_DIR> 替换为实际的 Skill 安装路径。
cd <SKILL_DIR> && uv run scripts/mineru_parser.py --file "文件路径" [选项]
uv run 会自动处理 Python 版本和依赖，跨平台通用（macOS / Linux / Windows），无需区分 shell 类型。
参数说明
必需参数
--file: PDF 文件路径
可选参数
-o,--output: 输出目录（默认使用 PDF 文件名作为目录名）--model: 解析模型版本vlm: VLM 模型（默认，推荐）pipeline: Pipeline 模型MinerU-HTML: HTML 模型--extra-formats: 额外导出格式，可选多个docx: 导出 Word 文档html: 导出 HTMLlatex: 导出 LaTeX--save-json: 保存中间 JSON 文件（layout.json, content_list.json, model.json）--save-pdf: 在输出目录中保留原始 PDF 文件--no-quota-check: 跳过配额检查（不推荐）--usage-summary: 显示用量摘要后退出
使用示例
以下示例假设当前已在 <SKILL_DIR> 目录。
示例 1：基本解析
uv run scripts/mineru_parser.py --file "paper.pdf"
示例 2：指定输出目录
uv run scripts/mineru_parser.py --file "research.pdf" -o "research_output"
示例 3：导出多种格式
uv run scripts/mineru_parser.py --file "paper.pdf" --extra-formats docx html
示例 4：查看用量统计
uv run scripts/mineru_parser.py --usage-summary
示例 5：保存所有中间文件
uv run scripts/mineru_parser.py --file "paper.pdf" --save-json --save-pdf
配额管理
每日限制
- 每日页数限制: 2000 页
- 系统会自动追踪当天已使用的页数
- 解析前会自动检查配额是否充足
- 解析完成后会自动记录用量
检查用量
uv run scripts/mineru_parser.py --usage-summary
输出示例：
📈 最近7天用量统计：
==================================================
2026-01-29: 150/2000 页 [███████░░░░░░...] 7.5%
2026-01-28: 450/2000 页 [██████████████...] 22.5%
...
==================================================
用量记录文件
- 用量数据保存在：
<SKILL_DIR>/data/usage.log - 格式为 JSON，包含日期、时间、页数、文件名等信息
- 可以手动编辑该文件来修正记录（不推荐）
输出结构
解析完成后会生成以下文件结构：
输出目录/
├── full.md # 主要的 Markdown 文件（含公式、表格）
├── images/ # 提取的图片
│ ├── image_001.png
│ └── ...
├── layout.json # 布局信息（如果使用 --save-json）
├── content_list.json # 内容列表（如果使用 --save-json）
├── model.json # 模型信息（如果使用 --save-json）
└── [原文件_origin.pdf] # 原始文件（如果使用 --save-pdf）
Agent 执行建议
标准工作流
-
解析前检查
bash # 先查看今日配额 cd <SKILL_DIR> && uv run scripts/mineru_parser.py --usage-summary -
执行解析
bash # 解析 PDF 文件到指定输出目录 cd <SKILL_DIR> && uv run scripts/mineru_parser.py --file "path/to/paper.pdf" -o "./解析结果" -
读取结果
- 读取生成的full.md文件
- 向用户展示解析结果
批量处理建议
如果需要处理多个 PDF：
1. 先统计所有 PDF 的总页数（可以通过查看文件属性或使用其他工具）
2. 检查配额是否充足
3. 如果超过限额，建议分批处理
4. 每次解析后系统会自动更新用量
错误处理
常见错误：
- 配额不足: 等待第二天重置，或者选择性解析更重要的文件
- 文件格式错误: 确保是标准的 PDF 文件
- 网络超时: 脚本默认超时 600 秒，如仍超时可修改 mineru_parser.py 中的 wait_for_batch_completion 超时参数
API 密钥配置
API 密钥支持三种读取方式，优先级：CLI 参数 > 环境变量 > 配置文件。
方式 1：环境变量（推荐）
设置环境变量 MINERU_API_KEY（也支持 MINERU_TOKEN）：
macOS / Linux（zsh / bash）：
export MINERU_API_KEY="your-jwt-token-here"
Windows（PowerShell）：
$env:MINERU_API_KEY = "your-jwt-token-here"
方式 2：CLI 参数（临时使用）
uv run scripts/mineru_parser.py --file "paper.pdf" --api-key "your-jwt-token-here"
方式 3：配置文件（fallback，不推荐）
API 密钥可存储在：<SKILL_DIR>/config/minerU.apikey（纯文本，一行一个 token）。
> ⚠️ 切勿将 config/minerU.apikey 提交到版本控制。 该文件已在 .gitignore 中排除。发布 Skill 前请确认该文件不存在。
依赖管理
本 Skill 使用 PEP 723 内联元数据管理依赖，依赖声明写在 scripts/mineru_parser.py 顶部：
# /// script
# requires-python = ">=3.9"
# dependencies = [
# "requests",
# ]
# ///
uv run首次执行时自动创建.venv/虚拟环境并安装requests- 后续执行直接复用已有环境，零开销
usage_tracker.py为本地模块，无需额外声明- 如果受网络限制，可使用国内镜像：
uv run --index-url https://pypi.tuna.tsinghua.edu.cn/simple scripts/mineru_parser.py ...
> 如果遇到 Unicode 编码问题：
> - macOS / Linux: 通常默认为 UTF-8，无需额外设置
> - Windows: $env:PYTHONIOENCODING = "utf-8"（PowerShell）或 set PYTHONIOENCODING=utf-8（CMD）
注意事项
- 页数限制：每日最多解析 2000 页，请合理安排
- 文件大小：建议单个文件不超过 100MB
- 解析时间：根据页数和复杂度，可能需要几分钟
- 网络要求：需要稳定的网络连接
- 配额重置：每天 00:00 自动重置配额计数（基于本地时间）
- Markdown质量：VLM 模型通常提供最好的解析质量
高级用法
使用 Python 模块方式调用
from pathlib import Path
import sys
# 添加脚本路径（替换为实际的 Skill 目录）
skill_dir = Path("<SKILL_DIR>")
skill_scripts = skill_dir / "scripts"
sys.path.insert(0, str(skill_scripts))
from mineru_parser import MinerULocalParser
from usage_tracker import UsageTracker
# 检查配额
tracker = UsageTracker()
today_used = tracker.get_today_usage()
print(f"今日已用: {today_used}/2000 页")
# 解析文件
api_key_path = skill_dir / "config" / "minerU.apikey"
with open(api_key_path) as f:
api_key = f.read().strip()
parser = MinerULocalParser(api_key)
md_files, pages = parser.parse_local_file("paper.pdf", output_dir="output")
print(f"解析完成: {pages} 页")
> 注意：UsageTracker 默认将日志存放在 <SKILL_DIR>/data/usage.log。如果在非 Skill 目录下运行上述代码，建议显式指定 log_file 路径。
纯 Python 环境运行（不使用 uv）
如果环境中已安装 requests（Python 3.9+），也可以跳过 uv 直接运行：
cd <SKILL_DIR> && python scripts/mineru_parser.py --file "paper.pdf"
更新日志
- v1.0 (2026-01-29)
- 初始版本
- 支持 PDF 转 Markdown
- 每日配额追踪（2000页）
-
用量统计功能
-
v1.1 (2026-04-23)
- 修正路径引用
- 修正输出目录结构说明
-
增加 Python 环境说明
-
v1.2 (2026-05-22)
- 适配 macOS / Linux 与 Windows 双平台
- 使用
<SKILL_DIR>占位符替代硬编码路径 -
不同系统的命令和配置说明分离展示
-
v1.3 (2026-05-22)
- 迁移到
uv+ PEP 723 内联元数据管理依赖 - 不再需要手动安装 Python 依赖或配置虚拟环境
uv run跨平台统一命令，无需区分 shell- 保留纯
python运行的 fallback 方案
