PPT Master 使用教程：用 VS Code 和 AI 生成可编辑 PPTX

一、PPT Master 是什么？ヾ(≧▽≦*)o

适合人群：会打开 VS Code，但不熟悉 Python 项目、不知道怎么配置 API Key、想先跑通一份真正可编辑 PPT 的用户。

PPT Master 是一个开源 AI PPT 工作流项目。它不是网页上的"一键生成 PPT"工具，而是一套放在本地电脑里的工作流：你把资料交给 AI，AI 按项目规则生成 SVG 页面，再导出为真正的 .pptx。

✨ 最大亮点：真正可编辑的 PPT

很多 AI PPT 工具导出的其实是整页截图——看起来很美，但双击进去什么都改不了 (╯°□°）╯，PPT Master 不一样，它导出的是 PowerPoint 原生对象：

元素	是否可编辑
文字	✅ 可以直接改
图形	✅ 可以拖动、变形
图标	✅ 可以换颜色
图片	✅ 可以替换
演讲者备注	✅ 可以修改

🎯 适合这些场景

把 PDF / Word / Markdown / 网页资料整理成演示稿
做汇报、课程展示、答辩、读书笔记、方案初稿
想要本地可控，不想把所有资料上传到在线 PPT 平台
希望 AI 先做粗稿，后续自己在 PowerPoint 里精修

⚠️ 但要先说清楚

它不是许愿池 (￣▽￣)ﾉ

想要高质量结果，你需要准备：资料（资料越清晰，PPT 越好）、模型 API（文本生成用）、图片 API（找图/生图用），以及一点点耐心，让 AI 按步骤生成和修正。

二、你需要准备什么？(｀・ω・´)

1. VS Code，（我这里使用VS Code，其他IDE也可以）

用 VS Code 打开整个项目目录，后续你和 AI 的对话、命令执行、文件查看都在这里完成。还没安装的去官网下载：https://code.visualstudio.com，详细安装配置教程参考https://blog.csdn.net/2301_78095812/article/details/148654572

装完之后，记得在扩展市场里搜索并安装 Python 扩展（搜索 ms-python.python）。

2. Python / Anaconda

本次实践使用的是 Anaconda 环境（路径：E:\Anaconda\python.exe）。

💡 为什么推荐 Anaconda？ 它自带 conda 包管理器，环境隔离更干净，不容易和系统其他 Python 串环境，对小白来说更不容易翻车。

如果你电脑里有多个 Python，建议在 VS Code 里明确选择一个解释器（因为需要在Python环境里安装项目所需要的库）：

① 按 Ctrl + Shift + P 打开命令面板
② 输入 "Python: Select Interpreter" 并回车
③ 选择你想用的，比如：Python 3.12.7 (base) E:\Anaconda\python.exe

🔔 我电脑里的python很多，我在Anaconda里新建一个Ptthon环境，也就是Python 3.12.7 (base) E:\Anaconda\python.exe

3. AI 工具（在 VS Code 里用的那种）

你需要一个能在 VS Code 里读写文件、运行命令的 AI 工具：

工具	特点
Codex	本文实际使用的工具
Claude Code	Anthropic 出品，命令行 AI 编码助手
Cursor	内置 AI 的 VS Code fork
GitHub Copilot	VS Code 插件，功能相对简单

4. API Key（两种，别搞混）

类型	用途	填写位置
文本模型 Key	给 Codex / Claude Code / Cursor 使用	填在 AI 工具的设置里
生图或图库 Key	让 PPT Master 调用图片服务	填在项目的 `.env` 文件里

⚠️ 安全提醒：不要把 API Key 发给别人，也不要贴到公开博客、截图或 GitHub 里！一旦泄露，你的额度可能被别人消耗掉 (╥﹏╥)

三、下载项目 (๑•̀ㅂ•́)و✧

项目地址：https://github.com/hugohe3/ppt-master

方法一：Git Clone（网络好时推荐）

powershell

git clone https://github.com/hugohe3/ppt-master.git

方法二：直接下载 ZIP（网络不稳时用这个，挂梯子下载可能会快，下载ZIP对于新手小白来说更加直观，所以我也就采用这种方式）

国内访问 GitHub 有时候很慢，git clone 可能半天没动静甚至直接报错。这时候直接下载 ZIP 往往更快：打开项目页 → 点绿色按钮 "Code" → 点 "Download ZIP"，下载后解压到你想放的位置，比如 D:\Desktop\VS code存放\PPT制作。

解压后目录名叫 ppt-master-main (｀・ω・´)。最终结构大概是：

D:\Desktop\VS code存放\PPT制作\ppt-master-main\
  ├── README_CN.md         # 中文说明文档
  ├── requirements.txt     # Python 依赖列表
  ├── .env.example         # 环境变量示例文件
  ├── skills\              # PPT Master 核心工作流
  ├── projects\            # 你的 PPT 项目都放这里
  └── docs\                # 文档

然后在 VS Code 里：文件 → 打开文件夹 → 选择 ppt-master-main。

四、安装依赖 (ง •_•)ง，（这一步推荐使用codex或者其他AI来帮你完成），以下是古法手动安装：

在 VS Code 终端里，确认你在项目根目录，然后运行：

E:\Anaconda\python.exe -m pip install -r requirements.txt

💡 为什么不直接用 pip？因为你电脑里可能有多个 Python，直接用 pip 可能装到系统 Python 而不是 Anaconda 环境。写完整路径更保险。

安装过程可能需要几分钟，耐心等待就好 ☕

国内网速慢的话，可以加上清华镜像源，也可以挂梯子：

E:\Anaconda\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，验证一下：

E:\Anaconda\python.exe -c "import pptx, fitz, edge_tts; print('ok')"

看到 ok 就说明核心依赖可用，可以继续了 🎉

常见报错速查：

报错	可能原因	解决方法
`pip: command not found`	系统没找到 pip	用完整路径 `E:\Anaconda\python.exe -m pip`
`Could not find a version...`	网络问题	加清华镜像源参数
`Permission denied`	权限不够	以管理员身份运行 VS Code 终端

五、配置 `.env` (づ｡◕‿‿◕｡)づ

项目根目录有一个 .env.example，这是配置模板。

第一步：复制一份，改名为 .env

或者使用codex，让codex来进行操作

第二步：打开 .env，按需填写

配置一：AI 生图（可选）

IMAGE_BACKEND=openai
OPENAI_API_KEY=你的生图APIKey
OPENAI_MODEL=gpt-image-2
OPENAI_BASE_URL=你的接口地址

如果是官方 OpenAI，OPENAI_BASE_URL 可以不填。如果是中转或第三方兼容接口，填它提供的 /v1 地址，我自己是使用中转站。

AI生图配置这里记得把#删掉

配置二：Pexels 网络找图（推荐配置）继续在.env文件往下滑

PPT Master 支持多个图库，质量对比：

图库	是否需要 Key	图片质量
Openverse	不需要	一般，有时找不到合适的
Wikimedia	不需要	偏学术，不适合商务场景
Pexels	需要（免费申请）	⭐⭐⭐⭐ 高质量商业摄影
Pixabay	需要（免费申请）	⭐⭐⭐ 质量不错

建议去 https://www.pexels.com/api/ 申请免费 Key，注册后几分钟内就能拿到，然后填入 .env：

申请教程：如何获取 Pixabay API Key 密钥（分步指南） - 幂简集成

# 申请地址: https://www.pexels.com/api/
PEXELS_API_KEY=你的PexelsKey

⚠️ `.env` 注意事项（有任何问题就去问Codex或者你自己的AI助手）

格式必须是 KEY=VALUE，注释行必须以 # 开头。以下写法会报 Expected KEY=VALUE 错误：

Sign up: https://www.pexels.com/api/    ❌ 既不是注释，也不是 KEY=VALUE

这样就是对的：

# Sign up: https://www.pexels.com/api/    ✅

六、第一次测试：生成 3 页 PPT ٩(◕‿◕｡)۶

正式做项目之前，强烈建议先跑一个 3 页测试 PPT，验证依赖、.env、图片服务、工作流全部正常。

在 VS Code 里对 Codex 说：

请先阅读 skills/ppt-master/SKILL.md，然后用 PPT Master 生成一份 3 页测试 PPT。
主题：人工智能如何提升学习效率。
要求：16:9，中文，现代简洁风格，优先使用 Pexels 和网络找图，没找到再使用 AI 生图。

Codex一般也会在projects里自动新建一个你的PPT项目文件夹

PPT Master 的"八项确认"是什么？

生成前会弹出一个设计方案确认，这不是 Bug，是故意设计的，目的是让你在开始前明确所有设计决策 (｀・ω・´)

确认项	示例
画布比例	PPT 16:9
页数	3 页
目标受众	学生、职场学习者
叙事模式	instructional（教学型）
视觉风格	soft-rounded（圆润现代）
配色方案	主色 `#2563EB`，辅色 `#F59E0B`
字体方案	标题：思源黑体，正文：微软雅黑
图片方案	优先 Pexels，其次 Openverse，最后 AI 生图

你逐一确认（或提出修改）后，AI 会按顺序执行：

1️⃣  创建项目目录
2️⃣  写 design_spec.md（人类可读的设计说明）
3️⃣  写 spec_lock.md（机器执行锁，锁定颜色、字体、图标规则）
4️⃣  搜索或生成图片（调用 Pexels / Openverse / AI 生图）
5️⃣  手写 SVG 页面（每一页都是 AI 精心排版的）
6️⃣  生成 speaker notes（演讲者备注）
7️⃣  质量检查（AI 自己 review 一遍）
8️⃣  导出 PPTX（运行 Python 脚本转换）

整个过程大概需要 3-10 分钟，取决于页数、网速和图片数量。

七、项目生成后在哪里看结果？(＾▽＾)

生成的项目通常在 projects\项目名_ppt169_日期\，比如：

最终 PPTX 路径类似：

projects\test_ai_learning_ppt169_20260614\exports\test_ai_learning_20260615_000140.pptx

用WPS 双击打开即可。第一次打开建议检查：字体显示正不正常？图片有没有显示？点一下文字框，能编辑吗？全部正常的话恭喜你，PPT Master 跑通啦 🎉(ﾉ◕ヮ◕)ﾉ*:･ﾟ✧

八、怎么重新导出 PPTX？(ﾟДﾟ*)ﾉ

改了 SVG 里的文字、换了图片、修改了备注之后，不需要重新生成整个项目，直接重新导出就好，在项目根目录运行三个脚本：

# 第一步：处理 SVG 总文件，拆分成单页
E:\Anaconda\python.exe skills\ppt-master\scripts\total_md_split.py projects\你的项目目录

# 第二步：后处理 SVG（清理、优化）
E:\Anaconda\python.exe skills\ppt-master\scripts\finalize_svg.py projects\你的项目目录

# 第三步：SVG 转 PPTX
E:\Anaconda\python.exe skills\ppt-master\scripts\svg_to_pptx.py projects\你的项目目录

新的 PPTX 会出现在 projects\你的项目目录\exports\，文件名带上新的时间戳，老文件不会被覆盖，放心 (≧∇≦)/

九、正式项目应该怎么做？(•̀ᴗ•́)و

第一步：准备资料目录

projects\你的项目名\sources\
  ├── report.pdf          # 主要资料
  ├── data.xlsx           # 数据表格
  ├── reference.docx      # 参考文档
  └── images\             # 参考图片

💡 资料越清晰，PPT 越好。如果 PDF 里文字是扫描图片，AI 读不出来，效果会很差。最好用有文字层的 PDF。

第二步：给 AI 下指令

请阅读 skills/ppt-master/SKILL.md，
用 projects\你的项目名\sources\report.pdf 生成一份 10 页中文 PPT。
要求：16:9，商务简洁风格，优先使用 Pexels 和网络找图，没找到再使用 AI 生图。

想套模板就加一句：请使用 projects\你的项目名\sources\template.pptx 套模板。
不想套就说：不用模板，自由设计。

第三步：让 AI 修改某一页

第 2 页图片太暗，换一张更明亮的 Pexels 图，并重新导出 PPTX。
第 3 页文字太多，压缩成三个短句，重新导出。
第 5 页的数据图换成柱状图风格，颜色改成蓝色系，重新导出。

十、常见坑和解决办法 (´；ω；`)

坑 1：GitHub 下载失败
直接下 ZIP，不要死磕 git clone，换方法就好 (°ー°〃)

坑 2：VS Code 找不到 Python 解释器
确认装了 Python 扩展 → Ctrl+Shift+P → Python: Select Interpreter → 点 "Enter interpreter path" → 手动填路径。

坑 3：依赖装到了错误的 Python 环境
症状是明明装了 pptx，但运行时报 ModuleNotFoundError。原因是直接用 pip install 装到了系统 Python。解决：永远用 E:\Anaconda\python.exe -m pip install 而不是直接用 pip。

坑 4：.env 报 Expected KEY=VALUE
打开 .env，找到不是注释（# 开头）也不是 KEY=VALUE 格式的行，加上 # 注释掉即可。

坑 5：图片质量不满意
在指令里明确图片优先顺序：1. Pexels → 2. Pixabay → 3. Openverse/Wikimedia → 4. AI 生图，并要求保留候选图目录供人工挑选。

坑 6：生成的 PPT 不完美
这是正常的 (｡•́︿•̀｡)。PPT Master 相当于一个尽职的 AI 实习生——能搭框架，细节还需要你打磨。遇到不满意的地方告诉 AI 修改后重新导出，或者自己在 PowerPoint 里精修。

坑 7：字体显示异常
PPT Master 默认使用思源黑体 / 微软雅黑。如果你的电脑没有这些字体，PowerPoint 会自动替换，可能影响排版。解决方法：安装思源黑体（Adobe 官网或 Google Fonts 免费下载），或者在 design_spec.md 里修改字体方案后重新导出。

十一、推荐的最稳流程 (ﾉ´ヮ`)ﾉ*: ･ﾟ

第一次使用：
下载项目 → VS Code 打开 → 选择 Anaconda 解释器 → 安装依赖 → 配置 .env（至少配 Pexels Key）→ 生成 3 页测试 PPT → 验证 exports 里的 .pptx 能否正常打开和编辑 → 🎉 跑通！

正式使用：
准备资料放入 sources/ → 让 AI 读 SKILL.md → 确认八项设计方案 → 等待生成 ☕ → 打开 PPTX 检查效果 → 不满意的地方告诉 AI 修改重新导出 → PowerPoint 最终精修 → 🎉 完成！

页数建议：

阶段	建议页数	原因
第一次测试	3 页	快速验证流程
正式初稿	8-12 页	图片/字体/配色稳了再扩展
大型项目	20+ 页	确认工作流稳定之后再做

别一上来就做 40 页大项目，容易翻车，出了问题也难排查 (￣▽￣)ﾉ

十二、总结ヾ(^▽^*)))

功能	PPT Master	普通在线 PPT 工具
资料位置	本地，不上传	上传到云端
输出格式	真正可编辑的 PPTX	多为 PNG/截图嵌入
图片来源	Pexels / Pixabay / AI 生图	内置图库（有限）
能否继续修改	✅ 让 AI 改后重新导出	一般不支持
适合场景	资料型、内容密集型 PPT	快速一键生成

PPT Master 更像一个 "AI + 本地 PPT 工厂"，而不是一个网页按钮。第一次配置确实有点麻烦（感同身受 (｡•́︿•̀｡)），但跑通之后，后面每次做 PPT 都会轻松很多，尤其是有大量资料需要整理成演示的场景，会让你省下大量时间。

希望这篇教程能帮你少走弯路，顺利跑通第一个 PPT ٩(◕‿◕｡)۶

Wangxinyang