Skill

mineru-ocr

将本地文档、远程文档 URL 或网页 URL 转换为 Markdown。默认使用免登录轻量接口开箱即用；若已配置 MinerU Token，则自动切换到标准 API。保留 archive 回溯能力，并支持 Token 自检与私有部署连接说明。本技能应在用户需要 PDF 转 Markdown、OCR、远程文档转换、网页内容提取、表格识别、公式识别、文档转换、图片转文字、扫描件转换时使用。

npx claudepluginhub cat-xierluo/legal-skills --plugin minimax-image-understand

Tool Access

This skill uses the workspace's default tool permissions.

Preview

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

Supporting Assets

CHANGELOG.mdLICENSE.txtscripts/convert.js

SKILL.md

Similar Skills

to-markdown

221

Converts files and URLs to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube using MarkItDown with trafilatura/Playwright fetches. For LLM/RAG pipelines.

4 files

armory

document-conversion

242

Converts PDFs, DOCX, PPTX, XLSX, HTML, images, URLs, CSV, JSON, and more to markdown via tiered fallbacks: MCP markitdown, native tools, or user notice. For ingesting non-plain-text files.

3 files

leyline

paddle-ocr

179

面向法律 PDF 与扫描件的 PaddleOCR 结构化解析技能。默认将本地 PDF 或图片转换为 Markdown，并在技能内部保留可追溯 archive 归档。适用于卷宗、病历、证据材料、发票、财报、复杂扫描件、表格密集文档、公式与多栏版面。触发词包括：法律 PDF OCR、卷宗 OCR、病历 OCR、证据扫描件转 Markdown、PaddleOCR、表格识别、公式识别、版面分析、PDF 转 Markdown、复杂 PDF 解析。

10 files

legal-skills

Stats

Stars179

Forks29

Last CommitApr 1, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

MinerU PDF 转 Markdown

前置配置

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

免配置快速使用

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

升级到标准 API（可选）

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

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

申请 API Token

访问 https://mineru.net/apiManage/token
注册/登录账号
创建 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。

当前读取优先级为：

本 skill 的 .claude/skills/mineru-ocr/config/.env 中的 MINERU_API_TOKEN
环境变量 MINERU_API_TOKEN
环境变量 MINERU_TOKEN
官方 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 账户额度