name: pptx description: “演示文稿工具包 (.pptx)。用于程序化创建、编辑幻灯片、布局、内容、演讲者笔记、评论，实现演示文稿的自动化创建和修改。” license: 专有。LICENSE.txt 包含完整条款

PPTX 创建、编辑和分析

概述

.pptx 文件是一个包含 XML 文件和资源的 ZIP 归档。使用文本提取、原始 XML 访问或 html2pptx 工作流来创建、编辑或分析 PowerPoint 演示文稿。此技能适用于程序化演示文稿创建和修改。

使用科学示意图增强视觉效果

使用此技能创建文档时，始终考虑添加科学图表和示意图以增强视觉传达。

如果文档未包含示意图或图表：

使用 scientific-schematics 技能生成 AI 驱动的出版物质量图表
只需用自然语言描述所需图表
Nano Banana Pro 将自动生成、审查和优化示意图

对于新文档： 默认应生成科学示意图，以视觉方式呈现文本中描述的关键概念、工作流、架构或关系。

如何生成示意图：

python scripts/generate_schematic.py "你的图表描述" -o figures/output.png

AI 将自动：

创建出版物质量的图像，格式正确
通过多次迭代审查和优化
确保可访问性（色盲友好、高对比度）
将输出保存到 figures/ 目录

何时添加示意图：

幻灯片的工作流程图表
幻灯片设计过程流程图
内容组织图表
系统架构插图
过程流程可视化
任何受益于可视化的复杂概念

有关创建示意图的详细指南，请参阅 scientific-schematics 技能文档。

读取和分析内容

文本提取

要读取演示文稿的文本内容，将文档转换为 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% 的纯色块
渐变填充（仅垂直或对角）
分割背景（两种颜色，对角或垂直）
边到边颜色带
负空间作为设计元素

布局技巧

对于包含图表或表格的幻灯片：

双列布局（首选）：使用全宽标题，然后下方两列 - 一列放文本/项目符号，另一列放特色内容。这提供更好的平衡并提高图表/表格的可读性。使用不等宽列（如 40%/60% 分割）的 flexbox 以优化每类内容的空间。
全幻灯片布局：让特色内容（图表/表格）占据整个幻灯片以最大化影响和可读性
切勿垂直堆叠：不要在单列中将图表/表格置于文本下方 - 这导致可读性差和布局问题

工作流程

强制 - 完整阅读文件：完整从头到尾阅读 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（约 500 行）。切勿设置任何范围限制。 在任何演示文稿编辑前，阅读完整文件内容以获取 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 template.pptx > template-content.md
- 阅读 template-content.md：完整阅读文件以了解模板演示文稿的内容。切勿设置任何范围限制。
- 创建缩略图网格：python scripts/thumbnail.py template.pptx
- 更多详情见创建缩略图网格部分
分析模板并将库存保存到文件：
- 视觉分析：审查缩略图网格以了解幻灯片布局、设计模式和视觉结构
- 在 template-inventory.md 创建并保存模板库存文件：
```
# 模板库存分析
**总幻灯片数：[计数]**
**重要：幻灯片为 0 索引（第一张幻灯片 = 0，最后一张 = 计数-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 template.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,               // 仅当 bullet 为 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 占位符类型的形状自动从库存中排除
- 项目符号：当 bullet: true 时，level 总是包括（即使为 0）
- 间距：space_before、space_after 和 line_spacing（点）（仅当设置时包括）
- 颜色：RGB 用 color（如 “FF0000”），主题颜色用 theme_color（如 “DARK_1”）
- 属性：输出中仅包括非默认值

生成替换文本并将数据保存到 JSON 文件 基于上一步的文本库存：
- 关键：首先验证库存中存在哪些形状 - 仅引用实际存在的形状
- 验证：replace.py 脚本将验证替换 JSON 中的所有形状存在于库存中
  - 如果引用不存在的形状，错误将显示可用形状
  - 如果引用不存在的幻灯片，错误将指示幻灯片不存在
  - 所有验证错误在脚本退出前一次性显示
- 重要：replace.py 脚本内部使用 inventory.py 识别所有文本形状
- 自动清除：所有库存中的文本形状将被清除，除非提供 “paragraphs”
- 向需要内容的形状添加 “paragraphs” 字段（非 “replacement_paragraphs”）
- 替换 JSON 中没有 “paragraphs” 的形状将自动清除其文本
- 带有项目符号的段落将自动左对齐。当 "bullet": true 时，勿设置 alignment 属性
- 为占位符文本生成适当的替换内容
- 使用形状大小确定适当内容长度
- 关键：包括原始库存中的段落属性 - 勿仅提供文本
- 重要：当 bullet: true 时，勿在文本中包含项目符号（•, -, *） - 自动添加
- 基本格式规则：
  - 标题/标题通常应有 "bold": true
  - 列表项应有 "bullet": true, "level": 0（当 bullet 为 true 时，level 必需）
  - 保留任何对齐属性（如 "alignment": "CENTER" 用于居中文本）
  - 当不同于默认时包括字体属性（如 "font_size": 14.0、"font_name": "Lora"）
  - 颜色：RGB 用 "color": "FF0000"，主题颜色用 "theme_color": "DARK_1"
  - 替换脚本期望正确格式化的段落，而非仅文本字符串
  - 重叠形状：优先选择 default_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 中的段落属性保留格式
- 自动处理项目符号、对齐、字体属性和颜色
- 保存更新的演示文稿
示例验证错误：
```
ERROR: 替换 JSON 中的无效形状：
  - 形状 'shape-99' 在 'slide-0' 中未找到。可用形状：shape-0, shape-1, shape-4
  - 幻灯片 'slide-999' 在库存中未找到
```
```
ERROR: 替换文本使溢出在以下形状中更糟：
  - slide-0/shape-2: 溢出恶化了 1.25"（原为 0.00"，现为 1.25"）
```

创建缩略图网格

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

python scripts/thumbnail.py template.pptx [output_prefix]

功能：

创建：thumbnails.jpg（或大文件为 thumbnails-1.jpg、thumbnails-2.jpg 等）
默认：5 列，每网格最多 30 张幻灯片（5×6）
自定义前缀：python scripts/thumbnail.py template.pptx my-grid
- 注意：如果要在特定目录输出，输出前缀应包括路径（如 workspace/my-grid）
调整列数：--cols 4（范围：3-6，影响每网格幻灯片数）
网格限制：3 列 = 12 幻灯片/网格，4 列 = 20，5 列 = 30，6 列 = 42
幻灯片为零索引（幻灯片 0、幻灯片 1 等）

用例：

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

示例：

# 基本用法
python scripts/thumbnail.py presentation.pptx

# 组合选项：自定义名称、列数
python scripts/thumbnail.py template.pptx analysis --cols 4

将幻灯片转换为图像

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

将 PPTX 转换为 PDF：

soffice --headless --convert-to pdf template.pptx

将 PDF 页面转换为 JPEG 图像：
```
pdftoppm -jpeg -r 150 template.pdf slide
```
创建文件如 slide-1.jpg、slide-2.jpg 等。

选项：

-r 150：设置分辨率为 150 DPI（调整质量/大小平衡）
-jpeg：输出 JPEG 格式（如偏好 PNG，用 -png）
-f N：要转换的起始页（如 -f 2 从第 2 页开始）
-l N：要转换的结束页（如 -l 5 到第 5 页）
slide：输出文件前缀

特定范围示例：

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # 仅转换第 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 解析）