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: 统一流程顺序、优化时机与命名规范

hugohe36c6b830600f5
diff --git a/AGENTS.md b/AGENTS.md
index 39717a21..17c21a07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,8 +27,8 @@ PPT Master 是一个 AI 驱动的多格式 SVG 内容生成系统,通过多角
源内容转换工具(如需要)
│
▼
-【创建项目文件夹】← ← ← ← ← 第一步!
- python3 tools/project_manager.py init
+【创建项目文件夹】← ← ← ← ← 获取原始材料后立即执行
+ python3 tools/project_manager.py init <名称> --format <格式>
│
▼
┌─────────────────────────────────────────┐
@@ -94,7 +94,7 @@ PPT Master 是一个 AI 驱动的多格式 SVG 内容生成系统,通过多角
└──────────────────────────────────────────────────┘
│
▼
-【后处理】← ← ← ← ← 自动执行
+【后处理】← ← ← ← ← 默认由 AI 自动执行
python3 tools/total_md_split.py # 拆分讲稿
python3 tools/finalize_svg.py
│
@@ -102,23 +102,26 @@ PPT Master 是一个 AI 驱动的多格式 SVG 内容生成系统,通过多角
SVG 文件保存到 svg_final/
│
▼
-【导出 PPTX】← ← ← ← ← 自动执行
+【导出 PPTX】← ← ← ← ← 默认由 AI 自动执行
python3 tools/svg_to_pptx.py
│
▼
-Optimizer_CRAP (可选优化)
+Optimizer_CRAP (可选优化,**在完整初版后**不满意时才考虑)
+ │
+ ▼
+如执行优化:重新运行【后处理】与【导出 PPTX】
```
> **注意**:
>
-> - **项目文件夹必须在用户输入内容后立即创建**(第一步)
+> - **项目文件夹必须在源材料转换完成后立即创建**
> - **模板选项必须在策略师开始之前确认**,策略师需要根据模板选项调整设计方案
> - 如选择 A(使用已有模板),策略师需参考模板的配色、布局、风格进行设计
> - 如选择 C(生成新模板),策略师完成大纲后再调用模板设计师
> - **策略师的「八项确认」是强制要求,无论模板选项如何都不可跳过**
> - Image_Generator 是串行环节,图片归集完成后才进入 Executor 阶段
-> - 后处理和导出步骤由 AI 自动执行
-> - Optimizer_CRAP 仅在质量不足时使用;若使用优化,需重新运行后处理与导出以保持产物一致
+> - 后处理和导出步骤以 **AI 自动执行为主**(需要时可手动运行命令)
+> - Optimizer_CRAP 仅在质量不足时使用;**须在完整初版产出后再考虑,优化后需重新运行后处理与导出**
---
@@ -206,7 +209,7 @@ Optimizer_CRAP (可选优化)
### 逻辑构建阶段(必须)
- [x] 已生成完整演讲备注文稿 `notes/total.md`
-### 自动执行后处理
+### 自动执行后处理(默认由 AI 执行,必要时可手动运行)
# 1. 拆分讲稿(将 total.md 拆分为各页独立文件)
python3 tools/total_md_split.py <项目路径>
@@ -219,6 +222,7 @@ python3 tools/svg_to_pptx.py <项目路径> -s final
```
> ⚠️ **强制要求**:演讲备注是 Executor 阶段的必须产出,SVG 页面生成完毕后必须进入「逻辑构建阶段」生成 `notes/total.md`,然后再进行后处理。
+> ⚠️ **优化提示**:仅在完整初版产出后考虑 Optimizer;若优化过,请重新运行后处理与导出以保持产物一致。
---
@@ -250,7 +254,7 @@ python3 tools/svg_to_pptx.py <项目路径> -s final
└─ Markdown → 使用 view_file 读取内容
│
▼
- 创建项目文件夹(python3 tools/project_manager.py init)
+ 创建项目文件夹(python3 tools/project_manager.py init <名称> --format <格式>)
│
▼
询问模板选项(A 使用已有 / B 不使用 / C 生成新模板)
@@ -537,7 +541,7 @@ project/
### 流程要点
-- **项目文件夹必须在用户输入内容后立即创建**(第一步)
+- **项目文件夹必须在源材料转换完成后立即创建**
- **创建项目后立即询问模板选项**(A 使用已有 / B 不使用 / C 生成新模板)— 这是流程步骤,非策略师职责
- **模板选项必须在策略师开始之前确认完成**,策略师需根据模板选项调整设计方案
- 如用户选择 A(使用已有模板),需**分别复制**:图片资源拷贝到项目 `images/` 目录,其他文件(SVG、design_spec 等)拷贝到项目 `templates/` 目录(来源:用户自备/其他项目/示例库等)
diff --git a/docs/quick_reference.md b/docs/quick_reference.md
index 4de1cf65..47e5ef34 100644
--- a/docs/quick_reference.md
+++ b/docs/quick_reference.md
@@ -72,7 +72,7 @@
### ✅ 使用 Optimizer(可选)
-- [ ] 仅在质量不足时使用
+- [ ] 仅在**完整初版产出后**仍不满意时使用
- [ ] 选择需要优化的页面
- [ ] 提供原始 SVG
- [ ] 说明优化重点(如果有)
@@ -182,7 +182,7 @@
```
请根据设计规范生成第[X]页:[页面主题]
-请将SVG保存到:projects/[项目名]_[YYYYMMDD]/svg_output/[页码]_[主题].svg
+请将SVG保存到:projects/[项目名]_[格式]_[YYYYMMDD]/svg_output/[页码]_[主题].svg
例如: projects/company_report_20251012/svg_output/01_cover.svg
```
@@ -349,16 +349,16 @@ BCG深蓝: #003F6C
### 项目文件夹
```
-projects/项目英文名_YYYYMMDD/
+projects/项目英文名_格式_YYYYMMDD/
或
-projects/项目拼音_YYYYMMDD/
+projects/项目拼音_格式_YYYYMMDD/
例如:
-projects/market_analysis_20251012/
-projects/shichang_fenxi_20251012/
+projects/market_analysis_ppt169_20251012/
+projects/shichang_fenxi_ppt169_20251012/
```
-**重要**: 必须添加日期后缀 `_YYYYMMDD`,例如 `_20251012` 表示 2025年10月12日
+**重要**: 命名格式为 `name_format_YYYYMMDD`,例如 `market_analysis_ppt169_20251012`
### 源文档
diff --git a/docs/workflow_tutorial.md b/docs/workflow_tutorial.md
index 5b80f429..767249ab 100644
--- a/docs/workflow_tutorial.md
+++ b/docs/workflow_tutorial.md
@@ -24,7 +24,7 @@
| **Executor_General** | 设计规范 | SVG 代码 | 通用风格项目 | 所有格式 |
| **Executor_Consultant** | 设计规范 | SVG 代码 | 一般咨询风格项目 | 所有格式 |
| **Executor_Consultant_Top** | 设计规范 | SVG 代码 | 顶级咨询风格项目(MBB 级) | 所有格式 |
-| **Optimizer_CRAP** | SVG 代码 | 优化后的 SVG | 需要优化时 | 所有格式 |
+| **Optimizer_CRAP** | SVG 代码 | 优化后的 SVG | 完整初版后需优化时 | 所有格式 |
### 角色协作流程图
@@ -52,7 +52,7 @@
▼
┌────────────────────────┐
│ 创建项目文件夹 (必须) │
- │ project_manager.py init│
+ │ project_manager.py init <名称> --format <格式> │
└────────────┬───────────┘
│
▼
@@ -161,7 +161,7 @@
│
▼
┌────────────────────────┐
- │ 后处理 (自动执行) │
+ │ 后处理 (默认AI自动执行) │
│ 1. total_md_split.py │
│ • 拆分讲稿 │
│ 2. finalize_svg.py │
@@ -177,21 +177,23 @@
│
▼
┌────────────────────────┐
- │ 导出 PPTX (自动执行) │
+ │ 导出 PPTX (默认AI自动执行)│
│ svg_to_pptx.py │
│ • 自动嵌入演讲备注 │
└────────────┬───────────┘
│
- ┌────────────────┴────────────────┐
- │ 是否需要优化? │
- ▼ ▼
- ┌─────────┐ ┌─────────────┐
- │ 否 │ │ 是 │
- └────┬────┘ └──────┬──────┘
+ ▼
+ ┌────────────────────────┐
+ │ Optimizer_CRAP (可选) │
+ │ 初版不满意再优化 │
+ └────────────┬───────────┘
+ │
+ ▼
+ 如执行优化:重新运行后处理与导出
│ │
│ ▼
│ ┌─────────────────────────────────────────┐
- │ │ 阶段 3: 视觉优化 (可选) │
+ │ │ 阶段 3: 视觉优化 (可选,初版后) │
│ │ ┌─────────────────────────────────┐ │
│ │ │ Optimizer_CRAP │ │
│ │ │ (CRAP 优化师) │ │
@@ -229,7 +231,7 @@
│
▼
┌────────────────────────┐
- │ 后处理(推荐) │
+ │ 后处理(默认AI自动执行)│
│ ┌──────────────────┐ │
│ │ finalize_svg.py │ │
│ │ • 嵌入图标/图片 │ │
@@ -241,7 +243,7 @@
│
▼
┌────────────────────────┐
- │ 导出 PPTX(可选) │
+ │ 导出 PPTX(默认AI自动执行)│
│ ┌──────────────────┐ │
│ │ svg_to_pptx.py │ │
│ │ → output.pptx │ │
@@ -259,7 +261,7 @@
| **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 |
+| **3. 视觉优化** | Optimizer | CRAP 原则优化(可选,初版后不满意再用) | yh_slide_XX_xxx.svg |
| **4. 后处理** | (工具) | 拆分讲稿、修正路径、导出 PPTX | notes/\*.md + \*.pptx |
**注意事项**:
@@ -268,7 +270,7 @@
- 阶段 1 的八项确认是**强制要求**,不可跳过
- 阶段 1.5 仅当图片方式**包含**「C) AI 生成」时触发(如 C、B+C、C+D 等组合),是**串行环节**,图片归集完成后才进入阶段 2
- 阶段 2a 和 2b 是 **Executor 的两阶段**,2b(逻辑构建)**不可跳过**
-- 阶段 3 是可选的,仅对关键页面使用
+- 阶段 3 是可选的,仅在**完整初版产出后**对关键页面使用;优化后需重新执行阶段 4
- 阶段 4 由工具自动执行:`total_md_split.py` → `finalize_svg.py` → `svg_to_pptx.py`
### 2. 准备你的内容
@@ -574,7 +576,7 @@ Executor: [生成三栏卡片SVG]
### 步骤 6: 优化关键页面(可选)
-对于重要的页面,可以请 Optimizer_CRAP 优化(仅在质量不足时使用;使用后需重新运行 `finalize_svg.py` 和 `svg_to_pptx.py` 以保持产物一致):
+仅在**完整初版产出后**仍不满意时,再请 Optimizer_CRAP 优化关键页面;优化后需重新运行 `finalize_svg.py` 和 `svg_to_pptx.py` 以保持产物一致:
```
你: 请使用CRAP原则优化第2页的视觉效果
@@ -614,7 +616,7 @@ Optimizer_CRAP:
- 检查一致性和质量
- **检查 PPT 兼容性**(见下方规则)
-3. **后处理(推荐)**
+3. **后处理(默认由 AI 自动执行;需要时可手动)**
```bash
# 1. 拆分讲稿(将 notes/total.md 拆分为各页独立文件)
@@ -624,7 +626,7 @@ Optimizer_CRAP:
python3 tools/finalize_svg.py <项目路径>
```
-4. **导出为 PPTX(推荐)**
+4. **导出为 PPTX(默认由 AI 自动执行)**
```bash
# 使用最终版本(推荐)
diff --git a/roles/README.md b/roles/README.md
index 42bef8be..d02b5b57 100644
--- a/roles/README.md
+++ b/roles/README.md
@@ -26,7 +26,9 @@
```
用户输入文档
↓
-[创建项目文件夹] project_manager.py init
+[源内容转换] pdf_to_md.py / web_to_md.py(如需要)
+ ↓
+[创建项目文件夹] project_manager.py init <名称> --format <格式>
↓
[模板选项] 询问用户选择(必须在策略师之前确认)
│
@@ -52,16 +54,14 @@
│ │
▼ ▼
[Executor] 执行师(根据模板选项决定是否遵循模板)
- ↓ 逐页生成SVG代码
- ↓
-[Optimizer_CRAP] 优化师 (可选)
- ↓ CRAP原则优化
+ ↓ 逐页生成SVG代码 → svg_output/
↓
-SVG 文件 (svg_output/)
- ↓
-后处理工具 (推荐,用户自行调用)
+后处理工具(默认由 AI 自动执行,必要时可手动调用)
├── finalize_svg.py → svg_final/ (嵌入图标 + 修复图片宽高比 + 嵌入图片 + 文本扁平化 + 圆角转Path)
└── svg_to_pptx.py → output.pptx (导出 PowerPoint)
+ ↓
+[Optimizer_CRAP] 优化师 (可选,仅在完整初版后不满意时使用)
+ ↓ CRAP原则优化(优化后需重新运行后处理与导出)
```
> **注意**: