把一份 Markdown 或会议纪要交给 Claude Code 之后，很多人期待它直接吐出一个可以编辑的 .pptx。用 op7418/NanoBanana-PPT-Skills 前，先把这个边界弄清楚：它更像一个“PPT 画面生成器”，核心产物是一组 16:9 的幻灯片图片和一个 HTML 播放页；如果再配置可灵 AI 和 FFmpeg，才会进入转场视频链路。

这个边界不是缺点，反而决定了它适合什么场景。要快速把产品方案、课程大纲、会议纪要做成视觉效果统一的演示画面，它很顺；如果目标是后续在 PowerPoint 里逐字改文本、调形状、套公司母版，就要提前知道它不是传统 PPTX 编辑工作流。

先确认：它解决的是“做出一套可播放的 PPT 画面”

op7418/NanoBanana-PPT-Skills 的主线很清楚：Claude Code 负责读文档、规划页数和页面内容，项目里的 generate_ppt.py 再调用 Google Nano Banana Pro，也就是 Gemini 3 Pro Image Preview，生成每一页的图片。默认输出目录是 outputs/TIMESTAMP/，里面通常会看到 images/slide-01.png、index.html 和 prompts.json。

所以它最适合三类任务：第一，已有结构化文档，需要快速做成演示画面；第二，希望 PPT 风格统一，比如科技发布、培训课件、产品介绍；第三，要把静态页继续做成带转场的视频版本。它不适合拿来处理已有 PPT 文件，也不适合追求每个文本框都能在 PowerPoint 里继续编辑的场景。

内置风格目前主要是两条线：styles/gradient-glass.md 偏渐变毛玻璃，适合科技产品、商务演示、数据报告；styles/vector-illustration.md 偏矢量插画，适合教育培训、创意提案和品牌故事。新手第一次不要急着自定义风格，先用这两个文件跑通一遍，更容易判断问题出在文档结构、密钥还是生成模型。

安装时别只克隆仓库，密钥和依赖也要放对位置

作为 Claude Code Skill 使用时，推荐装到 ~/.claude/skills/ppt-generator。仓库提供了 install_as_skill.sh，会创建 Skill 目录、复制文件、安装 Python 依赖，并引导创建 .env。如果想手动安装，可以按下面这条路径走：

mkdir -p ~/.claude/skills/ppt-generator
git clone https://github.com/op7418/NanoBanana-PPT-Skills.git ~/.claude/skills/ppt-generator
cd ~/.claude/skills/ppt-generator
python3 -m venv venv
source venv/bin/activate
pip install google-genai pillow python-dotenv
cp .env.example .env

接下来编辑 ~/.claude/skills/ppt-generator/.env。图片生成必须有 GEMINI_API_KEY；KLING_ACCESS_KEY 和 KLING_SECRET_KEY 只在生成转场视频时需要。只想先生成 PPT 图片，后两项可以先留空。视频链路还要检查 ffmpeg -version，没有 FFmpeg 时，图片和 HTML 播放页仍然能用，但完整视频合成会卡住。

装完以后先做一个轻量检查，不要直接塞长文档：

cd ~/.claude/skills/ppt-generator
source venv/bin/activate
python3 generate_ppt.py --help

如果能看到 --plan、--style、--resolution、--output 这些参数，依赖层基本通了。下一步再回到 Claude Code，让它基于一小段内容生成 5 页、2K、只含图片的版本。第一次就上 15 页、4K、再加视频，排错范围会被拉得很大。

第一次试跑，把检查点放在输出目录里

可以在 Claude Code 里直接说：基于一段 500 字左右的产品说明生成 5 页 PPT，使用矢量插画风格，2K 分辨率，先只生成图片。这个请求足够小，既能验证文档分析和页面规划，也不会因为页数太多把 API 配额和等待时间一次耗掉。

成功后先看三个位置。第一，看 outputs/TIMESTAMP/images/ 里是否按顺序生成 slide-01.png、slide-02.png。第二，打开 outputs/TIMESTAMP/index.html，确认左右键翻页、全屏和播放页正常。第三，看 prompts.json 是否记录了每页内容和生成参数；这份文件不是给读者看的成品，但排查某一页效果不好时很有用。

图片稳定以后再考虑视频。视频模式要先让 Claude Code 分析已经生成的幻灯片图片，保存转场描述文件，例如 outputs/TIMESTAMP/transition_prompts.json，再运行：

python3 generate_ppt_video.py 
  --slides-dir outputs/TIMESTAMP/images 
  --output-dir outputs/TIMESTAMP_video 
  --prompts-file outputs/TIMESTAMP/transition_prompts.json

这一步依赖可灵 AI 密钥，也依赖 FFmpeg。生成完成后再看 outputs/TIMESTAMP_video/video_index.html 和 full_ppt_video.mp4。如果报可灵密钥未配置，先退回图片模式；如果报 FFmpeg 不可用，先安装 FFmpeg；如果某些页图像质量不稳，优先改输入文档和页数规划，不要急着重复跑视频。

几个容易踩坑的地方

第一，输入文档要有清楚层级。一个只有大段文字的文件，会让页面内容拆分变得模糊；带标题、分段、要点的 Markdown 更容易生成稳定结构。第二，每页内容不要太满，5 页演示可以按“封面、三个核心观点、总结”来拆，15 页以上再考虑章节和数据页。

第三，2K 比 4K 更适合第一次试跑。仓库文档里给出的经验是 2K 约 30 秒一页，4K 约 60 秒一页，文件也更大。第四，不要把视频功能当成默认必开项；转场视频会多出可灵 API、转场描述文件、并发限制和视频合成这些环节，任何一个环节出错都会增加排查成本。

总结一下，op7418/NanoBanana-PPT-Skills 更适合把结构化文档快速变成一套统一风格的 PPT 图片和播放页，视频转场是进阶功能。先装好 Skill 目录和 .env，用 5 页 2K 图片小样确认输出，再决定是否接入可灵和 FFmpeg，成功率会高很多。