pptx

Name: pptx
Author: rysweet

github.com/rysweet文档处理76419 次安装21 周前更新

代码仓库

关于 pptx

用于创建、编辑和分析 PowerPoint 文件的技能，涵盖文本提取、OOXML 检查、模板处理及 HTML 转幻灯片工作流。

主要功能

01将演示文稿文本提取为 Markdown
02检查并编辑原始 OOXML
03从 HTML 创建幻灯片
04使用现有模板制作演示文稿
05验证并预览幻灯片布局

适用场景

01提取 .pptx 文件中的文本
02检查演讲者备注或幻灯片评论
03从头创建演示文稿
04将内容套用到现有模板

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rysweet/amplihack --skill pptx

安装后在 Claude Code 中输入/pptx确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

DEPENDENCIES.md

README.md

examples/

example_usage.md

scripts/

html2pptx.js

inventory.py

rearrange.py

replace.py

thumbnail.py

tests/

test_pptx_skill.py

详细介绍

PPTX 创建、编辑和分析

概述

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

读取和分析内容

文本提取

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

# Convert document to markdown
python -m markitdown path-to-file.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（约 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，包含：
```
# 模板清单分析

**幻灯片总数：[count]**
**重要：幻灯片以 0 为起始索引（第一张幻灯片 = 0，最后一张幻灯片 = count-1）**
## [类别名称]

- 幻灯片 0：[布局代码（如有）] - 描述/用途
- 幻灯片 1：[布局代码] - 描述/用途
- 幻灯片 2：[布局代码] - 描述/用途
  [... 每一张幻灯片都必须按其索引单独列出 ...]
```
- 使用缩略图网格：参考可视化缩略图以识别：
  - 布局模式（标题幻灯片、内容布局、章节分隔页）
  - 图片占位符的位置和数量
  - 各幻灯片组之间的设计一致性
  - 视觉层级和结构
- 此清单文件是下一步选择合适模板的必需文件
根据模板清单创建演示文稿大纲：
- 查看第 2 步中获得的可用模板。
- 为第一张幻灯片选择一个引言或标题模板。这应当是排在最前面的模板之一。
- 为其他幻灯片选择稳妥的、基于文本的布局。
- 关键：将布局结构与实际内容相匹配：
  - 单栏布局：用于统一的叙述或单一主题
  - 双栏布局：仅当恰好有 2 个不同的条目/概念时使用
  - 三栏布局：仅当恰好有 3 个不同的条目/概念时使用
  - 图片 + 文本布局：仅当有实际图片需要插入时使用
  - 引语布局：仅用于人物的真实引语（附出处），绝不用于强调
  - 切勿使用占位符多于内容的布局
  - 如果有 2 个条目，不要强行套入三栏布局
  - 如果有 4 个或更多条目，考虑拆分为多张幻灯片或使用列表格式
- 在选择布局之前，先清点实际的内容块数量
- 确认所选布局中的每个占位符都将填入有意义的内容
- 为每个内容部分选择一个代表最佳布局的选项。
- 保存 outline.md，其中包含内容以及利用可用设计的模板映射
- 模板映射示例：
```
# Template slides to use (0-based indexing)
# WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
# Mapping: slide numbers from outline -> template slide indices
template_mapping = [
    0,   # Use slide 0 (Title/Cover)
    34,  # Use slide 34 (B1: Title and body)
    34,  # Use slide 34 again (duplicate for second B1)
    50,  # Use slide 50 (E1: Quote)
    54,  # Use slide 54 (F2: Closing + Text)
]
```
使用 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": "Paragraph 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", // 取自首个 run
          "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"）
  - 颜色：RGB 使用 "color": "FF0000"，主题颜色使用 "theme_color": "DARK_1"
  - 替换脚本期望的是格式正确的段落，而不仅仅是文本字符串
  - 重叠形状：优先选择 default_font_size 更大或 placeholder_type 更合适的形状
- 将带有替换内容的更新后清单保存到 replacement-text.json
- 警告：不同的模板布局具有不同的形状数量——在创建替换内容前务必检查实际清单
示例 paragraphs 字段展示正确的格式：
```
"paragraphs": [
  {
    "text": "New presentation title text",
    "alignment": "CENTER",
    "bold": true
  },
  {
    "text": "Section Header",
    "bold": true
  },
  {
    "text": "First bullet point without bullet symbol",
    "bullet": true,
    "level": 0
  },
  {
    "text": "Red colored text",
    "color": "FF0000"
  },
  {
    "text": "Theme colored text",
    "theme_color": "DARK_1"
  },
  {
    "text": "Regular paragraph text without special formatting"
  }
]
```
未在替换 JSON 中列出的形状会被自动清空：
```
{
  "slide-0": {
    "shape-0": {
      "paragraphs": [...] // This shape gets new text
    }
    // shape-1 and shape-2 from inventory will be cleared automatically
  }
}
```
演示文稿的常见格式模式：
- 标题幻灯片：粗体文本，有时居中
- 幻灯片内的章节标题：粗体文本
- 项目符号列表：每个项需要 "bullet": true, "level": 0
- 正文文本：通常不需要特殊属性
- 引用：可能有特殊的对齐或字体属性
使用 replace.py 脚本应用替换
```
python scripts/replace.py working.pptx replacement-text.json output.pptx
```
该脚本将：
- 首先使用 inventory.py 中的函数提取所有文本形状的清单
- 校验替换 JSON 中的所有形状都存在于清单中
- 清空清单中识别出的所有形状的文本
- 仅将新文本应用到替换 JSON 中定义了 "paragraphs" 的形状
- 通过应用 JSON 中的段落属性来保留格式
- 自动处理项目符号、对齐、字体属性和颜色
- 保存更新后的演示文稿
示例校验错误：
```
ERROR: Invalid shapes in replacement JSON:
  - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
  - Slide 'slide-999' not found in inventory
```
```
ERROR: Replacement text made overflow worse in these shapes:
  - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 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
幻灯片从零开始编号（Slide 0、Slide 1 等）

使用场景：

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

示例：

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
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  # Converts only pages 2-5

代码风格指南

IMPORTANT：为 PPTX 操作生成代码时：

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

依赖项

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

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

支持 Markdown

登录后评论

基本信息

作者: rysweet
仓库: rysweet/amplihack
分类: 文档处理
安装次数: 419
GitHub Stars: 76

报告问题