pptx

用途

pptx 技能用于在任何涉及 .pptx 或 .potx 文件的场景中工作，包括作为输入、输出或两者兼有。典型任务包括：创建幻灯片演示文稿、路演材料，编辑现有演示文稿，或基于模板构建新文稿，以及读取和分析演示文稿内容。

主要能力

该技能把 .pptx 视为 XML 文件的 ZIP 压缩包，并根据任务类型提供不同处理路径：

创建新演示文稿：编写 pptxgenjs 脚本。
编辑现有文稿或基于模板构建：解压 → 编辑 ppt/slides/slideN.xml → 重新打包。
读取内容：使用 markitdown deck.pptx，每张幻灯片对应一个块，位于  标记下；也可用 python scripts/thumbnail.py deck.pptx 生成可视化网格。

技能附带以下脚本（路径相对于技能目录）：

scripts/thumbnail.py deck.pptx [prefix]：生成每张幻灯片的带标签网格，用于挑选模板版式。仅支持 .pptx。需传入 prefix，默认值 thumbnails 会覆盖同目录下其他文稿的网格。
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml]：复制幻灯片（或 slideLayoutN.xml），并完成所有包内登记。也可直接对 .pptx 使用，配合 -o out.pptx。
scripts/clean.py unpacked/：删除不再被引用的幻灯片、媒体和关系文件。在 <p:sldIdLst> 最终确定后运行。
scripts/office/validate.py deck.pptx [--original src.pptx]：检查架构、关系、内容类型、图表和幻灯片；每个失败项会给出修复方法。对任何基于模板的文稿都应传入 --original。
scripts/office/soffice.py --headless --convert-to pdf deck.pptx：LibreOffice 包装器。

使用方式

使用 pptxgenjs 创建

pptxgenjs 已预装，不要先运行 npm install；直接编写脚本并 require('pptxgenjs')。仅当 require 失败时才运行 npm install pptxgenjs。

需要注意的要点包括：在添加幻灯片前设置 pres.layout；十六进制颜色不要带 #，不要用 8 位；pptxgenjs 会就地修改选项对象，不要跨 add* 调用共享同一对象；阴影偏移必须 ≥ 0；letterSpacing 会被忽略，应使用 charSpacing；列表项使用 bullet: true，不要用字面量 •；每个输出文件只创建一个 pptxgen() 实例；rectRadius 仅适用于 ROUNDED_RECTANGLE；不支持渐变填充；文本框有内置内边距，需要对齐时设置 margin: 0；演讲者备注使用 slide.addNotes("...")；图表尽量保持原生，使用 addChart()；默认图表样式简陋，需设置标题、数据标签、颜色等；堆叠条形图或柱状图的 dataLabelPosition 必须为 ctr、inEnd 或 inBase；组合图使用次坐标轴时需要同时提供 valAxes 和 catAxes；writeFile() 后运行 validate.py；不要重排 <p:presentation> 的子元素；图标可渲染 react-icons 为 SVG，再用 sharp 栅格化后插入。

编辑现有文稿和模板

先用 scripts/thumbnail.py template.pptx template-thumbs 挑选版式，它会生成带标签的网格并打印创建的文件。始终传入第二个参数，以文稿命名。默认值 thumbnails 会导致同目录下两个文稿的网格互相覆盖。

解压、复制幻灯片、重排/删除幻灯片、清理、编辑内容、重新打包、校验的流程如下：

python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml

重排/删除幻灯片 = 编辑 ppt/presentation.xml 中的 <p:sldIdLst>

python scripts/clean.py unpacked/

编辑 ppt/slides/slideN.xml 中的幻灯片内容

(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .) python scripts/office/validate.py out.pptx --original deck.pptx

所有结构性工作（添加、删除、重排）应在编辑任何幻灯片内容之前完成。不要手工复制幻灯片文件，应使用 add_slide.py。如果使用 python-pptx，它不支持复制幻灯片、通过 text_frame.text = "..." 保留格式，以及读取模板中常见的 SVG/EMF。旧版 .ppt 必须先转换。

填充模板

如果编写 XML 转换脚本，使用 defusedxml.minidom 解析，避免用 xml.etree.ElementTree 往返 OOXML 导致命名空间前缀被重写。模板槽位与源项目数量可能不一致，多余项应删除整个组。每个列表项一个 <a:p>，不要拼接。项目符号应从版式继承，仅添加 <a:buChar>、<a:buAutoNum> 或 <a:buNone> 来覆盖。带前导或尾随空格的文本需要在 <a:t> 上设置 xml:space="preserve"。

设计建议

不要创建无聊的幻灯片。纯白背景加项目符号不会给人留下印象。建议：

选择大胆、与内容相关的配色方案，一种颜色主导（60-70% 视觉权重），1-2 种辅助色，一个鲜明强调色。
深色/浅色对比：标题和结论用深色背景，内容用浅色，或全程深色。
坚持一个视觉母题，并在每张幻灯片上重复。
每张幻灯片都需要视觉元素：图片、图表、图标或形状。
版式可选：双栏、图标+文本行、2x2 或 2x3 网格、半出血图片。
数据展示：大数字标注、对比栏、时间线或流程图。
字体：安全字体包括 Arial、Calibri、Cambria、Times New Roman、Courier New、Bookman Old Style、Century Schoolbook。标题 36-44pt 粗体，节标题 20-24pt 粗体，正文 14-16pt，说明文字 10-12pt。
间距：最小边距 0.5"，内容块之间 0.3-0.5"。
避免：重复相同版式、居中正文、尺寸对比不足、默认蓝色、随机间距、只做一张幻灯片、纯文本幻灯片、忘记文本框内边距、低对比度元素、标题下划线、装饰性色条或强调条纹、默认奶油/米色背景、文本溢出形状。

适用场景

适用于需要创建、编辑、分析或基于模板构建 PowerPoint 演示文稿的场景，包括制作幻灯片、路演材料、读取演示文稿内容、生成缩略图网格以挑选版式等。

限制

缩略图脚本仅支持 .pptx，.potx 需先复制为 .pptx 名称。
视觉 QA 需要全分辨率渲染，缩略图仅用于模板分析。
字体渲染由用户的 PowerPoint 决定，QA 通过 LibreOffice 渲染，部分字体替换后宽度不同，可能导致溢出检查不准确。
不支持渐变填充，需使用渐变图片作为背景。
组合图使用次坐标轴时必须同时提供 valAxes 和 catAxes，否则 PowerPoint 会丢弃图表并报告文件损坏。
不要重排 <p:presentation> 的子元素，否则文稿可能无法打开。
旧版 .ppt 必须先转换为 .pptx。
使用 python-pptx 时有三项限制：无法复制幻灯片、无法通过 text_frame.text 保留格式、无法读取 SVG/EMF。
交付前必须进行内容 QA 和文件 QA，使用 markitdown 和 validate.py 检查。