agf-writing-pptx-reports

name	agf-writing-pptx-reports
description	用 python-pptx 写"现代化中文制度 / 党政 / 企业宣贯 PPT"（含决议书提报、评审报告、管理办法、培训宣贯等 23 页量级 deck）。当用户要求程序化生成 PPT 且抱怨"老土 / 字体丑 / 表格乱 / 文字溢出 / 中文字体 fallback / 缺架构图"时启用——`python-pptx` 默认 API 一堆坑必须主动避开。提供：路径决策 / 设计 token / 12 个 helper 全套 / 7 个致丑反模式 / 12 个关键技巧 / LibreOffice 渲染验证闭环 / 跨平台中文字体生效 lxml 写法 / 配套 draw.io 画架构图选型（中文字体、配色、8 大坑、嵌入 PPT 链路）。

写 pptx 报告 — 高密度实战手册

沉淀自《AI 4A 架构评审管理办法》v1.0 PPT 实战（23 页，GAC 红主调，含双视图嵌入流程图），全部踩过 + 验证过的坑与方法。重型参考材料在 references/，按下方索引按需 Read 全文，不要凭记忆写代码。

何时用本 skill

信号	用本 skill
需要程序化生成 PPT（数据驱动 / 模板批量 / 内容版本化）	✅
中文制度 / 党政 / 企业内部宣贯 deck	✅
用户反馈"老土 / 字体丑 / 表格乱 / 文字溢出 / 中文字体 fallback"	✅
内容会反复迭代，PPT 必须从源码可重生成	✅
需要 mermaid 流程图嵌入 + 双视图卡片化	✅
高度自由排版 / 视觉冲击型营销 deck	❌ 直接 Keynote / Figma
复杂动画 / 视频嵌入	❌ python-pptx 弱项
一次性单页海报	❌ 直接画
要 docx / xlsx	❌ 转 writing-docx-reports / xlsx skill

路径决策（4 选 1）

路径	何时选	代价
手动复制 .pptx 模板编辑	一次性 deck / 设计师介入 / 不需重生成	几分钟；后续维护成本高
pptx skill 局部改	已有 .pptx 做小幅修改（≤ 5 张 slide / 仅换文字）	中等；不适合从零生成
基于模板 + python-pptx 混合 ⭐	仓库已有 .pptx 模板 / 视觉风格已定 / 需版本化 + 重生成	一次 ~500 行；保留模板视觉投入 + 代码可重跑
python-pptx 全定制	没现成模板 / 视觉自己定义 / 跨平台中文 / 23+ 页量级	一次 ~800 行 Python，复用率 90%

判定经验：

• 本仓库 template/ 已有 1 个 .pptx 模板（Template.pptx，coral 团队风）→ 默认走"基于模板 + python-pptx 混合"，不要重造视觉
• 用户说"老土 / 中文字体不对 / 表格乱" 基本意味着要"模板混合"或"全定制"——只有"手动复制"路径根治不了
• 用户给了具体模板路径（如 "用 Template.pptx"）→ 必走"模板混合"路径，并先读对应的 template-*-guide.md

References 索引（什么时候必读哪份）

场景	必读（Read 全文）
走"基于模板 + python-pptx 混合"路径（动手前）	references/template-based-generation.md（7 步流程 / 模板分析三件套 / Placeholder vs Shape / 关键文件指针）+ 对应 template-*-guide.md（如 template-team-guide.md）
写 helper / 设计 token / 字号 layout / 品牌色板（任何写代码前）	references/design-tokens-and-techniques.md（设计 token + 12 个关键技巧完整代码 + 品牌色获取 3 步）+ template.py（可直接 python3 template.py 跑样例）
deck 缺架构 / 流程 / 矩阵图（走 draw.io 前）	diagram-generation-guide.md（500 行：安装 CLI / mxGraph 模板 / AGF token / 字号体系 / 8 大致丑坑 / 批量工作流 / 嵌入链路）
mermaid 出图嵌 PPT / 多 PNG 合 PDF 提报 / 查外部资源链接与沉淀来源	references/rendering-and-embedding.md
操作 .pptx 底层（unpack / thumbnail / pack）	.claude/skills/pptx/SKILL.md（Anthropic 低层 skill）

工具链（macOS 实测）

用途	工具	装法
PPT 生成	python-pptx ≥ 1.0	pip3 install --user --break-system-packages python-pptx
XML 微调（EA 字体 / 表格属性 / 阴影）	lxml	通常已装
PPT → PDF（实际渲染验证）	soffice（LibreOffice）	brew install --cask libreoffice
PDF → PNG（视觉验证）	pdftocairo（poppler）	brew install poppler
多 PNG → PDF 合并	sips（系统自带）+ pdfunite	brew install poppler
mermaid 流程图	mmdc	brew install mermaid-cli

⚠ 不要装 PrinceXML（商业 + 免费版水印）；不要走 pandoc --pdf-engine=prince 这条路。

★ 图层 — 架构图 / 流程图先于 PPT

• deck 里 5+ 张架构 / 流程 / 矩阵 / 决策图 → 图先行 + 单独生成 PNG → PPT 嵌入
• 选型速判（≤ 5min）：deck 总图数 ≤ 10 → 全 Mermaid；> 10 张或需"视觉一致" → 全 draw.io 沉本到底，不混搭（完整选型表见 guide §1）
• 触发信号：用户说"deck 缺图 / 架构看不懂 / 文字墙"；某 slide 描述完没图可塞；派单含"需要 N 张架构图"或"图先行"
• 走 draw.io 前先读 diagram-generation-guide.md 全文（见上方索引）
• ⚠️ 字体一致性：图与 PPT 一律 PingFang SC（PPT 用 _fix_ph_font(ph, name="PingFang SC")）；别图用 Heiti SC、PPT 用 PingFang SC 造成跨页面字体跳变

