PPTX 创建、编辑和分析

概览

用户可能会要求你创建、编辑或分析 .pptx 文件的内容。.pptx 文件本质上是一个包含 XML 文件和其他资源的 ZIP 归档，你可以读取或编辑这些内容。

读取和分析内容

文本提取

如果只需要读取演示文稿的文本内容，你应该将文档转换为 markdown：

# 将文档转换为 markdown
python -m markitdown 路径到文件.pptx

原始 XML 访问

你需要原始 XML 访问来处理：评论、演讲者备注、幻灯片布局、动画、设计元素和复杂格式。对于这些功能，你需要解包演示文稿并读取其原始 XML 内容。

解包文件

python ooxml/scripts/unpack.py <office_file> <output_dir>

注意：unpack.py 脚本位于 skills/pptx/ooxml/scripts/unpack.py 相对于项目根目录的路径。如果该路径下没有脚本，请使用 find . -name "unpack.py" 来定位它。

关键文件结构

ppt/presentation.xml - 主演示文稿元数据和幻灯片引用
ppt/slides/slide{N}.xml - 各个幻灯片内容（例如 slide1.xml, slide2.xml）
ppt/notesSlides/notesSlide{N}.xml - 每个幻灯片的演讲者备注
ppt/comments/modernComment_*.xml - 特定幻灯片的评论
ppt/slideLayouts/ - 幻灯片布局模板
ppt/slideMasters/ - 主幻灯片模板
ppt/theme/ - 主题和样式信息
ppt/media/ - 图像和其他媒体文件

排版和颜色提取

当给定一个示例设计以模仿时：首先使用以下方法分析演示文稿的排版和颜色：

读取主题文件：检查 ppt/theme/theme1.xml 中的颜色（<a:clrScheme>）和字体（<a:fontScheme>）
样本幻灯片内容：检查 ppt/slides/slide1.xml 中实际的字体使用（<a:rPr>）和颜色
搜索模式：使用 grep 在所有 XML 文件中查找颜色（<a:solidFill>, <a:srgbClr>）和字体引用

无模板创建新的 PowerPoint 演示文稿

当从头开始创建新的 PowerPoint 演示文稿时，使用 html2pptx 工作流程将 HTML 幻灯片转换为 PowerPoint，并准确定位。

设计原则

关键：在创建任何演示文稿之前，分析内容并选择适当的设计元素：

考虑主题：这个演示文稿是关于什么的？它暗示了什么语调、行业或情绪？
检查品牌：如果用户提到公司/组织，请考虑他们的品牌颜色和身份
与内容匹配的调色板：选择反映主题的颜色
陈述你的方法：在编写代码之前解释你的设计选择

要求：

✅ 在编写代码之前陈述你的内容驱动的设计方法
✅ 仅使用网络安全字体：Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
✅ 通过大小、权重和颜色创建清晰的视觉层次
✅ 确保可读性：强对比度、适当大小的文本、清晰的对齐
✅ 保持一致性：在幻灯片中重复模式、间距和视觉语言

颜色调色板选择

创造性地选择颜色：

超越默认：什么颜色真正匹配这个特定主题？避免自动驾驶选择。
考虑多个角度：主题、行业、情绪、能量水平、目标受众、品牌身份（如果提到）
冒险：尝试意想不到的组合 - 医疗保健演示文稿不必是绿色的，金融不必是海军蓝
构建你的调色板：选择 3-5 种可以一起工作的颜色（主导颜色 + 支持色调 + 重点）
确保对比：文本必须在背景上清晰可读

示例调色板（用这些来激发创造力 - 选择一个，适应它，或创建你自己的）：

