文档解析与格式转换

技能文档

---
name: complex-doc-parser
description: 专业级文档解析与格式转换引擎。支持 PDF/Word/Excel/PPT/扫描件的高精度结构化提取，自动清洗噪声，智能处理合并单元格；同时支持多种格式互转：Word/Excel/PPT/图片/Markdown 转 PDF，PDF 转 Word/Excel/Markdown。Word/Excel/PPT 转 PDF 优先调用真实 Office 渲染引擎（LibreOffice/MS Word/WPS）做保真转换，完整保留图片、表格与原始版式。当用户需要解析文档、提取表格、OCR识别、格式转换、Word转PDF、PDF转Word、Excel转PDF、PDF转Excel、图片转PDF、批量处理文件时触发此技能。
title: 文档解析与格式转换
category: 办公效率
---

# 文档解析与格式转换 v3.0

专业级文档解析与格式转换引擎，支持文档提取和格式互转两大核心功能。

## 核心能力

### 📄 文档解析

| 文件类型 | 处理能力 | 脚本 |
|---------|---------|------|
| PDF | 文本+表格提取、合并单元格检测、页眉页脚过滤 | `native_parse.py pdf` |
| Word | 段落+表格+标题层级提取 | `native_parse.py docx` |
| Excel | 多Sheet、合并单元格、HTML表格保留结构 | `excel_parse.py` |
| PPT | 幻灯片文本+表格提取 | `native_parse.py pptx` |
| 扫描件/图片 | OCR文字识别、图像预处理、版面分析 | `ocr_process.py` |

### 🔄 格式转换

| 转换类型 | 说明 |
|---------|------|
| **Word → PDF** | **默认保真转换**（LibreOffice/MS Word/WPS 引擎），保留图片、表格、字体、页眉页脚、精确版式；无引擎时降级近似渲染（.docx） |
| **Excel → PDF** | 默认保真转换（引擎），无引擎时降级多Sheet近似渲染 |
| **PPT → PDF** | 需要 LibreOffice 引擎，逐页完整保留图形与动画帧 |
| **图片 → PDF** | 自适应页面大小，保持原图比例，异常时自动清理临时文件 |
| **Markdown → PDF** | 标题、段落渲染，支持加粗/斜体/代码/列表/表格/链接/引用 |
| **PDF → Word** | 提取文本+表格，生成可编辑 Word |
| **PDF → Excel** | 提取表格，每个表格一个 Sheet，自动去重表名 |
| **PDF → Markdown** | 提取文本+表格，输出标准 Markdown，单元格内 \| 自动转义 |

### 保真转换引擎策略（v3.0）

Office 文档（Word/Excel/PPT）转 PDF 时，按以下顺序选择渲染引擎，确保输出与原文档**所见即所得**：

1. **LibreOffice**（首选）— 开源免费、跨平台，`soffice --headless --convert-to pdf`，保真度最高。
2. **Microsoft Word** — Windows 已安装 Office 时，通过 COM 自动化 `SaveAs PDF`。
3. **WPS Office** — 检测到但无稳定 CLI 导出接口，提示安装 LibreOffice。

> 无任何引擎时：`.docx/.xlsx/.pptx` 降级为 reportlab 近似渲染（会丢失图片与精确版式，结果中带 `note` 标注）；旧版 `.doc/.xls` 需安装 LibreOffice。

## 工作流

### 文档解析流程
1. **识别文件类型**：根据扩展名判断
2. **选择解析脚本**：
   - PDF/Word/PPT → `scripts/native_parse.py <type> <file_path>`
   - Excel → `scripts/excel_parse.py <file_path> [format]`
   - 图片/扫描件 → `scripts/ocr_process.py <image_path> [config_json]`
3. **后处理**：自动移除页眉页脚、校正表格结构
4. **输出结果**：返回干净的文本内容及解析摘要

### 格式转换流程
1. **识别转换需求**：根据输入/输出文件扩展名自动判断
2. **调用转换脚本**：
   ```bash
   python scripts/format_converter.py <input_path> [output_path] [conversion_type]
   # Office 文档可选直接调用保真转换器：
   python scripts/faithful_convert.py <input_path> <output.pdf>
   ```
