pptx

PPTX 创建、编辑和分析

.pptx 文件是 XML 文件的 ZIP 归档。根据任务选择方法：

任务	方法
创建新演示文稿	编写 pptxgenjs 脚本——参见下面的注意事项
编辑现有演示文稿，或从模板构建	解压 → 编辑 ppt/slides/slideN.xml → 压缩
读取内容	markitdown deck.pptx（每个幻灯片一个块，位于 <!-- Slide number: N --> 标记下）；视觉网格：python scripts/thumbnail.py deck.pptx

脚本

路径相对于此技能目录。其他所有内容都是纯 Python、node 或 shell。

脚本	功能
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——它会将架构检查与模板进行基线比较，因此模板自身的 XSD 错误不会被视为你的错误
scripts/office/soffice.py --headless --convert-to pdf deck.pptx	LibreOffice 包装器——裸 soffice 在此沙箱中会挂起

使用 pptxgenjs 创建——注意事项

pptxgenjs 已预装——不要先运行 npm install；直接编写脚本并 require('pptxgenjs')。仅当该 require 失败时：npm install pptxgenjs。模型了解 API；以下是陷阱：

• 在添加幻灯片之前设置 pres.layout。 默认画布是 LAYOUT_16x9 = 10" × 5.625"，不是 13.3" 宽。超出边缘的坐标会被写入，而不是被裁剪——形状只是不在幻灯片上。（LAYOUT_WIDE 是 13.3" × 7.5"。）
• 十六进制颜色：绝不使用 #，绝不使用 8 位数字。 color: "FF0000"。"#FF0000" 和十六进制中嵌入的 alpha（"00000020"）都会损坏文件。对于半透明：填充和图像使用 transparency: 0-100，阴影使用 opacity: 0.0-1.0——每个在另一个上都会被静默忽略。
• pptxgenjs 会就地修改选项对象（首次使用时将值转换为 EMU）。绝不要在两个 add* 调用之间共享一个 shadow/选项对象——每次都构建一个新对象。
• 阴影 offset 必须 ≥ 0——负偏移会损坏文件。要向上投射阴影，请使用 angle: 270 和正偏移。
• letterSpacing 会被静默忽略——真正的选项是 charSpacing。
• 列表： 每个项目使用 bullet: true，绝不使用字面 •（会渲染双项目符号）。在每个数组项目上设置 breakLine: true，除了最后一个。使用 paraSpaceAfter 分隔项目符号段落，而不是 lineSpacing（会产生巨大间隙）。
• 每个输出文件使用一个 new pptxgen()——绝不重用实例。
• rectRadius 仅适用于 ROUNDED_RECTANGLE，不适用于 RECTANGLE。
• 不支持渐变填充——使用渐变图像作为背景。
• 文本框有内置内边距——当文本必须与同一 x 处的形状、线条或图标对齐时，设置 margin: 0。
• 演讲者备注放在 slide.addNotes("...") 中（纯文本，每个幻灯片一次），绝不放在幻灯片上的文本框中。
• 保持图表原生。 对于 PowerPoint 可以绘制的所有内容，使用 addChart()（对于组合图，传递 {type, data, options} 数组）。对于库未公开的 PowerPoint 原生功能（趋势线、误差线），自行计算额外系列或后处理生成的 OOXML——不要回退到渲染图像。只有 PowerPoint 没有原生形式的图表类型（Sankey、网络、和弦）才作为图像插入。
• 默认图表渲染为裸图——没有标题、没有数据标签、过时的调色板。设置 showTitle + title、showValue: true + dataLabelPosition、chartColors: [...] 从你的调色板中，并静音框架（catAxisLabelColor/valAxisLabelColor、valGridLine: { color, size }、catGridLine: { style: "none" }、对于单个系列使用 showLegend: false）。
• 在堆叠条形图或柱状图上，dataLabelPosition 必须是 ctr、inEnd 或 inBase。 outEnd 会损坏文件。
• 使用 secondaryValAxis/secondaryCatAxis 的组合系列需要在图表选项上同时设置 valAxes 和 catAxes，每个两个条目。 没有它们，pptxgenjs 会写入它从未声明的轴 id，PowerPoint 会丢弃该图表并报告文件损坏。仅提供 valAxes 是不够的。
• 在 writeFile() 之后，运行 python scripts/office/validate.py deck.pptx。 它会报告上述两个图表故障和 PowerPoint 拒绝的幻灯片 XML 缺陷，并指出每个的修复方法。在生成器中修复它们，而不是手动编辑打包的 XML。
• 绝不要重新排序 <p:presentation> 的子元素。 pptxgenjs 在 <p:sldIdLst> 之后立即写入 <p:notesMasterIdLst>，并将两个母版指向一个主题部件。PowerPoint 可以愉快地读取该文件——移动元素后，同一个演示文稿将无法打开。
• 图标： 将 react-icons 渲染为 SVG（ReactDOMServer.renderToStaticMarkup），使用 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）。

