ppt-master 实测:77k 星的 AI 生成 PPT 工作流,我解包验证了它的「原生可编辑」承诺

用 AI 生成 PPT 的工具不少,但它们交回来的东西大多是一张张图片,或者一个个不可编辑的文本框拼贴——想改个数字、换个颜色,只能重新生成一遍。GitHub 上有个叫 ppt-master 的开源项目不这么干:它让 AI 把每一页写成 SVG,再由本地脚本把 SVG 编译成真正的 DrawingML——形状是形状、文本是文本框、图表带着可编辑的数据工作簿。11 月 18 日我用 GitHub API 现查,它 77,939 star、MIT 协议、昨天(11 月 17 日)还在推送代码。我花了一个上午在 M4 Mac 上把它的生成链路、原生承诺和 Agent 全流程各跑了一遍,这篇是结果。

它是什么:一条「SVG 进,PPTX 出」的编译管线

ppt-master 不是网站也不是 App,是一套跑在任意 Agent 工具(Claude Code、Cursor、opencode 都行)里的技能包:Python 3.10–3.14,克隆下来装好依赖就能用。它的架构分两半:

  • Agent 侧:读源文档、定设计规格、逐页手写 SVG。SVG 不是随便画的,要遵守一套作者契约(1280×720 画布、语义分组、文本必须用 <text> 节点);
  • 本地脚本侧:质检器先验契约,导出器再把 SVG 编译成原生 PPTX。这一侧完全确定性,不花一个 token。

技能入口 SKILL.md 只有 143 行(我用 o200k 计数器量了,2,380 token),但整个技能包有 230 个文档、合计约 48.9 万 token——这个数字后面会再出现,它和一次实测的账单直接相关。

实测一:质检器是个「fail-closed」的门,我先喂了它三个真实错误

在跑 Agent 之前,我手工写了 4 页 SVG 直接过管线,想看看它到底拦什么。结果三个错误全是它抓的,而且每个都拦得有道理:

  1. 我把图表标题写进了元数据 JSON,但没在可见的 SVG 回退图形里画出来——它直接报错:这段文字只在原生导出时出现,属于「隐藏文本」,要么删掉要么画出来。这条规则挺讲究:它防止「导出前预览和导出后成品不一致」。
  2. 一个分组没写 data-pptx-bounds,报错。原生 PPTX 对象必须有明确的边界框,SVG 里不写清楚就没法编译。
  3. 图表容器边界写小了,几行文字超出容器 10 个像素,报错——而且是逐行指出来「这行字超在哪条边上」。

三个都修完,质检通过,我用 stamp_native_fallbacks.py 给原生对象盖了基线哈希,然后加了 --native-charts-and-tables 参数导出。这套「先质检、再盖章、后导出」的顺序是硬性的:质检不过关,导出器拒绝工作。我试过故意不修,它确实一动不动。对生产工具来说,fail-closed 比 fail-open 安全得多—— 宁可不出,不出错的文件。

实测二:「原生可编辑」是真是假,解包见分晓

这是这次实测最想验证的声称。用 python-pptx 把导出的 PPTX 拆开看:

  • 第 1 页我画的封面:标题和副标题是 3 个真正的 TEXT_BOX,背景矩形被自动提升成了母版层的形状;
  • 第 4 页我标记的图表:是一个真正的 PowerPoint 原生 CHART 对象,类型 COLUMN_CLUSTERED,三个分类和数值一字不差,更关键的是包内嵌着一个 Excel 工作簿(ppt/embeddings/Microsoft_Excel_Sheet401.xlsx)——意味着你在 PowerPoint 里右键「编辑数据」是真的能改数、图会跟着变的;
  • 同页的表格也是原生 TABLE,三行两列,每个单元格都是真文本。

换句话说,「原生可编辑」不是营销词。AI 写的是 SVG,但用户拿到手的是可以在 PowerPoint 里逐个对象改的东西。顺带说下速度:4 页导出含质检报告落盘,总耗时 0.91 秒,这一步完全本地、零 token。

实测三:免费模型跑通全流程,但烧了 190 万输入 token

最后跑完整闭环。我写了一份 19 行的《API 设计速查》文档扔给它,用 opencode 挂 OpenRouter 的 cohere/north-mini-code:free(0 美元档),指令只有一句:quick generate,5 页,中文,16:9,不要图。

4 分 15 秒后,5 页 SVG 全部生成、自检通过,内容忠实度不错:「用复数名词」「游标分页优于 offset」「Idempotency-Key 保证幂等」这些源文档要点都在页面上。我从 opencode 的数据库里把这次会话的账单捞了出来:输入 1,930,338 token,输出 42,694 token。输出少(就是那几页 SVG 和过程日志),输入接近 200 万——免费模型在 OpenRouter 上不享受缓存,SKILL.md 虽然只有 2,380 token,但路由文档、生成规范、各种参考文档会被反复读。如果换成付费模型按输入计费,这一次 5 页的生成大约要花 1 到 2 美元(以主流模型 1–3 美元/百万输入 token 的价位估算)。「开源免费」指的是软件本身,token 账单是实打实的,页数越多、文档越长,这个数越大。

