Back to Details

powerpoint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PowerPoint Skill

PowerPoint 自动化技能组件

Generates, updates, and manages PowerPoint slide decks using 
python-pptx
with YAML-driven content and styling definitions.
通过
python-pptx
结合YAML驱动的内容与样式定义，实现PowerPoint演示文稿的生成、更新与管理。

Overview

概述

This skill provides Python scripts that consume YAML configuration files to produce PowerPoint slide decks. Each slide is defined by a 
content.yaml
file describing its layout, text, and shapes. A 
style.yaml
file defines dimensions, template configuration, layout mappings, metadata, and defaults.
SKILL.md covers technical reference: prerequisites, commands, script architecture, API constraints, and troubleshooting. For conventions and design rules (element positioning, visual quality, color and contrast, contextual styling), follow 
pptx.instructions.md
.
本技能提供Python脚本，可读取YAML配置文件来生成PowerPoint演示文稿。每张幻灯片由描述其布局、文本和形状的
content.yaml
文件定义。
style.yaml
文件则定义尺寸、模板配置、布局映射、元数据及默认设置。
SKILL.md包含技术参考内容：前置要求、命令、脚本架构、API约束及故障排除。如需了解规范与设计规则（元素定位、视觉质量、颜色与对比度、上下文样式），请参考
pptx.instructions.md
。

Prerequisites

前置要求

PowerShell

PowerShell

The 
Invoke-PptxPipeline.ps1
script handles virtual environment creation and dependency installation automatically via 
uv sync
. Requires 
uv
, Python 3.11+, and PowerShell 7+.
Invoke-PptxPipeline.ps1
脚本可通过
uv sync
自动处理虚拟环境创建与依赖安装。需要安装
uv
、Python 3.11+及PowerShell 7+。

Installing uv

安装uv

If 
uv
is not installed:
bash
undefined
若未安装
uv
：
bash
undefined

macOS / Linux

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Via pip (fallback)

Via pip (备用方案)

pip install uv
undefined
pip install uv
undefined

System Dependencies (Export and Validation)

系统依赖（导出与验证）

The Export and Validate actions require LibreOffice for PPTX-to-PDF conversion and optionally 
pdftoppm
from poppler for PDF-to-JPG rendering. When 
pdftoppm
is not available, PyMuPDF handles the image rendering.
The Validate action's vision-based checks require the GitHub Copilot CLI for model access.
bash
undefined
导出和验证操作需要LibreOffice来实现PPTX转PDF转换，可选使用poppler中的
pdftoppm
来实现PDF转JPG渲染。当
pdftoppm
不可用时，将由PyMuPDF处理图像渲染。
验证操作中的视觉检查需要GitHub Copilot CLI来访问模型。
bash
undefined

macOS

macOS

brew install --cask libreoffice brew install poppler # optional, provides pdftoppm
brew install --cask libreoffice brew install poppler # 可选，提供pdftoppm

Linux

Linux

sudo apt-get install libreoffice poppler-utils
sudo apt-get install libreoffice poppler-utils

Windows (winget preferred, choco fallback)

Windows（优先使用winget，choco作为备选）

winget install TheDocumentFoundation.LibreOffice
winget install TheDocumentFoundation.LibreOffice

choco install libreoffice-still # alternative

choco install libreoffice-still # 替代方案

poppler: no winget package; use choco install poppler (optional, provides pdftoppm)

poppler：暂无winget包；可使用choco install poppler（可选，提供pdftoppm）

undefined
undefined

Copilot CLI (Vision Validation)

Copilot CLI（视觉验证）

The 
validate_slides.py
script uses the GitHub Copilot SDK to send slide images to vision-capable models. The Copilot CLI must be installed and authenticated:
bash
undefined
validate_slides.py
脚本使用GitHub Copilot SDK将幻灯片图像发送至支持视觉的模型。必须安装并认证Copilot CLI：
bash
undefined

Install Copilot CLI

安装Copilot CLI

npm install -g @github/copilot-cli
npm install -g @github/copilot-cli

Authenticate (uses the same GitHub account as VS Code Copilot)

认证（使用与VS Code Copilot相同的GitHub账户）

copilot auth login
copilot auth login

Verify

验证

copilot --version
undefined
copilot --version
undefined

Required Files

必需文件

  • style.yaml
    — Dimensions, defaults, template configuration, and metadata
  • content.yaml
    — Per-slide content definition (text, shapes, images, layout)
  • (Optional) 
    content-extra.py
    — Custom Python for complex slide drawings
  • style.yaml
    — 尺寸、默认设置、模板配置及元数据
  • content.yaml
    — 单张幻灯片的内容定义（文本、形状、图像、布局）
  • （可选）
    content-extra.py
    — 用于复杂幻灯片绘制的自定义Python脚本

Content Directory Structure

内容目录结构