编辑现有演示文稿和模板

首先选择版式：python scripts/thumbnail.py template.pptx template-thumbs 会写入每个幻灯片的带标签网格，并打印它创建的文件——template-thumbs.jpg，超过 12 张幻灯片时拆分为 template-thumbs-N.jpg。始终传递第二个参数，以演示文稿命名。 它默认为 thumbnails，因此同一目录中两个演示文稿的缩略图会静默覆盖彼此的网格——第一个演示文稿的网格就消失了（仅模板分析——视觉 QA 需要 转换为图像 中的全分辨率渲染；它只接受 .pptx，因此先将 .potx 复制为 .pptx 名称）。将其与 markitdown 结合使用，将每个内容部分映射到模板幻灯片，并变化版式——不要将每个部分放在相同的标题和项目符号幻灯片上。

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   # 复制幻灯片（或 slideLayoutN.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 .)           # 从目录内部压缩；先 rm，否则已删除的部分会保留
python scripts/office/validate.py out.pptx --original deck.pptx

• 在编辑任何幻灯片内容之前，完成所有结构工作——添加、删除、重新排序。 add_slide.py 会逐字复制幻灯片文件，因此编辑后复制会克隆编辑过的内容；clean.py 会删除 <p:sldIdLst> 中缺失的任何幻灯片，包括你刚刚写入的。
• 绝不要手动复制幻灯片文件——add_slide.py 会执行新幻灯片所需的每个注册，并报告它创建的内容（Created ppt/slides/slide17.xml from slide2.xml）。它也可以直接对文件操作：add_slide.py deck.pptx slide2.xml -o out.pptx——传递 -o，否则它会原地重写输入演示文稿。 复制的幻灯片仍然引用其源文件的图表/SmartArt/嵌入对象部件，而不是克隆它们，因此编辑一个幻灯片的图表会改变另一个。
• 如果你使用 python-pptx，它不会做三件事：复制幻灯片（其唯一入口点是 add_slide(layout)）、通过 text_frame.text = "..." 保留格式（这会将段落折叠为单个无样式运行——改为分配 run.text）、或读取大多数模板艺术使用的 SVG/EMF（add_picture 会引发 UnidentifiedImageError）。
• 旧版 .ppt 必须先转换：python scripts/office/soffice.py --headless --convert-to pptx file.ppt。.potx 模板的解压和打包方式相同——在输出上保留 .potx 扩展名。
• 要重用模板图标或图像，请复制已包含它的幻灯片或版式。

填充模板时：

• 如果你编写 XML 转换脚本，请使用 defusedxml.minidom 解析——通过 xml.etree.ElementTree 往返 OOXML 会重写命名空间前缀并损坏演示文稿。
• 模板槽 ≠ 源项目。 如果模板显示 4 个团队成员而你有 3 个，请删除第 4 个成员的整个组（图像 + 文本框），而不仅仅是其文本——然后在 QA 中检查是否有孤立的视觉元素。
• 每个列表项一个 <a:p>——绝不要将项目连接成单个段落。复制兄弟 <a:pPr> 以保留间距，并在标题、节标题和内联标签（Status:、Owner:）的 <a:rPr> 上放置 b="1"。
• 让项目符号继承自版式；仅添加 <a:buChar>、<a:buAutoNum>（编号）或 <a:buNone> 来覆盖——绝不要在文本中使用字面 •。
• 带有前导或尾随空格的文本需要在其 <a:t> 上设置 xml:space="preserve"。

设计理念

不要创建无聊的幻灯片。 白色背景上的纯项目符号不会给任何人留下深刻印象。考虑此列表中的每个幻灯片的想法。

开始之前

• 选择大胆、内容相关的调色板：调色板应感觉是为这个主题设计的。如果交换颜色到完全不同的演示文稿仍然“有效”，那么你的选择不够具体。
• 主导而非平等：一种颜色应占主导（60-70% 的视觉权重），有 1-2 个辅助色调和一个锐利强调色。绝不要给所有颜色相同的权重。
• 深色/浅色对比：标题和结论幻灯片使用深色背景，内容使用浅色（“三明治”结构）。或者全程使用深色以获得高级感。
• 致力于视觉主题：选择一个独特的元素并重复——圆角图像框、彩色圆圈中的图标。在每个幻灯片上携带它。不要使用颜色条或强调条纹作为主题（参见避免列表）。

