必需：
- GEMINI_API_KEY: Google AI API 密钥（用于生成 PPT 图片）
可选（用于视频功能）：
- KLING_ACCESS_KEY: 可灵 AI Access Key
- KLING_SECRET_KEY: 可灵 AI Secret Key
pip install google-genai pillow python-dotenv
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg
/ppt-generator-pro
或直接向 Claude 说明：
我想基于以下文档生成一个 5 页的 PPT，使用渐变毛玻璃风格。
[文档内容...]
选项 A: 文档路径
用户: 基于 my-document.md 生成 PPT
→ 使用 Read 工具读取文件内容
选项 B: 直接文本
用户: 我想生成一个关于 AI 产品设计的 PPT
主要内容：
1. 现状分析
2. 设计原则
3. 案例研究
选项 C: 主动询问
如果用户未提供内容，则询问：
"请提供文档路径或直接粘贴文档内容"
扫描 styles/ 目录，列出可用风格：
# 自动检测风格文件
styles = ['gradient-glass.md', 'vector-illustration.md']
如果有多个风格，使用 AskUserQuestion：
问题: 请选择 PPT 风格
选项:
- 渐变毛玻璃卡片风格（科技感、商务演示）
- 矢量插画风格（温暖、教育培训）
使用 AskUserQuestion 询问：
问题: 希望生成多少页 PPT？
选项:
- 5 页（5 分钟演讲）
- 5-10 页（10-15 分钟演讲）
- 10-15 页（20-30 分钟演讲）
- 20-25 页（45-60 分钟演讲）
问题: 选择图片分辨率
选项:
- 2K (2752x1536) - 推荐，快速生成
- 4K (5504x3072) - 高质量，适合打印
如果配置了可灵 AI 密钥，询问：
问题: 是否生成转场视频？
选项:
- 仅图片（快速）
- 图片 + 转场视频（完整体验）
根据页数范围，智能规划每一页内容：
5 页版本：
1. 封面：标题 + 核心主题
2. 要点 1：第一个核心观点
3. 要点 2：第二个核心观点
4. 要点 3：第三个核心观点
5. 总结：核心结论或行动建议
5-10 页版本：
1. 封面
2-3. 引言/背景
4-7. 核心内容（3-4 个关键观点）
8-9. 案例或数据支持
10. 总结与行动建议
10-15 页版本：
1. 封面
2-3. 引言/目录
4-6. 第一章节（3 页）
7-9. 第二章节（3 页）
10-12. 第三章节/案例研究
13-14. 数据可视化
15. 总结与下一步
20-25 页版本：
1. 封面
2. 目录
3-4. 引言和背景
5-8. 第一部分（4 页）
9-12. 第二部分（4 页）
13-16. 第三部分（4 页）
17-19. 案例研究
20-22. 数据分析和洞察
23-24. 关键发现和建议
25. 总结与致谢
创建 JSON 文件：
{
"title": "文档标题",
"total_slides": 5,
"slides": [
{
"slide_number": 1,
"page_type": "cover",
"content": "标题：AI 产品设计指南\n副标题：构建以用户为中心的智能体验"
},
{
"slide_number": 2,
"page_type": "content",
"content": "核心原则\n- 简单直观\n- 快速响应\n- 透明可控"
},
{
"slide_number": 3,
"page_type": "content",
"content": "设计流程\n1. 用户研究\n2. 原型设计\n3. 测试迭代"
},
{
"slide_number": 4,
"page_type": "data",
"content": "用户满意度\n使用前：65%\n使用后：92%\n提升：+27%"
},
{
"slide_number": 5,
"page_type": "content",
"content": "总结\n- 以用户为中心\n- 持续优化迭代\n- 数据驱动决策"
}
]
}
重要： 将此文件保存到：
- 独立使用：./slides_plan.json
- Skill 模式：.claude/skills/ppt-generator/slides_plan.json
独立模式：
cd /path/to/ppt-generator
Skill 模式：
cd ~/.claude/skills/ppt-generator
python generate_ppt.py \
--plan slides_plan.json \
--style styles/gradient-glass.md \
--resolution 2K
或使用 uv run（推荐）：
uv run python generate_ppt.py \
--plan slides_plan.json \
--style styles/gradient-glass.md \
--resolution 2K
参数说明：
- --plan: slides 规划 JSON 文件路径
- --style: 风格文件路径
- --resolution: 分辨率（2K 或 4K）
- --template: HTML 模板路径（可选）
脚本会输出进度信息：
✅ 已加载环境变量: /path/to/.env
📊 开始生成 PPT 图片...
总页数: 5
分辨率: 2K (2752x1536)
风格: 渐变毛玻璃卡片风格
🎨 生成第 1 页 (封面页)...
提示词已生成
调用 Nano Banana Pro API...
✅ 第 1 页生成成功 (32.5 秒)
🎨 生成第 2 页 (内容页)...
✅ 第 2 页生成成功 (28.3 秒)
...
✅ 所有页面生成完成！
📁 输出目录: outputs/20260112_143022/
这是 Skill 的核心优势：我（Claude Code）会分析生成的 PPT 图片，为每个转场生成精准的视频提示词。
我会读取所有生成的图片：
# 自动读取输出目录中的所有图片
slides = ['slide-01.png', 'slide-02.png', ...]
对于每对相邻图片，我会：
1. 视觉分析：理解两张图片的布局、元素、色彩差异
2. 生成预览提示词：为首页创建可循环的微动效描述
3. 生成转场提示词：详细描述如何从起始帧过渡到结束帧
示例输出：
{
"preview": {
"slide_path": "outputs/.../slide-01.png",
"prompt": "画面保持封面的静态构图，中心的3D玻璃环缓慢旋转..."
},
"transitions": [
{
"from_slide": 1,
"to_slide": 2,
"prompt": "镜头从封面开始，玻璃环逐渐解构，分裂成透明碎片..."
}
]
}
我会将生成的提示词保存到：
outputs/TIMESTAMP/transition_prompts.json
关键优势：
- ✅ 不需要单独的 Claude API 密钥
- ✅ 提示词针对实际图片内容定制
- ✅ 考虑文字稳定性，避免视频模型弄模糊文字
- ✅ 符合渐变毛玻璃风格的视觉语言
如果用户选择生成视频，使用阶段 4 生成的提示词文件：
python generate_ppt_video.py \
--slides-dir outputs/20260112_143022/images \
--output-dir outputs/20260112_143022_video \
--prompts-file outputs/20260112_143022/transition_prompts.json
生成内容：
- 首页循环预览视频（preview.mp4）
- 页面间转场视频（transition_01_to_02.mp4 等）
- 交互式视频播放器（video_index.html）
- 完整视频（full_ppt_video.mp4）
✅ PPT 生成成功！
📁 输出目录: outputs/20260112_143022/
🖼️ PPT 图片: outputs/20260112_143022/images/
🎬 播放网页: outputs/20260112_143022/index.html
打开播放网页:
open outputs/20260112_143022/index.html
播放器快捷键:
- ← → 键: 切换页面
- ↑ Home: 回到首页
- ↓ End: 跳到末页
- 空格: 暂停/继续自动播放
- ESC: 全屏切换
- H: 隐藏/显示控件
✅ PPT 视频生成成功！
📁 输出目录: outputs/20260112_143022_video/
🖼️ PPT 图片: outputs/20260112_143022/images/
🎬 转场视频: outputs/20260112_143022_video/videos/
🎮 交互式播放器: outputs/20260112_143022_video/video_index.html
🎥 完整视频: outputs/20260112_143022_video/full_ppt_video.mp4
打开交互式播放器:
open outputs/20260112_143022_video/video_index.html
播放逻辑:
1. 首页: 播放循环预览视频
2. 按右键 → 播放转场视频 → 显示目标页图片（2 秒）
3. 再按右键 → 播放下一个转场 → 显示下一页图片
4. 依此类推...
视频播放器快捷键:
- ← → 键: 上一页/下一页（含转场）
- 空格: 播放/暂停当前视频
- ESC: 全屏切换
- H: 隐藏/显示控件
Skill 会按以下顺序查找 .env 文件：
./ppt-generator/.env.git 或 .env 的目录~/.claude/skills/ppt-generator/.env# Google AI API 密钥（必需）
GEMINI_API_KEY=your_gemini_api_key_here
# 可灵 AI API 密钥（可选，用于视频功能）
KLING_ACCESS_KEY=your_kling_access_key_here
KLING_SECRET_KEY=your_kling_secret_key_here
1. API 密钥未设置
错误: ⚠️ 未找到 .env 文件，尝试使用系统环境变量
未设置 GEMINI_API_KEY 环境变量
解决:
1. 创建 .env 文件
2. 添加 GEMINI_API_KEY=your_key_here
2. Python 依赖缺失
错误: ModuleNotFoundError: No module named 'google.genai'
解决: pip install google-genai pillow python-dotenv
3. FFmpeg 未安装
错误: ❌ FFmpeg 不可用！
解决: brew install ffmpeg # macOS
sudo apt-get install ffmpeg # Ubuntu
4. API 调用失败
错误: API 调用超时或失败
解决:
1. 检查网络连接
2. 确认 API 密钥有效
3. 稍后重试
5. 视频生成失败
错误: 可灵 AI 密钥未配置
解决:
1. 如果只需要图片，跳过视频生成步骤
2. 如果需要视频，配置 KLING_ACCESS_KEY 和 KLING_SECRET_KEY
gradient-glass.md)视觉特点：
- Apple Keynote 极简主义
- 玻璃拟态效果
- 霓虹紫/电光蓝/珊瑚橙渐变
- 3D 玻璃物体 + 电影级光照
适用场景：
- 科技产品发布
- 商务演示
- 数据报告
- 企业品牌展示
vector-illustration.md)视觉特点：
- 扁平化矢量设计
- 统一黑色轮廓线
- 复古柔和配色
- 几何化简化
适用场景：
- 教育培训
- 创意提案
- 儿童相关
- 温暖品牌故事
styles/ 目录创建新的 .md 文件Nano Banana Pro（图片生成）：
- 模型：gemini-3-pro-image-preview
- 比例：16:9
- 响应模式：IMAGE
- 分辨率：2K (2752x1536) 或 4K (5504x3072)
可灵 AI（视频生成）：
- 模式：专业模式（professional）
- 时长：5 秒
- 分辨率：1920x1080
- 帧率：24fps
FFmpeg（视频合成）：
- 编码：H.264
- 质量：CRF 23
- 帧率：24fps（统一）
- 分辨率：1920x1080（统一）
生成速度：
- PPT 图片：~30 秒/页（2K）| ~60 秒/页（4K）
- 转场视频：~30-60 秒/段
- 视频合成：~5-10 秒
文件大小：
- PPT 图片：~2.5MB/页（2K）| ~8MB/页（4K）
- 转场视频：~3-5MB/段（1080p，5 秒）
- 完整视频：~12-20MB（5 页 PPT + 转场）
仅图片模式：
outputs/20260112_143022/
├── images/
│ ├── slide-01.png
│ ├── slide-02.png
│ └── ...
├── index.html # 图片播放器
└── prompts.json # 提示词记录
视频模式：
outputs/20260112_143022_video/
├── videos/
│ ├── preview.mp4 # 首页循环预览
│ ├── transition_01_to_02.mp4
│ ├── transition_02_to_03.mp4
│ └── ...
├── video_index.html # 交互式播放器
└── full_ppt_video.mp4 # 完整视频