ppt-design-skill

PPT 设计技能

设置（首次运行）

此技能调用的 pptx 工具——scripts/office/*、add_slide.py、clean.py、thumbnail.py——未随本仓库提供（其许可证禁止重新分发）。首次使用前，请从上游仓库获取一次：

python3 scripts/setup_upstream.py           # no-op when already installed
python3 scripts/setup_upstream.py --check   # verify installed

该脚本固定了一个上游提交以确保可复现（可用 --ref 覆盖），并会获取 upstream/SKILL.md（设计思路参考）以及管辖所获取文件的上游 LICENSE.txt。所获取工具的 Python 依赖：pip install defusedxml lxml Pillow "markitdown[pptx]"。

快速参考

任务	指南
阅读/分析内容	python -m markitdown presentation.pptx
基于模板编辑或创建	阅读 editing.md
从头创建	规划 → 生成 → QA（见下方“从头创建”）
设计决策（叙事/节奏/自适应）	阅读 references/design-playbook.md
设计主题与版式	阅读 design-system.md
主题 token（列出/验证/提取）	python3 scripts/theme.py list + references/custom-themes.md
确定性 QA 门禁	scripts/qa/（溢出 / 对比度 / 边缘 / token / 字体，独立使用 stdlib）
大纲门禁（规划门禁）	python3 scripts/qa/outline_check.py outline.json + references/outline-schema.md
模块化幻灯片（≥15 页）	python3 scripts/scaffold_deck.py outline.json --out-dir deck --theme <name> + references/modular-decks.md

---

阅读内容

# Text extraction
python -m markitdown presentation.pptx

# Visual overview
python scripts/thumbnail.py presentation.pptx

# Raw XML
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" presentation.pptx

---

编辑工作流

阅读 editing.md 获取完整详情。

1. 使用 thumbnail.py 分析模板
2. 提取 → 结构性更改（add_slide.py / <p:sldIdLst> / clean.py）→ 编辑内容 → 压缩 → validate.py --original

---

从头创建

创建工作流（三段式，顺序固定）：

步骤 1 · 规划（必做，禁止跳过）

阅读 references/design-playbook.md — 叙事弧、页面规划表、明暗节奏、版式决策树、自适应规则、中文排版、密度控制。

选择主题：python3 scripts/theme.py list（内置 9 套 + 项目 ./ppt-themes/ + 用户级）。发现项目/用户级主题 → 询问用户是否优先使用；用户自带品牌色 → 使用 references/custom-themes.md 中的提取流程。

生成页面规划表（页码 → 版式 → 明暗 → 内容形状 → 视觉元素），写入 outline.json 并通过规划门禁后再编写代码：

python3 scripts/qa/outline_check.py outline.json   # exit 0=PASS；主题名/版式 id/多样性/连续重复全查

Schema 与注册版式 id 见 references/outline-schema.md。未通过门禁时先修改 outline.json——规划阶段改一行，胜过代码阶段返工一页。

步骤 2 · 生成

阅读 pptxgenjs.md 了解 API 详情和可能导致文件损坏的问题。

• 主题与配色：design-system.md（9 种主题，只使用安全字体）
• 版式代码：杂志风 templates/layouts/magazine-layouts.md / 瑞士风 templates/layouts/swiss-layouts.md / 分析模型 templates/layouts/analysis-models.md（SWOT/PEST/画布/双钻/竞争定位）
• 组件配方：templates/components.md
• 瑞士风硬性约束：references/swiss-layout-lock.md
• ≥15 页时使用分模块管线：python3 scripts/scaffold_deck.py outline.json --out-dir deck --theme <name> 生成 slide-NN.mjs + compile.mjs；契约与子代理并行填充方式见 references/modular-decks.md

步骤 3 · QA

确定性门禁（先运行，全部 PASS 后再进行视觉检查；exit 0=PASS / 1=存在违规，可接入 CI）：

python3 scripts/qa/cjk_overflow_check.py output.pptx   # 文字溢出/越界（CJK 1em·半角 0.5em 估宽）
python3 scripts/qa/contrast_check.py output.pptx       # WCAG 对比度（4.5:1 正文 / 3:1 大字）
python3 scripts/qa/token_check.py slides/*.mjs --theme ink-classic  # 主题 token 门禁（硬编码色/字体即 fail）
python3 scripts/qa/font_check.py output.pptx                        # Office 安全字体 + 本地可用性（fc-list）
pdftoppm -png -r 150 output.pdf slide \
  && python3 scripts/qa/edge_check.py slide-*.png      # 渲染后边缘裁切/空页（纯 stdlib，PNG）

五个脚本只依赖 stdlib，且独立解析（不依赖上游获取的文件）。然后按照 references/checklist.md 检查 P0-P3（见下方 QA 节）。

---

设计理念

完整的设计理念清单——灵感配色、字体规则、间距和常见错误列表——位于设置时获取的上游参考文档中：运行 scripts/setup_upstream.py 后，阅读 upstream/SKILL.md（§ Design Ideas）。以下部分是本仓库在此基础上制定的设计系统。

核心原则（简版）：

• 用一种主色贯穿整套演示文稿，点缀色要鲜明且少用
• 标题页和结束页使用深色背景，内容页使用浅色背景；也可以全程使用深色，营造高级感
• 选定一种视觉母题，并在每张幻灯片上重复使用
• 每张幻灯片至少包含一个视觉元素（图片、图表、图标、形状），不要制作纯文字幻灯片
• 整套演示文稿的版式要有变化；同一种版式连续使用不得超过 3 张幻灯片

设计系统快速入门

预设主题和版式坐标请参阅 design-system.md。其中包括：

• 9 套内置主题（5 套杂志风格 + 4 套瑞士风格），提供可直接使用的 PptxGenJS 颜色配置
• 32 个版式模板——完整代码见 templates/layouts/（杂志风格 10 个 + 瑞士风格 22 个）
• 杂志风格（衬线）和瑞士风格（无衬线）均提供 Office 安全字体搭配

规划先行：写代码前先读 references/design-playbook.md，产出页面规划表。版式坐标是基线，不是牢房——按 playbook 第 4 节的自适应规则变形。

7 个澄清问题（用户只有模糊想法时的可选最佳实践）：

1. 受众与场景：路演 / 内部分享 / 技术发布 / 作品集 / 学术？
2. 时长与页数：10-12 / 15-20 / 25+ 张幻灯片？
3. 现有材料：文档 / 链接 / 旧 PPT / 数据 / 图片？
4. 主题选择：参见下方的内置主题——杂志风格（优雅 / 人文）还是瑞士风格（极简 / 理性）？
5. 风格偏好：暖色调的衬线标题，还是高对比点缀色的无衬线字体？
6. 语言：中文 / 英文 / 双语？
7. 交付内容：仅 PPTX / 还需要封面图片 / 还需要网页版？

风格画廊技巧（借鉴 humanize-ppt）：用户对主题犹豫时，不要盲选——用 2-4 套候选主题各渲染一张封面供用户挑选，选定后再制作整套演示文稿。

主题使用节奏：

Cover       →  Main theme (consistent across deck)
Section     →  Same theme, variant switch (light/dark)
Data page   →  Same theme, light variant
Highlight   →  Same theme, dark variant
Closing     →  Same theme, dark variant or cover style

规则：整套演示文稿中不得切换主题。

内置设计系统主题

9 套内置主题（5 套杂志风格 + 4 套瑞士风格）的完整色值与适用场景见 design-system.md。主题名即 token：ink-classic / indigo-porcelain / forest-ink / kraft-paper / dune / swiss-blue / swiss-yellow / swiss-green / swiss-orange（项目 / 用户级主题可通过 python3 scripts/theme.py list 查看）。

内置版式模板

版式坐标见 design-system.md；完整代码见 templates/layouts/——杂志风格 10 种版式 + 瑞士风格 S01-S22 + 5 种分析模型（SWOT / PEST / 画布 / 双钻 / 竞争定位）。outline.json 引用这些注册 id（完整列表见 references/outline-schema.md）；outline_check.py 会在规划阶段强制检查版式多样性和连续重复上限。

中文安全字体（内置主题已锁定）

只用 Office 安全字体——用户机器上没有的字体（Inter / Playfair / Noto 系列）会回退到宋体。内置主题的中英文字体搭配（杂志风格衬线 / 瑞士风格无衬线）已固定在 design-system.md 中，直接使用主题 token，不要自行搭配字体（font_check.py 会检查）。

---

QA（必需）

假设存在问题。你的任务是找出问题。

首次渲染几乎从来都不正确。要把 QA 当作查找 bug，而不是确认步骤。如果首次检查时一个问题都没发现，那就是检查得还不够仔细。

内容 QA

python -m markitdown output.pptx

检查是否有内容遗漏、拼写错误或顺序错误。

使用模板时，检查是否残留占位文本：

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

如果 grep 返回结果，请先修复，再宣布成功。

文件 QA

python scripts/office/validate.py output.pptx                      # built from scratch
python scripts/office/validate.py output.pptx --original src.pptx  # built from a template

如果演示文稿基于模板制作，始终传入 --original——这样会以模板为基准检查 schema / 幻灯片，避免把模板自身的缺陷归咎于你。

视觉 QA

⚠️ 使用子代理——即使只有 2–3 张幻灯片也要使用。你已经盯着代码看了很久，看到的会是你预期中的内容，而不是实际呈现的内容。子代理能以全新的视角进行检查。

将幻灯片转换为图像（参见转换为图像），然后把 references/checklist.md §「子代理看图提示词」中的可直接使用的检查提示词发送给子代理——它会逐张检查重叠、溢出、碰撞、间隙、对比度和遗留占位符，并报告所有问题，包括细微问题。

交付前检查清单

在宣布成功之前，请按照 references/checklist.md（P0–P3 级别）逐项检查。交付前必须全部通过 P0 项：没有占位符文本、没有溢出或截断、没有元素重叠、主题保持一致、字体大小达到最低要求。

验证循环

1. 生成幻灯片 → 转换为图像 → 检查
2. 列出发现的问题（如果没有发现问题，就再仔细检查一遍）
3. 修复问题——按失败模式目录的修复顺序：内容 → 结构 → 版式 → 样式，不要从样式开始修
4. 重新验证受影响的幻灯片——一次修复往往会引发另一个问题
5. 重复上述步骤，直到完整检查一遍后不再发现新问题。最多 3 轮；3 轮后仍有 P0 问题，请向用户说明剩余问题，不要无限重试。

至少完成一轮修复并验证之后，才能宣布成功。

---

设计系统参考

文档	内容
design-system.md	9 种内置主题（5 种杂志风格 + 4 种瑞士风格）、版式坐标速查表、安全字体搭配
references/design-playbook.md	设计决策手册：叙事弧、页面规划表、明暗节奏、版式决策树、自适应规则、中文排版、密度控制（写代码前必读）
templates/themes/magazine-themes.md	5 种杂志风格主题的颜色详情
templates/themes/swiss-themes.md	4 种瑞士风格主题的颜色详情
templates/layouts/magazine-layouts.md	10 种杂志风格版式——完整的 PptxGenJS 代码及变体（权威参考）
templates/layouts/swiss-layouts.md	22 种瑞士风格版式 S01–S22——完整的 PptxGenJS 代码（权威参考）
templates/layouts/analysis-models.md	商业分析版式：SWOT / PEST / 商业模式画布 / 双钻模型 / 竞争定位
templates/components.md	组件指南（统计卡片、标注框、图标行、图表、界面元素）
references/checklist.md	P0–P3 质量检查清单（针对 .pptx）
references/outline-schema.md	outline.json 规划门禁：schema、注册版式 id、检查规则
references/image-prompts.md	图像生成提示词指南
references/screenshot-framing.md	截图适配规范
references/swiss-layout-lock.md	22 种已注册的瑞士风格版式及硬性约束

---

转换为图像

将演示文稿转换为单张幻灯片图像，以便进行视觉检查：

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

---

依赖项

• 首次运行：python3 scripts/setup_upstream.py——获取工具运行时（参见 Setup）
• pip install "markitdown[pptx]" - 提取文本
• pip install Pillow defusedxml lxml - 生成缩略图网格 / 验证
• npm install -g pptxgenjs - 从头创建
• LibreOffice（soffice）- 转换为 PDF（通过 scripts/office/soffice.py 自动配置，以适用于沙盒环境）
• Poppler（pdftoppm）- 将 PDF 转换为图像