调色板

选择与主题匹配的颜色——不要默认使用通用蓝色。使用这些调色板作为灵感：

主题	主色	辅助色	强调色
午夜行政	1E2761（海军蓝）	CADCFC（冰蓝）	FFFFFF（白色）
森林与苔藓	2C5F2D（森林绿）	97BC62（苔藓绿）	F5F5F5（奶油色）
珊瑚能量	F96167（珊瑚红）	F9E795（金色）	2F3C7E（海军蓝）
温暖赤陶	B85042（赤陶色）	E7E8D1（沙色）	A7BEAE（鼠尾草绿）
海洋渐变	065A82（深蓝）	1C7293（蓝绿色）	21295C（午夜蓝）
炭黑极简	36454F（炭黑）	F2F2F2（米白）	212121（黑色）
蓝绿信任	028090（蓝绿色）	00A896（海沫绿）	02C39A（薄荷绿）
浆果与奶油	6D2E46（浆果色）	A26769（灰玫瑰）	ECE2D0（奶油色）
鼠尾草宁静	84B59F（鼠尾草绿）	69A297（桉树绿）	50808E（石板蓝）
樱桃大胆	990011（樱桃红）	FCF6F5（米白）	2F3C7E（海军蓝）

每个幻灯片

每个幻灯片都需要一个视觉元素——图像、图表、图标或形状。纯文本幻灯片容易被遗忘。

布局选项：

• 两列（文本在左，插图在右）
• 图标 + 文本行（彩色圆圈中的图标，粗体标题，下方描述）
• 2x2 或 2x3 网格（一侧图像，另一侧内容块网格）
• 半出血图像（整左或右侧）与内容叠加

数据展示：

• 大数字标注（60-72pt 大数字，下方小标签）
• 比较列（之前/之后、优点/缺点、并排选项）
• 时间线或流程（编号步骤、箭头）

视觉润色：

• 节标题旁边的小彩色圆圈中的图标
• 关键统计或标语使用斜体强调文本

排版

你写入 .pptx 的字体名称由用户的 PowerPoint 渲染，而不是此环境。 你的视觉 QA 通过 LibreOffice 渲染，它会替换没有的字体——对于某些字体，替换字体具有不同的宽度，因此你的 QA 预览可能显示文本溢出（或适合），而实际演示文稿不会。为了保持 QA 可信：

• 安全字体（在 QA 中按宽度真实渲染并且随 Office 提供）：Arial、Calibri、Cambria、Times New Roman、Courier New、Bookman Old Style、Century Schoolbook。用于正文和任何适合性重要的内容。
• 零 QA 风险的个性标题：将安全列表中的衬线标题（Cambria、Bookman Old Style、Century Schoolbook）与安全列表中的无衬线正文（Calibri 或 Arial）配对。你获得视觉对比，而不放弃可靠的溢出检查。
• 如果用户要求安全列表之外的字体（例如 Georgia 或 Trebuchet MS）：在用户要求的地方使用它，但为这些容器留出额外空间（约 10%），并且不要信任这些元素上的 QA 文本适配——该字体的预览是近似的。如果用户未指定，正文文本优先使用安全列表字体。
• QA 不可靠字体（替换字体宽度不同——溢出检查可能错误）：Georgia、Trebuchet MS、Impact、Arial Black、Garamond、Consolas、Palatino Linotype。Calibri Light 的替换因环境而异；视为 QA 不可靠。适合标题/强调，留有余量；不要信任这些上的 QA 文本适配。
• 绝不要默认使用 Aptos——Office 2023 后的默认字体在此没有度量兼容的替换并且在较旧的 Office 安装中缺失，因此两端都不可靠。

元素	大小
幻灯片标题	36-44pt 粗体
节标题	20-24pt 粗体
正文	14-16pt
标题	10-12pt 弱化

间距

• 最小边距 0.5"
• 内容块之间 0.3-0.5"
• 留出呼吸空间——不要填满每一寸

避免（常见错误）

