/jackyshen-gen-pptx [-t THEME] [-IMG] [-QA]

生成指定风格的 pptx 格式幻灯片。

🟢 默认行为：只生成 PPTX 文件，不生图、不做 QA。 这是为了让你快速拿到可编辑的 .pptx 后立刻进入你自己的设计/审阅流程。 如果你需要更完整的交付（自动配图 + 视觉质检），显式传 -IMG 和 -QA。

• 不带参数：只生成 .pptx（不生图、不做 QA）。
• 参数 -t THEME：指定 配色方案。
• 参数 -IMG：显式启用配图——调用文生图 skill 为 PPT 配图。
• 参数 -QA：显式启用 QA——生成后做内容 + 视觉质检。

---

⚠️ 当 -IMG 被传入时：图片先行流程（来自真实事故的反思）

本节规则只在用户传了 -IMG 时才生效。默认不带 -IMG，本节不触发。

【事故复盘 2026-07-01 】

用户在使用本 skill 生成 30 页某敏捷转型方案书时，我漏掉了全部 6 张配图——直接生成了一份纯文字+图表+形状的 PPT。用户当场质问："为什么没有配图？" 我补救后用户再次强调："将你的反思 backfill 到 skill 里，防止下次再放这个不配图的毛病。"

根因（为什么会犯错）：

• 我把"内容很密集、文本就够用"当成了不配图的理由。这是错的——B2B 投标书、项目方案书、年度汇报、产品发布等所有正式商务场景一旦决定配图，就必须配到位。
• 我先写完 519 个元素的 PPT 代码，再想加图，结果布局已经写死，只能事后硬塞，导致第一次集成时图片和文字严重重叠（slide 11 的 ALPHA 图片盖住了第 5 个圆圈、slide 22 同时放了两张金字塔）。

强制规则（仅当传入 -IMG 时，写入 Task 0，不允许跳过）：

1. 一旦启用 -IMG，整份 PPT 至少出 2 张图——这是底线，不是目标。5 页以上的演示应配 4-6 张图（封面 1 + 概念页 1-2 + 收尾 1 + 关键流程/数据页 1-2）。禁止只出 0 张或 1 张图就交付。
2. 图片是规划出来的，不是事后补救的。在写任何 PPT 代码之前，必须先列出每张幻灯片放什么图、图的 x/y/w/h，以及图占多大比例（半出血 / 1/3 栏 / 装饰角落 / 全屏背景）。
3. 必配图页面：封面页、章节页、概念页（方法论/模型/流程）、收尾页——这些是"四金刚"。其余页面按内容需要酌情加图。
4. 图必须在 Task 0 完成生成和下载——文案大纲 → 图片清单 → 批量生图 → 下载到本地 → 再开始写 PPT 代码。绝对禁止写完代码再补图。
5. 图与文字必须分层规划：用 PPT 时不要把图塞到文字中间；要么左图右文（双栏）、要么上半图下半文（半出血）、要么图做背景文字浮在上（透明叠层）。
6. 集成图后必须做一次 slide-by-slide 视觉 QA（同时启用 -QA），检查是否压字、压框、压边距——尤其是图片放右上角时，容易和最右侧的元素冲突。

自检清单（每次启用 -IMG 写完 PPT 代码后过一遍）：

• 总图数 ≥ 2？（5 页以上演示应 ≥ 4 张）
• 封面页有图吗？
• 章节页有图吗？
• 每个核心概念（方法论、流程模型、关键数据可视化）配图了吗？
• 结尾页有图吗？
• 图片的 x/y/w/h 在写代码前就定好了吗？
• 渲染后用 pdftoppm 转图肉眼检查过图片区域和文字区域不冲突？

未启用 -IMG 时 = 走"纯文字 + 形状/图表"路线 = 用户拿到 .pptx 后自行决定是否补图 = 这是默认的、合理的快速交付模式。

快速参考

---

读取内容

# 文本提取
python -m markitdown presentation.pptx

# 可视化概览
python scripts/thumbnail.py presentation.pptx

# 原始 XML
python scripts/office/unpack.py presentation.pptx unpacked/

---

编辑工作的流程

完整详情请阅读 editing.md。

1. 用 thumbnail.py 分析模板
2. 解包 → 操作幻灯片 → 编辑内容 → 清理 → 打包

---

从零开始创建

完整详情请阅读 creating.md。

