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 里