All slide content lives under the working directory's 
content/
folder:
text
content/
├── global/
│   ├── style.yaml              # Dimensions, defaults, template config, and theme metadata
│   └── voice-guide.md          # Voice and tone guidelines
├── slide-001/
│   ├── content.yaml            # Slide 1 content and layout
│   └── images/                 # Slide-specific images
│       ├── background.png
│       └── background.yaml     # Image metadata sidecar
├── slide-002/
│   ├── content.yaml            # Slide 2 content and layout
│   ├── content-extra.py        # Custom Python for complex drawings
│   └── images/
│       └── screenshot.png
├── slide-003/
│   ├── content.yaml
│   └── images/
│       ├── diagram.png
│       └── diagram.yaml
└── ...
所有幻灯片内容存储在工作目录的
content/
文件夹下：
text
content/
├── global/
│   ├── style.yaml              # 尺寸、默认设置、模板配置及主题元数据
│   └── voice-guide.md          # 语气与语调指南
├── slide-001/
│   ├── content.yaml            # 幻灯片1的内容与布局
│   └── images/                 # 幻灯片专属图片
│       ├── background.png
│       └── background.yaml     # 图片元数据辅助文件
├── slide-002/
│   ├── content.yaml            # 幻灯片2的内容与布局
│   ├── content-extra.py        # 用于复杂绘制的自定义Python脚本
│   └── images/
│       └── screenshot.png
├── slide-003/
│   ├── content.yaml
│   └── images/
│       ├── diagram.png
│       └── diagram.yaml
└── ...

Global Style Definition (
style.yaml
)

全局样式定义（
style.yaml
）

The global 
style.yaml
defines dimensions, template configuration, layout mappings, metadata, and defaults. Color and font choices are specified per-element in each slide's 
content.yaml
rather than centralized in the style file.
See the style.yaml template for the full template, field reference, and usage instructions.
全局
style.yaml
定义尺寸、模板配置、布局映射、元数据及默认设置。颜色与字体选择在每张幻灯片的
content.yaml
中按元素单独指定，而非集中在样式文件中。
完整模板、字段参考及使用说明请查看style.yaml 模板。

Per-Slide Content Definition (
content.yaml
)

单张幻灯片内容定义（
content.yaml
）

Each slide's 
content.yaml
defines layout, text, shapes, and positioning. All position and size values are in inches. Color values use 
#RRGGBB
hex format or 
@theme_name
references.
See the content.yaml template for the full template, supported element types, supported shape types, and usage instructions.
每张幻灯片的
content.yaml
定义布局、文本、形状及定位。所有位置与尺寸值以英寸为单位。颜色值使用
#RRGGBB
十六进制格式或
@theme_name
主题引用。
完整模板、支持的元素类型、形状类型及使用说明请查看content.yaml 模板。

Complex Drawings (
content-extra.py
)

复杂绘制（
content-extra.py
）

When a slide requires complex drawings that cannot be expressed through 
content.yaml
element definitions, create a 
content-extra.py
file in the slide folder. The 
render()
function signature is fixed. The build script calls it after placing standard 
content.yaml
elements.
See the content-extra.py template for the full template, function parameters, and usage guidelines.
当幻灯片需要无法通过
content.yaml
元素定义实现的复杂绘制时，可在幻灯片文件夹中创建
content-extra.py
文件。
render()
函数签名固定，构建脚本会在放置完
content.yaml
标准元素后调用该函数。
完整模板、函数参数及使用指南请查看content-extra.py 模板。

Security Validation

安全验证

Before executing a 
content-extra.py
file, the build script performs AST-based static analysis to reject dangerous code. Validation runs automatically unless the 
--allow-scripts
flag is passed.
Allowed imports:
  • pptx
    and all 
    pptx.*
    submodules
  • Safe standard-library modules (e.g., 
    math
    , 
    copy
    , 
    json
    , 
    re
    , 
    pathlib
    , 
    collections
    , 
    itertools
    , 
    functools
    , 
    typing
    , 
    enum
    , 
    dataclasses
    , 
    decimal
    , 
    fractions
    , 
    string
    , 
    textwrap
    )
Blocked imports:
  • subprocess
    , 
    os
    , 
    shutil
    , 
    socket
    , 
    ctypes
    , 
    signal
    , 
    multiprocessing
    , 
    threading
    , 
    http
    , 
    urllib
    , 
    ftplib
    , 
    smtplib
    , 
    imaplib
    , 
    poplib
    , 
    xmlrpc
    , 
    webbrowser
    , 
    code
    , 
    codeop
    , 
    compileall
    , 
    py_compile
    , 
    zipimport
    , 
    pkgutil
    , 
    runpy
    , 
    ensurepip
    , 
    venv
    , 
    sqlite3
    , 
    tempfile
    , 
    shelve
    , 
    dbm
    , 
    pickle
    , 
    marshal
    , 
    importlib
    , 
    sys
    , 
    telnetlib
  • Any third-party package not on the allowlist
Blocked builtins:
  • Dangerous: 
    eval
    , 
    exec
    , 
    __import__
    , 
    compile
    , 
    breakpoint
  • Indirect bypass: 
    getattr
    , 
    setattr
    , 
    delattr
    , 
    globals
    , 
    locals
    , 
    vars
