PPT Builder Skill

版本 见同目录 `VERSION`。

---

🚨 启用本 Skill 后做的第一件事：跑一次自动更新

任何 AI 在本会话第一次用到这个 Skill 时，必须先把下面这条命令作为它的第一个 tool call：

python3 scripts/apply_update.py

这条命令会自动：

1. 从远端 update_source（git+ 仓库）拉取最新 updates.json
2. 比对本地 VERSION 与远端 latest_version
3. 如果有新版本 → 只下载真正变动的文件（增量更新，无 LFS 流量浪费）
4. 如果已是最新 → 几秒内退出，输出 OK Nothing to do

⚠️ 本 Skill 不会自动 push 更新，必须由 AI 主动 pull。如果跳过这一步，可能在用过期版本，行为、规则、模板都可能与文档不符。

✅ 同一会话内只需做一次，后续 tool call 不必重复检查。

---

⚠️ 非商业使用：本 Skill 与其内置 PPT 模板仅供个人学习和研究，严禁用于任何商业用途（含商业演示、销售、培训分发、客户提案、企业内部以营利为目的的使用等）。模板素材来自第三方设计师作品，二次商用需要获取原作者授权。

何时使用本 Skill

当用户的需求满足下列任何一项就调用本 Skill：

• 需要"做一份 PPT / 演示文稿 / 幻灯片"，无论是工作汇报、年终总结、季度复盘、项目提案、述职竞聘、教学课件、开题答辩、读书报告……
• 用户给了文字大纲或一段描述，希望"做成 PPT"
• 用户拿来一份 .pptx 文件，希望"按这个模板做一份新的"
• 用户希望"调整 / 编辑 PPT 的某些文字"，且要求"不破坏排版"
• 用户希望对比多个 PPT 模板，选一个合适的

更新机制说明

完整的更新工具有两个脚本：

脚本	干嘛	何时用
scripts/apply_update.py	检查 + 应用（一步到位）	每次启用 Skill 第一件事（见顶部红框）
scripts/check_update.py	仅检查、不应用，列出会变的文件	当你只想预览改了什么、不想立即更新时

如果只想先看变化再决定要不要升级：

python3 scripts/check_update.py     # 列出 added / modified / removed

updates.json 的 update_source 已配置为 git+https://github.com/GordenSun/GordenPPTSkill.git#main，开箱即用，无需修改。

三种模式

收到用户需求后，先判断走哪种模式：

模式 A：从内置模板里挑

默认走这条路。 19 套内置模板覆盖了绝大多数中文场景。

1. 读 `templates/INDEX.md` ——一份精简清单，列出每套模板的风格、主色、适用场景、页数。
2. 匹配用户输入 —— 把用户描述（场景、风格关键词、所需页面类型、颜色偏好）和每个模板的 intro.md 对比。
3. 选模板的决策规则：
   • 用户已明确指定模板 → 直接用。
   • 你高度确信只有 1 个模板最合适（场景 + 风格 + 主色都强匹配，且明显优于其它）→ 可直接用，但开工前一句话告诉用户你选了哪个、为什么，给用户一个否决的机会。
   • 其余所有情况（用户没指定，或你不能完全把握哪个最合适）→ 必须让用户来选：
     • 用 AskQuestion 提供 正好 3 个候选模板，每个附上一句话理由（风格 / 适用场景 / 页数），并把对应的 templates/<slug>/preview.png 一并展示给用户看图决策。
     • 选项里始终额外带一个「都不满意，换一批」。用户选它时，再按匹配度给出另外 3 个没出现过的候选（同样附预览图）。可反复换，直到用户选定或候选用尽。
     • 候选都用尽仍不满意 → 询问用户更具体的偏好（风格 / 颜色 / 场景），或转模式 C 原创。
   • ⚠️ 不要在没让用户看预览图的情况下，仅凭模糊匹配就自作主张定一个模板。
4. 拿到目标模板后：
   • 读 templates/<slug>/intro.md（高度浓缩，告诉你这个模板的特性）
   • 读 templates/<slug>/detail.json（结构化数据，告诉你每页 / 每个文本位的细节）
   • 按 模式 A 工作流 选页、写 edits.json、跑 build_pptx.py

模式 B：用户自己带 PPT 模板

当用户提供了 .pptx 文件且明确希望以它作模板时：

