paperbanana-slide-deck

PaperBanana 幻灯片

端到端创建和修改幻灯片。两种幻灯片模式（image 和 editable，在阶段 M 中明确选择）；其中，图像模式包含两种工作流：从头创建新幻灯片，以及修改提示词后重新生成现有幻灯片。

图像流水线： 内容 → 风格选择 → 大纲 → 提示词 → 图像生成 → 合并为 PPTX 可编辑流水线： 内容 → slide-spec.json（原生文本/表格/图表/形状/线条/组合）→ 验证 → 构建 PPTX → 渲染预览 → Critic 审核 → 修改规格 → 重新构建

阶段 M：选择幻灯片模式

在 deck-mode.txt 中准确记录一行：image 或 editable。

• 当用户要求在 PowerPoint 中编辑文本/表格/图表/连接线，或明确要求可编辑的 PPTX 时，使用 editable。
• 当用户要求生成整页艺术作品，或保留现有 PaperBanana 图像工作流时，使用 image。
• 如果两种模式都有可能，生成前先询问。不要根据文件是否存在来推断。
• editable 必须有 slide-spec.json；缺少或无效的规格均属于错误。声称支持编辑时，绝不能回退到图像模式。

模式检测（图像模式）

在图像模式下，检查目标目录以确定工作流：

条件	模式	开始阶段
目标目录不存在，或没有 outline.md	新建	阶段 R（完整 RDIV）
目标目录中有 outline.md 和 prompts/	修改	阶段 I（生成 + 合并）

在修改模式下，用户已在外部编辑提示词或大纲。直接跳至阶段 I。

依赖项

组件	用途	位置
google-genai SDK	路径 B 图像生成	pip install google-genai
PaperBanana CLI	路径 A 图像生成	python -m paperbanana.cli slide-batch
merge-to-pptx.ts	PPTX 合并（图像模式）	plugins/paperbanana-slide-deck/scripts/merge-to-pptx.ts
build-deck.ts	显式 --mode image|editable 路由器	plugins/paperbanana-slide-deck/scripts/build-deck.ts
可编辑渲染器	slide-spec.json → 原生 PPTX	plugins/paperbanana-slide-deck/scripts/editable/
风格库	风格预设（4 个来源，150+ 项）	参见 R1 中的发现路径
Bun	运行构建/合并脚本	bun

可编辑模式工作流

当 deck-mode.txt 指定 editable 时，跳过下文的阶段 R/D/I，改为遵循以下循环（契约详情和完整示例：references/editable-slide-spec.md）：

1. 仅生成无文本素材（照片、插画面板，不含渲染后的文本），使用 PaperBanana 生成；记录每个素材的 SHA-256。
2. 编写 slide-deck/{topic-slug}/slide-spec.json —— 在 13.333×7.5 英寸画布上使用原生 text、shape、line、table、chart、image 和 group 元素，并为每张幻灯片添加 [Sources] 演讲者备注。
3. 验证 + 构建（失败即关闭；缺少或无效的规格属于错误，绝不静默回退到图像模式）：

bun "${SKILL_DIR}/scripts/build-deck.ts" --mode editable "slide-deck/{topic-slug}"

4. 渲染 PPTX 预览，使用 LibreOffice + Poppler（先运行 soffice --headless --convert-to pdf，然后运行 pdftoppm -png -r 150 … slide → slide-NN.png）。
5. 在预览上运行 Critic（仅检查预览；绝不修改 PPTX）：

python3 "${SKILL_DIR}/scripts/editable/review-editable.py" \
  --spec "slide-deck/{topic-slug}/slide-spec.json" \
  --rendered-dir "slide-deck/{topic-slug}/rendered" \
  --output "slide-deck/{topic-slug}/critic-review.json"

6. 将问题对应到元素 ID（建议以 slide-id/element-id: … 的形式给出），修改 slide-spec.json 并重新构建。重复此过程，直至没有问题。

阶段 R：研究（仅限新建模式）

在修改模式下完全跳过此阶段。

R1：发现样式库 — 扫描全部四个来源，并合并为统一列表。

# Source 0 (PRIMARY): Local extended library (123 styles from Fooocus/ComfyUI, structured)
LOCAL_STYLES="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)/references/styles"

# Source 1: baoyu-slide-deck styles (16 slide-optimized)
BAOYU_SLIDE=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-slide-deck/references/styles 2>/dev/null | head -1)