Runtime namespace restriction:
Even after AST validation passes, the executed module runs in a restricted namespace where 
__builtins__
is limited to safe builtins only. The dangerous and indirect-bypass builtins listed above are removed from the module namespace before execution (
__import__
is kept because the import machinery requires it; the AST checker blocks direct 
__import__()
calls).
--allow-scripts
flag:
Pass 
--allow-scripts
to skip AST validation and namespace restriction for trusted content. This flag is required when a 
content-extra.py
script legitimately needs blocked imports or builtins.
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx \
  --allow-scripts
When validation fails, the build raises 
ContentExtraError
with a message identifying the violation and file path.
在执行
content-extra.py
文件前，构建脚本会基于AST进行静态分析，拒绝危险代码。除非传入
--allow-scripts
参数，否则验证会自动运行。
允许的导入：
  • pptx
    及其所有
    pptx.*
    子模块
  • 安全的标准库模块（如
    math
    、
    copy
    、
    json
    、
    re
    、
    pathlib
    、
    collections
    、
    itertools
    、
    functools
    、
    typing
    、
    enum
    、
    dataclasses
    、
    decimal
    、
    fractions
    、
    string
    、
    textwrap
    ）
禁止的导入：
  • subprocess
    、
    os
    、
    shutil
    、
    socket
    、
    ctypes
    、
    signal
    、
    multiprocessing
    、
    threading
    、
    http
    、
    urllib
    、
    ftplib
    、
    smtplib
    、
    imaplib
    、
    poplib
    、
    xmlrpc
    、
    webbrowser
    、
    code
    、
    codeop
    、
    compileall
    、
    py_compile
    、
    zipimport
    、
    pkgutil
    、
    runpy
    、
    ensurepip
    、
    venv
    、
    sqlite3
    、
    tempfile
    、
    shelve
    、
    dbm
    、
    pickle
    、
    marshal
    、
    importlib
    、
    sys
    、
    telnetlib
  • 不在允许列表中的任何第三方包
禁止的内置函数：
  • 危险函数：
    eval
    、
    exec
    、
    __import__
    、
    compile
    、
    breakpoint
  • 间接绕过函数：
    getattr
    、
    setattr
    、
    delattr
    、
    globals
    、
    locals
    、
    vars
运行时命名空间限制：
即使AST验证通过，执行的模块仍会在受限命名空间中运行，其中
__builtins__
仅包含安全的内置函数。上述危险函数和间接绕过函数会在执行前从模块命名空间中移除（
__import__
会保留，因为导入机制需要它；AST检查器会阻止直接调用
__import__()
）。
--allow-scripts
参数：
传入
--allow-scripts
可跳过AST验证和命名空间限制，适用于可信内容。当
content-extra.py
脚本确实需要使用被禁止的导入或内置函数时，必须使用该参数。
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx \
  --allow-scripts
当验证失败时，构建过程会抛出
ContentExtraError
，并显示包含违规内容和文件路径的提示信息。

Script Reference

脚本参考

All operations are available through the PowerShell orchestrator (
Invoke-PptxPipeline.ps1
) or directly via the Python scripts. The PowerShell script manages the Python virtual environment and dependency installation automatically via 
uv sync
.
所有操作可通过PowerShell编排器（
Invoke-PptxPipeline.ps1
）或直接通过Python脚本执行。PowerShell脚本会通过
uv sync
自动管理Python虚拟环境和依赖安装。

Build a Slide Deck

构建演示文稿

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx
Reads all 
content/slide-*/content.yaml
files in numeric order and generates the complete deck. Executes 
content-extra.py
files when present.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx
按数字顺序读取所有
content/slide-*/content.yaml
文件，生成完整的演示文稿。若存在
content-extra.py
文件则会执行。

Build from a Template

从模板构建

[!WARNING] 
--template
creates a NEW presentation inheriting only slide masters, layouts, and theme from the template. All existing slides are discarded. Use 
--source
for partial rebuilds.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx `
  -TemplatePath corporate-template.pptx
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx \
  --template corporate-template.pptx
Loads slide masters and layouts from the template PPTX. Layout names in each slide's 
content.yaml
resolve against the template's layouts, with optional name mapping via the 
layouts
section in 
style.yaml
. Populate themed layout placeholders using the 
placeholders
section in content YAML.
[!WARNING] 
--template
会创建一个新的演示文稿，仅从模板继承幻灯片母版、布局和主题。所有现有幻灯片会被丢弃。如需部分重建，请使用
--source
参数。
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx `
  -TemplatePath corporate-template.pptx
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx \
  --template corporate-template.pptx
从模板PPTX加载幻灯片母版和布局。每张幻灯片
content.yaml
中的布局名称会与模板中的布局匹配，也可通过
style.yaml
的
layouts
部分进行名称映射。使用内容YAML中的
placeholders
部分填充主题布局占位符。

Update Specific Slides

更新特定幻灯片

[!IMPORTANT] Use 
--source
(not 
--template
) for partial rebuilds. Combining 
--template
and 
--source
is not supported.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx `
  -SourcePath slide-deck/presentation.pptx `
  -Slides "3,7,15"
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --source slide-deck/presentation.pptx \
  --output slide-deck/presentation.pptx \
  --slides 3,7,15
Opens the existing deck, clears shapes on the specified slides, rebuilds them in-place from their 
content.yaml
, and saves. All other slides remain untouched. After building, verify the output slide count matches the original deck.
[!IMPORTANT] 如需部分重建，请使用
--source
（而非
--template
）。不支持同时使用
--template
和
--source
参数。
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Build `
  -ContentDir content/ `
  -StylePath content/global/style.yaml `
  -OutputPath slide-deck/presentation.pptx `
  -SourcePath slide-deck/presentation.pptx `
  -Slides "3,7,15"
bash
python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --source slide-deck/presentation.pptx \
  --output slide-deck/presentation.pptx \
  --slides 3,7,15
打开现有演示文稿，清除指定幻灯片上的形状，根据其
content.yaml
原地重建，然后保存。其他所有幻灯片保持不变。构建完成后，请验证输出幻灯片数量与原演示文稿一致。

Extract Content from Existing PPTX

从现有PPTX提取内容

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Extract `
  -InputPath existing-deck.pptx `
  -OutputDir content/
bash
python scripts/extract_content.py \
  --input existing-deck.pptx \
  --output-dir content/
Extracts text, shapes, images, and styling from an existing PPTX into the 
content/
folder structure. Creates 
content.yaml
files for each slide and populates the 
global/style.yaml
from detected patterns.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Extract `
  -InputPath existing-deck.pptx `
  -OutputDir content/
bash
python scripts/extract_content.py \
  --input existing-deck.pptx \
  --output-dir content/
从现有PPTX中提取文本、形状、图像和样式，保存到
content/
文件夹结构中。为每张幻灯片创建
content.yaml
文件，并根据检测到的模式填充
global/style.yaml
。

Extract Specific Slides

提取特定幻灯片

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Extract `
  -InputPath existing-deck.pptx `
  -OutputDir content/ `
  -Slides "3,7,15"
bash
python scripts/extract_content.py \
  --input existing-deck.pptx \
  --output-dir content/ \
  --slides 3,7,15
Extracts only the specified slides (plus the global style). Useful for targeted updates on large decks.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Extract `
  -InputPath existing-deck.pptx `
  -OutputDir content/ `
  -Slides "3,7,15"
bash
python scripts/extract_content.py \
  --input existing-deck.pptx \
  --output-dir content/ \
  --slides 3,7,15
仅提取指定幻灯片（加上全局样式）。适用于对大型演示文稿进行针对性更新。

Extraction Limitations

提取限制

  • Picture shapes that reference external (linked) images instead of embedded blobs are recorded with 
    path: LINKED_IMAGE_NOT_EMBEDDED
    . The script does not crash but the image must be re-embedded manually.
  • When text elements inherit font, size, or color from the slide master or layout, the extraction records no inline styling. Content YAML for these elements needs explicit font properties added before rebuild.
  • The 
    detect_global_style()
    function uses frequency analysis across all slides. For decks with mixed styling, review and adjust 
    style.yaml
    values manually after extraction.
  • 引用外部（链接）图像而非嵌入 blob 的图片形状会被记录为
    path: LINKED_IMAGE_NOT_EMBEDDED
    。脚本不会崩溃，但需要手动重新嵌入图像。
  • 当文本元素从幻灯片母版或布局继承样式时，提取结果中不会包含内联样式。重建前需要在内容YAML中添加明确的字体属性。
  • detect_global_style()
    函数通过对所有幻灯片进行频率分析来生成结果。对于样式混杂的演示文稿，提取后需要手动检查并调整
    style.yaml
    的值。

Validate a Deck

验证演示文稿

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/
The Validate action runs a two- or three-step pipeline:
  1. Export — Clears stale slide images from the output directory, then renders slides to JPG images via LibreOffice (PPTX → PDF → JPG). When 
    -Slides
    is used, output images are named to match original slide numbers (e.g., 
    slide-023.jpg
    for slide 23), not sequential PDF page numbers.
  2. PPTX validation — Checks PPTX-only properties (
    validate_deck.py
    ) for speaker notes and slide count.
  3. Vision validation (optional) — Sends slide images to a vision-capable model via the Copilot SDK (
    validate_slides.py
    ) for visual quality checks. Runs when 
    -ValidationPrompt
    or 
    -ValidationPromptFile
    is provided.
For validation criteria (element positioning, visual quality, color contrast, content completeness), see 
pptx.instructions.md
Validation Criteria.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/
验证操作会运行两步或三步流程：
  1. 导出 — 清除输出目录中的旧幻灯片图像，然后通过LibreOffice将幻灯片渲染为JPG图像（PPTX → PDF → JPG）。当使用
    -Slides
    参数时，输出图像会以原幻灯片编号命名（例如，幻灯片23命名为
    slide-023.jpg
    ），而非按PDF页码顺序命名。
  2. PPTX验证 — 检查仅针对PPTX的属性（
    validate_deck.py
    ），如演讲者备注和幻灯片数量。
  3. 视觉验证（可选） — 通过Copilot SDK将幻灯片图像发送至支持视觉的模型（
    validate_slides.py
    ），进行视觉质量检查。当提供
    -ValidationPrompt
    或
    -ValidationPromptFile
    参数时运行。
验证标准（元素定位、视觉质量、颜色对比度、内容完整性）请查看
pptx.instructions.md
中的验证标准部分。

Built-in System Message

内置系统提示

The 
validate_slides.py
script includes a built-in system message that focuses on issue detection only (not full slide description). It checks overlapping elements, text overflow/cutoff, decorative line mismatch after title wraps, citation/footer collisions, tight spacing, uneven gaps, insufficient edge margins, alignment inconsistencies, low contrast, narrow text boxes, and leftover placeholders. For dense slides, near-edge placement or tight boundaries are acceptable when readability is not materially affected. The 
-ValidationPrompt
parameter provides supplementary user-level context and does not need to repeat these checks.
validate_slides.py
脚本包含一个内置系统提示，仅聚焦于问题检测（而非完整幻灯片描述）。它会检查元素重叠、文本溢出/截断、标题换行后装饰线条不匹配、引用/页脚冲突、间距过紧、间隙不均、边缘边距不足、对齐不一致、对比度低、文本框过窄及残留占位符等问题。对于内容密集的幻灯片，只要可读性未受实质影响，靠近边缘放置或边界较窄是可接受的。
-ValidationPrompt
参数用于补充用户级上下文，无需重复这些检查项。

Validate with Vision Checks

结合视觉检查进行验证

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -ValidationPrompt "Validate visual quality. Focus on recently modified slides for content accuracy." `
  -ValidationModel claude-haiku-4.5