1. 把用户的 pptx 当作"未知模板"
2. 用 scripts/render_slides.py 把每页渲染成 PNG，再用 python-pptx 现场探查每页的 shape / paragraph / run 结构（无需额外脚本）
3. 自己看每页（PNG + shape 输出）：
   • 推断每页是什么角色（封面 / 目录 / 章节扉页 / 内容页 / 结束 / 模板宣传）
   • 推断每页适合放什么内容
   • 跳过模板宣传 / "稻壳儿" / 感谢下载 之类
4. 按 模式 B 工作流 用 explicit address 写 edits.json 选页 + 文字替换
5. 不要修改用户模板原文件；所有改动写到新的 output.pptx

模式 C：完全原创（不基于任何模板）

当用户明确要求"原创设计 / 不用模板 / 简单干净的样式"时：

1. 创建尽量简洁的版式 —— 大量留白、对齐严格、装饰极少
2. 单页元素 ≤ 4 个，避免复杂图形 / 图标群组
3. 字体：英文 Arial / Helvetica；中文 微软雅黑 / 思源黑体；标题加粗即可
4. 主色 1 个 + 灰阶 + 白底；不要拼凑多种风格
5. 用 python-pptx 直接代码生成，参考 `references/original-design-guide.md`

编辑铁律（所有模式通用）

1. 不改排版 —— 只改文字。形状的位置、大小、颜色、字体、字号、行距，都不动。
2. 所有占位文字必须替换 —— 模板里的 "Question 1" / "Vivamus..." / "Key Words Here" / "项目名称" 等占位文本都必须用真实内容替换。一份完成的 PPT 里不应出现任何示例占位词。
3. 字数受 max_chars 约束（按文本框真实尺寸精算，含 20% 余量） —— detail.json 每个 slot 的 max_chars 是用"文本框宽高 + 字号"算出的容量（单位：视觉宽度，中文 1 字=1、英文/数字≈0.5）。还提供 chars_per_line（每行可容字数）和 max_lines（可容行数）。写文字前先看这三个值，确保不超过 max_chars。capacity_unknown:true 的槽（自适应/组合内异形框）测不准，谨慎短写。
   • 构建时 build_pptx.py 会自动检测出框：超容量会告警；加 --strict 时直接拒绝保存，必须缩短后重试。出框时只缩短文字、不要改字号（改字号会破坏同级一致，见第 8 条）。
4. 数字 / 序号默认不动 —— editable: false 的 slot 是装饰性 "01/02/1/2/%" 之类，除非用户明确要求改顺序，否则保持。
5. 图形 / 图表通常无法同步 —— 装饰性的进度条 / 圆环 / 旗帜路径 / 流程箭头是固定形状；改了百分比文字不会改弧长。每个模板 detail.json 里如有这类页面会在 cautions 字段列出。
6. 真实数据图表才能改数据 —— 如果某页有 PPT 原生 chart（shape.has_chart=True），可以用 build_pptx.py --chart-data 同步更新；详见 `references/chart-editing.md`。
7. 章节名前后呼应 —— 改了目录章节名，对应的分章扉页 + 内容页面包屑文字都要同步改。
8. 封面 / 致谢页按模板能力来，不要硬造 ——
   • 读 detail.json 的 page_roles，如果 cover 数组为空，直接从第一张内容页开始，不要拿一张内容页当封面用，更不要从其他模板临时凑一张封面页。
   • 如果 ending 数组为空，直接以最后一张内容页收尾，不要硬造"感谢聆听"。
   • 同理，agenda 空 → 不强加目录；section_divider 空 → 不强加分章扉页。
   • 也就是说：模板有什么角色就用什么角色，少一个角色就少一页，不要破坏视觉一致性去拼凑。这条规则在 v1.0.3 起对所有模板生效。
9. 同级标题字号必须一致，靠"控制长度"而非"缩字号"达成 ——
   • detail.json 顶部有 type_scale（字号层级表，level 1 = 最大），每个 slot 标了 level。同一 level 的文字必须保持模板原字号，不要改字号。
   • 当某处文字太长放不下时，永远是缩短文字（换更精炼的表达），绝不是把这一处的字号改小 —— 那会让本该同级的标题大小不一，非常难看。
   • 选多页拼一份 PPT 时，确认各页同 level 的标题用词长度相近，整体才齐整。

