pdf2md-agent-skill

English | 简体中文

让 LLM agent 高效读懂任何文档。 一条命令把 PDF / Word / PPT / Excel / HTML / CSV 转为结构化 Markdown。英文 PDF 使用 md_convert.py 智能分流；中文论文和中文扫描 PDF 使用独立的 md_convert_zh.py。

✨ 核心特性

• 📄 英文 PDF 智能分流：md_convert.py 逐页自动判断，文本页 PyMuPDF（快+免费）、公式页视觉 OCR（转 LaTeX）、扫描页 OCR
• 中文论文独立链路：md_convert_zh.py 用于中文正文为主的论文和中文扫描 PDF，可使用 Ark OCR，便于单独调试中文 OCR 与版面问题
• ⚡ 并行 OCR：所有 OCR 页先一次性分类预渲染，再并行调用视觉模型（默认并发 10），多篇公式页近似单页耗时而非逐页串行等待
• 🔢 公式转 LaTeX：学术论文公式从 Unicode 碎片 → 标准 LaTeX（\( A_i \sim P_{\pi,\mathcal{T}}(\cdot | E_{i-1}) \)），LLM 友好
• 📝 段落结构保留：按 block 合并成段落，非"一行一断"；双栏论文正确排序；自动过滤页眉页脚/水印
• 📦 全格式覆盖：PDF + docx/pptx/xlsx/html/csv/epub 等，一条命令统一处理
• 🤖 面向 agent 设计：作为 Claude Code skill 自动触发，无需你手动调用

🎯 效果对比

学术论文 PDF 提取

📸 实际效果

以下均为 examples/ 真实样本的转换输出片段，完整结果点击各链接查看。

PDF · 公式转 LaTeX

数学定义转写为标准 LaTeX（inline \( ... \)、行间 \[ ... \]），LLM 可直接理解：

**Definition 1 (Stochastic Agent System).** Let \( E_i \) be an environment state, a mixture of ... Let \( O_i \) and \( A_i \) be the \( i \)-th turn observation and action derived from distributions \( P \) and \( P_{\pi,\mathcal{T}} \), respectively, where \( \mathcal{T} \) indicates a tool set and \( \pi \) is an LLM policy.

\[ A_i \sim P_{\pi,\mathcal{T}}(\cdot | E_{i-1}, O_{i-1}), \quad O_i \sim P(\cdot | A_i, E_i), \quad E_i = h(E_{i-1}, O_{i-1}, A_i). \]

→ 完整输出 examples/sample_pdf.md（搜 Definition 1）

PDF · 双栏排序

双栏论文左栏整段在前、右栏整段在后，阅读顺序正确（pdfminer 会把两栏无关正文按行拼到同一行）：

expanded toolkit is 5.6 compared to the 2.7 (seemingly unrelated) tools in the original BFCL dataset, meaning that three semantically-related functions were added on average to each one of the 200 testcases. Next, we evaluate the FC performance of multiple agents using the generated benchmark.

3 Agentic FC Robustness Evaluation
3.1 Experimental Setup

...（左栏续：Models / Evaluation Approach / 3.2 Experimental Results …）...

is the humidity level in Miami,Florida in the upcoming 7 days?". The expected response includes the function weather.humidity_forecast() and validates its location parameter by exact match to one of the predefined values: ["Miami", "Miami, Florida", "FL"].

左栏讲 toolkit expansion、右栏讲 Miami humidity，两段无关正文被正确分栏而非交错拼接。→ examples/sample_twocol.md

中文论文

12 页中文论文：每页都是覆盖整页的位图，且隐藏文本层不可直接使用。

# 新移相角下双有源桥变换器的优化控制策略

**摘要**：电路结构简单且易于控制的典型隔离型双有源桥DAB(dual-active-bridge)变换器，在需要能量双向流动的场合被广泛应用。因此，研究如何提高变换器的工作效率尤为重要。

**关键词**：双有源桥；变换器；新移相角；优化控制

# 1 双有源桥的拓扑和工作原理

双有源桥双向变换器的拓扑结构如图1所示。图中：$U_p$为一次侧电压；$C_p$为一次侧电容；$i_p$为一次侧电流；$S_{p1} \sim S_{p4}$为一次侧开关管。

