AI 做 PPT 都在出图，PPT Master 把每张图翻译成了 PowerPoint 原住民

大家好，我是若风。前阵子有个朋友拿着刚生成的 PPT 来找我，说 AI 出片快，但只能在浏览器里看，PPT 里一堆破绽，要么字不能选，要么图全糊了，要么配色沾着改不动，像贴了一层皮。

我原先觉得，这是行业通行做法。AI PPT 工具十个里有九个是把每页渲染成图塞进 pptx，好看是好看了，可它不是 PowerPoint 公民，是住进 PPTX 的外来户。

直到我拆开 PPT Master，才发现 AI 做幻灯片还有另一种走法，它不渲染，它翻译。5.1 万 Star，4135 个 fork，作者 Hugo He 是个注册会计师，不是程序员出身。他自己天天审改 PPT，受不了 AI 出的是死图，就自己动手写了个方案，让 AI 生成的每一页，都变成 PowerPoint 原生对象，能点、能选、能改。

那它到底怎么做到的？今天我把它拆开看。

一句话定位

PPT Master 是一个跑在任何 Agent 能力 AI 工具里的工作流，你喂它 PDF、DOCX、网页或者一个主题，它在你本地跑完全流程，导出原生可编辑的 pptx。它不是一个一键生成的 SaaS，是一套带路由、带质量闸门、带角色分工的「技能包」，装进 Claude Code、Cursor、Codex 里用。

选品看三点。第一，有可拆的源码，244 个 Python 文件，核心管线从 source_to_md 一路到 svg_to_pptx，全是具体实现。第二，有文档化的设计哲学，docs/technical-design.md 把每个架构决策的为什么都写了。第三，有真实痛点可以验证，GitHub issue 249 就有人抱怨新版本不如 2.x 好看。三条都齐，标准深挖型。

坦白讲，「可编辑器」这个词本身就是最大的陷阱。市面上标榜可编辑的 AI PPT，大多数只是把文字和背景拆成两层嵌进去，图片还是整张、阴影还是死的，你动一下它，整页就崩。PPT Master 要的不是这种可编辑，它要的是把 PowerPoint 的原生对象模型本身交给你，这个标准完全不同。

先想清楚一件事，AI 到底该输出什么

从用户视角看，问题很平。AI 出 PPT，无非两种终点，要么渲染成图片嵌进 pptx，要么直接把 PowerPoint 的 XML 写出来。前者不可编辑，后者是死路。

时间线先理清，作者在 technical-design.md 里把这三条路逐个否掉，都是「为什么」级别的否决。直接生成 DrawingML，那是 PowerPoint 的地底层语言，一个圆角矩形要嵌套几十行 XML，AI 的训练数据里这种东西极少，输出不可靠，肉眼根本没法调错，这是第一个「为什么」。

HTML/CSS 是第二条否决。HTML 描述的是文档，讲究内容流，标题、段落、列表按顺序排，而 PowerPoint 描述的是画布，每个元素都是绝对定位的独立对象，没有流，没有上下文。这不是布局计算问题，是世界观冲突。就算你解决了浏览器排版引擎那个百万行级问题，一个 HTML 表格也映射不成一组独立的幻灯片形状，这是第二个「为什么」。

WMF/EMF 是第三条。它是微软自家矢量格式，跟 DrawingML 同宗同源，转换损耗最小，可 AI 对它的训练数据几乎为零，这条路出生即死。技术文档原话是，连微软自家格式都输给了 SVG，这是第三个「为什么」。

三种互斥的方案都用同一个标准淘汰，一是 AI 训练数据覆盖度高不高，二是和 DrawingML 的映射是否天然。最后剩下 SVG，两个条件同时满足。SVG 和 DrawingML 是同一个世界观，绝对坐标二维矢量，矩形、路径、渐变、阴影一一对应。文档里那张映射表值得摘出来看。

但关键在下一句，这个 SVG 是项目专用中间语言，不是浏览器的 SVG。