Vision validation results are written to 
validation-results.json
in the image output directory, containing raw model responses per slide with quality findings. Per-slide response text is also written to 
slide-NNN-validation.txt
files next to each slide image.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -ValidationPrompt "验证视觉质量。重点检查最近修改的幻灯片内容准确性。" `
  -ValidationModel claude-haiku-4.5
视觉验证结果会写入图像输出目录中的
validation-results.json
，包含每张幻灯片的原始模型响应及质量问题。每张幻灯片的响应文本也会写入对应幻灯片图像旁的
slide-NNN-validation.txt
文件。

Validate Specific Slides

验证特定幻灯片

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -Slides "3,7,15"
Validates only the specified slides. When content directories cover fewer slides than the PPTX, the slide count check reports an informational note rather than an error.
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -Slides "3,7,15"
仅验证指定幻灯片。当内容目录中的幻灯片数量少于PPTX中的数量时，幻灯片数量检查会显示信息性提示而非错误。

validate_slides.py CLI Reference

validate_slides.py 命令行参考

FlagRequiredDefaultDescription
--image-dir
Yes—Directory containing 
slide-NNN.jpg
images
--prompt
One of 
--prompt
/ 
--prompt-file
—Validation prompt text
--prompt-file
One of 
--prompt
/ 
--prompt-file
—Path to file containing the validation prompt
--model
No
claude-haiku-4.5
Vision model ID
--output
NostdoutJSON results file path
--slides
NoallComma-separated slide numbers to validate
-v
, 
--verbose
No—Enable debug-level logging
参数是否必填默认值描述
--image-dir
是—包含
slide-NNN.jpg
图像的目录
--prompt
--prompt
/ 
--prompt-file
二选一		—验证提示文本
--prompt-file
--prompt
/ 
--prompt-file
二选一		—包含验证提示的文件路径
--model
否
claude-haiku-4.5
视觉模型ID
--output
否stdoutJSON结果文件路径
--slides
否全部要验证的幻灯片编号（逗号分隔）
-v
, 
--verbose
否—启用调试级日志

validate_deck.py CLI Reference

validate_deck.py 命令行参考

FlagRequiredDefaultDescription
--input
Yes—Input PPTX file path
--content-dir
No—Content directory for slide count comparison
--slides
NoallComma-separated slide numbers to validate
--output
NostdoutJSON results file path
--report
No—Markdown report file path
--per-slide-dir
No—Directory for per-slide JSON files (
slide-NNN-deck-validation.json
)
参数是否必填默认值描述
--input
是—输入PPTX文件路径
--content-dir
否—用于幻灯片数量对比的内容目录
--slides
否全部要验证的幻灯片编号（逗号分隔）
--output
否stdoutJSON结果文件路径
--report
否—Markdown报告文件路径
--per-slide-dir
否—存储单张幻灯片JSON文件的目录（
slide-NNN-deck-validation.json
）

Validation Outputs

验证输出

When run through the pipeline, validation produces these files in the image output directory:
FileFormatContent
deck-validation-results.json
JSONPer-slide PPTX property issues (speaker notes, slide count)
deck-validation-report.md
MarkdownHuman-readable report for PPTX property validation
validation-results.json
JSONConsolidated vision model responses with quality findings
slide-NNN-validation.txt
TextPer-slide vision response text (next to 
slide-NNN.jpg
)
slide-NNN-deck-validation.json
JSONPer-slide PPTX property validation result (next to 
slide-NNN.jpg
)
Per-slide vision text files are written alongside their corresponding 
slide-NNN.jpg
images, enabling agents to read validation findings for individual slides without parsing the consolidated JSON file.
通过编排器运行验证时，会在图像输出目录中生成以下文件：
文件格式内容
deck-validation-results.json
JSON单张幻灯片的PPTX属性问题（演讲者备注、幻灯片数量）
deck-validation-report.md
MarkdownPPTX属性验证的人类可读报告
validation-results.json
JSON整合后的视觉模型响应及质量问题
slide-NNN-validation.txt
文本单张幻灯片的视觉响应文本（位于
slide-NNN.jpg
旁）
slide-NNN-deck-validation.json
JSON单张幻灯片的PPTX属性验证结果（位于
slide-NNN.jpg
旁）
单张幻灯片的视觉文本文件会与对应的
slide-NNN.jpg
图像放在一起，方便工具读取单张幻灯片的验证结果，无需解析整合后的JSON文件。

Validation Scope for Changed Slides

变更幻灯片的验证范围

When validating after modifying or adding specific slides, always validate a block that includes one slide before and one slide after the changed or added slides. This catches edge-proximity issues, transition inconsistencies, and spacing problems that arise between adjacent slides.
For example, when slides 5 and 6 were changed, validate slides 4 through 7:
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -Slides "4,5,6,7" `
  -ValidationPrompt "Check for text overlay, overflow, margin issues, color contrast"