• 不要重复相同的布局——在幻灯片之间变化列、卡片和标注
• 不要居中正文——左对齐段落和列表；仅居中标题
• 不要吝啬大小对比——标题需要 36pt+ 才能从 14-16pt 正文中脱颖而出
• 不要默认使用蓝色——选择反映特定主题的颜色
• 不要随机混合间距——选择 0.3" 或 0.5" 的间隙并一致使用
• 不要只样式化一张幻灯片而其余保持朴素——完全投入或全程保持简单
• 不要创建纯文本幻灯片——添加图像、图标、图表或视觉元素；避免纯标题 + 项目符号
• 不要忘记文本框内边距——当将线条或形状与文本边缘对齐时，在文本框上设置 margin: 0 或偏移形状以考虑内边距
• 不要使用低对比度元素——图标和文本都需要与背景形成强烈对比；避免浅色背景上的浅色文本或深色背景上的深色文本
• 绝不要在标题下使用强调线——这是 AI 生成幻灯片的标志；使用空白或背景色代替
• 绝不要添加装饰性颜色条或强调条纹——这包括：跨越幻灯片宽度的页眉/页脚条、沿幻灯片边缘的垂直侧边条纹、沿卡片或内容块边缘的细强调条纹，以及矩形上的“单侧边框”。这些看起来像 AI 生成的填充。如果你想区分卡片，使用微妙的背景色调、投影或图标——而不是边缘条纹。
• 不要默认使用奶油色/米色背景——当未指定背景时，使用白色（FFFFFF）或用户的品牌调色板；避免暖中性默认值，如 F5F5DC、FAF0E6、FAEBD7、FFF8E1
• 不要交付溢出其形状的文本——如果文本不适合，减小字体大小、拆分到多张幻灯片或扩大容器；绝不要让内容被截断或溢出边界

QA（必需）

你的第一次渲染通常会有几个真实问题——重叠、溢出、对齐。找到并修复它们，仅重新渲染你更改的幻灯片，然后停止。

内容 QA

markitdown output.pptx

检查缺失内容、拼写错误、顺序错误。

使用模板时，检查是否有遗留的占位符文本：

markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"

如果 grep 返回结果，在宣布成功之前修复它们。

文件 QA（必需）

python scripts/office/validate.py output.pptx                      # 从头构建
python scripts/office/validate.py output.pptx --original src.pptx  # 从模板构建

如果演示文稿来自模板，始终传递 --original。 模板本身可能包含 XSD 拒绝的部件，因此裸运行可能报告你从未引起的失败——而真正的回归可能隐藏在它们之中。--original 将架构和幻灯片检查与模板进行基线比较，抑制它已有的错误。结构检查——关系、内容类型、图表——忽略 --original，无论如何都会报告模板继承的问题，因此根据其自身优点阅读它们。

pptxgenjs 会生成 PowerPoint 拒绝打开的图表 XML，而其他所有工具都接受：python-pptx 可以打开这些演示文稿，LibreOffice 可以渲染它们，XSD 通过它们。每个失败都会指出修复方法。在生成器中修复并重建。

视觉 QA

将幻灯片转换为图像（参见 转换为图像）并检查每一张。盯着生成代码看后，你往往看到的是期望而不是实际渲染，因此以新鲜眼光查看图像（如果你有子代理，这很有效）。要查找的用户可见缺陷：

• 文本溢出或文本在框或幻灯片边界处被截断——首先检查这个。 这是最常见的缺陷，并且总是用户可见的。（对于预览器按排版不可靠渲染的字体，预览是近似的：信任你留下的约 10% 余量，而不是其表面适配。）
• 重叠元素（文本穿过形状、线条穿过文字、堆叠元素）
• 来源引用或页脚与上方内容碰撞
• 元素太近（< 0.3" 间隙）或卡片/部分几乎接触
• 间隙不均匀（一处大空白，另一处拥挤）
• 距幻灯片边缘的边距不足（< 0.5"）
• 列或类似元素未一致对齐
• 低对比度文本（例如，奶油色背景上的浅灰色文本）
• 文本替换后模板装饰错位——例如，标题下划线定位为一行，但替换的标题换行为两行
• 低对比度图标（例如，深色背景上的深色图标，没有对比圆圈）
• 文本框太窄导致过度换行
• 遗留的占位符内容

转换为图像

将演示文稿转换为单独的幻灯片图像以进行视觉检查：

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

将上面打印的绝对路径直接传递给视图工具。 rm 清除先前运行中的陈旧图像。pdftoppm 根据页数零填充：少于 10 页的演示文稿为 slide-1.jpg，10-99 页为 slide-01.jpg，100+ 页为 slide-001.jpg。

修复后，重新运行上述所有四个命令——必须从编辑后的 .pptx 重新生成 PDF，然后 pdftoppm 才能反映你的更改。

依赖项

pptxgenjs（npm，预装——仅当 require('pptxgenjs') 失败时安装）· markitdown[pptx]、Pillow、defusedxml、lxml（pip——文本转储、缩略图、清理、验证）· LibreOffice（soffice，通过 scripts/office/soffice.py 自动配置用于沙箱环境）· pdftoppm（Poppler）

---

此技能由 Anthropic 创建和维护。此处仅修改了 frontmatter 元数据，其余未修改；条款见 LICENSE.txt。