Metadata-Version: 2.4
Name: mineru2md
Version: 0.1.1
Summary: 使用 MinerU API 将 PDF 文件转换为 Markdown 的命令行工具
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.34.2

# mineru2md

使用 [MinerU API](https://mineru.net) 将 PDF 文件转换为 Markdown 的命令行工具。

## 功能

- 🚀 单个命令将本地 PDF 转为 Markdown
- 🎯 支持 **免费模式**（无需 API Key，限制 10MB / 20 页）
- 🔑 支持 **精准解析模式**（配置 `MINERU_API_KEY` 后自动启用，最高支持 200MB / 600 页）
- 📁 输出 Markdown 文件默认与源 PDF 同名、同目录
- 🔄 自动重试（最多 3 次，指数退避）
- ⚡ 若目标 Markdown 已存在则跳过，避免重复转换

## 环境要求

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) 包管理工具（推荐），或 pip

## 安装

### 方式一：通过 uv 全局安装（推荐）

```bash
uv tool install mineru2md
```

### 方式二：通过 pip 安装

```bash
pip install mineru2md
```

### 方式三：从源码安装

```bash
git clone <repo-url>
cd mineru-cli
uv tool install .
```

安装成功后，`mineru` 命令即可在终端直接使用。

## 环境变量配置

| 变量名 | 必填 | 说明 |
| --- | --- | --- |
| `MINERU_API_KEY` | 否 | MinerU 精准解析 API 的 Token。未设置时使用免费 Agent API |

### 获取 API Key

1. 访问 [MinerU 官网](https://mineru.net) 注册/登录
2. 进入个人中心或 API 管理页面，申请 Token
3. 将 Token 设置为环境变量：

**macOS / Linux：**

```bash
export MINERU_API_KEY="your-api-token"
```

可将该行添加到 `~/.zshrc` 或 `~/.bashrc` 中持久化。

**Windows（PowerShell）：**

```powershell
$env:MINERU_API_KEY="your-api-token"
```

### 两种模式对比

| 维度 | 免费模式（无 API Key） | 精准解析模式（有 API Key） |
| --- | --- | --- |
| API 接口 | `/api/v1/agent` | `/api/v4` |
| 文件大小限制 | ≤ 10 MB | ≤ 200 MB |
| 页数限制 | ≤ 20 页 | ≤ 600 页 |
| 模型 | pipeline 轻量模型 | vlm 模型 |
| 输出格式 | Markdown | Zip 包（含 Markdown、JSON 等） |

## 使用方法

```bash
mineru <pdf路径> [-o 输出目录]
```

### 参数说明

| 参数 | 说明 |
| --- | --- |
| `pdf_path` | （必填）本地 PDF 文件路径 |
| `-o, --output-dir` | （可选）输出目录，默认为 PDF 文件所在目录 |

### 示例

```bash
# 基本用法：将 example.pdf 转为 example.md（输出到同目录）
mineru ./example.pdf

# 指定输出目录
mineru ./example.pdf -o ./output

# 配合环境变量使用精准解析
export MINERU_API_KEY="your-token"
mineru ./large-document.pdf
```

## 开发

```bash
# 克隆项目
git clone <repo-url>
cd mineru-cli

# 创建虚拟环境并安装依赖
uv sync

# 直接运行
python main.py ./example.pdf
```

## 技术栈

- Python 3.11+
- [requests](https://docs.python-requests.org/) — HTTP 客户端
- [uv](https://docs.astral.sh/uv/) — 包管理与构建

## License

MIT
