nano-banana

Nano Banana

使用 Gemini 的图像生成 API 生成高质量的演示文稿幻灯片图像，在浏览器中交互式预览，并根据反馈迭代编辑。

适用场景

• 用户要求创建演示文稿、幻灯片或 PPT
• 用户想为演讲或讲座生成视觉效果丰富的幻灯片
• 用户有文档或大纲，并希望据此制作幻灯片
• 用户说“帮我做个 PPT”“生成幻灯片”“创建演示文稿”
• 用户想编辑或完善已生成的幻灯片
• 用户需要用于论文或文档的高质量图表、示意图或插图
• 用户要求生成研究图表、架构图或概念插图

请勿用于：

• 撰写学术论文 → 使用 paper-writing
• 规划学术会议演讲的叙事结构 → 使用 academic-slides

---

开始之前：前置条件

开始生成幻灯片之前，请确认满足以下前置条件。本文档中的脚本和样式路径均相对于此技能目录。

1. 依赖项：pip install pillow google-genai python-pptx python-dotenv（也列在技能根目录的 requirements.txt 中）。请将依赖项安装到用户当前使用的环境中。Atlas Cloud 使用相同的依赖项，无需额外的 SDK。

2. 提供方和 API 密钥：Gemini 是默认提供方。请检查是否有可用的 API 密钥：

   echo $GOOGLE_API_KEY
   

   如果为空，请让用户提供密钥。用户可以通过以下任一方式提供：

   • 通过配置设置：EvoSci config set google_api_key <key>
   • 直接提供（通过 --api-key 参数传入）
   • 如果用户在对话中提供密钥，请通过 --api-key 将其传给脚本

   若要改用 Atlas Cloud，请设置 ATLASCLOUD_API_KEY 并传入 --provider atlas。Atlas Cloud 需主动选择，不会改变默认的 Gemini 工作流。

3. 语言：询问用户幻灯片内容应使用哪种语言。这会影响你在 slides_plan.json 中编写的内容，而不会影响样式模板。

---

核心工作流

Phase 1: Content Planning Conversation     ← most important phase
Phase 2: Generate slides_plan.json
Phase 3: Select Style & Generate Slides
Phase 4: Launch Review Server
Phase 5: Apply Feedback Edits              ← repeat Phase 4-5 until satisfied
Phase 6: Package as PPTX
Phase 7: Cleanup

请按顺序完成以下阶段。请勿跳过阶段 1——生成幻灯片的质量直接取决于规划的深度。

---

阶段 1：内容规划对话

这是最关键的阶段。未充分规划便仓促生成，会导致幻灯片质量平庸。请与用户进行结构化对话：

步骤 1 — 了解背景：

• 演示主题是什么？
• 受众是谁？（技术同行、高管、学生、普通公众）
• 演讲时长是多少？（这决定页数）
• 使用场合是什么？（会议、内部演讲、讲座、提案）

步骤 2 — 确定故事线：

• 开场引子是什么？（一个令人惊讶的事实、一个问题、一种趋势）
• 主要章节或论点有哪 3–5 个？
• 希望观众记住的核心要点是什么？
• 结尾信息是什么？

步骤 3 — 制定逐页内容大纲：

• 为每张幻灯片确定：标题 + 2–4 个要点 + 视觉描述
• 标明哪些幻灯片属于封面、内容页或数据页
• 确保各页之间逻辑连贯

时长与页数参考：

时长	页数	结构
5 分钟	5	封面 + 3 页内容 + 结尾
10–15 分钟	8–12	封面 + 引言 + 3–4 个章节 + 总结 + 结尾
20–30 分钟	15–20	封面 + 引言 + 5–6 个章节 + 总结 + 结尾
45–60 分钟	25–30	封面 + 引言 + 7–9 个章节（每个章节 2–3 页）+ 总结 + 结尾

如果用户提供了文档或大纲，请先通读，再提出幻灯片内容拆分方案，待用户批准后再继续。

---

阶段 2：生成 slides_plan.json

在工作区根目录中创建 slides_plan.json 文件，遵循以下架构：

{
  "title": "Presentation Title",
  "total_slides": 10,
  "slides": [
    {
      "slide_number": 1,
      "page_type": "cover",
      "content": "Title: My Presentation\nSubtitle: A subtitle here\nLabel: 2026 Edition"
    },
    {
      "slide_number": 2,
      "page_type": "content",
      "content": "Title: First Topic\nKey points:\n- Point one\n- Point two\n- Point three"
    },
    {
      "slide_number": 3,
      "page_type": "data",
      "content": "Title: Key Metrics\nMetric 1: 95% accuracy\nMetric 2: 3x faster\nMetric 3: 10k users"
    }
  ]
}

page_type 可选值： cover、content、data

内容字段关键规则

content 字段会传递给图像生成模型。请严格遵守以下规则：