这是 PPT Master 最容易被误解的一层，它接收的 SVG 是有白名单的。项目契约规定允许哪些元素、哪些属性、哪些单位、哪些元数据，还有对应的 DrawingML 映射，超出映射范围的输入一律报错阻断。技术文档原话是，SVG 适应 PPT Master，不是 PPT Master 去追随整个 SVG 标准。

这套契约把输入分成三态。规范作者输入，是提示词、模板、示例产出的唯一推荐写法，校验后直接编译。兼容输入，是历史遗留或手写输入，有且只有一个确定性的归一化路径，检查器给非阻断警告，转换器在编译边界归一化。无效或不支持输入，没有映射、含义模糊、结构契约破损，检查器报错阻断标准流程。

举个具体的，项目排版用 SVG px 语义，font-size="24" 这种无单位有限值才是规范写法，另一种单位只有当转换器能确定性归一化、检查器认作兼容时才能进，且永远不成为新的生成写法。兼容可读，是被控的迁移边界，不是扩权的许可。

为什么较这个真？因为 AI 生成不收敛，长 deck 里兼容性越界会不断冒出来，最后在 svg_to_pptx 中途夭折，或 PowerPoint 悄悄丢元素。把「第 14 页导出失败」变成「第 14 页违反 SVG 兼容契约」，排查成本降一个数量级，这也是长 deck 能迭代起来的经济基础。

把整条链路摊开看，长这样，五层，从路由到输出。

这张图从上往下，就是一次生成的真实路径，SKILL.md 先定纪律，routing.md 选路，角色层负责想和画，中间语言层保留作者意愿，谱译层把 SVG 变成 PowerPoint 真的认的东西，输出层落盘。中间语言层高亮，因为它是整套设计的承重墙。

逐元素派发，而不是整文件翻译

svg_to_pptx 的入口是个薄壳，真正干活的是 svg_to_pptx/drawingml/converter.py，2454 行，开头文档写的是 Core SVG -> DrawingML dispatcher, group handling, and main entry point。

它为什么不整文件翻译？converter.py 的文档理由很工程，SVG 的层级模型和 DrawingML 的 group / shape / picture 类型天然对应，不需要一个整体优化器去重排页面。每个形状种类一个窄小的 translator，每个 translator 简单到能独立单测和调试。一页的输出质量，是无数独立本地转换之和，这个性质在整文件翻译下脆弱，在元素派发下稳固。

从文件里能看到这个派发粒度有多细。converter.py 锚着十几个预检函数，_require_project_freeform_geometry、_require_project_stroke_styles、_require_project_image_aspect_ratios、_require_project_line_end_markers、_require_project_gradients，每个函数管一类兼容性。文本处理那里还做了个很硬的工程决策，_require_project_text_properties 旁边挂着 tspan_flattener，因为 DrawingML 的文本游程不支持段中重新定位，一个用 dy 叠起来的 块，如果不压平，导出后全挤在一条基线上。

图标也有一层自己的展开器。use_expander.py 585 行，开头就解释，DrawingML 不认识 <use data-icon="...">，如果不先展开，每个图标都会悄悄消失。展开在内存里做，svg_to_pptx 直接读 svg_output，不用先落盘 finalize，内部限了 64 层深和 1 万个实例，防止恶意或失控的引用图把自己卡死。

187 个 Office 预设形状是另一块硬核。pptx_shapes/registry.py 里有 PresetShapeRegistry，求值函数接收 rightArrow、320、160 这种参数，返回几何。底层数据是 pptx_shapes/data/presetShapeDefinitions.xml，来自 OpenXML SDK 的标准定义，连微调手柄和连接点都在，所以 AI 画的箭头、标注框、流程图节点，导出后还带着 PowerPoint 的调整点，能拖。技术文档里写的 187-name preset-shape vocabulary，指的是 Office 的预设几何表，不是 PPT Master 自己攒的。

AI 画图，脚本把关，两把闸门

生成链路跟所有的 AI 内容工具一样，核心问题是不确定性。svg_quality_checker.py 就是给不确定性上的保险。