3. **自动检测转换类型**：
   - `.doc/.docx` → `.pdf` = word_to_pdf（默认保真引擎）
   - `.xls/.xlsx` → `.pdf` = excel_to_pdf（默认保真引擎）
   - `.ppt/.pptx` → `.pdf` = ppt_to_pdf（需 LibreOffice）
   - `.png/.jpg` → `.pdf` = image_to_pdf
   - `.md` → `.pdf` = markdown_to_pdf
   - `.pdf` → `.docx` = pdf_to_word
   - `.pdf` → `.xlsx` = pdf_to_excel
   - `.pdf` → `.md` = pdf_to_markdown
4. **输出结果**：返回转换状态、输出文件路径与使用的引擎

### 批量处理
当用户提供多个文件时：
1. 遍历所有文件
2. 根据需求选择解析或转换
3. 汇总结果，按文件名分节输出

## 输出格式策略（解析功能）

| 场景 | 输出格式 | 说明 |
|-----|---------|------|
| 简单表格 | Markdown `|...|` | 无合并单元格时 |
| 复杂表格 | HTML `<table>` | 有合并单元格时 |
| 纯文本 | Markdown | 默认格式 |
| 用户指定 | 按用户要求 | `--format=html/markdown` |

## 关键约束

1. **禁止幻觉**：严禁编造文档中不存在的内容。模糊不清处标注 `[Unclear]`。
2. **表格优先**：保留文档中的表格结构，不转为纯文本。
3. **噪声过滤**：自动移除页眉页脚、页码、重复文本。
4. **Token 控制**：超过 50 页的文档按章节分片，每片不超过 2000 Tokens。
5. **错误恢复**：解析失败时尝试降级处理。

## 错误处理

| 错误类型 | 处理方式 |
|---------|---------|
| 文件不存在 | 返回错误信息 |
| 格式不支持 | 提示支持的格式列表 |
| 解析失败 | 返回错误详情 |
| OCR 引擎缺失 | 提示安装 pytesseract 或 paddleocr |
| 转换依赖缺失 | 提示安装相应依赖 |
| 无文档渲染引擎 | 提示安装 LibreOffice，或对 .docx 降级近似渲染 |
| 合并单元格异常 | 降级为普通表格 |

## 参考文档

- `references/table_rules.md` - 高级表格还原规则
- `references/ocr_config.md` - OCR 参数配置指南
- `references/output_format.md` - 输出格式规范

## 使用说明

### 调用方式

所有脚本通过命令行调用，统一以 JSON 输出结果（`status` 表示成功/失败，`content` 携带解析内容，`message` 携带错误信息）。脚本位于 `scripts/` 目录，需在工作目录或脚本所在目录执行。

| 场景 | 命令 |
|------|------|
| 解析 PDF / Word / PPT | `python scripts/native_parse.py <pdf\|docx\|pptx> <file>` |
| 解析 Excel | `python scripts/excel_parse.py <file> [markdown\|html\|auto]` |
| OCR 识别扫描件/图片 | `python scripts/ocr_process.py <image> [config_json]` |
| 格式互转（自动识别类型） | `python scripts/format_converter.py <input> [output] [conversion_type]` |
| 保真转换（Office→PDF） | `python scripts/faithful_convert.py <input> [output.pdf] [--force-reportlab]` |

### 输出约定

1. **解析成功**：返回 `{"status": "success", "content": "...", "type": "pdf|docx|pptx|excel"}`，`content` 为清洗后的 Markdown/HTML 文本。
2. **转换成功**：返回 `{"status": "success", "output": "<产物路径>", "conversion": "<转换类型>"}`，Office 类保真转换额外带 `engine` 与 `note` 字段。
3. **失败**：返回 `{"status": "error", "message": "<原因>"}`；文件不存在、格式不支持、依赖缺失均返回此结构。

### 关键规则

1. **禁止幻觉**：解析内容缺失或模糊时标注 `[Unclear]`，严禁编造文档中不存在的内容。
2. **表格优先**：保留表格结构；简单表格输出 Markdown，含合并单元格的表格输出 HTML `<table>`。
3. **转换优先级**：Office→PDF 自动走保真引擎（LibreOffice > MS Word > WPS），无引擎时降级 reportlab 近似渲染并在结果中标注 `note`。
4. **Token 控制**：超过 50 页的文档按章节分片，每片不超过 2000 Tokens。

## 使用示例

### 解析文档
```bash
# 解析 PDF
python scripts/native_parse.py pdf document.pdf

# 解析 Word
python scripts/native_parse.py docx report.docx

# 解析 Excel（指定 HTML 输出）
python scripts/excel_parse.py data.xlsx html

# 解析 PPT
python scripts/native_parse.py pptx presentation.pptx

# OCR 识别
python scripts/ocr_process.py scan.png
```

