PPT Generator Pro - Claude Code Skill

Description

# PPT Generator Pro - Claude Code Skill ## 📋 元数据 - **Skill 名称**: ppt-generator-pro - **版本**: 2.0.0 - **描述**: 基于 AI 自动生成高质量 PPT 图片和视频，支持智能转场和交互式播放 - **作者**: 歸藏 - **标签**: ppt, presentation, video, ai, nano-banana, kling-ai, image-generation ## ✨ 功能特性 ### 核心功能 - 🤖 **智能文档分析** - 自动提取核心要点，规划 PPT 内容结构 - 🎨 **多风格支持** - 内置渐变毛玻璃、矢量插画两种专业风格 - 🖼️ **高质量图片** - 使用 Nano Banana Pro 生成 16:9 高清 PPT - 🎬 **AI 转场视频** - 可灵 AI 生成流畅的页面过渡动画 - 🎮 **交互式播放器** - 视频+图片混合播放，支持键盘导航 - 🎥 **完整视频导出** - FFmpeg 合成包含所有转场的完整 PPT 视频 ### 新功能 (v2.0) - 🔄 **首页循环预览** - 自动生成吸引眼球的循环动画 - 🎞️ **智能转场** - 自动生成页面间的过渡视频 - 🔧 **参数统一** - 自动统一所有视频分辨率和帧率 ## 📦 系统要求 ### 环境变量 **必需：** - `GEMINI_API_KEY`: Google AI API 密钥（用于生成 PPT 图片） **可选（用于视频功能）：** - `KLING_ACCESS_KEY`: 可灵 AI Access Key - `KLING_SECRET_KEY`: 可灵 AI Secret Key ### Python 依赖 ```bash pip install google-genai pillow python-dotenv ``` ### 视频功能依赖 ```bash # macOS brew install ffmpeg # Ubuntu/Debian sudo apt-get install ffmpeg ``` ## 🚀 使用方法 ### 在 Claude Code 中调用 ```bash /ppt-generator-pro ``` 或直接告诉 Claude： ``` 我想基于以下文档生成一个 5 页的 PPT，使用渐变毛玻璃风格。 [文档内容...] ``` ## 📝 Skill 执行流程 ### 阶段 1: 收集用户输入 #### 1.1 获取文档内容 **选项 A: 文档路径** ``` 用户: 基于 my-document.md 生成 PPT → 使用 Read 工具读取文件内容 ``` **选项 B: 直接文本** ``` 用户: 我想生成一个关于 AI 产品设计的 PPT 主要内容： 1. 现状分析 2. 设计原则 3. 案例研究 ``` **选项 C: 主动询问** ``` 如果用户未提供内容，询问： "请提供文档路径或直接粘贴文档内容" ``` #### 1.2 选择风格 扫描 `styles/` 目录，列出可用风格： ```python # 自动检测风格文件 styles = ['gradient-glass.md', 'vector-illustration.md'] ``` **如果有多个风格，使用 AskUserQuestion：** ```markdown 问题: 请选择 PPT 风格 选项: - 渐变毛玻璃卡片风格（科技感、商务演示） - 矢量插画风格（温暖、教育培训） ``` #### 1.3 选择页数范围 使用 AskUserQuestion 询问： ```markdown 问题: 希望生成多少页 PPT？ 选项: - 5 页（5 分钟演讲） - 5-10 页（10-15 分钟演讲） - 10-15 页（20-30 分钟演讲） - 20-25 页（45-60 分钟演讲） ``` #### 1.4 选择分辨率 ```markdown 问题: 选择图片分辨率 选项: - 2K (2752x1536) - 推荐，快速生成 - 4K (5504x3072) - 高质量，适合打印 ``` #### 1.5 是否生成视频（可选） 如果配置了可灵 AI 密钥，询问： ```markdown 问题: 是否生成转场视频？ 选项: - 仅图片（快速） - 图片 + 转场视频（完整体验） ``` ### 阶段 2: 文档分析与内容规划 #### 2.1 内容规划策略 根据页数范围，智能规划每一页内容： **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. 总结与致谢 #### 2.2 生成 slides_plan.json 创建 JSON 文件： ```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` ### 阶段 3: 生成 PPT 图片 #### 3.1 确定工作目录 **独立模式：** ```bash cd /path/to/ppt-generator ``` **Skill 模式：** ```bash cd ~/.claude/skills/ppt-generator ``` #### 3.2 执行生成命令 ```bash python generate_ppt.py \ --plan slides_plan.json \ --style styles/gradient-glass.md \ --resolution 2K ``` **或使用 uv run（推荐）：** ```bash 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 模板路径（可选） #### 3.3 监控生成进度 脚本会输出进度信息： ``` ✅ 已加载环境变量: /path/to/.env 📊 开始生成 PPT 图片... 总页数: 5 分辨率: 2K (2752x1536) 风格: 渐变毛玻璃卡片风格 🎨 生成第 1 页 (封面页)... 提示词已生成 调用 Nano Banana Pro API... ✅ 第 1 页生成成功 (32.5 秒) 🎨 生成第 2 页 (内容页)... ✅ 第 2 页生成成功 (28.3 秒) ... ✅ 所有页面生成完成！ 📁 输出目录: outputs/20260112_143022/ ``` ### 阶段 4: 生成转场提示词（视频模式需要） **这是 Skill 的核心优势**：我（Claude Code）会分析生成的 PPT 图片，为每个转场生成精准的视频提示词。 #### 4.1 读取并分析 PPT 图片 我会读取所有生成的图片： ```python # 自动读取输出目录中的所有图片 slides = ['slide-01.png', 'slide-02.png', ...] ``` #### 4.2 分析图片差异并生成提示词 对于每对相邻图片，我会： 1. **视觉分析**：理解两张图片的布局、元素、色彩差异 2. **生成预览提示词**：为首页创建可循环的微动效描述 3. **生成转场提示词**：详细描述如何从起始帧过渡到结束帧 **示例输出：** ```json { "preview": { "slide_path": "outputs/.../slide-01.png", "prompt": "画面保持封面的静态构图，中心的3D玻璃环缓慢旋转..." }, "transitions": [ { "from_slide": 1, "to_slide": 2, "prompt": "镜头从封面开始，玻璃环逐渐解构，分裂成透明碎片..." } ] } ``` #### 4.3 保存提示词文件 我会将生成的提示词保存到： ``` outputs/TIMESTAMP/transition_prompts.json ``` **关键优势：** - ✅ 不需要单独的 Claude API 密钥 - ✅ 提示词针对实际图片内容定制 - ✅ 考虑文字稳定性，避免视频模型弄模糊文字 - ✅ 符合渐变毛玻璃风格的视觉语言 ### 阶段 5: 生成转场视频（可选） 如果用户选择生成视频，使用阶段 4 生成的提示词文件： ```bash 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`） ### 阶段 6: 返回结果 #### 6.1 仅图片模式 ``` ✅ PPT 生成成功！ 📁 输出目录: outputs/20260112_143022/ 🖼️ PPT 图片: outputs/20260112_143022/images/ 🎬 播放网页: outputs/20260112_143022/index.html 打开播放网页: open outputs/20260112_143022/index.html 播放器快捷键: - ← → 键: 切换页面 - ↑ Home: 回到首页 - ↓ End: 跳到末页 - 空格: 暂停/继续自动播放 - ESC: 全屏切换 - H: 隐藏/显示控件 ``` #### 5.2 视频模式 ``` ✅ 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: 隐藏/显示控件 ``` ## 🔧 环境变量配置 ### .env 文件位置 Skill 会按以下顺序查找 `.env` 文件： 1. **脚本所在目录** - `./ppt-generator/.env` 2. **向上查找项目根目录** - 直到找到包含 `.git` 或 `.env` 的目录 3. **Claude Skill 标准位置** - `~/.claude/skills/ppt-generator/.env` 4. **系统环境变量** - 如果以上都未找到 ### .env 文件示例 ```bash # 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 ``` ## 🎨 风格系统 ### 已内置风格 #### 1. 渐变毛玻璃卡片风格 (`gradient-glass.md`) **视觉特点：** - Apple Keynote 极简主义 - 玻璃拟态效果 - 霓虹紫/电光蓝/珊瑚橙渐变 - 3D 玻璃物体 + 电影级光照 **适用场景：** - 科技产品发布 - 商务演示 - 数据报告 - 企业品牌展示 #### 2. 矢量插画风格 (`vector-illustration.md`) **视觉特点：** - 扁平化矢量设计 - 统一黑色轮廓线 - 复古柔和配色 - 几何化简化 **适用场景：** - 教育培训 - 创意提案 - 儿童相关 - 温暖品牌故事 ### 添加自定义风格 1. 在 `styles/` 目录创建新的 `.md` 文件 2. 按照现有风格格式编写 3. Skill 会自动识别并提供选择 ## 📊 技术细节 ### API 配置 **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 # 完整视频 ``` ## 🎯 最佳实践 1. **文档质量**：输入文档内容越清晰结构化，生成的 PPT 质量越高 2. **页数选择**：根据文档长度和演示场景合理选择页数 3. **分辨率选择**：日常使用推荐 2K，重要展示场合可选 4K 4. **视频功能**：首次使用建议先尝试仅图片模式，熟悉后再使用视频功能 5. **提示词调整**：查看 `prompts.json` 了解生成逻辑，可手动调整后重新生成 ## 📝 使用示例 ### 示例 1: 快速生成 **用户输入：** ``` 我需要基于这份会议纪要生成一个 5 页的 PPT，使用矢量插画风格。 会议主题：Q1 产品路线图规划 参与人：产品团队 讨论内容： 1. 用户反馈汇总 2. 新功能优先级 3. 技术可行性评估 4. Q1 里程碑 5. 下一步行动项 ``` **Skill 执行：** 1. 收集输入（已提供内容） 2. 确认风格（矢量插画） 3. 确认页数（5 页） 4. 确认分辨率（询问用户） 5. 生成 slides_plan.json 6. 执行生成命令 7. 返回结果 ### 示例 2: 完整流程 **用户输入：** ``` 基于 AI-Product-Design.md 文档，生成一个 15 页的 PPT，使用渐变毛玻璃风格，需要转场视频。 ``` **Skill 执行：** 1. 读取文档内容 2. 确认风格（渐变毛玻璃） 3. 确认页数（15 页） 4. 确认分辨率（询问用户） 5. 确认生成视频（是） 6. 分析文档，规划 15 页内容 7. 生成 slides_plan.json 8. 生成 PPT 图片 9. 生成转场视频 10. 合成完整视频 11. 返回所有结果 ## 🔄 更新日志 ### v2.0.0 (2026-01-12) - 🎬 **新增视频功能** - 可灵 AI 转场视频生成 - 交互式视频播放器 - FFmpeg 完整视频合成 - 首页循环预览视频 - 🔧 **优化视频合成** - 自动统一分辨率和帧率 - 修复视频拼接兼容性问题 - 静态图片展示时间改为 2 秒 - 🔑 **改进环境变量** - 智能查找 .env 文件 - 支持多种部署模式 - 自动向上查找项目根目录 - 📚 **文档完善** - 重命名为 SKILL.md（符合官方规范） - 更新所有路径和命令 - 添加视频功能使用指南 ### v1.0.0 (2026-01-09) - ✨ 首次发布 - 🎨 内置 2 种专业风格 - 🖼️ 支持 2K/4K 分辨率 - 🎬 HTML5 图片播放器 - 📊 智能文档分析 ## 📄 许可证 MIT License ## 📞 技术支持 - 项目架构：参见 `ARCHITECTURE.md` - API 管理：参见 `API_MANAGEMENT.md` - 环境配置：参见 `ENV_SETUP.md` - 安全说明：参见 `SECURITY.md` - 完整文档：参见 `README.md`

Security Status