当没有模板或参考演示文稿时使用。

---

设计思路

不要制作无聊的幻灯片。 白底上的纯要点列表不会给任何人留下深刻印象。考虑从这个列表中为每张幻灯片获取灵感。

开始前

• 选择一个醒目且与内容相关的配色方案：配色应该感觉是为这个主题量身定制的。如果把配色换到完全不同的演示文稿中仍然能"work"，说明你的选择还不够具体。
• 主次分明：一种颜色应该占主导地位（60-70% 的视觉权重），搭配 1-2 种辅助色调和一种锐利的强调色。永远不要给所有颜色同等权重。
• 深浅对比：标题页和结论页用深色背景，内容页用浅色背景（"三明治"结构）。或者全程使用深色以营造高级感。
• 坚持一个视觉主题：选择一个独特的元素并重复使用——圆角图片边框、放在彩色圆形中的图标、粗的单侧边框。在每张幻灯片上保持一致。

配色方案

选择与主题匹配的配色——不要默认使用通用蓝色。用这些配色方案作为灵感：

缺省默认主题色是优普丰(UPerform)蓝粉系

配色原则：

• 主导色占60-70%视觉权重，1-2个辅助色，1个强调色
• 避免所有颜色等权重分配
• 深色背景用于标题和结尾页，浅色用于内容页（”三明治”结构）
• 选一个独特的视觉元素并在每页重复使用

对于每张幻灯片

每张幻灯片都需要一个视觉元素——图片、图表、图标或形状。纯文字幻灯片容易被遗忘。

布局选项：

• 双栏（文字在左，插图在右）
• 图标 + 文字行（图标在彩色圆形中，标题加粗，下方配描述）
• 2x2 或 2x3 网格（图片在一侧，内容块网格在另一侧）
• 半出血图片（占满左或右半边）配内容叠加

数据展示：

• 大数字亮点（大号数字 60-72pt，下方配小标签）
• 对比栏（前后对比、优缺点、选项并列）
• 时间线或流程（编号步骤、箭头）

视觉打磨：

• 章节标题旁的小彩色圆形图标
• 斜体强调文字用于关键数据或标语

视觉决策框架：结构 vs 隐喻

这是选图决策，不是排版清单。问的不是"哪个好看"——是"这页要让读者带走的是结构清晰度，还是情绪方向？"

视觉决策涉及两个维度，它们之间是主从张力关系，不是正交、也不是上下层：

何时走哪条路径？

关键提醒： 同样的 3 层内容（如"AI 转型 战略 → 业务 → 执行"），可以走 3 条不同路径：

• 纯结构 → Plain Pyramid（中性、清晰、强调层级）
• 结构 + 兼容隐喻 → Staircase（保留层级、加"↗ 升级"方向感）
• 隐喻覆盖 → Mountain / Wave Timeline / Growth Curve（情绪优先，结构被重新定义成山峰/折线/曲线）

字体排版

选择有趣的字体搭配——不要默认使用 Arial。选择有个性的标题字体，搭配干净的正文字体。

间距

• 最小边距 0.5"
• 内容块间距 0.3"-0.5"
• 留出呼吸空间——不要填满每一寸

避免（常见错误）

• 不要重复相同的布局——不同的幻灯片要变换栏位、卡片和强调点
• 正文不要居中对齐——段落和列表左对齐；仅标题居中
• 不要吝啬字号对比——标题需要 36pt+ 才能从 14-16pt 的正文中突出
• 不要默认使用蓝色——选择反映特定主题的配色
• 不要随机混用间距——选择 0.3" 或 0.5" 的间距并一致使用
• 不要只设计一张幻灯片而让其余的保持朴素——要么完全投入，要么保持简洁一致
• 不要制作纯文字幻灯片——添加图片、图标、图表或视觉元素；避免单调的标题 + 要点
• 不要忘记文本框内边距——当用文本边缘对齐线条或形状时，在文本框上设置 margin: 0 或偏移形状以留出内边距
• 不要使用低对比度元素——图标和文字都需要与背景形成强对比；避免浅色文字配浅色背景或深色文字配深色背景
• 绝对不要在标题下使用强调线——这是 AI 生成幻灯片的标志；使用留白或背景色代替
• 如果启用 -IMG，不要先生成 PPT 代码再想起来加图片 — 图片是规划出来的，不是事后补救的。如果先写了代码再加水印式图片，布局必然混乱。必须在 Task 0 阶段就完成所有图片的规划、生成、下载。详见顶部「⚠️ 当 -IMG 被传入时：图片先行流程」一节。
• 如果启用 -IMG，不要随意放置图片 — 每张图片必须有固定的 x/y/w/h，必须在写代码之前就确定位置，而不是写代码时随手一摆。
• 不要让元素超出边界 — 所有元素（包括装饰性元素）必须完全位于幻灯片内（x≥0, y≥0, x+w≤10, y+h≤5.625）。延伸到边界外可能引发渲染问题。
• 不要让主标题换行 - 规划布局时要考虑主标题尽量是在同一行，文本框宽度要足够容纳
• 不要把"内容密集"当成不配图的借口 — 默认行为（不传 -IMG）下生成纯文字/形状/图表的 PPT 是合法的；只有当用户显式启用 -IMG 时，才进入"图片先行"硬约束（封面/章节/概念/收尾四金刚 + 整份 ≥ 2 张图）。详见顶部「⚠️ 当 -IMG 被传入时：图片先行流程」。