### 格式转换
```bash
# Word 转 PDF（自动保真转换，保留图片/表格/版式）
python scripts/format_converter.py document.docx output.pdf
python scripts/format_converter.py document.doc output.pdf

# 保真转换（可直接调用，指定引擎）
python scripts/faithful_convert.py document.doc output.pdf

# Excel 转 PDF
python scripts/format_converter.py data.xlsx data.pdf

# PPT 转 PDF（需 LibreOffice）
python scripts/format_converter.py slides.pptx slides.pdf

# 图片转 PDF
python scripts/format_converter.py image.png image.pdf

# Markdown 转 PDF
python scripts/format_converter.py readme.md readme.pdf

# PDF 转 Word
python scripts/format_converter.py document.pdf output.docx

# PDF 转 Excel（提取表格）
python scripts/format_converter.py document.pdf tables.xlsx

# PDF 转 Markdown
python scripts/format_converter.py document.pdf output.md
```

## 依赖安装

```bash
# Python 基础依赖
pip install -r requirements.txt

# 保真转换引擎（推荐安装，图片/表格/版式 100% 还原）
# Windows:
winget install --id TheDocumentFoundation.LibreOffice
# macOS:
brew install --cask libreoffice
# 或安装 Microsoft Office / WPS Office（自动检测）
```

使用说明

# Complex Doc Parser v3.0

## 📖 简介

**文档解析与格式转换** 是一个专业级文档解析与格式转换技能（Skill），支持 PDF/Word/Excel/PPT 及扫描件的高精度结构化提取，同时支持多种格式互转功能。**v3.0 新增保真转换引擎**：Word/Excel/PPT 转 PDF 优先调用真实 Office 渲染引擎，完整保留图片、表格、字体与原始版式。

## ✨ 核心功能

### 🔄 格式转换

| 转换方向 | 支持类型 | 特性 |
|---------|---------|------|
| **→ PDF** | Word / Excel / PPT / 图片 / Markdown | 保真引擎转换，保留图片、表格、版式 |
| **PDF →** | Word / Excel / Markdown | 提取文本+表格，生成可编辑文件 |

#### 详细转换能力
- **Word → PDF**：v3.0 默认走保真引擎（LibreOffice/MS Word/WPS），图片、表格、字体、页眉页脚、分页与 Word 中显示一致
- **Excel → PDF**：多Sheet转换、表格样式保留、横向排版
- **PPT → PDF**：需 LibreOffice，逐页完整还原
- **图片 → PDF**：自适应页面大小，保持原图比例
- **Markdown → PDF**：标题、段落渲染，支持中文
- **PDF → Word**：提取文本+表格，生成可编辑 Word 文档
- **PDF → Excel**：提取表格，每个表格一个 Sheet
- **PDF → Markdown**：提取文本+表格，输出标准 Markdown

### 📄 文档解析

| 功能 | 说明 |
|------|------|
| 📄 多格式解析 | PDF / Word / Excel / PPT / 图片 |
| 📊 智能表格 | 自动检测合并单元格，Markdown/HTML 自适应 |
| 🧹 噪声清洗 | 自动移除页眉、页脚、页码 |
| 🔍 OCR 增强 | 图像预处理 + 文字识别 + 版面分析 |
| 📦 批量处理 | 多文件批量解析与转换 |

## 🚀 快速开始

### 安装依赖
```bash
pip install -r requirements.txt
```

### 使用方式

#### 格式转换

```bash
# Word 转 PDF（v3.0 默认保真转换，保留图片/表格/版式）
python scripts/format_converter.py document.docx output.pdf
python scripts/format_converter.py document.doc output.pdf

# 保真转换器（直接调用，自动探测 LibreOffice / MS Word / WPS）
python scripts/faithful_convert.py document.doc output.pdf

# Excel 转 PDF
python scripts/format_converter.py data.xlsx data.pdf

# PPT 转 PDF（需 LibreOffice）
python scripts/format_converter.py slides.pptx slides.pdf

# 图片转 PDF
python scripts/format_converter.py image.png image.pdf

# Markdown 转 PDF
python scripts/format_converter.py readme.md readme.pdf

# PDF 转 Word
python scripts/format_converter.py document.pdf output.docx

# PDF 转 Excel（提取表格）
python scripts/format_converter.py document.pdf tables.xlsx

# PDF 转 Markdown
python scripts/format_converter.py document.pdf output.md
```