在修改或添加特定幻灯片后进行验证时，应始终验证包含变更/添加幻灯片的前一张和后一张的范围。这样可以捕获相邻幻灯片之间出现的边缘 proximity 问题、过渡不一致及间距问题。
例如，当修改了幻灯片5和6时，验证幻灯片4至7：
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Validate `
  -InputPath slide-deck/presentation.pptx `
  -ContentDir content/ `
  -Slides "4,5,6,7" `
  -ValidationPrompt "检查文本重叠、溢出、边距问题、颜色对比度"

Export Slides to Images

将幻灯片导出为图像

powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Export `
  -InputPath slide-deck/presentation.pptx `
  -ImageOutputDir slide-deck/validation/ `
  -Slides "1,3,5" `
  -Resolution 150
bash
undefined
powershell
./scripts/Invoke-PptxPipeline.ps1 -Action Export `
  -InputPath slide-deck/presentation.pptx `
  -ImageOutputDir slide-deck/validation/ `
  -Slides "1,3,5" `
  -Resolution 150
bash
undefined

Step 1: PPTX to PDF

步骤1：PPTX转PDF

python scripts/export_slides.py
--input slide-deck/presentation.pptx
--output slide-deck/validation/slides.pdf
--slides 1,3,5
python scripts/export_slides.py
--input slide-deck/presentation.pptx
--output slide-deck/validation/slides.pdf
--slides 1,3,5

Step 2: PDF to JPG (pdftoppm from poppler)

步骤2：PDF转JPG（使用poppler中的pdftoppm）

pdftoppm -jpeg -r 150 slide-deck/validation/slides.pdf slide-deck/validation/slide

Converts specified slides to JPG images for visual inspection. The PowerShell orchestrator handles both steps automatically, clears stale images before exporting, names output images to match original slide numbers when `-Slides` is used, and uses a PyMuPDF fallback when `pdftoppm` is not installed.

When running the two-step process manually (outside the pipeline), note that `render_pdf_images.py` uses sequential numbering by default. Pass `--slide-numbers` to map output images to original slide positions:

```bash
python scripts/render_pdf_images.py \
  --input slide-deck/validation/slides.pdf \
  --output-dir slide-deck/validation/ \
  --dpi 150 \
  --slide-numbers 1,3,5
Dependencies: Requires LibreOffice for PPTX-to-PDF conversion and either 
pdftoppm
(from 
poppler
) or 
pymupdf
(pip) for PDF-to-JPG rendering.
pdftoppm -jpeg -r 150 slide-deck/validation/slides.pdf slide-deck/validation/slide

将指定幻灯片转换为JPG图像，用于视觉检查。PowerShell编排器会自动处理这两个步骤，导出前清除旧图像，当使用`-Slides`参数时输出图像以原幻灯片编号命名，当`pdftoppm`不可用时会使用PyMuPDF作为备选方案。

当手动运行两步流程（在编排器外）时，注意`render_pdf_images.py`默认按顺序编号。传入`--slide-numbers`参数可将输出图像映射到原幻灯片位置：

```bash
python scripts/render_pdf_images.py \
  --input slide-deck/validation/slides.pdf \
  --output-dir slide-deck/validation/ \
  --dpi 150 \
  --slide-numbers 1,3,5