还有一个坑值得写下来:Agent 在生成完 SVG 后自己尝试导出 PPTX,失败了——因为 opencode 用的系统 Python 没装 python-pptx,而我把依赖装在了独立 venv 里。最后是我切到 venv 手动跑导出命令补完的。如果你在自己的环境里跟这个教程,把 pip install -r requirements.txt 装到 Agent 实际会用的那个 Python 里,就能避免这一步。

值不值得用:我的判断

先说它适合谁:手里有现成文档(Markdown、PDF、Word 都支持)、想要一份能继续改的原生 PPT、已经在用 Claude Code 或 opencode 这类 Agent 工具的人。它把「排版体力活」变成了「审稿活」,这点和之前测过的 sand3d 让 LLM 写 3D 模型是同一个思路——模型负责生成结构化产物,确定性编译器负责落地。

三种情况不建议用:

  1. 急用。一次生成几分钟起步,token 大户,想「10 分钟出活」不如手改模板;
  2. 想要绝对的设计水准。免费小模型生成的版式能用但平淡,官方 FAQ 也直说质量上限由模型决定,想出惊艳的效果要用大上下文的旗舰模型,token 账单也水涨船高;
  3. 没装 Agent 工具、只想网页上点一下。这不是 SaaS,没有网页版,上手门槛是「会用命令行」。

再给两个上手提示:第一,纯文字版式(不生成图片)可以完全避开对图像生成 API 的依赖,Openverse 图搜是零配置的备选;第二,它支持 8 种画布,除了 16:9 还有小红书 3:4、朋友圈 1:1、竖屏 9:16,做社媒图文比做汇报 PPT 更轻——之前写 caveman 省 token 时说过「Agent 的产出物越小越便宜」,这里同样成立,5 页竖图比 20 页横版 PPT 的账单低一个量级。

想现在就试的话,下面是我本次实测用的最小上手路径(运行环境:macOS 26.5.2 / Apple M4 / 16GB,Python 3.13.12,依赖装进独立 venv 并让 Agent 也能用同一个 Python——这是我踩过的坑):

Bash
# 1. 克隆仓库并安装依赖(纯本地,不需要任何 API Key)
git clone https://github.com/hugohe3/ppt-master.git &#x26;&#x26; cd ppt-master
python3 -m venv venv &#x26;&#x26; ./venv/bin/pip install -r requirements.txt

# 2. 在 Agent 工具里打开这个目录,说一句话:
#    "Quick generate a 5-page PPT from projects/demo/sources/xxx.md,
#     Chinese deck, 16:9, pure vector design."
#    SVG 生成后,导出用 venv 里的 Python 跑(不要用系统 Python):
./venv/bin/python skills/ppt-master/scripts/svg_to_pptx.py \
  projects/&#x3C;你的项目目录> --quick-generate \
  -o projects/&#x3C;你的项目目录>/exports/deck.pptx

# 3. 可选:要 PowerPoint 原生图表/表格对象(可右键"编辑数据"),
#    SVG 里按契约写 data-pptx-replace-with 标记后加参数导出:
./venv/bin/python skills/ppt-master/scripts/svg_to_pptx.py \
  projects/&#x3C;你的项目目录> --quick-generate --native-charts-and-tables \
  -o projects/&#x3C;你的项目目录>/exports/deck_native.pptx

结尾

这套工具让我比较意外的地方是那个质检器:它不信任 AI 的产出,每一页都按契约验一遍,验不过就不放行。AI 负责创意和结构,脚本负责确定性和兜底,这个分工比例拿捏得比很多「一句话生成 PPT」的 SaaS 要诚实。如果你的日常就是和文档、PPT 打交道,值得装一份试试——记得先确认 Agent 用的 Python 环境里有 python-pptx,这是这次实测里我替你踩掉的坑。

相关阅读:LoopForge 实测:腾讯开源的编码 Agent 交付引擎、agent-desktop 实测:给 AI Agent 的电脑操控 CLI、open-code-review 实测:阿里开源的 AI 代码审查 CLI。

推荐阅读

  • cognee 实测:3.3 万星的 Agent 长期记忆库,我在 M4 Mac 上喂了三句中文笔记,问它要回了端口和 bug 备忘

    给 AI Agent 装长期记忆的 cognee,我在 M4 Mac 上完整实测 1.6.10:全本地模式 0.1 秒检索但答案是半成品,接免费模型后三句中文笔记答对端口和 bug 备忘、改写问题不迷…

  • Univer 实测:不开浏览器也能算 Excel 公式,Agent 写表格前先弄清三处静默改数据

    Univer 1.5.2 的开源部分能在纯 Node 里跑表格引擎:建表、写公式、跨表引用、存快照。我在 M4 Mac 上跑通 34 条公式和一份端到端销售报表,六项指标与 Python 独立核算完全…

  • LoopForge 实测:腾讯开源的编码 Agent 交付引擎,我用免费模型跑通了一条完整 SOP 交付线

    腾讯开源的 LoopForge 把编码 Agent 的交付流程做成 SOP 引擎:角色分离、人工门禁、需求追踪。我在 M4 Mac 用 Local 版装进 Codex 和 opencode,免费模型一…

  • open-code-review 实测:阿里开源的 AI 代码审查 CLI,我种的 5 个 bug 它全抓到了

    阿里开源的 open-code-review 用确定性流水线锁死代码审查流程,Agent 只做动态决策。我在 M4 Mac 实测 v1.13.9:种 5 个缺陷的 diff 全部命中、0 误报、行号精…