1. 务必撰写描述性标题和项目符号
2. 务必描述你想要的视觉布局（例如“左右对比”“4 个图标卡片”）
3. 不要在行首添加“Slogan:”“Visual:”“Points:”或任何元标签——模型会将这些内容渲染为幻灯片上的可见文本
4. 不要在标题区域和内容底部重复相同的句子——这会导致重复
5. 不要添加页脚文字、页码或水印说明

错误示例（元标签会泄漏为可见文本）：

Title: Why AI Matters
Visual: left-right comparison chart
Points:
- Point one
- Point two
Slogan: AI changes everything

正确示例（简洁，不含元标签）：

Title: Why AI Matters
Visual layout: left-right comparison chart showing traditional vs AI approach
Key points:
- Point one with brief explanation
- Point two with brief explanation
Bottom tagline: AI changes everything

---

第 3 阶段：选择风格并生成幻灯片

可用风格

风格	文件	视觉特征	最适用场景
线性彩色	styles/lineal-color.md	白色背景、青绿色点缀、扁平 2D 图标、信息卡片	技术演讲、讲座、教育
渐变玻璃	styles/gradient-glass.md	浅色柔和背景、磨砂玻璃卡片、Apple Keynote 风格	产品发布、推介、SaaS
矢量插画	styles/vector-illustration.md	奶油色背景、黑色轮廓、复古色彩、玩具模型般的魅力	教育、儿童内容、品牌故事

向用户展示这些风格并让他们选择。如果不确定，推荐默认使用线性彩色。

可用模型

模型	速度	质量	适用场景
gemini-3-pro-image-preview	中等	最佳	最终版本、重要演示文稿
gemini-3.1-flash-image-preview	快	良好	草稿、快速迭代、大型幻灯片组
gemini-2.5-flash-image	最快	基本	快速原型、批量生成
google/nano-banana-2-lite/text-to-image	快	良好	使用 Atlas Cloud 以 1K 分辨率生成幻灯片
google/nano-banana-2-lite/edit	快	良好	使用 Atlas Cloud 以 1K 分辨率编辑幻灯片

首次生成时，推荐使用 gemini-3.1-flash-image-preview（迭代速度快）。最终版本切换到 gemini-3-pro-image-preview。

生成命令

python scripts/generate_ppt.py \
  --plan slides_plan.json \
  --style styles/lineal-color.md \
  --model gemini-3.1-flash-image-preview \
  --output ppt_output

Atlas Cloud 可作为可选提供方使用：

python scripts/generate_ppt.py \
  --plan slides_plan.json \
  --style styles/lineal-color.md \
  --provider atlas \
  --output ppt_output

参数：

• --plan（必需）：slides_plan.json 的路径
• --style（必需）：风格模板的路径
• --provider：gemini（默认）或 atlas
• --model：图像生成模型（默认为 gemini-3-pro-image-preview；Atlas 仅接受 google/nano-banana-2-lite/text-to-image）
• --resolution：Gemini 支持 2K（默认）或 4K；Atlas 使用 1K
• --output：输出目录（默认：ppt_output/TIMESTAMP）
• --api-key：提供方 API 密钥（如果未设置提供方环境变量）
• --workers：并行工作线程数（默认：1，大型幻灯片组建议设为 3-5）

输出结构：

ppt_output/
├── images/
│   ├── slide-01.png
│   ├── slide-02.png
│   └── ...
├── prompts.json    # All prompts used (for debugging)
└── index.html      # Browser viewer

退出代码。 0 表示所有幻灯片均已生成。2 表示已写入部分幻灯片组：stderr 的最后一行会列出缺失的幻灯片编号（Failed slides: 3, 7），每次失败都会打印为 [n/total] FAIL: <reason>。重新运行命令会重新生成整个幻灯片组，因此如果失败原因相同（配额、密钥、模型名称），请先解决该问题。1 表示未生成任何幻灯片（或缺少 API 密钥／库）；目前无需检查。

---

第 4 阶段：启动审核服务

启动交互式审核服务，让用户检查幻灯片并撰写反馈：

python scripts/serve_viewer.py \
  --dir ppt_output \
  --plan slides_plan.json \
  --port 8080 \
  --pid-file .viewer.pid

告诉用户：

审核服务正在 http://localhost:8080 运行。在浏览器中打开该地址，即可检查每张幻灯片。在需要修改的幻灯片下方文本框中填写反馈，然后点击“Save Feedback”。完成后告诉我。

服务会将反馈直接保存到 slides_plan.json 中每张幻灯片的 feedback 字段。

请等待用户确认已保存反馈后再继续。

---

第 5 阶段：应用反馈修改

读取 slides_plan.json，找出所有 feedback 字段非空的幻灯片。对每张幻灯片运行编辑脚本：

python scripts/edit_slide.py \
  --input ppt_output/images/slide-{NUMBER}.png \
  --instruction "{FEEDBACK_TEXT}" \
  --output ppt_output/images/slide-{NUMBER}.png \
  --model gemini-3.1-flash-image-preview

要通过 Atlas Cloud 进行编辑，脚本会先上传本地源图像，供临时生成使用，然后再提交编辑任务：