**图1 双有源桥双向变换器拓扑**
Fig.1 Topology of DAB bidirectional converter

# 2 新移相角下整流平均电流和传输功率的数学建模

定义$D_N=1-d_1$、$D_J=d_2-d_1/2$，此时$P^*=4D_ND_J$；当$0 \leq D_N \leq 1$且$0 \leq D_J \leq 1$时功率正向传输。

-> examples/sample_zh_dab.md

Word · 标题 / 列表结构保留

# 测试文档：Uncertainty Quantification 简介

## 1. 研究背景
不确定性量化（Uncertainty Quantification, UQ）是机器学习安全性的关键组件。大语言模型（LLM）在复杂任务中部署，需要可靠的 UQ 机制。

## 2. 主要方法
### 2.1 无序列表
* 基于概率的方法
* 基于一致性的方法
* 基于语言化的方法

### 2.2 有序列表
1. 数据收集
2. 模型训练
3. 不确定性估计
4. 结果评估

→ 完整输出 examples/sample_docx.md（含表格转换）

Excel · 多 sheet + 原值保留

每个 sheet 独立成章节。转换器不对生成后的 Markdown 做全局数字替换，避免误改文本中的版本号、料号或固定精度标识：

## 实验结果
| 方法 | 准确率 | AUROC | F1 |
| --- | --- | --- | --- |
| Baseline | 0.852 | 0.78 | 0.83 |
| Method A | 0.891 | 0.85 | 0.87 |
| Method B | 0.913 | 0.89 | 0.90 |

## 超参数
| 参数 | 值 | 说明 |
| --- | --- | --- |
| learning\_rate | 0.001 | 学习率 |
| batch\_size | 32.000 | 批大小 |
| epochs | 100.000 | 训练轮数 |

→ 完整输出 examples/sample_xlsx.md

🚀 快速开始

方式一：独立 CLI

# 1. 克隆并创建隔离环境
git clone https://github.com/taotaoboom/pdf2md-agent-skill.git
cd pdf2md-agent-skill
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt

# 2. 无 Key 快速体验：该双栏文本 PDF 全程本地转换
python3 scripts/md_convert.py examples/sample_twocol.pdf -o sample_twocol.md

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活环境，并可将 python3 替换为 py。

方式二：Claude Code skill

mkdir -p ~/.claude/skills
git clone https://github.com/taotaoboom/pdf2md-agent-skill.git \
  ~/.claude/skills/pdf2md-agent-skill
python3 -m pip install -r \
  ~/.claude/skills/pdf2md-agent-skill/requirements.txt

重启 Claude Code 后，可直接要求它阅读、总结或转换 PDF。

方式三：Codex skill

CODEX_SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$CODEX_SKILLS_DIR"
git clone https://github.com/taotaoboom/pdf2md-agent-skill.git \
  "$CODEX_SKILLS_DIR/pdf2md-agent-skill"
python3 -m pip install -r \
  "$CODEX_SKILLS_DIR/pdf2md-agent-skill/requirements.txt"

重启 Codex 后，可通过 $pdf2md-agent-skill 显式调用，也可在文档转换任务中自动触发。

可选：配置视觉 OCR

只有公式密集页、扫描页或文本提取为空的页面会调用视觉 OCR：

export ARK_API_KEY="your-ark-api-key"

# 转换
python3 scripts/md_convert.py paper.pdf -o paper.md

中文论文或中文扫描论文使用独立中文脚本；需要 OCR 时同样配置 ARK_API_KEY：

python3 scripts/md_convert_zh.py chinese-paper.pdf -o chinese-paper.md

🧭 PDF 脚本选择

md_convert.py 保留既有英文 PDF 的自动逐页分流和非 PDF 文档转换行为；md_convert_zh.py 仅用于中文 PDF 链路。

📋 支持格式

🔧 依赖说明

必需依赖

按格式可选（markitdown 后端）

一键安装全部：

python3 -m pip install -r requirements.txt

Python 版本

要求 Python 3.10+（markitdown 要求）。

⚙️ 配置

环境变量

默认视觉模型

当前默认使用火山方舟视觉模型 doubao-seed-1-6-flash-250828。它只在公式密集页、扫描页或空文本页触发视觉 OCR 时调用；普通文本页仍由 PyMuPDF 在本地处理。

