PPT 格式提取与风格套用

> 给使用者：本文件是给 AI 读的说明书。人类使用请看同目录下的 使用说明.txt
> （双击即开，含安装步骤、使用方法、换模板步骤、常见问题）。

八个脚本

依赖

唯一依赖：python-pptx

pip install python-pptx

装完即可用，脚本无其他外部依赖、无网络请求、无凭据需求。

⭐ 主力用法：给内容计划，出标准格式 PPT

# ① 看 plan.json 该怎么写
python scripts/build_pptx.py --print-plan-schema

# ② 生成
python scripts/build_pptx.py plan.json -o "输出.pptx"

# ③ 验收（改完必跑，不靠肉眼）
python scripts/check_pptx_layout.py "输出.pptx"

7 种页型

卡片字段

{ "no":"01", "title":"卡标题", "desc":"说明文字",
  "quote":"引文块(带语义底色的那格)", "tags":"标签(分隔线下方)",
  "color":"蓝" }

quote 省略时自动上移 desc；全部省略则卡片更矮。

颜色可写中文

蓝 / 深蓝 / 亮蓝 / 红 / 深红 / 绿 / 橙 / 深橙 / 白 / 深底，或直接 #RRGGBB。

完整示例

见 test/plan_regression.json（中性内容，7 页覆盖全部页型）。

基准格式规范

完整规范见 assets/TEMPLATE-格式规范.md（9 节：色板 / 字体 / 字号层级表 / 7 类页型几何参数 / 页脚规范 / 10 条铁律）。核心速查：

• 画布 960×540pt（16:9）
• 字体 Noto Sans SC（页脚用微软雅黑 9pt）
• 主色 #2B5CE6　深蓝 #004FDD　错误红 #E65050/#B44646　正确绿 #008C50　提示橙 #E6A032
• 字号 页标题 32 / 卡片序号 40 / 卡片标题 24 / 要点 20 / 正文 16 / 页脚 9
• 页脚 每页右下 L812.4 T523.4，格式 {章节} | {页码两位}

10 条套用铁律

1. 字体一律显式指定 Noto Sans SC
2. 字号只取规范表中的值；正文 16pt
3. 颜色只取规范表中的值；语义色不互换（红=错/绿=对/橙=提示）
4. 内容页标题 32pt bold #2B5CE6；暗底页 32pt bold 白
5. 卡片 = 白底 + 1pt 语义色描边 + 6pt 顶脊
6. 每页右下 9pt #969696 页脚
7. 页面四周留边 ≥ 24pt
8. 内容超长先降级字号（16→14→12），不缩字距不换字体
9. 背景优先母版白底；暗底用 #001548 或 #2B5CE6 满幅
10. 禁用渐变、阴影、3D、非常规字体

换一份参考 PPT（脚本不动）

# ① 抽出新参考的格式
python scripts/extract_pptx_format.py "新参考.pptx" -o ./spec

# ② 看层级映射表与配色频次，据此改 ppt_style.py 的常量
python scripts/summarize_pptx_style.py ./spec/spec.json

# ③ 推断页型模式，据此调整构件函数
python scripts/analyze_pptx_layouts.py ./spec/spec.json

# ④ 选几页 dump 出几何蓝本
python scripts/dump_pptx_page.py ./spec/spec.json 1,6,33

# ⑤ 生成空骨架并剥字体（保留母版/主题/版式，去掉全部幻灯片与内嵌字体）
python -c "
import shutil;from pptx import Presentation
shutil.copy('新参考.pptx','assets/_raw.pptx')
p=Presentation('assets/_raw.pptx')
L=p.slides._sldIdLst
R='{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id'
for s in list(L): p.part.drop_rel(s.get(R)); L.remove(s)
p.save('assets/_raw.pptx'); print('ok')"
python scripts/strip_fonts.py assets/_raw.pptx -o "assets/TEMPLATE-基准骨架.pptx"
rm assets/_raw.pptx

改完必须跑回归，确保 7 页仍全过校验：

python scripts/build_pptx.py test/plan_regression.json -o test/out.pptx
python scripts/check_pptx_layout.py test/out.pptx

关键教训（都是踩过的坑）

边界

• 本技能只做风格级继承（配色/字体/字号层级/版式语汇），不做坐标级 1:1 复刻。
  坐标级复刻需用 ppt_style.py 的构件函数显式指定每个形状坐标。
• 需要非常规版式（流程图/时间轴/复杂表格）时，在 plan 里用 "type":"custom"，
  然后直接 import ppt_style 调 Deck.box() / Deck.text() 手搭。
• 输入 pptx 需为非加密、未设编辑密码的 .pptx（.ppt 不支持）。
• 骨架已剥离内嵌字体；目标机器若未装 Noto Sans SC 会回退到系统无衬线字体。
  该字体免费可商用，缺失时安装即可保真。
• 全包无写死绝对路径，assets 由 __file__ 相对定位，整目录可复制到任意机器/任意路径。

v2 版式（2026-10-05 修正）

🔴 v1 的两个硬编码缺陷（已修）

plan.json 可用的版式参数（content / page 页型）

推荐组合（商业培训课件）

{ "type": "content", "title": "…", "color": "蓝",
  "cards": [ { "no":"01", "title":"…", "desc":"…" },
              { "no":"02", "title":"…", "desc":"…" },
              { "no":"03", "title":"…", "desc":"…" },
              { "no":"04", "title":"…", "desc":"…" } ],
  "body_size": 20, "center_y": true, "max_h": 300 }

自适应高度估算公式（card_h）

h = 6(顶脊) + 40(序号) + 8(间隙) + 48(标题)
  + 72(若有 quote) + 36(若有 tags)
  + 22 × desc行数 + 24(底部留白)
下限 170pt

卡宽公式（w=None 时）：

w = min(340.0, (W - 2*MARGIN - (n - 1) * gap) / n)

⇒ 4 卡时 w≈219，总宽 4×219+3×12=912 ≤ 960 ✔

v1 / v2 效果对照

备份

scripts/ppt_style.py.bak —— v1 版本，可回退（覆盖后重跑 build 即可）

🔴 踩坑

• card_row 内引用 MARGIN / W 必须写模块级常量，
  不能写 self.MARGIN（无该类属性 → AttributeError）
• card_row 的 **kw 会把未知 key 透传给 card()；
  新增参数务必显式声明在签名里，否则被 **kw 吞掉不生效
• 颜色别名只有 蓝/深蓝/亮蓝/红/深红/绿/橙/深橙/白/深底 或 #RRGGBB，
  写 青/琥珀 会抛 ValueError

验收闭环（改完必跑）

python scripts/build_pptx.py plan.json -o out.pptx
python scripts/check_pptx_layout.py out.pptx   # 必须「版式校验通过」

只看脚本无报错不作数 —— 必须渲染出图肉眼核对。
本机用 WPS CLI（比 LibreOffice 快、不占 1GB）：

WPS="/d/Users/Neo/WPS Office/12.1.0.28488/office6"
"$WPS/kwpsconvert.exe" ppt2pdf "D:/…/out.pptx" --output "D:/…/_render"
"$WPS/kwpsconvert.exe" pdf2photo "D:/…/_render/out.pdf" --output "D:/…/_render/png"

⚠️ 必须绝对路径（正斜杠 D:/…），相对路径会被解析到
C:\\Users\\…\\AppData\\Local\\wpscli → Error(203) File not found。
产物是 .jpg；多页会拼成一张大图，需 PIL 切片后单页查看。