河洛文档格式转换器

在 Markdown、Word(.docx)、PDF、PowerPoint(.pptx)、Excel(.xlsx/.xls/.csv) 五种格式之间互转文档（十八向全覆盖），转换后排版精美、结构清晰，支持五种内置样式主题。

核心特性：纯本地处理，不上传任何文件到外部服务，适合处理含敏感信息的文档。转换后表格自动按内容比例分配列宽并自动换行，避免内容重叠。PPT 转换自动按标题层级分页，应用样式主题配色。Excel 转换支持多 Sheet、自动截断超长表格。

快速开始

python scripts/convert.py <输入文件> <目标格式> [--output <输出文件>] [--style <样式名>]

支持的十八种转换方向

样式主题

MD→Word、MD→PDF、MD→PPT、Word→PDF、Word→PPT、PDF→Word、PDF→PPT、PPT→PDF、PPT→Word、Excel→PDF、XLS→PDF、CSV→PDF 支持 --style / -s 参数：

• default — 蓝灰专业风（通用报告）
• elegant — 暖色学术风，宽边距（学术/正式文档）
• modern — 紫色科技风，紧凑排版（技术文档）
• classic — 棕色经典风，大字号（法律/正式报告）
• minimal — 黑白极简风（极简主义文档）

详见 references/styles.md。

能力边界

适用于

• Markdown 文档转 Word/PDF/PPT（含标题、段落、代码块、表格、列表、引用、图片）
• Word(.docx) 转 Markdown（提取标题、表格、列表、加粗/斜体、引用）
• Word(.docx) 转 PDF/PPT（提取结构化块后重新排版）
• PDF 转 Markdown（提取文字、表格、图片，自动识别标题层级）
• PDF 转 Word/PPT（提取结构化块后重新排版）
• PowerPoint(.pptx) 转 Markdown（提取标题、正文、表格、图片）
• PowerPoint(.pptx) 转 PDF/Word（重新排版为精美文档）
• Excel(.xlsx) 转 PDF/Markdown（多 Sheet 支持，每 Sheet 一个标题+表格）
• Excel 97(.xls) 转 PDF/Markdown
• CSV 转 PDF/Markdown（自动检测编码和分隔符）
• 五种样式主题一键切换
• 表格按内容比例自动分配列宽，长内容自动换行，不重叠
• PPT 自动按 H1/H2 标题分页，每页内容自适应排版
• Excel 超 5000 行工作表自动截断防内存溢出

不适用于

• PPT 美化设计 — 本技能生成结构化 PPT，不支持动画、母版设计、复杂排版美化，请使用 pptx 或 heluo-ppt-gen 技能
• PDF 内容编辑 — 本技能不支持修改已有 PDF 内容
• OCR 识别 — 扫描件 PDF 无文字层时无法提取文字，请使用 paddleocr-doc-parsing 技能
• 图片转文字 — 请使用 OCR 相关技能
• Excel 复杂操作 — 本技能仅支持 Excel 转 PDF/Markdown（提取数据为表格），不支持公式计算、图表生成、数据透视表等操作，请使用 xlsx 技能
• HTML 文件转换 — 暂不支持 HTML 作为输入/输出

灰色地带

• 加密 PDF：会检测并提示输入密码，不自动破解
• 超大文件（>50MB）：可处理但耗时较长，建议拆分后转换
• 嵌套列表：支持一级嵌套，深层嵌套会扁平化处理
• 复杂表格（合并单元格）：DOCX→MD/PPT 和 PPT→MD 时合并单元格会拆分为独立单元格
• PPT 动画与母版：转出 PPT 不含动画、切换效果或母版设计；转入时忽略这些元素
• PPT 精度：PPT→其他格式时，SmartArt、图表、嵌入对象等高级元素不提取
• Excel 公式：读取 .xlsx 时 data_only=True，仅提取计算结果值而非公式本身；未在 Excel 中打开过的文件公式单元格可能返回 None
• Excel 图表/图片：不提取 Excel 内嵌图表和图片，仅提取单元格数据
• 超长 Excel 表：单 Sheet 超过 5000 行自动截断并附加提示，避免内存溢出

自然语言触发示例

用户说以下内容时自动触发本技能：

依赖与环境

脚本自动检测并安装以下 Python 包：

pip install python-docx reportlab pymupdf markdown python-pptx openpyxl xlrd

