文档转Markdown

技能文档

---
name: make-to-markdown-cn
title: 文档转Markdown
category: 办公效率
description: 使用markitdown将PDF、Word、PPT、Excel、图片、音频等20+种格式一键转换为RAG就绪的Markdown。当用户需要转换文档格式、将文件转为Markdown、批量转换文档时触发。触发词：转Markdown、转换文档、文档转md、批量转换。
---

# 文档转Markdown

> **分级导航**：L1=摘要（本段）→ L2=红线+流程+命令速查（§⛔/§1-§3）→ L3=完整运维细节（[REFERENCE.md](REFERENCE.md)）

## 技能工作流

### 步骤1：⛔ 核心红线 (Critical Constraints)

1. **源文件零修改**：转换过程只读操作。所有中间产物写入临时目录，完成后不保留可关联回源文件的痕迹。
2. **输出覆盖确认**：`-o` 输出文件已存在时必须暂停确认，禁止静默覆写。
3. **加密文档不重试**：检测到加密（`File is encrypted`）立即终止，提示用户解密后重试。
4. **旧格式无预处理环境阻断**：`.doc`/`.ppt` 且 COM 和 LibreOffice 均不可用时，暂停告知用户安装 Office 或 LibreOffice，禁止静默跳过。
5. **禁止绕过 convert.py**：所有转换必须经由 `scripts/convert.py` 统一入口。禁止裸调 `markitdown` / `uvx markitdown` / 原生库。
6. **禁止外部 API 泄露**：转换全程本地执行，禁止上传文档内容至任何外部 API。
7. **网络驱动器 + 执行器约束**：Windows 网络驱动器（如 `E:\Marvis_Data`）路径优先用 `python_executor`，脚本内部 `pathlib.Path` 自动适配平台。
8. **系统破坏操作禁令 (HARB)**：`rm -rf` / `diskpart clean` / `DROP TABLE` / `git reset --hard` 等破坏性命令不得自动执行，必须输出完整预览并等待用户确认。
9. **输出 UTF-8 + 批量确认 + 禁循环清洗**：输出必须 UTF-8 无乱码；批量转换前确认源/目标路径+数量+格式；禁止 `post_clean.py`↔`convert.py` 循环清洗。

> 完整禁令细则及 HARB 黑名单详见 [REFERENCE.md §4](REFERENCE.md)。

核心入口：`scripts/convert.py`。零人工干预：`依赖检测 → uv 安装 extras → 转换 → 降级兜底 → 后置清洗 → 输出`。

🟢 **最小可用示例**：`python scripts/convert.py input.docx`。版本自查：`python scripts/convert.py --version`。

## 1. 核心执行流程

只需调用一次 `scripts/convert.py`，脚本内部自动完成：

```
(.doc/.ppt?)→预处理为 .docx/.pptx → 依赖检测 → 自动安装 → markitdown → (失败)原生降级 → 后置清洗 → 输出
```

| 步骤 | 说明 |
|------|------|
| 预处理 | `.doc`/`.ppt` 自动转为 `.docx`/`.pptx`（见 §2.5） |
| 依赖 | 按扩展名自动检测+安装缺失 Python 模块，120s 超时 |
| markitdown extras | 自动补全可选依赖，pypdf 已就绪则跳过 |
| markitdown 转换 | CLI 调用 |
| 降级兜底 | 失败时自动切换 python-docx/openpyxl/python-pptx |
| 后置清洗 | 内联执行：去水印+页码+标题修复+表格补全+摘要注入 |
| 结果反馈 | 输出路径 + H 标题统计 + 表格计数 + 转换方式 |

## 1.1 Init-Step-Poll 渐进式防卡死协议

单个小文件可直接调用 `scripts/convert.py`。批量转换、大文件、网络驱动器文件、旧格式 `.doc/.ppt`、含 OCR/音频/ZIP 的慢转换任务，必须采用 Init → Step → Poll 渐进式执行，避免长时间转换卡死或失败文件被静默吞掉。

| 阶段 | 动作 | 输出 | 失败回退 |
|:---|:---|:---|:---|
| Init | 确认源路径、输出路径、格式过滤、文件数量、覆盖策略和平台能力 | `task_id`、待转换清单、输出目录、进度 `0/N` | 路径不可达、输出覆盖未授权、旧格式环境缺失时暂停 |
| Step | 每次只转换 1 个文件或 1 个小批次，执行 `convert.py`/`batch_convert.py` 并立即做 V1-V6 检查 | 成功文件、失败文件、输出路径、质量检查结果 | 单文件失败写入失败清单，不影响其他文件；加密文件不重试 |
| Poll | 汇总成功/失败/待处理数量、最近失败原因和可续跑命令 | `running/success/failed/paused`、进度百分比、失败清单、待确认项 | 中断后从失败清单和未处理清单续跑，不重复转换已验证输出 |

