pptx-generator

PPTX 幻灯片生成器

使用 python-pptx 生成专业且符合品牌风格的演示文稿幻灯片。此技能支持：

• 幻灯片生成 - 为 brands/ 中的任意品牌创建演示文稿
• 轮播图生成 - 创建 LinkedIn 轮播图（方形格式，导出为 PDF）
• 幻灯片编辑 - 修改现有 PPTX 文件
• 布局管理 - 创建、编辑和更新布局手册中的布局

重要： 所有技能资源都位于 .claude/skills/pptx-generator/。查找文件时，始终使用以 .claude/skills/pptx-generator/ 开头的 Glob 模式。

---

⚠️ 关键：批量生成规则

一次最多生成 5 张幻灯片。

规则	详情
每批最多幻灯片数	5（可以是 1、2、3、4 或 5）
每批生成后	停止并验证输出
必须验证	检查：没有重复标题、间距恰当、颜色正确
继续的条件	验证通过
所有批次完成后	合并为单个文件并删除分段文件

这可以避免令牌限制错误，并尽早发现质量问题。

关键：合并后务必清理分段文件。 用户最终只能看到一个 PPTX 文件，而不是多个分段文件。

---

⚠️ 前提条件：品牌检查

生成幻灯片前，检查是否存在品牌。

Glob: .claude/skills/pptx-generator/brands/*/brand.json

如果没有找到品牌（仅存在 template/）：

1. 停止 - 不要继续生成幻灯片

2. 询问用户：

   "尚未配置任何品牌。您希望我先帮您创建一个品牌吗？ 我需要您的品牌颜色、字体和风格指南来完成设置。"

3. 如果用户想创建品牌，请按照下文的创建新品牌部分操作。

4. 如果用户拒绝，说明幻灯片需要品牌配置，并提出将通用样式作为备用方案。

---

创建新品牌

不存在品牌或用户要求创建新品牌时：

第 1 步：阅读模板

Read: .claude/skills/pptx-generator/brands/template/README.md
Read: .claude/skills/pptx-generator/brands/template/brand.json
Read: .claude/skills/pptx-generator/brands/template/config.json

第 2 步：收集品牌信息

询问用户以下信息（或从所提供的材料中提取）：

必需项	描述
品牌名称	文件夹名称（小写，不含空格）
颜色	背景色、文字色、强调色（十六进制代码）
字体	标题字体、正文字体、代码字体

可选项	描述
输出目录	生成文件的保存位置（默认：output/{brand}）
徽标	徽标文件的路径（PNG/SVG）
品牌指南	可供参考的现有风格指南或网站
语气风格	写作风格、词汇偏好

第 3 步：创建品牌文件

1. 创建品牌文件夹：

   mkdir -p .claude/skills/pptx-generator/brands/{brand-name}
   

2. 使用收集到的信息创建 brand.json：

   {
     "name": "Brand Name",
     "description": "One-line description",
     "colors": {
       "background": "hex-without-hash",
       "background_alt": "hex-without-hash",
       "text": "hex-without-hash",
       "text_secondary": "hex-without-hash",
       "accent": "hex-without-hash",
       "accent_secondary": "hex-without-hash",
       "accent_tertiary": "hex-without-hash",
       "code_bg": "hex-without-hash",
       "card_bg": "hex-without-hash",
       "card_bg_alt": "hex-without-hash"
     },
     "fonts": {
       "heading": "Font Name",
       "body": "Font Name",
       "code": "Monospace Font"
     },
     "assets": {
       "logo": "assets/logo.png",
       "logo_dark": null,
       "icon": null
     }
   }
   

3. 使用输出设置创建 config.json：

   {
     "output": {
       "directory": "output/{brand}",
       "naming": "{name}-{date}",
       "keep_parts": false
     },
     "generation": {
       "slides_per_batch": 5,
       "auto_combine": true,
       "open_after_generate": false
     },
     "defaults": {
       "slide_width_inches": 13.333,
       "slide_height_inches": 7.5
     }
   }
   

4. 创建 brand-system.md - 从模板复制并填写品牌指南

5. 创建 tone-of-voice.md - 从模板复制并填写语气指南

6. 添加资源 - 将徽标/图片复制到 brands/{brand-name}/assets/

第 4 步：验证

创建品牌后，使用以下内容进行验证：

Glob: .claude/skills/pptx-generator/brands/{brand-name}/*

然后继续生成幻灯片。

---

技能模式

此技能以三种模式运行：

模式 1：生成演示文稿幻灯片

用户希望使用品牌样式创建演示文稿幻灯片（16:9）。 → 按照以下流程操作：品牌发现 → 布局选择 → 内容调整 → 执行 → 布局位于：cookbook/*.py

模式 2：生成 LinkedIn 轮播图

用户希望创建用于社交媒体的 LinkedIn 轮播图（正方形 1:1 格式）。 → 按照以下流程操作：品牌发现 → 轮播图规划 → 生成 → 导出 PDF → 布局位于：cookbook/carousels/*.py

模式 3：管理布局手册中的布局

用户希望创建、编辑或改进布局模板。 → 按照“布局 CRUD 操作”部分操作

---

模式 1：生成演示文稿幻灯片

步骤 1：品牌探索

1. 列出可用品牌：

   Glob: .claude/skills/pptx-generator/brands/*/brand.json
   

   从路径中提取唯一的品牌名称（例如，brands/rasmus/... → “rasmus”）

