先选对生成模式

交付级任务，默认选择 Build Mode

如果你的 PPT 要交给客户、管理层、投资人或正式会议使用，优先使用 Build Mode。它允许 LLM 逐页规划结构、锁定视觉方向、精确控制布局， 并在 PPTX → PDF → PNG 后进行视觉复核和返工，是三种模式中视觉控制力和 交付确定性最高的路径。

如何判断

• 你关心“最终看起来是否专业”，而不是只要一个草稿：Build Mode；
• 你想快速验证主题、内容或风格方向：FreeStyle Mode；
• 你必须沿用企业模板、Logo、字体和版式：VI Build Mode。

FreeStyle 的 generate_ppt(query=...) 和 generate_ppt(content=...) 是同一个模式的两种输入方式，不是两条独立 的生成引擎。无论选择哪种模式，正式交付都必须经过 PNG 视觉检查。

本技能的核心价值

pptx-designer 负责把设计决策生成成可编辑 PPTX；本技能负责保证设计 决策和交付过程的质量：

需求确认
  → 领域判断与页面结构
  → 视觉方向建议与用户确认
  → 设计 token / 页面锚点锁定
  → pptx-designer 生成可编辑 PPTX
  → PPTX → PDF → PNG
  → 第一门：整体视觉效果与客户级完成度
  → 第二门：严重缺陷、需求和可编辑性检查
  → 源码/内容返工并重新渲染
  → 用户确认与交付

技术上“运行成功”不等于设计完成。本技能会直接检查导出的 PNG，判断页面 是否有视觉重心、合理密度、清晰层级、完整构图和符合用户需求的设计效果。

核心理念

这不是“一句话生成 PPT”的包装层，而是一套设计交付流程：

用户需求确认
  → PPT 结构设计
  → 视觉方案设计
  → 用户确认方向
  → pptx-designer 生成 PPTX
  → PPTX → PDF → PNG
  → LLM 逐页视觉检查
  → 代码/内容修订
  → 再次渲染检查
  → 用户确认最终效果
  → 交付

PPTX 文件成功生成、Python 没有报错、shape 数量正常，都不能代替 PNG 视觉检查。

生成前，LLM 会把用户需求整理成可追踪的视觉验收合同；生成 PNG 后，逐项 对照需求和页面证据，记录 PASS、NEEDS_REVISION 或 BLOCKED。因此 PNG 检查不是泛泛地判断“好不好看”，而是验证结果是否真正满足用户目标。

精选设计案例

这里展示的是可以下载、打开并继续编辑的完整 PowerPoint 案例。它们覆盖 技术系统、产业研究、品牌编辑和空间叙事，用来说明本技能如何把内容结构、 视觉方向和原生可编辑对象结合成完整的演示设计。

这些案例不是为了证明代码能够运行，而是为了展示从设计判断到最终页面 完成度的完整结果。更多页面和下载入口请查看在线案例画廊 和 examples/README.md。

每个项目展示全部页面缩略图，点击任意缩略图即可进入在线查看器，浏览完整页面并下载 PPTX、PDF：

AI Agent Operating System · 技术系统蓝图	AI Infrastructure Economics · 编辑型产业研究
Couture in Motion · 高级定制视觉研究	Luxury Fragrance Lookbook · 暗色产品编辑型画册
Architecture Vision Book · 建筑竞赛愿景书

安装

请先克隆仓库，再从仓库根目录执行安装。安装器会自动安装已发布的 pptx-designer Python 库，并把 Skill 安装到指定的 AI 编码工具：

# 克隆 Skill 仓库
git clone https://github.com/sunchaokun/PPT-Design-Skill.git
cd PPT-Design-Skill

python installer/install.py --platform opencode --force
python skill/scripts/check_runtime.py

可以将 opencode 替换为 claude、codex、deepseek-harness 或 all。 安装完成后请重启对应的 AI 编码工具。

首选渲染器是 Windows PowerPoint COM。备用方案需要 LibreOffice 和 Poppler （pdftoppm）。本技能不会静默安装桌面应用程序。