执行约束：

- Init 阶段必须显示待转换数量和限定格式；禁止未确认就递归整个目录。
- Step 阶段不得覆盖已有输出，除非用户已在 Init 阶段明确授权。
- Poll 阶段完成度只能按“已通过 V1-V6 的输出文件数 / 待转换文件数”计算。
- 批量任务必须保留 `_conversion_errors.log` 或等价失败清单，最终回复需列出失败文件和下一步处理建议。
- 网络驱动器或路径含空格时优先使用 Python/pathlib 路径处理，不依赖 PowerShell 字符串拼接。

## 2. 依赖速查

`convert.py` 自动处理依赖。以下为手动参考，完整映射表见 [REFERENCE.md §1](REFERENCE.md)。

| 格式 | 额外包 |
|------|--------|
| .docx/.doc | python-docx |
| .xlsx | openpyxl |
| .xls | xlrd |
| .pptx/.ppt | python-pptx |
| .pdf | pypdf |
| .epub | ebooklib |

无需额外依赖的格式：`.html` `.csv` `.json` `.xml` `.png` `.jpg` `.jpeg` `.gif` `.bmp` `.tiff` `.webp` `.mp3` `.wav` `.m4a` `.ogg` `.flac` `.zip`

```bash
# 一次性安装全部可选依赖（脚本自动处理）
uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib
```

## 2.5 旧格式预处理

`.doc`/`.ppt` 不被 markitdown 直接支持，`convert.py` 自动尝试两种方式：

| | `.doc`→`.docx` | `.ppt`→`.pptx` |
|---|---|---|
| 方式1 | Word COM (Windows only) | PowerPoint COM (Windows only) |
| 方式2 | `soffice --headless --convert-to docx` | `soffice --headless --convert-to pptx` |

**LibreOffice 定位链**：`shutil.which("soffice")` → `$SOFFICE_PATH` → 常见安装路径 → 裸名兜底。详见 [REFERENCE.md §3](REFERENCE.md)。

> 🔴 **CHECKPOINT**：旧格式且 COM 和 LibreOffice 均不可用时，暂停并告知用户安装 Office 或 LibreOffice。`.xls` 无需预处理。

## 3. 命令速查

```bash
# 单文件（推荐）
python scripts/convert.py input.docx -o output.md

# 默认输出名 / 跳过摘要 / 静默
python scripts/convert.py input.pdf
python scripts/convert.py data.xlsx --no-summary
python scripts/convert.py report.pptx -q

# 批量转换（确认源/目标/数量/格式后执行）
python scripts/batch_convert.py <源目录> <输出目录> --ext .pdf .docx --clean

# 单独后置清洗（仅极端场景）
python scripts/post_clean.py output.md --check-only
```

> 🔴 **CHECKPOINT**：`-o` 输出已存在时暂停确认；批量转换前必须确认路径+数量+格式。

## 3.2 降级转换器

markitdown 失败时自动启用原生降级（输出同样经过后置清洗）：

| 格式 | 降级方案 | 能力 |
|------|---------|------|
| .docx/.doc | python-docx | 段落样式→标题、表格→MD 表格 |
| .xlsx/.xls | openpyxl | Sheet→H2 章节、数据行→MD 表格 |
| .pptx | python-pptx | 幻灯片→H2 章节、表格自动转换 |

## 4. 后置清洗

`convert.py` 内联清洗管线（6 类 15+ 正则）：去水印/页码/机密标记/版权声明 + 空白压缩 + 标题层级修复 + 表格分隔符补全 + 文档摘要注入。完整清洗项及正则模式详见 [REFERENCE.md §1](REFERENCE.md)。

## 5. 异常处理

| 错误类型 | 处理方式 |
|:---|:---|
| 依赖安装失败 | 终止，输出缺失包名，提示手动安装 |
| markitdown 失败 | 自动降级到原生转换器 |
| 加密文档 | 🔴 立即终止，提示解密后重试 |
| 旧格式无预处理环境 | 🔴 CHECKPOINT：暂停，告知安装 Office/LibreOffice |
| 批量单文件失败 | 跳过，记入 `_conversion_errors.log`，其余继续 |
| 输出路径不可写 | 终止，提示检查权限/磁盘空间 |

> 完整异常分类表（含 uv 不在 PATH、网络驱动器不可达等）见 [REFERENCE.md §10](REFERENCE.md)。

## 6. 输出反馈模板

```
{状态}将 `{源文件名}` 转换为 Markdown [{转换方式}] | H1={n} H2={n} H3={n} | 表格={n} | {文件大小}
输出: {绝对路径}
```

