AI 编程：用 Claude Code 实现 Word 文档自动转 PPT

AI编程

AI 编程：用 Claude Code 实现 Word 文档自动转 PPT

本文记录了使用 Claude Code Skills 将 .docx 文档自动转化为 .pptx 演示文稿的完整过程，涵盖原理解析、工具链选型、工作流设计、样式提取与最终规则沉淀。

一、为什么要做 DOCX 转 PPTX？

工程师写技术报告习惯用 Word，但汇报时需要 PPT。手动搬运内容费时费力：调格式、贴截图、对齐样式，一份 10 页的报告往往要花 30 分钟以上做 PPT。

核心诉求很简单：

  • 内容从 Word 来：标题、正文、图片、表格
  • 样式从模板来：已有的公司 PPT 模板（颜色、字体、布局）
  • 输出一份新 PPT：内容 + 样式合并，开箱即用

这个任务非常适合 AI 编程：结构化输入、明确的转换规则、可验证的输出。

二、技术选型与工具链

2.1 为什么不用 python-pptx？

python-pptx 是 Python 生态中最常见的 PPT 生成库，但它有几个痛点：

维度 python-pptx pptxgenjs
模板支持 需要操作底层 XML Slide Master API 直观
图表能力 基础 丰富（Bar/Line/Pie 等）
样式控制 繁琐的 Emu 单位 英寸为单位，直觉友好
AI 生成友好度 一般 高（JSON-like 配置）

最终选择 pptxgenjs（Node.js），配合 Claude Code 的 Skills 系统完成整个流程。

2.2 Skills 依赖

整个工作流依赖两个 Claude Code Skills：

1
2
docx skill  →  读取 Word 内容（文本 + 图片）
pptx skill  →  生成 PPT（pptxgenjs）

Skills 是 Claude Code 的能力扩展机制，每个 Skill 包含工具脚本和使用指南，让 AI 具备特定领域的专业能力。

三、工作流全景

3.1 整体架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
┌─────────────────────────────────────────────────────────┐
│                    输入层                                 │
├──────────────────────┬──────────────────────────────────┤
│  .docx 文档          │  .pptx 模板                      │
│  (内容源)            │  (样式源)                         │
└──────────┬───────────┴──────────────┬───────────────────┘
           │                          │
           ▼                          ▼
┌──────────────────────┐   ┌──────────────────────────────┐
│  docx skill          │   │  pptx skill                  │
│  ├─ pandoc 提取文本  │   │  ├─ markitdown 提取结构      │
│  └─ unpack 提取图片  │   │  └─ unpack 提取 theme XML    │
└──────────┬───────────┘   └──────────────┬───────────────┘
           │                              │
           ▼                              ▼
┌─────────────────────────────────────────────────────────┐
│                   转换层                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  内容映射规则                                    │    │
│  │  H1 → 新幻灯片标题                              │    │
│  │  段落 → 文本框                                   │    │
│  │  图片 → addImage                                 │    │
│  │  表格/对比数据 → addTable                        │    │
│  └─────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │  样式映射规则                                    │    │
│  │  theme.xml → COLORS 常量                         │    │
│  │  fontScheme → fontFace 参数                      │    │
│  │  slideMaster → defineSlideMaster                 │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   输出层                                  │
│  pptxgenjs 生成 .pptx → markitdown 验证内容完整性       │
└─────────────────────────────────────────────────────────┘

3.2 五步工作流

步骤 工具 命令 产出
1. 提取文本 pandoc pandoc input.docx -o output.md Markdown 格式的文档结构
2. 提取图片 unpack.py python scripts/office/unpack.py input.docx unpacked/ word/media/ 下的所有图片
3. 分析模板 unpack.py python scripts/office/unpack.py template.pptx unpacked/ theme XML + slideMaster XML
4. 生成 PPT pptxgenjs node create_pptx.js 最终 .pptx 文件
5. 验证输出 markitdown python -m markitdown output.pptx 文本内容校验

四、原理详解

4.1 Word 文档的内部结构

.docx 本质是一个 ZIP 压缩包，解压后的核心结构：

1
2
3
4
5
6
7
8
9
10
document.docx (ZIP)
├── word/
│   ├── document.xml    ← 正文内容（段落、标题、表格）
│   ├── media/          ← 嵌入的图片文件
│   │   ├── image1.jpeg
│   │   ├── image2.png
│   │   └── ...
│   └── _rels/          ← 资源引用关系
├── [Content_Types].xml
└── _rels/.rels

pandoc 将 document.xml 解析为 Markdown，保留标题层级、列表结构和图片引用。unpack.py 则直接解压获取 word/media/ 下的原始图片文件。

4.2 PPT 模板的样式提取

.pptx 同样是 ZIP 压缩包，样式信息集中在三个位置：

