ppt-builder（PPT 生成器）

PPT Builder

从一句话需求到高品质演示 PPT 的完整方法论。覆盖内容策划、文案撰写、视觉设计、AI 生图、QA 迭代、交付全流程。

When to Use

• 用户想从零开始做一份演示 PPT（产品演示 / pitch deck / 培训材料 / 报告）
• 用户有一个主题但还没有具体内容
• 用户已有内容文档但需要高品质视觉呈现
• 用户想用可复现、可迭代、低成本的方式生成 PPT

核心理念

内容和形式分离。分三步走，每步独立交付、独立审批：

下游不反向改上游。如果 Step 3 生成时发现某页内容装不下，回 Step 1 改内容，不在 Step 3 里"压一压"。

工作流总览（7 个阶段）

阶段 1 Brainstorming → 收敛决策，形成定位 阶段 2 Spec 文档 → 大纲 + 多轮自审 → 批准 阶段 3 内容文档 → 每页文案 阶段 4 设计文档 → 视觉系统 + 模板 + 每页指令 阶段 5 PPT 生成 → Nano Banana 逐页生图 + 组装 阶段 6 QA 迭代 → 只修有问题的页 阶段 7 交付 → pptx + pdf

阶段 1：Brainstorming

目标：把模糊的需求收敛为一份明确的决策清单。

推荐 Skill：如果已安装 idea-to-design（头脑风暴 · 从想法到设计），可以先调用它完成通用的 brainstorming 流程（探索上下文 → 逐一提问 → 提出方案 → 呈现设计 → Spec 自审）。本阶段的 PPT 专属决策项作为 brainstorming 的具体问题输入。

方法

每次只问一个问题，给 3-5 个选项，标注你的推荐。等用户回答后再问下一个。不要一次性抛多个问题。

必须收敛的决策

关键原则

• 接纳用户的重新定义。用户可能打断你的问法，提出更好的流程框架，接受它
• 不要在 brainstorming 阶段写任何内容。只做决策，不写文案
• brainstorming 结束的标志：所有决策项都有明确答案

阶段 2：Spec 文档

目标：写一份全局定位 + 每页大纲 + 视觉方向的 spec 文档。

文档结构

[Deck名称] - 设计文档

1. 全局定位（阶段 1 所有决策的汇总表）

2. N 页完整大纲

### Part X — [章节名]（M 页） | # | 页面 | 核心论点 | 必备内容 |

3. 生产流程（三步走 + 每步的验收标准）

4. 视觉方向（色彩/字体/背景/关键视觉元素）

5. 风险和待补项

6. 不在范围（Out of Scope）

必做：多轮自审

Spec 写完后必须至少做两轮自审，不审不进下一步。

第一轮：受众视角审

站在目标受众的角度读一遍大纲，问自己：

• 开场有没有让我继续读的理由？（钩子）
• 这份 deck 70% 在讲我的世界还是在讲产品？（应该是前者）
• 读完我能做什么？（CTA 必须具体可行）
• 有没有让我感觉"又是一个卖概念的"？
• 每一页的标题是我会问的问题还是产品经理的术语？

详细检查清单见 references/spec-review-checklist.md

第二轮：文案质量审

grep 扫描禁用词（见 references/writing-principles.md），确保零正文命中。

如果自审发现问题

直接改。改完不需要重新审——修了就过。但严重问题（如结构性缺失）需要标注版本号（v1 → v2）并记录变更原因。

阶段 3：内容文档

目标：写 content.md，覆盖每一页的完整文案。

粒度策略

每页标准格式

Slide N - [标题]

核心论点：[一句话，这页要让读者记住什么] 详细文案：[终稿文字 或 3-5 个 bullet 要点] 图片意图：[需要什么视觉素材——只讲意图不讲样式] 关键数据（可选）：[数字和引用来源，占位用 [待补]]

写作铁律

1. 用事实和数据制造张力，不用形容词
2. 具体 > 抽象——每句话要么是事实、要么是具体动作
3. 先演示后下定义——核心 claim 放在故事讲完之后
4. 数据克制——没有真实数据就用 [待补]，别编
5. 每个 CTA 必须此刻能兑现——不承诺不存在的产物
6. 占位符统一格式——全部用 [待补]，不用 TBD / TODO

详细写作原则见 references/writing-principles.md

验收

• 禁用词 grep 零正文命中
• 核心 claim 只在指定页出现（如有）
• 人物 / 数字 / 名称全 deck 一致
• 每页都有"核心论点"（没有空壳页）

阶段 4：设计文档

目标：写 design.md，定义视觉系统和每页的具体版式。

文档结构

§1 视觉系统

色彩（hex 值 + 用途）/ 字体（字号层级）/ 背景 / 标志性元素 / 间距

§2 页面模板库（6-10 种）

每种模板：用途 / Wireframe / 元素清单 / 尺寸 / 变体 / 禁止事项

§3 每页设计指令

每页：模板 / 文案来源 / 图像清单 / 版式要点

§4 AI 插图 Prompt 清单

概念插画（需要 AI 生成的）/ 示意图（脚本生成的）/ 图标

§5 降级版规范（可选）

投影仪 / 打印 / 移动端 的适配规则

模板设计原则

• 模板数量 6-10 种（太少挤进不合适的模板，太多视觉碎片化）
• 最复杂的模板优先设计——它的质量决定全 deck 品质上限
• 每个模板的"禁止事项"和"允许的变体"必须明确

