聪叙
发布于 2026-10-24 / 8 阅读
0
0

ppt-master-技术分享

让 AI 做出"真·可编辑"的 PPT:PPT Master 技术拆解

项目地址:https://github.com/hugohe3/ppt-master
版本:SKILL v6.7.3 · 许可证:MIT

一、问题:AI 做 PPT,难点不在"画"

市面上的 AI PPT 工具很多,但交付物大致分三类:

  1. 整页图片:好看,但文字不能选、颜色不能改,本质是截图。

  2. 套模板填文字:可编辑,但只是"能改的表皮",版式死板。

  3. 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/:

目录

作用

SKILL.md

入口:全局执行纪律 + 路由交接

workflows/

各条路线的运行时流程(生成、编辑原生 PPTX、创建模板等)

references/

按角色拆分的提示词规范(strategist / executor-* / image-* ……)

scripts/

确定性工具:源文档转换、SVG 质检、SVG→PPTX 编译器、PPTX→SVG 回导等

templates/

品牌、版式、图表、图标、整套 deck 模板

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/skills/ppt-master/

<项目>/.claude/skills/ppt-master/

Codex

~/.agents/skills/ppt-master/(旧版本为 ~/.codex/skills/)

<项目>/.agents/skills/ppt-master/

Hermes Agent

~/.hermes/skills/ppt-master/

<项目>/.hermes/skills/ 或 <项目>/.agents/skills/

方式二: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)

作者在技术文档里把候选方案逐个排除了一遍:

方案

问题

直接生成 DrawingML

极其繁琐,一个圆角矩形要几十行嵌套 XML;训练数据少,生成不稳定,肉眼没法调试

HTML/CSS

世界观不同。HTML 是文档流,PPT 是绝对定位画布。一个 <table> 没法自然变成几个独立形状

WMF/EMF

微软原生矢量格式,转换损耗理论最小,但 AI 几乎没见过,死在起点

SVG 渲染成图片嵌入

最简单,但彻底丧失可编辑性

SVG 胜出,因为它和 DrawingML 是同一类东西:都是绝对坐标的 2D 矢量格式,概念可以一一对应。

SVG

DrawingML

<path d="...">

<a:custGeom>

<rect rx="...">

<a:prstGeom prst="roundRect">

<circle> / <ellipse>

<a:prstGeom prst="ellipse">

transform

<a:xfrm>

linearGradient / radialGradient

<a:gradFill>

fill-opacity

<a:alpha>

所以转换是"方言翻译",不是"格式代沟"。而且 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 标准。

输入被分成三种状态:

状态

处理

规范创作输入

提示词和模板只生成这一种写法,直接编译

兼容输入

已登记、可安全归一化的历史写法;Checker 给 warning,转换器归一化后编译

非法输入

无映射、有歧义、可能产出坏 PPTX;Checker 报 error 阻断

原则叫"规范窄写入、受控兼容读取"。比如颜色只允许六位大写 #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

适用场景

pyramid

结论先行的说服

narrative

讲故事

instructional

教学

showcase

展示

briefing

中性信息通报

叙事 mode 和视觉风格(内置 18 种,如 swiss-minimal、dark-tech、ink-wash)是两条独立的轴,可以任意组合。策略师会给出三套完整、差异明显的方案,每一套都是整体设计好的,不是从选项里拼出来的。

八、原生能力清单

能力

实现

母版与版式

真正的 p:sldMaster / p:sldLayout 继承

形状

187 种预设几何,带调节手柄;连接线;自由路径

图表 / 表格

默认导出为 DrawingML 形状,保证 PowerPoint、Keynote、LibreOffice、WPS 显示一致;加 --native-charts-and-tables 导出带"编辑数据"工作簿的原生对象

公式

LaTeX/mhchem 编译为 OMML,支持块级和行内,不生成公式图片

超链接

SVG <a href> 编译为 relationship,#slide-N 支持页内跳转

动画 / 转场

真正的 OOXML 计时,包括 Morph

旁白

演讲者备注转语音,支持声音克隆

能力边界也写得很清楚: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 里自己改。

十一、总结:可以借鉴的思路

  1. 选对中间表示。找一个 AI 擅长生成、和目标格式世界观一致、人能直接预览的中间格式。SVG 对 DrawingML 就是这种关系。

  2. 收窄中间语言。不追求兼容整个标准,规范写法越窄,生成越稳、编译越可测。

  3. 模型做判断,脚本做确定性工作。创作、构图交给模型;转换、校验、打包交给可测试的代码。

  4. 用契约文件对抗上下文漂移。长任务里把必须稳定的决策沉淀成机器可读的锁文件。

  5. 在固定节点设质量门。早期样本门 + 最终门,而不是每步都检查,也不是完全不检查。

  6. 一致性优先时,慎用并行子代理。共享状态强依赖的任务,单代理串行可能更好。

这些思路不只适用于 PPT。任何"让 AI 生成结构化、可编辑的专业文档"的场景,比如 Word 报告、Excel 模型、设计稿,都可以参考。

参考


评论