1
2
3
4
5
6
7
8
template.pptx (ZIP)
├── ppt/
│   ├── theme/
│   │   └── theme1.xml       ← 颜色方案 + 字体方案
│   ├── slideMasters/
│   │   └── slideMaster1.xml ← 背景、页脚、占位符布局
│   └── slideLayouts/        ← 各种布局模板
└── ...

颜色方案在 theme1.xml 的 <a:clrScheme> 节点中：

1
2
3
4
5
6
<a:clrScheme name="Lenovo">
  <a:dk1><a:srgbClr val="000000"/></a:dk1>      <!-- 深色1：黑色 -->
  <a:lt1><a:sysClr val="window"/></a:lt1>        <!-- 浅色1：白色 -->
  <a:accent1><a:srgbClr val="E2231A"/></a:accent1> <!-- 强调色：红色 -->
  <a:accent4><a:srgbClr val="3E8DDD"/></a:accent4> <!-- 强调色：蓝色 -->
</a:clrScheme>

字体方案在 <a:fontScheme> 中：

1
2
3
4
<a:fontScheme name="Office Classic 2">
  <a:majorFont><a:latin typeface="Arial"/></a:majorFont>
  <a:minorFont><a:latin typeface="Arial"/></a:minorFont>
</a:fontScheme>

这些信息直接映射为 pptxgenjs 的配置参数。

4.3 pptxgenjs 生成原理

pptxgenjs 的工作方式是：用 JavaScript 对象描述幻灯片内容，最终序列化为 OOXML 格式的 .pptx 文件。

核心 API 链路：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 1. 创建实例，设置全局属性
const pres = new pptxgen();
pres.layout = "LAYOUT_16x9";

// 2. 定义 Slide Master（对应模板样式）
pres.defineSlideMaster({
  title: "CONTENT",
  background: { color: "FFFFFF" },
  objects: [
    { rect: { x: 0, y: 0, w: 10, h: 0.8, fill: { color: "1A1A2E" } } },  // 顶部深色条
    { rect: { x: 0, y: 0.8, w: 10, h: 0.06, fill: { color: "E2231A" } } }, // 红色分隔线
  ],
});

// 3. 添加幻灯片，引用 Master
let slide = pres.addSlide({ masterName: "CONTENT" });

// 4. 添加内容元素
slide.addText("标题", { x: 0.3, y: 0.1, w: 9.4, h: 0.6, fontSize: 18 });
slide.addImage({ path: "image.png", x: 0.3, y: 1.5, w: 4.5, h: 2.5 });
slide.addTable(rows, { x: 0.5, y: 1.2, w: 9.0 });

// 5. 写入文件
pres.writeFile({ fileName: "output.pptx" });

坐标系统使用英寸，16:9 布局的画布尺寸为 10” x 5.625”。

五、实战案例：Bxxxxb 性能报告

5.1 输入分析

Word 文档结构（pandoc 提取后）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Bxxxxb ADMAR driver Performance report

# Performance TEST1: BIOS Kernel DMA protection On + DMAR SDMA driver
  - BIOS 截图 (image1.jpeg, image2.jpeg)
  - 性能数据：CPU 22-30%, Read 90MB/s, Write 70MB/s
  - 测试截图 (image3.png, image4.png, image5.png)

# Performance TEST2: BIOS Kernel DMA protection Off + DMAR disabled ADMA driver
  - BIOS 截图 (image6.jpeg, image7.png)
  - 性能数据：CPU 22-28%, Read 95MB/s, Write 85+MB/s
  - 测试截图 (image8.png, image9.png, image10.png)

# Final Conclusion
  - SDMA 比 ADMA 多 2-5% CPU
  - Write 性能低 15-20%
  - 同一 SD 卡、同一 PC (P16v Gen 2)

模板样式（从 Lenovo 模板提取）：

属性 值
颜色方案 Lenovo（红色 #E2231A，深灰 #6F7170）
字体 Arial
布局 16:9 宽屏
页脚 白色文字，深色背景条

5.2 内容到幻灯片的映射

根据文档结构，规划 8 张幻灯片：

幻灯片 来源 布局策略
1. 标题页 文档标题 + 作者信息 深色背景 + 大标题
2. TEST1 设置 BIOS 截图 x2 双图并排
3. TEST1 摘要 性能数据要点 文本列表 + 高亮关键数据
4. TEST1 图表 测试截图 x3 三图网格布局
5. TEST2 设置 BIOS 截图 x2 双图并排
6. TEST2 摘要 性能数据要点 文本列表 + 高亮关键数据
7. TEST2 图表 测试截图 x3 三图网格布局
8. 结论 对比数据 + 结论 表格 + 要点列表

5.3 Slide Master 设计

