English | 中文

[!info] 阅读导览
第 1 章 项目概览与核心卖点 → 第 2 章 六种风格效果展示 → 第 3 章 作者介绍 → 第 4 章 快速开始（环境 / Agent / 安装 / 创作 / 配图）→ 第 5-11 章 文档导航、协议与项目信息

_{本项目由 PackyCode 等赞助方支持，得以持续免费开源。}

	感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本项目的用户提供了特别优惠，使用 此链接 注册并在充值时填写"ppt-master"优惠码，可以享受 9 折优惠。

在线预览 · 关于何雨果 · 示例下载 · 常见问题 · 联系我

_{↑ 一份 12 页的原生可编辑 PPT，端到端由 一个微信公众号链接 通过 Claude Opus 4.7 生成。无需人工设计，不走图片导出——每一个形状、文本框、图表都可以在 PowerPoint 里直接点击编辑。}

1. 项目概览

丢进一份 PDF、DOCX、网址或 Markdown，拿回一份 原生可编辑的 PowerPoint——真正的形状、真正的文本框、真正的图表，不是图片。点击任何元素即可编辑。

[!warning]
PPT Master 是 harness，不是完整的 agent。 harness + model = agent——工具负责工作流，模型决定上限。要组成真正高质量的 agent，推荐组合是：Claude 大上下文窗口（约 100 万 token）+ AI 生图（gpt-image-2）。其他模型能跑流程，但达不到同等质量上限。效果不理想，请先换模型，不要质疑 harness。

1.1. 核心特性

[!tip] 模板复刻
把任何一份你喜欢的 .pptx 丢给 AI，一句"用 /create-template 复刻成模板"，就能拿到一套可被 PPT Master 直接调用的页面布局——主题色、字体、母版/版式结构、复用图片、甚至精灵图裁剪关系都按 OOXML 真实抽取，封面/章节/装饰繁复的页面都能稳定还原。从此你不再受限于内置模板：公司品牌 deck、客户中标模板、找的高质量参考稿，都能一键变成你的私人模板库。详见 模板指南 →。

[!tip] 动画
导出的 deck 支持页间转场和页内元素入场动画，输出为真正的 OOXML 动画（不是嵌入视频）。默认进入页面后元素按顺序自动级联入场，无需点击；在 PowerPoint 和 Keynote 中原生播放，无需额外工具。详见 转场与动画使用指南 →。

[!tip] 旁白与视频
把演讲者备注按页生成语音旁白（默认 edge-tts，也可配置云端 TTS 获得高质量音色），把音频嵌回 PPTX，再用 PowerPoint 自带"导出视频"产出带旁白和转场的 MP4，全程无需第三方工具。详见 音频旁白与视频导出 →。

[!tip] 声音复刻
用 ElevenLabs / MiniMax / Qwen / CosyVoice 复刻出你自己的声音（或在授权前提下复刻演讲者的声音），让整份 deck 用你的声音念出来。在 provider 控制台复刻一次，把得到的 voice_id 传进来，PPT Master 就会用这个音色逐页朗读备注并嵌入回 PPTX。详见 使用复刻音色 →。

1.2. 运作方式

PPT Master 是一套在 AI IDE（Claude Code / Cursor / VS Code + Copilot / Codebuddy 等）里运行的工作流（一个 “skill”）。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT"，AI 按这套工作流在你本机生成一个真正可编辑的 .pptx。你不写任何代码——IDE 只是你和 AI 对话的地方。

flowchart LR
    A[原始材料<br>PDF / DOCX / 网址 / Markdown] --> B[AI IDE 对话<br>Claude Code / Cursor / Copilot]
    B --> C[PPT Master 工作流<br>内容分析 → 视觉设计 → SVG 生成]
    C --> D[原生可编辑 PPTX<br>真形状 / 文本框 / 图表]
    D --> E[PowerPoint 中直接点击编辑]

你要做的：装 Python、装一个 AI IDE、把资料放进来。

1.3. 与其他工具的区别

PPT Master 不一样：

• 真正的 PPT——如果一个文件在 PowerPoint 里打不开、不能编辑，它就不应该被叫做 PPT。PPT Master 输出的每个元素都能直接点击修改
• 成本透明可控——工具免费开源，唯一成本是你自己的 AI 模型用量。当前主流 AI 工具都已转向按量计费，你用多少付多少——PPT Master 不在此之外增加任何额外订阅费用
• 数据不出本地——你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外，全流程在你的电脑上完成
• 不锁定平台——你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动；Claude、GPT、Gemini、Kimi 等模型均可使用

