涉及 .pptx/.potx…

只要需要创建、读取、提取、编辑、拆分合并 .pptx/.potx 幻灯片（含模板 .potx、版式、备注、批注），就用本经验：新建走 pptxgenjs、改已有走解包改 XML、只读走 markitdown，最后必须过内容、文件、视觉三道 QA。

适用场景

解决思路

1. 先按任务选路径：新建 deck 写 pptxgenjs 脚本；编辑已有 deck 或基于模板构建走 unzip → 改 ppt/slides/slideN.xml → zip；只读内容用 markitdown deck.pptx（每页一个块，位于 <!-- Slide number: N --> 标记下），要看视觉网格用 python scripts/thumbnail.py deck.pptx。
2. 用 scripts/thumbnail.py deck.pptx [prefix] 生成每页带标签的网格图，用于挑选模板版式；仅支持 .pptx，.potx 先复制成 .pptx 名字。始终传第二个参数 prefix，因为默认值 thumbnails 会让同目录下另一个 deck 的网格被静默覆盖。
3. 用 scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml] 复制一张幻灯片（或 slideLayoutN.xml）并完成所有包登记，它会打印新幻灯片的路径。
4. add_slide.py 也可直接作用于文件：add_slide.py deck.pptx slide2.xml -o out.pptx，必须传 -o，否则会原地改写输入 deck。
5. 用 scripts/clean.py unpacked/ 删除不再被引用的幻灯片、媒体和 rels；必须在 <p:sldIdLst> 定稿之后运行。
6. 用 scripts/office/validate.py deck.pptx [--original src.pptx] 做 schema、关系、内容类型、图表和幻灯片校验，每个失败都会给出修法；任何从模板派生的 deck 都要传 --original。
7. 需要 PDF 时用 scripts/office/soffice.py --headless --convert-to pdf deck.pptx（裸 soffice 在此沙箱会挂起）。
8. pptxgenjs 已预装，直接写脚本 require('pptxgenjs')，不要先 npm install；只有该 require 失败时才 npm install pptxgenjs。
9. 在添加幻灯片之前先设置 pres.layout：默认画布是 LAYOUT_16x9 = 10" × 5.625"，不是 13.3" 宽；LAYOUT_WIDE 才是 13.3" × 7.5"。超出边界的坐标会被写入而不被裁剪，形状只是不在页面上。
10. 十六进制颜色不要 #、不要 8 位：写 color: "FF0000"。"#FF0000" 和把 alpha 塞进 hex（"00000020"）都会损坏文件。半透明用填充/图片的 transparency: 0-100、阴影的 opacity: 0.0-1.0，两者互换会被静默忽略。
11. 不要复用选项对象：pptxgenjs 会就地改写 option 对象（首次使用即转成 EMU），因此 shadow/options 对象每次 add* 调用都要新建。
12. 阴影 offset 必须 ≥ 0，负值会损坏文件；要向上投影请用 angle: 270 配正值 offset。
13. letterSpacing 会被静默忽略，正确选项是 charSpacing。
14. 列表：每项设 bullet: true，不要写真实的「•」（会渲染成双项目符号）；数组每一项除最后一项外都要设 breakLine: true；项目符号段落之间用 paraSpaceAfter 而不是 lineSpacing（后者会产生巨大间距）。
15. 每个输出文件只 new 一个 pptxgen()，绝不复用实例。
16. rectRadius 只对 ROUNDED_RECTANGLE 生效，对 RECTANGLE 无效。
17. 不支持渐变填充，改用渐变图片作背景。
18. 文本框自带内部内边距：凡文字要与同一 x 位置的形状、线条或图标对齐，就设 margin: 0。
19. 演讲者备注写进 slide.addNotes("...")（纯文本，每页一次），不要放进幻灯片上的文本框。
20. 图表尽量保持原生：PowerPoint 能画的都用 addChart()（组合图传 {type, data, options} 数组）；库未暴露的原生特性（趋势线、误差线）自己额外算系列或后处理生成的 OOXML，不要退回渲染成图片；只有 PowerPoint 无原生形式的图（Sankey、network、chord）才以图片插入。
21. 默认图表很素（无标题、无数据标签、配色过时）：显式设置 showTitle + title、showValue: true + dataLabelPosition、chartColors: [...]，并收拾边框（catAxisLabelColor/valAxisLabelColor、valGridLine: { color, size }、catGridLine: { style: "none" }，单系列时 showLegend: false）。
22. 堆叠柱形/条形图上 dataLabelPosition 只能是 ctr、inEnd 或 inBase；outEnd 会损坏文件。
23. 组合图使用 secondaryValAxis/secondaryCatAxis 时，图表选项必须同时提供 valAxes 和 catAxes，各两个条目；只给 valAxes 不够，pptxgenjs 会写出从未声明的轴 id，PowerPoint 会丢弃该图表并报文件损坏。
24. writeFile() 之后运行 python scripts/office/validate.py deck.pptx，它能报出上面两类图表缺陷和 PowerPoint 拒绝打开的幻灯片 XML 缺陷；在生成器里修，不要手工编辑打包后的 XML。
25. 绝不要重排 <p:presentation> 的子元素顺序：pptxgenjs 把 <p:notesMasterIdLst> 紧跟在 <p:sldIdLst> 之后并让两个 master 指向同一个主题部件，PowerPoint 能正常读取，但一移动该元素同一个 deck 就打不开。
26. 图标：用 ReactDOMServer.renderToStaticMarkup 把 react-icons 渲染成 SVG，用 sharp 以 ≥256px 栅格化，再通过 addImage({ data: "image/png;base64," + buf.toString("base64") }) 插入（image/png;base64, 前缀必需）；react-icons、react、react-dom、sharp 已预装，只有 require 失败时才 npm install react-icons react react-dom sharp。
27. 编辑已有 deck 或模板时先选版式：python scripts/thumbnail.py template.pptx template-thumbs 输出每页带标签的网格并打印生成的文件（超过 12 页拆成 template-thumbs-N.jpg）；第二个参数必须按 deck 命名，因为默认 thumbnails 会让两个 deck 的网格互相覆盖、前一个直接消失。缩略图只用于模板分析，视觉 QA 要用全分辨率渲染。
28. 把 thumbnail 网格与 markitdown 输出结合，将每一段内容映射到某个模板幻灯片，并变换版式——不要让每个章节都用同一张标题+要点页。
29. 解包：python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx。
30. 重排或删除幻灯片 = 编辑 ppt/presentation.xml 里的 <p:sldIdLst>。
31. 打包：(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .) —— 必须从目录内部打包，且先 rm，否则已删除的部件会残留在包里。
32. 打包后运行 python scripts/office/validate.py out.pptx --original deck.pptx。
33. 所有结构性操作（新增、删除、重排）都要在任何幻灯片内容编辑之前完成：add_slide.py 逐字复制幻灯片文件，之后复制会克隆已改的内容；clean.py 会删掉任何不在 <p:sldIdLst> 里的幻灯片，包括你刚写好的那张。
34. 绝不要手工复制幻灯片文件，用 add_slide.py（它会做新幻灯片所需的全部登记并打印结果，如 Created ppt/slides/slide17.xml from slide2.xml）。注意复制出的幻灯片仍引用源页的图表/SmartArt/嵌入对象部件，改其中一个页面的图表会同时改变另一个。
35. 若用 python-pptx，注意它有三件做不到的事：不能复制幻灯片（唯一入口是 add_slide(layout)）；text_frame.text = "..." 会把段落塌缩成单个无格式 run（应改为给 run.text 赋值）；读不了模板美术常用的 SVG/EMF（add_picture 抛 UnidentifiedImageError）。
36. 旧版 .ppt 必须先转换：python scripts/office/soffice.py --headless --convert-to pptx file.ppt。.potx 模板解包/打包方式与 .pptx 完全相同，输出要保留 .potx 扩展名。
37. 要复用模板里的图标或图片，就复制已经包含它的那张幻灯片或版式。
38. 写 XML 变换脚本时用 defusedxml.minidom 解析；用 xml.etree.ElementTree 往返 OOXML 会重写命名空间前缀并损坏 deck。
39. 模板槽位 ≠ 源内容条目：模板显示 4 名团队成员而你只有 3 名时，删掉第 4 名成员的整组内容（图片 + 文本框），而不只是文字，然后在 QA 中检查是否留下孤立视觉元素。
40. 每个列表项一个 <a:p>，绝不把多项拼进同一个段落；复制同级 <a:pPr> 以保留间距；标题、章节标题和内联标签（Status:、Owner:）的 <a:rPr> 上加 b="1"。
41. 项目符号交给版式继承，只用 <a:buChar>、<a:buAutoNum>（编号）或 <a:buNone> 覆盖，绝不在文本里写真实的「•」。
42. 带前导或尾随空格的文字，其 <a:t> 要加 xml:space="preserve"。
43. 不要做无聊的幻灯片：白底纯要点不会打动任何人，每页都从设计建议中挑思路。
44. 开始前选一个大胆、与内容相关的配色：如果把这套配色换到完全不同的主题上仍然「能用」，说明你做得不够具体。
45. 追求主次而非均等：让一个颜色占主导（60-70% 视觉权重），配 1-2 个辅助色和一个锐利强调色，绝不让所有颜色等权重。
46. 用暗/亮对比：标题页和结论页用深色背景，内容页用浅色（「三明治」结构）；或全程深色以营造高级感。
47. 确定一个视觉母题并重复使用（圆角图片框、彩色圆里的图标等），贯穿每一页；不要用色条或强调条纹作为母题。
48. 按内容主题从给出的主题色板中选色（Midnight Executive、Forest & Moss、Coral Energy、Warm Terracotta、Ocean Gradient、Charcoal Minimal、Teal Trust、Berry & Cream、Sage Calm、Cherry Bold 及其主色/辅色/强调色十六进制值），不要默认通用蓝色。
49. 每一页都要有视觉元素——图片、图表、图标或形状；纯文字页很难被记住。
50. 版式可选：两栏（左文右图）、图标+文字行（彩色圆内图标 + 粗体标题 + 下方描述）、2x2 或 2x3 网格（一侧图片，另一侧内容块网格）、半出血图片（整侧图片）配内容叠加。
51. 数据展示：大号数字标注（60-72pt 数字 + 下方小标签）、对比栏（前后/优劣/并排选项）、时间线或流程（编号步骤、箭头）。
52. 视觉润色：章节标题旁放彩色圆内小图标；关键数据或标语用斜体强调文本。
53. 字体认知：写进 .pptx 的字体名由用户的 PowerPoint 渲染，而本环境的视觉 QA 走 LibreOffice，会替换缺失字体，某些字体的替换体宽度不同，QA 预览可能显示真实 deck 不会有的溢出（或不溢出）。
54. 安全字体（QA 中宽度真实且随 Office 发布）：Arial、Calibri、Cambria、Times New Roman、Courier New、Bookman Old Style、Century Schoolbook；正文和任何在乎适配的地方都用这些。
55. 想给标题加个性又不冒 QA 风险：用安全列表中的衬线标题（Cambria、Bookman Old Style、Century Schoolbook）配安全列表无衬线正文（Calibri 或 Arial），既有视觉对比又保住可靠的溢出检查。
56. 用户明确要求安全列表外的字体（如 Georgia、Trebuchet MS）时按用户要求使用，但对这些容器多留约 10% 余量，且不要相信这些元素的 QA 文本适配结果；用户未指定时正文优先用安全列表字体。
57. QA 不可靠字体（替换体宽度不同，溢出判断可能错误）：Georgia、Trebuchet MS、Impact、Arial Black、Garamond、Consolas、Palatino Linotype；Calibri Light 的替换因环境而异，同样按不可靠处理。这些可用于标题/强调并留余量，但不要相信其 QA 文本适配。
58. 绝不要默认 Aptos：它是 Office 2023 之后的默认字体，这里没有度量兼容的替代，旧版 Office 也没有，两端都不可靠。
59. 字号规范：幻灯片标题 36-44pt 粗体；章节标题 20-24pt 粗体；正文 14-16pt；图注 10-12pt 且用弱化色。
60. 间距规范：页边距至少 0.5"；内容块之间 0.3-0.5"；留出呼吸空间，不要把每一寸都填满。
61. 不要重复同一版式——跨页变换栏、卡片和标注的排布。
62. 不要居中对齐正文——段落和列表左对齐，只让标题居中。
63. 不要吝啬字号对比——标题需要 36pt 以上才能从 14-16pt 正文中跳出来。
64. 不要默认蓝色——选能反映具体主题的颜色。
65. 不要随机混用间距——选定 0.3" 或 0.5" 的间隙并始终一致。
66. 不要只美化一页而其余页素着——要么全部贯彻设计，要么全篇统一简洁。
67. 不要做纯文字页——加图片、图标、图表或视觉元素，避免单纯的标题+要点。
68. 不要忘记文本框内边距——让线条或形状与文字边缘对齐时，设 margin: 0 或相应偏移形状。
69. 不要用低对比元素——图标和文字都要与背景有强对比，避免浅底浅字或深底深字。
70. 绝不要在标题下加强调线——这是 AI 生成幻灯片的标志，改用留白或背景色。
71. 绝不添加装饰性色条或强调条纹——包括横跨整页宽度的页眉/页脚条、沿幻灯片一侧的竖直侧边条、卡片或内容块边缘的细强调条纹、矩形的单边边框。要区分卡片就用轻微背景底色、投影或图标，而不是边缘条纹。
72. 不要默认米色/奶油色背景——未指定背景时用白色（FFFFFF）或用户品牌色，避免 F5F5DC、FAF0E6、FAEBD7、FFF8E1 这类暖中性默认色。
73. 不要交付溢出形状的文字——放不下就缩小字号、拆到多页或放大容器，绝不留下被裁切或越出边界的内容。
74. 内容 QA：运行 markitdown output.pptx，检查内容缺失、错别字、顺序错误。
75. 使用模板时检查残留占位文本：markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"；若 grep 有输出，必须先修掉再宣布完成。
76. 文件 QA（必做）：从零构建的 deck 运行 python scripts/office/validate.py output.pptx；从模板构建的运行 python scripts/office/validate.py output.pptx --original src.pptx。
77. 模板派生 deck 一定要传 --original：模板自身可能含有 XSD 拒绝的部件，裸跑会报你没造成的失败，真实回归也可能藏在其中；--original 以模板为基线抑制模板既有的 schema 与幻灯片错误。注意结构检查（关系、内容类型、图表）忽略 --original，模板继承的问题照样会报，要单独按其本身判断。
78. 记住 pptxgenjs 会产出 PowerPoint 拒绝打开、而其它工具都能接受的图表 XML（python-pptx 能打开、LibreOffice 能渲染、XSD 能通过），每个失败都会给出修法；在生成器里修好后重建，而不是手工改 XML。
79. 视觉 QA：把幻灯片转成图片并逐张检查；盯着生成代码时你容易看到预期而非实际渲染，所以要用全新的眼光看图（如有子代理，交给子代理看效果好）。
80. 视觉缺陷逐项检查：文字溢出或被文本框/幻灯片边界截断（最先查，最常见且用户一定可见）；元素重叠（文字穿过形状、线条穿过文字、元素堆叠）；来源引用或页脚与上方内容相撞；元素过近（< 0.3"）或卡片/区块几乎相触；间距不均（一处大片空白、一处拥挤）；距幻灯片边缘不足 0.5"；栏或同类元素未对齐；低对比文字（如奶油底上的浅灰字）；文字替换后模板装饰错位（例如标题下划线按一行定位，但替换后的标题换行成两行）；低对比图标（如深底深色图标且无对比圆底）；文本框过窄导致过度换行；残留的占位内容。对预览器渲染不可靠的字体，预览只是近似：相信你预留的约 10% 余量，而不是它看起来的适配。
81. 转图命令：python scripts/office/soffice.py --headless --convert-to pdf output.pptx；然后 rm -f slide-*.jpg 清掉上次残留；再 pdftoppm -jpeg -r 150 output.pdf slide；再 ls -1 "$PWD"/slide-*.jpg。
82. 把上面打印出的绝对路径直接传给 view 工具查看。pdftoppm 按页数补零命名：不足 10 页是 slide-1.jpg，10-99 页是 slide-01.jpg，100 页以上是 slide-001.jpg。
83. 修改后要重跑上述四条命令（PDF 必须先从改后的 .pptx 重新生成，pdftoppm 才能反映改动），只重渲染改过的幻灯片然后停止。
84. 依赖清单：pptxgenjs（npm，预装）、markitdown[pptx]、Pillow、defusedxml、lxml（pip，用于文本导出、缩略图、clean、validate）、LibreOffice（soffice，通过 scripts/office/soffice.py 为沙箱环境自动配置）、pdftoppm（Poppler）。

适用边界 · 注意事项

• 完全不涉及 .pptx/.potx 文件时（例如只要一份纯文本大纲，或目标是 Google Slides / Keynote 原生格式）不需要这套流程。
• 环境缺少 LibreOffice(soffice)、pdftoppm 或 node，且无法安装依赖时，PDF 转换、视觉 QA 与 pptxgenjs 生成路径都无法完成。
• 只需要一次性、可舍弃的粗略内容读取且不产出/不修改 deck 时，直接用 markitdown 即可，无需解包、打包与完整校验流程。