标准工作流（模式 A）

# 1. 从 templates/INDEX.md 选定一个模板，例如 minimal-business-summary
TEMPLATE=templates/minimal-business-summary

# 2. 读两个文件
#    - $TEMPLATE/intro.md     -> 模板风格 / 适用场景 / 结构概述
#    - $TEMPLATE/detail.json  -> 每页 / 每个文本位的详细描述

# 3. 自己决定要用哪些页（用 detail.json 的 page.role 和 use_for）
#    生成 edits.json：
#    {
#      "template_slug": "minimal-business-summary",
#      "selected_slides": [1, 2, 3, 5, 7, 9, 10, 12, 13, 14, 16],
#      "edits": [
#        {"slide": 1, "slot_id": "cover_title_cn", "new_text": "2026 年度复盘"},
#        ...
#      ]
#    }

# 4. 跑构建
python3 scripts/build_pptx.py \
    $TEMPLATE/template.pptx \
    edits.json \
    out/final.pptx \
    --detail $TEMPLATE/detail.json \
    --strict

# 5. （可选）渲染最终 pptx 给用户预览 / 自检（每页一张 PNG）
python3 scripts/render_slides.py out/final.pptx out/renders --dpi 144

目录结构

GordenPPTSkill/
├── SKILL.md               ← 本文件
├── VERSION                ← 当前版本号
├── CHANGELOG.md           ← 人类可读变更日志
├── updates.json           ← 机器可读版本增量索引
├── manifest.json          ← 所有文件的 sha256 与版本归属
├── README.md              ← 仓库概览（用户阅读）
├── scripts/
│   ├── build_pptx.py          # 按 edits.json 选页 + 换字 → 输出 pptx（含出框检测）
│   ├── render_slides.py       # pptx → PDF → 每页 PNG（预览/自检）
│   ├── compute_capacity.py    # 由 template.pptx 计算每个 slot 的容量字段（数据准备）
│   ├── check_update.py        # 检查远端是否有更新
│   ├── apply_update.py        # 增量更新本地文件
│   └── build_manifest.py      # 重建 manifest.json
├── references/
│   ├── workflow.md
│   ├── pptx-edit-schema.md
│   ├── custom-template-workflow.md
│   ├── chart-editing.md
│   └── original-design-guide.md
└── templates/
    ├── INDEX.md
    └── <slug>/
        ├── template.pptx
        ├── intro.md       # 高度浓缩简介
        ├── detail.json    # 详细页面 / slot 数据（含容量字段 + type_scale）
        └── preview.png    # 4 页 2×2 拼接预览图

关键脚本一句话说明

脚本	干嘛用
build_pptx.py	按 edits.json（选页 + 文字替换）从模板生成最终 pptx；带出框检测，--strict 时出框拒绝保存
render_slides.py	把任意 pptx 渲染成每页一张 PNG（用 LibreOffice + pdftoppm），用于预览 / 自检
compute_capacity.py	由 template.pptx 算出每个 slot 的 chars_per_line/max_lines/max_chars 等容量字段（自带模板已算好，仅在加新模板时需要）
check_update.py	对比本地 VERSION 和远端 updates.json，告诉你要不要更新
apply_update.py	按 updates.json 的 delta 列表只下载变动文件
build_manifest.py	重新计算 manifest.json

字体说明

模板 XML 里大量使用 微软雅黑。如果运行环境没有该字体，配合 ~/.config/fontconfig/fonts.conf 把它别名到本地已安装的字体（推荐顺序：WenQuanYi Micro Hei → DengXian → Noto Sans SC → PingFang SC）。预览图正是用这条 fallback 链渲染的。

最终交给用户的 .pptx 在 PowerPoint / WPS / Keynote 里打开时会自动用宿主机的字体渲染，因此不需要担心字体丢失问题。

一些常见误区

• 不要只改文字不改章节名一致性 —— 改 agenda 必须同步改分章扉页
• 不要在装饰图上加文字以为是真图表
• 不要把 lorem ipsum 留在最终 PPT 里
• 不要为了塞下文字而忽略 max_chars
• 不要修改用户原始模板文件 —— 所有产出都到新文件
• 不要用本 Skill 做商业项目 —— 见顶部声明