Excel 读取依赖说明：
- openpyxl：读取 .xlsx 文件（MIT 许可证）
- xlrd：读取 .xls 文件（Excel 97-2003 格式，BSD 许可证）
- csv：读取 .csv 文件（Python 内置，无需安装）

系统字体自动检测：
- Windows：宋体(SimSun)、微软雅黑(Microsoft YaHei)、黑体(SimHei)
- Linux：Noto Sans CJK、文泉驿正黑
- 如果未找到 CJK 字体，回退到 Helvetica 并在输出中标注"CJK字体缺失"

> ⚠️ 国内合规提示：本技能所有处理均在本地完成，不上传文件到任何外部服务，适合处理含敏感信息的文档。依赖的 Python 包均为开源项目（python-docx MIT、reportlab BSD、pymupdf AGPL/商业、markdown BSD、python-pptx MIT、openpyxl MIT、xlrd BSD），可通过 pip show <包名> 查看许可证。

工作流程

核心架构：统一中间表示（结构化块）

所有转换方向共享一套“结构化块”中间表示（MarkdownBlock），每种格式先解析为块列表，再将块列表渲染为目标格式。这确保了六向转换的排版一致性和代码复用。

输入文件 → [解析为结构化块列表] → [渲染为目标格式] → 输出文件
             ↑ MarkdownBlock ↑
   支持：heading/paragraph/code/table/list/quote/hr/image

MD→Word / PDF / PPT

1. 读取源 Markdown 文件（自动检测 UTF-8 / GBK / GB2312 编码）
2. 解析为结构化块（标题、段落、代码、表格、列表、引用、图片、分隔线）
3. 应用选定的样式主题（颜色、字体、间距、表格样式）
4. 生成输出文件：
   - 标题带颜色强调和底部边框线（h1/h2）
   - 代码块带灰色背景和等宽字体
   - 表格带主题色表头和隔行底色 + 按内容比例分配列宽 + 自动换行
   - 引用块带左侧强调线和浅色背景
   - PDF 含页边距、行距和页脚页码
   - PPT 按 H1/H2 标题自动分页，每页含标题栏+内容区，表格单独放置
5. 保存输出文件并验证文件有效性

Word→Markdown

1. 用 python-docx 打开 .docx 文件
2. 按文档顺序遍历段落和表格（保持原始顺序交错）
3. 映射段落样式到 Markdown 结构化块
4. 表格转换为 Markdown 管道表格
5. 写入 .md 文件

Word→PDF / PPT

1. 用 python-docx 打开 .docx 文件
2. 解析为结构化块列表（标题、段落、表格、列表、引用）
3. 用 ReportLab 生成精美 PDF 或用 python-pptx 生成 PPT（应用样式主题、表格列宽分配、自动换行）

PDF→Markdown

1. 用 PyMuPDF(fitz) 打开 PDF
2. 前置检查：检测 PDF 是否加密、是否有文字层（扫描件检测）
3. 逐页提取文字，通过字体大小自动识别标题层级
4. 尝试提取表格（PyMuPDF 内置表格检测）
5. 提取图片到伴随的 _images/ 目录
6. 后处理：清理空白行、移除页码噪音、识别中文章节标记（第X章/节）
7. 写入 .md 文件

PDF→Word / PPT

1. 用 PyMuPDF 打开 PDF，执行加密/扫描件前置检查
2. 逐页提取文字（字体大小识别标题层级）、表格、图片，解析为结构化块列表
3. 后处理：清理页码噪音、空行
4. 用 python-docx 生成精美 DOCX 或用 python-pptx 生成 PPT（应用样式主题、表格列宽分配、自动换行）

PPT→Markdown

1. 用 python-pptx 打开 .pptx 文件
2. 按幻灯片顺序遍历每张幻灯片的形状（shape）
3. 根据形状类型提取内容：文本框（标题/正文）、表格（管道表格）、图片（提取到 _images/）
4. 字号≥24pt 的文本识别为标题，其余为正文
5. 写入 .md 文件

PPT→PDF / Word

1. 用 python-pptx 打开 .pptx 文件，解析为结构化块列表
2. 用 ReportLab 生成精美 PDF 或用 python-docx 生成 Word（应用样式主题、表格列宽分配、自动换行）

Excel→PDF / Markdown