依赖：需要LibreOffice实现PPTX转PDF转换，需要
pdftoppm
（来自
poppler
）或
pymupdf
（通过pip安装）实现PDF转JPG渲染。

Script Architecture

脚本架构

The build and extraction scripts use shared modules in the 
scripts/
directory:
ModulePurpose
pptx_utils.py
Shared utilities: exit codes, logging configuration, slide filter parsing, unit conversion (
emu_to_inches()
), YAML loading
pptx_colors.py
Color resolution (
#hex
, 
@theme
, dict with brightness), theme color map (16 entries)
pptx_fonts.py
Font resolution, family normalization, weight suffix handling, alignment mapping
pptx_shapes.py
Shape constant map (29 entries + circle alias), auto-shape name mapping, rotation utilities
pptx_fills.py
Solid, gradient, and pattern fill application/extraction; line/border styling with dash styles
pptx_text.py
Text frame properties (margins, auto-size, vertical anchor), paragraph properties (spacing, level), run properties (underline, hyperlink)
pptx_tables.py
Table element creation and extraction with cell merging, banding, and per-cell styling
pptx_charts.py
Chart element creation and extraction for 12 chart types (column, bar, line, pie, scatter, bubble, etc.)
validate_deck.py
PPTX-only validation for speaker notes and slide count
validate_slides.py
Vision-based slide issue detection and quality validation via Copilot SDK with built-in checks and plain-text per-slide output
render_pdf_images.py
PDF-to-JPG rendering via PyMuPDF with optional slide-number-based naming
构建和提取脚本使用
scripts/
目录下的共享模块：
模块用途
pptx_utils.py
共享工具：退出码、日志配置、幻灯片过滤器解析、单位转换（
emu_to_inches()
）、YAML加载
pptx_colors.py
颜色解析（
#hex
、
@theme
、带亮度的字典）、主题颜色映射（16个条目）
pptx_fonts.py
字体解析、家族标准化、字重后缀处理、对齐映射
pptx_shapes.py
形状常量映射（29个条目+圆形别名）、自动形状名称映射、旋转工具
pptx_fills.py
纯色、渐变和图案填充的应用/提取；带虚线样式的线条/边框样式
pptx_text.py
文本框属性（边距、自动大小、垂直锚点）、段落属性（间距、级别）、文本片段属性（下划线、超链接）
pptx_tables.py
表格元素的创建与提取，支持单元格合并、条纹样式和单元格级样式
pptx_charts.py
12种图表类型（柱状图、条形图、折线图、饼图、散点图、气泡图等）的创建与提取
validate_deck.py
仅针对PPTX的验证，检查演讲者备注和幻灯片数量
validate_slides.py
通过Copilot SDK进行基于视觉的幻灯片问题检测和质量验证，包含内置检查和单张幻灯片纯文本输出
render_pdf_images.py
通过PyMuPDF实现PDF转JPG渲染，支持基于幻灯片编号的命名

python-pptx Constraints

python-pptx 约束

  • python-pptx does NOT support SVG images. Always convert to PNG via 
    cairosvg
    or 
    Pillow
    .
  • python-pptx cannot create new slide masters or layouts programmatically. Use blank layouts or start from a template PPTX with the 
    --template
    argument.
  • Transitions and animations are preserved when opening and saving existing files, but cannot be created or modified via the API.
  • When extracting content, slide master and layout inheritance means many text elements have no inline styling. Add explicit font properties in content YAML before rebuilding.
  • The Export and Validate actions require LibreOffice for PPTX-to-PDF conversion. The PowerShell orchestrator checks for LibreOffice availability before starting and provides platform-specific install instructions if missing.
  • Accessing 
    background.fill
    on slides with inherited backgrounds replaces them with 
    NoFill
    . Check 
    slide.follow_master_background
    before accessing the fill property.
  • Gradient fills use the python-pptx 
    GradientFill
    API with 
    GradientStop
    objects. Each stop specifies a position (0–100) and a color.
  • Theme colors resolve via 
    MSO_THEME_COLOR
    enum. Brightness adjustments apply through the color format's 
    brightness
    property.
  • Template-based builds load layouts by name or index. Layout name resolution falls back to index 6 (blank) when no match is found.
  • python-pptx 不支持SVG图像。请通过
    cairosvg
    或
    Pillow
    转换为PNG格式。
  • python-pptx无法通过编程方式创建新的幻灯片母版或布局。请使用空白布局，或通过
    --template
    参数从模板PPTX开始构建。
  • 打开和保存现有文件时会保留切换效果和动画，但无法通过API创建或修改它们。
  • 提取内容时，由于幻灯片母版和布局的继承关系，许多文本元素没有内联样式。重建前需要在内容YAML中添加明确的字体属性。
  • 导出和验证操作需要LibreOffice实现PPTX转PDF转换。PowerShell编排器会在启动前检查LibreOffice是否可用，若缺失会提供平台专属的安装说明。
  • 对继承背景的幻灯片访问
    background.fill
    会将其替换为
    NoFill
    。访问填充属性前请检查
    slide.follow_master_background
    。
  • 渐变填充使用python-pptx的
    GradientFill
    API和
    GradientStop
    对象。每个停止点指定位置（0–100）和颜色。
  • 主题颜色通过
    MSO_THEME_COLOR
    枚举解析。亮度调整通过颜色格式的
    brightness
    属性实现。
  • 基于模板的构建通过名称或索引加载布局。当未找到匹配项时，布局名称解析会回退到索引6（空白布局）。