从模板提取的样式转化为 pptxgenjs 的 Slide Master：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 内容页 Master：深色顶栏 + 红色分隔线 + 深色底栏
pres.defineSlideMaster({
  title: "CONTENT",
  background: { color: "FFFFFF" },
  objects: [
    { rect: { x: 0, y: 0, w: 10, h: 0.8, fill: { color: "1A1A2E" } } },
    { rect: { x: 0, y: 0.8, w: 10, h: 0.06, fill: { color: "E2231A" } } },
    { rect: { x: 0, y: 5.2, w: 10, h: 0.425, fill: { color: "1A1A2E" } } },
    { text: {
        text: "2026 Bayhub Confidential. All rights reserved.",
        options: { x: 0.3, y: 5.25, w: 6, h: 0.3, fontSize: 8, color: "FFFFFF" },
    }},
  ],
});

这个 Master 复现了模板的视觉结构：顶部标题区（深色背景 + 白色文字）、中间内容区（白色背景）、底部页脚（深色背景 + 版权信息）。

5.4 关键技巧

图片路径处理：从解包的 docx 中引用图片，使用绝对路径：

1
2
const MEDIA = path.join(__dirname, "docx_unpacked", "word", "media");
slide.addImage({ path: path.join(MEDIA, "image1.jpeg"), x: 0.3, y: 1.5, w: 4.5, h: 2.5 });

数据高亮：关键数据用红色强调，与模板的 accent1 颜色一致：

1
{ text: "SDMA costs about 20-25% CPU", options: { bold: true, color: "E2231A" } }

对比表格：结论页使用 addTable 展示两种模式的性能对比：

1
2
3
4
5
6
7
8
const tableRows = [
  [{ text: "Metric", options: { bold: true, color: "FFFFFF", fill: { color: "1A1A2E" } } },
   { text: "DMAR + SDMA", options: { ... } },
   { text: "DMAR Off + ADMA", options: { ... } }],
  [{ text: "Sequential Read" }, { text: "~90 MB/s" }, { text: "~95 MB/s" }],
  [{ text: "Sequential Write" }, { text: "~70 MB/s" }, { text: "~85+ MB/s" }],
];
slide.addTable(tableRows, { x: 0.5, y: 1.2, w: 9.0, colW: [3.0, 3.0, 3.0] });

六、验证与输出

6.1 内容验证

生成后使用 markitdown 提取文本，确认所有内容完整：

1
python -m markitdown output.pptx

检查项：

  • 每张幻灯片的标题是否正确
  • 数据是否与原文一致
  • 图片是否全部嵌入
  • 表格结构是否完整

6.2 清理临时文件

生成完成后，输出目录只保留最终 .pptx：

1
2
rm -rf docx_unpacked template_unpacked node_modules
rm -f extracted.md package.json package-lock.json create_pptx.js

七、规则沉淀：CLAUDE.md

整个工作流验证通过后，将经验固化为项目级规则文件 CLAUDE.md，确保后续转换任务可复现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# DOCX to PPTX Conversion Rules

## Skills Dependencies
- docx: 读取 Word 内容
- pptx: 生成演示文稿（pptxgenjs）

## Workflow
1. pandoc 提取文本 → 2. unpack 提取图片 → 3. 分析模板样式
→ 4. pptxgenjs 生成 → 5. markitdown 验证

## Content Mapping Rules
| Word 元素 | PPT 处理方式 |
|-----------|-------------|
| H1 标题   | 新幻灯片标题 |
| 段落      | 文本框       |
| 图片      | addImage     |
| 数据对比  | addTable     |

## Key Constraints
- 统一使用 pptxgenjs，不写 Python 脚本
- 颜色值不加 # 前缀
- 不使用 unicode bullet，使用 bullet: true
- 生成后清理临时文件

CLAUDE.md 的价值在于：将一次性的探索过程转化为可重复执行的规则。下次在同一目录下启动 Claude Code，它会自动加载这些规则，无需重新解释工作流。

八、总结

8.1 技术栈总结

层级 技术 作用
内容提取 pandoc + unpack.py 从 .docx 获取文本和图片
样式分析 unpack.py + XML 解析 从模板 .pptx 提取颜色/字体/布局
PPT 生成 pptxgenjs (Node.js) 程序化创建幻灯片
内容验证 markitdown 验证输出完整性
流程编排 Claude Code Skills AI 驱动的自动化工作流

8.2 适用场景

  • 技术报告转汇报 PPT：工程师写 Word，自动生成演示文稿
  • 批量文档转换：多份报告使用同一模板批量生成
  • 模板标准化：确保所有输出 PPT 符合公司视觉规范

8.3 局限与改进方向

  1. 复杂排版：Word 中的复杂表格、嵌套列表目前需要人工调整映射规则
  2. 图片尺寸：当前使用固定尺寸，未来可根据图片原始比例自动计算
  3. 模板背景图：pptxgenjs 无法直接复用模板的背景图片，需要手动提取后作为 base64 嵌入
  4. 动画效果：pptxgenjs 不支持 PPT 动画，如需动画需后期手动添加