| 字段 | 取值 |
|:---|:---|
| 状态 | `成功` / `失败` / `部分成功` |
| 转换方式 | `markitdown` / `原生降级(python-docx)` / `原生降级(openpyxl)` / `原生降级(python-pptx)` |

批量：`批量转换完成 | 总计=N | 成功=N | 失败=N`，详情见 `_conversion_errors.log`。

## 7. 脚本清单

| 脚本 | 用途 |
|------|------|
| `scripts/convert.py` | 智能转换引擎（依赖补全 + markitdown + 降级 + 内联清洗） |
| `scripts/batch_convert.py` | 批量递归转换，保持目录结构 |
| `scripts/post_clean.py` | 单独后置清洗（极端场景备用） |
| `scripts/platform_detect.py` | 平台检测模块，`best_office_tool()` 路由 |

前置校验：`python -c "from pathlib import Path; assert Path('scripts/convert.py').exists()"`

## 8. 平台兼容性

Windows / Linux / macOS 全支持。`convert.py` 启动时自动检测平台能力，脚本使用 `pathlib.Path` 适配路径。详见 [REFERENCE.md §3](REFERENCE.md)。

## 9. 反模式禁令

1. **裸调 markitdown** → 必须 `python scripts/convert.py`
2. **shell_executor 执行网络驱动器脚本** → 用 `python_executor`
3. **加密文档反复重试** → 首次失败即终止
4. **旧格式无预处理时强行转换** → 告知用户安装 Office/LibreOffice
5. **批量转换不设 `--ext`** → 必须指定格式过滤
6. **重复清洗 convert.py 输出** → 禁止循环清洗

详细禁令清单见 [REFERENCE.md §4](REFERENCE.md)。

## 10. 验证检查表

转换完成后必须执行逐项检查，任一未通过即进入 §5 异常处理。

| # 检查项 | 验证命令（替换 `<输出.md>`） |
|:---|:---|:---|
| V1 | 文件存在且非空 | `python -c "import os; assert os.stat('<输出.md>').st_size>0"` |
| V2 | UTF-8 无乱码 | `python -c "open('<输出.md>',encoding='utf-8').read()"` |
| V3 | 无残留水印 | `python -c "import re; t=open('<输出.md>').read(); assert not re.search(r'Generated by\|Page \\d+',t)"` |
| V4 | 标题层级正常 | H1 存在 + 无跳跃（H1→H3 无 H2） |
| V5 | 表格分隔符完整 | 无 `\|---\|` 缺失 |
| V6 | 批量文件数对应 | 输出目录文件数 = 源文件数 |

Agent 完成后在最终回复中确认：V1 存在非空 / V2+V3 抽检前 3 段无乱码水印 / V4 无跳跃 / V5 表格完整 / V6（批量时）数量一致。

> 详细验证 oneliner、回归测试用例（RT1-RT3）见 [REFERENCE.md §5](REFERENCE.md)。自检清单见 [REFERENCE.md §2](REFERENCE.md)。

使用说明

# Make-to-Markdown — 使用说明

> 工业级 RAG Markdown 物料生成器。将 20+ 种文档格式一键转换为清洗后的 Markdown，为知识库提供统一的"通用语言"。

---

## 1. 功能概览

本工具负责将任意文档转换为 RAG 就绪的 Markdown，核心流程全自动：**依赖检测 → 自动安装 → 格式转换 → 失败降级 → 后置清洗**。

### 支持的输入格式

| 类别 | 格式 |
|:---|:---|
| 文档 | `.pdf` `.docx` `.doc` `.epub` |
| 表格 | `.xlsx` `.xls` `.csv` |
| 演示 | `.pptx` `.ppt` |
| 网页 | `.html` `.htm` |
| 数据 | `.json` `.xml` |
| 图片 | `.png` `.jpg` `.jpeg` `.gif` `.bmp` `.tiff` `.webp`（含 EXIF/OCR） |
| 音频 | `.mp3` `.wav` `.m4a` `.ogg` `.flac`（含语音转写） |
| 压缩包 | `.zip` |
| 视频 | YouTube 链接 |

### 核心能力

- **零手工依赖**：自动检测并安装所需 Python 包，无需手动 `pip install`
- **旧格式兼容**：`.doc` / `.ppt` 自动通过 Office COM 或 LibreOffice 转为新版格式
- **智能降级**：markitdown 失败时自动切换原生库（python-docx / openpyxl / python-pptx）
- **后置清洗**：自动去除水印、页码、机密标记，修复标题层级，补全表格分隔符
- **批量转换**：递归遍历目录，保持原始结构，失败文件独立记录

---

## 2. 环境要求