2. 读取品牌配置文件：

   Read: .claude/skills/pptx-generator/brands/{brand-name}/brand.json
   Read: .claude/skills/pptx-generator/brands/{brand-name}/config.json
   

   • brand.json - 颜色、字体、素材
   • config.json - 输出目录、生成设置

3. 阅读辅助 Markdown 文件以了解上下文：

   Glob: .claude/skills/pptx-generator/brands/{brand-name}/*.md
   

   这些文件提供语气、风格和设计理念。

4. 从品牌文件中提取信息：

   • **从 brand.json 中提取：**颜色（不含 # 的十六进制值）、字体、素材路径
   • **从 config.json 中提取：**输出目录、每批幻灯片数、命名约定
   • **从 Markdown 中提取：**语气、风格、词汇、视觉原则

如果未找到品牌，请列出可用品牌并请用户选择。

步骤 2：布局探索（读取所有前置元数据）

⚠️ 必须：在选择任何布局之前，读取所有布局的前置元数据。

此步骤对于做出明智的布局决策至关重要。选择前必须了解所有布局的特点。

步骤 2a：发现所有布局：

Glob: .claude/skills/pptx-generator/cookbook/*.py

步骤 2b：读取每个布局文件（不只读取一两个）：

对于找到的每个 .py 文件，读取前 40 行，提取 # /// layout 前置元数据块。建立对以下内容的整体认知：

• 每种布局的用途（purpose、best_for）
• 不应使用每种布局的情况（avoid_when）
• 限制和约束（max_*、min_*、*_max_chars）

前置元数据块如下所示：

# /// layout
# name = "floating-cards-slide"
# purpose = "Feature highlights, process steps, multiple equal items with depth"
# best_for = [
#     "Exactly 3 related features or concepts",
#     "Process with 3 steps",
# ]
# avoid_when = [
#     "More than 3 items - use multi-card-slide instead",
#     "Long card titles (over 15 characters)",
# ]
# max_cards = 3
# card_title_max_chars = 15
# instructions = [
#     "EXACTLY 3 cards required - no more, no less",
#     "Card titles must be SHORT: 1-2 words, max 15 characters",
# ]
# ///

前置元数据的关键字段：

字段	描述
name	布局标识符
purpose	此布局的用途
best_for	理想使用场景（数组）
avoid_when	不应使用此布局的情况（数组）
max_* / min_*	项目数量限制（卡片、项目符号、统计数据）
instructions	使用此布局的具体建议

步骤 2c：选择布局（仅在读取所有前置元数据后进行）：

现在你已了解所有可用布局及其约束：

1. 用户指定布局 → 使用该布局（但需确认其适合内容）
2. 用户描述内容 → 根据最匹配的 best_for 标准进行选择
3. 检查 avoid_when → 避免在布局警告的情况下使用该布局
4. 遵守限制 → 如果内容超出 max_*，请改用其他布局
5. 需要多张幻灯片 → 为每张幻灯片选择合适的布局
6. 没有合适的布局 → 创建自定义布局（参见模式 2）

布局选择示例：

• 用户想要“AI 基础设施的 5 大支柱”
• 你已阅读所有前置元数据并了解：
  • floating-cards-slide：max_cards = 3 → 不适用
  • multi-card-slide：max_cards = 5 → 完美匹配
• 选择 multi-card-slide

为什么要读取所有前置元数据？

• 布局会在 avoid_when 中互相引用（例如，“改用 multi-card-slide”）
• 不了解所有选项，就无法做出正确选择
• 避免布局不适用时再返工

步骤 2d：视觉优先的布局选择（对多样性至关重要）

🎨 默认选择视觉型布局。content-slide 是最后的选择，而非默认选项。

多样性问题

生成演示文稿时，最大的错误是在需要传达信息时，总是默认使用 content-slide（标题 + 项目符号）。这会导致演示文稿重复、乏味。

常见失败模式：

• 30 张幻灯片中有 11 张使用 content-slide（重复率 37%）
• 用户说“缺乏多样性”
• 你认为“但我用了 11 种不同的布局！”
• 实际上：布局种类不少，但分布很糟糕

多样性规则

硬性限制：

1. 同一布局连续使用不得超过 2-3 次
2. content-slide 应少于幻灯片总数的 25%（而非 35-40%）
3. 视觉型布局（卡片、统计数据、分栏、主视觉、斜向布局）应占幻灯片的 50% 以上
4. 章节分隔页不算作多样性——它们属于结构元素（不计入多样性）

决策树：“我应该使用 content-slide 吗？”

默认使用 content-slide 前，按顺序回答以下问题：

Do I have 3-5 equal items?
  YES → Use multi-card-slide (not content-slide)

Do I have 2-4 big numbers/metrics?
  YES → Use stats-slide (not content-slide)

Am I comparing two things?
  YES → Use two-column-slide (not content-slide)

Do I have a central concept with surrounding items?
  YES → Use circular-hero-slide (not content-slide)

Do I have exactly 3 related items?
  YES → Use floating-cards-slide (not content-slide)

Do I have 1-3 words I want to emphasize dramatically?
  YES → Use giant-focus-slide or bold-diagonal-slide (not content-slide)

Do I have a powerful quote or principle?
  YES → Use quote-slide (not content-slide)

Is this the ONLY way to present this information?
  YES → NOW you can use content-slide
  NO → Go back through the decision tree

将项目符号转换为可视化布局

示例 1：「验证模式」

❌ 不佳（content-slide）：

Title: Validation Patterns
Bullets:
- Run comprehensive test suites
- Type checking and linting
- Code review by humans and AI
- Deployment previews

✅ 较佳（multi-card-slide）：

Title: Validation Patterns
Cards:
1. Testing | Run comprehensive test suites after every change
2. Linting | Type checking and formatting as guardrails
3. Review | Human and AI code review process
4. Preview | Deployment previews for visual regression

示例 2：「PIV 为何有效」

❌ 不佳（content-slide）：

Title: Why PIV Works
Bullets:
- Forces planning before implementation
- Validation catches issues immediately
- Iterative improvements compound
- System gets smarter with every bug

✅ 较佳（带 3 张卡片的 floating-cards-slide）：

Title: Why PIV Works
Cards:
1. Plan First | Forces architectural thinking before coding
2. Fast Feedback | Validation catches issues immediately
3. Compounds | System improves with every bug

（注：从 4 项减少到 3 项，以符合 floating-cards-slide 的 max_cards 限制）

示例 3：「人在回路策略」

❌ 不佳（content-slide）：

Title: Human-in-the-Loop Strategy
Bullets:
- In-the-loop: Human approves before execution
- On-the-loop: Human reviews after completion
- Code review remains critical
- AI generates, humans validate

✅ 较佳（two-column-slide）：

Title: Human-in-the-Loop Strategy
Left: In-the-Loop
- Human approves before execution
- Critical for production changes
- Quality gateway

Right: On-the-Loop
- Human reviews after completion
- Faster iteration cycles
- AI generates, human validates

主动进行视觉思考

在规划每张幻灯片之前，先问问自己：

1. 「能否让它更具视觉效果？」——答案几乎总是肯定的。
2. 「最近 2 张幻灯片中用过 content-slide 吗？」——如果用过，就换一种布局。
3. 「这张幻灯片看起来和上一张相似吗？」——如果相似，就更换布局。
4. 「我是否陷入了某种模式？」——立即打破它。
5. 「做成卡片、分栏或数据指标的形式，会不会更吸引人？」——通常会。

何时适合使用 content-slide

仅在以下情况下使用 content-slide：

• 你确实尝试过所有其他布局，但都不合适
• 信息本质上是线性且以文本为主的（很少见）
• 需要在两张复杂的可视化幻灯片之间插入一张「缓冲」幻灯片
• 已达到布局分布限制（近期已用过所有可视化布局）

切勿将 content-slide 作为默认选择。

速查：内容类型 → 最佳布局

内容类型	最佳布局	原因
3-5 个同等重要的特性/步骤	multi-card-slide	卡片能建立视觉层次
恰好 3 个重点项目	floating-cards-slide	突出的卡片能增加层次感
2-4 个指标/KPI	stats-slide	大号数字能吸引注意力
前后对比	two-column-slide	并排展示能凸显差异
带有多种类型的中心概念	circular-hero-slide	辐射式布局能展现关联
强调重点（1-3 个词）	giant-focus-slide	尺寸能营造冲击力
高强度警告	bold-diagonal-slide	动态形状能传达紧迫感
有力的引言/原则	quote-slide	标注出处能增强权威性
相关项目列表	multi-card-slide	比项目符号更好
分步骤的流程	floating-cards-slide	可视化流程胜过文字
技术对比	two-column-slide	便于进行结构化对比

仅在以下情况下使用 content-slide：

• 以上布局都不合适
• 信息确实是线性的
• 需要在可视化幻灯片之间插入一张文字较多的缓冲幻灯片
• 已达到多样性限制

步骤 3：幻灯片规划（务必执行）

生成任何幻灯片之前，先制定书面计划。

这适用于单页幻灯片、批次和完整演示文稿。规划有助于避免：

• 幻灯片内容重复
• 布局选择错误
• 遗漏关键信息
• 流程和结构不佳

创建幻灯片计划表：

| # | Layout | Title | Key Content | Notes |
|---|--------|-------|-------------|-------|
| 1 | title-slide | [Title] | [Subtitle, author] | Opening slide |
| 2 | content-slide | [Title] | [3-4 bullet points] | Main concepts |
| 3 | stats-slide | [Title] | [2-3 metrics] | Impact data |
| ... | ... | ... | ... | ... |

为每张幻灯片指定：

• 幻灯片编号 - 在演示文稿中的位置
• 布局 - 使用哪种 cookbook 布局
• 标题 - 标题的准确文本（检查是否重复！）
• 关键内容 - 项目符号、统计数据、引语等
• 备注 - 任何特殊注意事项

规划检查清单：

• 幻灯片标题均不重复
• 幻灯片之间的逻辑流程顺畅
• 为每种内容类型选择合适的布局
• 内容适合所选布局
• 批次分组合理（每批最多 5 张幻灯片）
• 多样性检查：内容型幻灯片占总幻灯片数的比例低于 25%
• 多样性检查：相同布局连续使用不超过 2-3 张幻灯片
• 多样性检查：视觉布局（卡片、统计数据、分栏、主视觉）占幻灯片总数的 50% 以上
• 多样性检查：每张内容型幻灯片都先根据决策树进行评估

规划完成后，先简要展示计划，再生成幻灯片。

30 张幻灯片的演示文稿中，多样性分布的良好示例：

• 内容型幻灯片：6-7 张（20-23%）
• 章节分隔页：5 张（17%）
• 视觉布局：15-16 张（50-53%）
  • 多卡片：3-4 张
  • 双栏：2-3 张
  • 统计数据：1-2 张
  • 悬浮卡片：2-3 张
  • 圆形主视觉：1-2 张
  • 巨型焦点/粗体斜线：2-3 张
  • 引语：1 张
• 标题页/结束页：2-3 张（7-10%）

步骤 4：内容调整

对于计划中的每张幻灯片：

演示文稿文本格式规则

重要：所有幻灯片文本都必须遵循这些规则。

元素	规则	示例
标题	末尾不加句号或逗号	“Why AI Matters”，而不是 “Why AI Matters.”
副标题	末尾不加标点	“The future of coding”，而不是 “The future of coding.”
项目符号	末尾不加句号（完整句子除外）	“更快的开发”，而不是 “更快的开发。”
标题语句	标点尽量精简，不使用省略号	“What's Next”，而不是 “What's Next...”
统计数据/数字	格式简洁，末尾不加标点	“50%”，而不是 “50%.”
行动号召	末尾不加标点	“开始使用”，而不是 “开始使用。”
标签	简短，不加标点	“步骤 1”，而不是 “步骤 1：”

避免：

• 在标题、项目符号、标签末尾加句号
• 在标题语句中使用省略号（...）
• 在简短短语中过度使用逗号
• 在标签/标题末尾使用冒号
• 在项目符号中使用分号

**例外：**完整句子的描述或引语可以使用恰当的标点。

品牌价值映射

1. 将 brand.json 中的值映射到布局占位符：

   布局占位符	brand.json 路径
   BRAND_BG	colors.background
   BRAND_BG_ALT	colors.background_alt
   BRAND_TEXT	colors.text
   BRAND_TEXT_SECONDARY	colors.text_secondary
   BRAND_ACCENT	colors.accent
   BRAND_ACCENT_SECONDARY	colors.accent_secondary
   BRAND_ACCENT_TERTIARY	colors.accent_tertiary
   BRAND_CODE_BG	colors.code_bg
   BRAND_CARD_BG	colors.card_bg
   BRAND_CARD_BG_ALT	colors.card_bg_alt
   BRAND_HEADING_FONT	fonts.heading
   BRAND_BODY_FONT	fonts.body
   BRAND_CODE_FONT	fonts.code

   **注意：**brand.json 中的所有颜色值都是不带 # 前缀的十六进制值。

2. 使用品牌的语气撰写内容（参见 tone-of-voice.md）

3. 保留布局结构（装饰元素、间距、层级）

步骤 5：批量生成（关键）

每批最多 5 张幻灯片。这是硬性限制。

生成多张幻灯片时：

1. 在单个 PPTX 文件中生成 1-5 张幻灯片
2. 停止并检查输出，然后再生成更多幻灯片
3. 只有验证通过后，才能继续生成下一批
4. 重复此过程，直到生成所有幻灯片

分批处理的重要性：

• 避免令牌限制错误
• 允许在各批次之间进行质量检查
• 尽早发现问题，防止问题扩散

⚠️ 关键背景修复：

每张幻灯片都必须显式设置背景。 如果不设置 slide.background.fill.solid() 和 slide.background.fill.fore_color.rgb，幻灯片将使用 PowerPoint 默认的白色背景，导致深色主题品牌的文字难以辨认。

每张幻灯片都必须执行：

slide = prs.slides.add_slide(prs.slide_layouts[6])
slide.background.fill.solid()  # ← REQUIRED
slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG)  # ← REQUIRED

以下情况尤其重要：

• 生成多个批次时（每个批次都是一个新的 Presentation 对象）
• 使用辅助函数创建幻灯片时
• 合并多个独立的 PPTX 文件时

执行方式：

首选：使用 heredoc（不创建文件）：

uv run --with python-pptx==1.0.2 python << 'EOF'
# [Adapted code with brand values and content]
EOF

如果 heredoc 失败（Windows 问题）：使用临时目录：

# Create temp directory if needed
mkdir -p .claude/skills/pptx-generator/.tmp

# Write script to temp directory
# (create file at .claude/skills/pptx-generator/.tmp/gen.py)

# Execute
uv run --with python-pptx==1.0.2 python .claude/skills/pptx-generator/.tmp/gen.py

# MANDATORY: Clean up immediately after execution
rm .claude/skills/pptx-generator/.tmp/gen.py

关键：切勿在仓库根目录中创建 Python 文件。 始终使用 heredoc，或在技能文件夹中使用临时目录。

步骤 6：质量验证（必须执行）

每批生成后，都必须先验证，再继续：

1. 打开生成的 PPTX 并进行目视检查
2. 检查以下常见问题：

问题	检查内容	修复方法
白色背景	幻灯片背景是否为白色，而不是品牌色	添加 slide.background.fill.solid() 并设置 fore_color.rgb
标题重复	同一张幻灯片上是否出现相同的标题文本两次	删除重复的文本框
间距问题	标题是否与副标题/内容过于接近	增大下方元素的 Y 位置
文本溢出	内容是否超出幻灯片边界	减小字号或拆分内容
元素缺失	装饰元素是否未能渲染	检查形状的位置和颜色
颜色错误	颜色是否与品牌不匹配	验证十六进制值（代码中不加 # 前缀）
标点不当	标题/项目符号末尾是否有句号/逗号	删除不必要的标点

3. 如果发现问题：

   • 继续之前，先修复当前批次
   • 记录问题，避免在后续批次中重复出现

4. 如果验证通过：

   • 继续生成下一批幻灯片

步骤 7：输出

使用 config.json 中的输出设置：

配置项	默认值	说明
output.directory	output/{brand}	文件保存位置
output.naming	{name}-{date}	文件命名模式
output.keep_parts	false	合并后是否保留分批文件

替换占位符：

• {brand} → 品牌文件夹名称
• {name} → 用户请求中的演示文稿名称
• {date} → 当前日期（YYYY-MM-DD）

# Create output directory from config
mkdir -p {resolved-output-directory}

分批生成工作流：

1. 将每批生成为 {name}-part1.pptx、{name}-part2.pptx 等文件
2. 继续之前，验证每一批
3. 所有批次完成后，合并为最终文件（如果 auto_combine 为 true）
4. 删除分批文件（如果 keep_parts 为 false）

步骤 8：合并批次（适用于多批次演示文稿）

🚨 严重错误警告：合并时必须设置背景 🚨

合并演示文稿时，add_slide() 创建的幻灯片会采用默认白色背景。复制形状不会复制幻灯片背景属性。创建每张新幻灯片后，必须立即显式设置背景。

这是合并演示文稿时出现白色幻灯片最常见的原因。

验证完所有批次后，将它们合并为一个 PPTX：

uv run --with python-pptx==1.0.2 python << 'SCRIPT'
from pptx import Presentation
from pptx.dml.color import RGBColor
from pathlib import Path
import shutil

def hex_to_rgb(hex_color: str) -> RGBColor:
    h = hex_color.lstrip("#")
    return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))

# Brand background color (get from brand.json)
BRAND_BG = "REPLACE_WITH_BRAND_BACKGROUND"  # e.g., "07090F"

# List all part files in order
output_dir = Path("output/{brand-name}")
part_files = sorted(output_dir.glob("{name}-part*.pptx"))

if len(part_files) > 1:
    # Start with first part as base
    combined = Presentation(part_files[0])

    # Add slides from remaining parts
    for part_file in part_files[1:]:
        part_prs = Presentation(part_file)
        for slide in part_prs.slides:
            # Copy slide layout and add to combined
            blank_layout = combined.slide_layouts[6]
            new_slide = combined.slides.add_slide(blank_layout)

            # 🚨 CRITICAL: Set background IMMEDIATELY after creating slide
            # PowerPoint defaults to WHITE background - this MUST be set before copying shapes
            new_slide.background.fill.solid()
            new_slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG)

            # Copy all shapes from source slide
            for shape in slide.shapes:
                # Clone shape to new slide
                el = shape.element
                new_slide.shapes._spTree.insert_element_before(
                    el, 'p:extLst'
                )

    # Save combined file
    combined.save(output_dir / "{name}-final.pptx")
    print(f"Combined {len(part_files)} parts into {name}-final.pptx")

    # MANDATORY: Clean up part files - user should only see final file
    for part_file in part_files:
        part_file.unlink()
        print(f"Deleted {part_file.name}")
else:
    # Single part, just rename
    shutil.move(part_files[0], output_dir / "{name}-final.pptx")
SCRIPT

最终输出： output/{brand-name}/{name}-final.pptx

错误原因：

• combined.slides.add_slide() 会创建一个新的幻灯片对象，其背景为 PowerPoint 默认的白色
• shapes._spTree.insert_element_before() 会复制形状（文本、矩形、图像），但不会复制背景
• 背景是幻灯片属性，而非形状，因此必须单独设置
• 如果不显式设置背景，第 6 至 30 张幻灯片（或在基础幻灯片之后添加的其他数量的幻灯片）就会是白色

合并后的测试清单：

• 打开合并后的 PPTX
• 浏览所有幻灯片（不只是前几张）
• 确认每张幻灯片的背景颜色都正确
• 如果发现任何白色幻灯片，说明合并代码缺少背景设置

---

模式 2：生成 LinkedIn 轮播图

LinkedIn 轮播图是采用正方形（1:1）格式的多页 PDF。每一页都是可滑动浏览的幻灯片。

轮播图与演示文稿的区别

方面	演示文稿	轮播图
尺寸	16:9（13.333" × 7.5"）	1:1（7.5" × 7.5"）
布局	cookbook/*.py	cookbook/carousels/*.py
输出	PPTX	PDF（通过 PPTX 转换）
幻灯片数	通常为 10-50 张以上	最佳为 5-10 张
文字大小	标准	更大（便于在手机上阅读）
内容	详尽	每张幻灯片一个要点

步骤 1：品牌探索

与模式 1 相同——读取 brand.json、config.json 和 tone-of-voice.md。

步骤 2：轮播图布局探索

探索轮播图专用布局：

Glob: .claude/skills/pptx-generator/cookbook/carousels/*.py

可用的轮播图布局：

布局	用途	最适合
hook-slide	开篇吸引注意力	仅用于第一张幻灯片
single-point-slide	一个要点及其说明	正文内容
numbered-point-slide	带大号数字的编号列表项	清单、步骤
quote-slide	带出处的引言	社会认同、见解
cta-slide	行动号召	仅用于最后一张幻灯片

阅读 frontmatter，了解每种布局的限制和约束。

步骤 3：规划轮播图

典型的轮播图结构（5-10 张幻灯片）：

| # | Layout | Content |
|---|--------|---------|
| 1 | hook-slide | Attention-grabbing hook |
| 2-8 | single-point or numbered-point | Body content |
| 9/10 | cta-slide | Call to action |

轮播图内容规则：

• 每张幻灯片一个要点——不要塞入多个要点
• 大号文字——必须便于在手机上阅读
• 精简文案——标题最多 50 个字符，正文最多 150 个字符
• 脉络清晰——单独查看每张幻灯片时也应易于理解
• 开篇有吸引力——第一张幻灯片要让人停下滑动
• 行动号召明确——最后一张幻灯片要告诉读者该做什么

步骤 4：生成轮播图

轮播图尺寸（正方形 1:1）：

prs.slide_width = Inches(7.5)
prs.slide_height = Inches(7.5)

将所有幻灯片生成为一个 PPTX 文件（轮播图通常为 5-10 张，因此很少需要分批处理）。

执行：

uv run --with python-pptx==1.0.2 python << 'SCRIPT'
# Carousel generation code with 7.5" x 7.5" dimensions
SCRIPT

步骤 5：导出为 PDF

LinkedIn 轮播图帖子需要使用 PDF。将 PPTX 转换为 PDF：

选项 A：使用 LibreOffice（推荐）

libreoffice --headless --convert-to pdf --outdir output/rasmus output/rasmus/carousel.pptx

选项 B：使用 soffice

soffice --headless --convert-to pdf output/rasmus/carousel.pptx

**注意：**必须安装 LibreOffice。在 macOS 上：brew install --cask libreoffice

步骤 6：输出

保存两个文件：

• output/{brand}/{name}-carousel.pptx - 可编辑的源文件
• output/{brand}/{name}-carousel.pdf - 可用于 LinkedIn 的文件

轮播图检查清单

• 阅读品牌配置
• 阅读 cookbook/carousels/ 中的轮播图布局 frontmatter
• 规划轮播图结构（吸引注意力 → 正文 → 行动号召）
• 保持文字精简（检查 frontmatter 中的字符数限制）
• 使用 7.5" × 7.5" 尺寸
• 生成 PPTX
• 验证输出
• 导出为 PDF
• 在 LinkedIn 预览中测试 PDF

---

模式 3：布局的增删改查操作

创建新布局

当用户请求新的布局类型时：

1. 研究现有布局，了解其模式：

   Glob: .claude/skills/pptx-generator/cookbook/*.py
   

   阅读 2-3 个布局，了解：

   • 代码结构和导入项
   • 品牌变量的使用方式
   • 装饰元素的模式
   • 定位惯例

2. 按照以下质量标准进行设计：

   必须达到可用于生产环境的质量：

   • 外观专业、精致
   • 视觉效果吸引人（不平淡或泛泛而谈）
   • 装饰元素独具特色
   • 视觉层次分明
   • 恰当运用留白

   使用恰当的元素：

   • 图表 - 饼图、圆环图、条形图、柱状图，用于数据可视化
   • 图像 - 用于截图、照片的占位形状
   • 形状 - 圆形、矩形、平行四边形，增添视觉趣味
   • 卡片 - 带阴影的浮动卡片，营造层次感
   • 几何图案 - 固定在角落或边缘的醒目形状

   避免：

   • 纯文本布局
   • 没有样式的通用项目符号
   • 缺乏视觉冲击力的小型装饰元素
   • 所有内容都居中的乏味构图

3. 编写布局文件，并添加详细的 frontmatter：

   ⚠️ 重要：frontmatter 是为未来的 AI Agent 编写的文档。

   每个布局都必须包含全面的 frontmatter，指导未来的 AI Agent：

   • 何时使用此布局（以及何时不使用）
   • 如何正确使用
   • 存在哪些限制和约束
   • 某些选择为何重要

   #!/usr/bin/env -S uv run
   # /// script
   # requires-python = ">=3.11"
   # dependencies = [
   #     "python-pptx==1.0.2",
   # ]
   # ///
   # /// layout
   # name = "layout-name"
   # purpose = "When to use this layout - be specific"
   # best_for = [
   #     "Ideal use case 1",
   #     "Ideal use case 2",
   # ]
   # avoid_when = [
   #     "Situation to avoid 1 - and what to use instead",
   #     "Situation to avoid 2 - and what to use instead",
   # ]
   # max_items = 5  # or other relevant limits
   # instructions = [
   #     "Specific tip 1",
   #     "Specific tip 2",
   # ]
   # ///
   """
   LAYOUT: [Name]
   PURPOSE: [When to use this layout - be specific]
   
   CUSTOMIZE:
   - [List customizable elements]
   """
   
   # ... implementation
   

   必需的 frontmatter 字段（内容要详细且具体）：

   字段	说明	示例
   name	布局标识符（与文件名一致）	"multi-card-slide"
   purpose	简明的一句话描述	"一行展示多个卡片形式的项目，共 3-5 张卡片"
   best_for	详细列出理想适用场景	["恰好 3 个相关功能", "包含 3 个步骤的流程"]
   avoid_when	具体列出不适用的场景及替代方案	["超过 3 个项目时，请改用 multi-card-slide"]
   instructions	可操作的正确使用建议	["卡片标题必须简短：1-2 个词，最多 15 个字符"]

   可选但推荐的字段：

   字段	说明	示例
   max_* / min_*	项目数量的硬性限制	max_cards = 3、min_surrounding_items = 4
   *_max_chars	文本的字符数限制	card_title_max_chars = 15

   编写优质 frontmatter：

   ✅ **应该：**具体且可操作

   # avoid_when = [
   #     "More than 3 items - use multi-card-slide instead",
   #     "Long card titles (over 15 characters) - abbreviate or use content-slide",
   # ]
   # instructions = [
   #     "EXACTLY 3 cards required - no more, no less",
   #     "Card titles must be SHORT: 1-2 words, max 15 characters",
   #     "If titles are too long, abbreviate or use different layout",
   # ]
   

   ❌ **不应该：**含糊或没有帮助

   # avoid_when = ["Too many items", "Wrong content"]
   # instructions = ["Use correctly", "Follow the pattern"]
   

   将 frontmatter 视为在指导同事——如果不向你提问，他们需要了解什么才能正确使用此布局？

4. 保存到 cookbook：

   .claude/skills/pptx-generator/cookbook/{layout-name}-slide.py
   

5. 通过生成示例来测试新布局

编辑现有布局

1. 查找布局：

   Glob: .claude/skills/pptx-generator/cookbook/*{name}*.py
   

2. 阅读并理解当前结构，包括 frontmatter

3. 进行修改，同时保留：

   • 脚本头部格式
   • 品牌变量命名惯例
   • 文档字符串格式（LAYOUT、PURPOSE、CUSTOMIZE）

4. 如果更改影响以下内容，请更新 frontmatter：

   • 布局最适用的场景（best_for）
   • 应避免使用的场景（avoid_when）
   • 项目数量限制（max_*、min_*）
   • 使用说明（instructions）

5. 保存回同一文件

6. 测试修改后的布局

更新／改进布局

当被要求提升布局质量时：

1. 分析当前的不足：

   • 视觉效果是否吸引人？
   • 装饰元素是否足够？
   • 视觉层次是否清晰？
   • 空间利用是否合理？

2. 应用改进：

   • 添加醒目的几何形状
   • 改进配色
   • 增加层次感（阴影、重叠）
   • 调整字体大小
   • 添加更具特色的装饰元素

3. 保留功能——不要破坏已有的可用功能

4. 检查并完善 frontmatter：

   • best_for 和 avoid_when 是否仍然准确？
   • instructions 是否体现了新的约束？
   • 添加改进过程中总结的经验
   • 如果元素大小／数量发生变化，则更新限制

删除布局

只需删除文件：

rm .claude/skills/pptx-generator/cookbook/{layout-name}.py

---

编辑现有 PPTX 文件

当用户提供现有的 PPTX 文件时：

1. 读取文件：

   from pptx import Presentation
   prs = Presentation("path/to/existing.pptx")
   

2. 分析： 幻灯片数量、样式、内容结构

3. 应用更改： 添加／删除幻灯片、更新内容、修改样式

4. 保存到输出目录（除非用户要求，否则不要覆盖原文件）

---

技术参考

幻灯片尺寸（16:9）：

• 宽度：13.333 英寸
• 高度：7.5 英寸
• 安全边距：0.5 英寸

始终使用：

• 空白布局：prs.slide_layouts[6]
• python-pptx 版本：1.0.2

常用导入：

from pptx import Presentation
from pptx.chart.data import CategoryChartData
from pptx.dml.color import RGBColor
from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION
from pptx.enum.shapes import MSO_SHAPE
from pptx.enum.text import PP_ALIGN, MSO_ANCHOR
from pptx.util import Inches, Pt

可用的图表类型：

• XL_CHART_TYPE.PIE - 饼图
• XL_CHART_TYPE.DOUGHNUT - 环形图
• XL_CHART_TYPE.BAR_CLUSTERED - 水平条形图
• XL_CHART_TYPE.COLUMN_CLUSTERED - 垂直柱形图
• XL_CHART_TYPE.LINE - 折线图

添加图表：

chart_data = CategoryChartData()
chart_data.categories = ["A", "B", "C"]
chart_data.add_series("Values", [10, 20, 30])

slide.shapes.add_chart(
    XL_CHART_TYPE.DOUGHNUT,
    Inches(x), Inches(y),
    Inches(width), Inches(height),
    chart_data
)

添加图片：

slide.shapes.add_picture(
    "path/to/image.png",
    Inches(x), Inches(y),
    width=Inches(w)  # Height auto-calculated
)

---

预览所有布局

查看所有可用布局：

uv run .claude/skills/pptx-generator/generate-cookbook-preview.py

这会生成包含每种布局的 cookbook-preview.pptx。

---

检查清单

用于生成幻灯片：

• 读取 brand.json，了解颜色和字体
• 读取 config.json，了解输出目录和设置
• 读取 Markdown 文件，了解语气和风格
• 读取所有 cookbook 布局的 frontmatter（每个 .py 文件的前 40 行）：
  • 搜索所有 .claude/skills/pptx-generator/cookbook/*.py
  • 读取每个文件，提取 # /// layout 块
  • 全面了解所有 best_for、avoid_when 和限制
• 然后根据完整了解选择布局：
  • 根据 best_for 标准匹配内容
  • 遵循 avoid_when 警告
  • 检查 max_* / min_* 限制
  • 遵循所选布局的 instructions
• 生成前创建幻灯片计划表：
  • 列出所有幻灯片及其布局、标题和内容
  • 检查是否有重复标题
  • 确认逻辑流程合理
  • 分成多个批次（每批最多 5 张）
  • 多样性检查：内容型幻灯片少于总数的 25%
  • 多样性检查：同一布局的幻灯片不得连续出现 3 张或更多
  • 多样性检查：视觉型布局占演示文稿的 50% 或以上
  • 多样性检查：使用决策树评估每张内容型幻灯片
• 继续之前简要展示计划
• 应用品牌颜色和字体
• 使用品牌语气撰写内容
• 每批最多生成 5 张幻灯片（或使用配置中的 slides_per_batch）
• 通过 UV REPL 执行
• 继续之前验证输出：
  • 没有重复标题
  • 元素之间的间距恰当
  • 内容未超出边界
  • 颜色符合品牌规范
  • 标题和项目符号末尾没有标点
• 将批次保存到配置中的输出目录
• 如有需要，重复上述步骤处理下一批
• 将所有批次合并为最终 PPTX（如果 auto_combine 为 true）
• 清理分段文件（如果 keep_parts 为 false）

用于创建布局：

• 研究现有布局，了解其模式
• 采用适合投入生产的质量标准进行设计
• 添加独特的装饰元素
• 适当使用图表、图片和形状
• 添加 TOML 风格的 frontmatter，包含：
  • name、purpose
  • best_for、avoid_when 数组
  • 包含使用技巧的 instructions 数组
  • 视需要添加 max_* / min_* 限制
• 编写规范的文档字符串（LAYOUT、PURPOSE、CUSTOMIZE）
• 测试新布局