名称: pptx 描述: “演示文稿的创建、编辑和分析。当Claude需要处理演示文稿（.pptx文件）时，用于：(1) 创建新演示文稿，(2) 修改或编辑内容，(3) 处理布局，(4) 添加评论或演讲者笔记，或其他任何演示文稿任务” 许可: 专有。LICENSE.txt包含完整条款

PPTX创建、编辑和分析

概述

用户可能会要求您创建、编辑或分析.pptx文件的内容。.pptx文件本质上是一个ZIP存档，包含XML文件和其他资源，可以读取或编辑。针对不同任务，有不同的工具和工作流可用。

读取和分析内容

文本提取

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

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

原始XML访问

对于以下功能需要原始XML访问：评论、演讲者笔记、幻灯片布局、动画、设计元素和复杂格式化。对于任何这些功能，都需要解包演示文稿并读取其原始XML内容。

解包文件

python ooxml/scripts/unpack.py <office文件> <输出目录>

注意：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-20点），单色
双线边框，对比色
角括号而非完整框架
L形边框（顶部+左侧或底部+右侧）
标题下方的下划线强调（3-5点厚）

排版处理：

极端大小对比（72点标题 vs 11点正文）
全大写标题，宽字母间距
超大显示类型的编号部分
单空格字体（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（约500行）。在阅读此文件时切勿设置任何范围限制。 在任何演示文稿编辑前，阅读完整文件内容以获取OOXML结构和编辑工作流的详细指导。
解包演示文稿：python ooxml/scripts/unpack.py <office文件> <输出目录>
编辑XML文件（主要是ppt/slides/slide{N}.xml和相关文件）
关键：每次编辑后立即验证并在继续前修复任何验证错误：python ooxml/scripts/validate.py <目录> --original <文件>
打包最终演示文稿：python ooxml/scripts/pack.py <输入目录> <office文件>

创建新的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（点）（仅当设置时包括）
- 颜色：color表示RGB（如"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"）
  - 颜色：使用"color": "FF0000"表示RGB或"theme_color": "DARK_1"表示主题颜色
  - 替换脚本期望正确格式化的段落，而不仅仅是文本字符串
  - 重叠形状：优先选择具有较大default_font_size或更合适placeholder_type的形状
- 将替换后的更新清单保存到replacement-text.json
- 警告：不同模板布局有不同形状计数——在创建替换前始终检查实际清单
示例paragraphs字段显示正确格式化：
```
"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中的无效形状：
  - 形状'shape-99'在'slide-0'上未找到。可用形状：shape-0, shape-1, shape-4
  - 幻灯片'slide-999'在清单中未找到
```
```
错误: 替换文本使溢出在这些形状中更糟：
  - slide-0/shape-2: 溢出恶化1.25英寸（原0.00英寸，现1.25英寸）
```

创建缩略图网格

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

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

特征：

创建：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为索引（幻灯片 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页

代码风格指南

重要：生成PPPTX操作代码时：

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

依赖项

必需依赖项（应已安装）：

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解析）