每页设计指令格式

Slide N - [标题]

模板：[模板名或变体] 文案来源：content.md Slide N 图像清单：

• [ILL-N / SCR-N / DGM-N / ICO-N：描述]

版式要点：

• [2-3 条具体指令]

阶段 5：PPT 生成

目标：用 Nano Banana Pro 逐页生成幻灯片图片，组装成 pptx。

技术栈

• 模型：Nano Banana Pro（Gemini 图像生成模型）
• API 网关：Ofox（无需 VPN）或 OpenRouter
• 组装工具：python-pptx（将每页 JPG 塞进空白 slide）
• 成本：约 ¥0.1-0.3 / 页

生成脚本

安装后运行：

# 1. 复制 slides.example.json 为 slides.json，填入你的 prompt cp scripts/slides.example.json scripts/slides.json

# 2. 生成全部页 python3 scripts/generate_deck.py

# 3. 只生成第 1-5 页 python3 scripts/generate_deck.py --start 1 --end 5

# 4. 重跑某页（删旧图再跑） rm scripts/output/slide_03.jpg && python3 scripts/generate_deck.py --start 3 --end 3

# 5. 生成完自动组装 PPTX python3 scripts/generate_deck.py --assemble

slides.json 格式：style（全局风格前缀）+ slides 数组（每页一个 num + prompt）。 见 scripts/slides.example.json 示例。

依赖：pip install python-pptx（仅组装 PPTX 时需要）

全局风格 Prompt

每页 prompt = 全局风格前缀 + 页面具体内容。

全局前缀应包含：角色设定（"你是一名顶级 PPT 设计师"）、输出格式（"16:9 比例的幻灯片图片"）、设计风格要求（从 design.md 提取的背景、色彩、字体）、中文渲染强制要求、"只生成一张图片"。

每页 Prompt 写作规则

详见 references/prompt-writing-guide.md，核心要点：

1. 文案从 content.md 原文复制——不让 AI "发挥"
2. 颜色用 hex 不用名字——精确色值，不是"深绿色"
3. UI mockup 要详细描述——不说"一个聊天截图"，要描述每个气泡的内容
4. 中文名加 CRITICAL 指令——AI 生图经常乱码
5. 表格逐行列出——不说"一个7行表格"
6. 避免 prompt 泄漏——第一句不要写样式指令，写"这是一张什么页"

断点续跑

已生成的页自动跳过（检查文件是否存在且大于 10KB）。要重跑某页时手动删掉该 JPG 再跑。

组装

使用 python-pptx 创建 16:9 空白演示文稿，逐页将 JPG 以全屏尺寸添加到空白 slide 上，最后保存为 pptx。

阶段 6：QA 迭代

目标：审查所有页面，只修有问题的页，不动通过的页。

QA 协议

1. 逐页审——打开 pptx 或查看每页 JPG
2. 分级——Critical（内容错误）> Important（版式/渲染）> Minor（微调）
3. 只重跑受影响的页——rm slide_NN.jpg → 修 prompt → 重跑 → 重组装
4. 永远不碰已通过的页

常见问题修复

详见 references/qa-fix-patterns.md，涵盖：

• 标题被加了前缀（"Slide N:"）
• Prompt 指令被渲染为可见文字
• 中文名乱码
• 字号标注泄漏到标题
• 时间轴节点数量错误
• 表格或数据缺失
• 风格不一致（页间跳跃）
• 数字被 AI 篡改

参考链模式（提升风格一致性）

生成每页时把上一页的 JPG 作为 visual reference 传入 API。减少页间风格跳跃。

首次全量生成可不用（独立出图速度更快），QA 修复特定页时建议启用。

阶段 7：交付

产出物

output/ ├── slide_01.jpg ~ slide_NN.jpg ├── deck-v1.pptx └── deck-v1.pdf (可选)

交付前 Checklist

• [ ] 全部页面生成成功（0 失败）
• [ ] QA 修复后的页面已替换并重组装
• [ ] pptx 在 PowerPoint / Keynote 能正常打开
• [ ] 核心论点在每一页都站得住
• [ ] 禁用词零命中
• [ ] 数字全 deck 一致（同一个数字不出现两个版本）
• [ ] 人物/品牌名称全程一致
• [ ] CTA 页的每个行动都能此刻兑现

迭代和定制

改 content.md 里的内容 → 只重跑受影响的页 → 重组装。

不需要全量重跑。改一页成本 ¥0.1-0.3 + 30 秒。

成本参考

大部分时间花在内容和设计上（阶段 1-4）。PPT 生成本身只需 15 分钟 + ¥5。

内容质量 > 视觉效果——PPT 的说服力 80% 来自内容，20% 来自视觉。

Key Pitfalls

• Never paraphrase user content — use exact text from content.md
• Never add "Slide N:" prefixes to titles
• Never add English subtitles unless the spec says so
• Never include meta-notes (like "Final CTA" or "重点页") in visible content
• Never use font size notation like "(36pt)" in visible title text
• Never fabricate data — only use numbers from the spec, or mark as [待补]
• Never skip self-review — at least two rounds before proceeding
• Never regenerate approved slides during QA rounds
• Never let AI "improve" the copy — it always makes it worse
• Never promise deliverables that don't exist yet in CTA pages