xjyloly-prog PPT Template Fill
把用户的内容需求"套"进用户指定的 PPTX 模板：模板的每一页都是候选版式，克隆整页后只替换文字/图片/表格内容，版式、字体、配色、装饰元素一律不动。产物是原生可编辑的 PPTX，不经过 HTML 中间态。
SKILL.md 所在目录记为 <skill-root>。
红线(先读。违反任何一条 = 交付失败)
- 只能用本 skill 的脚本操作 PPTX。解析、克隆、填充、截图全部通过
inspect_template.py/build_deck.py/snapshot.py完成。禁止自己编写或执行任何 python-pptx / OOXML / 其他 PPT 读写代码——网上流传的克隆代码会产出畸形文件(如一页挂两个版式关系)，你手写的填充不会保留格式。 - 脚本缺失或报错时：停下，把报错原样告诉用户。手写替代实现不是备选项；缺
python-pptx就先pip install python-pptx。 - 禁止新增/删除/移动任何形状。不许新建文本框，不许改字体、字号、颜色、位置。你的全部自由度只有两个：成品每一页选模板哪一页 + 每个槽位填什么文字。标题、副标题、页眉都在模板槽位里，不存在"模板没给标题所以我加一个"的情况——没有该槽位就说明这页版式不需要它。
- 选中的模板页，非装饰文本槽必须全部填(plan 里不许残留任何「【待填】」)。想保留模板原文，就把原文作为值填回去。漏填的槽会原样残留"内容简述"之类演示文案，属于最难看的交付事故，
--check默认按错误阻断。 - 用户给了素材文档时，标题/数字/术语/结论必须出自素材。禁止填入素材里没有的泛化文案(如素材讲"根因诊断"却写成"趋势预测")。
环境要求
- Python 3.10+，
python-pptx(必需；缺失时pip install python-pptx) - 截图(可选增强)：Windows 本机 PowerPoint，或 LibreOffice(+PyMuPDF)。用
snapshot.py --probe探测；不可用时按"无截图 QA"降级，并在交付时说明未做视觉复核。
命令速查
# 0. 自检: 脚本可达 + 截图后端探测
python <skill-root>/scripts/inspect_template.py --help
python <skill-root>/scripts/snapshot.py --probe
# 1. 模板槽位清单(先 --compact 看全貌, 再 --out 存完整契约)
python <skill-root>/scripts/inspect_template.py <模板.pptx> --compact
python <skill-root>/scripts/inspect_template.py <模板.pptx> --out <workdir>/manifest.json
# 2. 每页截图(选版式和成品 QA 都用它)
python <skill-root>/scripts/snapshot.py <某.pptx> <输出目录> [--width 1440]
# 3. 生成计划骨架(选定页序后, 每个非装饰槽预填「【待填】+ 原文」)
python <skill-root>/scripts/build_deck.py <workdir>/plan.json --scaffold \
--template <模板.pptx> --pages 1,2,4,4,4,6 --deck-out <workdir>/成品.pptx
# 4. 校验计划 / 生成成品
python <skill-root>/scripts/build_deck.py <workdir>/plan.json --check
python <skill-root>/scripts/build_deck.py <workdir>/plan.json
plan.json 的完整格式和槽位 ID 规则见 <skill-root>/references/plan-format.md。
工作流
- 自检：跑上面两条自检命令。
inspect_template.py --help失败说明脚本不可达——停止并告知用户(红线 2)。--probe失败则记下"本次无视觉复核"，后续走无截图 QA。 - 确认输入：模板文件路径 + 内容需求(主题、受众、页数、重点)。用户没给模板路径时先问；用户只给了素材文档时，从文档中提炼内容(红线 5)。输出目录用当前会话工作目录下的
output/<deck-name>/，不要写进<skill-root>。 - 解析模板：先
--compact看每页角色和槽位概况，再--out保存完整 manifest。随后对模板跑snapshot.py，用 Read 逐张查看截图——截图是判断每页真实用途和视觉密度的第一依据，role_guess只是提示。 - 规划结构：先定章节大纲，再为成品每一页选模板源页。同一源页可以多次使用(这是常态：正文页会被反复克隆)。封面用封面页、结尾用结尾页，各用一次。目录页条目数以模板实际槽位为准，反推章节数量，保证目录与章节页一一对应。
- 生成骨架：按选好的页序跑
--scaffold。骨架里每个非装饰文本槽都带「【待填】+ 模板原文」，原文就是字数和分段的参照。 - 填空：把每个「【待填】」值整体替换成新文案(保留模板原文 = 只删掉「【待填】 」前缀)。遵守下方填写规则。表格格子已按原文预填，只改需要变的。图片槽见
_image_slots提示，有素材才填images。 - 校验：
build_deck.py plan.json --check。E(错误)必须修复——「未填将残留」「仍含待填」都是 E；W(警告)逐条评估——超预算的文本先精简文案，确实无法精简再接受并在 QA 时重点看该页。 - 生成 + QA：去掉
--check生成成品。有截图后端：对成品跑snapshot.py，逐页 Read 检查三件事——文字溢出/遮挡、模板演示文案残留、图片变形错位；发现问题改 plan 重新生成，最多 2 轮。无截图后端：把--check的警告清单逐条核对(尤其超预算槽位的文案再精简一轮)，交付时明确说明未做视觉复核。 - 交付：给出成品 pptx 绝对路径，说明用了模板哪几页、做了哪些假设、QA 方式(截图目检 or 契约校验)。
填写规则
- 字数纪律：不超过槽位
max_chars(见 manifest 或骨架_hints)；没有max_chars时以样本原文长度为基准上下浮动 20%。标题槽只写短语不写句子。空占位符看layout_prompt判断用途。宁可精炼，不可溢出——python-pptx 不会自动缩字号。 - 分段：
\n分段，段落数尽量与样本一致；max_lines: 1的槽不要多段。 - 装饰槽不动：
decorative: true(页码、序号、LOGO 字样等)骨架里不会出现，也不要手动加进 plan。 - 内容语言跟随用户：用户用英文沟通就写英文文案，模板残留语言不算数。
- 图片槽：用户给了素材才替换(路径相对 plan.json，一张素材只用一次)；没给素材时保留模板原图——原图与模板风格协调，不要伪造路径或强行配图。替换时引擎会按槽位宽高比自动居中裁切，选图时留意
aspect。 - 表格：按
<shape_id>!r行c列逐格填写，行列数以 manifest 为准，不能增删行列。 - 图表/SmartArt 页(manifest
other列出)：当前版本不能改其数据。避免选这类页；用户坚持要用时保留原样并明确告知。 - 备注加分项：每页
notes可写 1-2 句演讲备注，整体委托时默认写上。
常见陷阱
- 模板页数少、正文版式单一是模板本身的限制，不要为凑页数硬造视觉——多复用现有正文页，靠内容分段。绝不允许通过自己加文本框来"补"版式(红线 3)。
- 目录条目多于实际章节时，多余条目填入真实的收尾性内容(如"总结与展望")，不许留"内容简述"这类样本。
- 校验通过≠视觉合格：CJK 长词、全角标点都会造成意外换行，能截图时成品必须过目。
- 发现自己正在写
from pptx import ...或解压 pptx 改 XML——立即停止，回到脚本(红线 1)。