shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

mineru-ocr

Convert PDF documents to Markdown format using the MinerU API, supporting OCR, table, and formula recognition. This skill should be used when users need to convert PDF, Word, PPT, or image documents to Markdown, or mention PDF to Markdown conversion, OCR, text recognition, table recognition, formula recognition, document conversion, image to text, and scanned document conversion.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

MinerU PDF 转 Markdown

前置配置

默认 Auto 模式：未配置 Token 时，自动使用官方免登录轻量接口；配置 Token 后，自动切换到标准 API。

免配置快速使用

  • 无需登录、无需创建 .env
  • 适合快速转换本地小文件或远程文档 URL
  • 受官方轻量接口限制影响：按 IP 限频、单文件 10 MB、最多 20 页

升级到标准 API（可选）

如遇到以下情况，建议配置 Token：

  • 文件超过 10 MB
  • 页数超过 20 页
  • 轻量接口遇到 IP 限频
  • 需要提取网页 URL
  • 希望更稳定地使用标准 API 配额

申请 API Token

  1. 访问 https://mineru.net/apiManage/token
  2. 注册/登录账号
  3. 创建 API Token 并复制（格式：eyJ0eXAiOiJKV1QiLCJhbGc...）

配置 Token

方式一：让 AI 配置

"帮我配置 MinerU，Token 是：xxx"

方式二：手动配置

cd .claude/skills/mineru-ocr/config
cp .env.example .env
nano .env  # 填入 MINERU_API_TOKEN

方式三：复用官方 CLI 已保存的 Token

如果你已经跑过官方 mineru-open-api auth，本 skill 也会尝试回退读取 ~/.mineru/config.yaml 中保存的 Token。

当前读取优先级为：

  1. 本 skill 的 .claude/skills/mineru-ocr/config/.env 中的 MINERU_API_TOKEN
  2. 环境变量 MINERU_API_TOKEN
  3. 环境变量 MINERU_TOKEN
  4. 官方 CLI 配置 ~/.mineru/config.yaml

Token 更新

按当前规则，Token 有效期 3 个月（约 90 天）。过期后转换失败（错误 401 或 Unauthorized）。

更新方法：告诉 AI "我的 MinerU Token 过期了，新的 Token 是：xxx"

功能说明

通过 MinerU 将文档转换为 Markdown 格式，支持：

  • Auto 模式：无 Token 走免登录轻量接口，有 Token 走标准 API
  • PDF、DOC、DOCX、PPT、PPTX、PNG、JPG、JPEG
  • 本地文件、远程文档 URL、网页 URL
  • OCR 文字识别
  • 表格识别和保留
  • 数学公式识别
  • 结果归档，保留 Markdown、接口响应和相关图片资源，便于回溯

能力边界

| 场景 | 免登录轻量接口 | 标准 Token API | | ---- | -------------- | -------------- | | 本地 PDF / 图片 / Docx / Pptx | 支持 | 支持 | | 远程文档 URL（PDF、图片、Doc/Docx、PPT/PPTx） | 支持 | 支持 | | 网页 URL / HTML | 不支持 | 支持 | | 单文件大小 | 10 MB 内 | 200 MB 内 | | 页数限制 | 20 页内 | 600 页内 | | 表格识别 | 不支持，按官方口径需升级到标准模式 | 支持 | | 公式识别 | 不支持，按官方口径需升级到标准模式 | 支持 | | 输出 | Markdown | Zip 结果包 + Markdown / JSON / 额外格式 |

轻量模式适用

  • 初次使用、快速试跑
  • 本地小文件
  • 远程 PDF / Doc / Ppt 链接
  • 不要求表格识别、公式识别

标准 API 适用

  • 大文件、长文档
  • 对表格、公式、复杂版面更敏感的场景
  • 网页 URL 提取
  • 希望获得更完整的结果包并保留更多中间结果

使用方法

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "/path/to/file.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js "https://example.com/article"
/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken

配置选项