经典蓝色：深海军蓝（#1C2833），板岩灰（#2E4053），银（#AAB7B8），米白色（#F4F6F6）
蓝绿色 & 珊瑚色：蓝绿色（#5EA8A7），深蓝绿色（#277884），珊瑚色（#FE4447），白色（#FFFFFF）
大胆红色：红色（#C0392B），鲜红色（#E74C3C），橙色（#F39C12），黄色（#F1C40F），绿色（#2ECC71）
温暖的腮红：紫红色（#A49393），腮红（#EED6D3），玫瑰色（#E8B4B8），奶油色（#FAF7F2）
勃艮第豪华：勃艮第（#5D1D2E），深红色（#951233），铁锈色（#C15937），金色（#997929）
深紫色 & 翡翠：紫色（#B165FB），深蓝色（#181B24），翡翠（#40695B），白色（#FFFFFF）
奶油色 & 森林绿：奶油色（#FFE1C7），森林绿（#40695B），白色（#FCFCFC）
粉红色 & 紫色：粉红色（#F8275B），珊瑚色（#FF574A），玫瑰色（#FF737D），紫色（#3D2F68）
酸橙 & 李子：酸橙（#C5DE82），李子（#7C3A5F），珊瑚色（#FD8C6E），蓝灰色（#98ACB5）
黑色 & 金色：金色（#BF9A4A），黑色（#000000），奶油色（#F4F6F6）
鼠尾草 & 陶土：鼠尾草（#87A96B），陶土（#E07A5F），奶油色（#F4F1DE），木炭色（#2C2C2C）
木炭 & 红色：木炭色（#292929），红色（#E33737），浅灰色（#CCCBCB）
鲜明的橙色：橙色（#F96D00），浅灰色（#F2F2F2），木炭色（#222831）
森林绿：黑色（#191A19），绿色（#4E9F3D），深绿色（#1E5128），白色（#FFFFFF）
复古彩虹：紫色（#722880），粉红色（#D72D51），橙色（#EB5C18），琥珀色（#F08800），金色（#DEB600）
复古大地色调：芥末色（#E3B448），鼠尾草（#CBD18F），森林绿（#3A6B35），奶油色（#F4F1DE）
海岸玫瑰：旧玫瑰（#AD7670），海狸色（#B49886），鸡蛋壳（#F3ECDC），灰烬灰色（#BFD5BE）
橙色 & 绿松石：浅橙色（#FC993E），灰绿色（#667C6F），白色（#FCFCFC）

视觉细节选项

几何图案：

对角线部分分隔符而不是水平的
不对称的列宽（30/70, 40/60, 25/75）
旋转的文本标题 90° 或 270°
圆形/六边形框架用于图像
三角形口音形状在角落
重叠形状以增加深度

边框和框架处理：

单色边框（10-20pt）仅在一侧
对比色双线边框
角落支架而不是全框
L形边框（顶部+左侧或底部+右侧）
标题下方的下划线口音（3-5pt厚）

排版处理：

极端大小对比（72pt 标题 vs 11pt 正文）
全部大写标题与宽字母间距
用超大显示字体编号部分
数据/统计/技术内容的等宽字体（Courier New）
用于密集信息的压缩字体（Arial Narrow）
轮廓文本以强调

图表和数据样式：

单色图表，单个重点数据的单色
水平条形图而不是垂直的
点图而不是条形图
最小网格线或没有
数据标签直接在元素上（没有图例）
关键指标的超大数字

布局创新：

全出血图像与文本覆盖
侧栏列（20-30% 宽度）用于导航/上下文
模块化网格系统（3×3, 4×4 块）
Z形或 F形内容流
彩色形状上的浮动文本框
杂志风格的多栏布局

背景处理：

占据 40-60% 幻灯片的纯色块
仅垂直或对角线渐变填充
分割背景（两种颜色，对角线或垂直）
边缘到边缘的颜色带
负空间作为设计元素

布局技巧

当创建包含图表或表格的幻灯片时：

两列布局（首选）：使用跨越整个宽度的标题，然后在下面有两个列 - 一个列中包含文本/项目符号，另一个列中包含特色内容。这提供了更好的平衡，并使图表/表格更易读。使用 flexbox 与不等列宽（例如，40%/60% 分割）来优化每种内容类型的空间。
全幻灯片布局：让特色内容（图表/表格）占据整个幻灯片，以获得最大影响和可读性
永不垂直堆叠：不要将图表/表格放在单列中的文本下方 - 这会导致可读性和布局问题

