pptx-official
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePPTX creation, editing, and analysis
PPTX演示文稿的创建、编辑与分析
Overview
概述
A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
用户可能会要求您创建、编辑或分析.pptx文件的内容。.pptx文件本质上是一个包含XML文件和其他资源的ZIP压缩包,您可以对其进行读取或编辑。针对不同的任务,您可以使用不同的工具和工作流。
Reading and analyzing content
内容读取与分析
Text extraction
文本提取
If you just need to read the text contents of a presentation, you should convert the document to markdown:
bash
undefined如果您只需读取演示文稿的文本内容,应将文档转换为markdown格式:
bash
undefinedConvert document to markdown
将文档转换为markdown
python -m markitdown path-to-file.pptx
undefinedpython -m markitdown path-to-file.pptx
undefinedRaw XML access
原始XML访问
You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.
如需处理以下内容,您需要访问原始XML:批注、演讲者备注、幻灯片布局、动画、设计元素以及复杂格式。针对这些功能,您需要解压演示文稿并读取其原始XML内容。
Unpacking a file
解压文件
python ooxml/scripts/unpack.py <office_file> <output_dir>Note: The unpack.py script is located at relative to the project root. If the script doesn't exist at this path, use to locate it.
skills/pptx/ooxml/scripts/unpack.pyfind . -name "unpack.py"python ooxml/scripts/unpack.py <office_file> <output_dir>注意:unpack.py脚本位于项目根目录下的路径。如果该脚本不在此路径,请使用命令查找。
skills/pptx/ooxml/scripts/unpack.pyfind . -name "unpack.py"Key file structures
关键文件结构
- - Main presentation metadata and slide references
ppt/presentation.xml - - Individual slide contents (slide1.xml, slide2.xml, etc.)
ppt/slides/slide{N}.xml - - Speaker notes for each slide
ppt/notesSlides/notesSlide{N}.xml - - Comments for specific slides
ppt/comments/modernComment_*.xml - - Layout templates for slides
ppt/slideLayouts/ - - Master slide templates
ppt/slideMasters/ - - Theme and styling information
ppt/theme/ - - Images and other media files
ppt/media/
- - 演示文稿主元数据和幻灯片引用
ppt/presentation.xml - - 单个幻灯片内容(如slide1.xml、slide2.xml等)
ppt/slides/slide{N}.xml - - 每张幻灯片的演讲者备注
ppt/notesSlides/notesSlide{N}.xml - - 特定幻灯片的批注
ppt/comments/modernComment_*.xml - - 幻灯片布局模板
ppt/slideLayouts/ - - 幻灯片母版模板
ppt/slideMasters/ - - 主题和样式信息
ppt/theme/ - - 图片和其他媒体文件
ppt/media/
Typography and color extraction
排版与颜色提取
When given an example design to emulate: Always analyze the presentation's typography and colors first using the methods below:
- Read theme file: Check for colors (
ppt/theme/theme1.xml) and fonts (<a:clrScheme>)<a:fontScheme> - Sample slide content: Examine for actual font usage (
ppt/slides/slide1.xml) and colors<a:rPr> - Search for patterns: Use grep to find color (,
<a:solidFill>) and font references across all XML files<a:srgbClr>
当需要模仿示例设计时:务必先通过以下方法分析演示文稿的排版和颜色:
- 读取主题文件:查看中的颜色(
ppt/theme/theme1.xml)和字体(<a:clrScheme>)<a:fontScheme> - 采样幻灯片内容:检查中的实际字体使用(
ppt/slides/slide1.xml)和颜色<a:rPr> - 搜索模式:使用grep命令在所有XML文件中查找颜色(、
<a:solidFill>)和字体引用<a:srgbClr>
Creating a new PowerPoint presentation without a template
无模板创建新PowerPoint演示文稿
When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.
从零开始创建新PowerPoint演示文稿时,请使用html2pptx工作流将HTML幻灯片转换为PowerPoint,确保定位准确。
Design Principles
设计原则
CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:
- Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
- Check for branding: If the user mentions a company/organization, consider their brand colors and identity
- Match palette to content: Select colors that reflect the subject
- State your approach: Explain your design choices before writing code
Requirements:
- ✅ State your content-informed design approach BEFORE writing code
- ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
- ✅ Create clear visual hierarchy through size, weight, and color
- ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
- ✅ Be consistent: repeat patterns, spacing, and visual language across slides
至关重要:在创建任何演示文稿之前,请分析内容并选择合适的设计元素:
- 考虑主题内容:该演示文稿的主题是什么?它暗示了何种基调、行业或氛围?
- 检查品牌标识:如果用户提及公司/组织,请考虑其品牌颜色和形象
- 配色与内容匹配:选择能体现主题的颜色
- 说明设计思路:在编写代码之前,先解释您的设计选择
要求:
- ✅ 在编写代码之前,务必说明基于内容的设计思路
- ✅ 仅使用网页安全字体:Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
- ✅ 通过字号、字重和颜色建立清晰的视觉层次
- ✅ 确保可读性:高对比度、合适的字号、整洁的对齐方式
- ✅ 保持一致性:在所有幻灯片中重复使用相同的模式、间距和视觉语言
Color Palette Selection
配色方案选择
Choosing colors creatively:
- Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
- Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
- Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
- Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
- Ensure contrast: Text must be clearly readable on backgrounds
Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):
- Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
- Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
- Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
- Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
- Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
- Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
- Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
- Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
- Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
- Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
- Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
- Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
- Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
- Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
- Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
- Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
- Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
- Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)
创意选色:
- 超越默认选项:哪些颜色真正匹配该特定主题?避免机械选择。
- 多角度考虑:主题、行业、氛围、活力水平、目标受众、品牌标识(如有提及)
- 大胆尝试:尝试意想不到的组合——医疗行业演示文稿不一定必须用绿色,金融行业不一定必须用深蓝色
- 构建配色方案:选择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)
Visual Details Options
视觉细节选项
Geometric Patterns:
- Diagonal section dividers instead of horizontal
- Asymmetric column widths (30/70, 40/60, 25/75)
- Rotated text headers at 90° or 270°
- Circular/hexagonal frames for images
- Triangular accent shapes in corners
- Overlapping shapes for depth
Border & Frame Treatments:
- Thick single-color borders (10-20pt) on one side only
- Double-line borders with contrasting colors
- Corner brackets instead of full frames
- L-shaped borders (top+left or bottom+right)
- Underline accents beneath headers (3-5pt thick)
Typography Treatments:
- Extreme size contrast (72pt headlines vs 11pt body)
- All-caps headers with wide letter spacing
- Numbered sections in oversized display type
- Monospace (Courier New) for data/stats/technical content
- Condensed fonts (Arial Narrow) for dense information
- Outlined text for emphasis
Chart & Data Styling:
- Monochrome charts with single accent color for key data
- Horizontal bar charts instead of vertical
- Dot plots instead of bar charts
- Minimal gridlines or none at all
- Data labels directly on elements (no legends)
- Oversized numbers for key metrics
Layout Innovations:
- Full-bleed images with text overlays
- Sidebar column (20-30% width) for navigation/context
- Modular grid systems (3×3, 4×4 blocks)
- Z-pattern or F-pattern content flow
- Floating text boxes over colored shapes
- Magazine-style multi-column layouts
Background Treatments:
- Solid color blocks occupying 40-60% of slide
- Gradient fills (vertical or diagonal only)
- Split backgrounds (two colors, diagonal or vertical)
- Edge-to-edge color bands
- Negative space as a design element
几何图案:
- 用对角分隔线替代水平分隔线
- 不对称列宽(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%
- 渐变填充(仅垂直或对角)
- 分割背景(两种颜色,对角或垂直)
- 边缘到边缘的色带
- 将负空间作为设计元素
Layout Tips
布局技巧
When creating slides with charts or tables:
- Two-column layout (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
- Full-slide layout: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
- NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues
创建包含图表或表格的幻灯片时:
- 首选两栏布局: 使用跨整个宽度的标题,下方分为两栏——一栏放置文本/项目符号,另一栏放置特色内容。这种布局平衡性更好,能提升图表/表格的可读性。使用flexbox设置不等宽列(如40%/60%分割),为每种内容类型优化空间。
- 全屏布局: 让特色内容(图表/表格)占据整个幻灯片,以获得最大视觉冲击力和可读性
- 绝对不要垂直堆叠: 不要在单列中将图表/表格放在文本下方——这会导致可读性差和布局问题
Workflow
工作流
- MANDATORY - READ ENTIRE FILE: Read completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
html2pptx.md - Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
- Use ,
<p>-<h1>,<h6>,<ul>for all text content<ol> - Use for areas where charts/tables will be added (render with gray background for visibility)
class="placeholder" - CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
- LAYOUT: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
- Use
- Create and run a JavaScript file using the library to convert HTML slides to PowerPoint and save the presentation
html2pptx.js- Use the function to process each HTML file
html2pptx() - Add charts and tables to placeholder areas using PptxGenJS API
- Save the presentation using
pptx.writeFile()
- Use the
- Visual validation: Generate thumbnails and inspect for layout issues
- Create thumbnail grid:
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4 - Read and carefully examine the thumbnail image for:
- Text cutoff: Text being cut off by header bars, shapes, or slide edges
- Text overlap: Text overlapping with other text or shapes
- Positioning issues: Content too close to slide boundaries or other elements
- Contrast issues: Insufficient contrast between text and backgrounds
- If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
- Repeat until all slides are visually correct
- Create thumbnail grid:
- 必须完成 - 阅读整个文件: 完整阅读从开头到结尾。阅读此文件时绝对不要设置任何范围限制。在开始创建演示文稿之前,请阅读完整文件内容,了解详细语法、关键格式规则和最佳实践。
html2pptx.md - 为每张幻灯片创建一个HTML文件,设置正确尺寸(例如16:9比例为720pt × 405pt)
- 使用、
<p>-<h1>、<h6>、<ul>标记所有文本内容<ol> - 为将添加图表/表格的区域使用(渲染为灰色背景以便识别)
class="placeholder" - 至关重要: 先使用Sharp将渐变和图标栅格化为PNG图片,再在HTML中引用
- 布局: 对于包含图表/表格/图片的幻灯片,使用全屏布局或两栏布局以提升可读性
- 使用
- 使用库创建并运行JavaScript文件,将HTML幻灯片转换为PowerPoint并保存演示文稿
html2pptx.js- 使用函数处理每个HTML文件
html2pptx() - 使用PptxGenJS API将图表和表格添加到占位符区域
- 使用保存演示文稿
pptx.writeFile()
- 使用
- 视觉验证: 生成缩略图并检查布局问题
- 创建缩略图网格:
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4 - 读取并仔细检查缩略图,查看以下问题:
- 文本截断: 文本被标题栏、形状或幻灯片边缘截断
- 文本重叠: 文本与其他文本或形状重叠
- 定位问题: 内容过于靠近幻灯片边界或其他元素
- 对比度问题: 文本与背景之间对比度不足
- 如果发现问题,调整HTML的边距/间距/颜色,重新生成演示文稿
- 重复此过程,直到所有幻灯片视觉效果正确
- 创建缩略图网格:
Editing an existing PowerPoint presentation
编辑现有PowerPoint演示文稿
When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.
编辑现有PowerPoint演示文稿的幻灯片时,您需要处理原始Office Open XML(OOXML)格式。这包括解压.pptx文件、编辑XML内容,然后重新打包。
Workflow
工作流
- MANDATORY - READ ENTIRE FILE: Read (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
ooxml.md - Unpack the presentation:
python ooxml/scripts/unpack.py <office_file> <output_dir> - Edit the XML files (primarily and related files)
ppt/slides/slide{N}.xml - CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding:
python ooxml/scripts/validate.py <dir> --original <file> - Pack the final presentation:
python ooxml/scripts/pack.py <input_directory> <office_file>
- 必须完成 - 阅读整个文件: 完整阅读(约500行)从开头到结尾。阅读此文件时绝对不要设置任何范围限制。在开始编辑演示文稿之前,请阅读完整文件内容,了解OOXML结构和编辑工作流的详细指南。
ooxml.md - 解压演示文稿:
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>
Creating a new PowerPoint presentation using a template
使用模板创建新PowerPoint演示文稿
When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.
当您需要按照现有模板的设计创建演示文稿时,您需要先复制和重新排列模板幻灯片,然后替换占位符内容。
Workflow
工作流
-
Extract template text AND create visual thumbnail grid:
- Extract text:
python -m markitdown template.pptx > template-content.md - Read : Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
template-content.md - Create thumbnail grids:
python scripts/thumbnail.py template.pptx - See Creating Thumbnail Grids section for more details
- Extract text:
-
Analyze template and save inventory to a file:
- Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
- Create and save a template inventory file at containing:
template-inventory.mdmarkdown# Template Inventory Analysis **Total Slides: [count]** **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)** ## [Category Name] - Slide 0: [Layout code if available] - Description/purpose - Slide 1: [Layout code] - Description/purpose - Slide 2: [Layout code] - Description/purpose [... EVERY slide must be listed individually with its index ...] - Using the thumbnail grid: Reference the visual thumbnails to identify:
- Layout patterns (title slides, content layouts, section dividers)
- Image placeholder locations and counts
- Design consistency across slide groups
- Visual hierarchy and structure
- This inventory file is REQUIRED for selecting appropriate templates in the next step
-
Create presentation outline based on template inventory:
- Review available templates from step 2.
- Choose an intro or title template for the first slide. This should be one of the first templates.
- Choose safe, text-based layouts for the other slides.
- CRITICAL: Match layout structure to actual content:
- Single-column layouts: Use for unified narrative or single topic
- Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
- Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
- Image + text layouts: Use ONLY when you have actual images to insert
- Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
- Never use layouts with more placeholders than you have content
- If you have 2 items, don't force them into a 3-column layout
- If you have 4+ items, consider breaking into multiple slides or using a list format
- Count your actual content pieces BEFORE selecting the layout
- Verify each placeholder in the chosen layout will be filled with meaningful content
- Select one option representing the best layout for each content section.
- Save with content AND template mapping that leverages available designs
outline.md - Example template mapping:
# 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) ]
-
Duplicate, reorder, and delete slides using:
rearrange.py- Use the script to create a new presentation with slides in the desired order:
scripts/rearrange.pybashpython scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52 - The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
- Slide indices are 0-based (first slide is 0, second is 1, etc.)
- The same slide index can appear multiple times to duplicate that slide
- Use the
-
Extract ALL text using thescript:
inventory.py-
Run inventory extraction:bash
python scripts/inventory.py working.pptx text-inventory.json -
Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. NEVER set any range limits when reading this file.
-
The inventory JSON structure:json
{ "slide-0": { "shape-0": { "placeholder_type": "TITLE", // or null for non-placeholders "left": 1.5, // position in inches "top": 2.0, "width": 7.5, "height": 1.2, "paragraphs": [ { "text": "Paragraph text", // Optional properties (only included when non-default): "bullet": true, // explicit bullet detected "level": 0, // only included when bullet is true "alignment": "CENTER", // CENTER, RIGHT (not LEFT) "space_before": 10.0, // space before paragraph in points "space_after": 6.0, // space after paragraph in points "line_spacing": 22.4, // line spacing in points "font_name": "Arial", // from first run "font_size": 14.0, // in points "bold": true, "italic": false, "underline": false, "color": "FF0000" // RGB color } ] } } } -
Key features:
- Slides: Named as "slide-0", "slide-1", etc.
- Shapes: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
- Placeholder types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
- Default font size: in points extracted from layout placeholders (when available)
default_font_size - Slide numbers are filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
- Bullets: When ,
bullet: trueis always included (even if 0)level - Spacing: ,
space_before, andspace_afterin points (only included when set)line_spacing - Colors: for RGB (e.g., "FF0000"),
colorfor theme colors (e.g., "DARK_1")theme_color - Properties: Only non-default values are included in the output
-
-
Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:
- CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
- VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
- If you reference a non-existent shape, you'll get an error showing available shapes
- If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
- All validation errors are shown at once before the script exits
- IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
- AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
- Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
- Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
- Paragraphs with bullets will be automatically left aligned. Don't set the property on when
alignment"bullet": true - Generate appropriate replacement content for placeholder text
- Use shape size to determine appropriate content length
- CRITICAL: Include paragraph properties from the original inventory - don't just provide text
- IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
- ESSENTIAL FORMATTING RULES:
- Headers/titles should typically have
"bold": true - List items should have (level is required when bullet is true)
"bullet": true, "level": 0 - Preserve any alignment properties (e.g., for centered text)
"alignment": "CENTER" - Include font properties when different from default (e.g., ,
"font_size": 14.0)"font_name": "Lora" - Colors: Use for RGB or
"color": "FF0000"for theme colors"theme_color": "DARK_1" - The replacement script expects properly formatted paragraphs, not just text strings
- Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
- Headers/titles should typically have
- Save the updated inventory with replacements to
replacement-text.json - WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements
Example paragraphs field showing proper formatting:json"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" } ]Shapes not listed in the replacement JSON are automatically cleared:json{ "slide-0": { "shape-0": { "paragraphs": [...] // This shape gets new text } // shape-1 and shape-2 from inventory will be cleared automatically } }Common formatting patterns for presentations:- Title slides: Bold text, sometimes centered
- Section headers within slides: Bold text
- Bullet lists: Each item needs
"bullet": true, "level": 0 - Body text: Usually no special properties needed
- Quotes: May have special alignment or font properties
-
Apply replacements using thescript
replace.pybashpython scripts/replace.py working.pptx replacement-text.json output.pptxThe script will:- First extract the inventory of ALL text shapes using functions from inventory.py
- Validate that all shapes in the replacement JSON exist in the inventory
- Clear text from ALL shapes identified in the inventory
- Apply new text only to shapes with "paragraphs" defined in the replacement JSON
- Preserve formatting by applying paragraph properties from the JSON
- Handle bullets, alignment, font properties, and colors automatically
- Save the updated presentation
Example validation errors: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 inventoryERROR: Replacement text made overflow worse in these shapes: - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
-
提取模板文本并创建视觉缩略图网格:
- 提取文本:
python -m markitdown template.pptx > template-content.md - 阅读:完整阅读文件内容,了解模板演示文稿的内容。阅读此文件时绝对不要设置任何范围限制。
template-content.md - 创建缩略图网格:
python scripts/thumbnail.py template.pptx - 有关更多详细信息,请参阅创建缩略图网格部分
- 提取文本:
-
分析模板并将清单保存到文件:
- 视觉分析: 查看缩略图网格,了解幻灯片布局、设计模式和视觉结构
- 创建并保存模板清单文件,内容如下:
template-inventory.mdmarkdown# 模板清单分析 **总幻灯片数: [数量]** **重要提示:幻灯片采用0索引(第一张幻灯片=0,最后一张幻灯片=数量-1)** ## [分类名称] - Slide 0: [布局代码(如有)] - 描述/用途 - Slide 1: [布局代码] - 描述/用途 - Slide 2: [布局代码] - 描述/用途 [... 必须逐个列出每张幻灯片及其索引 ...] - 使用缩略图网格: 参考视觉缩略图识别:
- 布局模式(标题幻灯片、内容布局、节分隔符)
- 图片占位符的位置和数量
- 幻灯片组之间的设计一致性
- 视觉层次和结构
- 此清单文件是下一步选择合适模板的必要条件
-
基于模板清单创建演示文稿大纲:
- 查看步骤2中的可用模板。
- 为第一张幻灯片选择介绍或标题模板。应选择前几个模板之一。
- 为其他幻灯片选择安全的、基于文本的布局。
- 至关重要:布局结构必须与实际内容匹配:
- 单列布局:用于统一叙事或单一主题
- 两栏布局:仅当您有恰好2个不同的项目/概念时使用
- 三栏布局:仅当您有恰好3个不同的项目/概念时使用
- 图片+文本布局:仅当您有实际图片要插入时使用
- 引用布局:仅用于实际的名人名言(需注明出处),绝不用于强调
- 不要使用占位符数量多于您内容数量的布局
- 如果您有2个项目,不要强行放入三栏布局
- 如果您有4个以上项目,考虑拆分为多张幻灯片或使用列表格式
- 在选择布局之前,先统计您的实际内容数量
- 验证所选布局中的每个占位符都将填充有意义的内容
- 为每个内容部分选择一个代表最佳布局的选项。
- 保存包含内容和模板映射的,利用现有设计
outline.md - 模板映射示例:
# 要使用的模板幻灯片(0索引) # 警告:验证索引是否在范围内!包含73张幻灯片的模板索引为0-72 # 映射:大纲中的幻灯片编号 -> 模板幻灯片索引 template_mapping = [ 0, # 使用Slide 0(标题/封面) 34, # 使用Slide 34(B1: 标题与正文) 34, # 再次使用Slide 34(复制以创建第二个B1幻灯片) 50, # 使用Slide 50(E1: 引用) 54, # 使用Slide 54(F2: 结尾+文本) ]
-
使用复制、重新排序和删除幻灯片:
rearrange.py- 使用脚本创建包含所需顺序幻灯片的新演示文稿:
scripts/rearrange.pybashpython scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52 - 该脚本会自动处理重复幻灯片、删除未使用的幻灯片和重新排序
- 幻灯片索引采用0索引(第一张幻灯片是0,第二张是1,依此类推)
- 同一幻灯片索引可以多次出现,以复制该幻灯片
- 使用
-
使用脚本提取所有文本:
inventory.py-
运行清单提取:bash
python scripts/inventory.py working.pptx text-inventory.json -
阅读text-inventory.json:完整阅读text-inventory.json文件,了解所有形状及其属性。阅读此文件时绝对不要设置任何范围限制。
-
清单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", // 来自第一个文本块 "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(即使为0)level - 间距:、
space_before和space_after以磅为单位(仅在设置时包含)line_spacing - 颜色:RGB颜色使用(例如"FF0000"),主题颜色使用
color(例如"DARK_1")theme_color - 属性:仅包含非默认值
-
-
生成替换文本并保存到JSON文件 基于上一步的文本清单:
- 至关重要:首先验证清单中存在哪些形状——仅引用实际存在的形状
- 验证:replace.py脚本将验证替换JSON中的所有形状是否存在于清单中
- 如果您引用了不存在的形状,将显示错误并列出可用形状
- 如果您引用了不存在的幻灯片,将显示错误指出该幻灯片不存在
- 所有验证错误会一次性显示,然后脚本退出
- 重要提示:replace.py脚本内部使用inventory.py来识别所有文本形状
- 自动清除:清单中的所有文本形状将被清除,除非您为其提供"paragraphs"
- 为需要填充内容的形状添加"paragraphs"字段(不是"replacement_paragraphs")
- 替换JSON中没有"paragraphs"的形状将自动清除文本
- 带项目符号的段落将自动左对齐。当时,不要设置
"bullet": true属性alignment - 为占位符文本生成合适的替换内容
- 根据形状大小确定合适的内容长度
- 至关重要:保留原始清单中的段落属性——不要只提供文本
- 重要提示:当bullet: true时,不要在文本中包含项目符号符号(•、-、*)——它们会自动添加
- 基本格式规则:
- 标题/副标题通常应设置
"bold": true - 列表项应设置(当bullet为true时,level是必需的)
"bullet": true, "level": 0 - 保留任何对齐属性(例如,居中文本设置)
"alignment": "CENTER" - 当字体属性与默认不同时,包含该属性(例如、
"font_size": 14.0)"font_name": "Lora" - 颜色:RGB颜色使用,主题颜色使用
"color": "FF0000""theme_color": "DARK_1" - 替换脚本需要格式正确的段落,而不仅仅是文本字符串
- 重叠形状:优先选择默认字号较大或占位符类型更合适的形状
- 标题/副标题通常应设置
- 将包含替换内容的更新清单保存到
replacement-text.json - 警告:不同的模板布局有不同的形状数量——创建替换内容之前务必检查实际清单
格式正确的paragraphs字段示例: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中未列出的形状将自动清除:json{ "slide-0": { "shape-0": { "paragraphs": [...] // 该形状将获得新文本 } // 清单中的shape-1和shape-2将自动清除 } }演示文稿的常见格式模式:- 标题幻灯片:粗体文本,有时居中
- 幻灯片内的节标题:粗体文本
- 项目符号列表:每个项目需要
"bullet": true, "level": 0 - 正文文本:通常不需要特殊属性
- 引用:可能有特殊对齐或字体属性
-
使用脚本应用替换内容
replace.pybashpython scripts/replace.py working.pptx replacement-text.json output.pptx该脚本将:- 首先使用inventory.py中的函数提取所有文本形状的清单
- 验证替换JSON中的所有形状是否存在于清单中
- 清除清单中识别的所有形状的文本
- 仅对替换JSON中定义了"paragraphs"的形状应用新文本
- 通过应用JSON中的段落属性来保留格式
- 自动处理项目符号、对齐方式、字体属性和颜色
- 保存更新后的演示文稿
验证错误示例:ERROR: 替换JSON中的无效形状: - Shape 'shape-99'在'slide-0'上未找到。可用形状: shape-0, shape-1, shape-4 - Slide 'slide-999'在清单中未找到ERROR: 替换文本导致以下形状的文本溢出情况恶化: - slide-0/shape-2: 溢出增加了1.25英寸(原0.00英寸,现1.2英寸)
Creating Thumbnail Grids
创建缩略图网格
To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:
bash
python scripts/thumbnail.py template.pptx [output_prefix]Features:
- Creates: (or
thumbnails.jpg,thumbnails-1.jpg, etc. for large decks)thumbnails-2.jpg - Default: 5 columns, max 30 slides per grid (5×6)
- Custom prefix:
python scripts/thumbnail.py template.pptx my-grid- Note: The output prefix should include the path if you want output in a specific directory (e.g., )
workspace/my-grid
- Note: The output prefix should include the path if you want output in a specific directory (e.g.,
- Adjust columns: (range: 3-6, affects slides per grid)
--cols 4 - Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
- Slides are zero-indexed (Slide 0, Slide 1, etc.)
Use cases:
- Template analysis: Quickly understand slide layouts and design patterns
- Content review: Visual overview of entire presentation
- Navigation reference: Find specific slides by their visual appearance
- Quality check: Verify all slides are properly formatted
Examples:
bash
undefined要创建PowerPoint幻灯片的视觉缩略图网格,以便快速分析和参考:
bash
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
- 注意:如果要在特定目录中输出,输出前缀应包含路径(例如
- 调整列数:(范围:3-6,影响每个网格的幻灯片数量)
--cols 4 - 网格限制:3列=12张幻灯片/网格,4列=20张,5列=30张,6列=42张
- 幻灯片采用0索引(Slide 0、Slide 1等)
使用场景:
- 模板分析:快速了解幻灯片布局和设计模式
- 内容审核:演示文稿的视觉概览
- 导航参考:通过视觉外观查找特定幻灯片
- 质量检查:验证所有幻灯片格式是否正确
示例:
bash
undefinedBasic usage
基本用法
python scripts/thumbnail.py presentation.pptx
python scripts/thumbnail.py presentation.pptx
Combine options: custom name, columns
组合选项:自定义名称、列数
python scripts/thumbnail.py template.pptx analysis --cols 4
undefinedpython scripts/thumbnail.py template.pptx analysis --cols 4
undefinedConverting Slides to Images
将幻灯片转换为图片
To visually analyze PowerPoint slides, convert them to images using a two-step process:
-
Convert PPTX to PDF:bash
soffice --headless --convert-to pdf template.pptx -
Convert PDF pages to JPEG images:bash
pdftoppm -jpeg -r 150 template.pdf slideThis creates files like,slide-1.jpg, etc.slide-2.jpg
Options:
- : Sets resolution to 150 DPI (adjust for quality/size balance)
-r 150 - : Output JPEG format (use
-jpegfor PNG if preferred)-png - : First page to convert (e.g.,
-f Nstarts from page 2)-f 2 - : Last page to convert (e.g.,
-l Nstops at page 5)-l 5 - : Prefix for output files
slide
Example for specific range:
bash
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide # Converts only pages 2-5要视觉分析PowerPoint幻灯片,请通过两步流程将其转换为图片:
-
将PPTX转换为PDF:bash
soffice --headless --convert-to pdf template.pptx -
将PDF页面转换为JPEG图片:bash
pdftoppm -jpeg -r 150 template.pdf slide这将生成、slide-1.jpg等文件。slide-2.jpg
选项:
- : 设置分辨率为150 DPI(可调整以平衡质量和大小)
-r 150 - : 输出JPEG格式(如果偏好PNG,可使用
-jpeg)-png - : 开始转换的页码(例如
-f N从第2页开始)-f 2 - : 结束转换的页码(例如
-l N到第5页结束)-l 5 - : 输出文件的前缀
slide
特定范围转换示例:
bash
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide # 仅转换第2-5页Code Style Guidelines
代码风格指南
IMPORTANT: When generating code for PPTX operations:
- Write concise code
- Avoid verbose variable names and redundant operations
- Avoid unnecessary print statements
重要提示: 生成PPTX操作相关代码时:
- 编写简洁的代码
- 避免冗长的变量名和冗余操作
- 避免不必要的打印语句
Dependencies
依赖项
Required dependencies (should already be installed):
- markitdown: (for text extraction from presentations)
pip install "markitdown[pptx]" - pptxgenjs: (for creating presentations via html2pptx)
npm install -g pptxgenjs - playwright: (for HTML rendering in html2pptx)
npm install -g playwright - react-icons: (for icons)
npm install -g react-icons react react-dom - sharp: (for SVG rasterization and image processing)
npm install -g sharp - LibreOffice: (for PDF conversion)
sudo apt-get install libreoffice - Poppler: (for pdftoppm to convert PDF to images)
sudo apt-get install poppler-utils - defusedxml: (for secure XML parsing)
pip install defusedxml
所需依赖项(应已安装):
- markitdown: (用于从演示文稿中提取文本)
pip install "markitdown[pptx]" - pptxgenjs: (用于通过html2pptx创建演示文稿)
npm install -g pptxgenjs - playwright: (用于html2pptx中的HTML渲染)
npm install -g playwright - react-icons: (用于图标)
npm install -g react-icons react react-dom - sharp: (用于SVG栅格化和图片处理)
npm install -g sharp - LibreOffice: (用于PDF转换)
sudo apt-get install libreoffice - Poppler: (用于pdftoppm将PDF转换为图片)
sudo apt-get install poppler-utils - defusedxml: (用于安全XML解析)
pip install defusedxml
When to Use
使用场景
This skill is applicable to execute the workflow or actions described in the overview.
本技能适用于执行概述中描述的工作流或操作。",