它的设计思路，是让检查器永远不自动修。技术文档里写得很坦白，机械补丁会悄悄覆盖有效的设计意图，发出一张更差的页，所以要 AI 自己重画，再重跑检查。扫描器（checker.py 9554 行）按契约读 svg_output，报告三类问题，阻断报错、非阻断警告、遗留来源问题。

闸门有两道。早闸门在 P01 到 P05，头 5 页当方法样本，AI 先把全部问题集分类，把每个阻断错误和选中的警告修完，再继续生成剩余页，中段不插检查，6 页以内的 deck 直接跳过早闸门。最终闸门在全部页面完成后跑，零阻断错误才允许导出。svg_to_pptx.py 那边还有个配套逻辑，正式发布导出会核对质量报告的指纹，报告缺失或过期就拒绝生成 pptx，防止有人绕过闸门直接拿源 SVG 出片。

图表还有一道独立的几何校验，坐标不正确这个类别，SVG 合法但柱高、扇区角度、坐标轴刻度是错的，检查器抓不住，所以 verify-charts 阶段跟检查器挂在同一个闸门上，让 AI 在同一个认知上下文里回看自己画的东西。

把三态判定和两把闸门拼起来看，一条完整的水路就出来了。

左侧三列是契约的三态，中间是永远不自动修的检查器，右侧是转化器和它背着的两把闸门。无效输入走的是虚线，说明它压根进不了编译，这是失败关闭，不是宽容放行。

只跑单 Agent，不跑一堆子 Agent

这也是个反直觉的架构决策。明明是多阶段长流程，为什么不让 Strategy Agent 分头干活？技术文档给了三个理由。

第一，子 Agent 拿到的是过期的 deck 状态快照。页面设计依赖完整上游上下文，Strategy Agent 的配色、真实拿到的图片资源（哪些失败了被替换了）、前面页面的视觉节奏，一个子 Agent 起步时手里只有残缺快照，视觉必然漂移。

第二，同一个逻辑禁止按批生成页面。每回合生成 5 页看似提速，代价是上下文压缩加速，deck 视觉一致性崩塌的速度，比省下的时间快得多。

第三，角色靠指令文件切，不靠独立 Agent 切。Strategy Agent 跑的是「跟用户谈判」模式，开放式对话、允许后退，Executor 跑的是「产出严格 XML」模式，可以重构图，但必须准守细节。两个模式塞一个 Agent 里会混成四不像，拆成 role 文件，每个角色只加载自己需要的部分。

这个决策的代价很直白，Why PPT Master 文档自己写了，10 页 deck 要 10 到 20 分钟，串行逐页生成，SaaS 几秒就出一坨。PPT Master 把速度让给了质量一致性和可编辑性，这是个定位问题，不是缺陷。

模板是合约，不是相似度

模板系统里 PPT Master 也逆着行业套路走。它不是按主题相似度帮你选模板，而是把模板冻结成一等公民。

默认流程的第三步只准备候选，不打开 UI、不读模板内容。第一阶段把「沟通建议」和「自由设计 / 用模板」两个选择一起摆给你，普通请求默认自由设计，只有显式点名模板意图或给了 workspace 根目录，才进模板模式。系统永远不按主题相似度挑模板。

技术文档为「自由设计为何保留显式选项」写了一段很妙的解释，模板是地板，容易变成天花板。模板会把 deck 锁进模板的视觉语言，不管内容本身想怎么讲。自由设计的版面结构来自源内容，视觉节奏跟内容走，而不是跟固定语法走。

这套系统把模板分成四类，brand 管身份，style 管方向和方法，layout 管品牌中立结构，deck 管应用和身份结构一体。一个 workspace 根目录就是一次原子安装，四个种类至多各贡献一个 spec 文件，以 segments 级别解析所有权归属。这套明细管理会写出一个 master 和 N 个 layout，然后把虚位映射成 placeholder 绑定，是 PowerPoint 真正的原生结构。

诚实的边界，以及一处刺眼的回归