编辑 .claude/skills/mineru-ocr/config/.env：

| 选项 | 默认值 | 说明 | | --------------------- | -------- | --------------- | | MINERU_API_TOKEN | 空 | 可选；填写后强制走标准 Token API | | MINERU_ENABLE_OCR | true | 启用 OCR | | MINERU_ENABLE_TABLE | true | 启用表格识别；主要对标准 Token API 生效 | | MINERU_ENABLE_FORMULA | false | 启用公式识别；主要对标准 Token API 生效 | | MINERU_LANGUAGE_CODE | ch | 语言代码 | | MINERU_API_BASE | https://mineru.net/api/v4 | 标准 API 地址 | | MINERU_MODEL_VERSION | pipeline | 标准 Token API 模型；法律文档建议默认 pipeline，复杂版面可改 vlm | | MINERU_PAGE_RANGES | 空 | 标准 Token API 页码范围，如 1-20、2,4-6 | | MINERU_POLL_MAX | 20 | 最大轮询次数 | | MINERU_POLL_SLEEP | 10 | 轮询间隔（秒） | | MINERU_LOG_LEVEL | medium | 日志等级 |

输出

  • 本地文件：Markdown 保存到源文件同目录
  • 远程文档 URL / 网页 URL：Markdown 默认保存到执行命令时的当前目录
  • 归档：.claude/skills/mineru-ocr/archive/日期_时间_文件名/
  • 归档内容：转换得到的 Markdown、接口响应、原始输入文件，以及可下载的图片资源清单

法律文档建议

  • 默认保持 MINERU_MODEL_VERSION=pipeline
  • 对起诉状、证据目录、法院通知、传票这类正式材料，优先追求稳定和低幻觉风险，不建议默认改成 vlm
  • 只有在扫描质量差、版面极复杂、表格密集时，再考虑切到 vlm
  • 如果只需要先看卷宗前几页，可设置 MINERU_PAGE_RANGES=1-20

Token 自检

当你想确认当前 Token 是否有效时，可运行：

/usr/bin/osascript -l JavaScript .claude/skills/mineru-ocr/scripts/convert.js checktoken
  • 未配置 Token：会提示当前处于轻量模式
  • Token 有效：会提示标准 API 可用
  • Token 失效：会明确提示重新申请与更新

云端模式 / 自定义地址

当前 skill 仅面向 官方云端 API。

如需走你自己的云端转发网关，且该网关 兼容官方 v4 API，可在 .env 中修改：

MINERU_API_BASE=https://your-gateway.example.com/api/v4

当前脚本默认适配的是官方云端 v4 API 工作流。

如果你部署的是官方 mineru-api / mineru-router FastAPI 服务，它们主要暴露的是 /tasks、/file_parse 等接口，不在本 skill 当前支持范围内。这类场景建议：

  • 优先使用官方 CLI / SDK 直连自建服务
  • 本 skill 继续只维护云端模式，避免混入第二套协议

关于官方 Crawl

官方 skill 中的网页提取主要是通过 CLI 的 mineru-open-api crawl <url> 实现的，属于 Token 模式能力，不是轻量接口能力。

这里的 CLI 是 官方提供的命令行封装层。CLI 底层仍然会调用 MinerU 的云端 API；它不是本地离线解析器。

你当前这个 skill 现在也支持网页 URL，但仅在 已配置 Token 时启用；未配置 Token 时，网页 URL 会提示用户改用标准 API。

故障排除

| 问题 | 解决方案 | | ---------------- | ---------------------------------------------- | | 轻量接口限频 | 稍后重试，或配置 Token 切换到标准 API | | 文件过大 / 页数过多 | 配置 Token，改走标准 API | | 网页 URL 无法轻量解析 | 轻量接口不支持 HTML，请配置 Token | | 401/Unauthorized | Token 已过期，重新申请并更新 | | 转换超时 | 增加 MINERU_POLL_MAX 或检查文件大小 | | 配额不足 | 检查 MinerU 账户额度 |