可通过 -m/--model 覆盖默认模型：

python3 scripts/md_convert.py paper.pdf -o paper.md \
  --model YOUR_ARK_VISION_MODEL_ID

模型 ID 可能随平台更新而下线或更名。若 OCR 报模型不存在，请在火山方舟控制台选择当前可用的视觉模型。

获取 Ark API Key

1. 注册 火山方舟 平台
2. 创建 API Key
3. 配置：

   echo 'export ARK_API_KEY="your-key"' >> ~/.zshrc
   source ~/.zshrc
   

换用其他视觉模型：Ark 已验证。其他端点必须兼容 OpenAI Chat Completions、视觉输入和 data URL；可通过 ARK_BASE_URL 与 -m 尝试配置，但目前不声明 Azure 或本地 vLLM 已验证兼容。

📖 使用方法

命令行

# 英文 PDF（保留既有自动分流行为）
python3 scripts/md_convert.py paper.pdf -o paper.md

# 中文论文 / 中文扫描 PDF
python3 scripts/md_convert_zh.py chinese-paper.pdf -o chinese-paper.md

# 中文 PDF：强制全篇 Ark OCR，指定模型并调整并发
python3 scripts/md_convert_zh.py chinese-paper.pdf -o chinese-paper.md \
  --ocr -m MODEL_ID -j 10

# 中文 PDF：不导出独立内嵌图片或 assets
python3 scripts/md_convert_zh.py chinese-paper.pdf -o chinese-paper.md \
  --no-extract-images

# Word / PPT / Excel
python3 scripts/md_convert.py report.docx -o report.md
python3 scripts/md_convert.py slides.pptx -o slides.md
python3 scripts/md_convert.py data.xlsx -o data.md

# 强制全篇 OCR（确定是扫描件时，省去自动检测）
python3 scripts/md_convert.py scanned.pdf -o scanned.md --ocr

参数

中文脚本额外支持 --no-extract-images：不导出独立内嵌图片，也不创建对应的 assets 目录。中文脚本默认只导出论文中的独立内嵌图片；覆盖几乎整页的扫描底图会跳过，因为这类图片包含整页正文，应由 Ark OCR 识别而不是作为重复页面图片保存。

作为 Agent skill

安装到 Claude Code 或 Codex 对应的 skills 目录并重启后，agent 可在 PDF/文档转换任务中调用本 skill。Codex 也可以使用 $pdf2md-agent-skill 显式调用。

核心规则（写给 agent）：禁止用 Read 直接读 PDF，必须先转 Markdown 再读。

🧠 工作原理

PDF 智能分流

逐页分析：
  数学符号占比 ≥ 1.5%？ ──是──> 公式页 -> 视觉 OCR（转 LaTeX）
  文字稀少 + 有图片？    ──是──> 扫描页 -> 视觉 OCR
  否                     ──────> 文本页 -> PyMuPDF（段落合并+双栏排序+页眉过滤）

文本页用 PyMuPDF 秒转（免费），只有公式页和扫描页才调用视觉模型（收费），平衡质量与成本。

Office 格式

走 markitdown 原生路径；本 skill 不对 xlsx 生成的 Markdown 做全局数字替换，以免篡改文本值。pptx 图片可选 LLM 描述。

📂 文件结构

pdf2md-agent-skill/
├── SKILL.md            # Agent skill 定义
├── agents/openai.yaml  # Codex UI 元数据
├── README.md           # 本文件
├── README_EN.md        # English documentation
├── CHANGELOG.md        # 版本变更记录
├── LICENSE             # MIT
├── requirements.txt    # 依赖清单
├── .gitignore
├── examples/           # 示例输入输出
│   ├── README.md
│   ├── sample.docx / sample_docx.md
│   ├── sample.xlsx / sample_xlsx.md
│   ├── sample.pdf  / sample_pdf.md
│   ├── sample_twocol.pdf / sample_twocol.md
│   └── sample_zh_dab.pdf / sample_zh_dab.md
└── scripts/
    ├── md_convert.py      # 英文 PDF + 非 PDF 文档转换脚本
    └── md_convert_zh.py   # 中文论文 / 中文扫描 PDF 转换脚本

📄 许可证

MIT License - 详见 LICENSE