工作流程

强制性 - 阅读整个文件：从开始到结束完全阅读 html2pptx.md。在阅读此文件时永远不要设置任何范围限制。 在进行演示文稿创建之前，阅读完整的文件内容以了解详细的语法、关键格式规则和最佳实践。
创建每个幻灯片的 HTML 文件，具有适当的尺寸（例如，16:9 的 720pt × 405pt）
- 使用 <p>, <h1>-<h6>, <ul>, <ol> 用于所有文本内容
- 使用 class="placeholder" 用于将添加图表/表格的区域（用灰色背景渲染以提高可见性）
- 关键：首先使用 Sharp 将渐变和图标光栅化为 PNG 图像，然后在 HTML 中引用
- 布局：对于包含图表/表格/图像的幻灯片，使用全幻灯片布局或两列布局以获得更好的可读性
使用 html2pptx.js 库创建并运行 JavaScript 文件，将 HTML 幻灯片转换为 PowerPoint 并保存演示文稿
- 使用 html2pptx() 函数处理每个 HTML 文件
- 使用 PptxGenJS API 在占位符区域添加图表和表格
- 使用 pptx.writeFile() 保存演示文稿
视觉验证：生成缩略图并检查布局问题
- 创建缩略图网格：python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
- 仔细检查缩略图图像：
  - 文本截断：文本被标题栏、形状或幻灯片边缘切断
  - 文本重叠：文本与其他文本或形状重叠
  - 定位问题：内容离幻灯片边界或其他元素太近
  - 对比度问题：文本和背景之间的对比度不足
- 如果发现问题，调整 HTML 边距/间距/颜色并重新生成演示文稿
- 重复直到所有幻灯片在视觉上正确

编辑现有的 PowerPoint 演示文稿

当编辑现有 PowerPoint 演示文稿中的幻灯片时，你需要使用原始的 Office Open XML (OOXML) 格式。这涉及到解包 .pptx 文件，编辑 XML 内容，并重新打包它。

工作流程

强制性 - 阅读整个文件：从开始到结束完全阅读 ooxml.md。在阅读此文件时永远不要设置任何范围限制。 在进行任何演示文稿编辑之前，阅读完整的文件内容以了解 OOXML 结构和编辑工作流程的详细指导。
解包演示文稿：python ooxml/scripts/unpack.py <office_file> <output_dir>
编辑 XML 文件（主要是 ppt/slides/slide{N}.xml 和相关文件）
关键：每次编辑后立即验证并修复任何验证错误，然后再继续：python ooxml/scripts/validate.py <dir> --original <file>
打包最终演示文稿：python ooxml/scripts/pack.py <input_directory> <office_file>

使用模板创建新的 PowerPoint 演示文稿

当你需要创建一个遵循现有模板设计的演示文稿时，你需要复制和重新排列模板幻灯片，然后替换占位符上下文。

工作流程

提取模板文本并创建视觉缩略图网格：
- 提取文本：python -m markitdown 模板.pptx > 模板内容.md
- 阅读 模板内容.md：完全阅读整个文件以了解模板演示文稿的内容。在阅读此文件时永远不要设置任何范围限制。
- 创建缩略图网格：python scripts/thumbnail.py 模板.pptx
- 参见创建缩略图网格部分以获取更多详细信息
分析模板并保存清单到文件：
- 视觉分析：查看缩略图网格以了解幻灯片布局、设计模式和视觉结构
- 创建并保存模板清单文件在 template-inventory.md 包含：
```
# 模板清单分析
**总幻灯片数：[count]**
**重要提示：幻灯片是 0 索引的（第一张幻灯片 = 0，最后一张幻灯片 = count-1）**

## [类别名称]
- 幻灯片 0：[布局代码（如果可用）] - 描述/用途
- 幻灯片 1：[布局代码] - 描述/用途
- 幻灯片 2：[布局代码] - 描述/用途
[... 必须逐个列出每张幻灯片及其索引 ...]
```
- 使用缩略图网格：参考视觉缩略图以识别：
  - 布局模式（标题幻灯片、内容布局、部分分隔符）
  - 图像占位符位置和计数
  - 幻灯片组之间的设计一致性
  - 视觉层次和结构