先说新鲜热辣的一条反例。issue 249 是 2026 年 5 月底提出来的，标题是「感觉新版本没有之前 2.x 版本生成的 PPT 好看」，作者用 GPT-5.6 跑了一遍自查，怀疑是风格、图标、布局都没按规格执行，说他自己的诊断结果是规则更少但设计指令更具体、执行链更短的时代更好看，现在是规则更完整、配置更精细，但中间层更多，而且缺风格落地和图标覆盖的强制验收。这个 issue 目前还开着，4 条评论。

这个证据打的是规则工程化的脸。规则越多，越会稀释设计的强表达，checker 只保证合规，管不了审美，规则保证你不越界，但保证不了好看。那位用户踩到的坑，恰好是文档里反复强调的「三层分离」的边界本身。

然后是明牌的边界清单，这些不是隐藏缺陷，是白纸黑字的定位声明。SmartArt 刻意不做，因为那是个封闭又脆弱的对象模型，拆成普通原生形状重建更好。原生 WordArt 和扭曲文字不做，AI 生成的装饰字体加普通可编辑文字已经覆盖用例。反射、柔化边缘这类装饰效果不做。OLE、视频、宏这些内嵌或陈旧对象不做，因为这些需要宿主应用或较新 Office 版，在别的机器上会退化成静止预览，恰好是这项目要避免的跨渲染器退化。

依赖和速度也是硬边界。requirements 里 python-pptx、PyMuPDF、edge-tts、uharfbuzz、skia-pathops 这些都是本地跑，部署确实只要求 Python 3.10+，但生成速度实打实，10 到 20 分钟出 10 页，串行逐页。没有协作，本地文件没有实时共同编辑，没有分享链接。如果你要的是零安装、浏览器里秒出，SaaS 才是对的。

另外两个 README 里没细说的坑，值得单独提。第一，默认出片不嵌字体，品牌字体或网络字体只有在目标机器确认装了才生效，否则退回安全字体家族，设计规格里记录的字体意愿不等于最终文件里的字体。第二，图表表格默认导出为 SVG 派生的可编辑形状，跨 Keynote、LibreOffice、WPS 渲染像素一致，但你要的是带 Edit Data 工作簿的原生数据图表，得显式开 --native-charts-and-tables。这个二选一是设计选择，不是缺陷，但 README 服务端描述得不够显式。

给代码审查者的一张 TODO 清单

拆完 PPT Master，有一招值得单独收走，我管它叫「符合性中间格式」模式。你想让 AI 产出某种晦涩、冗长、训练数据稀少的格式（DrawingML 就是典型），不要逼 AI 直接写它。换个思路，挑一种 AI 擅长、又有确定性转换中间人的格式，然后把中间格式收窄成白名单语言，白名单之外的输入一律阻断，用一条契约同时管住生成质量和转换安全。

这个模式的三个要件，PPT Master 一个不缺。第一，中间格式要跟目标格式共享世界观，SVG 和 DrawingML 都是绝对坐标二维矢量，映射是方言翻译，不是格式桥。第二，质量闸门放在后处理之前，后处理会重写 SVG，可能掩盖源头违规，要读作者真正产出的 svg_output。第三，检查器永远不自动修，修是 AI 的事，check 是脚本的事，混了就会出 issue 249 那种在审美线上的漂移。

那什么时候该绕开 PPT Master？要零安装、秒级出片、浏览器里能协作，选 SaaS。要交付给甲方一份深度原生、可继续编辑、能蒸馏成自家模板的 deck，PPT Master 值得装。它 5 万 Star 不全是虚火，它解决的是「AI 出片不能改」这个真痛点，只是解法是有代价的，代价是速度，和一条你绕不开但没有它走不通的中间格式。

最后说两句。我自己写博客、做分享，被「AI 出片不能改」坑过不止一次，所以看到这种把可编辑性当真问题的项目，天然有好感。它的作者是个非科班出身的人，靠 Python 和 Agent 的耐心把这条路趟通了，这件事本身比 PPT 更值得看。你不需要会用 PowerPoint 高级功能，你只需要知道，出片之后你还想不想接着改，想，就值得装。