---
name: mineru-doc-to-markdown
description: 使用 MinerU 将 pdf、doc、docx、ppt、pptx、图片或 html 转成 Markdown。适用于用户要求把简历、JD、作品集或其他文档先转成 Markdown，再继续做总结、改写、问答、结构化提取或喂给其他工作流的场景。优先使用环境变量 MINERU_API_TOKEN 调用精准解析 API；如果未提供 token，则自动降级到免 token 的 Agent API。调用 bundled script 完成本地文件上传、远程 URL 解析、轮询和保存 Markdown。
---

# 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`

## 推荐命令

单个本地文件：

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

批量本地文件：

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

远程 URL：

```bash
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"
```

指定输出目录：

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

强制使用轻量免 token 模式：

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

强制使用精准解析模式：

```bash
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，只在当前执行环境中使用，不要写入代码、文档、日志示例或提交记录