---
name: isos-pdf2md
description: 将 PDF 文件转换为结构化 Markdown。使用 pdftotext 提取文本并后处理为标题、列表、表格、代码块等结构。触发：用户提到"PDF 转 Markdown"、"/isos-pdf2md"、或将 PDF 内容提取为可编辑格式。
---

# isos-pdf2md: PDF 转 Markdown 工具

将 PDF 文件转换为结构化 Markdown，用于项目文档处理。

## 触发条件

- 用户执行 `/isos-pdf2md`
- 用户提到"PDF 转 Markdown"、"提取 PDF 内容"、"PDF 变成 MD"
- 用户要求将 PDF 文件转为可编辑格式

## 使用方法

### 基本用法

```bash
# 由 Claude 调用脚本
/workspace/scripts/pdf2md.sh <input.pdf>
```

### 参数

| 参数 | 说明 |
|------|------|
| `-o FILE` | 输出文件路径（默认同名 `.md`，`-` 表示 stdout） |
| `-f N` | 起始页码 |
| `-l N` | 结束页码 |
| `--raw` | 跳过后处理，输出原始文本 |
| `--no-toc` | 不生成目录 |
| `-h` | 显示帮助 |

### 示例

```bash
# 基本转换
/workspace/scripts/pdf2md.sh docs/ref.pdf

# 指定输出路径
/workspace/scripts/pdf2md.sh docs/ref.pdf -o docs/ref.md

# 只转换前 10 页
/workspace/scripts/pdf2md.sh docs/ref.pdf -f 1 -l 10

# 输出到 stdout（适合管道）
/workspace/scripts/pdf2md.sh docs/ref.pdf -o -
```

## 工作流程

1. **验证输入**：检查 PDF 文件存在、pdftotext 已安装
2. **提取文本**：`pdftotext -layout -enc UTF-8 -nopgbrk` 提取带布局文本
3. **后处理**：Python 脚本识别结构并转为 Markdown：
   - 全大写短行 → `##` 标题
   - 短行 + 前空行 → `###` 标题
   - `- ` / `* ` / `* ` 开头 → 无序列表
   - `1.` 开头 → 有序列表
   - 连续缩进 >= 4 空格 → 代码块
   - 含 `|` 的行 → 表格
   - `---` 分隔线保留
4. **生成目录**：从 `##` 标题自动生成
5. **输出**：写入 .md 文件或 stdout

## 依赖

- `poppler-utils`（提供 `pdftotext` 命令）

## 已知限制

- 不支持扫描件/图片型 PDF（需 OCR）
- 复杂表格识别有限
- 多栏布局可能产生交错文本
- 不提取 PDF 中的图片

## 注意事项

- 转换完成后应读取输出文件，检查质量
- 如果输出不理想，可使用 `--raw` 获取原始文本后手动修正
- 对包含中文的 PDF，确保使用 `-enc UTF-8`（脚本已默认）