| 依赖 | 说明 |
|:---|:---|
| Python 3.8+ | 系统内置或手动安装 |
| uv | markitdown 运行环境，[安装指南](https://docs.astral.sh/uv/) |
| Microsoft Office（可选） | .doc / .ppt 旧格式预处理（Windows） |
| LibreOffice（可选） | .doc / .ppt 旧格式预处理（全平台） |

首次运行时工具自动通过 `uv tool install markitdown --with=...` 安装 markitdown 及完整可选依赖。

---

## 3. 快速开始

### 单文件转换

```bash
cd path/to/Make-to-Markdown

# 转换 Word 文档
python scripts/convert.py report.docx -o report.md

# 转换 PDF
python scripts/convert.py paper.pdf

# 静默模式 + 跳过摘要
python scripts/convert.py data.xlsx -q --no-summary
```

### 批量转换

```bash
# 递归转换整个文件夹
python scripts/batch_convert.py ./source/ ./output/

# 仅转换指定格式
python scripts/batch_convert.py docs/ output/ --ext .pdf .docx
```

### 单独清洗已有 Markdown

```bash
python scripts/post_clean.py 文件.md --summary -o 清洗后.md
```

---

## 4. 脚本体系

| 脚本 | 用途 | 常用参数 |
|:---|:---|:---|
| `scripts/convert.py` | 智能转换引擎（推荐） | `-o <输出>` `-q` `--no-summary` |
| `scripts/batch_convert.py` | 批量转换 | `--ext` `--clean` |
| `scripts/post_clean.py` | 后置清洗 | `-o` `--summary` `--check-only` |
| `scripts/platform_detect.py` | 平台能力检测 | — |

### convert.py 工作流

```
输入文件 → 格式判断
  ├─ .doc/.ppt → COM/LibreOffice 预处理 → .docx/.pptx
  └─ 其他格式 → 直接进入
      ↓
依赖检测 → 自动安装缺失包 → markitdown 转换
      ↓ (失败)
原生降级转换器 (python-docx / openpyxl / python-pptx)
      ↓
后置清洗（去水印 / 标题修复 / 表格补全 / 摘要注入）
      ↓
输出 .md 文件
```

---

## 5. 常见问题

**Q: 提示 markitdown 依赖缺失？**
A: convert.py 启动时自动安装，通常无需手动干预。若网络受限，手动执行：
```bash
uv tool install markitdown --with python-docx --with openpyxl --with python-pptx --with pypdf --with xlrd --with ebooklib
```

**Q: .doc 文件转换失败？**
A: 需要安装 Microsoft Office（含 Word）或 LibreOffice。二选一即可。若两者都不装，脚本会暂停并提示。

**Q: 转换结果标题层级混乱？**
A: 后置清洗会自动修复（多 H1 降级、越级补过渡），无需手动处理。

**Q: 输出文件有水印残留？**
A: 清洗管线覆盖 15+ 噪声模式（Generated by markitdown、Confidential、Page X of Y 等），若仍有残留可单独运行 `post_clean.py`。

**Q: 加密文档如何处理？**
A: 工具会检测到加密提示，立即终止该文件并告知用户先解密。不会反复重试。

**Q: 批量转换时个别文件失败？**
A: 失败文件会被记录到 `输出目录/_conversion_errors.log`，其余文件正常转换，不会中断整个流程。

---

## 6. 输出质量验收

转换完成后建议检查以下 5 项：

1. 文件非空（> 0 字节）
2. 无乱码（UTF-8 编码正常）
3. 无水印/页码残留
4. 标题层级无跳跃（H1 → H3 不能没有 H2）
5. 表格分隔符完整

工具在转换完成时会打印 H1/H2/H3 统计和表格计数，可据此快速判断质量。

---

## 7. 版本记录

当前技能包版本：v1.0.11（2026-07-02）

详细信息见 [REFERENCE.md §9](REFERENCE.md)。快速查阅：

| 版本 | 日期 | 主要更新 |
|:---|:---|:---|
| v1.0.11 | 2026-07 | 新增 Init-Step-Poll 渐进式防卡死协议，批量转换按初始化清单、单步转换、状态轮询和失败清单续跑执行 |
| v3.6 | 2026-06 | 文档精简 + 版本自查 (`--version`) |
| v3.5 | 2026-06 | 静默失败防护、平台检测、增强异常处理 |
| v3.1 | 2026-06 | CHECKPOINT 块、反馈格式固定模板 |
| v2.8 | 2026-06 | 平台检测模块 |
| v2.6 | 2026-06 | 标题层级修复、表格补全 |
| v2.0 | 2026-06 | 初始技能创建 |

完整更新记录和运维参考见 [REFERENCE.md](REFERENCE.md)。

如何安装此技能？

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