MinerU Doc To Markdown

当用户要把文档转成 Markdown 时，优先使用这个 skill，而不是手写一堆临时请求。

什么时候用

• 输入是 pdf、doc、docx、ppt、pptx、图片或 html
• 目标是拿到可继续编辑、总结或喂给 LLM 的 Markdown
• 需要保留比普通 OCR 更稳定的结构化结果
• 用户希望同一套 skill 同时兼容“有 token 的高精度模式”和“无 token 的轻量模式”

不要什么时候用

• 用户只是要总结已经贴出的文本
• 用户明确要求使用别的转换链路
• 输入是 xlsx/csv 一类表格文件，这个 skill 不覆盖

运行前检查

1. 如果存在 MINERU_API_TOKEN，默认走精准解析 API；没有则自动走免 token 的 Agent API
2. 判断输入是本地文件还是远程 URL，不要在一次命令里混用
3. 默认输出到当前工作目录下的 outputs/mineru/
4. 日志输出到当前工作目录下的 logs/mineru_markdown.log

推荐命令

单个本地文件：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf

批量本地文件：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./a.pdf ./b.docx

远程 URL：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"

指定输出目录：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --output-dir ./outputs/custom

强制使用轻量免 token 模式：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --mode agent

强制使用精准解析模式：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --mode precise

工作方式

精准解析模式

触发条件：

• 明确指定 --mode precise
• 或存在 MINERU_API_TOKEN 且未指定 --mode

本地文件：

1. 调 POST /api/v4/file-urls/batch 申请上传地址
2. 对每个地址执行 PUT
3. 轮询 GET /api/v4/extract-results/batch/{batch_id}
4. 下载 full_zip_url
5. 从 zip 中提取 full.md

远程 URL：

1. 调 POST /api/v4/extract/task/batch
2. 轮询 GET /api/v4/extract-results/batch/{batch_id}
3. 下载 full_zip_url
4. 从 zip 中提取 full.md

轻量 Agent 模式

触发条件：

• 明确指定 --mode agent
• 或未提供 token 且未指定 --mode

本地文件：

1. 调 POST /api/v1/agent/parse/file
2. 上传返回的 file_url
3. 轮询 GET /api/v1/agent/parse/{task_id}
4. 下载 markdown_url

远程 URL：

1. 调 POST /api/v1/agent/parse/url
2. 轮询 GET /api/v1/agent/parse/{task_id}
3. 下载 markdown_url

结果处理约定

• 成功后优先把 .md 路径告诉用户
• 如用户后续要继续分析，直接读取生成的 Markdown，不要再重复请求 MinerU
• 如果失败，优先汇报 MinerU 返回的错误信息
• 如果文档超过限制，建议拆分文档后重试

注意事项

• 默认模式是 auto
• auto 下优先精准解析，其次轻量 Agent
• 精准模式默认模型使用 vlm
• 本地文件和远程 URL 不要混传
• full.md 是主产物，.zip 保留用于排查或复用
• Agent 模式限制更严，适合轻量场景，不保证大文件一定成功
• 如果用户给了 token，只在当前执行环境中使用，不要写入代码、文档、日志示例或提交记录