---

QA（仅当传入 -QA 时执行）

本节默认不执行。只有在用户显式传 -QA 时才进入 QA 流程；否则直接交付 .pptx，由用户自行检查。

假设存在问题。你的工作是找到它们。

你的第一次渲染几乎从来不是完全正确的。把 QA 当作 bug hunt，而不是确认步骤。如果你第一次检查没发现任何问题，说明你看得不够仔细。

内容 QA

python -m markitdown output.pptx

检查缺失内容、拼写错误、顺序错误。

使用模板时，检查遗留的占位符文本：

python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"

如果 grep 返回结果，在宣布成功前修复它们。

视觉 QA

⚠️ spawn sub agents——即使只有 2-3 张幻灯片。你一直盯着代码，会看到你期望看到的，而不是实际存在的。子代理有新鲜的视角。

首先探测环境中是否存在图像理解(image understanding)模型或相应视觉理解大模型或相应SKILL或服务能力（注意不是视觉生成能力）。如果不存在，则跳过此视觉QA环节。如果存在，则将幻灯片转换为图片（见转换为图片），调用视觉理解模型并使用以下提示词：

视觉检查这些幻灯片。假设存在问题——找出它们。

查看：
- 元素重叠（文字穿过形状、线条穿过文字、元素堆叠）
- 文字溢出或在边缘/框边界处被截断
- 装饰线为单行文字设计但标题换行到两行
- 来源引用或页脚与上方内容冲突
- 元素太近（< 0.3" 间距）或卡片/章节几乎相触
- 不均匀的间距（一处大块空白，另一处拥挤）
- 距幻灯片边缘的边距不足（< 0.5"）
- 栏或相似元素不一致对齐
- 低对比度文字（例如，浅灰色文字配奶油色背景）
- 低对比度图标（例如，深色图标配深色背景但没有对比圆形）
- 文本框太窄导致过度换行
- 遗留的占位符内容

对于每张幻灯片，列出问题或关注区域，即使是小问题。

阅读并分析这些图片：
1. /path/to/slide-01.jpg（预期：[简要描述]）
2. /path/to/slide-02.jpg（预期：[简要描述]）

报告发现的所有问题，包括小问题。

验证循环

1. 生成幻灯片 → 转换为图片 → 检查
2. 列出发现的问题（如果没有发现问题，再更批判性地看一次）
3. 修复问题
4. 重新验证受影响的幻灯片——一次修复经常会产生另一个问题
5. 重复直到完整检查没有发现新问题

在完成至少一个修复-验证循环之前，不要宣布成功。

---

转换为图片

将演示文稿转换为单独的幻灯片图片以便视觉检查：

python scripts/office/soffice.py --headless --convert-to pdf output.pptx
pdftoppm -jpeg -r 150 output.pdf slide

这会创建 slide-01.jpg、slide-02.jpg 等。

要在修复后重新渲染特定幻灯片：

pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed

---

依赖

• pip install "markitdown[pptx]" - 文本提取
• pip install Pillow - 缩略图网格
• npm install -g pptxgenjs - 从零创建
• LibreOffice（soffice）- PDF 转换（通过 scripts/office/soffice.py 为沙盒环境自动配置）
• Poppler（pdftoppm）- PDF 转图片