市面上的 AI PPT 工具大致分四类，PPT Master 只做最后一类：

在线预览 → · examples/ — 22 个项目，309 页 · 为什么选 PPT Master？

2. 效果展示

杂志风 — 暖色调，大图排版，生活方式感	学术风 — 严谨结构，数据图表，论文答辩场景
暗色艺术风 — 电影感深色背景，美术馆陈列感	自然纪录风 — 沉浸式摄影，简洁信息层级
科技 / SaaS 风 — 白底卡片，定价表格，产品说明书	发布会风 — 高对比度，参数突出，苹果/小米发布会感

3. 关于作者

我是何雨果（Hugo He），投融资领域从业者（注册会计师 · 资产评估师 · 咨询工程师（投资）），工作中经常审阅和修改 PPT。我希望 AI 生成的幻灯片仍然能在 PowerPoint 里继续编辑，而不是被压成一张张图片——所以做了这个。

🌐 个人网站 · 📧 [email protected] · 🐙 @hugohe3

4. 快速开始

4.1. 前置条件

只需装 Python 即可。 其余依赖通过 pip install -r requirements.txt 一次装齐。

一句话总结——装好 Python，跑一行 pip install -r requirements.txt，就可以开始生成 PPT 了。

[!tip] Windows 用户
Windows 需要一些额外步骤（PATH 设置、执行策略等）。我们为 Windows 用户写了一份手把手安装指南：Windows 安装指南——从零到跑通第一份 PPT，10 分钟搞定。

简要流程：从 python.org 下载 Python → 安装时勾选 “Add to PATH” → pip install -r requirements.txt → 完成。

macOS / Linux——安装即用

# macOS
brew install python
pip install -r requirements.txt

# Ubuntu / Debian
sudo apt install python3 python3-pip
pip install -r requirements.txt

边缘场景备用方案——99% 的用户用不到

Pandoc：只在需要转小众格式时才装：.doc、.odt、.rtf、.tex、.rst、.org、.typ。.docx、.html、.epub、.ipynb 已由 Python 原生处理，不需要 pandoc。

# macOS
brew install pandoc

# Ubuntu / Debian
sudo apt install pandoc

4.2. 选择一个 Agent

PPT Master 在任何具备 agent 能力（可读写文件、执行命令、持续多轮对话）的工具里都能跑。

模型推荐：优先选 Claude Opus / Sonnet，搭配大上下文窗口和 gpt-image-2 生图——原因见上方说明。

[!tip] 没有 Claude / GPT / Gemini 渠道？
本项目赞助商 PackyCode 可以解决大多数卡点——没有 API Key、无法直连、没有境外信用卡无法订阅、或者只是不想为偶尔使用付整月费，PackyCode 都能让你按量调用 Claude、GPT、Gemini 等主流模型，直接用上推荐的 Claude 模型，支持国内支付，开箱即用。充值时填写优惠码 ppt-master 享 9 折。

4.3. 配置项目

方式 A — 下载 ZIP（无需安装 Git）：GitHub → Code → Download ZIP · AtomGit → 克隆/下载 → 下载 ZIP（国内网速更快）

方式 B — Git clone（需先安装 Git）：

# GitHub
git clone https://github.com/hugohe3/ppt-master.git
# AtomGit（国内网速更快）
git clone https://atomgit.com/hugohe3/ppt-master.git
cd ppt-master

然后安装依赖：

pip install -r requirements.txt

日常更新（方式 A / B）：python3 skills/ppt-master/scripts/update_repo.py

[!note] 方式 C — Skill marketplace
仓库已添加 .claude-plugin/marketplace.json 元数据，可通过 Claude Code plugin marketplace 生态一行安装：

# 跨 agent CLI（Claude Code、Cursor、Codex 等）
npx skills add hugohe3/ppt-master

# 或在 Claude Code 内
/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master

上述两种安装方式都只会拉取 skill 文件本身（不含完整仓库），后处理脚本仍需在安装目录跑 pip install -r requirements.txt。

4.4. 开始创作

提供原始材料（推荐）： 将 PDF、DOCX、图片等文件放入 projects/ 目录下，在 AI 聊天面板中告诉它使用哪些文件。获取路径的最快方式：在文件管理器或 IDE 侧边栏中右键文件 → 复制路径（Copy Path / Copy Relative Path），直接粘贴进聊天框。

你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT

