PPTX技能（pptx-style-cloner）

它解决什么

用户给两样东西：一个模板 PPTX（定义 Logo 位置、字体、字号、配色、版式、装饰）和一份内容（另一个 PPTX、Word、Markdown 或口述文字），要求产出风格与模板一致的 PPTX。

核心原则：不要照着模板"重画"样式，而是把模板的页面当作版式原型整页克隆，再回填新内容。 克隆继承母版、主题、图片、装饰形状、段落级 run 格式，因此位置与样式天然逐像素一致（本技能自检中，原样回填的像素差异为 0.0%）；重画则必然走样。

前置检查

python -c "import pptx, PIL; print(pptx.__version__, PIL.__version__)"
python -c "import win32com.client; print('com ok')"   # 可选：用于渲染目检

缺 python-pptx / Pillow 就装；缺 pywin32 只是无法渲染目检，静态体检仍可用。若 python 不是装了这些库的解释器，改用实际解释器路径（如 C:\Users\<user>\.workbuddy\binaries\python\envs\default\Scripts\python.exe）。下文命令里的 $S 指本技能 scripts/ 目录。

工作流

第 1 步：摸清模板（必做，不可跳）

python $S/inspect_template.py 模板.pptx -o tpl.profile.json -m tpl.profile.md

产出 tpl.profile.md：页面尺寸、主题色板、字体、Logo 覆盖率、页面底色，以及版式原型目录（A01、A02… 每页的类型、结构、文字槽 role#n、字号、容量、图片/表格/图表槽）。

A0x 就是克隆源编号。必须读这份 md 再动手，原型选型靠它，不能靠猜。

第 2 步：摸清内容

python $S/extract_content.py --pptx 内容稿.pptx --md 补充.md --docx 说明.docx -o content.json --img-dir imgs

多个来源可叠加。产出统一结构：title / subtitle / body[{text,level}] / table / image / notes。PPTX 来源会导出内嵌图片、跳过 Logo。

第 3 步：写 build plan（决定成品成败）

先试自动选型，再定点修正：

python $S/build_pptx.py 模板.pptx content.json -o 草稿.pptx --auto-map

自动选型只是草稿。审 草稿_build_report.json 与渲染图后，写显式 plan（assets/build-plan.example.json 可复制）：

{"options": {"min_font_scale": 0.7, "split_overflow": true,
             "defaults": {"meta": "战略发展部 · 2026.10"}},
 "slides": [
   {"archetype": "A01", "title": "……", "subtitle": "……", "meta": "……"},
   {"archetype": "A03", "title": "……", "body": ["要点1", {"text": "子要点", "level": 1}]},
   {"archetype": "A05", "title": "关键指标", "body": [["41%", "设备联网率"], ["28%", "集成率"]]},
   {"archetype": "A06", "title": "……", "table": [["表头"], ["值"]]},
   {"archetype": "A08", "title": "……", "body": ["……"], "image": "imgs/p01.png"},
   {"archetype": "A09", "title": "谢 谢"}
 ]}

三类写法按精度递增：--auto-map（省事）→ 指定 archetype（推荐）→ 再叠加 slots: {"COLH1": "优势"} 精确到形状名（模板有语义化命名或自动归位不理想时用）。

字段与选型规则见 references/build-plan.md。

第 4 步：构建

python $S/build_pptx.py 模板.pptx plan.json -o 成品.pptx --report build_report.json

build_report.json 逐页记录：用了哪个原型、哪些槽降了字号（scaled）、哪些溢出（overflow）、哪些槽被清空（cleared）、告警。这三类字段必须逐条看完：overflow 非空即是缺陷，cleared 里若出现本该有内容的槽，说明 plan 漏填。

第 5 步：验收（必做，不可跳）

python $S/verify_deck.py 成品.pptx --template 模板.pptx --plan plan.json --render

检查页面尺寸、字体越界、色板越界、Logo 覆盖、文本溢出、模板样文残留、页数。--render 同时导出每页 PNG 与 _contact.png 联系表。

必须亲自看联系表：脚本只能算几何与配色，"看起来像不像原模板"只能靠眼睛。判据见 references/qa-checklist.md。有 error 就回到第 3 步修 plan，不要用改字号、删文字来"消除告警"。

决策规则

原型选型（详见 references/build-plan.md）

内容归位：title→title 槽、subtitle→subtitle 槽（无则并入正文首行）、meta→meta 槽、body 按槽数对位（逐槽 / 整块 / 分块三种策略自动择一）。未被填写的槽会被清空，以防模板样文流入成品；需要保留的固定标签写进 keep_text: ["COLH1"]。

溢出处理顺序：① 拆页（同一原型再克隆，标题加"（续N）"，split_overflow 默认开）→ ② 降字号（min_font_scale 默认 0.7）→ ③ 精简文字。不要为了塞进去把字号降到 0.7 以下，不要改动文本框几何。

红线

• 不改母版、不改主题、不新建版式：一旦动这两层，全册风格即失守。
• 不改文本框位置与尺寸：模板的网格是风格的一部分；装不下就拆页。
• 不引入模板外字体与颜色：需要强调色时从模板色板里挑。
• 不残留样文：成品里出现模板示例文字（"2024 年度报告""某某公司"）属严重错误。
• 图片必须替换或删除：模板的示例配图是占位素材，成品里保留即为穿帮。
• 交付前必须真实打开一次成品（verify_deck --render 走 PowerPoint/WPS 即是一次真实打开），确认无"无法显示该图像""需要修复"等提示。

常见故障

交付

一次性交付：成品.pptx + build_report.json + _verify.md + 联系表 PNG。若用户要"先看效果"，先给联系表 PNG 让其确认版式，再定稿。

资源

• scripts/pptx_kit.py — 核心库（风格指纹、整页克隆、样式保真回填、图片/表格/图表、自适应缩字）
• scripts/inspect_template.py — 模板指纹与原型目录
• scripts/extract_content.py — PPTX/MD/DOCX/TXT → content.json
• scripts/build_pptx.py — plan → 成品 + 构建报告
• scripts/verify_deck.py — 风格一致性体检
• scripts/render_pptx.py — 逐页 PNG + 联系表（PowerPoint/WPS COM，回退 LibreOffice）
• references/build-plan.md — plan 全字段、选型与归位规则
• references/style-elements.md — 风格六要素怎么读、哪些必须克隆
• references/qa-checklist.md — 验收清单
• references/troubleshooting.md — 已知坑与定位手法
• assets/build-plan.example.json — 可直接改用的 plan 样例