PPT Master 上手指南：把 PDF、DOCX 转成原生可编辑 PPT 的 AI 工作流
项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master PPT Master 是一个开源的 AI 生成原生可编辑 PPT 的工作流：它跑在任意带 Agent 能力的 AI 工具里，读取你的 PDF、DOCX 或纯文字，产出在 PowerPoint 里每个形状都能单独点选修改的 .pptx 文件。它适合经常要处理报告、技术文档，并且愿意花十几分钟做一次本地环境配置、换取产出完全可控的用户。
周三晚上，桌上躺着一份 40 页的 PDF
假设是这样的处境：季度汇报的原始材料是一份 40 页 PDF，明早 9 点要讲，你需要一份能直接改的 PPT。用常见的 AI 演示工具，大概率拿到每页一张图的"扁平化"幻灯片——数字错了改不了，排版挤了动不了；换成 SaaS 网页版工具，浏览器里看着不错，导出的文件在 PowerPoint 里却塌了布局。问题不在生成，而在于生成的东西你没法接手。
PPT Master 要解决的就是"接手"这一环：AI 先读材料、理逻辑、画版面，最后交给脚本导出真正的 PowerPoint 对象。你拿到的不是图，是一份继续编辑的起点。
它不是独立软件，而是跑在 AI 工具里的一套工作流
先说清楚它是什么：PPT Master 本身没有独立的 App 或网站，核心是仓库里的 skills/ppt-master/ 目录——一套工作流说明、Python 脚本和模板资源。AI 模型负责理解内容、规划结构和绘制版面，脚本负责转换和导出，你只负责在对话框里下指令。
核心机制可以概括为一句：AI 生成 SVG，脚本把 SVG 编译成 PowerPoint 的 DrawingML。SVG 和 DrawingML 本质上是同一类东西——基于绝对坐标的 2D 矢量格式，矩形、路径、渐变、阴影都能一一映射，所以这次转换是"方言互译"，不是两种不兼容格式之间的硬桥。结果就是导出的形状带调节手柄、文本是真文本框、渐变阴影都是原生属性，而不是 python-pptx 那种"能编辑但只有扁平文本框"的基础产物，更不是嵌入图片路线下整页锁死的状态。
另外两件容易被忽略的事：一是它在动笔前先读源材料、定叙事模式（结论先行的 pyramid、讲故事的 narrative、教学的 instructional 等五种），再搭大纲——也就是说它管的是论证结构，不只是版面；二是成本结构透明，工具本身免费开源，你只为自己 AI 模型的用量付费，且除与大模型对话外，源文档转换、SVG 生成、PPTX 导出全程在本机完成，细节见 docs/zh/why-ppt-master.md。
从一份本地 PDF 到第一个可编辑 PPTX 文件
整个上手链路是：装环境 → 选一个 Agent 工具 → 丢材料 → 等导出。前置条件只有一个，Python 3.10+，其余依赖一条命令装齐。
克隆仓库并安装依赖
仓库体积超过 1GB（内含大量示例工程），如果下载失败或嫌大，Releases 页有约 56MB 的纯技能包可替代：
git clone https://gitcode.com/GitHub_Trending/ppt/ppt-master
cd ppt-master
pip install -r requirements.txt
Windows 用户需要处理 PATH 和执行策略等额外步骤，仓库有专门的 Windows 安装指南，从零到跑通大约 10 分钟。
用 Agent 工具打开项目并下指令
PPT Master 在任何能读写文件、执行命令、支持多轮对话的 AI 工具里都能跑：Cursor、Trae、Windsurf 这类 IDE 内置 Agent，VS Code / JetBrains 里的 Claude Code、GitHub Copilot、Cline 插件，或 Claude Code CLI、Codex CLI 等命令行工具，任选其一。在 IDE 类工具里用"文件 → 打开文件夹"打开 ppt-master 目录即可，后续一切在聊天面板完成，不需要写代码。
把要用的材料（PDF、DOCX、图片）放进 projects/ 目录，然后在聊天里说明用哪个文件：
你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT
默认流程下 AI 会先和你确认设计规范——用不用模板、16:9 还是别的画布、大概多少页——确认后依次做内容分析、视觉设计、SVG 生成和 PPTX 导出。不想来回确认的话，直接在指令里加一句"不用跟我确认"，它就进入快速生成模式，省掉交互但保留完整的图表、公式、图片处理能力。产物以 exports/<名称>_<时间戳>.pptx 保存，PowerPoint、Keynote、WPS、LibreOffice 都能打开继续编辑。
可选：配两个免费图片 Key
如果 deck 需要配图，在 .env 里填 PEXELS_API_KEY 和 PIXABAY_API_KEY（都免费申请），网络搜图质量会明显更稳定；不配置也能用内置的零配置搜索兜底，只是素材水平看运气。详见 docs/zh/faq.md 的配图章节。
数据图表、实时预览、旁白音频：成品 deck 能做的事
图表默认是矢量形状，需要数据联动时切原生对象。 导出的图表和表格默认走 SVG 派生的可编辑 DrawingML 形状，保证 PowerPoint / Keynote / WPS 之间渲染一致；如果你的工作流需要"编辑数据"工作簿，导出时加 --native-charts-and-tables 参数，符合条件的图表和表格会变成带数据源的原生 Chart/Table 对象，另存为 _native_charts_tables.pptx。两者都可编辑，区别在对象模型而不在可编辑性。
18 种内置视觉风格 × 5 种叙事模式自由组合。 swiss-minimal、editorial、dark-tech、brutalist、水墨 ink-wash 等都内置，风格和叙事骨架在确认时锁定、全 deck 保持稳定。仓库 examples/ 目录下有 20 组完整示例工程，覆盖财经数据、论文解读、建筑杂志、音乐节海报等不同方向，其中 ppt169_cangzhuo 是纯中文内容，证明它对中文排版和文化向题材的处理：
生成过程中有实时预览面板。 浏览器里（默认 http://localhost:5050）可以看到页面逐张渲染。这里有个不经 AI 的快捷通道：选中元素直接在侧边面板改文字、颜色、字号，拖拽或方向键挪位置，点"应用修改"写回；也可以选中元素写批注，说"应用我的批注"让 AI 重写该区域再重新导出。
演讲备注能变成配音。 对 AI 说"为这份 deck 生成旁白并重新导出嵌入音频"，它会用 edge-tts（覆盖约 90 种语言环境）把每页备注读成语音嵌回 PPTX，随后让 PowerPoint 直接导出带同步旁白的 MP4，不需要第三方工具。如果要用自己的声音，从 ElevenLabs、MiniMax、Qwen、CosyVoice 导入克隆语音、在聊天里传 voice_id 即可，完整说明在 docs/zh/audio-narration.md。
适不适合你：配置成本、十分钟生成时长这些事实
先说清楚边界：它不适合想要"打开浏览器立即出片"的场景——需要装 Python、克隆仓库、配一个 AI 工具，且一份 10 页的 deck 串行生成大约要 10~20 分钟（SaaS 工具是秒级），也没有实时协作和共享链接，产出是本地文件。适合它的是：对数据敏感不想上传第三方服务器、要求产出能在 PowerPoint 里深度编辑、或者想复用自己现有 .pptx 模板的团队和个人。
几个高频问题：
没有生图 API Key 能不能用？ 能。Agent 宿主自带生图能力时直接用它，不配任何 Key 也行；否则内置的零配置搜索（Openverse / Wikimedia Commons）可作兜底，质量要求高就自己找图，把链接发给 AI 用 image_search.py --from-url <链接> 下载替换。
AI 中途忘了步骤或跑偏了怎么办？ 让它重新读取 skills/ppt-master/SKILL.md 和对应工作流文件再继续；文本溢出、元素重叠这类排版问题，重跑该页或在实时预览里直接修。完整排查清单在 docs/faq.md，按真实用户反馈持续更新。
只有一个主题、没有任何材料能生成吗？ 能。Generate 流程有 topic-research 阶段，会自动补齐规划所需的事实基础和来源记录；但质量取决于公开网页的覆盖度，手头有专业资料（论文、内部文档）时直接给文件效果更好。
PPT Master 把"AI 出图、人工没法改"这个断层补成了"AI 出初稿、原生对象接着改"，代价是本地配置的功夫和十几分钟的等待。想先判断水平，最快的方式是从 examples/ 挑一份 .pptx 下载下来在 PowerPoint 里打开；第一次使用从 docs/zh/getting-started.md 开始即可。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
