Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs: 强制 Executor 逻辑构建阶段生成演讲备注

hugohe3a932226fe031
diff --git a/AGENTS.md b/AGENTS.md
index 94af0b49..40ccaafc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -84,12 +84,18 @@ PPT Master 是一个 AI 驱动的多格式 SVG 内容生成系统,通过多角
▼ ▼
┌──────────────────────────────────────────────────┐
│ Executor (General/Consultant/Consultant_Top) │
-│ • 逐页生成 SVG(可基于模板) │
-│ • 保存到 svg_output/ │
+│ │
+│ 【视觉构建阶段】 │
+│ • 逐页生成 SVG(可基于模板)→ svg_output/ │
+│ │
+│ 【逻辑构建阶段】← ← ← ← 必须 │
+│ • 生成完整讲稿 → notes/total.md │
+│ │
└──────────────────────────────────────────────────┘
│
▼
【后处理】← ← ← ← ← 自动执行
+ python3 tools/total_md_split.py # 拆分讲稿
python3 tools/finalize_svg.py
│
▼
@@ -192,22 +198,28 @@ Optimizer_CRAP (可选优化)
```markdown
## ✅ Executor 阶段完成
+### 视觉构建阶段
- [x] 已阅读对应的 Executor 角色定义
- [x] 所有 SVG 页面已生成到 `svg_output/`
- [x] 已通过质量检查
-- [ ] **下一步**: 自动执行后处理与导出
+
+### 逻辑构建阶段(必须)
+- [x] 已生成完整演讲备注文稿 `notes/total.md`
### 自动执行后处理
-# 1. 后处理(修正图片路径、优化代码)
+# 1. 拆分讲稿(将 total.md 拆分为各页独立文件)
+python3 tools/total_md_split.py <项目路径>
+# 2. 后处理(修正图片路径、嵌入图标)
python3 tools/finalize_svg.py <项目路径>
-# 2. 导出为 PPTX(默认嵌入演讲备注)
-
+# 3. 导出为 PPTX(默认嵌入演讲备注)
python3 tools/svg_to_pptx.py <项目路径> -s final
```
+> ⚠️ **强制要求**:演讲备注是 Executor 阶段的必须产出,SVG 页面生成完毕后必须进入「逻辑构建阶段」生成 `notes/total.md`,然后再进行后处理。
+
---
## 源内容自动处理(强制触发)
@@ -535,16 +547,20 @@ project/
- 图标使用方式需在八项确认中确认(Emoji / AI 生成 / 内置库 / 自定义)
- 图片使用方式需在八项确认中确认(不使用 / 用户提供 / AI 生成 / 占位符)
- **图片生成流程**:如果图片方式**包含**「C) AI 生成」(如 C、B+C、C+D),**必须**先切换到 Image_Generator 角色,阅读角色定义,完成图片生成后再进入 Executor 阶段
+- **Executor 两阶段**:SVG 页面生成(视觉构建)完成后,**必须**进入逻辑构建阶段生成演讲备注 `notes/total.md`,**禁止**跳过此步骤直接进入后处理
### 后处理提示
-SVG 生成完成后,**直接运行以下两条命令**,无需任何参数:
+**演讲备注和 SVG 都生成完成后**,运行以下命令:
```bash
-# 1. 后处理(直接运行)
+# 1. 拆分讲稿(将 total.md 拆分为各页独立文件)
+python3 tools/total_md_split.py <项目路径>
+
+# 2. 后处理(修正图片路径、嵌入图标)
python3 tools/finalize_svg.py <项目路径>
-# 2. 导出 PPTX
+# 3. 导出 PPTX
python3 tools/svg_to_pptx.py <项目路径> -s final
```
diff --git a/README.md b/README.md
index 4d308e49..f1cdf294 100644
--- a/README.md
+++ b/README.md
@@ -142,14 +142,14 @@ AI(Strategist 角色):好的,在开始之前我需要完成八项确认.
[Image_Generator] 图片生成师(当选择 AI 生成时)
↓
[Executor] 执行师 - 分阶段生成
- ├── 视觉构建阶段:连续生成所有 SVG 页面
- └── 逻辑构建阶段:批量生成演讲备注 → notes/
+ ├── 视觉构建阶段:连续生成所有 SVG 页面 → svg_output/
+ └── 逻辑构建阶段:生成完整讲稿 → notes/total.md
↓
[Optimizer_CRAP] 优化师(可选)
↓
-[后处理] → finalize_svg.py → svg_to_pptx.py(自动嵌入讲稿)
+[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py
↓
-输出: SVG + PPTX
+输出: SVG + PPTX(自动嵌入讲稿)
```
> 📖 详细工作流程请参阅 [工作流教程](./docs/workflow_tutorial.md) 和 [角色定义](./roles/README.md)
diff --git a/README_EN.md b/README_EN.md
index 0462de4c..6ce3ee60 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -142,14 +142,14 @@ User Input (PDF/URL/Markdown)
[Image_Generator] (When AI generation is selected)
↓
[Executor] - Two-Phase Generation
- ├── Visual Construction Phase: Generate all SVG pages consecutively
- └── Logic Construction Phase: Batch generate speaker notes → notes/
+ ├── Visual Construction Phase: Generate all SVG pages → svg_output/
+ └── Logic Construction Phase: Generate complete script → notes/total.md
↓
[Optimizer_CRAP] (Optional)
↓
-[Post-processing] → finalize_svg.py → svg_to_pptx.py (auto-embeds notes)
+[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py
↓
-Output: SVG + PPTX
+Output: SVG + PPTX (auto-embeds notes)
```
> 📖 For detailed workflow, see [Workflow Tutorial](./docs/workflow_tutorial.md) and [Role Definitions](./roles/README.md)
diff --git a/docs/quick_reference.md b/docs/quick_reference.md
index 89eb0f5b..dad6d9c4 100644
--- a/docs/quick_reference.md
+++ b/docs/quick_reference.md
@@ -55,14 +55,19 @@
💡 **提示**: 图片生成是串行环节,必须完成后才能进入 Executor 阶段
-### ✅ 使用 Executor
+### ✅ 使用 Executor(两阶段)
+**视觉构建阶段**:
- [ ] 明确告知需要生成哪一页
- [ ] 提供设计规范引用
- [ ] 检查生成的 SVG 效果
- [ ] 如需修改,提供具体反馈
- [ ] 保存 SVG 到项目的 svg_output 文件夹
+**逻辑构建阶段**(必须):
+- [ ] 所有 SVG 页面完成后,生成完整演讲备注文稿 `notes/total.md`
+- [ ] 确保讲稿包含所有页面的过渡语和控场标记
+
### ✅ 使用 Optimizer(可选)
- [ ] 仅在质量不足时使用
@@ -77,19 +82,21 @@
**后处理和导出步骤由 AI 自动执行:**
+- [ ] AI 自动拆分讲稿:`python3 tools/total_md_split.py <项目路径>`
+ - 将 `notes/total.md` 拆分为各页独立文件
- [ ] AI 自动运行后处理:`python3 tools/finalize_svg.py <项目路径>`
- 修正图片路径
- 优化代码结构
- 生成最终版本到 `svg_final/`
- [ ] AI 自动导出 PPTX:`python3 tools/svg_to_pptx.py <项目路径> -s final`
- 生成可用的 PowerPoint 文件
- - 自动嵌入演讲备注(如有)
+ - 自动嵌入演讲备注
- [ ] 在 PowerPoint 中预览最终效果
- [ ] 检查所有页面的一致性
- [ ] 添加项目 README 文档(可选)
- [ ] 备份重要文件(可选)
-💡 **提示**: 后处理和导出无需手动执行,AI 会在生成完所有 SVG 后自动完成
+💡 **提示**: 后处理和导出无需手动执行,AI 会在完成演讲备注后自动完成
## 🎨 设计风格选择指南
@@ -428,10 +435,17 @@ yh_02_kpi_dashboard.svg
## 🔧 后处理工具
+### 拆分讲稿
+
+```bash
+# 将 notes/total.md 拆分为各页独立文件
+python3 tools/total_md_split.py <项目路径>
+```
+
### 最终化处理
```bash
-# 直接运行,无需参数
+# 修正图片路径、嵌入图标
python3 tools/finalize_svg.py <项目路径>
```
diff --git a/docs/workflow_tutorial.md b/docs/workflow_tutorial.md
index ec6ada84..b6c40479 100644
--- a/docs/workflow_tutorial.md
+++ b/docs/workflow_tutorial.md
@@ -142,6 +142,7 @@
│
▼
┌────────────────────────┐
+ │ 【视觉构建阶段】 │
│ SVG 文件 (逐页生成) │
│ 保存到 svg_output/ │
│ 01_封面.svg │
@@ -151,10 +152,19 @@
│
▼
┌────────────────────────┐
+ │ 【逻辑构建阶段】(必须) │
+ │ 生成完整演讲备注文稿 │
+ │ → notes/total.md │
+ └────────────┬───────────┘
+ │
+ ▼
+ ┌────────────────────────┐
│ 后处理 (自动执行) │
- │ finalize_svg.py │
- │ • 修正图片路径 │
- │ • 优化代码结构 │
+ │ 1. total_md_split.py │
+ │ • 拆分讲稿 │
+ │ 2. finalize_svg.py │
+ │ • 修正图片路径 │
+ │ • 优化代码结构 │
└────────────┬───────────┘
│
▼
@@ -240,21 +250,24 @@
### 流程要点说明
-| 阶段 | 角色 | 关键动作 | 输出物 |
-| ----------------- | --------------- | ----------------------------------------- | ---------------------- |
-| **0. 源内容转换** | (自动) | PDF/URL 转 Markdown(强制触发) | 源内容.md |
-| **1. 策略规划** | Strategist | 八项确认、内容分析、规范编制 | 《设计规范与内容大纲》 |
-| **1.5. 图片生成** | Image_Generator | 生成提示词、AI 生图、归集图片(条件触发) | images/\*.png |
-| **2. SVG 生成** | Executor | 逐页生成 SVG 代码 | slide_XX_xxx.svg |
-| **3. 视觉优化** | Optimizer | CRAP 原则优化(可选) | yh_slide_XX_xxx.svg |
+| 阶段 | 角色 | 关键动作 | 输出物 |
+| --------------------- | --------------- | ----------------------------------------- | ---------------------- |
+| **0. 源内容转换** | (自动) | PDF/URL 转 Markdown(强制触发) | 源内容.md |
+| **1. 策略规划** | Strategist | 八项确认、内容分析、规范编制 | 《设计规范与内容大纲》 |
+| **1.5. 图片生成** | Image_Generator | 生成提示词、AI 生图、归集图片(条件触发) | images/\*.png |
+| **2a. 视觉构建** | Executor | 逐页生成 SVG 代码 | svg_output/\*.svg |
+| **2b. 逻辑构建** | Executor | 生成完整演讲备注文稿(**必须**) | notes/total.md |
+| **3. 视觉优化** | Optimizer | CRAP 原则优化(可选) | yh_slide_XX_xxx.svg |
+| **4. 后处理** | (工具) | 拆分讲稿、修正路径、导出 PPTX | notes/\*.md + \*.pptx |
**注意事项**:
- 阶段 0 是**强制触发**:识别到 PDF/URL 后必须立即调用转换工具
- 阶段 1 的八项确认是**强制要求**,不可跳过
- 阶段 1.5 仅当图片方式**包含**「C) AI 生成」时触发(如 C、B+C、C+D 等组合),是**串行环节**,图片归集完成后才进入阶段 2
-- 阶段 2 根据风格选择使用不同的 Executor
+- 阶段 2a 和 2b 是 **Executor 的两阶段**,2b(逻辑构建)**不可跳过**
- 阶段 3 是可选的,仅对关键页面使用
+- 阶段 4 由工具自动执行:`total_md_split.py` → `finalize_svg.py` → `svg_to_pptx.py`
### 2. 准备你的内容
@@ -600,7 +613,10 @@ Optimizer_CRAP:
3. **后处理(推荐)**
```bash
- # 直接运行,无需参数
+ # 1. 拆分讲稿(将 notes/total.md 拆分为各页独立文件)
+ python3 tools/total_md_split.py <项目路径>
+
+ # 2. 后处理 SVG(修正路径、嵌入图标)
python3 tools/finalize_svg.py <项目路径>
```