python scripts/edit_slide.py \
  --input ppt_output/images/slide-01.png \
  --instruction "Remove the footer text at the bottom" \
  --output ppt_output/images/slide-01.png \
  --provider atlas

参数：

• --input（必需）：原始幻灯片图像的路径
• --instruction（必需）：编辑指令（来自 feedback 字段）
• --output：输出路径（默认：覆盖输入文件）
• --provider：gemini（默认）或 atlas
• --model：图像编辑模型（默认：gemini-3-pro-image-preview；Atlas 仅接受 google/nano-banana-2-lite/edit）
• --api-key：服务提供商 API 密钥（如果未设置在服务提供商环境变量中）

edit_slide.py 成功时会打印 OK: <path> 并以状态码 0 退出；失败时会打印 FAIL: <reason> 并以状态码 1 退出。如果缺少必需的 Python 包，两个脚本都会在发出任何请求前以状态码 1 退出。

Atlas 生成 POST 请求只会提交一次，不会重试。只有预测 GET 请求会使用有界轮询。

编辑完所有有反馈的幻灯片后，清空 slides_plan.json 中的 feedback 字段，并告知用户刷新浏览器以查看更新后的幻灯片。

如果用户还有更多反馈，请重复第 4 至第 5 阶段。这个审阅—编辑循环会持续进行，直到用户满意。

---

第 6 阶段：打包为 PPTX

用户批准所有幻灯片后，询问所需的文件名并进行打包：

python scripts/package_pptx.py \
  --dir ppt_output/images \
  --output presentation.pptx \
  --kill-server .viewer.pid

参数：

• --dir（必需）：包含 slide-XX.png 图像的目录
• --output（必需）：输出 .pptx 文件路径
• --kill-server：来自 serve_viewer.py 的 PID 文件 — 打包完成后自动停止审阅服务

---

第 7 阶段：清理

• package_pptx.py --kill-server 会自动停止审阅服务
• 询问用户是否要保留 ppt_output/ 目录，或将其清理
• 可以保留 slides_plan.json，以便将来重新生成

---

容易违反直觉的规则

1. 内容中绝不包含元标签 — “Slogan:”“Visual:”“Points:”等词会作为可见文本显示在幻灯片上。请直接描述所需内容，不要添加前缀。

2. 内容描述的是“是什么”，而不是“怎么做” — 风格模板负责视觉布局。content 字段应侧重文本和逻辑结构，而不是颜色或位置。

3. 规划越充分，幻灯片效果越好 — 在第 1 阶段的交流上花 10 分钟，可以节省数小时的重新生成时间。不要急着进入第 3 阶段。

4. 编辑，而非重新生成 — 幻灯片只需小幅修改时（修正文字、更改颜色、移除页脚），请使用 edit_slide.py，不要从头重新生成。编辑可以保持视觉风格一致。

5. 草稿使用 flash 模型 — gemini-3.1-flash-image-preview 的速度足以支持迭代。只有在处理完所有反馈并制作最终版本时，才切换到 gemini-3-pro-image-preview。

6. 绝不要自行查看生成的图像 — 并非所有模型都支持多模态输入。不要使用 read_file 检查生成的 PNG 图像质量。务必启动审阅服务，让用户在浏览器中查看幻灯片。用户的反馈是唯一的质量评估依据。

7. 每张幻灯片只表达一个观点 — 不要在一张幻灯片中塞入多个概念。如果一张幻灯片包含超过 4 个项目符号，请拆成两张。

8. 底部标语不应重复标题 — 如果标题是“Why AI Matters”，底部标语应补充新见解，而不是重复标题。

---

脚本参考

脚本	用途	关键参数
scripts/generate_ppt.py	根据计划批量生成所有幻灯片	--plan、--style、--provider、--model、--output、--resolution、--api-key、--workers
scripts/edit_slide.py	根据指令编辑单张幻灯片	--input、--instruction、--output、--provider、--model、--api-key
scripts/atlas_image.py	提交并轮询可选的 Atlas Cloud 图像任务	由生成和编辑脚本使用
scripts/serve_viewer.py	带反馈功能的本地审阅服务器	--dir、--plan、--port、--no-open、--pid-file
scripts/package_pptx.py	将幻灯片图像打包为 .pptx	--dir、--output、--kill-server

---

样式模板格式

样式模板是 styles/ 中采用固定结构的 Markdown 文件，generate_ppt.py 会解析这些文件：

部分	用途	由代码解析
## Base Prompt	所有幻灯片共用的视觉规范	是 — 注入每个提示词
## Page Templates	每种页面类型的布局说明	仅作为后备
## Examples	使用 {Base Prompt} 和 [Content] 占位符的实际提示词模板	是 — 主要模板
其他部分	仅供文档说明	否

要创建新样式：复制现有的 .md 文件，并修改 ## Base Prompt 和 ## Examples 部分。代码会从 ## Examples 中提取 ### Cover、### Content 和 ### Data 代码块。