mineru-extract

用途

MinerU Extract 将 MinerU 作为上游的“内容规范化器”：向 MinerU 提交一个 URL，轮询任务完成状态，下载结果 zip，并提取其中的主 Markdown。它适用于把网页或文档链接转换为结构化 Markdown 文本。

主要能力

支持多种来源：HTML 页面（例如微信公众号文章），以及直接的 PDF、Office、图片链接。
提供两个脚本：
- 主脚本（MCP 风格）：scripts/mineru_parse_documents.py，输入为 --file-sources（逗号或换行分隔），输出为 stdout 上的 JSON 契约：{ ok, items, errors }。
- 底层脚本（单 URL）：scripts/mineru_extract.py。
默认模型启发式：URL 以 .pdf/.doc/.ppt/.png/.jpg 结尾时使用 pipeline，否则使用 MinerU-HTML（最适合 HTML 页面，如微信公众号文章）。
输出：脚本始终下载并解压 MinerU 结果 zip 到 ~/.openclaw/workspace/mineru/<task_id>/，写入 result.zip 以及解压后的文件（Markdown + JSON + 资源）。同时向 stderr 打印包含路径的 JSON 摘要：task_id、full_zip_url、out_dir、markdown_path。

使用方式

1) 配置 token（技能本地）

将密钥放入技能根目录的 .env（不要粘贴到聊天输出中）：

# In the mineru-extract skill directory: .env
MINERU_TOKEN=your_token_here
MINERU_API_BASE=https://mineru.net

认证：设置 MINERU_TOKEN（来自 mineru.net 的 Bearer token）。

2) 解析 URL → Markdown（推荐）

MCP 风格包装器（返回 JSON，可选包含 markdown 文本）：

python3 mineru-extract/scripts/mineru_parse_documents.py \
  --file-sources "<URL1>\n<URL2>" \
  --language ch \
  --enable-ocr \
  --model-version MinerU-HTML

如果希望 markdown 内容内联在 JSON 中（可能很大）：

python3 mineru-extract/scripts/mineru_parse_documents.py \
  --file-sources "<URL>" \
  --model-version MinerU-HTML \
  --emit-markdown --max-chars 20000

底层用法（单 URL，将 markdown 打印到 stdout）：

python3 mineru-extract/scripts/mineru_extract.py "<URL>" --model MinerU-HTML --print > /tmp/out.md

常用参数

--model: pipeline | vlm | MinerU-HTML（HTML 需要 MinerU-HTML）
--ocr/--no-ocr: 启用 OCR（对 pipeline/vlm 有效）
--table/--no-table: 表格识别
--formula/--no-formula: 公式识别
--language ch|en|...
--page-ranges "2,4-6"（非 HTML）
--timeout 600 / --poll-interval 2

适用场景

将微信公众号文章等 HTML 页面转换为 Markdown。
将 PDF、Office、图片链接解析为 Markdown。
需要批量提交多个 URL 并获取结构化 JSON 结果的流程。

限制与失败处理

MinerU 可能无法抓取某些 URL（反爬 / 地域 / 登录限制）。
回退方案：提供 HTML 文件或 PDF/长截图，然后使用 MinerU 批量上传端点实现“上传 + 解析”流程。
始终报告失败的 URL 和 MinerU 的 err_msg，并在输出中保留原始来源链接。

参考

MinerU API 文档：https://mineru.net/apiManage/docs
MinerU 输出文件说明：https://opendatalab.github.io/MinerU/reference/output_files/