| 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 索引（什么时候必读哪份）
工具链（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
cd /tmp && rm -rf preview && mkdir preview && cd preview
soffice --headless --convert-to pdf /path/to/output.pptx
pdftocairo -png -r 100 output.pdf p
每页 3 步检查：✓ 文字是否被截断 / 溢出框 / 遮挡？ ✓ 中文字体是否正确（不是 fallback 到丑字体）？ ✓ 表格 / 列宽是否合理，斑马纹是否生效？
Checklist — 交付前自检
通用（所有路径都查）：
基于模板路径专项（增加 4 项）：
Anti-prompt — 让 Claude 不要做的事
把上文 Checklist 反过来念即是 anti-prompt（每条 [ ] → "不要 X"），不在此重列。Checklist 未覆盖的唯一一条额外禁令：
- 不要 commit 渲染产物（HTML / PDF / .pyc）— 在 .gitignore 里