# Source 2: baoyu-infographic styles (20 visual-rich)
BAOYU_INFOG=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-infographic/references/styles 2>/dev/null | head -1)

# Source 3: theme-factory themes (10 color/typography presets)
THEME_FACTORY=$(ls -td ~/.claude/plugins/cache/anthropic-agent-skills/document-skills/*/skills/theme-factory/themes 2>/dev/null | head -1)

合并：对全部四个目录执行 Glob，查找 *.md，按文件名去重（优先级：baoyu-slide-deck > local > baoyu-infographic > theme-factory）。在 R3 期间向用户展示完整的统一列表。

如果未找到任何样式：使用 PaperBanana 内置的 23 种预设。

R2：分析内容 — 主题、受众、语气、建议的幻灯片数量。

R3：推荐样式 — 根据内容特征推荐 2-3 种样式。完整的样式与内容映射表请参阅 references/style-guide.md。

R4：交互式选择 — 使用 AskUserQuestion 询问用户的样式、受众和幻灯片数量。

R5：保存分析 — 创建 slide-deck/{topic-slug}/analysis.md。

阶段 D：设计（仅限新建模式）

在修改模式下，用户直接处理提示词编辑。

D1：加载样式规范 — 从 baoyu 样式库或 PaperBanana 内置样式中读取。

D2：生成大纲 — 创建包含幻灯片结构的 outline.md。请参阅 references/outline-format.md。

D3：可选的大纲审阅 — 询问用户是否希望在继续之前审阅大纲。

D4：生成提示词 — 为每张幻灯片创建 prompts/NN-slide-{slug}.md。每个提示词文件先包含样式说明块，然后是 ---，接着是该幻灯片专属的内容和设计要求。

阶段 I：实现（两种模式均适用）

步骤 I1：图像生成（双路径）

路径 A — PaperBanana CLI（首选，具有评审器质量审查）：

cd <project_root>
python -m paperbanana.cli slide-batch \
  --prompts-dir "slide-deck/{topic-slug}/prompts" \
  --output-dir "slide-deck/{topic-slug}" \
  --resolution 4k \
  --iterations 2

自动降级触发条件： 如果任意幻灯片（不只是第一张）遇到以下情况之一，则切换到路径 B。不要继续重试路径 A：

• RetryError / ResourceExhausted / HTTP 429（请求受限）
• ServerError（5xx）或非 429 的 ClientError（4xx）
• 任意单张幻灯片的评审器处理时间超过 3 分钟
• 用户报告“一直 429”/持续受到请求速率限制 → 立即降级，跳过路径 A 的后续重试

区分两种 429 来源：

来源	表现	处理方式
评审器 429（VLM 请求速率限制）	错误出现在评审器循环中，是路径 A 特有的	自动降级到路径 B（没有评审器 → 绕过此问题）
图像生成 429（gemini-3-pro-image-preview）	路径 B 中出现相同错误	指数退避：time.sleep(30 * 2**retry)，最长等待 5 分钟，然后告知用户

部分批次恢复：如果遇到 429 前已生成部分幻灯片，则保留现有 PNG，并从下一张缺失的幻灯片继续（交叉比对 prompts/*.md 与现有的 NN-slide-*.png）。

注意（上游同步待完成）： 上游 paperbanana CLI（≥ #129）已为路径 A 的 slide-batch 原生支持 batch_checkpoint.json，因此会自动恢复。上述跳过逻辑适用于路径 B 的后备代码，该代码目前尚未使用上游检查点格式。

路径 B — 直接调用 Gemini API（后备方案，无评审器，稳定）：

from google import genai
from google.genai import types
from PIL import Image
from io import BytesIO
import base64, os, time

# Read API key from paperbanana/.env
client = genai.Client(api_key=GOOGLE_API_KEY)

config = types.GenerateContentConfig(
    response_modalities=['IMAGE'],
    image_config=types.ImageConfig(
        aspect_ratio='16:9',
        image_size='4K',
    ),
)

MAX_RETRIES = 5   # after which surface to user
BASE_SLEEP = 30   # seconds

for prompt_file in sorted(os.listdir(prompts_dir)):
    name = prompt_file.replace('.md', '')
    out_path = os.path.join(output_dir, f'{name}.png')

    # Partial-batch resume: skip slides already generated
    if os.path.exists(out_path):
        continue

    with open(os.path.join(prompts_dir, prompt_file), 'r', encoding='utf-8') as f:
        prompt_text = f.read()

    # Exponential backoff on 429 / transient errors
    for retry in range(MAX_RETRIES):
        try:
            response = client.models.generate_content(
                model='gemini-3-pro-image-preview',
                contents=prompt_text,
                config=config,
            )
            break
        except Exception as e:
            msg = str(e).lower()
            if '429' in msg or 'resource' in msg or 'rate' in msg:
                wait = min(BASE_SLEEP * (2 ** retry), 300)  # cap at 5 min
                time.sleep(wait)
                continue
            raise  # non-429 error → surface immediately
    else:
        raise RuntimeError(f'{name}: 429 after {MAX_RETRIES} retries, surface to user')

    for part in response.candidates[0].content.parts:
        inline = getattr(part, 'inline_data', None)
        if inline and getattr(inline, 'data', None):
            data = inline.data
            img_bytes = base64.b64decode(data) if isinstance(data, str) else data
            img = Image.open(BytesIO(img_bytes))
            img.save(out_path, 'PNG')
            break

    time.sleep(BASE_SLEEP)  # baseline cooldown between slides

API 密钥位于 <project_root>/paperbanana/.env 中，变量名为 GOOGLE_API_KEY。使用 dotenv 或手动读取。

步骤 I2：智能清理（合并前）

在 I1 生成完成后运行，而不是之前。 I1 支持部分批次处理，会跳过已生成的幻灯片；清理的唯一作用是移除自上次运行以来提示词已被删除或重命名的 PNG。在 I1 之前运行清理会删除恢复批次中的有效 WIP 幻灯片。

执行顺序：I1（生成 + 恢复）→ I2（清理孤立文件）→ I3（合并）。

1. 扫描 prompts/*.md → 构建预期 PNG 集合（例如，01-slide-hook.md → 01-slide-hook.png）
2. 扫描目标目录，查找符合 NN-slide-*.png 模式的 *.png 文件
3. 删除不在预期集合中的幻灯片 PNG（提示词重命名或删除后遗留的孤立文件）
4. 保留非幻灯片 PNG（例如 logo.png、background.png）以及预期集合中的所有 PNG

步骤 I3：合并为 PPTX

# Locate skill directory dynamically (works on any platform)
SKILL_DIR="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)"
bun "${SKILL_DIR}/scripts/merge-to-pptx.ts" "slide-deck/{topic-slug}"

如果合并脚本不可用：告知用户 PNG 图像已就绪，但合并为 PPTX 需要 bun 和本地的 merge-to-pptx.ts 脚本。

阶段 V：验证（两种模式）

V1：显示结果 — 读取并显示每张生成的幻灯片图片。报告幻灯片总数、输出目录和 PPTX 文件路径。

V2：用户反馈 — 询问：

• “效果很好，完成！”
• “重新生成——我会告诉你提示词需要修改的地方”

V3：重新生成 — 如果用户想要修改：

1. 用户编辑指定的提示词文件
2. 重新生成所有幻灯片（而不只是修改过的幻灯片——确保视觉一致性）
3. 执行智能清理 + 重新合并 PPTX
4. 返回 V1

回退行为

情况	回退方案
所有样式库均缺失	使用 PaperBanana 内置预设
本地合并脚本缺失	仅输出 PNG，跳过 PPTX
缺少 Bun/npx	跳过 PPTX 合并，并告知用户
Critic 429 / RetryError	自动降级为路径 B（无 critic）
路径 B 中的图像生成遇到 429	采用指数退避，最长等待 5 分钟，然后报告错误
批次已部分生成	从下一张缺失的幻灯片继续，并保留现有 PNG

输出结构

slide-deck/{topic-slug}/
  analysis.md            ← R phase (New mode only)
  outline.md             ← D phase
  prompts/               ← D phase
    01-slide-hook.md
    02-slide-cover.md
    ...
  01-slide-hook.png      ← I phase
  02-slide-cover.png
  ...
  {topic-slug}.pptx      ← I phase

快速参考

# Path A: PaperBanana CLI batch
python -m paperbanana.cli slide-batch --prompts-dir prompts/ --resolution 4k --iterations 2

# Path A: single slide (supports --vlm-model)
python -m paperbanana.cli slide --input prompt.md --resolution 4k

# List available styles
python -m paperbanana.cli slide --list-styles