如果你希望在 Windows 上使用 winget 安装备用渲染依赖，可以在安装 Skill 时显式追加参数：

python installer/install.py --platform opencode --force --render-deps

可选：使用 AI 生成配图

使用 AI 生成配图需要配置对应服务商的 API 密钥。将示例文件复制到运行 build.py 的 PPT 项目目录：

Copy-Item .env.example .env

然后在 .env 中配置一个服务商，例如：

PPT_IMAGE_LLM_PROVIDER=gpt-image
OPENAI_API_KEY=your-api-key

.env 属于用户自己的项目，不应放入已安装的 Skill 目录，也不能提交到 Git。 关于 Seedream、Gemini、Wanx、Kimi、OpenAI 兼容接口、素材搜索和宿主工具生成 图片的配置，请参阅图片与运行环境配置。

检查真实案例

python skill/scripts/inspect_pptx.py examples/output/luxury_fragrance_lookbook.pptx --pretty
powershell -ExecutionPolicy Bypass -File skill/scripts/render_pptx.ps1 `
  -InFile examples/output/luxury_fragrance_lookbook.pptx `
  -OutDir examples/output/luxury-fragrance-rendered

对 couture 和 architecture 案例重复执行。导出后，LLM 必须直接查看 PNG， 检查构图、层级、文字可读性、图片裁切、页间节奏、用户需求匹配度和可编辑 性。发现问题必须修改源代码或内容并重新渲染。

文档入口

• 技能主流程
• 设计原则
• 公共 API
• 质量与交付
• 跨平台安装
• 真实评估样例
• 高定视觉方向评估
• 科研结果汇报评估

解决什么问题

仅检查代码、文件和基础结构，不能保证 PPT 达到设计要求。即使“运行成功”， 仍可能存在标题层级弱、页面拥挤、图片裁切错误、图表不可读、页面重复和风格 不统一等问题。

本技能将视觉结果作为交付对象的一部分：

1. 用户先确认需求和受众；
2. LLM 先设计页面结构和视觉方向；
3. pptx-designer 生成可编辑 PPTX；
4. 通过确认过的 PPTX -> PDF -> PNG 路径导出页面；
5. LLM 直接查看 PNG，逐页判断是否达到设计要求；
6. 发现问题后回到 Python 源码或内容进行修订；
7. 重新导出并检查，最终交给用户确认。

设计能力

本技能采用成熟的设计思维，而不是把设计退化成选择一个 style 参数：

模式详细说明

FreeStyle

FreeStyle 使用 pptx-designer.generate_ppt() 完成库内的目标驱动生成：

from pptx_designer import generate_ppt

result = generate_ppt(
    "AI startup investor pitch",
    style="dark cyberpunk",
    output="output/pitch.pptx",
)

当页面目标和文案已经明确时，使用结构化 content：

result = generate_ppt(
    content={
        "title": "Q4 Revenue Review",
        "pages": [
            {"goal": "hook", "title": "Q4 2026", "subtitle": "Record quarter"},
            {"goal": "problem", "title": "The pressure is visible", "bullets": [
                "Enterprise demand is growing",
                "Delivery capacity is the constraint",
            ]},
            {"goal": "data", "title": "Key metrics", "bullets": [
                "Revenue: $12.8M",
                "Retention: 89%",
            ]},
        ],
    },
    style="professional",
    output="output/review.pptx",
)

query 和 content 都属于 FreeStyle，不是两个不同的渲染引擎。content 只是让 LLM 更明确地控制页面目标和文案；需要精确坐标时应使用 Build Mode。

VI Build Mode

当用户提供 template.pptx、企业母版或明确要求品牌合规时使用 VI Build：

1. 使用 extract_design_dna() 分析模板；
2. 提取颜色、字体、安全边距、页脚、Logo 和重复装饰；
3. 保留封面、目录、章节页和结尾等框架页；
4. 基于模板增加内容页；
5. 通过 PPTX -> PDF -> PNG 检查原有页面和新增页面的一致性。

