让 AI 做出"真·可编辑"的 PPT:PPT Master 技术拆解
项目地址:https://github.com/hugohe3/ppt-master
版本:SKILL v6.7.3 · 许可证:MIT
一、问题:AI 做 PPT,难点不在"画"
市面上的 AI PPT 工具很多,但交付物大致分三类:
整页图片:好看,但文字不能选、颜色不能改,本质是截图。
套模板填文字:可编辑,但只是"能改的表皮",版式死板。
HTML 幻灯片:AI 最擅长写 HTML,但最后要么导出 PDF,要么转 PPTX 时样式崩坏。
职场里真正要的是:一份能在 PowerPoint 里继续精修的原生文档。母版版式是真的继承关系,圆角矩形拖得动黄色调节手柄,图表能"编辑数据",公式是 OMML 而不是图片。
PPT Master 的作者何雨果是投融资从业者,每天都在做 PPT。他对项目的定位很清楚:可编辑已经是及格线,差异在于原生深度(native depth)。
二、整体形态:不是 SaaS,是一个 Agent Skill
PPT Master 没有服务端,也没有自己的大模型。它是一套运行在 AI 编程 Agent(Claude Code、Codex、Cursor、Copilot、Cline 等)里的 Skill:
harness(工作流 + 规范 + 脚本) + model(你自己的大模型) = agent
仓库结构的核心在 skills/ppt-master/:
scripts/ 下的 Python 代码超过 20 万行,覆盖 17 个生图后端、4 个图片搜索源、6 个 TTS 后端,还有 70 多个测试文件。
这样做的好处:
成本透明:只付模型费用。用 Agent 的包月订阅批量出 deck,边际成本接近零。
数据本地:源文档转换、SVG 生成、PPTX 导出都在本机。只有和模型的对话,以及你主动开启的生图、搜图、配音会外发。
不锁定:换编辑器、换模型都行,模型能力决定质量上限。
用起来就是在 Agent 里打开项目目录,说一句"用 projects/xxx/report.pdf 做一份 PPT"。
三、安装教程:把 ppt-master 装进你的 Agent
不管用哪种方式安装,都要满足两个前提:
Python 3.10+:后处理脚本要用到。
装 Python 依赖:插件或 skill 安装只会拉取 skill 文件,依赖要自己在 skill 目录里执行
pip install -r requirements.txt。
方式一:直接在对话里让 Agent 帮你装
这是最省事的方法。Agent 能执行 shell 命令,你只要说清楚要装什么、装到哪里。比如:
帮我安装 GitHub 上 hugohe3 的 ppt-master skill(https://github.com/hugohe3/ppt-master)。
skill 本体在仓库的 skills/ppt-master/ 目录,要求:
1. 安装到当前 Agent 的用户级 skill 目录;
2. 进入安装后的 skill 目录执行 pip install -r requirements.txt;
3. 把 .env.example 复制到 ~/.ppt-master/.env(已存在就不要覆盖);
4. 最后告诉我安装路径,以及怎么验证 skill 已被识别。
写成这样有几个原因:
指明 skill 子目录:仓库根目录不是 skill,
SKILL.md在skills/ppt-master/下。不说清楚,Agent 可能把整个仓库复制过去。把装依赖写进需求:Agent 经常只复制文件,漏掉这一步。
要求回报路径:方便你确认它装到了正确位置。
装完后新开一个会话。大多数 Agent 只在会话启动时扫描 skill 目录。
各工具的用户级 skill 目录如下,也可以直接让 Agent 帮你查:
方式二:Claude Code 插件市场
仓库自带 .claude-plugin/marketplace.json。在 Claude Code 的对话框里输入:
/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master
这两条是需要你自己输入的斜杠命令,Agent 不能替你执行。安装后到插件目录执行 pip install -r requirements.txt,插件描述里也特别提醒了这一步。
方式三:跨 Agent 的 npx skills
项目 README 推荐这个命令,它同时支持 Claude Code、Cursor、Codex 等工具:
npx skills add hugohe3/ppt-master
运行前需要本机装有 Node.js/npm。命令会交互式询问装给哪个 Agent、装到用户级还是项目级。装完后照常到安装目录执行 pip install。
方式四:Codex
Codex 会从 ~/.agents/skills/ 和仓库内的 .agents/skills/ 发现 skill。除了方式一和方式三,也可以手动安装:
git clone --depth 1 https://github.com/hugohe3/ppt-master ~/src/ppt-master
mkdir -p ~/.agents/skills
ln -s ~/src/ppt-master/skills/ppt-master ~/.agents/skills/ppt-master
python3 -m pip install -r ~/src/ppt-master/skills/ppt-master/requirements.txt
这里用软链接而不是复制,更新时到 ~/src/ppt-master 执行 git pull 就行。重启 Codex 后,输入 /skills 或 $ 就能看到 ppt-master。
Codex 还内置了 $skill-installer,可以在对话里说"$skill-installer 安装 https://github.com/hugohe3/ppt-master/tree/main/skills/ppt-master"。不过有反馈称它仍默认装到旧的 ~/.codex/skills/ 目录(见 openai/skills#420),装完记得确认一下路径。
方式五:Hermes Agent
Hermes 有一条 GitHub 安装命令,hermes skills install <owner>/<repo>/<path>,对话里也可以用 /skills install。但 ppt-master 不建议用这种方式装。
原因是 Hermes 从 GitHub 安装时,只会复制 SKILL.md 以及它引用的 references/、templates/、scripts/、assets/、examples/ 目录。ppt-master 的核心流程放在 workflows/ 里,这个目录不在复制范围内,装完会缺文件。
推荐先 clone 仓库,再通过 external_dirs 让 Hermes 扫描它:
git clone --depth 1 https://github.com/hugohe3/ppt-master ~/src/ppt-master
python3 -m pip install -r ~/src/ppt-master/skills/ppt-master/requirements.txt
然后编辑 ~/.hermes/config.yaml:
skills:
external_dirs:
- ~/src/ppt-master/skills
新开会话后,用 hermes skills list 确认,或直接输入 /ppt-master 调用。如果你本来就维护着 ~/.agents/skills/ 这个共享目录,把它加进 external_dirs,Codex 和 Hermes 就能共用一份。
装完之后
配置 API Key(可选):AI 生图、图片搜索、配音这些功能需要。把 key 写进
~/.ppt-master/.env。读取顺序是:进程环境变量 → 当前目录 → skill 目录 → 仓库根目录 →~/.ppt-master/.env。从工作目录启动 Agent:不要在 skill 的安装或缓存目录里干活。生成的文件会落在
<工作目录>/projects/<项目名>/exports/。验证:新会话里说"用 ppt-master 把这段文字做成 3 页 PPT,快速模式",能跑到导出 PPTX 就说明装好了。
更新:clone 安装的执行
git pull,或者运行python3 skills/ppt-master/scripts/update_repo.py。插件或 npx 安装的,重新执行一次安装命令。
四、核心技术决策:为什么用 SVG 做中间语言
这是整个项目最值得讲的一点。核心流程只有一句话:
AI 生成 SVG → 脚本编译成 DrawingML(PPTX)
作者在技术文档里把候选方案逐个排除了一遍:
SVG 胜出,因为它和 DrawingML 是同一类东西:都是绝对坐标的 2D 矢量格式,概念可以一一对应。
所以转换是"方言翻译",不是"格式代沟"。而且 SVG 同时满足三方需求:AI 能稳定生成,人能在浏览器里直接预览,脚本能确定性地编译。
一个细节:圆角矩形怎么变成"原生"的
看 scripts/svg_to_pptx/drawingml/elements.py 里对 <rect> 的处理,能感受到"原生深度"具体指什么:
elif rx > 0 and abs(rx - ry) < 0.5:
# 对称圆角 → PowerPoint 原生圆角矩形
# adj 是圆角半径占短边的比例,单位 1/100000,上限 50000(胶囊形)
short_side = min(w, h)
radius = min(rx, short_side / 2)
adj = max(0, min(50000, int(round(radius / short_side * 100000))))
geom = (
'<a:prstGeom prst="roundRect">'
f'<a:avLst><a:gd name="adj" fmla="val {adj}"/></a:avLst>'
'</a:prstGeom>'
)
elif rx > 0 or ry > 0:
# 椭圆角(rx != ry)DrawingML 没有预设,退化为 custGeom 贝塞尔曲线
geom = _build_round_rect_custgeom(w, h, rx, ry)
同样画出一个圆角矩形,用 custGeom 画路径和用 prstGeom roundRect 在视觉上完全一样。区别在于后者在 PowerPoint 里是真正的"圆角矩形":黄色调节手柄能拖,"重置形状"能用。这就是"能改"和"改得深"的差别。
SVG 不是"任意 SVG"
项目刻意强调:svg_output/ 里是项目规范化 SVG 中间语言,只借用 SVG 的语法,允许的元素、属性、单位都由项目封闭定义。方向是"SVG 适应 PPT Master",而不是追随整个 SVG 标准。
输入被分成三种状态:
原则叫"规范窄写入、受控兼容读取"。比如颜色只允许六位大写 #RRGGBB,透明度必须写在 fill-opacity 等属性里。约束越窄,模型越不容易跑偏,编译器也越好测。
五、流水线:从素材到 PPTX
默认的 Generate 流程如下(已简化):
用户输入(PDF / DOCX / XLSX / PPTX / URL / Markdown / 主题文本)
↓ source_to_md.py 按类型分派转换器;只有主题或事实不足时走 topic-research
[创建项目 + 归档来源] → sources/、analysis/
↓
[Strategist 策略师] 两阶段确认 → design_spec.md + spec_lock.md
↓
[Image Acquisition] AI 生图 / 网络搜图 / 切片(按需)
↓
[Executor 执行师] 逐页手写 SVG → svg_output/
├─ 先写 P01–P05 → early 质量门
├─ 不间断写完其余页面
└─ final 质量门(0 error 才放行)
↓
[图表校准] 含数据图表时校准坐标
↓
[后处理] finalize_svg.py → svg_to_pptx.py
↓
exports/<name>_<timestamp>.pptx
目录本身就是数据流:svg_output/ 是作者状态,svg_final/ 是派生预览,exports/ 和 backup/ 是派生交付物。分清"源"和"派生",重导出和人工修复才好推理。
如果你赶时间,还有 Quick 模式:跳过策略师规划和确认,一次生成。代价是没有设计规格文件,上下文丢了只能重跑。
六、Agent 工程上的几个取舍
这部分对做 Agent 应用的同学最有参考价值。
1. 单代理多角色,而不是并行子代理
Strategist、Image_Generator、Executor 都跑在同一个主代理里,只是按需加载不同的 references/<role>.md。
理由是页面设计依赖完整的上游上下文:策略师选的颜色、图片是否获取成功、前几页的视觉节奏。子代理只能拿到过期的局部快照,deck 风格会逐页漂移。
同理,禁止分批生成(比如一次 5 页)。分批会加速上下文压缩,一致性的下降比省下的时间更多。
2. 角色专属 prompt,而不是一个超大 prompt
Strategist 是"和用户协商"模式:开放、对话式、可回退。Executor 是"产出严格 XML"模式:不能重选方案,不能漏属性。
把两种纪律塞进同一个 prompt,模型要在同一轮里遵守互相矛盾的要求。按角色拆开,每个角色只加载自己需要的那部分。切换角色前必须重新读取对应规范,这既刷新了指令,也在对话记录里留下审计轨迹。
3. 禁止用脚本批量生成 SVG
页面 SVG 必须由主代理逐页手写,不允许写 Python/Node 生成器批量吐页面。脚本生成会丢掉跨页判断和视觉连续性。
这条和"确定性工具负责转换、校验、打包"形成清晰的分工:创作交给模型,可重复操作交给脚本。
4. 两份规格:给人看的和给机器看的
策略师阶段输出两份看似冗余的文件:
design_spec.md:人类可读,讲 deck 的"为什么",包括沟通意图、受众、叙事逻辑、页面大纲。spec_lock.md:机器可读的执行契约,锁定跨页必须稳定的东西,比如核心 HEX 色、字体角色、图标库、每页节奏(anchor/dense/breathing)、图片分配。
长 deck 最常见的问题是第 20 页的颜色和字号和第 1 页对不上。spec_lock.md 就是对抗这种漂移的锚点。上下文被压缩或会话恢复时,Executor 会重新读一遍。
5. 质量门放在固定节点
节奏是 P01–P05 → early gate → 连续生成其余页面 → final gate。
前 5 页是"方法样本":先在这里把错误模式找出来、修好,再把修正规则带到后续页面。中间不插 checker,避免频繁打断。svg_quality_checker.py 的 error 阻断导出,warning 放行。svg_to_pptx.py 正式导出前,要求有一份与当前页面匹配的 final 质检报告。
作者说得很直白:这些规则看起来很官僚,但 LLM 的默认倾向是"这一轮就把整个问题搞定",而串行流水线最需要的是每一步有边界、过检查点、被下一步消费。
七、“逻辑优先”:先想清楚,再画
PPT Master 不只管排版。策略师在画第一页之前,会先确定核心信息,然后选择一种叙事 mode:
叙事 mode 和视觉风格(内置 18 种,如 swiss-minimal、dark-tech、ink-wash)是两条独立的轴,可以任意组合。策略师会给出三套完整、差异明显的方案,每一套都是整体设计好的,不是从选项里拼出来的。
八、原生能力清单
能力边界也写得很清楚:SmartArt、WordArt、OLE、宏等明确不支持,完整对照见 docs/powerpoint-svg-mapping.md。
图表的默认值是一个值得一提的取舍:默认选择跨端像素一致,而不是原生数据对象。两种都可编辑,选择权留给用户。
九、双向通路:编辑已有 PPTX
除了从零生成,还有一条 Edit Native PPTX 路线:
源 PPTX → pptx_to_svg.py --roundtrip → SVG 工作区 → svg_to_pptx.py --roundtrip → 新 PPTX
既然 SVG 和 DrawingML 能互相映射,就可以把现有 deck 导入成 SVG 让 AI 修改,再编译回去。未修改的页面逐字节保留,支持选页和重排。这让它能直接套用企业已有的品牌模板,这也是很多公司场景里的硬需求。
十、局限
作者自己列得很诚实:
需要配置:要装 Python、克隆仓库、配好 AI 编辑器,不是打开浏览器就能用。
慢:10 页大约 10–20 分钟。逐页串行是为了保证一致性。
没有协作:本地文件,没有共编和分享链接。
依赖模型:模型决定上限。推荐 Claude 或长上下文模型。
不是一次出成品:交付的是高质量草稿,最后一公里在 PowerPoint 里自己改。
十一、总结:可以借鉴的思路
选对中间表示。找一个 AI 擅长生成、和目标格式世界观一致、人能直接预览的中间格式。SVG 对 DrawingML 就是这种关系。
收窄中间语言。不追求兼容整个标准,规范写法越窄,生成越稳、编译越可测。
模型做判断,脚本做确定性工作。创作、构图交给模型;转换、校验、打包交给可测试的代码。
用契约文件对抗上下文漂移。长任务里把必须稳定的决策沉淀成机器可读的锁文件。
在固定节点设质量门。早期样本门 + 最终门,而不是每步都检查,也不是完全不检查。
一致性优先时,慎用并行子代理。共享状态强依赖的任务,单代理串行可能更好。
这些思路不只适用于 PPT。任何"让 AI 生成结构化、可编辑的专业文档"的场景,比如 Word 报告、Excel 模型、设计稿,都可以参考。
参考
技术设计文档:
docs/zh/technical-design.md为什么选 PPT Master:
docs/zh/why-ppt-master.mdPowerPoint ↔ SVG 映射指南:
docs/zh/powerpoint-svg-mapping.md