直接输入内容： 也可以把文字内容直接粘贴进聊天窗口，AI 会根据这些内容生成 PPT。

你：请根据以下内容制作成 PPT：[粘贴你的文字内容...]

两种方式下 AI 都会先确认设计规范：

AI：好的，先确认设计规范：
   [模板] B) 自由设计
   [格式] PPT 16:9
   [页数] 8-10 页
   ...

AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。

输出说明： 原生形状版主 .pptx（可直接编辑）保存至 exports/<name>_<timestamp>.pptx；SVG 快照版 _svg.pptx 与 svg_output/ 副本归档至 backup/<timestamp>/，便于回溯视觉参考或免去 LLM 重跑直接重建 pptx。需要 Office 2016+。

[!tip] AI 迷失上下文？
让它先读 skills/ppt-master/SKILL.md。

[!tip] 遇到问题？
查看 常见问题——涵盖模型选择、排版问题、导出异常等，基于真实用户反馈持续更新。

4.5. 图片获取（可选）

非用户自带图片有两条路径，可在同一份 deck 里按行混用：

需要 API 的功能统一通过 .env 配置。clone 安装可以用 cp .env.example .env；skill marketplace 安装建议使用持久的用户级配置：

mkdir -p ~/.ppt-master
cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env

PPT Master 会优先读取当前进程环境变量，然后按顺序读取第一个存在的 .env：当前工作目录、clone 仓库根目录、~/.ppt-master/.env。

A) AI 生图 — image_gen.py。设置 IMAGE_BACKEND 和对应 *_API_KEY（OPENAI_API_KEY、GEMINI_API_KEY 等），流程会自动调用。python3 skills/ppt-master/scripts/image_gen.py --list-backends 查看完整后端清单。gpt-image-2 目前综合质量最佳。

B) 网络图片搜索 — image_search.py。零配置可用，但高质量使用建议配置 PEXELS_API_KEY / PIXABAY_API_KEY（都免费申请）。不配置时只使用 Openverse / Wikimedia Commons，适合作为兜底，但容易出现普通用户上传、构图随意、清晰度不稳定的图片；配置后默认搜索链会追加 Pexels / Pixabay，现代商业摄影、人物、办公、生活方式和插画类图片质量会明显更稳定。默认以图片质量和匹配度优先，直接把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选；如果选中的图片需要署名，Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时，才使用 --strict-no-attribution 限制为免署名图片。对视觉要求高的封面、产品图、人物图和品牌场景，优先级建议是：用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索。

完整说明：image-generator.md（AI）· image-searcher.md（网络）。

5. 文档导航

6. 贡献

详见 CONTRIBUTING.md

7. 开源协议

MIT

8. 致谢

SVG Repo · Tabler Icons · Simple Icons · Phosphor Icons · Robin Williams（CRAP 设计原则）

9. 关于项目

• 讨论与建议 → GitHub Discussions
• Bug 报告与需求 → GitHub Issues
• 作者主页 → www.hehugo.com

10. Star History

11. 赞助与支持

PPT Master 持续免费开源，Bug 修复、功能开发与文档维护都需要时间与心力，欢迎赞助支持。

赞助方

关于项目

感谢你对 PPT Master 的关注与支持。项目仍在持续迭代中，欢迎使用、反馈与贡献。

Made with ❤️ by 何雨果 Hugo He · 欢迎 Star · 回到顶部

_{官方仓库 GitHub（主仓库）· AtomGit（镜像）。其他平台转发版本均为非官方版本。MIT 协议，使用需保留署名。}

[!success] 核心要点

• 一句话定位：丢进 PDF / DOCX / 网址 / Markdown，拿回原生可编辑的 PPTX——真形状、真文本框、真图表，不是图片
• 本质是 harness：harness + model = agent，推荐 Claude 大上下文窗口 + gpt-image-2 生图；效果不理想先换模型
• 四大特性：模板复刻（/create-template）、OOXML 动画与转场、edge-tts 旁白 + 声音复刻（ElevenLabs / MiniMax / Qwen / CosyVoice）、AI IDE 内工作流
• 四个优势：真 PPT / 成本透明（仅模型用量）/ 数据不出本地 / 不锁定平台
• 快速上手：装 Python → 选 Agent（Claude Code / Cursor / Copilot 等）→ 方式 A/B/C 配置项目 → 丢材料给 AI 即可
• 效果示例：22 个项目 309 页，支持杂志 / 学术 / 暗色艺术 / 自然纪录 / 科技 SaaS / 发布会等风格