★ 7 个致丑反模式（必须主动避开）

#	反模式	为什么丑	正确做法
1	顶部厚色带（≥0.5"）每页都重复	压死页面空间 + 视觉疲劳	6pt 极细线 + 右上 140pt 装饰大数字
2	每页同一 header(title, page) 通用模板	章节同质化、无层次感	章节扉页与内容页分两种 layout
3	表格全网格（Excel 风）+ 默认 banding	老土 + 信息密度低	表头深色 + 0 内边框 + 自定义斑马纹
4	一页 5+ 种饱和色（绿/蓝/红/橙/紫）	眼花、权重失序	1 主色 + 1 强调色 + 灰阶 + 白
5	全屏文字墙（一页 >100 字）	没人会读完	卡片化（每个信息单元独立矩形）
6	标题用艺术字 / 阴影 / 3D / 渐变铺底	党政"信封风"	简洁字体 + 1pt 横线分隔
7	emoji 滥用（🚀 ✅ 🎉 等活泼感）	制度文件不严肃	仅 ⚠ ⛔ 🔒 类警示性图标

★ 关键坑速记（完整代码与解法见 references，坑本身必须先记住）

#	坑	正解
1	font.name 只写 <a:latin>，中文跨平台 fallback 丑字体	set_font 用 lxml 显式写 <a:ea> + <a:cs>（技巧 #1）
2	set_font(run) 改不动 placeholder 中文字体（<a:ea> 继承自 master）	placeholder 一律 _fix_ph_font(ph, ...)，自加 textbox 才用 set_font(run, ...)
3	textbox 默认 margin 非 0 → 文字神秘偏右/偏下	margin_left/right/top/bottom = Emu(0)
4	大字号装饰数字被自动换行（"01" → 两行）	word_wrap=False；宽度 ≥ 字符数 × 0.6 × 字号pt / 72
5	表格默认 banding 出怪横纹 / 行高失控	tblPr 关 firstRow/bandRow + 显式 row.height，斑马纹手动填色
6	shape.fill = None 不是"无填充"，是"默认"（会有边）	fill.background() / line.fill.background()
7	模板自带样例 slide 污染输出	加载后立即 clear_template_slides(prs)（template.py 提供）
8	LibreOffice 渲染页数 < len(prs.slides) 误判为代码 bug	模板含"工具说明页"不被渲染，先看 template-*-guide.md

★ 迭代验证流程（生死循环）

最致命的错误：只用 python-pptx 读回验证文件合法性，不看实际渲染。字符溢出 / 表格被截 / 文字遮挡 / 行高失控 / 中文字体 fallback——只能靠 LibreOffice 渲染 PDF + 看 PNG 才能发现。

python3 build-ppt.py                                        # 1. 生成
cd /tmp && rm -rf preview && mkdir preview && cd preview
soffice --headless --convert-to pdf /path/to/output.pptx    # 2. 转 PDF（实际渲染）
pdftocairo -png -r 100 output.pdf p                         # 3. 转 PNG（视觉）
# 4. 用 Read tool 看关键页（封面、表格页、嵌入图页、警示页）
# 5. 发现问题 → 改 build-ppt.py → 回到 1

每页 3 步检查：✓ 文字是否被截断 / 溢出框 / 遮挡？ ✓ 中文字体是否正确（不是 fallback 到丑字体）？ ✓ 表格 / 列宽是否合理，斑马纹是否生效？

Checklist — 交付前自检

通用（所有路径都查）：

• 跨平台中文字体（用了 lxml 写 <a:ea> + <a:cs>）
• 没有文字被截断 / 溢出 / 遮挡（LibreOffice 实测）
• 没有 emoji 滥用（仅 ⚠ ⛔ 🔒 类警示性）
• 单一主色 + 1 强调色（不超过 7 个色变量，上限 12）
• 表格关了 firstRow / bandRow（防 banding）
• 大字号 textbox 设了 word_wrap=False
• 所有 textbox 设了 margin_left/right = 0
• line_spacing 显式设置（标题 1.0 / 正文 1.45）
• 每页有页脚 + 页码 N / TOTAL
• 章节扉页与内容页 layout 不同
• 图片用 height=Inches(N) 等比缩放（不变形）
• 不依赖 PrinceXML / 商业 PDF 引擎
• 可用 python3 build-ppt.py 一键重生成

基于模板路径专项（增加 4 项）：

• 加载模板后已用 clear_template_slides(prs) 清空所有样例 slide
• 所有 placeholder 都已用 _fix_ph_font(ph, ...) 修字体（不是 set_font(run, ...)）
• 已对照 LibreOffice 输出页数 vs len(prs.slides) —— 不一致时确认是"模板含工具说明页"而非代码 bug
• 已读过对应的 template-*-guide.md（如 template-team-guide.md），知道该模板的可用 layout / 配色 / 字体坑

Anti-prompt — 让 Claude 不要做的事

把上文 Checklist 反过来念即是 anti-prompt（每条 [ ] → "不要 X"），不在此重列。Checklist 未覆盖的唯一一条额外禁令：

- 不要 commit 渲染产物（HTML / PDF / .pyc）— 在 .gitignore 里