ppt-image-first:对话优先、图像优先的 PPT 演示稿工作流

ppt-image-first 是一个面向 AI agent 的 PPT 工作流 skill:把一句模糊的「帮我做个 PPT」推进成内容基底、风格预览、定稿规划与可执行的生成流程。仓库形态是标准 skill 结构:SKILL.md 入口契约、四份 references 工作流文档、四份规划文件模板,以及三个承载预览、选图与评审阶段的 HTML 壳子。协议为 Apache-2.0。

项目对输出方式的说明非常坦白,这份坦白本身就是它的定位:整页视觉默认交给图像模型(README 点名 GPT Image 2)渲染成完整页面图,再封装进 PPTX 容器交付;它不是把每个文字框、形状、图表都还原成 PowerPoint 原生对象的「完全可编辑」生成器。成品更接近高完成度的视觉稿式演示页,适合展示、汇报与图像级返修。

一条分阶段的对话,四道确认门

工作流把用户当甲方、把 agent 当提方案的设计侧。 intake 刻意轻量:用途、受众、粗略页数或时长、手头材料,以及学校/公司/实验室/课程/品牌主体这类真实身份锚点;随后输出一段简短的 baseline judgment 就停下。之后按编号阶段推进,并特意留出 1.25、1.5、2.5、2.75 这些半步,让内容、风格与生成永远不在同一口气里被决定。

确认门	位置	锁定的事
需求确认	intake 与 baseline judgment 之后	用途、受众与材料基底已被理解
风格确认	多方向预览与可选 refinement 之后	从真实预览图里选定一个视觉方向
生成前确认	三份规划文件写完之后	生成必须继承的执行计划
初稿评审与返修	第一版整页视觉出来之后	哪些页可以交付;导出只在这之后

README 强调多个确认点是刻意设计而非冗余;workflow 参考文档还给了节奏规则:第一次确认要快,第二次要重,第三次要短,最后的评审阶段则允许反复迭代。

先补内容基底,再谈风格

如果用户没有直接给出完整的报告式叙述,Stage 1.25 会插入一段风格前内容研究,产出 content_report.md。模板给了两种写法:材料已经扎实时「整理但不扩写」;只有主题、薄材料或散笔记时「补强并报告化生成」。无论哪种,文件都必须是一篇连贯的报告式文字,而不是一份干巴巴的提纲。

这一步保证的是下游的诚实:预览页、design_spec、slide_blueprint 与 spec_lock 的内容都从这个基底取料,于是预览是带真实内容的页面而不是空壳,规划文件也不是从裸主题硬编。preview-flow 明确禁止「在此输入」「title here」、lorem ipsum 之类的占位文案,并要求首页反映内容主张、正文页带可信的标题、要点、数字或关系。

风格方向要靠真实预览来判

风格确认不允许只凭文字。每个方向必须生成恰好三张 16:9 的真实图像预览:首页、目录页、正文页。首页看第一印象与隐喻,目录页看风格能否撑起系统页,正文页看视觉语法能否真的承载信息。

内部用一个八维风格向量推理:V1 版式系统、V2 质感与材质、V3 光影与纵深、V4 色彩、V5 容器与母题、V6 密度与节奏、V7 图文平衡、V8 品牌约束强度。控制权的划分是写死的:密度、图文平衡与品牌约束跟用户意图走,版式、质感、光影与容器由 agent 提案。V5 还有一条专门规则:首页用视觉隐喻,正文页用信息容器,且正文页要描述「视觉语法」而不是一个固定版式。

同一方向内的三张预览必须读起来像一个视觉家族:共享的色板角色、光影逻辑、材质语言、容器语法与克制程度。随方向附带的提案卡保持轻量,只有方向名、一句话定位、首页方向、正文页语法、适用场景与风险提示六项。

风格反演与全 deck 连续性锚点

Stage 2.75 是全套流程里最不常见也最有意思的一步:用户选定方向后,agent 把选中的预览图当「证据」做反演,把特征分成三桶——明确应延续的、效果好但需确认是否整套延续的、只在当前图里偶然成立而不建议锁死的。选中图是主证据,原始生成 prompt 只是辅助上下文。