Troubleshooting

故障排除

IssueCauseSolution
SVG runtime errorpython-pptx cannot embed SVGConvert to PNG via 
cairosvg
before adding
Text overlay between elementsInsufficient vertical spacingFollow element positioning conventions in 
pptx.instructions.md
Width overflow off-slideElement extends beyond slide boundaryFollow element positioning conventions in 
pptx.instructions.md
Bright accent color unreadable as fillWhite text on bright backgroundDarken accent to ~60% saturation for box fills
Background fill replaced with NoFillAccessed 
background.fill
on inherited background		Check 
slide.follow_master_background
before accessing
Missing speaker notesNotes not specified in 
content.yaml
Add 
speaker_notes
field to every content slide
LibreOffice not found during ValidateValidate exports slides to images firstInstall LibreOffice: 
brew install --cask libreoffice
(macOS)
uv
not found		uv package manager not installedInstall uv: 
curl -LsSf https://astral.sh/uv/install.sh | sh
(macOS/Linux) or 
pip install uv
Python not found by uvNo Python 3.11+ on PATHInstall via 
uv python install 3.11
or 
pyenv install 3.11
uv sync
fails		Missing or corrupt 
.venv
Delete 
.venv/
at the skill root and re-run 
uv sync
Import errors in scriptsDependencies not installed or stale venvRun 
uv sync
from the skill root to recreate the environment
问题原因解决方案
SVG运行时错误python-pptx无法嵌入SVG添加前通过
cairosvg
转换为PNG格式
元素间文本重叠垂直间距不足遵循
pptx.instructions.md
中的元素定位规范
宽度超出幻灯片边界元素延伸至幻灯片边界之外遵循
pptx.instructions.md
中的元素定位规范
亮色强调色作为填充时可读性差亮色背景上使用白色文本将强调色饱和度降低至约60%用于框填充
背景填充被替换为NoFill对继承背景的幻灯片访问了
background.fill
访问前检查
slide.follow_master_background
缺失演讲者备注
content.yaml
中未指定备注		为所有内容幻灯片添加
speaker_notes
字段
验证时未找到LibreOffice验证操作需要先将幻灯片导出为图像安装LibreOffice：macOS使用
brew install --cask libreoffice
未找到
uv
未安装uv包管理器安装uv：macOS/Linux使用
curl -LsSf https://astral.sh/uv/install.sh | sh
，或使用
pip install uv
uv无法找到PythonPATH中没有Python 3.11+通过
uv python install 3.11
让uv获取并管理解释器
uv sync
失败
.venv
缺失或损坏		删除技能根目录下的
.venv/
并重新运行
uv sync
脚本导入错误依赖未安装或虚拟环境过时从技能根目录运行
uv sync
重新创建环境

Environment Recovery

环境恢复

When scripts fail due to missing modules, import errors, or a corrupt virtual environment, recover with:
bash
cd .github/skills/experimental/powerpoint
rm -rf .venv
uv sync
This recreates the virtual environment from scratch using 
pyproject.toml
as the single source of truth. The 
Invoke-PptxPipeline.ps1
orchestrator runs 
uv sync
automatically on each invocation unless 
-SkipVenvSetup
is passed.
When 
uv
itself is not available, install it first (see Installing uv above), then retry. When Python 3.11+ is not available, run 
uv python install 3.11
to have uv fetch and manage the interpreter.
Brought to you by microsoft/hve-core
🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
当脚本因缺失模块、导入错误或虚拟环境损坏而失败时，可通过以下步骤恢复：
bash
cd .github/skills/experimental/powerpoint
rm -rf .venv
uv sync
此步骤会以
pyproject.toml
为唯一可信源，从头重新创建虚拟环境。
Invoke-PptxPipeline.ps1
编排器在每次调用时都会自动运行
uv sync
，除非传入
-SkipVenvSetup
参数。
当
uv
本身不可用时，请先安装uv（见上方安装uv部分），然后重试。当Python 3.11+不可用时，运行
uv python install 3.11
让uv获取并管理解释器。
由microsoft/hve-core提供
🤖 由✨Copilot根据出色的人类指令精准打造，再经我们挑剔的人工审核团队精心优化。