back
loading skill details...
支持使用 pandoc 在 Word (.docx) 与 Markdown 及多种格式之间进行双向转换，保留主要格式和图片。
# pandoc-docx
> 🔄 通过 pandoc 实现 Word (.docx) 与 Markdown 双向转换
---
## 📖 概述
基于 pandoc 的文档格式转换工具，支持 Word (.docx) 与 Markdown 之间的双向转换。
**核心能力：**
- ✅ 读取 Word (.docx) → Markdown
- ✅ 写入 Word (.docx) ← Markdown
- ✅ 格式转换 (.docx ↔ .md ↔ .pdf ↔ .txt ↔ .html)
- ✅ 批量处理
- ✅ 图片提取
- ✅ 格式保留（标题、粗体、列表、表格、代码）
**依赖：** pandoc (必需), libreoffice (可选，用于 .doc 支持)
---
## 🎯 触发条件
用户提到以下关键词时触发：
| 关键词 | 示例 |
|--------|------|
| "读取 Word" | "读取这个 report.docx" |
| "转为 Word" | "把这个 md 转为 word" |
| "docx 转 md" | "docx 转 md" |
| "创建 Word" | "创建一个 Word 文档" |
| "修改 docx" | "修改这个合同.docx" |
| "pandoc" | "用 pandoc 转换" |
| 文件路径包含 .docx | "处理 ~/documents/report.docx" |
---
## 🛠️ 支持格式
### 输入格式
| 格式 | 读取 | 写入 | 说明 |
|------|------|------|------|
| .docx | ✅ | ✅ | Word 2007+（主要支持） |
| .doc | ⚠️ | ⚠️ | 需要 libreoffice |
| .md | ✅ | ✅ | Markdown |
| .txt | ✅ | ✅ | 纯文本 |
| .pdf | ⚠️ | ❌ | 仅读取（需 pdftotext） |
| .html | ✅ | ✅ | HTML |
### 输出格式
| 格式 | 支持 | 说明 |
|------|------|------|
| .docx | ✅ | Word 文档 |
| .md | ✅ | Markdown |
| .pdf | ✅ | PDF（需 texlive） |
| .txt | ✅ | 纯文本 |
| .html | ✅ | HTML |
| .epub | ✅ | 电子书 |
---
## 🔄 核心流程
### 1. 读取 Word 文档
```
用户请求：读取 ~/report.docx
↓
检查文件格式 (.docx)
↓
调用 scripts/doc-read.sh
↓
pandoc report.docx -t markdown
↓
返回 Markdown 内容
↓
AI 分析/总结/处理
```
### 2. 写入 Word 文档
```
用户请求：创建 Word 文档
↓
AI 生成 Markdown 内容
↓
调用 scripts/doc-write.sh
↓
pandoc input.md -o output.docx
↓
返回 Word 文件路径
↓
确认完成
```
### 3. 格式转换
```
用户请求：docx 转 md
↓
检查源文件和目标格式
↓
调用 scripts/doc-convert.sh
↓
pandoc input.docx -o output.md
↓
返回转换结果
```
---
## 📝 使用方式
### 基础命令
```bash
# 读取文档
./scripts/doc-read.sh <文件路径> [格式]
# 写入文档
./scripts/doc-write.sh <输出文件> <输入文件|-> [格式]
# 格式转换
./scripts/doc-convert.sh <输入文件> -o <输出文件>
# 编辑文档
./scripts/doc-edit.sh <文件> <操作> [内容]
```
### 使用示例
```bash
# 读取 Word
./scripts/doc-read.sh ~/report.docx
# 创建 Word
echo "# 标题" | ./scripts/doc-write.sh ~/output.docx -
# 格式转换
./scripts/doc-convert.sh ~/input.docx -o ~/output.md
# 提取图片
./scripts/doc-convert.sh ~/input.docx -o ~/output.md --extract-media=./images
# 批量转换
for f in *.docx; do ./scripts/doc-convert.sh "$f" -o "${f%.docx}.md"; done
# 检查依赖
./scripts/check-deps.sh
```
---
## ⚠️ 依赖检查
### 必需依赖
| 工具 | 检查命令 | 安装命令 (Linux) | 安装命令 (macOS) |
|------|---------|-----------------|-----------------|
| pandoc | `pandoc --version` | `sudo apt install pandoc` | `brew install pandoc` |
### 可选依赖
| 工具 | 用途 | 安装命令 (Linux) | 安装命令 (macOS) |
|------|------|-----------------|-----------------|
| libreoffice | .doc 支持 | `sudo apt install libreoffice` | `brew install --cask libreoffice` |
| pdftotext | PDF 读取 | `sudo apt install poppler-utils` | `brew install poppler` |
| texlive | PDF 生成 | `sudo apt install texlive` | `brew install --cask mactex` |
---
## 📋 模板文件
### 文档摘要模板
```markdown
# 📄 文档摘要
**文件**: {filename}
**格式**: {format}
**大小**: {size}
**创建时间**: {created}
**修改时间**: {modified}
---
## 内容概览
- **标题数**: {heading_count}
- **段落数**: {paragraph_count}
- **表格数**: {table_count}
- **图片数**: {image_count}
---
## 核心内容
{content_summary}
---
**生成时间**: {timestamp}
```
---
## 🎯 典型场景
### 场景 1：读取并分析 Word 报告
```
用户：帮我分析这个季度报告 report.docx
↓
1. doc-read.sh report.docx
2. AI 分析内容
3. 生成摘要和洞察
```
### 场景 2：创建 Word 文档
```
用户：创建一个项目计划文档
↓
1. AI 生成 Markdown 内容
2. doc-write.sh plan.docx
3. 返回文件路径
```
### 场景 3：修改现有 Word
```
用户：把这个合同的甲方改为 ABC 公司
↓
1. doc-read.sh contract.docx
2. AI 修改内容
3. doc-write.sh contract-updated.docx
```
### 场景 4：批量转换
```
用户：把所有 Word 文档转为 Markdown
↓
1. 批量调用 doc-convert.sh
2. 返回转换结果列表
```
---
## ⚠️ 注意事项
### 格式保留
| 内容 | 保留度 | 说明 |
|------|--------|------|
| 标题层级 | ✅ 100% | H1-H6 完美转换 |
| 粗体/斜体 | ✅ 100% | **粗体** *斜体* |
| 列表 | ✅ 100% | 有序/无序列表 |
| 表格 | ✅ 95% | 简单表格完美，复杂表格可能简化 |
| 代码块 | ✅ 90% | 保留语言和格式 |
| 图片 | ✅ 100% | 需使用 --extract-media |
| 超链接 | ✅ 100% | 完美转换 |
### 可能丢失的内容
| 内容 | 说明 |
|------|------|
| 复杂样式 | 字体颜色、背景色等 |
| 页眉页脚 | Markdown 不支持 |
| 分页符 | Markdown 不支持 |
| 批注/修订 | 不转换 |
| 宏 | 不转换 |
| 合并单元格 | 可能简化为普通表格 |
### 最佳实践
1. **优先使用 .docx 格式**
- .doc 需要 libreoffice，转换质量略低
2. **图片单独提取**
```bash
pandoc input.docx -o output.md --extract-media=./images
```
3. **保留原始格式**
```bash
pandoc input.docx -o output.md --wrap=preserve
```
4. **使用参考文档（保持样式）**
```bash
pandoc input.md -o output.docx --reference-doc=template.docx
```
---
## 🔧 脚本说明
| 脚本 | 用途 | 参数 |
|------|------|------|
| `doc-read.sh` | 读取文档 | `<文件> [格式]` |
| `doc-write.sh` | 写入文档 | `<输出> <输入|-> [格式]` |
| `doc-convert.sh` | 格式转换 | `<输入> -o <输出> [选项]` |
| `doc-edit.sh` | 编辑文档 | `<文件> <操作> [内容]` |
| `check-deps.sh` | 检查依赖 | 无 |
---
## 📚 相关文档
- [supported-formats.md](./references/supported-formats.md) - 完整格式支持列表
- [pandoc-options.md](./references/pandoc-options.md) - pandoc 参数详解
---
## 🚀 快速开始
```bash
# 1. 检查依赖
./scripts/check-deps.sh
# 2. 读取 Word
./scripts/doc-read.sh ~/document.docx
# 3. 创建 Word
echo "# 标题" | ./scripts/doc-write.sh ~/output.docx -
# 4. 格式转换
./scripts/doc-convert.sh ~/input.docx -o ~/output.md
```
---
**版本**: 1.0.0
**创建**: 2026-03-21
**依赖**: pandoc >= 2.0
**作者**: Cyber 🌟
**许可**: MIT
don't have the plugin yet? install it then click "run inline in claude" again.