VI Build 不能承诺对所有 PowerPoint master、SmartArt、动画和 OOXML 行为 进行像素级复刻，详细边界见 template-brand.md。

Build Mode

Build Mode 是交付级路径。LLM 生成普通 Python 文件，布局、文案、颜色和 数据都可以在 Git 中审查、修改和重复构建：

from pptx_designer import Presentation
from pptx_designer.tools.cards import kpi_card
from pptx_designer.tools.layout import page_header
from pptx_designer.tools.shapes import rect

C = {
    "primary": "#1D78FA",
    "accent": "#FF6B35",
    "background": "#FFFFFF",
    "text_dark": "#172554",
    "text_body": "#475569",
}

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6])
page_header(slide, "Q4 Revenue Report", "Financial Summary", C=C)
kpi_card(slide, 1.0, 2.0, 3.5, 1.5, "$12.8M", "Revenue", "+23%", C=C)
rect(slide, 0.5, 6.8, 12.3, 0.08, fill="primary", C=C)
prs.save("output/report.pptx")

Build Mode 规则：

• 所有坐标使用英寸；
• 使用 pptx_designer 公共 API；
• 优先使用原生文本、形状、图表和图示；
• 使用 cover_image() 保持图片比例；
• 颜色集中在设计 token 或 C 字典中；
• 不使用旧版 ppt_pro_max 或私有模块；
• 生成后必须运行、重开、导出和视觉检查。

设计过程中的三个控制量

这些控制量影响页面结构和信息节奏，不是简单的颜色开关。科研、学术和 医疗场景通常需要降低装饰和动效，即使主题本身是科技方向。

重要禁止行为

• 没有需求和页面结构就直接生成完整交付 PPT；
• 只换颜色、字体就把多个方案称为结构不同；
• 每页重复同一种卡片或项目符号布局；
• 用小字号容纳未经编辑的过量内容；
• 编造精确指标、客户案例、引用或证据；
• 拉伸图片或使用与内容无关的图片；
• 把整页内容烘焙为截图，替代可编辑对象；
• 将商业融资模板套用到科研、论文、医疗内容；
• 只确认 Python 和 PPTX 文件成功，不查看 PNG；
• PNG 发现问题后不重新生成、不重新检查。

运行和渲染

如需重新安装或升级 Python 运行时，可以直接运行安装器；它会自动处理 pptx-designer：

python installer/install.py --platform opencode --force
python skill/scripts/check_runtime.py

安装技能到编码工具：

python installer/install.py --platform claude --force
python installer/install.py --platform codex --force
python installer/install.py --platform opencode --force
python installer/install.py --platform deepseek-harness --force

导出 PPTX、PDF 和 PNG：

powershell -ExecutionPolicy Bypass -File skill/scripts/render_pptx.ps1 `
  -InFile examples/output/luxury_fragrance_lookbook.pptx `
  -OutDir output/luxury-fragrance-rendered

渲染器优先使用 Microsoft PowerPoint COM；无 PowerPoint 时使用 LibreOffice 生成 PDF，再使用 Poppler 的 pdftoppm 生成 PNG。桌面渲染器属于系统依赖， 可以显式执行：

python installer/install.py --render-deps

交付清单

正式交付通常包含：

• .pptx 文件；
• 可重复构建的 Python 源码或结构化 content；
• .pdf 预览文件；
• 每页 PNG 或联系表；
• 基础结构检查结果；
• PNG 视觉检查结果；
• 用户最终确认记录。

目录结构

PPT-Design-Skill/
├── skill/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── references/
│   └── scripts/
├── docs/assets/cases/
│   ├── contact-sheet.png
│   └── representative slide previews
├── examples/output/
│   ├── luxury_fragrance_lookbook.pptx
│   ├── couture_editorial_deck.pptx
│   └── architecture_vision_book.pptx
├── installer/
├── docs/
├── install.py
└── skill.json