1. 根据文件后缀选择读取方式：.xlsx 用 openpyxl，.xls 用 xlrd，.csv 用内置 csv 模块
2. 逐 Sheet 读取数据，每 Sheet 转换为：H1 标题块（Sheet 名）+ table 块（二维数据列表）
3. 多 Sheet 之间用 hr 分隔线隔开
4. 超 5000 行的 Sheet 自动截断并附加提示引用块
5. PDF 方向：复用 _blocks_to_pdf 管道，应用样式主题、表格列宽按内容比例分配
6. MD 方向：复用 _blocks_to_md_text 序列化为 Markdown 管道表格
7. CSV 自动检测编码（UTF-8/GBK/GB18030/Latin-1）和分隔符（逗号/分号/制表符）

命令行用法

# Markdown 转 Word，使用学术样式
python scripts/convert.py input.md docx --style elegant

# Markdown 转 PDF，使用科技样式
python scripts/convert.py input.md pdf --style modern

# Markdown 转 PPT，使用科技样式
python scripts/convert.py input.md pptx --style modern

# Word 转 Markdown
python scripts/convert.py input.docx md -o output.md

# Word 转 PDF
python scripts/convert.py input.docx pdf --style elegant

# Word 转 PPT
python scripts/convert.py input.docx pptx --style default

# PDF 转 Markdown
python scripts/convert.py input.pdf md -o output.md

# PDF 转 Word
python scripts/convert.py input.pdf docx --style default

# PDF 转 PPT
python scripts/convert.py input.pdf pptx --style elegant

# PPT 转 Markdown
python scripts/convert.py input.pptx md -o output.md

# PPT 转 PDF
python scripts/convert.py input.pptx pdf --style elegant

# PPT 转 Word
python scripts/convert.py input.pptx docx --style default

# Excel 转 PDF，使用学术样式
python scripts/convert.py data.xlsx pdf --style elegant

# Excel 转 Markdown
python scripts/convert.py data.xlsx md -o result.md

# CSV 转 PDF
python scripts/convert.py data.csv pdf --style modern

# CSV 转 Markdown
python scripts/convert.py data.csv md -o result.md

模块导入

import sys
sys.path.insert(0, 'scripts')
from convert import convert

# 返回输出文件路径
result = convert('report.md', 'pdf', style_name='elegant')
result = convert('report.md', 'pptx', style_name='modern')
result = convert('document.docx', 'md')
result = convert('slides.pptx', 'pdf', style_name='elegant')
result = convert('paper.pdf', 'docx', output_file='result.docx')
result = convert('data.xlsx', 'pdf', style_name='elegant')
result = convert('data.xlsx', 'md', output_file='result.md')
result = convert('data.csv', 'pdf', style_name='modern')

自定义样式

在 scripts/convert.py 的 STYLES 字典中添加新条目：

"my-theme": {
    "primary_color": "#1a1a2e",
    "accent_color": "#e94560",
    "heading_color": "#1a1a2e",
    "text_color": "#2c2c2c",
    "bg_color": "#ffffff",
    "code_bg": "#f5f5f5",
    "border_color": "#e0e0e0",
    "quote_color": "#7f8c8d",
    "quote_border": "#e94560",
    "link_color": "#e94560",
    "table_header_bg": "#e94560",
    "table_row_alt_bg": "#fdf2f4",
    "font_size": 11,
    "heading_scale": 1.25,
    "line_height": 1.6,
    "margin": 2.5,
},

然后使用 --style my-theme。

输出验证

每次转换完成后自动执行以下验证：

1. 文件存在检查：输出文件是否成功创建
2. 文件大小检查：输出文件 > 0 字节
3. 格式有效性检查：
   - DOCX：验证可被 python-docx 重新打开
   - PDF：验证文件头为 %PDF
   - MD：验证可被 UTF-8 解码
   - PPTX：验证可被 python-pptx 重新打开并读取幻灯片数量
   - Excel 转 PDF/MD：验证 PDF 文件头或 MD 可被 UTF-8 解码
4. 空结果检测：如果输出内容为空或极少（<10 字符），输出警告

验证失败时返回非零退出码和诊断信息。

常见问题速查

> 详细故障排除、错误码说明和反模式请见 references/troubleshooting.md。

目录结构

doc-converter/
├── SKILL.md                    # 本文件 — 技能说明与使用指南
├── scripts/
│   └── convert.py             # 主转换脚本（十八种方向）
└── references/
    ├── styles.md              # 五种样式主题详细规格
    └── troubleshooting.md     # 错误码、故障排除、反模式与FAQ

> 📌 渐进式披露：本文件提供快速上手的全部信息。当遇到错误或需要深入了解时，按需查阅 references/troubleshooting.md；需要自定义样式细节时查阅 references/styles.md。

```