- 此清单文件是选择下一步中适当模板所必需的
基于模板清单创建演示文稿大纲：
- 回顾第 2 步中可用的模板。
- 选择一个介绍或标题模板作为第一张幻灯片。这应该是第一组模板之一。
- 选择安全的基于文本的布局用于其他幻灯片。
- 关键：将布局结构与实际内容匹配：
  - 单列布局：用于统一叙述或单一主题
  - 双列布局：仅当恰好有 2 个不同的项目/概念时使用
  - 三列布局：仅当恰好有 3 个不同的项目/概念时使用
  - 图像 + 文本布局：仅当有实际图像要插入时使用
  - 引用布局：仅用于实际引用（带归属），绝不用于强调
  - 永远不要使用比你拥有的内容更多的占位符的布局
  - 如果你有 2 个项目，不要强迫它们进入 3 列布局
  - 如果你有 4+ 项目，考虑分成多个幻灯片或使用列表格式
- 在选择布局之前计算你实际的内容片段数量
- 验证所选布局中的每个占位符都将被有意义的内容填充
- 选择一个代表每个内容部分最佳布局的选项。
- 保存 outline.md，内容和模板映射利用可用设计
- 示例模板映射：
```
# 要使用的模板幻灯片（0 基础索引）
# 警告：验证索引是否在范围内！有 73 张幻灯片的模板索引为 0-72
# 映射：大纲中的幻灯片编号 -> 模板幻灯片索引
template_mapping = [
    0,   # 使用幻灯片 0（标题/封面）
    34,  # 使用幻灯片 34（B1：标题和正文）
    34,  # 再次使用幻灯片 34（重复 B1）
    50,  # 使用幻灯片 50（E1：引用）
    54,  # 使用幻灯片 54（F2：结束 + 文本）
]
```
使用 rearrange.py 复制、重新排序和删除幻灯片：
- 使用 scripts/rearrange.py 脚本创建一个新演示文稿，幻灯片按所需顺序排列：
```
python scripts/rearrange.py 模板.pptx working.pptx 0,34,34,50,52
```
- 脚本处理重复幻灯片的复制，删除未使用的幻灯片，并自动重新排序
- 幻灯片索引是 0 基础的（第一张幻灯片是 0，第二张是 1 等）
- 同一个幻灯片索引可以多次出现以复制该幻灯片

使用 inventory.py 脚本提取所有文本：

运行清单提取：

python scripts/inventory.py working.pptx text-inventory.json

阅读 text-inventory.json：完全阅读整个 text-inventory.json 文件以了解所有形状及其属性。在阅读此文件时永远不要设置任何范围限制。

清单 JSON 结构：

  {
    "slide-0": {
      "shape-0": {
        "placeholder_type": "TITLE",  // 或者非占位符为 null
        "left": 1.5,                  // 位置以英寸为单位
        "top": 2.0,
        "width": 7.5,
        "height": 1.2,
        "paragraphs": [
          {
            "text": "段落文本",
            // 可选属性（仅当非默认值时包括）：
            "bullet": true,           // 检测到明确的项目符号
            "level": 0,               // 仅当项目符号为 true 时包括
            "alignment": "CENTER",    // CENTER, RIGHT（不是 LEFT）
            "space_before": 10.0,     // 段落前的空间以点为单位
            "space_after": 6.0,       // 段落后的空间以点为单位
            "line_spacing": 22.4,     // 行距以点为单位
            "font_name": "Arial",     // 来自第一次运行
            "font_size": 14.0,        // 以点为单位
            "bold": true,
            "italic": false,
            "underline": false,
            "color": "FF0000"         // RGB 颜色
          }
        ]
      }
    }
  }

