/ppt
一键生成专业 PPT 的编排器
🚀 首次使用初始化(必读)
在生成 PPT 之前,必须先确认用户的账号和工具可用性。
Step 1: 确认账号能力
必须使用 AskUserQuestion 工具询问用户:
问题1: 您是否有 ChatGPT Plus/Pro 账号?
- 是 → 可使用 deep-research 进行深度研究
- 否 → 仅使用 WebSearch(研究质量较低)
问题2: 您是否有 Gemini API Key(Pro 或以上)?
- 是 → 可使用 nano-banana-image 生成配图
- 否 → 跳过配图生成
Step 2: 安装依赖 Skill
根据用户确认,安装对应的 skill:
如果有 ChatGPT Plus,安装 deep-research
相对路径: ../../../openai-deep-research (同一个 git 库)
SKILL_BASE="/home/david/prj/origin-task"
deep-research skill
if [ ! -d "$SKILL_BASE/openai-deep-research" ]; then echo "deep-research skill 已在 $SKILL_BASE/openai-deep-research" fi
nano-banana-image skill
if [ ! -d "$SKILL_BASE/nano-banana-image" ]; then echo "nano-banana-image skill 已在 $SKILL_BASE/nano-banana-image" fi
Step 3: 配置认证
ChatGPT Plus 用户:
提示: 请在浏览器中登录 ChatGPT (chat.openai.com) deep-research 将使用 Playwright 自动化访问
Gemini API 用户:
提示: 请设置环境变量 GEMINI_API_KEY export GEMINI_API_KEY="your-api-key-here"
Step 4: 记录用户配置
将确认结果保存到 .pptrc.yaml :
.pptrc.yaml (自动生成)
capabilities: deep_research: true # 有 ChatGPT Plus image_generation: true # 有 Gemini API
auth: chatgpt_logged_in: true gemini_api_key_set: true
⚠️ 初始化检查清单
每次执行 /ppt 时,检查:
是否存在 .pptrc.yaml ?
-
否 → 执行初始化流程
-
是 → 读取已保存的配置
deep-research 是否可用?
-
检查: python -c "from research.deep_research import DeepResearch"
nano-banana-image 是否可用?
- 检查: skill 目录是否存在 + GEMINI_API_KEY 是否设置
如果任何检查失败,提示用户重新配置!
🔄 强制反思协议(P1 必读)
每个阶段完成后,必须输出反思报告,检查是否有遗漏或问题。
为什么需要反思?
AI 容易"声称完成"但实际跳过步骤。强制反思机制:
-
验证 artifact 文件是否真的存在
-
检查内容质量(非空、有来源)
-
发现遗漏并立即修正
反思输出格式
每个 Stage 完成后,必须输出:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 STAGE REFLECTION: [STAGE_NAME] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ [检查项1]: 通过 ✅ [检查项2]: 通过 ⚠️ [检查项3]: 警告 - [原因] ❌ [检查项4]: 失败 - [原因]
⚠️ Warnings:
- [警告1]
- [警告2]
📌 Next: [下一步操作] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
各阶段检查清单
Stage 0: Init 反思
检查项:
- .pptrc.yaml 已创建
- deep_research 配置正确
- image_generation 配置正确
Stage 1: Skeleton 反思
检查项:
- skeleton.yaml 已创建
- research_tasks 已定义(数量 > 0)
- structure 已定义
Stage 2: Research 反思
检查项:
- research_results/ 目录已创建
- 所有 required 任务都有对应的 .md 文件
- 每个结果文件内容 > 100 字符
- 每个结果文件包含来源引用
Stage 2.5: Images 反思(如果启用)
检查项:
- images/ 目录已创建
- 封面图已生成
- 章节图已生成(可选)
Stage 3: Enrich 反思
检查项:
- slides/ 目录已创建
- 所有幻灯片文件已生成
- @RESEARCH 标记内容已填充(非占位符)
Stage 4: Render 反思
检查项:
- PPTX 文件已生成
- 文件大小合理(> 10KB)
反思后行动
如果有 ❌ 错误: → 停止,修复问题,重新执行当前阶段
如果有 ⚠️ 警告: → 输出警告,询问用户是否继续
如果全部 ✅ 通过: → 继续下一阶段
🎨 图片生成协议(P1)
当 image_generation: true 时,在研究完成后生成装饰图片。
触发条件
.pptrc.yaml 中
capabilities: image_generation: true # ← 此项为 true 时触发
执行时机
Stage 2: Research 完成 ↓ Stage 2.5: Images 生成 ← 在此执行 ↓ Stage 3: Enrich
图片生成任务
根据 skeleton.yaml 中的 image_position 字段:
位置 用途 Aspect Ratio
cover
封面主视觉 16:9
section
章节标题背景 16:9
ending
结尾感谢图 16:9
AI 执行协议
当看到 image_generation: true 时:
Step 1: 显式输出图片任务
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎨 IMAGE GENERATION TASK ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Skill: nano-banana-image Images to generate:
- cover: 封面主视觉
- section-01: 章节1背景
- ending: 结尾感谢图
Status: ⏳ Generating... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: 调用图片生成
使用 Task 工具调用 nano-banana-image
Task( subagent_type="general-purpose", prompt=""" 使用 nano-banana-image skill 生成 PPT 装饰图片:
1. 封面图:
描述: [PPT标题相关的视觉描述]
输出: images/cover.png
比例: 16:9
2. 结尾图:
描述: Thank you, professional closing
输出: images/ending.png
比例: 16:9
要求: 使用 nano-banana-pro 色彩风格(深色背景、金色/青色点缀)
""",
description="Generate PPT images"
)
Step 3: 保存到 images/ 目录
output/project-name/ ├── images/ # 🆕 图片目录 │ ├── cover.png │ ├── section-01.png │ └── ending.png ├── research_results/ ├── slides/ └── skeleton.yaml
Step 4: 在 slide-md 中引用
slide: id: "01-01" type: cover layout: title-only image: images/cover.png # 🆕 引用图片
PPT 标题
图片生成失败处理
如果图片生成失败: → 输出警告,但继续后续流程 → 幻灯片将没有装饰图,但内容不受影响
📋 Research Directive 语法(必读)
这是 PPT 生成的核心机制:显式声明研究任务,强制执行获取结果。
语法定义
- skeleton.yaml 中声明研究任务
在 skeleton.yaml 顶层或章节内声明
research_tasks:
- id: "r01" # 唯一标识符
query: | # 研究提示词(详细描述)
Tesla TSLA stock performance in 2025:
- Opening and closing prices
- Year-over-year change percentage
- Major events affecting stock price
- Analyst ratings summary skill: "deep-research" # 使用的 skill required: true # true=必须执行, false=可选 output_format: | # 期望的输出格式
2025年股价表现
- 年初价格: $XXX
- 年末价格: $XXX
- 涨跌幅: +/-XX%
关键事件
- [事件1]
- [事件2]
- slide-md 中标记填充位置
slide: id: "02-02" layout: two-column
2025年股价回顾
::: left <!-- @RESEARCH: r01 --> 此区域将由研究结果 r01 填充 <!-- @/RESEARCH --> :::
::: right <!-- @RESEARCH: r02 --> 此区域将由研究结果 r02 填充 <!-- @/RESEARCH --> :::
⚠️ AI 执行协议(强制)
当看到 research_tasks 或 <!-- @RESEARCH: --> 标记时,必须执行以下步骤:
Step 1: 显式输出研究任务
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 RESEARCH TASK [r01] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Skill: deep-research Query: Tesla TSLA stock performance in 2025:
- Opening and closing prices
- Year-over-year change percentage ...
Expected Output Format:
2025年股价表现
- 年初价格: $XXX ... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: 调用 Skill 执行研究
必须使用 Task 工具调用 deep-research
Task( subagent_type="general-purpose", prompt=""" 执行研究任务 [r01]:
使用 openai-deep-research skill 研究以下内容:
{query}
输出格式要求:
{output_format}
要求:
1. 数据必须有来源引用
2. 数据时效性:最近6个月
3. 包含具体数字,不要模糊表述
""",
description="Research: r01"
)
Step 3: 🆕 保存研究结果到文件(P0 强制)
⚠️ 关键改动: 研究结果必须持久化到文件,渲染器会验证!
目录结构
output/project-name/ ├── skeleton.yaml ├── research_results/ # 🆕 必须存在 │ ├── r01.md # 研究结果内容 │ ├── r01.meta.json # 元数据(可选但推荐) │ ├── r02.md │ └── ... └── slides/ └── *.slide.md
保存 research_results/{task_id}.md:
Research Result: r01
Generated: 2026-01-12T10:30:00Z Skill: deep-research
2025年股价表现
- 年初价格: $248.42
- 年末价格: $445.03
- 涨跌幅: +79.1%
关键事件
- Q1: FSD V12 发布,股价上涨 15%
- Q3: Robotaxi 发布会,股价创新高
- Q4: 马斯克政治参与引发波动
来源: Yahoo Finance, Reuters 研究时间: 2026-01-12
保存 research_results/{task_id}.meta.json (可选):
{ "task_id": "r01", "skill": "deep-research", "query_hash": "abc123...", "executed_at": "2026-01-12T10:30:00Z", "duration_seconds": 45, "source_count": 5, "content_length": 1234 }
Step 4: 填充结果到 slide-md
从 research_results/{task_id}.md 读取内容填充:
<!-- @RESEARCH: r01 -->
2025年股价表现
- 年初价格: $248.42
- 年末价格: $445.03
- 涨跌幅: +79.1%
关键事件
- Q1: FSD V12 发布,股价上涨 15%
- Q3: Robotaxi 发布会,股价创新高
- Q4: 马斯克政治参与引发波动
来源: Yahoo Finance, Reuters <!-- @/RESEARCH -->
🚫 渲染阻断机制(P0)
render.js 会在渲染前验证 research_results/ 目录!
如果 skeleton.yaml 定义了 research_tasks: 但 research_results/ 目录不存在 或 必需任务 (required: true) 没有对应的 .md 文件
则渲染器拒绝执行并输出:
╔════════════════════════════════════════════════════════════╗ ║ ARTIFACT VALIDATION FAILED ║ ╚════════════════════════════════════════════════════════════╝
🚫 RENDER BLOCKED: research_results/ 目录不存在
skeleton.yaml 定义了 5 个必需研究任务:
- [r01] Tesla TSLA stock performance in 2025...
- [r02] Tesla 2026 bullish catalysts... ...
解决方法:
- 使用 /ppt-enrich 执行研究任务
- 确保每个任务都调用 deep-research skill
- 将结果保存为 research_results/{task_id}.md
绕过方法(不推荐):
node render.js ./slides/ --skip-artifact-check
研究任务类型
类型 适用场景 示例 query
market_data
股价、财务数据 "TSLA stock price 2025"
news_events
新闻事件分析 "Tesla major news 2025"
case_study
案例研究 "AI manufacturing cases China 2025"
statistics
统计数据 "Global EV market share 2025"
comparison
对比分析 "Tesla vs BYD sales comparison"
forecast
预测分析 "Tesla stock price forecast 2026"
工具优先级
优先级 工具 使用条件
🥇 1st deep-research
required: true 或 capabilities.deep_research=true
🥈 2nd WebSearch
仅当 deep-research 不可用时的 fallback
❌ 禁止行为
❌ 看到 research_tasks 却不执行研究 ❌ 使用 WebSearch 代替 deep-research(当可用时) ❌ 不显式输出研究任务就直接填充内容 ❌ 填充的内容没有来源引用 ❌ 使用过时数据(超过6个月)
✅ 正确流程示例
- 读取 skeleton.yaml
- 发现 research_tasks: [r01, r02, r03]
- 输出: "🔍 RESEARCH TASK [r01]..."
- 调用: Task(subagent_type="general-purpose", prompt="使用 deep-research...")
- 等待结果
- 输出: "🔍 RESEARCH TASK [r02]..."
- 调用: Task(...)
- ...
- 生成 slide-md,填充 <!-- @RESEARCH: rXX --> 标记
概述
/ppt 是 PPT 生成的主入口命令,它编排 outline → enrich → render 三阶段流程,将用户的原始需求转化为专业的 PPTX 文件。
🎨 设计工具箱 (Design Toolkit)
重要: 生成 PPT 时,请充分利用以下丰富的设计工具,确保输出美观大方、专业精致。
可用布局类型
布局 类型 适用场景 效果
title-only
全屏标题 封面、章节页、结尾 视觉冲击力强
bullets
要点列表 通用内容、3-5 个要点 清晰易读
two-column
双列对比 对比内容、左右分列 结构对称
three-cards
三列卡片 案例展示、特性对比 并列展示
table
表格 数据密集、多维比较 信息整齐
quote
引用 名人金句、重点强调 突出重点
chart
图表 流程、时间线、层级 可视化强
可用图表模板
使用 ::: chart 块或 ```mermaid 代码块:
模板 语法示例 适用内容
流程图 template: process-flow
步骤、阶段、流程
对比图 template: comparison
传统 vs 现代、优劣势
时间线 template: timeline
历史、规划、路线图
金字塔 template: pyramid
层级、架构、分类
自定义
代码块
复杂自定义图表
图表语法示例:
::: chart
template: process-flow
title: AI实施三阶段
steps:
- 快赢期 | 0-6月
- 价值放大 | 6-18月
- 全面转型 | 18月+
:::
装饰图片位置
使用 nano-banana-image 生成同色系装饰图:
位置
适用页面
效果
cover
封面页
全屏主视觉,增强冲击力
section
章节标题页
背景装饰,突出主题
side
内容页
侧边装饰,增加美感
ending
结尾页
感谢装饰,温馨收尾
设计决策原则
- 数据 → 图表: 有数字就可视化,不堆砌数字
- 对比 → 双列/图表: 对比内容必须清晰区分
- 流程 → 流程图: 步骤内容用流程图展示
- 案例 → 卡片: 多案例并列用卡片布局
- 引用 → Quote: 金句单独突出展示
- 重要页 → 配图: 封面、章节页配装饰图
主题选择
主题
风格
适用场景
corporate-light
浅色正式
企业汇报、正式场合
nano-banana-pro
深色科技
创意提案、科技演讲
架构
/ppt(编排器)
│
┌────────────────┼────────────────┐
▼ ▼ ▼
/ppt-outline /ppt-enrich /ppt-render
(骨架生成) (内容填充) (PPTX渲染)
│ │ │
▼ ▼ ▼
skeleton.yaml slide-md/*.md output.pptx
用法
快速开始
/ppt # 交互式生成
/ppt ./docs/ # 从文档目录生成
/ppt "做一个AI培训的PPT,30分钟" # 从自然语言生成
完整参数
/ppt [input] [options]
Arguments:
[input] 输入源(目录/文件/描述)
Options:
-o, --output <path> 输出 PPTX 路径
-t, --theme <name> 主题 (corporate-light | nano-banana-pro)
-d, --duration <min> 目标时长(分钟)
--no-research 跳过研究步骤
--step <stage> 只执行到指定阶段 (outline | enrich | render)
--resume <state> 从断点恢复
-v, --verbose 详细输出
工作模式
模式 1: 交互式(默认)
/ppt
📋 PPT 生成向导
━━━━━━━━━━━━━━━
检测到上下文:
- docs/ 目录: 7 个文档, 35,604 字
- 已有骨架: skeleton.yaml
请选择操作:
1. 从现有文档生成 PPT
2. 从骨架继续(跳过 outline)
3. 重新开始
选择 [1]: _
模式 2: 批处理
# 从文档目录一键生成
/ppt ./docs/ -o presentation.pptx
# 指定主题和时长
/ppt ./docs/ --theme nano-banana-pro -d 60 -o dark-theme.pptx
模式 3: 自然语言
/ppt "给企业高管做一个AI转型的培训,90分钟,需要案例"
# 系统会:
# 1. 解析意图 → 识别为 training, executives, 90min
# 2. 生成骨架 → skeleton.yaml
# 3. 执行研究 → 补充案例和数据
# 4. 生成内容 → slide-md 文件
# 5. 渲染输出 → presentation.pptx
流程阶段
Stage 1: Outline(骨架生成)
Input: 上下文 / 自然语言描述
Output: skeleton.yaml
Tool: /ppt-outline
生成结构化骨架,定义章节、时长、研究需求。
Stage 2: Enrich(内容填充)
Input: skeleton.yaml + 上下文
Output: slides/*.slide.md
Tool: /ppt-enrich
检测内容空缺,执行研究,生成每页幻灯片的 Markdown。
Stage 3: Render(渲染输出)
Input: slides/*.slide.md
Output: presentation.pptx
Tool: /ppt-render
将 slide-md 文件渲染为最终 PPTX。
断点续传
支持从任意阶段恢复:
# 保存状态
/ppt ./docs/ --step enrich
# → 生成 .ppt-state.json
# 从断点恢复
/ppt --resume .ppt-state.json
# → 从 render 阶段继续
状态文件结构:
{
"stage": "enrich",
"skeleton_path": "skeleton.yaml",
"slides_dir": "slides/",
"options": {...},
"timestamp": "2026-01-12T10:00:00Z"
}
错误恢复
错误类型
处理策略
骨架验证失败
提示修复,不继续
研究超时
跳过该项,继续生成
渲染失败
保存 slide-md,提示手动渲染
输出
默认输出结构
project/
├── skeleton.yaml # 骨架文件
├── slides/ # slide-md 文件
│ ├── 00-01-cover.slide.md
│ ├── 01-01-section.slide.md
│ └── ...
├── presentation.pptx # 最终 PPT
└── .ppt-state.json # 状态文件(可选)
清理选项
/ppt ./docs/ --clean # 生成后删除中间文件
配置
项目配置 (.pptrc.yaml)
# .pptrc.yaml
defaults:
theme: corporate-light
duration: 30
audience: professionals
research:
mode: browser # browser | api | mock
cache: true
timeout: 300 # 秒
output:
dir: ./output
clean_intermediate: false
环境变量
变量
说明
OPENAI_API_KEY
OpenAI API 密钥(api 研究模式)
PPT_THEME
默认主题
PPT_OUTPUT_DIR
默认输出目录
文件结构
.claude/skills/ppt/
├── SKILL.md # 本文档
├── scripts/
│ ├── orchestrator.py # 主编排脚本
│ ├── intent_parser.py # 意图解析器
│ └── state_manager.py # 状态管理器
└── templates/
└── .pptrc.yaml # 配置模板
依赖的 Skills
Skill
用途
/ppt-outline
生成骨架
/ppt-enrich
内容填充
/ppt-render
PPTX 渲染
版本历史
版本
日期
变更
1.0.0
2026-01-12
初版
1.1.0
2026-01-13
P1: 强制反思协议、图片生成协议
1.2.0
2026-01-13
P2: Intent Engine 集成、布局预决策
🧠 跨会话追踪协议(P2)
使用 Intent Engine 记录 PPT 生成的每个阶段,支持跨会话恢复和决策审计。
为什么需要跨会话追踪?
- 断点恢复: 会话中断后,新会话能知道上次进度
- 决策审计: 记录为什么选择某个布局/主题
- 质量追踪: 里程碑记录便于复盘
集成方式
from ie_integration import IETracker
tracker = IETracker("ai-trends-brief", Path("./output"))
# 创建任务(会话开始时)
tracker.create_ppt_task("AI未来趋势简报", 30, "nano-banana-pro")
# 每个阶段完成后记录里程碑
tracker.log_milestone("skeleton", "Generated 5 sections, 12 slides")
tracker.log_milestone("research", "Completed 3 research tasks with 15 sources")
tracker.log_milestone("layout", "Applied layout decisions: 3 cards, 2 bullets")
tracker.log_milestone("render", "Generated presentation.pptx (2.3MB)")
# 记录重要决策
tracker.log_decision(
topic="Section 02 Layout",
options=["bullets", "three-cards", "chart"],
chosen="three-cards",
rationale="Content has 3 AI trends, perfect for card layout"
)
# 记录阻塞
tracker.log_blocker("images", "Gemini API rate limited", "Wait 60s and retry")
AI 执行协议
每个阶段完成后,必须输出并记录:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 IE MILESTONE: [STAGE_NAME]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: ai-trends-brief
Stage: skeleton
Summary: Generated skeleton.yaml with 2 sections
Artifacts:
✅ skeleton.yaml (1.2KB)
✅ research_tasks: 1
Logged to Intent Engine: ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
会话恢复
新会话开始时:
# 查看当前任务状态
ie status
# 搜索未完成任务
ie search "PPT doing"
📐 布局预决策协议(P2)
在生成 slide-md 之前,必须先运行 LayoutAdvisor 分析内容并决定布局。
为什么需要预决策?
- 避免单调布局: 不是所有内容都用 bullets
- 智能推荐: 根据内容特征自动推荐最佳布局
- 设计一致性: 确保设计决策有据可查
工作流程
skeleton.yaml
│
▼
┌─────────────────┐
│ LayoutAdvisor │ ← 分析内容特征
│ (预决策) │
└────────┬────────┘
│
▼
skeleton.yaml (enriched)
with _layout_decision
│
▼
┌─────────────────┐
│ SlideMDWriter │ ← 使用决策生成
│ (内容生成) │
└────────┬────────┘
│
▼
slides/*.slide.md
布局决策字段
预决策后,skeleton.yaml 中每个 slide 会添加:
structure:
- id: "02-trends"
title: "2026三大趋势"
slides:
- id: "02-01"
type: content
layout: three-cards
_layout_decision: # 🆕 预决策结果
layout: three-cards
confidence: 0.9
chart_type: null
image_position: icon
design_hints:
- 每个卡片展示一个趋势
- 突出关键指标
rationale: "内容有3个并列趋势,适合卡片布局"
AI 执行协议
Enrich 阶段必须先执行预决策:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📐 LAYOUT PRE-DECISION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Analyzing 5 sections...
[02-01] 2026三大趋势
Layout: three-cards (confidence: 90%)
Rationale: 内容有3个并列趋势,适合卡片布局
[03-01] 实施路线图
Layout: chart (confidence: 85%)
Chart: timeline
Rationale: 时间相关内容适合时间线图表
Layout Distribution:
three-cards: 2
bullets: 2
chart: 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
布局推荐规则
内容特征
推荐布局
置信度
3个并列项
three-cards
90%
对比内容
two-column / comparison chart
80-85%
步骤/流程
chart (process-flow)
90%
时间线
chart (timeline)
90%
层级结构
chart (pyramid)
85%
引用/金句
quote
90%
数据密集
table
75%
默认
bullets
60%
调用方式
from layout_advisor import LayoutAdvisor
advisor = LayoutAdvisor(verbose=True)
# 为单个章节推荐布局
decision = advisor.recommend_layout(section)
print(f"推荐: {decision.layout.value}, 置信度: {decision.confidence}")
# 批量应用到 skeleton
enriched_skeleton = advisor.apply_decisions_to_skeleton(skeleton)
# 生成设计报告
report = advisor.generate_design_report(skeleton)
print(report)
快速示例
# 最简单的用法
/ppt ./docs/ -o my-presentation.pptx
# 完整流程
/ppt ./docs/ \
--theme corporate-light \
--duration 60 \
-o presentation.pptx \
-v