/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 时，检查：

1. 是否存在 .pptrc.yaml？

   • 否 → 执行初始化流程
   • 是 → 读取已保存的配置

2. deep-research 是否可用？

   • 检查: python -c "from research.deep_research import DeepResearch"

3. nano-banana-image 是否可用？

   • 检查: skill 目录是否存在 + GEMINI_API_KEY 是否设置

如果任何检查失败，提示用户重新配置！

🔄 强制反思协议（P1 必读）

每个阶段完成后，必须输出反思报告，检查是否有遗漏或问题。

为什么需要反思？

AI 容易”声称完成”但实际跳过步骤。强制反思机制：

1. 验证 artifact 文件是否真的存在
2. 检查内容质量（非空、有来源）
3. 发现遗漏并立即修正

反思输出格式

每个 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 字段：

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 生成的核心机制：显式声明研究任务，强制执行获取结果。

语法定义

1. 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. [事件1]
      2. [事件2]

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%

### 关键事件
1. Q1: FSD V12 发布，股价上涨 15%
2. Q3: Robotaxi 发布会，股价创新高
3. 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%

### 关键事件
1. Q1: FSD V12 发布，股价上涨 15%
2. Q3: Robotaxi 发布会，股价创新高
3. 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...
  ...

解决方法：
  1. 使用 /ppt-enrich 执行研究任务
  2. 确保每个任务都调用 deep-research skill
  3. 将结果保存为 research_results/{task_id}.md

绕过方法（不推荐）：

node render.js ./slides/ --skip-artifact-check

研究任务类型

工具优先级

❌ 禁止行为

❌ 看到 research_tasks 却不执行研究
❌ 使用 WebSearch 代替 deep-research（当可用时）
❌ 不显式输出研究任务就直接填充内容
❌ 填充的内容没有来源引用
❌ 使用过时数据（超过6个月）

✅ 正确流程示例

1. 读取 skeleton.yaml
2. 发现 research_tasks: [r01, r02, r03]
3. 输出: "🔍 RESEARCH TASK [r01]..."
4. 调用: Task(subagent_type="general-purpose", prompt="使用 deep-research...")
5. 等待结果
6. 输出: "🔍 RESEARCH TASK [r02]..."
7. 调用: Task(...)
8. ...
9. 生成 slide-md，填充 <!-- @RESEARCH: rXX --> 标记

概述

/ppt 是 PPT 生成的主入口命令，它编排 outline → enrich → render 三阶段流程，将用户的原始需求转化为专业的 PPTX 文件。

🎨 设计工具箱 (Design Toolkit)

重要: 生成 PPT 时，请充分利用以下丰富的设计工具，确保输出美观大方、专业精致。

可用布局类型

可用图表模板

使用 ::: chart 块或 ```mermaid 代码块：

图表语法示例:

::: chart
template: process-flow
title: AI实施三阶段
steps:
  - 快赢期 | 0-6月
  - 价值放大 | 6-18月
  - 全面转型 | 18月+
:::

装饰图片位置

使用 nano-banana-image 生成同色系装饰图：

设计决策原则

1. 数据 → 图表: 有数字就可视化，不堆砌数字
2. 对比 → 双列/图表: 对比内容必须清晰区分
3. 流程 → 流程图: 步骤内容用流程图展示
4. 案例 → 卡片: 多案例并列用卡片布局
5. 引用 → Quote: 金句单独突出展示
6. 重要页 → 配图: 封面、章节页配装饰图

主题选择

架构

                    /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"
}

错误恢复

输出

默认输出结构

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

环境变量

文件结构

.claude/skills/ppt/
├── SKILL.md                # 本文档
├── scripts/
│   ├── orchestrator.py     # 主编排脚本
│   ├── intent_parser.py    # 意图解析器
│   └── state_manager.py    # 状态管理器
└── templates/
    └── .pptrc.yaml         # 配置模板

依赖的 Skills

版本历史

🧠 跨会话追踪协议（P2）

使用 Intent Engine 记录 PPT 生成的每个阶段，支持跨会话恢复和决策审计。

为什么需要跨会话追踪？

1. 断点恢复: 会话中断后，新会话能知道上次进度
2. 决策审计: 记录为什么选择某个布局/主题
3. 质量追踪: 里程碑记录便于复盘

集成方式

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 分析内容并决定布局。

为什么需要预决策？

1. 避免单调布局: 不是所有内容都用 bullets
2. 智能推荐: 根据内容特征自动推荐最佳布局
3. 设计一致性: 确保设计决策有据可查

工作流程

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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

布局推荐规则

调用方式

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