pptx-generator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePPTX Presentation Generator
PPTX演示文稿生成器
Operator Context
操作方上下文
This skill operates as an operator for programmatic presentation generation, configuring Claude's behavior for a 6-phase pipeline that transforms content into polished PowerPoint decks. It uses (pure Python, MIT licensed) for deterministic slide construction and a visual QA subagent loop for quality control.
python-pptxCore thesis: "Slides are visual documents, not text dumps. Generate mechanically, validate visually."
The pipeline separates content decisions (LLM) from slide construction (Python script) from visual validation (subagent). This separation prevents the common failure mode where the generator rationalizes away visual defects it introduced.
本技能作为程序化演示文稿生成的操作方,配置Claude的行为以执行六阶段流程,将内容转换为精美的PowerPoint演示文稿。它使用(纯Python,MIT许可证)进行确定性幻灯片构建,并通过视觉QA子代理循环进行质量控制。
python-pptx核心理念:“幻灯片是视觉文档,而非文本堆砌。机械生成,视觉验证。”
该流程将内容决策(LLM)、幻灯片构建(Python脚本)和视觉验证(子代理)分离。这种分离避免了常见的失败模式:生成器会合理化自己引入的视觉缺陷。
Hardcoded Behaviors (Always Apply)
硬编码行为(始终适用)
- CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution. Project instructions override default behaviors.
- Over-Engineering Prevention: Build the deck the user asked for. No speculative slides, no "bonus" content, no unsolicited animations or transitions.
- Anti-AI Slide Rules: Every generated deck MUST avoid the 10 anti-AI patterns defined in . Why: AI-generated slides have a distinctive "template pack" aesthetic that undermines credibility. The QA subagent checks for all violations.
references/anti-ai-slide-rules.md - Deterministic Generation: Slide construction happens via , not inline python-pptx code. Why: scripts are testable, reproducible, and save tokens. The LLM decides WHAT goes on slides; the script decides HOW.
scripts/generate_pptx.py - Blank Layout Only: Always use (blank) as the base layout. Why: using template-specific layouts (title, content) inherits unpredictable formatting from whatever default template python-pptx ships. Blank gives us full control.
slide_layouts[6] - Safe Fonts Only: Use Calibri and Arial exclusively. Why: presentations are shared documents. Custom fonts cause rendering failures on machines that lack them. Portability trumps aesthetics.
- Slide Map Approval: Always present the slide map to the user for approval before generating the PPTX. Why: content rework after generation wastes QA iteration budget.
- CLAUDE.md合规性:执行前阅读并遵循仓库中的CLAUDE.md文件。项目说明优先于默认行为。
- 防止过度设计:构建用户要求的演示文稿。不添加推测性幻灯片、“额外”内容,不主动添加动画或转场效果。
- 反AI幻灯片规则:每个生成的演示文稿必须避免中定义的10种反AI模式。原因:AI生成的幻灯片具有独特的“模板包”美学,会损害可信度。QA子代理会检查所有违规情况。
references/anti-ai-slide-rules.md - 确定性生成:幻灯片构建通过完成,而非内联python-pptx代码。原因:脚本可测试、可复现,且节省token。LLM决定幻灯片的内容,脚本决定如何实现。
scripts/generate_pptx.py - 仅使用空白布局:始终使用(空白)作为基础布局。原因:使用特定模板布局(标题、内容)会继承python-pptx默认模板中不可预测的格式。空白布局让我们完全控制样式。
slide_layouts[6] - 仅使用安全字体:仅使用Calibri和Arial字体。原因:演示文稿是共享文档。自定义字体在缺少该字体的机器上会导致渲染失败。便携性优先于美观。
- 幻灯片地图审批:在生成PPTX之前,必须向用户展示幻灯片地图并获得批准。原因:生成后再修改内容会浪费QA迭代预算。
Default Behaviors (ON unless disabled)
默认行为(启用状态,除非禁用)
- Communication Style: Fact-based progress. "Generated 10 slides, Corporate palette, QA passed" -- not "I've crafted a stunning presentation."
- Palette Selection: Auto-select palette based on presentation type and audience using the heuristic in . Default to Minimal when uncertain.
references/design-system.md - Widescreen Format: 16:9 (13.333 x 7.5 inches). This is the universal modern presentation format.
- Visual QA Loop: When LibreOffice is available, convert to images and run a QA subagent. Max 3 fix iterations. When LibreOffice is unavailable, fall back to structural validation only and note the skip.
- Cleanup: Remove intermediate files (PDFs, PNGs, temp JSON) after final output.
- Absolute Paths: Always use absolute paths for all file arguments to scripts.
- 沟通风格:基于事实的进度汇报。例如“已生成10张幻灯片,使用Corporate配色方案,QA通过”——而非“我已制作了一份惊艳的演示文稿”。
- 配色方案选择:根据演示文稿类型和受众,使用中的启发式规则自动选择配色方案。不确定时默认使用Minimal方案。
references/design-system.md - 宽屏格式:16:9(13.333 x 7.5英寸)。这是现代演示文稿的通用格式。
- 视觉QA循环:当LibreOffice可用时,将演示文稿转换为图像并运行QA子代理。最多进行3次修复迭代。当LibreOffice不可用时,仅进行结构验证并记录跳过情况。
- 清理:最终输出后删除中间文件(PDF、PNG、临时JSON)。
- 绝对路径:所有脚本的文件参数始终使用绝对路径。
Optional Behaviors (OFF unless enabled)
可选行为(禁用状态,除非启用)
- Template-Based Generation: Use an existing .pptx file as a template instead of blank. Enable when user provides a branded template.
- Image Embedding: Embed user-provided images into slides. Enable when user provides image files or paths.
- Speaker Notes: Add speaker notes to slides. Enable when user explicitly requests notes.
- Dark Theme: Use the Midnight palette with inverted contrast. Enable when user requests dark slides or keynote-style dark decks.
- 基于模板的生成:使用现有.pptx文件作为模板,而非空白布局。当用户提供品牌模板时启用。
- 图片嵌入:将用户提供的图片嵌入幻灯片。当用户提供图片文件或路径时启用。
- 演讲者备注:为幻灯片添加演讲者备注。仅当用户明确要求时启用。
- 深色主题:使用Midnight配色方案并反转对比度。当用户要求深色幻灯片或主题演讲风格的深色演示文稿时启用。
What This Skill CAN Do
本技能可实现的功能
- Generate complete .pptx slide decks from content outlines, documents, or freeform descriptions
- Apply 8 curated color palettes with consistent typography and spacing
- Build 8 layout types: title, section divider, content/bullets, two-column, image+text, quote/callout, table, closing
- Validate generated slides structurally (slide count, titles, content presence)
- Run visual QA via LibreOffice conversion and subagent inspection (when LibreOffice is available)
- Use existing .pptx files as templates for branded decks
- Embed user-provided images into slides
- 从内容大纲、文档或自由格式描述生成完整的.pptx幻灯片演示文稿
- 应用8种精心设计的配色方案,搭配一致的排版和间距
- 构建8种布局类型:标题页、章节分隔页、内容/项目符号、双栏、图片+文本、引用/标注、表格、结束页
- 从结构上验证生成的幻灯片(幻灯片数量、标题、内容存在性)
- 通过LibreOffice转换和子代理检查运行视觉QA(当LibreOffice可用时)
- 使用现有.pptx文件作为模板生成品牌化演示文稿
- 将用户提供的图片嵌入幻灯片
What This Skill CANNOT Do
本技能无法实现的功能
- Google Slides or Keynote export: Generates .pptx only. Users convert manually.
- Live editing or preview: Produces a file; there is no interactive editing capability.
- Custom fonts: Only Calibri and Arial for portability. Custom font embedding is not supported.
- Animations or transitions: No animations by default. Python-pptx has limited animation support; even if requested, results are unreliable.
- Auto-generate images: Does not create diagrams, charts, or illustrations. Pair with for image assets.
gemini-image-generator - Speaker notes generation: Deferred to future version. The skill generates slides, not presenter scripts.
- 导出为Google Slides或Keynote格式:仅生成.pptx格式。用户需手动转换。
- 实时编辑或预览:仅生成文件,无交互式编辑功能。
- 自定义字体:仅支持Calibri和Arial以保证便携性。不支持自定义字体嵌入。
- 动画或转场效果:默认无动画。python-pptx的动画支持有限;即使请求,结果也不可靠。
- 自动生成图片:不创建图表、图形或插图。如需图片资产,可与搭配使用。
gemini-image-generator - 生成演讲者备注:该功能推迟到未来版本。本技能仅生成幻灯片,不生成演示者脚本。
Instructions
操作说明
Phase 1: GATHER
阶段1:收集
Goal: Collect content, determine presentation structure, identify the presentation type.
Why this phase exists: Jumping straight to slide design without understanding the content produces a generic deck that doesn't serve the audience. Gathering first ensures every slide has a purpose.
Step 1: Parse the user request
Extract from the user's input:
- Topic: What is the presentation about?
- Audience: Who will view it? (executives, engineers, students, general public)
- Tone: Formal, casual, technical, inspirational?
- Slide count: Explicit request or estimate from content volume. Default: 8-12 slides.
- Presentation type: Classify as one of:
- Pitch deck: Investor/stakeholder persuasion
- Tech talk: Engineering audience, architecture, code
- Status update: Progress report, metrics, next steps
- Educational: Teaching, workshop, tutorial
- General: Does not fit above categories
Step 2: Extract content
If the user provides source material (document, outline, notes, article):
- Extract key points, data, and quotes
- Organize into logical sections
- Identify content that maps to specific slide types (data -> table, key insight -> quote, comparison -> two-column)
If no source material is provided:
- Work with the user to develop an outline
- Ask clarifying questions about scope and depth
If the user provides an existing .pptx as a template:
- Read it with python-pptx to understand the existing structure
- Plan which slides to modify vs. add
Step 3: Determine slide structure
Based on content volume and presentation type, plan the slide sequence. Follow the layout rhythm guidelines in :
references/slide-layouts.md| Deck Size | Rhythm Pattern |
|---|---|
| Short (5-8) | Title, Content, Content, Two-Column, Content, Closing |
| Medium (8-12) | Title, Content, Content, Quote, Section, Content, Two-Column, Content, Closing |
| Long (12+) | Title, Content, Content, Quote, Section, Content, Image+Text, Content, Section, Two-Column, Table, Content, Closing |
GATE: Content outline exists with at least 1 key point per planned slide. Presentation type identified. Slide count determined. If the user's content is too thin for the requested slide count, flag this and suggest a smaller deck rather than padding with filler.
目标:收集内容,确定演示文稿结构,明确演示文稿类型。
该阶段存在的原因:不理解内容就直接进行幻灯片设计会生成无法满足受众需求的通用演示文稿。先收集信息可确保每张幻灯片都有明确的目的。
步骤1:解析用户请求
从用户输入中提取:
- 主题:演示文稿的主题是什么?
- 受众:谁会观看?(高管、工程师、学生、普通大众)
- 语气:正式、随意、技术化、鼓舞人心?
- 幻灯片数量:明确要求或根据内容量估算。默认:8-12张幻灯片。
- 演示文稿类型:归类为以下类型之一:
- 推介文档(Pitch deck):面向投资者/利益相关者的说服性演示
- 技术演讲:面向工程师受众,涉及架构、代码等
- 状态更新:进度报告、指标、下一步计划
- 教育类:教学、工作坊、教程
- 通用类:不符合上述类别
步骤2:提取内容
如果用户提供源材料(文档、大纲、笔记、文章):
- 提取关键点、数据和引用
- 组织为逻辑章节
- 识别适合特定幻灯片类型的内容(数据→表格、关键见解→引用、对比→双栏)
如果未提供源材料:
- 与用户协作制定大纲
- 询问关于范围和深度的澄清问题
如果用户提供现有.pptx作为模板:
- 使用python-pptx读取以理解现有结构
- 规划要修改和添加的幻灯片
步骤3:确定幻灯片结构
根据内容量和演示文稿类型,规划幻灯片顺序。遵循中的布局节奏指南:
references/slide-layouts.md| 演示文稿大小 | 节奏模式 |
|---|---|
| 短(5-8张) | 标题页、内容页、内容页、双栏页、内容页、结束页 |
| 中(8-12张) | 标题页、内容页、内容页、引用页、章节页、内容页、双栏页、内容页、结束页 |
| 长(12张以上) | 标题页、内容页、内容页、引用页、章节页、内容页、图片+文本页、内容页、章节页、双栏页、表格页、内容页、结束页 |
关卡:内容大纲已存在,且每张规划的幻灯片至少有一个关键点。已明确演示文稿类型。已确定幻灯片数量。如果用户的内容不足以支撑请求的幻灯片数量,需标记此问题并建议减少幻灯片数量,而非添加填充内容。
Phase 2: DESIGN
阶段2:设计
Goal: Select palette and typography, produce the slide map, get user approval before generation.
Why this phase exists: Design decisions made after generation are expensive -- they require regenerating the entire deck. Making them upfront and getting user approval saves iteration budget for visual fixes, not content rework.
Step 1: Select color palette
Use the palette selection heuristic from :
references/design-system.md| Presentation Type | Recommended Palette | Fallback |
|---|---|---|
| Business / Finance | Corporate | Minimal |
| Engineering / Dev talk | Tech | Minimal |
| Creative / Workshop | Warm | Sunset |
| Healthcare / Sustainability | Ocean | Forest |
| Dark theme keynote | Midnight | Tech |
| Environmental / Nonprofit | Forest | Ocean |
| Startup / Energy | Sunset | Warm |
| Unknown / General | Minimal | Corporate |
If the user specifies a palette preference, use it. When in doubt, use Minimal.
Step 2: Plan layout rhythm
Select layout types for each slide. Use at least 2-3 distinct layout types to avoid the "AI-generated sameness" anti-pattern. See for all layout types.
references/slide-layouts.mdAvailable layouts: , (divider), (bullets), , , (callout), ,
titlesectioncontenttwo_columnimage_textquotetableclosingLayout rhythm rules:
- Never use the same layout more than 3 times in a row
- For 10+ slide decks, use at least 3 distinct layout types
- Insert a different layout type (quote, two-column, section divider) to break repetition
Step 3: Produce the slide map
Create a JSON array where each element represents one slide:
json
[
{
"type": "title",
"title": "Presentation Title",
"subtitle": "Subtitle or author"
},
{
"type": "content",
"title": "Slide Headline",
"bullets": ["Point 1", "Point 2", "Point 3"]
},
{
"type": "two_column",
"title": "Comparison",
"left": {"header": "Option A", "bullets": ["Pro 1", "Pro 2"]},
"right": {"header": "Option B", "bullets": ["Pro 1", "Pro 2"]}
},
{
"type": "quote",
"quote": "Key insight or memorable statement",
"attribution": "Speaker Name"
},
{
"type": "table",
"title": "Data Overview",
"headers": ["Column A", "Column B", "Column C"],
"rows": [["r1c1", "r1c2", "r1c3"], ["r2c1", "r2c2", "r2c3"]]
},
{
"type": "closing",
"title": "Thank You",
"subtitle": "contact@example.com"
}
]Step 4: Validate the slide map against anti-AI rules
Before presenting to the user, check:
- At least 2-3 distinct layout types used (not all )
content - No more than 3 consecutive slides with the same layout
- Max 6 bullets per content slide, max 10 words per bullet
- Title slide is first, closing slide is last (if appropriate)
- Section dividers placed before new sections (for 8+ slide decks)
See for the full checklist.
references/anti-ai-slide-rules.mdStep 5: Present slide map for user approval
Show the user the planned deck structure:
SLIDE MAP (10 slides, Corporate palette):
1. [Title] "Q4 Revenue Analysis"
2. [Content] "Executive Summary" (4 bullets)
3. [Content] "Revenue by Region" (5 bullets)
4. [Quote] Key insight from CFO
5. [Section] "Deep Dive: EMEA"
6. [Two-Column] EMEA vs APAC comparison
7. [Content] "Contributing Factors" (4 bullets)
8. [Table] Quarterly figures
9. [Content] "Recommendations" (3 bullets)
10. [Closing] "Questions?"
Approve this structure, or suggest changes?GATE: User approves the slide map. If the user requests changes, update the slide map and re-present. Do not proceed to generation without explicit approval. Why: regeneration costs iteration budget that should be reserved for visual QA fixes.
目标:选择配色方案和排版,生成幻灯片地图,在生成前获得用户批准。
该阶段存在的原因:生成后再做设计决策成本很高——需要重新生成整个演示文稿。提前做出设计决策并获得用户批准,可将迭代预算节省下来用于视觉修复,而非内容返工。
步骤1:选择配色方案
使用中的配色方案选择启发式规则:
references/design-system.md| 演示文稿类型 | 推荐配色方案 | 备选方案 |
|---|---|---|
| 商务/金融 | Corporate | Minimal |
| 工程/技术演讲 | Tech | Minimal |
| 创意/工作坊 | Warm | Sunset |
| 医疗/可持续发展 | Ocean | Forest |
| 深色主题主题演讲 | Midnight | Tech |
| 环保/非营利组织 | Forest | Ocean |
| 创业/能源 | Sunset | Warm |
| 未知/通用 | Minimal | Corporate |
如果用户指定了配色方案偏好,则使用该方案。不确定时使用Minimal方案。
步骤2:规划布局节奏
为每张幻灯片选择布局类型。至少使用2-3种不同的布局类型,以避免“AI生成的雷同感”反模式。有关所有布局类型,请参阅。
references/slide-layouts.md可用布局:、(分隔页)、(项目符号)、、、(标注)、、
titlesectioncontenttwo_columnimage_textquotetableclosing布局节奏规则:
- 连续使用同一布局不超过3次
- 对于10张以上的演示文稿,至少使用3种不同的布局类型
- 插入不同的布局类型(引用、双栏、章节分隔页)以打破重复
步骤3:生成幻灯片地图
创建一个JSON数组,其中每个元素代表一张幻灯片:
json
[
{
"type": "title",
"title": "演示文稿标题",
"subtitle": "副标题或作者"
},
{
"type": "content",
"title": "幻灯片标题",
"bullets": ["要点1", "要点2", "要点3"]
},
{
"type": "two_column",
"title": "对比",
"left": {"header": "选项A", "bullets": ["优势1", "优势2"]},
"right": {"header": "选项B", "bullets": ["优势1", "优势2"]}
},
{
"type": "quote",
"quote": "关键见解或难忘语句",
"attribution": "演讲者姓名"
},
{
"type": "table",
"title": "数据概览",
"headers": ["列A", "列B", "列C"],
"rows": [["r1c1", "r1c2", "r1c3"], ["r2c1", "r2c2", "r2c3"]]
},
{
"type": "closing",
"title": "谢谢观看",
"subtitle": "contact@example.com"
}
]步骤4:根据反AI规则验证幻灯片地图
向用户展示之前,检查:
- 至少使用2-3种不同的布局类型(不全部为)
content - 连续使用同一布局不超过3次
- 每张内容幻灯片最多6个项目符号,每个项目符号最多10个单词
- 标题页在最前,结束页在最后(如适用)
- 章节分隔页放置在新章节之前(对于8张以上的演示文稿)
完整清单请参阅。
references/anti-ai-slide-rules.md步骤5:向用户展示幻灯片地图以获得批准
向用户展示规划的演示文稿结构:
幻灯片地图(10张幻灯片,Corporate配色方案):
1. [标题页] "Q4收入分析"
2. [内容页] "执行摘要"(4个项目符号)
3. [内容页] "各地区收入"(5个项目符号)
4. [引用页] 首席财务官的关键见解
5. [章节页] "深入分析:欧洲、中东和非洲地区"
6. [双栏页] 欧洲、中东和非洲地区与亚太地区对比
7. [内容页] "影响因素"(4个项目符号)
8. [表格页] 季度数据
9. [内容页] "建议"(3个项目符号)
10. [结束页] "有问题吗?"
是否批准此结构,或建议修改?关卡:用户批准幻灯片地图。如果用户要求修改,更新幻灯片地图并重新展示。未获得明确批准不得进入生成阶段。原因:重新生成会消耗本应留给视觉QA修复的迭代预算。
Phase 3: GENERATE
阶段3:生成
Goal: Execute the deterministic Python script to produce the .pptx file.
Why this phase exists: Slide construction is mechanical work -- given a slide map and design config, the output is deterministic. This belongs in a script, not in LLM-generated inline code. Scripts are testable, reproducible, and consistent.
Step 1: Check dependencies
bash
python3 -c "from pptx import Presentation; print('python-pptx OK')"If python-pptx is not installed, install it:
bash
pip install python-pptx PillowStep 2: Write the slide map and design config to JSON files
Save the approved slide map and design config to temporary files:
bash
undefined目标:执行确定性Python脚本以生成.pptx文件。
该阶段存在的原因:幻灯片构建是机械性工作——给定幻灯片地图和设计配置,输出是确定性的。这应该由脚本完成,而非LLM生成的内联代码。脚本可测试、可复现且一致。
步骤1:检查依赖项
bash
python3 -c "from pptx import Presentation; print('python-pptx OK')"如果未安装python-pptx,则安装:
bash
pip install python-pptx Pillow步骤2:将幻灯片地图和设计配置写入JSON文件
将批准的幻灯片地图和设计配置保存到临时文件:
bash
undefinedWrite slide map JSON to temp file
将幻灯片地图JSON写入临时文件
python3 -c "
import json
slide_map = [...] # the approved slide map
with open('/tmp/slide_map.json', 'w') as f:
json.dump(slide_map, f, indent=2)
"
python3 -c "
import json
slide_map = [...] # 已批准的幻灯片地图
with open('/tmp/slide_map.json', 'w') as f:
json.dump(slide_map, f, indent=2)
"
Write design config JSON
写入设计配置JSON
python3 -c "
import json
design = {'palette': 'corporate'} # whichever palette was selected
with open('/tmp/design_config.json', 'w') as f:
json.dump(design, f, indent=2)
"
**Step 3: Run the generation script**
```bash
python3 /path/to/skills/pptx-generator/scripts/generate_pptx.py \
--slide-map /tmp/slide_map.json \
--design /tmp/design_config.json \
--output /absolute/path/to/output.pptxExit codes: 0 = success, 1 = missing python-pptx, 2 = invalid input, 3 = generation failed.
Step 4: Run structural validation
bash
python3 /path/to/skills/pptx-generator/scripts/validate_structure.py \
--input /absolute/path/to/output.pptx \
--slide-map /tmp/slide_map.jsonThis validates: slide count matches, each slide has text content, title slide exists, no empty slides.
GATE: .pptx file exists with non-zero size AND structural validation passes. If validation fails, diagnose the issue (usually a slide map JSON problem), fix, and re-run. Max 2 retries at this gate before escalating to the user.
python3 -c "
import json
design = {'palette': 'corporate'} # 所选的配色方案
with open('/tmp/design_config.json', 'w') as f:
json.dump(design, f, indent=2)
"
**步骤3:运行生成脚本**
```bash
python3 /path/to/skills/pptx-generator/scripts/generate_pptx.py \
--slide-map /tmp/slide_map.json \
--design /tmp/design_config.json \
--output /absolute/path/to/output.pptx退出代码:0 = 成功,1 = 缺少python-pptx,2 = 输入无效,3 = 生成失败。
步骤4:运行结构验证
bash
python3 /path/to/skills/pptx-generator/scripts/validate_structure.py \
--input /absolute/path/to/output.pptx \
--slide-map /tmp/slide_map.json此验证检查:幻灯片数量匹配、每张幻灯片有文本内容、存在标题页、无空白幻灯片。
关卡:.pptx文件存在且非零大小,且结构验证通过。如果验证失败,诊断问题(通常是幻灯片地图JSON问题),修复后重新运行。此关卡最多重试2次,之后需向用户升级问题。
Phase 4: CONVERT (Requires LibreOffice)
阶段4:转换(需要LibreOffice)
Goal: Convert the .pptx to per-slide PNG images for visual QA.
Why this phase exists: The QA subagent cannot read .pptx files. It needs rendered images to evaluate visual quality -- text clipping, color contrast, alignment, and anti-AI violations are only visible in rendered output.
Step 1: Check LibreOffice availability
bash
soffice --version 2>/dev/nullIf LibreOffice is not installed:
- Log: "LibreOffice not available. Skipping visual QA, using structural validation only."
- Skip Phase 5 (QA) and proceed directly to Phase 6 (OUTPUT)
- Note in the output report that visual QA was skipped
Step 2: Run the conversion script
bash
python3 /path/to/skills/pptx-generator/scripts/convert_slides.py \
--input /absolute/path/to/output.pptx \
--output-dir /tmp/pptx_qa_images/ \
--dpi 150Exit codes: 0 = success, 1 = no LibreOffice, 2 = conversion failed, 3 = invalid input.
Step 3: Verify conversion output
Check that one PNG exists per slide. If fewer PNGs than slides, some slides may have failed to render. Note which slides are missing.
GATE: Either (a) one PNG per slide exists, proceed to Phase 5, or (b) LibreOffice unavailable, skip to Phase 6 with a note. If conversion partially fails (some PNGs missing), proceed to QA with available images and note the gaps.
目标:将.pptx转换为单张幻灯片的PNG图像,用于视觉QA。
该阶段存在的原因:QA子代理无法读取.pptx文件。它需要渲染后的图像来评估视觉质量——文本截断、颜色对比度、对齐方式和反AI违规情况只有在渲染输出中才可见。
步骤1:检查LibreOffice可用性
bash
soffice --version 2>/dev/null如果未安装LibreOffice:
- 记录:"LibreOffice不可用。跳过视觉QA,仅使用结构验证。"
- 跳过阶段5(QA),直接进入阶段6(输出)
- 在输出报告中记录视觉QA已跳过
步骤2:运行转换脚本
bash
python3 /path/to/skills/pptx-generator/scripts/convert_slides.py \
--input /absolute/path/to/output.pptx \
--output-dir /tmp/pptx_qa_images/ \
--dpi 150退出代码:0 = 成功,1 = 无LibreOffice,2 = 转换失败,3 = 输入无效。
步骤3:验证转换输出
检查每张幻灯片是否对应一个PNG文件。如果PNG数量少于幻灯片数量,某些幻灯片可能渲染失败。记录缺失的幻灯片。
关卡:要么(a)每张幻灯片都有对应的PNG文件,进入阶段5;要么(b)LibreOffice不可用,跳过到阶段6并记录。如果转换部分失败(部分PNG缺失),使用可用图像进入QA并记录缺口。
Phase 5: QA (Visual Inspection Loop)
阶段5:QA(视觉检查循环)
Goal: A fresh-eyes subagent inspects the rendered slides and identifies visual issues. Fix and re-render up to 3 times.
Why a subagent: The generating agent has context bias -- it "knows" what the slide should look like and will rationalize visual problems. A fresh-eyes subagent with zero generation context sees the slide as a viewer would. This is the same anti-bias pattern as the voice-validator: the generator and the validator must be separate.
Why max 3 iterations: If visual issues persist after 3 fix cycles, the design is wrong, not the implementation. Looping further produces diminishing returns and wastes context.
Step 1: Dispatch QA subagent
Launch a subagent (via Task tool) with:
- The slide PNG images (one per slide)
- The original slide map for content comparison
- The QA checklist from
references/qa-checklist.md
The subagent checks each slide against these categories:
- Text Readability: Not clipped, not overlapping, sufficient contrast, adequate font size
- Layout and Alignment: Consistent margins, aligned elements, visual balance
- Color Usage: Palette consistency, max 3 colors per slide, adequate contrast
- Content Accuracy: Titles and bullets match the slide map
- Anti-AI Violations: All 10 rules from
references/anti-ai-slide-rules.md - Structural Checks: Slide count, title slide present, closing slide present
Subagent prompt structure:
You are a visual QA inspector for a PowerPoint presentation. You have ZERO
context about how these slides were generated. Evaluate each slide image
against the QA checklist.
For each slide, check:
1. Text readability (not clipped, not overlapping, adequate size, sufficient contrast)
2. Layout and alignment (consistent margins, aligned elements, visual balance)
3. Color usage (palette consistency, max 3 colors per slide)
4. Content accuracy (title matches expected, content present)
5. Anti-AI violations (accent lines under titles, gradient backgrounds, identical layouts,
shadows on everything, rounded rectangles everywhere, clip art icons, gradient text)
Return per-slide results:
SLIDE QA RESULT: [PASS | FAIL]
Slides checked: N
Issues found: M
SLIDE 1: PASS | FAIL
- [Category] Issue description
FIX: Specific fix instruction
...
OVERALL: PASS | FAIL (N issues on M slides)Step 2: Process QA results
If QA returns PASS: proceed to Phase 6.
If QA returns FAIL with Blocker or Major issues:
- Parse the fix instructions
- Modify the slide map JSON to address each issue (e.g., shorten a title, reduce bullet count, change layout type)
- Re-run Phase 3 (GENERATE) and Phase 4 (CONVERT)
- Re-dispatch the QA subagent
Severity levels:
- Blocker: Must fix (text unreadable, content missing, wrong slide order)
- Major: Should fix (alignment off, anti-AI violation, contrast issue)
- Minor: Report but do not require a fix cycle (slightly suboptimal spacing)
Only Blocker and Major issues trigger a fix iteration.
Track iteration count:
QA Iteration 1/3: 2 issues found (1 Blocker, 1 Major)
QA Iteration 2/3: 1 issue found (1 Minor)
QA Iteration 2/3: PASS (0 Blocker, 0 Major)GATE: QA subagent returns PASS, OR 3 iterations exhausted. If iterations exhausted with remaining issues, include them in the output report. Do not loop beyond 3.
目标:由一个“新鲜视角”的子代理检查渲染后的幻灯片并识别视觉问题。最多修复并重新渲染3次。
为何使用子代理:生成代理存在上下文偏见——它“知道”幻灯片应该是什么样子,会合理化视觉问题。一个没有生成上下文的“新鲜视角”子代理会像观众一样看待幻灯片。这与语音验证器的反偏见模式相同:生成器和验证器必须分离。
为何最多3次迭代:如果3次修复循环后视觉问题仍然存在,说明设计存在问题,而非实现问题。进一步循环会产生递减的回报,并浪费上下文。
步骤1:调度QA子代理
启动子代理(通过任务工具),提供:
- 幻灯片PNG图像(每张幻灯片一个)
- 用于内容对比的原始幻灯片地图
- 中的QA清单
references/qa-checklist.md
子代理根据以下类别检查每张幻灯片:
- 文本可读性:无截断、无重叠、对比度足够、字体大小合适
- 布局与对齐:边距一致、元素对齐、视觉平衡
- 颜色使用:配色方案一致、每张幻灯片最多3种颜色、对比度足够
- 内容准确性:标题和项目符号与幻灯片地图匹配
- 反AI违规:中的所有10条规则
references/anti-ai-slide-rules.md - 结构检查:幻灯片数量、存在标题页、存在结束页
子代理提示结构:
你是PowerPoint演示文稿的视觉QA检查员。你对这些幻灯片的生成过程一无所知。根据QA清单评估每张幻灯片图像。
对每张幻灯片检查:
1. 文本可读性(无截断、无重叠、大小合适、对比度足够)
2. 布局与对齐(边距一致、元素对齐、视觉平衡)
3. 颜色使用(配色方案一致、每张幻灯片最多3种颜色)
4. 内容准确性(标题与预期一致、内容存在)
5. 反AI违规(标题下的装饰线、渐变背景、相同布局、所有元素带阴影、到处是圆角矩形、剪贴画图标、渐变文本)
返回每张幻灯片的结果:
幻灯片QA结果:[通过 | 失败]
已检查幻灯片数量:N
发现问题数量:M
幻灯片1:通过 | 失败
- [类别] 问题描述
修复:具体修复说明
...
总体:通过 | 失败(M张幻灯片存在N个问题)步骤2:处理QA结果
如果QA返回通过:进入阶段6。
如果QA返回失败且存在阻塞或主要问题:
- 解析修复说明
- 修改幻灯片地图JSON以解决每个问题(例如,缩短标题、减少项目符号数量、更改布局类型)
- 重新运行阶段3(生成)和阶段4(转换)
- 重新调度QA子代理
严重程度级别:
- 阻塞:必须修复(文本不可读、内容缺失、幻灯片顺序错误)
- 主要:应该修复(对齐错误、反AI违规、对比度问题)
- 次要:报告但无需修复(间距略不理想)
只有阻塞和主要问题会触发修复迭代。
跟踪迭代次数:
QA迭代1/3:发现2个问题(1个阻塞,1个主要)
QA迭代2/3:发现1个问题(1个次要)
QA迭代2/3:通过(0个阻塞,0个主要)关卡:QA子代理返回通过,或已完成3次迭代。如果迭代次数用尽仍有问题,将其包含在输出报告中。不要循环超过3次。
Phase 6: OUTPUT
阶段6:输出
Goal: Deliver the final .pptx file with a summary report. Clean up intermediate files.
Step 1: Move the final .pptx to the user's working directory
Copy from temp location to a sensible output path:
- If user specified an output path, use it
- Otherwise: or
./presentation.pptx./[topic-slug].pptx
Step 2: Generate the output report
===============================================================
PRESENTATION GENERATED
===============================================================
File: /absolute/path/to/presentation.pptx
Slides: 10
Palette: Corporate
Format: 16:9 widescreen
Size: 45,230 bytes
Slide Map:
1. [Title] "Q4 Revenue Analysis"
2. [Content] "Executive Summary"
3. [Content] "Revenue by Region"
4. [Quote] CFO insight
5. [Section] "Deep Dive: EMEA"
6. [Two-Column] EMEA vs APAC
7. [Content] "Contributing Factors"
8. [Table] Quarterly figures
9. [Content] "Recommendations"
10. [Closing] "Questions?"
QA Result: PASS (2 iterations, 3 issues fixed)
Notes:
- [any remaining minor issues or caveats]
===============================================================Step 3: Clean up intermediate files
Remove:
/tmp/slide_map.json/tmp/design_config.json- directory (PNG renders and PDFs)
/tmp/pptx_qa_images/
Keep only the final .pptx file.
目标:交付最终.pptx文件和摘要报告。清理中间文件。
步骤1:将最终.pptx移动到用户的工作目录
从临时位置复制到合理的输出路径:
- 如果用户指定了输出路径,则使用该路径
- 否则:或
./presentation.pptx./[主题-slug].pptx
步骤2:生成输出报告
===============================================================
演示文稿已生成
===============================================================
文件:/absolute/path/to/presentation.pptx
幻灯片数量:10
配色方案:Corporate
格式:16:9宽屏
大小:45,230字节
幻灯片地图:
1. [标题页] "Q4收入分析"
2. [内容页] "执行摘要"
3. [内容页] "各地区收入"
4. [引用页] 首席财务官的见解
5. [章节页] "深入分析:欧洲、中东和非洲地区"
6. [双栏页] 欧洲、中东和非洲地区与亚太地区对比
7. [内容页] "影响因素"
8. [表格页] 季度数据
9. [内容页] "建议"
10. [结束页] "有问题吗?"
QA结果:通过(2次迭代,修复3个问题)
备注:
- [任何剩余的次要问题或注意事项]
===============================================================步骤3:清理中间文件
删除:
/tmp/slide_map.json/tmp/design_config.json- 目录(PNG渲染文件和PDF)
/tmp/pptx_qa_images/
仅保留最终.pptx文件。
Examples
示例
Example 1: Tech Talk from Outline
示例1:基于大纲的技术演讲
User says: "Create a 10-slide presentation about our new microservices architecture"
Actions:
- GATHER: Topic = microservices migration, audience = engineering team, type = tech talk, 10 slides
- DESIGN: Select Tech palette, build slide map with title, 6 content slides, 1 two-column (monolith vs micro), 1 section divider, closing. Present for approval.
- GENERATE: Run with slide map and Tech palette
generate_pptx.py - CONVERT: PPTX to PNGs via LibreOffice
- QA: Subagent inspects 10 slide images, finds title text clipped on slide 4, fixes in iteration 2
- OUTPUT: , 10 slides, Tech palette, QA passed
microservices-architecture.pptx
用户说:“创建一个关于我们新微服务架构的10张幻灯片演示文稿”
操作:
- 收集:主题=微服务迁移,受众=工程团队,类型=技术演讲,10张幻灯片
- 设计:选择Tech配色方案,构建包含标题页、6张内容页、1张双栏页(单体架构vs微服务)、1张章节分隔页、结束页的幻灯片地图。展示以获得批准。
- 生成:使用幻灯片地图和Tech配色方案运行
generate_pptx.py - 转换:通过LibreOffice将PPTX转换为PNG
- QA:子代理检查10张幻灯片图像,发现第4张幻灯片标题文本截断,在第2次迭代中修复
- 输出:,1张幻灯片,Tech配色方案,QA通过
microservices-architecture.pptx
Example 2: Pitch Deck from Document
示例2:基于文档的推介文档
User says: "Turn this business plan into a pitch deck" (attaches document)
Actions:
- GATHER: Extract key sections from business plan (problem, solution, market, traction, team, ask), type = pitch deck, 12 slides
- DESIGN: Select Sunset palette for startup energy, build slide map with standard pitch structure. Present for approval.
- GENERATE: Run script with slide map
- CONVERT: PPTX to PNGs
- QA: Subagent catches identical layout on 4 consecutive slides, fixes by inserting quote and two-column layouts
- OUTPUT: , 12 slides, Sunset palette, QA passed after 2 iterations
pitch-deck.pptx
用户说:“把这份商业计划转换成推介文档”(附上文档)
操作:
- 收集:从商业计划中提取关键章节(问题、解决方案、市场、进展、团队、融资请求),类型=推介文档,12张幻灯片
- 设计:为创业活力选择Sunset配色方案,构建包含标准推介结构的幻灯片地图。展示以获得批准。
- 生成:使用幻灯片地图运行脚本
- 转换:PPTX转换为PNG
- QA:子代理发现4张连续幻灯片布局相同,通过插入引用页和双栏页修复
- 输出:,12张幻灯片,Sunset配色方案,2次迭代后QA通过
pitch-deck.pptx
Example 3: Status Update (No LibreOffice)
示例3:状态更新(无LibreOffice)
User says: "Quick status update slides for the weekly standup, 5 slides"
Actions:
- GATHER: Topic = weekly status, audience = team, type = status update, 5 slides
- DESIGN: Select Minimal palette, build compact slide map. Present for approval.
- GENERATE: Run script, structural validation passes
- CONVERT: LibreOffice not available, skip visual QA
- QA: Skipped
- OUTPUT: , 5 slides, Minimal palette, visual QA skipped
weekly-status.pptx
用户说:“为每周站会快速制作5张状态更新幻灯片”
操作:
- 收集:主题=每周状态,受众=团队,类型=状态更新,5张幻灯片
- 设计:选择Minimal配色方案,构建紧凑的幻灯片地图。展示以获得批准。
- 生成:运行脚本,结构验证通过
- 转换:LibreOffice不可用,跳过视觉QA
- QA:已跳过
- 输出:,5张幻灯片,Minimal配色方案,视觉QA已跳过
weekly-status.pptx
Error Handling
错误处理
Error: python-pptx Not Installed
错误:python-pptx未安装
Cause: The package is missing from the Python environment.
Solution: Run . This is a hard dependency -- the skill cannot function without it. Verify with .
python-pptxpip install python-pptx Pillowpython3 -c "from pptx import Presentation; print('OK')"原因:Python环境中缺少包。
解决方案:运行。这是硬依赖——本技能无法在缺少它的情况下运行。通过验证。
python-pptxpip install python-pptx Pillowpython3 -c "from pptx import Presentation; print('OK')"Error: LibreOffice Not Available
错误:LibreOffice不可用
Cause: binary not found on the system. Required for the visual QA loop (Phases 4-5).
Solution: This is a soft dependency. The skill degrades gracefully:
soffice- Log that visual QA is unavailable
- Skip Phases 4-5
- Rely on structural validation from
validate_structure.py - Note in the output report that visual QA was skipped
Install with: (Debian/Ubuntu) or (macOS).
apt install libreoffice-impressbrew install --cask libreoffice原因:系统中未找到二进制文件。视觉QA循环(阶段4-5)需要它。
解决方案:这是软依赖。本技能会优雅降级:
soffice- 记录视觉QA不可用
- 跳过阶段4-5
- 依赖进行结构验证
validate_structure.py - 在输出报告中记录视觉QA已跳过
安装方式:(Debian/Ubuntu)或(macOS)。
apt install libreoffice-impressbrew install --cask libreofficeError: Slide Map JSON Invalid
错误:幻灯片地图JSON无效
Cause: Malformed JSON, missing field, or unsupported layout type.
Solution:
type- Validate JSON syntax before passing to the script
- Check that every slide object has a field
type - Supported types: ,
title,section,content,two_column,quote,table,image_textclosing - Unknown types fall back to layout
content
原因:JSON格式错误、缺少字段或不支持的布局类型。
解决方案:
type- 传递给脚本前验证JSON语法
- 检查每个幻灯片对象是否有字段
type - 支持的类型:、
title、section、content、two_column、quote、table、image_textclosing - 未知类型会回退到布局
content
Error: Generated PPTX Empty or Corrupt
错误:生成的PPTX为空或损坏
Cause: Script error during generation, typically from invalid slide data (null values, missing arrays).
Solution:
- Run to identify the specific failure
validate_structure.py - Check the slide map JSON for null or missing fields
- Fix and re-generate. Max 2 retries before escalating.
原因:生成过程中脚本出错,通常是由于无效幻灯片数据(空值、缺失数组)。
解决方案:
- 运行以确定具体失败原因
validate_structure.py - 检查幻灯片地图JSON中的空值或缺失字段
- 修复后重新生成。最多重试2次,之后需升级问题。
Error: QA Loop Exceeds 3 Iterations
错误:QA循环超过3次迭代
Cause: Visual issues persist despite fixes. Usually indicates a fundamental design problem.
Solution: Do NOT continue iterating. Report remaining issues, suggest the user simplify content or change layout approach, deliver the best available version with caveats.
原因:尽管进行了修复,视觉问题仍然存在。通常表明存在根本性设计问题。
解决方案:不要继续迭代。报告剩余问题,建议用户简化内容或更改布局方法,交付可用的最佳版本并附带说明。
Anti-Patterns
反模式
Inline python-pptx Code Instead of Script
使用内联python-pptx代码而非脚本
What it looks like: Writing python-pptx code directly in a Bash tool call instead of using .
Why wrong: Inline code is not testable, wastes tokens on boilerplate, and risks inconsistency. The script encapsulates palette application, layout selection, font sizing, spacing rules, and all design system constraints.
Do instead: Always use . If the script lacks a feature, extend the script.
scripts/generate_pptx.pygenerate_pptx.py表现:在Bash工具调用中直接编写python-pptx代码,而非使用。
错误原因:内联代码不可测试,会在样板代码上浪费token,且存在不一致风险。脚本封装了配色方案应用、布局选择、字体大小、间距规则和所有设计系统约束。
正确做法:始终使用。如果脚本缺少功能,扩展脚本。
scripts/generate_pptx.pygenerate_pptx.pySkipping Slide Map Review
跳过幻灯片地图审核
What it looks like: Generating the .pptx immediately after gathering content, without showing the user the planned structure.
Why wrong: Content changes after generation waste QA iteration budget. If the user wanted different emphasis or ordering, you lose fix cycles to structural rework instead of visual fixes.
Do instead: Present the slide map in Phase 2 and wait for approval. This is a gate, not a suggestion.
表现:收集内容后立即生成.pptx,不向用户展示规划的结构。
错误原因:生成后更改内容会浪费QA迭代预算。如果用户想要不同的重点或顺序,你会将修复周期浪费在结构返工上,而非视觉修复。
正确做法:在阶段2展示幻灯片地图并等待批准。这是一个关卡,而非建议。
Same Layout for Every Slide
每张幻灯片使用相同布局
What it looks like: Every content slide uses the (bullets) layout.
Why wrong: Identical layouts are the most obvious AI-slide tell. Real presentations have visual rhythm with varied layouts.
Do instead: Use at least 2-3 distinct layout types. Insert quote, two-column, or section divider slides to break repetition.
content表现:所有内容幻灯片都使用(项目符号)布局。
错误原因:相同布局是最明显的AI生成幻灯片特征。真实的演示文稿有视觉节奏,使用多种布局。
正确做法:至少使用2-3种不同的布局类型。插入引用页、双栏页或章节分隔页以打破重复。
contentLooping QA Beyond 3 Iterations
QA循环超过3次迭代
What it looks like: "Just one more fix cycle" after iteration 3 because there is one remaining minor issue.
Why wrong: If 3 iterations could not fix the issue, the design approach is wrong. More iterations burn context without convergence.
Do instead: Stop at 3. Report remaining issues. Deliver with caveats.
表现:3次迭代后“再进行一次修复循环”,因为还有一个次要问题。
错误原因:3次迭代无法修复问题说明设计方法错误,而非实现问题。更多迭代会消耗上下文而无收敛。
正确做法:3次迭代后停止。报告剩余问题。交付时附带说明。
Adding Decorative Elements "For Polish"
添加装饰元素“以提升美观度”
What it looks like: Adding accent lines under titles, shadows on every shape, rounded rectangles as bullet containers.
Why wrong: These are the exact patterns that mark a presentation as AI-generated. See .
Do instead: Keep slides clean. Use typography (size, weight, spacing) for visual hierarchy, not decorative shapes.
references/anti-ai-slide-rules.md表现:在标题下添加装饰线、为所有形状添加阴影、使用圆角矩形作为项目符号容器。
错误原因:这些正是标记演示文稿为AI生成的模式。请参阅。
正确做法:保持幻灯片简洁。使用排版大小、字重、间距)建立视觉层次,而非装饰形状。
references/anti-ai-slide-rules.mdAnti-Rationalization
反合理化
See shared-patterns/anti-rationalization-core.md for universal patterns.
有关通用模式,请参阅shared-patterns/anti-rationalization-core.md。
Domain-Specific Rationalizations
特定领域的合理化
| Rationalization Attempt | Why It's Wrong | Required Action |
|---|---|---|
| "The slide map is obvious, skip user review" | Content rework after generation costs QA iterations | Present the slide map and wait for approval |
| "One more QA iteration will fix it" (after 3) | 3 failed iterations means the design approach is wrong, not the implementation | Stop, report issues, deliver with caveats |
| "LibreOffice is slow, skip visual QA" | Structural validation catches data errors but not visual ones (clipped text, contrast, alignment) | Run visual QA when LibreOffice is available; note when it is skipped |
| "Inline code is faster than the script" | Faster for one run, inconsistent across many; wastes tokens on boilerplate | Use |
| "Adding a decorative line makes it look polished" | This is the single most recognizable AI-slide tell | Never add decorative lines under titles |
| "The user won't notice identical layouts" | Audiences do notice visual monotony, even subconsciously | Use 2-3+ distinct layout types per deck |
| "9 bullets is close enough to 6" | 9 bullets is a document paragraph, not a slide. Readability degrades sharply past 6 | Enforce the 6-bullet max; split into multiple slides |
| "Custom fonts would look better" | Custom fonts break on machines that lack them | Calibri/Arial only; portability trumps aesthetics |
| 合理化尝试 | 错误原因 | 要求的操作 |
|---|---|---|
| “幻灯片地图很明显,跳过用户审核” | 生成后内容返工会消耗QA迭代次数 | 展示幻灯片地图并等待批准 |
| “再进行一次QA迭代就能修复”(3次后) | 3次失败迭代说明设计方法错误,而非实现问题 | 停止,报告问题,交付时附带说明 |
| “LibreOffice很慢,跳过视觉QA” | 结构验证能发现数据错误,但无法发现视觉问题(文本截断、对比度、对齐) | 当LibreOffice可用时运行视觉QA;不可用时记录跳过情况 |
| “内联代码比脚本快” | 单次运行更快,但多次运行不一致;会在样板代码上浪费token | 始终使用 |
| “添加装饰线会让它看起来更精致” | 这是最容易识别的AI幻灯片特征 | 永远不要在标题下添加装饰线 |
| “用户不会注意到相同的布局” | 受众会注意到视觉单调,即使是潜意识的 | 每个演示文稿使用2-3种以上不同的布局类型 |
| “9个项目符号接近6个” | 9个项目符号是文档段落,不是幻灯片。超过6个后可读性急剧下降 | 强制执行最多6个项目符号的限制;拆分为多张幻灯片 |
| “自定义字体看起来更好” | 自定义字体在缺少该字体的机器上会失效 | 仅使用Calibri/Arial;便携性优先于美观 |
Blocker Criteria
阻塞标准
STOP and ask the user (do NOT proceed autonomously) when:
| Situation | Why Stop | Ask This |
|---|---|---|
| Content too thin for requested slide count | Padding produces empty slides that waste audience time | "You have content for about 5 slides but requested 12. Create a 5-slide deck or add more content?" |
| No clear topic or audience | Cannot select palette or structure without context | "Who is the audience, and what is the key message?" |
| User provides a .pptx template to modify | Template editing has different constraints than blank-slate generation | "Should I modify your existing deck, or create a new one using your template's styling?" |
| QA finds structural issues (wrong slide count) | Structural failures indicate a slide map problem, not a visual fix | "The generated deck has 8 slides but the map specified 10. Regenerate or adjust the map?" |
| Multiple valid palette choices | Aesthetic preference is personal | "I'd suggest [Palette] for this type of presentation. Want that, or prefer something else?" |
出现以下情况时停止并询问用户(不要自主继续):
| 情况 | 停止原因 | 询问内容 |
|---|---|---|
| 内容不足以支撑请求的幻灯片数量 | 填充内容会生成空幻灯片,浪费受众时间 | “您的内容大约够做5张幻灯片,但您请求12张。是创建5张幻灯片的演示文稿,还是添加更多内容?” |
| 无明确主题或受众 | 没有上下文无法选择配色方案或结构 | “受众是谁,核心信息是什么?” |
| 用户提供.pptx模板进行修改 | 模板编辑与从头生成的约束不同 | “我应该修改您现有的演示文稿,还是使用您模板的样式创建新的演示文稿?” |
| QA发现结构问题(幻灯片数量错误) | 结构失败表明幻灯片地图有问题,而非视觉修复能解决 | “生成的演示文稿有8张幻灯片,但地图指定10张。是重新生成还是调整地图?” |
| 有多个有效的配色方案选择 | 审美偏好因人而异 | “我建议为此类型的演示文稿使用[配色方案]。是否使用该方案,还是您有其他偏好?” |
Never Guess On
永远不要猜测
- Audience and tone (business vs technical vs casual changes everything)
- Whether to use dark theme (Midnight palette) -- strong aesthetic choice
- Whether to include images (user must provide assets or explicitly request generation)
- Slide count when user is vague ("a few slides" -- ask for a number)
- Content that the user hasn't provided (do not invent slide content)
- 受众和语气(商务vs技术vs随意会改变一切)
- 是否使用深色主题(Midnight配色方案)——强烈的审美选择
- 是否包含图片(用户必须提供资产或明确要求生成)
- 用户模糊时的幻灯片数量(“几张幻灯片”——询问具体数量)
- 用户未提供的内容(不要发明幻灯片内容)
Death Loop Prevention
防止死循环
Retry Limits
重试限制
- Phase 3 (GENERATE): Max 2 retries for script failures before escalating to user
- Phase 5 (QA): Max 3 iterations of the fix-and-recheck cycle
- Slide map revision: Max 2 rounds of user feedback before freezing the map
- 阶段3(生成):脚本失败最多重试2次,之后向用户升级问题
- 阶段5(QA):修复并重新检查循环最多3次
- 幻灯片地图修订:最多进行2轮用户反馈,之后冻结地图
Recovery Protocol
恢复协议
- Detection: Same QA issue reappearing after a fix attempt, generation script failing on the same input repeatedly, or slide map revisions not converging
- Intervention: Simplify the deck. Reduce slide count, use only and
contentlayouts, drop complex layouts (table, two-column) that may be causing issuestitle - Prevention: Validate the slide map JSON against the schema before generation. Check that bullet counts are within limits. Verify image paths exist before including slides.
image_text
- 检测:同一QA问题在修复后再次出现、生成脚本在同一输入上反复失败、或幻灯片地图修订无法收敛
- 干预:简化演示文稿。减少幻灯片数量,仅使用和
content布局,删除可能导致问题的复杂布局(表格、双栏)title - 预防:生成前验证幻灯片地图JSON是否符合模式。检查项目符号数量是否在限制内。包含幻灯片前验证图片路径是否存在。
image_text
Dependencies
依赖项
Required
必需
| Dependency | Type | Purpose | Install |
|---|---|---|---|
| pip | PPTX generation and manipulation | |
| 依赖项 | 类型 | 用途 | 安装方式 |
|---|---|---|---|
| pip | PPTX生成和操作 | |
Optional (enhances capability)
可选(增强功能)
| Dependency | Type | Purpose | Install |
|---|---|---|---|
| LibreOffice | system | PDF/PNG conversion for visual QA loop | |
| pip | Image handling for embedded images | |
| system | Higher-quality PDF-to-PNG conversion | |
| pip | Extract text from existing PPTX for content reuse | |
| 依赖项 | 类型 | 用途 | 安装方式 |
|---|---|---|---|
| LibreOffice | 系统 | 用于视觉QA循环的PDF/PNG转换 | |
| pip | 用于嵌入图片的图像处理 | |
| 系统 | 更高质量的PDF转PNG转换 | |
| pip | 从现有PPTX中提取文本以重用内容 | |
What We Do NOT Need
我们不需要的工具
| Tool | Why Not |
|---|---|
| Foreign ecosystem; python-pptx covers our needs |
| Raw XML unzip/rezip | python-pptx + lxml handles this natively |
| Headless browser | LibreOffice handles conversion |
| 工具 | 原因 |
|---|---|
| 外来生态系统;python-pptx已满足我们的需求 |
| 原始XML解压/重新压缩 | python-pptx + lxml原生支持此功能 |
| 无头浏览器 | LibreOffice可处理转换 |
Script Reference
脚本参考
generate_pptx.py
generate_pptx.py
Purpose: Deterministic slide construction. Reads slide map JSON + design config JSON, produces .pptx.
| Argument | Required | Description |
|---|---|---|
| Yes | Path to slide map JSON file |
| Yes | Path to design config JSON file |
| Yes | Output .pptx file path |
Design config format:
json
{
"palette": "minimal",
"template_path": null
}Exit codes: 0 = success, 1 = missing python-pptx, 2 = invalid input, 3 = generation failed.
用途:确定性幻灯片构建。读取幻灯片地图JSON + 设计配置JSON,生成.pptx。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 是 | 幻灯片地图JSON文件的路径 |
| 是 | 设计配置JSON文件的路径 |
| 是 | 输出.pptx文件的路径 |
设计配置格式:
json
{
"palette": "minimal",
"template_path": null
}退出代码:0 = 成功,1 = 缺少python-pptx,2 = 输入无效,3 = 生成失败。
convert_slides.py
convert_slides.py
Purpose: PPTX to PDF to per-slide PNG conversion for visual QA.
| Argument | Required | Description |
|---|---|---|
| Yes | Path to .pptx file |
| Yes | Directory for output PNG files |
| No | PNG resolution (default: 150) |
| No | Keep intermediate PDF file |
Exit codes: 0 = success, 1 = no LibreOffice, 2 = conversion failed, 3 = invalid input.
用途:将PPTX转换为PDF,再转换为单张幻灯片的PNG,用于视觉QA。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 是 | .pptx文件的路径 |
| 是 | 输出PNG文件的目录 |
| 否 | PNG分辨率(默认:150) |
| 否 | 保留中间PDF文件 |
退出代码:0 = 成功,1 = 无LibreOffice,2 = 转换失败,3 = 输入无效。
validate_structure.py
validate_structure.py
Purpose: Validate .pptx structural integrity against the slide map.
| Argument | Required | Description |
|---|---|---|
| Yes | Path to .pptx file |
| No | Expected slide count |
| No | Path to slide map JSON for content validation |
| No | Output results as JSON |
Exit codes: 0 = passed, 1 = missing python-pptx, 2 = validation failed, 3 = invalid input.
用途:根据幻灯片地图验证.pptx的结构完整性。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 是 | .pptx文件的路径 |
| 否 | 预期的幻灯片数量 |
| 否 | 用于内容验证的幻灯片地图JSON路径 |
| 否 | 以JSON格式输出结果 |
退出代码:0 = 通过,1 = 缺少python-pptx,2 = 验证失败,3 = 输入无效。
References
参考资料
For detailed information:
- Design System: references/design-system.md -- color palettes with hex codes, typography rules, spacing guidelines, python-pptx color usage
- Slide Layouts: references/slide-layouts.md -- 8 layout types with python-pptx code, positioning specs, and rhythm guidelines
- Anti-AI Slide Rules: references/anti-ai-slide-rules.md -- 10 patterns to avoid, detection criteria, and the summary checklist
- QA Checklist: references/qa-checklist.md -- visual QA criteria for the subagent, severity levels, and output format
有关详细信息:
- 设计系统:references/design-system.md —— 带十六进制代码的配色方案、排版规则、间距指南、python-pptx颜色使用方法
- 幻灯片布局:references/slide-layouts.md —— 8种布局类型的python-pptx代码、定位规范和节奏指南
- 反AI幻灯片规则:references/anti-ai-slide-rules.md —— 10种要避免的模式、检测标准和摘要清单
- QA清单:references/qa-checklist.md —— 子代理的视觉QA标准、严重程度级别和输出格式
Complementary Skills
互补技能
- research-to-article -- research output can feed slide content
- gemini-image-generator -- generate images for slides
- workflow-orchestrator -- orchestrate multi-step pipelines
- research-to-article —— 研究输出可作为幻灯片内容的来源
- gemini-image-generator —— 为幻灯片生成图片
- workflow-orchestrator —— 编排多阶段流程
Shared Patterns
共享模式
- Anti-Rationalization -- prevents shortcut rationalizations
- Gate Enforcement -- phase transition rules
- Verification Checklist -- pre-completion checks
- 反合理化 —— 防止捷径合理化
- 关卡强制执行 —— 阶段转换规则
- 验证清单 —— 完成前检查