关键特性：
- 幻灯片：命名为 “slide-0”, “slide-1” 等
- 形状：按视觉位置排序（从上到下，从左到右）为 “shape-0”, “shape-1” 等
- 占位符类型：TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, 或 null
- 默认字体大小：从布局占位符中提取的 default_font_size（当可用时）
- 幻灯片编号已过滤：具有 SLIDE_NUMBER 占位符类型的 SHAPES 自动从清单中排除
- 项目符号：当 bullet: true 时，level 总是包括（即使为 0）
- 间距：space_before, space_after, 和 line_spacing 以点为单位（仅当设置时包括）
- 颜色：color 为 RGB（例如，“FF0000”），theme_color 为主题颜色（例如，“DARK_1”）
- 属性：仅包括与默认值不同的属性

生成替换文本并保存数据到 JSON 文件 根据前一步的文本清单：
- 关键：首先验证哪些形状存在于清单中 - 仅引用实际存在的 SHAPES
- 验证：replace.py 脚本将验证替换 JSON 中的所有形状都存在于清单中
  - 如果你引用了一个不存在的形状，你将获得一个错误，显示可用的形状
  - 如果你引用了一个不存在的幻灯片，你将获得一个错误，指示幻灯片不存在
  - 所有验证错误都会在脚本退出前一次性显示
- 重要：replace.py 脚本在内部使用 inventory.py 来识别所有文本形状
- 自动清除：除非你为它们提供 “paragraphs”，否则清单中的所有文本形状都将被清除
- 为需要内容的形状添加一个 “paragraphs” 字段（不是 “replacement_paragraphs”）
- 在替换 JSON 中没有 “paragraphs” 的形状将自动清除其文本
- 带有项目符号的段落将自动左对齐。当 "bullet": true 时，不要在文本中设置 alignment 属性
- 为占位符文本生成适当的替换内容
- 使用形状大小来确定适当的内容长度
- 关键：包括原始清单中的段落属性 - 不要只提供文本
- 重要：当项目符号：true 时，不要在文本中包含项目符号（•，-，*） - 它们将自动添加
- 基本格式规则：
  - 标题/标题通常应该有 "bold": true
  - 列表项应该有 "bullet": true, "level": 0（当项目符号为 true 时，级别是必需的）
  - 保持任何对齐属性（例如，"alignment": "CENTER" 用于居中文本）
  - 包括与默认值不同的字体属性（例如，"font_size": 14.0, "font_name": "Lora"）
  - 颜色：使用 "color": "FF0000" 用于 RGB 或 "theme_color": "DARK_1" 用于主题颜色
  - 替换脚本需要 正确格式化的段落，不仅仅是文本字符串
  - 重叠形状：优先选择具有较大默认_font_size 或更合适 placeholder_type 的形状
- 将更新后的清单与替换保存到 replacement-text.json
- 警告：不同的模板布局具有不同数量的形状 - 在创建替换之前始终检查实际清单
示例段落字段显示正确的格式化：
```
"paragraphs": [
  {
    "text": "新演示文稿标题文本",
    "alignment": "CENTER",
    "bold": true
  },
  {
    "text": "部分标题",
    "bold": true
  },
  {
    "text": "没有项目符号的项目点不包含项目符号",
    "bullet": true,
    "level": 0
  },
  {
    "text": "红色文本",
    "color": "FF0000"
  },
  {
    "text": "主题颜色文本",
    "theme_color": "DARK_1"
  },
  {
    "text": "没有特殊格式的常规段落文本"
  }
]
```
未在替换 JSON 中列出的形状将自动清除：
```
{
  "slide-0": {
    "shape-0": {
      "paragraphs": [...] // 这个形状获得新文本
    }
    // shape-1 和 shape-2 从清单中将被自动清除
  }
}
```
演示文稿中常见的格式模式：
- 标题幻灯片：粗体文本，有时居中
- 幻灯片内的节标题：粗体文本
- 项目列表：每个项目需要 "bullet": true, "level": 0
- 正文：通常不需要特殊属性
- 引用：可能有特殊的对齐或字体属性

使用 replace.py 脚本应用替换