反演结果被压缩成一个 deck 级连续性锚点,至少锁定:基础明度区间与背景倾向、主色与辅色角色、光影模型与纵深强度、材质语言、容器语法与边缘处理、装饰语法、标题与强调语气、克制与张扬的程度。之后每一页的 prompt 都必须先继承这个锚点,这正是它对「同风格不同情绪」漂移的解法。

三份规划文件,固定顺序

风格确认与反演完成后才允许写规划三件套,且顺序固定:design_spec.md 写全 deck 的总理由(项目信息、叙事主线、受众、身份锚点、比例),slide_blueprint.md 写逐页意图,spec_lock.md 作为执行锁。blueprint 模板给了逐页 schema:slide_id、page_role、title、core_message、content_payload、content_basis_binding、claim_status、page_rhythm、text_visual_balance、visual_strategy、continuity_inheritance;其中 claim_status 就是用来标记推断内容的地方,避免没有出处的精确数字冒充用户事实。

spec_lock.md 最后写,只记生成不许偏离的约束:画布格式与比例(默认 16:9)、选定方向、反演出来并升级为硬约束的预览事实、连续性锚点、首页/正文连续性规则与允许的变化范围。三件套写完给用户一段摘要,过生成前确认门。

生成阶段保持 image-first

整轮生成前只问一个分支问题:每页先出 1 张直接进评审,还是每页先出多张候选再挑。多候选路径会装配自带的 candidate picker 壳子,等用户把复制的编号贴回对话,才进入评审。无论哪条分支,生成都必须保持 image-first:规则禁止在图像生成可用时悄悄回落到逐对象拼 PPT、手绘矢量、SVG 式代码或程序化重建,也禁止为了绕开文字渲染难题而偷偷改成无文字背景图。

prompt 侧做元数据隔离:slide 编号、候选码、文件名与批次标签只存在于外部映射表,送进图像模型的 prompt 正文只含面向观众的内容、页角色、视觉方向、连续性锚点与版式意图,生成后再靠文件名把产物接回编号。生成后的 overlay 默认为零:PIL/Pillow 只允许做评审标记渲染、格式转换、尺寸检查与封装支持,不允许创建或修补任何面向观众的页面内容。

评审壳子与返修循环

第一版整页视觉出来不等于交付。agent 装配自带的 review 壳子并在本地打开,把这份 HTML 而不是 PPT 文件当作协作面:页序可见、逐页可写评论,环境支持时还可以用笔刷、矩形、箭头做视觉标注。用户复制回来的是轻量 review-shell-v2 JSON,只带笔记、矩形与笔迹的归一化坐标标记,明确不含 base64 图片。

贴回的 JSON 存盘后用 scripts/render_review_markup.py 把坐标标记画回源图(默认标记色 #bc5b28,圈号数字映射成普通数字,文件名对不上时用 --image-map 兜底),标记图加上单独的文字评论一起作为返修参考。反馈先分类再动手:整页重生成、局部图像编辑、内容/blueprint 问题三类各走各的路。循环重复到用户确认为止,之后才导出最终 PPT 并尝试打开。

仓库里到底带了什么

除散文之外,assets/ 下有三个工作流壳子:preview shell、candidate picker shell 与 review shell,各自带一个 Python 构建脚本,skill 规则把它们当作阶段必备 UI 而不是可选灵感。templates/ 是四份规划文件参考,references/ 是 workflow、conversation framework、style system 与 preview flow 四份文档,docs/ 里有示例页图与一份约 32 MB 的可下载示例 deck——主题就是 ppt-image-first 本身,适合直接感受这套流程的页面完成度。

适合谁,不适合谁

项目自己点名的甜区:答辩稿、研究/项目汇报、产品介绍、路演 deck、培训课件与内部复盘,尤其是用户只有主题或零散材料、希望先看真实视觉方向再定稿的情况。它的对照类是原生可编辑生成器:需要每个文字框都能继续编辑的场景,应该选输出 PowerPoint 对象模型的项目;而看重视觉完成度、叙事深度与已确认风格系统的场景,ppt-image-first 更合适。读它自己的输出说明就是合同:完整页面图装进 PPTX、在图像层返修、经评审循环批准,而不是逐形状编辑。