#### 文档解析

```bash
# 解析 PDF
python scripts/native_parse.py pdf document.pdf

# 解析 Word
python scripts/native_parse.py docx report.docx

# 解析 Excel（指定 HTML 输出）
python scripts/excel_parse.py data.xlsx html

# 解析 PPT
python scripts/native_parse.py pptx slides.pptx

# OCR 识别
python scripts/ocr_process.py scan.png
```

## 📂 项目结构

```text
complex-doc-parser/
├── SKILL.md                    # 技能指令文件
├── README.md                   # 使用说明
├── requirements.txt            # Python 依赖
├── scripts/
│   ├── faithful_convert.py     # 保真转换器（v3.0 新增，LibreOffice/MS Word/WPS 引擎）
│   ├── native_parse.py         # PDF/Word/PPT 解析器
│   ├── excel_parse.py          # Excel 解析器（支持合并单元格）
│   ├── ocr_process.py          # OCR 处理器
│   └── format_converter.py     # 格式转换器（支持双向转换，自动路由保真/近似）
└── references/
    ├── table_rules.md          # 表格还原规则
    ├── ocr_config.md           # OCR 配置指南
    └── output_format.md        # 输出格式规范
```

## 📊 版本更新

### v3.0 (当前)
- ✨ **保真转换引擎**：Word/Excel/PPT 转 PDF 优先调用真实渲染引擎（LibreOffice / MS Word / WPS），完整保留图片、表格、字体、页眉页脚与精确版式，与原文档显示一致
- ✨ 新增 `scripts/faithful_convert.py` 独立保真转换器，自动探测本机引擎
- ✨ 修复旧版 `.doc`（WPS/Word 二进制格式）无法转换的问题
- ✨ 新增 PPT → PDF 转换（需 LibreOffice）
- ♻️ 无引擎时自动降级：`.docx/.xlsx` 走 reportlab 近似渲染并在结果中标注

### v2.3
- 🐛 修复格式转换时 XML 特殊字符（`<`、`>`、`&`）未转义导致 reportlab Paragraph 解析失败
- ✨ Markdown 转 PDF 支持完整语法：加粗、斜体、行内代码、无序/有序列表、表格、引用块、分割线、链接
- 🐛 修复 PDF 转 Markdown 表格单元格中 `|` 字符破坏表格结构，自动转义
- 🐛 修复 Image 转 PDF 异常时临时文件残留，改用 try/finally 确保清理
- 🐛 修复参差不齐的表格行导致转换异常，自动补齐
- 🐛 修复 PDF 转 Markdown 单行表格被跳过（`len(table) > 1` 条件）丢失数据
- 🐛 修复 PDF 转 Excel 重复 Sheet 名导致创建失败，自动去重
- ✨ Excel 转 PDF 增加中文字体支持
- ♻️ Word 转 PDF 将 import 移出循环，提升性能

### v2.2
- ✨ 新增 **PDF → Word** 转换
- ✨ 新增 **PDF → Excel** 转换（表格提取）
- ✨ 新增 **PDF → Markdown** 转换
- ✨ 支持更多格式互转

### v2.1
- ✨ 新增格式转换功能
- ✨ Word/Excel/图片/Markdown → PDF

### v2.0
- ✨ 新增 PPT 解析支持
- ✨ 集成真实 OCR 引擎
- ✨ 合并单元格自动检测
- ✨ 图像预处理

### v1.0
- 初始版本
- 支持 PDF/Word/Excel 解析

## 🛠️ 常见问题

**Q: PDF 转 Word 效果不好？**
A: PDF 转 Word 会尽量保留结构，但复杂的排版（如多栏、文字环绕图片）可能无法完美还原。建议转换后在 Word 中微调。

**Q: PDF 转 Excel 只能提取表格？**
A: 是的，PDF 转 Excel 专门用于提取表格数据。如果需要提取纯文本，请使用 PDF 转 Word 或 PDF 转 Markdown。

**Q: 格式转换失败？**
A: 确保已安装所有依赖：`pip install -r requirements.txt`

**Q: 中文显示异常？**
A: 系统需要安装中文字体。Windows 自带宋体，macOS 使用苹方。

## 📄 许可证

本项目仅供学习与研究使用。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。