python scripts/replace.py working.pptx replacement-text.json output.pptx

该脚本将：

首先使用 inventory.py 中的函数提取所有文本形状的清单
验证替换 JSON 中的所有形状都存在于清单中
从清单中识别的所有形状中清除文本
仅将新文本应用到替换 JSON 中定义了 “paragraphs” 的形状
通过应用 JSON 中的段落属性来保留格式
自动处理项目符号、对齐、字体属性和颜色
保存更新后的演示文稿

示例验证错误：

错误：替换 JSON 中的形状无效：
  - 幻灯片 'slide-0' 上的形状 'shape-99' 未找到。可用的形状：shape-0, shape-1, shape-4
  - 清单中未找到幻灯片 'slide-999'

错误：替换文本使这些形状的溢出变得更糟：
  - slide-0/shape-2：溢出恶化了 1.25"（原来是 0.00"，现在是 1.25"）

创建缩略图网格

要为快速分析和参考创建 PowerPoint 幻灯片的视觉缩略图网格：

python scripts/thumbnail.py 模板.pptx [输出前缀]

特性：

创建：thumbnails.jpg（或 thumbnails-1.jpg, thumbnails-2.jpg 等，对于大型套牌）
默认：5 列，每网格最多 30 张幻灯片（5×6）
自定义前缀：python scripts/thumbnail.py 模板.pptx 我的网格
- 注意：输出前缀应包括路径，如果你想在特定目录中输出（例如，workspace/我的网格）
调整列数：--cols 4（范围：3-6，影响每网格的幻灯片数）
网格限制：3 列 = 每网格 12 张幻灯片，4 列 = 20，5 列 = 30，6 列 = 42
幻灯片是零索引的（幻灯片 0，幻灯片 1 等）

用例：

模板分析：快速了解幻灯片布局和设计模式
内容审查：整个演示文稿的视觉概览
导航参考：根据视觉外观找到特定幻灯片
质量检查：验证所有幻灯片都正确格式化

示例：

# 基本用法
python scripts/thumbnail.py 演示文稿.pptx

# 结合选项：自定义名称，列
python scripts/thumbnail.py 模板.pptx 分析 --cols 4

将幻灯片转换为图像

要视觉上分析 PowerPoint 幻灯片，请使用两步过程将它们转换为图像：

将 PPTX 转换为 PDF：

soffice --headless --convert-to pdf 模板.pptx

将 PDF 页面转换为 JPEG 图像：

pdftoppm -jpeg -r 150 模板.pdf 幻灯片

这将创建像 slide-1.jpg, slide-2.jpg 等文件。

选项：

-r 150：将分辨率设置为 150 DPI（根据质量/大小平衡进行调整）
-jpeg：输出 JPEG 格式（如果需要，可以使用 -png 输出 PNG）
-f N：要转换的第一页（例如，-f 2 从第 2 页开始）
-l N：要转换的最后一页（例如，-l 5 在第 5 页停止）
幻灯片：输出文件的前缀

特定范围的示例：

pdftoppm -jpeg -r 150 -f 2 -l 5 模板.pdf 幻灯片  # 仅转换第 2-5 页

代码风格指南

重要：在生成 PPTX 操作代码时：

编写简洁的代码
避免冗长的变量名和多余的操作
避免不必要的打印语句

依赖项

所需的依赖项（应该已经安装）：

markitdown：pip install "markitdown[pptx]"（用于从演示文稿中提取文本）
pptxgenjs：npm install -g pptxgenjs（通过 html2pptx 创建演示文稿）
playwright：npm install -g playwright（html2pptx 中的 HTML 渲染）
react-icons：npm install -g react-icons react react-dom（用于图标）
sharp：npm install -g sharp（用于 SVG 光栅化和图像处理）
LibreOffice：sudo apt-get install libreoffice（用于 PDF 转换）
Poppler：sudo apt-get install poppler-utils（用于 pdftoppm 将 PDF 转换为图像）
defusedxml：pip install defusedxml（用于安全的 XML 解析）