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(readme): 大幅精简中英文 README 并新增环境配置

hugohe39b090f38088d
diff --git a/README.md b/README.md
index af67f9fb..4d308e49 100644
--- a/README.md
+++ b/README.md
@@ -14,9 +14,51 @@
---
-## 🚀 快速使用指南
+## 🚀 快速开始
-### 推荐工具
+### 1. 配置环境
+
+#### Python 环境(必需)
+
+本项目需要 **Python 3.8+**,用于运行 PDF 转换、SVG 后处理、PPTX 导出等工具。
+
+**安装 Python:**
+
+| 平台 | 推荐安装方式 |
+|------|------------|
+| **macOS** | 使用 [Homebrew](https://brew.sh/):`brew install python` |
+| **Windows** | 从 [Python 官网](https://www.python.org/downloads/) 下载安装包 |
+| **Linux** | 使用系统包管理器:`sudo apt install python3 python3-pip`(Ubuntu/Debian) |
+
+> 💡 **验证安装**:运行 `python3 --version` 确认版本 ≥ 3.8
+
+#### Node.js 环境(可选)
+
+如需使用 `web_to_md.cjs` 工具(用于微信公众号等高防站点的网页转换),需安装 Node.js。
+
+**安装 Node.js:**
+
+| 平台 | 推荐安装方式 |
+|------|------------|
+| **macOS** | 使用 [Homebrew](https://brew.sh/):`brew install node` |
+| **Windows** | 从 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本安装包 |
+| **Linux** | 使用 [NodeSource](https://github.com/nodesource/distributions):`curl -fsSL https://deb.nodesource.com/setup_lts.x \| sudo -E bash - && sudo apt-get install -y nodejs` |
+
+> 💡 **验证安装**:运行 `node --version` 确认版本 ≥ 18
+
+### 2. 克隆仓库并安装依赖
+
+```bash
+git clone https://github.com/hugohe3/ppt-master.git
+cd ppt-master
+pip install -r requirements.txt
+```
+
+> 如遇权限问题,可使用 `pip install --user -r requirements.txt` 或在虚拟环境中安装。
+
+### 3. 打开 AI 编辑器
+
+推荐使用以下 AI 编辑器:
| 工具 | 推荐度 | 说明 |
| --------------------------------------------------- | :----: | ----------------------------------------------------------------------------- |
@@ -25,23 +67,9 @@
| [VS Code + Copilot](https://code.visualstudio.com/) | ⭐⭐ | 微软官方方案 |
| [Claude Code](https://claude.ai/) | ⭐⭐ | Anthropic 官方 CLI 工具 |
-> 💡 **AI 生成图片建议**:如需 AI 生成配图,建议在 [Gemini](https://gemini.google.com/) 中生成后选择 **Download full size** 下载,分辨率比 Antigravity 直接生成的更高。Gemini 生成的图片右下角会有星星水印,可使用 [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover) 或本项目的 `tools/gemini_watermark_remover.py` 去除。
+### 4. 开始创作
-### 三步开始
-
-```
-1️⃣ 克隆仓库
- 打开编辑器 → Clone Repository → 输入本仓库地址
- git clone https://github.com/hugohe3/ppt-master.git
-
-2️⃣ 打开聊天窗口
- 在编辑器中打开 AI 聊天面板(Antigravity/Cursor/Copilot Chat)
-
-3️⃣ 开始对话
- 直接告诉 AI 你想创建什么内容(若 AI 迷失上下文,可提示其参考 AGENTS.md),AI 会自动按照仓库中的角色定义工作
-```
-
-### 使用示例
+在 AI 编辑器中打开聊天面板,直接描述你想创作的内容:
```
用户:我有一份关于 Q3 季度业绩的报告,需要制作成 PPT
@@ -52,7 +80,27 @@ AI(Strategist 角色):好的,在开始之前我需要完成八项确认.
...
```
-💡 **模型推荐**:Opus 4.5 效果最佳,Antigravity 目前可免费使用
+> 💡 **模型推荐**:Opus 4.5 效果最佳,Antigravity 目前可免费使用
+
+> 💡 **AI 迷失上下文?** 可提示 AI 参考 `AGENTS.md` 文件,它会自动按照仓库中的角色定义工作
+
+> 💡 **AI 生成图片建议**:如需 AI 生成配图,建议在 [Gemini](https://gemini.google.com/) 中生成后选择 **Download full size** 下载,分辨率比 Antigravity 直接生成的更高。Gemini 生成的图片右下角会有星星水印,可使用 [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover) 或本项目的 `tools/gemini_watermark_remover.py` 去除。
+
+---
+
+## 📚 文档导航
+
+| 文档 | 说明 |
+|------|------|
+| 📖 [工作流教程](./docs/workflow_tutorial.md) | 详细的工作流程和案例演示 |
+| 🎨 [设计指南](./docs/design_guidelines.md) | 配色、排版、布局规范详解 |
+| 📐 [画布格式](./docs/canvas_formats.md) | PPT、小红书、朋友圈等 10+ 种格式 |
+| 🖼️ [图片嵌入指南](./docs/svg_image_embedding.md) | SVG 图片嵌入最佳实践 |
+| 📊 [图表模板库](./templates/charts/) | 13 种标准化图表模板 · [在线预览](./templates/charts/preview.html) |
+| ⚡ [快速参考](./docs/quick_reference.md) | 常用命令和参数速查 |
+| 🔧 [角色定义](./roles/README.md) | 6 个 AI 角色的完整定义 |
+| 🛠️ [工具集](./tools/README.md) | 所有工具的使用说明 |
+| 💼 [示例索引](./examples/README.md) | 15 个项目、229 页 SVG 示例 |
---
@@ -60,1047 +108,149 @@ AI(Strategist 角色):好的,在开始之前我需要完成八项确认.
> 📁 **示例库**: [`examples/`](./examples/) · **15 个项目** · **229 页 SVG**
-### 示例项目总览
-
| 类别 | 项目 | 页数 | 特色 |
| --------------- | ------------------------------------------------------------------------------ | :--: | --------------------------------- |
| 🏢 **咨询风格** | [心理治疗中的依恋](./examples/ppt169_顶级咨询风_心理治疗中的依恋/) | 32 | 顶级咨询风格,最大规模示例 |
| | [构建有效AI代理](./examples/ppt169_顶级咨询风_构建有效AI代理_Anthropic/) | 15 | Anthropic 工程博客,AI Agent 架构 |
| | [重庆市区域报告](./examples/ppt169_顶级咨询风_重庆市区域报告_ppt169_20251213/) | 20 | 区域财政分析,企业预警通数据 🆕 |
| | [甘孜州经济财政分析](./examples/ppt169_顶级咨询风_甘孜州经济财政分析/) | 17 | 政务财政分析,藏区文化元素 |
-| | [南欧江水电站战略评估](./examples/ppt169_高端咨询风_南欧江水电站战略评估/) | 20 | "流域危机"设计语言 |
-| | [汽车认证五年战略规划](./examples/ppt169_高端咨询风_汽车认证五年战略规划/) | 20 | McKinsey/BCG 风格 |
-| | [麦肯锡风客户忠诚度](./examples/ppt169_麦肯锡风_kimsoong_customer_loyalty/) | 8 | 麦肯锡经典 MECE 原则 |
-| | [Google 年度工作汇报](./examples/ppt169_谷歌风_google_annual_report/) | 10 | Google 品牌设计语言 |
| 🎨 **通用灵活** | [Debug 六步法](./examples/ppt169_通用灵活+代码_debug六步法/) | 10 | 深色科技风格 |
| | [重庆大学论文格式](./examples/ppt169_通用灵活+学术_重庆大学论文格式标准/) | 11 | 学术规范指南 |
-| | [AI 编程工具对比](./examples/ppt169_通过灵活+代码_三大AI编程神器横向对比/) | 11 | 技术评测风格 |
| ✨ **创意风格** | [地山谦卦深度研究](./examples/ppt169_易理风_地山谦卦深度研究/) | 20 | 易经本体美学,阴阳爻变设计 |
| | [金刚经第一品研究](./examples/ppt169_禅意风_金刚经第一品研究/) | 15 | 禅意学术,水墨留白 |
| | [Git 入门指南](./examples/ppt169_像素风_git_introduction/) | 10 | 像素复古游戏风 |
-| | [PPT Master 介绍](./examples/demo_project_intro_ppt169_20251211/) | 10 | 清新科技风格 |
📖 [查看完整示例文档](./examples/README.md)
-### 代表作品展示
-
-#### 顶级咨询风格 · 心理治疗中的依恋(32 页)
-
-> 最大规模示例项目,"安全基地"视觉隐喻
-
-📁 [查看项目](./examples/ppt169_顶级咨询风_心理治疗中的依恋/) · 📄 [设计规范](./examples/ppt169_顶级咨询风_心理治疗中的依恋/设计规范与内容大纲.md)
-
-#### 易理玄学风格 · 地山谦卦深度研究(20 页)
-
-> 阴阳爻变设计语言,六爻层进结构
-
-📁 [查看项目](./examples/ppt169_易理风_地山谦卦深度研究/) · 📄 [设计规范](./examples/ppt169_易理风_地山谦卦深度研究/设计规范与内容大纲.md)
-
-#### 像素复古风格 · Git 入门指南(10 页)
-
-> 霓虹色系,"存档点"隐喻版本控制
-
-📁 [查看项目](./examples/ppt169_像素风_git_introduction/) · 📄 [设计规范](./examples/ppt169_像素风_git_introduction/设计规范与内容大纲.md)
-
---
-<details>
-<summary><b>📋 目录(点击展开)</b></summary>
-
-| 章节 | 链接 |
-| --------------- | ---------------------- |
-| 🚀 快速使用指南 | [跳转](#-快速使用指南) |
-| 🎴 精选示例 | [跳转](#-精选示例) |
-| 项目简介 | [跳转](#项目简介) |
-| 核心特性 | [跳转](#核心特性) |
-| 系统架构 | [跳转](#系统架构) |
-| 核心角色 | [跳转](#核心角色) |
-| 快速开始 | [跳转](#快速开始) |
-| 更多示例 | [跳转](#更多示例) |
-| 设计风格 | [跳转](#设计风格) |
-| 技术规范 | [跳转](#技术规范) |
-| 项目结构 | [跳转](#项目结构) |
-| 最佳实践 | [跳转](#最佳实践) |
-| 常见问题 | [跳转](#常见问题) |
-| 贡献指南 | [跳转](#贡献指南) |
-| 路线图 | [跳转](#路线图) |
-| 🛠️ 工具集 | [跳转](#️-工具集) |
-| 📄 开源协议 | [跳转](#-开源协议) |
-| 🙏 致谢 | [跳转](#-致谢) |
-| 📮 联系方式 | [跳转](#-联系方式) |
-
-</details>
-
-## 📚 文档导航
-
-- 🚀 **新手入门**: 阅读本 README
-- 📖 **详细教程**: [工作流教程](./docs/workflow_tutorial.md)
-- 🎨 **设计指南**: [设计规范详解](./docs/design_guidelines.md)
-- 📐 **画布格式**: [支持的所有格式](./docs/canvas_formats.md)
-- 🖼️ **图片嵌入**: [SVG 图片嵌入指南](./docs/svg_image_embedding.md)
-- 📊 **图表模板**: [标准化图表模板库](./templates/charts/) - 13种常用图表 · [在线预览](./templates/charts/preview.html)
-- ⚡ **快速查阅**: [快速参考指南](./docs/quick_reference.md)
-- 🔧 **角色定义**: [查看所有角色](./roles/README.md)
-- 🛠️ **工具集**: [工具使用指南](./tools/README.md)
-- 💼 **示例索引**: [查看所有示例](./examples/README.md)
-
-## 项目简介
-
-PPT Master 是一个创新的 AI 辅助视觉内容创作系统,通过多角色协作(策略师、图片生成师、执行师、优化师),实现从内容策划到视觉优化的完整工作流。系统不仅支持生成符合顶尖咨询公司(如麦肯锡、波士顿咨询)标准的商业演示文稿,还支持小红书帖子、朋友圈海报、Instagram 等多种社交媒体和营销物料格式。
-
-## 核心特性
-
-✨ **智能内容解构** - 自动分析源文档并重组为清晰的页面序列
-🎨 **三重设计风格** - 支持"通用灵活"、"一般咨询"和"顶级咨询(MBB 级)"
-📐 **多格式支持** - 演示文稿 (16:9/4:3)、小红书 (3:4)、朋友圈 (1:1)、Story (9:16) 等 10+ 种格式
-📊 **数据可视化** - 内置图表、时间轴、KPI 展示等专业组件
-🎯 **CRAP 设计原则** - 遵循对比、重复、对齐、亲密性四大核心原则
-🖼️ **纯 SVG 输出** - 高质量矢量图形,自动适配不同尺寸,无需第三方依赖
-🎤 **演讲者备注** - 自动生成讲稿并嵌入 PPTX,支持演讲者视图 🆕
-🔄 **迭代优化** - 支持逐页生成和反馈修改
-
-## 系统架构
-
-### 快速概览
+## 🏗️ 系统架构
```
用户输入 (PDF/URL/Markdown)
↓
-[源内容转换] 自动触发
- ├─ PDF → pdf_to_md.py
- ├─ URL → web_to_md.py / web_to_md.cjs
- └─ MD → 直接读取
+[源内容转换] → pdf_to_md.py / web_to_md.py
↓
-[创建项目文件夹] project_manager.py init
+[创建项目] → project_manager.py init
↓
-[模板选项] 询问用户选择(必须在策略师之前确认)
- │
- ├─ A) 使用已有模板 → 复制模板到项目 templates/ → 进入策略师(参考模板设计)
- ├─ B) 不使用模板 → 进入策略师
- └─ C) 生成新模板 → 进入策略师(大纲完成后调用 Template_Designer)
+[模板选项] A) 使用已有模板 B) 不使用模板 C) 生成新模板
↓
-[Strategist] 策略师 - 八项确认与设计规范(必须,不可跳过)
- │
- ├─ 模板选项 = C(生成新模板)?
- │ │
- │ YES → [Template_Designer] 模板设计师
- │ │
- │ NO ─────────────────────────────────────────────┤
- │ │
- ├─ 图片方式包含「AI 生成」? │
- │ │ │
- │ YES → [Image_Generator] 图片生成师 → 图片归集到 images/│
- │ │ │
- │ NO ───────────────────────────────────────────────────┤
- │ │
- ▼ ▼
-[Executor] 执行师(根据模板选项决定是否遵循模板)- SVG代码生成
+[Strategist] 策略师 - 八项确认与设计规范
↓
-[Optimizer_CRAP] 优化师 - 视觉优化(可选)
+[Template_Designer] 模板设计师(仅选项 C 触发)
↓
-SVG 文件 (svg_output/)
+[Image_Generator] 图片生成师(当选择 AI 生成时)
↓
-后处理工具(自动执行)
- ├── finalize_svg.py → svg_final/(嵌入图标 + 修复图片宽高比 + 嵌入图片 + 文本扁平化 + 圆角转Path)
- └── svg_to_pptx.py → output.pptx(导出 PowerPoint + 嵌入演讲者备注)
-```
-
-> **注意**:
->
-> - 源内容转换是强制触发的,识别到 PDF/URL 后必须立即调用工具
-> - 模板阶段是可选的,用户可选择使用已有模板、生成新模板或不使用模板
-> - Image_Generator 是串行环节,图片归集完成后才进入 Executor 阶段
-> - Optimizer_CRAP 仅在质量不足时使用;若使用优化,需重新运行后处理与导出以保持产物一致
-
-### 完整工作流程图
-
-```mermaid
-graph TD
- %% 样式定义
- classDef role fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
- classDef artifact fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
- classDef tool fill:#e0f2f1,stroke:#00695c,stroke-width:2px;
- classDef userAction fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
- classDef external fill:#eee,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5;
-
- %% 流程入口
- RawDoc([原始参考资料 PDF/Word]) --> PDFConvert{PDF 类型?}
-
- %% 准备阶段
- subgraph Preparation [准备阶段 Resources Prep]
- PDFConvert -- 原生 PDF --> PyMuPDF[pdf_to_md.py 本地转换]:::tool
- PDFConvert -- 扫描版/复杂排版 --> Mineru[MinerU 云端 AI 转换]:::tool
-
- PyMuPDF -- 提取文本与结构 --> MD([基础 Markdown 文档]):::artifact
- Mineru -- 提取文本与结构 --> MD
-
- %% 图片处理流程
- subgraph ImageFlow [图片资源]
- LocalImgs(必须包含的图片文件) --> ImgFolder[存入 images/ 文件夹]:::userAction
- ImgFolder -- 在 MD 中添加图片描述 --> MD
- end
-
- %% 图标处理流程
- subgraph IconFlow [图标资源]
- Repo[SVG Repo 网站]:::external -- 搜索下载 --> UserIcon[下载匹配图标]:::userAction
- UserIcon -- 明确引用要求 --> IconReq(图标引用说明)
- end
- end
-
- %% 连接到规划阶段
- MD --> Strategist
- IconReq --> Strategist
-
- %% 规划阶段
- subgraph Planning [规划阶段 Content & Design]
- Strategist[Role 1 策略师: 内容与规范]:::role
-
- %% 交互确认
- Strategist -.-> Confirm1[交互确认: 七项关键要素]:::userAction
- Confirm1 -- 确认范围 --> Strategist
-
- %% 提示
- note1>确认: 图片路径/图标需求/风格] -.-> Confirm1
-
- Strategist --> SpecDoc([设计规范与内容大纲]):::artifact
- end
-
- SpecDoc --> CheckImage{图片方式包含 AI 生成?}
-
- %% 图片生成阶段(条件触发)
- subgraph ImageGen [图片生成阶段 - 条件触发]
- CheckImage -- 是 --> ImageGenerator[Role 2 图片生成师]:::role
- ImageGenerator -- 生成图片 --> ImagesReady([图片归集到 images/]):::artifact
- end
-
- CheckImage -- 否 --> SelectStyle
- ImagesReady --> SelectStyle{选择风格}
-
- %% 执行阶段
- subgraph Execution [执行阶段 SVG Generation]
- SelectStyle -- 通用灵活 --> ExecGen[Role 3 通用执行师]:::role
- SelectStyle -- 一般咨询 --> ExecCon[Role 4 咨询执行师]:::role
- SelectStyle -- 顶级咨询 --> ExecTop[Role 4+ 顶级咨询执行师]:::role
-
- ExecGen --> GenerateLoop
- ExecCon --> GenerateLoop
- ExecTop --> GenerateLoop
-
- GenerateLoop[逐页生成 SVG]:::userAction
- end
-
- GenerateLoop --> CheckQA{是否需要优化?}
-
- %% 优化与输出
- subgraph Output [优化与后处理]
- CheckQA -- 是 --> Optimizer[Role 5 CRAP 优化师]:::role
- Optimizer --> OptimizedSVG([优化后的 SVG]):::artifact
- OptimizedSVG --> CheckQA
-
- CheckQA -- 否 --> RawOutput[SVG 文件 svg_output/]:::artifact
-
- RawOutput --> ToolFinal[finalize_svg.py 最终化处理]:::tool
- ToolFinal -- 嵌入 images 和 icons --> FinalSVG[最终 SVG svg_final/]:::artifact
- FinalSVG --> ToolPPT[svg_to_pptx.py PPTX 转换]:::tool
- end
-
- ToolPPT --> End([输出: .pptx 演示文稿]):::artifact
-```
-
-## 核心角色
-
-> 系统包含 6 个专业角色:1 个策略师 + 1 个图片生成师(条件触发)+ 3 个执行师变体 + 1 个优化师
-
-### 1️⃣ Strategist (策略师)
-
-**职责**: 内容分析与设计规划
-**输出**: 《演示文稿设计规范与内容大纲》
-
-⚠️ **重要**: 工作流程的首要步骤是**初始沟通与范围确认**
-
-**核心能力**:
-
-- **初始沟通(八项确认)**: 在分析内容前必须完成以下确认,并主动提供专业建议:
- 1. 📐 **画布格式**: 根据使用场景推荐最适合的格式(PPT/小红书/朋友圈等)
- 2. 📊 **页数范围**: 根据内容量和复杂度建议合理的页数范围
- 3. 🎯 **目标受众与场景**: 基于文档特征预判目标受众和使用场景
- 4. 🎨 **设计风格**: A) 通用灵活 B) 一般咨询 C) 顶级咨询(MBB级),给出推荐理由
- 5. 🎨 **配色方案**: 给出主导色、辅助色、强调色的具体 HEX 色值
- 6. 🔣 **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
- 7. 🖼️ **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
- 8. 📝 **排版方案**: 字体组合(P1-P5预设或自定义)+ 正文字号基准(14-20pt)
-- **智能解构**: 将源文档拆解并重组为清晰的页面序列
-- **色彩方案**: 提出完整的配色方案(主导色、辅助色、基础色调)
-- **布局规划**: 规划页面序列和推荐布局方案
-- **排版体系**: 定义字体组合和大小层级
-- **风格化规范输出**:
- - 通用灵活风格:侧重视觉布局(画布适配、色彩方案、排版体系)
- - 一般咨询风格:侧重结构化呈现(MECE 分解、KPI 仪表盘)
- - 顶级咨询风格:侧重专业表达(SCQA 框架、金字塔原则、数据情境化)
-
-📄 [查看完整角色定义](./roles/Strategist.md)
-
-### 2️⃣ Image_Generator (图片生成师) - 条件触发
-
-**职责**: AI 图片生成(当用户选择的图片方式包含「AI 生成」时触发)
-**输出**: 生成的图片文件,归集到 `images/` 目录
-
-**核心能力**:
-
-- **触发条件**: 当 Strategist 阶段用户选择的图片方式**包含**「C) AI 生成」时激活(如 C、B+C、C+D)
-- **提示词优化**: 为每张待生成图片创建优化的 AI 图片生成提示词
-- **图片生成**: 使用 AI 图片生成工具(如 Gemini、Banana 等)生成图片
-- **资源归集**: 将生成的图片保存到项目的 `images/` 目录
-- **串行流程**: 图片生成完成后才进入 Executor 阶段
-
-> ⚠️ **注意**: 这是一个串行环节,必须在图片归集完成后才能进入 Executor 阶段
-
-📄 [查看完整角色定义](./roles/Image_Generator.md)
-
-### 3️⃣ Executor_General (通用执行师)
-
-**职责**: 生成通用灵活风格的 SVG 代码
-**输出**: 单页 SVG 代码
-
-**核心能力**:
-
-- **绝对遵循规范**: 严格按照 Strategist 确认的设计规范执行
-- **逐页生成**: 每次只生成一页,确保质量和可控性
-- **动态调整**: 在遵循强制尺寸前提下智能微调元素
-- **迭代修改**: 支持基于反馈重新生成
-- **技术要求**:
- - 画布尺寸:根据选定格式自动适配(PPT: 1280×720,小红书: 1242×1660 等)
- - viewBox 与画布尺寸一致
- - 禁用项与 PPT 兼容规则遵循 `AGENTS.md`
- - 使用 `<tspan>` 手动换行
- - 根据画布比例调整布局和卡片尺寸
-
-📄 [查看完整角色定义](./roles/Executor_General.md)
-
-### 4️⃣ Executor_Consultant (一般咨询执行师)
-
-**职责**: 生成一般咨询风格的 SVG 代码
-**输出**: 商业级演示文稿页面
-
-**核心能力**:
-
-- **基础咨询风格**: 简洁、清晰、数据可视化
-- **数据驱动**: 使用图表、时间轴等可视化工具
-- **KPI 展示**: 专业的仪表盘和关键指标呈现
-- **结构清晰**: 将内容组织为最多 5 个逻辑板块
-- **配色专业**: 使用咨询行业标准配色
-
-📄 [查看完整角色定义](./roles/Executor_Consultant.md)
-
-### 5️⃣ Executor_Consultant_Top (顶级咨询执行师)
-
-**职责**: 生成顶级咨询风格(MBB 级)的 SVG 代码
-**输出**: 战略级演示文稿页面
-
-**核心能力**:
-
-- **MBB 级风格**: 采用麦肯锡、贝恩、BCG 等顶尖咨询公司设计风格
-- **5 大核心技巧**:
- 1. **数据情境化**: 永不孤立呈现数据,必有对比参照
- 2. **SCQA 框架**: 情境→复杂性→问题→答案的叙事结构
- 3. **金字塔原则**: 结论先行,论据支撑
- 4. **颜色战略性使用**: 聚焦注意力、降低认知负荷
- 5. **图表 vs 表格选择**: 根据场景选择最佳可视化形式
-- **配色专业**: 使用麦肯锡蓝、BCG 深蓝等顶尖咨询配色
-- **布局合理**: 确保元素不重叠,留白充足
-
-📄 [查看完整角色定义](./roles/Executor_Consultant_Top.md)
-
-### 6️⃣ Optimizer_CRAP (CRAP 优化师)
-
-**职责**: 基于 CRAP 原则优化设计(仅在质量不足时使用)
-**输出**: 优化后的 SVG 代码(yh\_前缀);使用后需重新运行 `finalize_svg.py` 和 `svg_to_pptx.py`
-
-**四大核心原则**:
-
-1. **对齐 (Alignment)**:
- - 检查并修正元素对齐关系
- - 创建强大的无形视觉连接线
- - 确保每个元素都与其他元素有明确对齐关系
-
-2. **对比 (Contrast)**:
- - 增强视觉层次,突出重点信息
- - 加大尺寸、字重或颜色差异
- - 创造清晰的视觉焦点
-
-3. **重复 (Repetition)**:
- - 统一同类元素的视觉风格
- - 重复使用颜色、字体、圆角等视觉元素
- - 创造组织性和统一性
-
-4. **亲密性 (Proximity / 聚拢)**:
- - 将相关内容在空间上靠近
- - 加大不同逻辑组块间的距离
- - 形成清晰的视觉单元
-
-📄 [查看完整角色定义](./roles/Optimizer_CRAP.md)
-
-## 快速开始
-
-### 基本工作流
-
-1. **准备源文档**
-
- 将原始参考资料转换为 AI 可读格式:
-
- | 步骤 | 说明 |
- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | 📄 **文档转换** | **优先使用** `python3 tools/pdf_to_md.py <PDF文件>` 进行本地转换(快速、免费、隐私安全)。如遇扫描版 PDF、复杂多栏排版或数学公式,改用 [MinerU](https://github.com/opendatalab/MinerU) 云端 AI 转换 |
- | 🖼️ **图片资源** | 将必须包含的图片存入项目的 `images/` 文件夹,并在 Markdown 中添加图片描述说明 |
- | 🔣 **图标资源** | 如需自定义图标,可从 [SVG Repo](https://www.svgrepo.com/) 下载,或使用项目内置的 640+ 图标库(`templates/icons/`) |
-
- > 💡 **PDF 转换策略**: PyMuPDF 优先(本地秒级),MinerU 兜底(云端 AI)。详见 [工具使用指南](./tools/README.md)
-
-2. **初始沟通(八项确认)**
- 与 Strategist 进行范围确认,Strategist 会对以下八项给出专业建议:
- 1. **画布格式**: PPT/小红书/朋友圈/Story 等(基于使用场景推荐)
- 2. **页数范围**: 基于内容量分析建议合理页数
- 3. **目标受众与场景**: 基于文档特征预判
- 4. **设计风格**: A) 通用灵活 B) 一般咨询 C) 顶级咨询(MBB 级)
- 5. **配色方案**: 主导色、辅助色、强调色(提供具体 HEX 色值)
- 6. **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
- 7. **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
- 8. **排版方案**: 字体组合(P1-P5预设)+ 正文字号基准(14-20pt)
-
- 💡 Strategist 不仅会提出问题,还会主动提供专业建议供你参考或确认
-
-3. **获取规划**
- Strategist 分析内容并生成《设计规范与内容大纲》,根据选定风格侧重不同:
- - 通用灵活:视觉布局规范(画布适配、排版体系)
- - 一般咨询:结构化布局(MECE 分解、数据可视化)
- - 顶级咨询:专业表达方法论(SCQA、金字塔原则、5大核心技巧)
-
-4. **逐页生成**
- 使用相应的 Executor 角色生成每一页 SVG
-
-5. **优化润色**(可选)
- 使用 Optimizer_CRAP 进行 CRAP 原则优化
-
-6. **后处理**(推荐)
-
- ```bash
- python3 tools/finalize_svg.py <项目路径> # 执行全部后处理
- ```
-
-7. **导出使用**
- ```bash
- # 导出为 PPTX
- python3 tools/svg_to_pptx.py <项目路径> -s final # 使用 svg_final(推荐)
- python3 tools/svg_to_pptx.py <项目路径> # 使用 svg_output(原始版本)
- ```
- 或将 SVG 文件直接嵌入到其他演示环境中
-
-### 示例对话流程
-
+[Executor] 执行师 - 分阶段生成
+ ├── 视觉构建阶段:连续生成所有 SVG 页面
+ └── 逻辑构建阶段:批量生成演讲备注 → notes/
+ ↓
+[Optimizer_CRAP] 优化师(可选)
+ ↓
+[后处理] → finalize_svg.py → svg_to_pptx.py(自动嵌入讲稿)
+ ↓
+输出: SVG + PPTX
```
-用户: 我有一份市场分析报告需要制作成演示文稿
-
-Strategist: 在开始分析您的内容之前,我需要先完成八项确认:
-
-1. 画布格式:[建议] PPT 16:9 (1280×720),适合商业演示场景
-2. 页数范围:[建议] 8-10 页,确保每个核心议题有充分展示空间
+> 📖 详细工作流程请参阅 [工作流教程](./docs/workflow_tutorial.md) 和 [角色定义](./roles/README.md)
-3. 目标受众与场景:[建议] 面向企业中高层管理者的战略分析材料,
- 适用于季度/年度战略会议
-
-4. 设计风格:[建议] C) 顶级咨询风格(MBB 级),
- 体现数据驱动和专业权威感
-
-5. 配色方案:[建议]
- - 主导色: #005587 (麦肯锡蓝) - 专业、可信
- - 辅助色: #E8E8E8 (浅灰) - 背景、留白
- - 强调色: #FF6B35 (活力橙) - 数据高亮、重点标注
-
-6. 图标方式:[建议] C) 内置图标库,专业简洁
-
-7. 图片使用:[建议] A) 不使用图片,数据报告以图表为主
-
-8. 排版方案:[建议] P1 预设(微软雅黑+Arial),正文 18pt 基准
-
-用户: 同意你的建议
-
-Strategist: [分析内容,生成完整的设计规范与内容大纲...]
-
-用户: 规划很好!请生成第1页:封面
+---
-Executor_Consultant_Top: [生成第1页SVG代码...]
+## 🛠️ 常用命令
-用户: 请继续生成第2页
+```bash
+# 初始化项目
+python3 tools/project_manager.py init <项目名> --format ppt169
-Executor_Consultant_Top: [生成第2页SVG代码...]
+# PDF 转 Markdown
+python3 tools/pdf_to_md.py <PDF文件>
-用户: 第2页很重要,请使用CRAP原则优化视觉效果
+# 后处理 SVG
+python3 tools/finalize_svg.py <项目路径>
-Optimizer_CRAP:
-我将分析第2页并应用CRAP原则:
-1. 对齐:确保所有元素严格对齐网格
-2. 对比:增大数字与标签的尺寸差异
-3. 重复:统一卡片样式
-4. 亲密性:将相关数据更紧密组合
-[输出优化后的yh_slide_02.svg...]
+# 导出 PPTX
+python3 tools/svg_to_pptx.py <项目路径> -s final
```
-💡 **提示**: 查看 `examples/` 目录下的示例项目,了解完整的项目实施过程和最终效果。
-
-## 设计风格
-
-### 通用灵活风格
-
-- 适用场景:一般商业演示、教育培训、团队汇报
-- 设计特点:灵活布局、色彩丰富、易于定制
-- 内容结构:清晰的逻辑层次和视觉引导
-
-### 一般咨询风格
-
-- 适用场景:商务报告、项目汇报、客户演示
-- 设计特点:简洁清晰、数据可视化、专业感
-- 典型元素:KPI 仪表盘、数据图表、MECE 分解
-
-### 顶级咨询风格(MBB 级)
-
-- 适用场景:战略报告、董事会演示、高端客户提案
-- 设计特点:简洁专业、数据驱动、强调洞察
-- 参考标准:麦肯锡、贝恩、BCG 等顶尖咨询公司
-- **5 大核心技巧**:数据情境化、SCQA 框架、金字塔原则、颜色战略性使用、图表 vs 表格选择
-- 典型元素:矩阵图、时间轴、KPI 仪表盘、瀑布图、驱动因素树
+> 📖 完整工具说明请参阅 [工具使用指南](./tools/README.md)
-### 政企风格
-
-- 适用场景:政府工作报告、党建汇报、央企国企演示
-- 设计特点:庄重权威、严谨大气、具有中国特色
-- 视觉元素:
- - **政府红**:体现政治站位与权威感
- - **科技蓝**:体现智慧政务与数字化
- - **电建蓝**:体现大国工匠与行业特色
-- 典型元素:徽标水印、红灯笼/丝带装饰、中国地图、严谨的标题层级
-
-## 技术规范
-
-### SVG 参数
-
-- **画布尺寸**: 根据选定格式自动适配(详见 [画布格式规范](./docs/canvas_formats.md))
- - PPT 16:9: 1280×720
- - PPT 4:3: 1024×768
- - 小红书: 1242×1660
- - 朋友圈: 1080×1080
- - Story: 1080×1920
- - 更多格式...
-- **ViewBox**: 与画布尺寸一致
-- **背景**: 使用 `<rect>`元素定义
-- **文本**: 使用 `<tspan>` 手动换行(禁用项详见 `AGENTS.md`)
-- **禁用项**: 遵循 `AGENTS.md` 中完整黑名单与 PPT 兼容规则
-- **字体**: 使用《设计规范与内容大纲》中指定的字体方案(详见 [字体选择](./docs/design_guidelines.md#字体选择))
-
-### PPT 兼容性规则(必须遵守)
-
-为确保导出 PPT 后效果一致,透明度必须使用标准写法:
-
-| ❌ 禁止 | ✅ 正确 |
-| ------------------------------ | ---------------------------------------------------- |
-| `fill="rgba(255,255,255,0.1)"` | `fill="#FFFFFF" fill-opacity="0.1"` |
-| `<g opacity="0.2">...</g>` | 每个子元素单独设置透明度 |
-| `<image opacity="0.3"/>` | 图片后加遮罩层 `<rect fill="背景色" opacity="0.7"/>` |
-
-> 📌 **记忆口诀**:PPT 不认 rgba、不认组透明、不认图片透明、不认 marker
-
-### 布局规范
-
-#### 通用灵活风格
-
-- **边距**: 根据画布比例自动调整(横屏 40-60px,竖屏 60-120px)
-- **卡片尺寸**: 根据画布高度和布局方式动态计算
-- **间距**: 20-60px(根据画布大小调整)
-
-#### 高端咨询风格
-
-- 遵循咨询行业最佳实践
-- 强调留白和视觉呼吸感
-- 数据图表占据主要视觉区域
-- 自动适配不同画布比例
-
-### 配色方案
-
-#### 咨询风格主导色
-
-- 德勤蓝: `#0076A8`
-- 麦肯锡蓝: `#005587`
-- BCG 深蓝: `#003F6C`
-
-#### 通用配色原则
-
-- 提供主导色、辅助色和基础色调
-- 支持亮色/深色主题
-- 使用 HEX 颜色值
+---
-## 项目结构
+## 📁 项目结构
```
ppt-master/
-├── README.md # 项目说明文档
-├── LICENSE # 许可证文件
-├── .gitignore # Git忽略规则
-│
-├── roles/ # AI 角色定义(请勿在此目录测试/写入示例)
-│ ├── README.md # 角色概览与工作流程
-│ ├── Strategist.md # 策略师角色定义
-│ ├── Image_Generator.md # 图片生成师角色定义(条件触发)
-│ ├── Executor_General.md # 通用执行师角色定义
-│ ├── Executor_Consultant.md # 一般咨询执行师角色定义
-│ ├── Executor_Consultant_Top.md # 顶级咨询执行师角色定义(MBB 级)
-│ └── Optimizer_CRAP.md # CRAP优化师角色定义
-│
-├── examples/ # 示例文件夹(每个示例一个独立目录)
-│ └── <project_name>_<format>_<YYYYMMDD>/
-│ ├── README.md
-│ ├── 设计规范与内容大纲.md / design_specification.md
-│ ├── preview.html(可选)
-│ └── svg_output/
-│
-├── docs/ # 文档中心
-│ ├── canvas_formats.md # 画布格式规范
-│ ├── design_guidelines.md # 详细设计指南(颜色、排版、布局)
-│ ├── svg_image_embedding.md # SVG 图片嵌入指南
-│ ├── workflow_tutorial.md # 工作流教程(实际案例演示)
-│ └── quick_reference.md # 快速参考指南(速查手册)
-│
-├── templates/ # 标准化模板库
-│ ├── charts/ # 图表模板(13种:KPI、柱状图、折线图等)
-│ │ ├── README.md # 图表模板使用说明
-│ │ ├── preview.html # 在线预览所有模板
-│ │ └── *.svg # 13个图表模板文件
-│ └── icons/ # 图标库(640+ 矢量图标)
-│ └── README.md # 图标库使用说明
-│
-├── tools/ # 实用工具
-│ ├── README.md # 工具说明
-│ ├── project_manager.py # 项目管理工具
-│ ├── svg_quality_checker.py # SVG 质量检查
-│ ├── batch_validate.py # 批量验证工具
-│ ├── finalize_svg.py # 最终化处理(嵌入图标 + 修复图片宽高比 + 嵌入图片)
-│ ├── embed_icons.py # 图标嵌入工具
-│ ├── embed_images.py # 图片嵌入工具
-│ ├── fix_image_aspect.py # 图片宽高比修复工具(防止 PPT 转形状时拉伸)
-│ ├── flatten_tspan.py # tspan扁平化工具
-│ └── svg_to_pptx.py # SVG转PPTX工具(原生矢量嵌入)
-│
-└── projects/ # 用户项目工作区(进行中的项目)
- └── <your_project_name>_<YYYYMMDD>/
-
-**重要**: 所有项目文件夹必须以日期后缀结尾,格式为 `_YYYYMMDD` (例如: `_20251012`)
-
-```
-
-## 最佳实践
-
-### 内容准备
-
-1. **清晰的逻辑结构** - 确保源文档有明确的章节和要点
-2. **数据准备充分** - 提供具体的数字和数据支持
-3. **视觉元素建议** - 预先考虑图表类型和布局需求
-
-### 设计过程
-
-1. **充分沟通** - 与 Strategist 确认所有设计参数
- - 💡 Strategist 会主动提供专业建议,认真考虑这些建议
- - 📋 如有不同想法,可以与 Strategist 的建议进行讨论和调整
-2. **逐页验证** - 每生成一页都要检查效果
-3. **适时优化** - 关键页面使用 Optimizer_CRAP 提升质量
-4. **保持一致** - 确保全套幻灯片风格统一
-
-### 输出管理
-
-1. **文件命名** - 使用清晰的命名规则(如:`01_cover.svg`)
-2. **版本控制** - 保存每次迭代的版本
-3. **格式转换** - 根据需要转换为 PNG 或 PDF
-4. **项目组织** - 将每个演示项目放在 `projects/` 目录下,包含设计规范和 SVG 输出
-
-## 更多示例
-
-本仓库是一个 **AI 工作流框架**,提供完整的角色定义、模板和工具集。
-
-### 📂 项目结构
-
-示例项目应位于 `examples/` 目录下,采用以下结构:
-
-```
-examples/
-└── <project_name>_<format>_<YYYYMMDD>/
- ├── 设计规范与内容大纲.md
- ├── images/ # 图片资源
- ├── svg_output/ # 原始 SVG(带占位符)
- └── svg_final/ # 最终 SVG(嵌入图标/图片)
+├── roles/ # AI 角色定义(6 个专业角色)
+├── docs/ # 文档中心(教程、设计指南、格式规范等)
+├── templates/ # 模板库(图表模板 + 640+ 图标)
+├── tools/ # 工具集(项目管理、转换、处理)
+├── examples/ # 示例项目(15 个完整案例)
+└── projects/ # 用户项目工作区
```
-### 🔍 预览 SVG
-
-```bash
-# 使用本地服务器预览
-python3 -m http.server --directory examples/<project>/svg_final 8000
-# 然后访问 http://localhost:8000
-```
-
-### 🚀 开始你的项目
-
-#### 使用项目管理工具(推荐)
-
-```bash
-# 1. 初始化新项目
-python3 tools/project_manager.py init my_project --format ppt169
-
-# 2. 编辑生成的设计规范文件
-# projects/my_project_ppt169_20251116/设计规范与内容大纲.md
-
-# 3. 使用 AI 角色生成 SVG 文件到 svg_output/ 目录
-
-# 4. 验证项目结构
-python3 tools/project_manager.py validate projects/my_project_ppt169_20251116
-```
-
-#### 手动创建项目
-
-参考示例结构,在 `projects/` 目录下创建你自己的项目:
-
-```
-projects/
-└── your_project_name_format_YYYYMMDD/ # 必须添加格式和日期后缀
- ├── README.md # 项目说明
- ├── 设计规范与内容大纲.md # Strategist生成的设计规范
- ├── 来源文档.md # 源文档(可选)
- ├── preview.html # 预览页面(自动生成)
- └── svg_output/ # 生成的SVG文件
- ├── 01_cover.svg
- ├── 02_xxx.svg
- └── ...
-```
-
-**重要命名规则**:
-
-- 项目文件夹名称格式: `{项目名称}_{format}_{YYYYMMDD}`
-- format: `ppt169`, `ppt43`, `wechat`, `xiaohongshu`, `story` 等
-- 日期使用8位数字格式,例如 `20251116` 代表 2025年11月16日
-- 示例: `my_presentation_ppt169_20251116`
-
-详细命名规范请参考上述示例
+---
-## 常见问题
+## ❓ 常见问题
<details>
-<summary><b>Q: 生成的SVG文件如何使用?</b></summary>
-
-A: SVG 文件可以:
+<summary><b>Q: 生成的 SVG 文件如何使用?</b></summary>
- 直接在浏览器中打开查看
-- 嵌入到 HTML 页面中
-- 使用设计工具(如 Figma、Adobe Illustrator)编辑
-- 转换为 PNG/PDF 格式用于传统演示软件
+- 使用 `svg_to_pptx.py` 导出为 PowerPoint
+- 嵌入到 HTML 页面或使用设计工具编辑
</details>
<details>
<summary><b>Q: 三种执行师有什么区别?</b></summary>
-A:
-
-- **Executor_General**: 适用于通用场景,提供灵活的布局和丰富的视觉选择
-- **Executor_Consultant**: 适用于一般咨询场景,简洁清晰的数据可视化
-- **Executor_Consultant_Top**: 适用于顶级咨询场景(MBB 级),采用 5 大核心表达技巧
+- **Executor_General**: 通用场景,灵活布局
+- **Executor_Consultant**: 一般咨询,数据可视化
+- **Executor_Consultant_Top**: 顶级咨询(MBB 级),5 大核心技巧
</details>
<details>
-<summary><b>Q: Image_Generator 什么时候使用?</b></summary>
+<summary><b>Q: 必须使用 Optimizer_CRAP 吗?</b></summary>
-A: Image_Generator 在 Strategist 的八项确认中,当图片方式**包含**「C) AI 生成」时触发(如 C、B+C、C+D 等组合)。它会在 Executor 阶段之前生成优化的图片提示词和图片,然后 Executor 可以直接引用生成的图片。
+不是必须的。仅在需要优化关键页面视觉效果时使用。
</details>
-<details>
-<summary><b>Q: 必须使用Optimizer_CRAP吗?</b></summary>
-
-A: 不是必须的。如果 Executor 生成的 SVG 已经满足需求,可以跳过优化步骤。Optimizer 主要用于进一步提升关键页面的视觉质量;若使用优化,需重新运行 `finalize_svg.py` 和 `svg_to_pptx.py` 以保持产物一致。
+> 📖 更多问题请查看 [工作流教程](./docs/workflow_tutorial.md#常见问题)
-</details>
-
-<details>
-<summary><b>Q: 可以自定义配色方案吗?</b></summary>
-
-A: 可以!在与 Strategist 沟通时,明确提出你的品牌色或偏好配色,Strategist 会据此调整设计规范。
-
-</details>
-
-## 贡献指南
+---
-我们欢迎各种形式的贡献!
+## 🤝 贡献指南
-### 如何贡献
+欢迎贡献!
1. Fork 本仓库
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
+2. 创建分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add AmazingFeature'`)
+4. 推送分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
-### 贡献方向
-
-- 🎨 新增设计风格模板
-- 📊 扩展图表类型和可视化组件
-- 📝 完善文档和教程
-- 🐛 报告 bug 和问题
-- 💡 提出新功能建议
-- 🌍 多语言支持
-- 📁 分享你的项目案例到 `examples/` 目录
-
-## 路线图
-
-### ✅ 已完成
-
-- [x] 建立完整的角色体系和工作流
-- [x] 实现通用和咨询两种设计风格
-- [x] 多格式画布支持(PPT 16:9/4:3、小红书、朋友圈、Story 等 10+ 格式)
-- [x] 项目管理工具集(初始化、验证、质量检查、批量处理)
-- [x] 标准化图表模板库(33 种图表类型)
-- [x] 640+ 矢量图标库(来源于 SVG Repo)
-- [x] Strategist 主动建议功能(从被动提问升级为主动顾问)
-- [x] **示例项目库**(15 个项目、229 页 SVG,涵盖咨询/通用/创意风格)
-- [x] 在线示例展示([幻灯片展示库](https://notes.36sjs.com/pages/ppt/slides-library.html))
-
-### 📋 计划中
-
-- [ ] 开发交互式配置工具
-- [ ] 支持动画效果和交互性
-- [ ] Web 界面开发
-- [ ] API 接口设计
-- [ ] GitHub Actions CI/CD 集成
-
-## 🛠️ 工具集
-
-PPT Master 提供了一套完整的工具来简化项目管理和内容生成流程。
-
-### 项目管理工具 (`project_manager.py`)
-
-创建、验证和管理项目的一站式工具:
-
-```bash
-# 初始化新项目
-python3 tools/project_manager.py init <project_name> --format ppt169
-
-# 验证项目结构
-python3 tools/project_manager.py validate <project_path>
-
-# 查看项目信息
-python3 tools/project_manager.py info <project_path>
-```
-
-支持的画布格式:`ppt169`, `ppt43`, `wechat`, `xiaohongshu`, `moments`, `story`, `banner`, `a4`
-
-### SVG 质量检查工具 (`svg_quality_checker.py`)
-
-检查 SVG 文件是否符合项目技术规范:
-
-```bash
-# 检查单个文件或目录
-python3 tools/svg_quality_checker.py examples/project/svg_output
-
-# 检查所有项目
-python3 tools/svg_quality_checker.py --all examples
-
-# 指定期望格式
-python3 tools/svg_quality_checker.py examples/project --format ppt169
-```
-
-**检查项目**:viewBox 属性、禁用元素(见 `AGENTS.md`)、字体使用、width/height 一致性、文本换行方式
-
-### 批量验证工具 (`batch_validate.py`)
-
-一次性检查多个项目的结构完整性:
-
-```bash
-# 验证单个目录
-python3 tools/batch_validate.py examples
-
-# 验证所有项目
-python3 tools/batch_validate.py --all
-
-# 导出报告
-python3 tools/batch_validate.py examples --export
-```
-
-### Examples 索引生成工具 (`generate_examples_index.py`)
-
-自动扫描 examples 目录并生成 README.md 索引文件:
-
-```bash
-python3 tools/generate_examples_index.py
-```
-
-### 后处理工具 (`finalize_svg.py`)
-
-统一后处理入口,执行嵌入图标、修复图片宽高比、嵌入图片、文本扁平化、圆角转 Path:
-
-```bash
-# 直接运行,无需参数
-python3 tools/finalize_svg.py <项目路径>
-```
-
-**处理步骤**:
-
-1. 嵌入图标 - 替换 `<use data-icon="..."/>` 为实际图标
-2. 修复图片宽高比 - 防止 PPT 转形状时图片拉伸变形 ✨
-3. 嵌入图片 - 将外部图片转为 Base64
-4. 文本扁平化 - 将 `<tspan>` 转为独立 `<text>`
-5. 圆角转 Path - 将 `<rect rx="..."/>` 转为 `<path>`
-
-**注意**:生成阶段仍应使用 `<tspan>` 手动换行,后处理会自动扁平化。
-
-### SVG 转 PPTX 工具 (`svg_to_pptx.py`)
-
-将 SVG 文件批量转换为 PowerPoint 演示文稿(原生 SVG 矢量嵌入):
-
-```bash
-# 使用最终版本(推荐)
-python3 tools/svg_to_pptx.py <项目路径> -s final
-
-# 使用原始版本
-python3 tools/svg_to_pptx.py <项目路径>
-
-# 指定输出文件
-python3 tools/svg_to_pptx.py <项目路径> -s final -o output.pptx
-```
-
-**特点**:SVG 以原生矢量格式嵌入,保持可编辑性,需要 PowerPoint 2016+ 查看。
-
-### 讲稿拆分工具 (`total_md_split.py`)
-
-将 `total.md` 讲稿文件拆分为多个独立的讲稿文件,每个文件对应一个 SVG 页面。
-
-**功能**:
-
-- 读取 `total.md` 文件,解析其中的一级标题和讲稿内容
-- 检查 `svg_output` 文件夹中的 SVG 文件是否都有对应的讲稿
-- 如果存在 SVG 没有对应的讲稿,会输出错误提示要求重新生成讲稿文件
-- 如果全部匹配,根据名称对文档进行拆分,分成多个文档
-- 拆分后的文档命名与 SVG 文件同名,后缀改为 `.md`
-- 拆分后的文档**不包含**一级标题
-
-**用法**:
-
-```bash
-# 基本用法
-python3 tools/total_md_split.py <项目路径>
-
-# 指定输出目录
-python3 tools/total_md_split.py <项目路径> -o <输出目录>
-
-# 静默模式
-python3 tools/total_md_split.py <项目路径> -q
-```
-
-**示例**:
-
-```bash
-# 基本用法
-python3 tools/total_md_split.py projects/<svg 标题>_ppt169_YYYYMMDD
-
-# 指定输出目录
-python3 tools/total_md_split.py projects/<svg 标题>_ppt169_YYYYMMDD -o notes
-
-# 静默模式
-python3 tools/total_md_split.py projects/<svg 标题>_ppt169_YYYYMMDD -q
-```
-
-**讲稿格式要求**:
-
-`total.md` 文件需要使用以下格式:
-
-```markdown
-# 01_<页面标题>
-
-讲稿内容...
-
----
-
-# 02_<页面标题>
-
-讲稿内容...
-
----
-
-# 03_<页面名称>
-
-讲稿内容...
-```
-
-- 每个章节以 `# ` 开头的一级标题开始
-- 章节之间用 `---` 分隔
-- 讲稿内容在标题之后,直到下一个标题或文件结束
-
-**错误处理**:
-
-如果存在 SVG 文件没有对应的讲稿,工具会输出错误信息:
-
-```
-错误: SVG 文件与讲稿不匹配
- 缺失的讲稿: <N>_<页面标题>
-
-请重新生成讲稿文件,确保每个 SVG 都有对应的讲稿。
-```
-
-**依赖**:
-
-- Python 3.6+
-- 无外部依赖(仅使用标准库)
-
-### 错误消息助手 (`error_helper.py`)
-
-提供友好的错误消息和具体的修复建议:
-
-```bash
-# 查看所有错误类型
-python3 tools/error_helper.py
-
-# 查看特定错误的解决方案
-python3 tools/error_helper.py missing_readme
-```
+**贡献方向**:🎨 设计模板 · 📊 图表组件 · 📝 文档完善 · 🐛 Bug 报告 · 💡 功能建议
---
-📖 **详细文档**: [工具使用指南](./tools/README.md)
-
## 📄 开源协议
本项目采用 [MIT License](LICENSE) 开源协议。
-你可以自由地:
-
-- ✅ 商业使用
-- ✅ 修改源代码
-- ✅ 分发和再授权
-- ✅ 私人使用
-
-但需要:
-
-- 📋 保留版权声明
-- 📋 保留许可证声明
-
## 🙏 致谢
-感谢以下开源项目:
-
-- [SVG Repo](https://www.svgrepo.com/) - 精美的开源图标库(本项目内置 640+ 图标)
-- [Robin Williams](<https://en.wikipedia.org/wiki/Robin_Williams_(author)>) - CRAP 设计原则的提出者
-- 麦肯锡、波士顿咨询、贝恩等顶尖咨询公司 - 设计灵感来源
+- [SVG Repo](https://www.svgrepo.com/) - 开源图标库
+- [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author)) - CRAP 设计原则
+- 麦肯锡、波士顿咨询、贝恩 - 设计灵感来源
## 📮 联系方式
- **Issue**: [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
- **GitHub**: [@hugohe3](https://github.com/hugohe3)
-- **项目链接**: [https://github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)
+
+---
## 🌟 Star History
diff --git a/README_EN.md b/README_EN.md
index 8e8dff78..0462de4c 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -6,7 +6,7 @@
English | [中文](./README.md)
-An AI-powered intelligent visual content generation system that transforms source documents into high-quality SVG content through collaboration of multiple professional roles, **supporting presentations, social media, marketing posters, and various other formats**.
+An AI-powered intelligent visual content generation system that transforms source documents into high-quality SVG content through multi-role collaboration, **supporting presentations, social media, marketing posters, and various other formats**.
> 🎴 **Online Examples**: [GitHub Pages Online Preview](https://hugohe3.github.io/ppt-master/) - View actual generated results
@@ -14,34 +14,62 @@ An AI-powered intelligent visual content generation system that transforms sourc
---
-## 🚀 Quick Start Guide
+## 🚀 Quick Start
-### Recommended Tools
+### 1. Configure Environment
-| Tool | Rating | Description |
-| --------------------------------------------------- | :----: | -------------------------------------------------------------------------------------------------------------------------------- |
-| **[Antigravity](https://antigravity.dev/)** | ⭐⭐⭐ | **Highly Recommended**! Free Opus 4.5 access, integrated Banana image generation, can generate images directly in the repository |
-| [Cursor](https://cursor.sh/) | ⭐⭐ | Mainstream AI editor, supports multiple models |
-| [VS Code + Copilot](https://code.visualstudio.com/) | ⭐⭐ | Microsoft official solution |
-| [Claude Code](https://claude.ai/) | ⭐⭐ | Anthropic official CLI tool |
+#### Python Environment (Required)
-> 💡 **AI Image Generation Tip**: For AI-generated images, we recommend generating them in [Gemini](https://gemini.google.com/) and selecting **Download full size** for higher resolution than Antigravity's direct generation. Gemini images have a star watermark in the bottom right corner, which can be removed using [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover) or this project's `tools/gemini_watermark_remover.py`.
+This project requires **Python 3.8+** for running PDF conversion, SVG post-processing, PPTX export, and other tools.
-### Three Steps to Start
+**Install Python:**
-```
-1️⃣ Clone the Repository
- Open editor → Clone Repository → Enter this repository URL
- git clone https://github.com/hugohe3/ppt-master.git
+| Platform | Recommended Installation |
+|----------|-------------------------|
+| **macOS** | Use [Homebrew](https://brew.sh/): `brew install python` |
+| **Windows** | Download installer from [Python Official Website](https://www.python.org/downloads/) |
+| **Linux** | Use package manager: `sudo apt install python3 python3-pip` (Ubuntu/Debian) |
+
+> 💡 **Verify Installation**: Run `python3 --version` to confirm version ≥ 3.8
+
+#### Node.js Environment (Optional)
-2️⃣ Open Chat Window
- Open AI chat panel in your editor (Antigravity/Cursor/Copilot Chat)
+If you need to use the `web_to_md.cjs` tool (for converting web pages from WeChat and other high-security sites), install Node.js.
-3️⃣ Start Conversation
- Tell the AI what content you want to create (if the AI loses context, you can suggest referring to AGENTS.md), it will automatically follow the role definitions in the repository
+**Install Node.js:**
+
+| Platform | Recommended Installation |
+|----------|-------------------------|
+| **macOS** | Use [Homebrew](https://brew.sh/): `brew install node` |
+| **Windows** | Download LTS version from [Node.js Official Website](https://nodejs.org/) |
+| **Linux** | Use [NodeSource](https://github.com/nodesource/distributions): `curl -fsSL https://deb.nodesource.com/setup_lts.x \| sudo -E bash - && sudo apt-get install -y nodejs` |
+
+> 💡 **Verify Installation**: Run `node --version` to confirm version ≥ 18
+
+### 2. Clone Repository and Install Dependencies
+
+```bash
+git clone https://github.com/hugohe3/ppt-master.git
+cd ppt-master
+pip install -r requirements.txt
```
-### Usage Example
+> If you encounter permission issues, use `pip install --user -r requirements.txt` or install in a virtual environment.
+
+### 3. Open AI Editor
+
+Recommended AI editors:
+
+| Tool | Rating | Description |
+| --------------------------------------------------- | :----: | -------------------------------------------------------------------------------------------------------------------- |
+| **[Antigravity](https://antigravity.dev/)** | ⭐⭐⭐ | **Highly Recommended**! Free Opus 4.5 access, integrated Banana image generation, can generate images directly in the repository |
+| [Cursor](https://cursor.sh/) | ⭐⭐ | Mainstream AI editor, supports multiple models |
+| [VS Code + Copilot](https://code.visualstudio.com/) | ⭐⭐ | Microsoft official solution |
+| [Claude Code](https://claude.ai/) | ⭐⭐ | Anthropic official CLI tool |
+
+### 4. Start Creating
+
+Open the AI chat panel in your editor and describe what content you want to create:
```
User: I have a Q3 quarterly report that needs to be made into a PPT
@@ -52,7 +80,27 @@ AI (Strategist role): Sure, before we begin I need to complete eight confirmatio
...
```
-💡 **Model Recommendation**: Opus 4.5 works best, Antigravity currently offers free access
+> 💡 **Model Recommendation**: Opus 4.5 works best, Antigravity currently offers free access
+
+> 💡 **AI Lost Context?** You can prompt the AI to refer to the `AGENTS.md` file, and it will automatically follow the role definitions in the repository
+
+> 💡 **AI Image Generation Tip**: For AI-generated images, we recommend generating them in [Gemini](https://gemini.google.com/) and selecting **Download full size** for higher resolution than Antigravity's direct generation. Gemini images have a star watermark in the bottom right corner, which can be removed using [gemini-watermark-remover](https://github.com/journey-ad/gemini-watermark-remover) or this project's `tools/gemini_watermark_remover.py`.
+
+---
+
+## 📚 Documentation Navigation
+
+| Document | Description |
+|----------|-------------|
+| 📖 [Workflow Tutorial](./docs/workflow_tutorial.md) | Detailed workflow and case demonstrations |
+| 🎨 [Design Guidelines](./docs/design_guidelines.md) | Colors, typography, layout specifications |
+| 📐 [Canvas Formats](./docs/canvas_formats.md) | PPT, Xiaohongshu, WeChat Moments, and 10+ formats |
+| 🖼️ [Image Embedding Guide](./docs/svg_image_embedding.md) | SVG image embedding best practices |
+| 📊 [Chart Template Library](./templates/charts/) | 13 standardized chart templates · [Online Preview](./templates/charts/preview.html) |
+| ⚡ [Quick Reference](./docs/quick_reference.md) | Common commands and parameters cheat sheet |
+| 🔧 [Role Definitions](./roles/README.md) | Complete definitions of 6 AI roles |
+| 🛠️ [Toolset](./tools/README.md) | Usage instructions for all tools |
+| 💼 [Examples Index](./examples/README.md) | 15 projects, 229 SVG pages of examples |
---
@@ -60,984 +108,149 @@ AI (Strategist role): Sure, before we begin I need to complete eight confirmatio
> 📁 **Example Library**: [`examples/`](./examples/) · **15 projects** · **229 SVG pages**
-### Example Projects Overview
-
| Category | Project | Pages | Features |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | :---: | ----------------------------------------------------- |
| 🏢 **Consulting Style** | [Attachment in Psychotherapy](./examples/ppt169_顶级咨询风_心理治疗中的依恋/) | 32 | Top consulting style, largest scale example |
| | [Building Effective AI Agents](./examples/ppt169_顶级咨询风_构建有效AI代理_Anthropic/) | 15 | Anthropic engineering blog, AI Agent architecture |
| | [Chongqing Regional Report](./examples/ppt169_顶级咨询风_重庆市区域报告_ppt169_20251213/) | 20 | Regional fiscal analysis, Enterprise Alert data 🆕 |
| | [Ganzi Prefecture Economic Analysis](./examples/ppt169_顶级咨询风_甘孜州经济财政分析/) | 17 | Government fiscal analysis, Tibetan cultural elements |
-| | [Nam Ou River Hydropower Strategic Assessment](./examples/ppt169_高端咨询风_南欧江水电站战略评估/) | 20 | "Basin Crisis" design language |
-| | [Automotive Certification 5-Year Strategic Plan](./examples/ppt169_高端咨询风_汽车认证五年战略规划/) | 20 | McKinsey/BCG style |
-| | [McKinsey Style Customer Loyalty](./examples/ppt169_麦肯锡风_kimsoong_customer_loyalty/) | 8 | Classic McKinsey MECE principles |
-| | [Google Annual Work Report](./examples/ppt169_谷歌风_google_annual_report/) | 10 | Google brand design language |
| 🎨 **General Flexible** | [Debug Six-Step Method](./examples/ppt169_通用灵活+代码_debug六步法/) | 10 | Dark tech style |
| | [Chongqing University Thesis Format](./examples/ppt169_通用灵活+学术_重庆大学论文格式标准/) | 11 | Academic standards guide |
-| | [AI Programming Tools Comparison](./examples/ppt169_通过灵活+代码_三大AI编程神器横向对比/) | 11 | Tech review style |
| ✨ **Creative Style** | [I Ching Qian Hexagram Study](./examples/ppt169_易理风_地山谦卦深度研究/) | 20 | I Ching aesthetics, Yin-Yang design |
| | [Diamond Sutra Chapter 1 Study](./examples/ppt169_禅意风_金刚经第一品研究/) | 15 | Zen academic, ink wash whitespace |
| | [Git Introduction Guide](./examples/ppt169_像素风_git_introduction/) | 10 | Pixel retro game style |
-| | [PPT Master Introduction](./examples/demo_project_intro_ppt169_20251211/) | 10 | Fresh tech style |
📖 [View Complete Examples Documentation](./examples/README.md)
-### Featured Works
-
-#### Top Consulting Style · Attachment in Psychotherapy (32 pages)
-
-> Largest scale example project, "Secure Base" visual metaphor
-
-📁 [View Project](./examples/ppt169_顶级咨询风_心理治疗中的依恋/) · 📄 [Design Specification](./examples/ppt169_顶级咨询风_心理治疗中的依恋/设计规范与内容大纲.md)
-
-#### I Ching Style · Qian Hexagram Deep Study (20 pages)
-
-> Yin-Yang transformation design language, six-line progressive structure
-
-📁 [View Project](./examples/ppt169_易理风_地山谦卦深度研究/) · 📄 [Design Specification](./examples/ppt169_易理风_地山谦卦深度研究/设计规范与内容大纲.md)
-
-#### Pixel Retro Style · Git Introduction Guide (10 pages)
-
-> Neon color scheme, "Save Point" version control metaphor
-
-📁 [View Project](./examples/ppt169_像素风_git_introduction/) · 📄 [Design Specification](./examples/ppt169_像素风_git_introduction/设计规范与内容大纲.md)
-
---
-<details>
-<summary><b>📋 Table of Contents (Click to expand)</b></summary>
-
-| Section | Link |
-| ------------------------ | --------------------------------- |
-| 🚀 Quick Start Guide | [Jump](#-quick-start-guide) |
-| 🎴 Featured Examples | [Jump](#-featured-examples) |
-| Project Introduction | [Jump](#project-introduction) |
-| Core Features | [Jump](#core-features) |
-| System Architecture | [Jump](#system-architecture) |
-| Roles | [Jump](#roles) |
-| Getting Started | [Jump](#getting-started) |
-| More Examples | [Jump](#more-examples) |
-| Design Styles | [Jump](#design-styles) |
-| Technical Specifications | [Jump](#technical-specifications) |
-| Project Structure | [Jump](#project-structure) |
-| Best Practices | [Jump](#best-practices) |
-| FAQ | [Jump](#faq) |
-| Contributing Guide | [Jump](#contributing-guide) |
-| Roadmap | [Jump](#roadmap) |
-| 🛠️ Toolset | [Jump](#️-toolset) |
-| 📄 License | [Jump](#-license) |
-| 🙏 Acknowledgments | [Jump](#-acknowledgments) |
-| 📮 Contact | [Jump](#-contact) |
-
-</details>
-
-## 📚 Documentation Navigation
-
-- 🚀 **Getting Started**: Read this README
-- 📖 **Detailed Tutorial**: [Workflow Tutorial](./docs/workflow_tutorial.md)
-- 🎨 **Design Guide**: [Design Guidelines](./docs/design_guidelines.md)
-- 📐 **Canvas Formats**: [All Supported Formats](./docs/canvas_formats.md)
-- 🖼️ **Image Embedding**: [SVG Image Embedding Guide](./docs/svg_image_embedding.md)
-- 📊 **Chart Templates**: [Standardized Chart Template Library](./templates/charts/) - 13 common charts · [Online Preview](./templates/charts/preview.html)
-- ⚡ **Quick Reference**: [Quick Reference Guide](./docs/quick_reference.md)
-- 🔧 **Role Definitions**: [View All Roles](./roles/README.md)
-- 🛠️ **Toolset**: [Tools Usage Guide](./tools/README.md)
-- 💼 **Examples Index**: [View All Examples](./examples/README.md)
-
-## Project Introduction
-
-PPT Master is an innovative AI-assisted visual content creation system that achieves a complete workflow from content planning to visual optimization through collaboration of multiple professional AI roles. The system not only supports generating business presentations that meet the standards of top consulting firms (such as McKinsey, Boston Consulting), but also supports various social media and marketing materials formats including Xiaohongshu posts, WeChat Moments posters, Instagram, and more.
-
-## Core Features
-
-✨ **Intelligent Content Deconstruction** - Automatically analyzes source documents and reorganizes them into clear page sequences
-🎨 **Three Design Styles** - Supports "General Flexible", "General Consulting" and "Top Consulting (MBB Level)"
-📐 **Multi-Format Support** - Presentations (16:9/4:3), Xiaohongshu (3:4), WeChat Moments (1:1), Story (9:16) and 10+ other formats
-📊 **Data Visualization** - Built-in charts, timelines, KPI displays and other professional components
-🎯 **CRAP Design Principles** - Follows four core principles: Contrast, Repetition, Alignment, Proximity
-🖼️ **Pure SVG Output** - High-quality vector graphics, automatically adapts to different sizes, no third-party dependencies
-🎤 **Speaker Notes** - Auto-generates scripts and embeds into PPTX, supports presenter view 🆕
-🔄 **Iterative Optimization** - Supports page-by-page generation and feedback modification
-
-## System Architecture
-
-### Quick Overview
+## 🏗️ System Architecture
```
User Input (PDF/URL/Markdown)
↓
-[Source Content Conversion] Auto-triggered
- ├─ PDF → pdf_to_md.py
- ├─ URL → web_to_md.py / web_to_md.cjs
- └─ MD → Direct read
+[Source Content Conversion] → pdf_to_md.py / web_to_md.py
↓
-[Create Project Folder] project_manager.py init
+[Create Project] → project_manager.py init
↓
-[Template Option] Ask user (must confirm before Strategist)
- │
- ├─ A) Use existing template → Copy to project templates/ → Strategist (reference template)
- ├─ B) No template → Proceed to Strategist
- └─ C) Generate new template → Proceed to Strategist (Template_Designer after outline)
+[Template Option] A) Use existing template B) No template C) Generate new template
↓
-[Strategist] - Eight Confirmations & Design Specifications (Required, cannot skip)
- │
- ├─ Template Option = C (Generate new)?
- │ │
- │ YES → [Template_Designer] - Generate templates
- │ │
- │ NO ──────────────────────────────────────────┐
- │ │
- ├─ Image Method = "C) AI Generated"? │
- │ │ │
- │ YES → [Image_Generator] - Generate to images/│
- │ │ │
- │ NO ──────────────────────────────────────────┤
- │ │
- ▼ ▼
-[Executor_General / Executor_Consultant / Executor_Consultant_Top] - SVG Code Generation
+[Strategist] - Eight Confirmations & Design Specifications
↓
-[Optimizer_CRAP] - Visual Optimization (Optional)
+[Template_Designer] (Only triggered for option C)
↓
-SVG Files (svg_output/)
+[Image_Generator] (When AI generation is selected)
↓
-Post-processing Tools (Auto-executed)
- ├── finalize_svg.py → svg_final/ (Embed icons + Fix image aspect ratio + Embed images + Text flattening + Round corners to Path)
- └── svg_to_pptx.py → output.pptx (Export to PowerPoint + Embed speaker notes)
-```
-
-> **Note**: Source content conversion is mandatory - tools must be called immediately upon detecting PDF/URL. Template option is a workflow step, not Strategist's responsibility. Image_Generator is a sequential step, images must be collected before entering Executor phase.
-
-### Complete Workflow Diagram
-
-```mermaid
-graph TD
- %% Style Definitions
- classDef role fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
- classDef artifact fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
- classDef tool fill:#e0f2f1,stroke:#00695c,stroke-width:2px;
- classDef userAction fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
- classDef external fill:#eee,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5;
-
- %% Entry Point
- RawDoc([Raw Reference Materials PDF/Word]) --> PDFConvert{PDF Type?}
-
- %% Preparation Stage
- subgraph Preparation [Preparation Stage - Resources Prep]
- PDFConvert -- Native PDF --> PyMuPDF[pdf_to_md.py Local Conversion]:::tool
- PDFConvert -- Scanned/Complex Layout --> Mineru[MinerU Cloud AI Conversion]:::tool
-
- PyMuPDF -- Extract Text & Structure --> MD([Basic Markdown Document]):::artifact
- Mineru -- Extract Text & Structure --> MD
-
- %% Image Processing Flow
- subgraph ImageFlow [Image Resources]
- LocalImgs(Required Image Files) --> ImgFolder[Store in images/ folder]:::userAction
- ImgFolder -- Add image descriptions in MD --> MD
- end
-
- %% Icon Processing Flow
- subgraph IconFlow [Icon Resources]
- Repo[SVG Repo Website]:::external -- Search & Download --> UserIcon[Download Matching Icons]:::userAction
- UserIcon -- Define reference requirements --> IconReq(Icon Reference Notes)
- end
- end
-
- %% Connect to Planning Stage
- MD --> Strategist
- IconReq --> Strategist
-
- %% Planning Stage
- subgraph Planning [Planning Stage - Content & Design]
- Strategist[Role 1 Strategist: Content & Specifications]:::role
-
- %% Interactive Confirmation
- Strategist -.-> Confirm1[Interactive Confirmation: 8 Key Elements]:::userAction
- Confirm1 -- Confirm Scope --> Strategist
-
- %% Notes
- note1>Confirm: Image paths/Icon needs/Style] -.-> Confirm1
-
- Strategist --> SpecDoc([Design Specification & Content Outline]):::artifact
- end
-
- SpecDoc --> CheckImage{AI Generated Images?}
-
- %% Image Generation Stage (conditionally triggered)
- subgraph ImageGenStage [Image Generation Stage - Conditionally Triggered]
- CheckImage -- Yes --> ImageGen[Role 2 Image Generator]:::role
- ImageGen -- Generate Images --> ImagesReady([Images in images/ folder]):::artifact
- end
-
- CheckImage -- No --> SelectStyle
- ImagesReady --> SelectStyle{Select Style}
-
- %% Execution Stage
- subgraph Execution [Execution Stage - SVG Generation]
- SelectStyle -- General Flexible --> ExecGen[Role 3 General Executor]:::role
- SelectStyle -- General Consulting --> ExecCon[Role 4 Consulting Executor]:::role
- SelectStyle -- Top Consulting --> ExecTop[Role 4+ Top Consulting Executor]:::role
-
- ExecGen --> GenerateLoop
- ExecCon --> GenerateLoop
- ExecTop --> GenerateLoop
-
- GenerateLoop[Generate SVG Page by Page]:::userAction
- end
-
- GenerateLoop --> CheckQA{Need Optimization?}
-
- %% Optimization & Output
- subgraph Output [Optimization & Post-processing]
- CheckQA -- Yes --> Optimizer[Role 5 CRAP Optimizer]:::role
- Optimizer --> OptimizedSVG([Optimized SVG]):::artifact
- OptimizedSVG --> CheckQA
-
- CheckQA -- No --> RawOutput[SVG Files svg_output/]:::artifact
-
- RawOutput --> ToolFinal[finalize_svg.py Finalization]:::tool
- ToolFinal -- Embed images and icons --> FinalSVG[Final SVG svg_final/]:::artifact
- FinalSVG --> ToolPPT[svg_to_pptx.py PPTX Conversion]:::tool
- end
-
- ToolPPT --> End([Output: .pptx Presentation]):::artifact
-```
-
-## Roles
-
-> The system includes 7 professional roles: 1 Strategist + 1 Template Designer (optional) + 1 Image Generator (conditionally triggered) + 3 Executor variants + 1 Optimizer
-
-### 1️⃣ Strategist
-
-**Responsibility**: Content analysis and design planning
-**Output**: Design Specification and Content Outline
-
-⚠️ **Important**: The first step in the workflow is **Initial Communication and Scope Confirmation**
-
-**Core Capabilities**:
-
-- **Initial Communication (Eight Confirmations)**: Must complete the following confirmations before analyzing content, providing professional recommendations:
- 1. 📐 **Canvas Format**: Recommend the most suitable format based on usage scenario (PPT/Xiaohongshu/WeChat Moments, etc.)
- 2. 📊 **Page Count**: Suggest reasonable page range based on content volume and complexity
- 3. 🎯 **Target Audience & Scenario**: Pre-judge target audience and usage scenario based on document characteristics
- 4. 🎨 **Design Style**: A) General Flexible B) General Consulting C) Top Consulting (MBB Level), with recommendation rationale
- 5. 🎨 **Color Scheme**: Provide specific HEX values for primary, secondary, and accent colors
- 6. 🔣 **Icon Method**: A) Emoji B) AI Generated C) Built-in Icon Library D) Custom Path
- 7. 🖼️ **Image Usage**: A) No images B) User provided C) AI Generated D) Placeholder reserved
- 8. 📝 **Typography**: Font combination (P1-P5 preset or custom) + body font size baseline (14-20pt)
-- **Intelligent Deconstruction**: Break down and reorganize source documents into clear page sequences
-- **Color Scheme**: Propose complete color scheme (primary, secondary, base tones)
-- **Layout Planning**: Plan page sequences and recommend layout solutions
-- **Typography System**: Define font combinations and size hierarchy
-- **Stylized Output**:
- - General Flexible Style: Focus on visual layout (canvas adaptation, color scheme, typography system)
- - General Consulting Style: Focus on structured presentation (MECE decomposition, KPI dashboards)
- - Top Consulting Style: Focus on professional expression (SCQA framework, Pyramid Principle, data contextualization)
-
-📄 [View Complete Role Definition](./roles/Strategist.md)
-
-### 2️⃣ Template_Designer (Template Designer) - Optional
-
-**Responsibility**: Page template generation
-**Output**: Page template SVG files
-
-**Trigger Condition**: Only called when user selects "B) Generate New Template" in Strategist's template options
-
-**Core Capabilities**:
-
-- Generate 4 core templates based on design specifications (cover, chapter, content, ending)
-- Optional: Generate table of contents template
-- Use placeholder markers for replaceable content
-- Ensure templates follow design specification's colors, fonts, and layout
-- Templates define visual consistency and structural pages, content area maintains maximum flexibility
-
-**Input**: Design Specification and Content Outline
-
-**Output**:
-
-- 4 core template SVG files
-- Optional: Table of contents template
-- Saved to project `templates/` directory
-
-📄 [View Complete Role Definition](./roles/Template_Designer.md)
-
-### 3️⃣ Image_Generator (Image Generator) - Conditionally Triggered
-
-**Responsibility**: AI image generation (conditionally triggered)
-**Output**: Image files + optimized prompts
-
-**Trigger Condition**: Only called when user selects "C) AI Generated" for image method in Strategist's eight confirmations
-
-**Workflow Position**: After Strategist, before Executor (sequential, not parallel)
-
-**Core Capabilities**:
-
-- Analyze "Image Resource List" from design specifications
-- Generate optimized prompts for each image (also serves as image description/alt text)
-- Generate images through AI tools (automatic or manual)
-- Save images to project `images/` directory
-
-**Input**: Design specifications (with Image Resource List)
-
-**Output**:
-
-- Optimized image prompts
-- Generated image files
-- Updated Image Resource List
-
-📄 [View Complete Role Definition](./roles/Image_Generator.md)
-
-### 4️⃣ Executor_General (General Executor)
-
-**Responsibility**: Generate SVG code in general flexible style
-**Output**: Single page SVG code
-
-**Core Capabilities**:
-
-- **Absolute Specification Compliance**: Strictly follow the design specifications confirmed by Strategist
-- **Page-by-Page Generation**: Generate only one page at a time to ensure quality and controllability
-- **Dynamic Adjustment**: Intelligently fine-tune elements while following mandatory dimensions
-- **Iterative Modification**: Support regeneration based on feedback
-- **Technical Requirements**:
- - Canvas size: Auto-adapt based on selected format (PPT: 1280×720, Xiaohongshu: 1242×1660, etc.)
- - viewBox matches canvas size
- - `<foreignObject>` is strictly prohibited
- - Use `<tspan>` for manual line breaks
- - Adjust layout and card sizes based on canvas ratio
-
-📄 [View Complete Role Definition](./roles/Executor_General.md)
-
-### 5️⃣ Executor_Consultant (General Consulting Executor)
-
-**Responsibility**: Generate SVG code in general consulting style
-**Output**: Business-level presentation pages
-
-**Core Capabilities**:
-
-- **Basic Consulting Style**: Clean, clear, data visualization
-- **Data-Driven**: Use charts, timelines and other visualization tools
-- **KPI Display**: Professional dashboards and key metrics presentation
-- **Clear Structure**: Organize content into maximum 5 logical sections
-- **Professional Colors**: Use consulting industry standard colors
-
-📄 [View Complete Role Definition](./roles/Executor_Consultant.md)
-
-### 6️⃣ Executor_Consultant_Top (Top Consulting Executor)
-
-**Responsibility**: Generate SVG code in top consulting style (MBB Level)
-**Output**: Strategic-level presentation pages
-
-**Core Capabilities**:
-
-- **MBB Level Style**: Adopts design styles of top consulting firms like McKinsey, Bain, BCG
-- **5 Core Techniques**:
- 1. **Data Contextualization**: Never present data in isolation, always with comparison reference
- 2. **SCQA Framework**: Situation → Complication → Question → Answer narrative structure
- 3. **Pyramid Principle**: Conclusion first, evidence supports
- 4. **Strategic Use of Color**: Focus attention, reduce cognitive load
- 5. **Chart vs Table Selection**: Choose the best visualization form based on scenario
-- **Professional Colors**: Use McKinsey blue, BCG dark blue and other top consulting colors
-- **Reasonable Layout**: Ensure elements don't overlap, ample white space
-
-📄 [View Complete Role Definition](./roles/Executor_Consultant_Top.md)
-
-### 7️⃣ Optimizer_CRAP (CRAP Optimizer)
-
-**Responsibility**: Optimize design based on CRAP principles
-**Output**: Optimized SVG code (yh\_ prefix)
-
-**Four Core Principles**:
-
-1. **Alignment**:
- - Check and correct element alignment relationships
- - Create powerful invisible visual connection lines
- - Ensure every element has clear alignment relationship with others
-
-2. **Contrast**:
- - Enhance visual hierarchy, highlight key information
- - Increase size, font weight or color differences
- - Create clear visual focus
-
-3. **Repetition**:
- - Unify visual style of similar elements
- - Repeatedly use colors, fonts, rounded corners and other visual elements
- - Create organization and unity
-
-4. **Proximity**:
- - Group related content spatially close together
- - Increase distance between different logical blocks
- - Form clear visual units
-
-📄 [View Complete Role Definition](./roles/Optimizer_CRAP.md)
-
-## Getting Started
-
-### Basic Workflow
-
-1. **Prepare Source Document**
-
- Convert raw reference materials to AI-readable format:
-
- | Step | Description |
- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | 📄 **Document Conversion** | **Prefer** `python3 tools/pdf_to_md.py <PDF_file>` for local conversion (fast, free, privacy-safe). For scanned PDFs, complex multi-column layouts, or math formulas, use [MinerU](https://github.com/opendatalab/MinerU) cloud AI conversion |
- | 🖼️ **Image Resources** | Store required images in the project's `images/` folder and add image descriptions in the Markdown |
- | 🔣 **Icon Resources** | For custom icons, download from [SVG Repo](https://www.svgrepo.com/), or use the built-in 640+ icon library (`templates/icons/`) |
-
- > 💡 **PDF Conversion Strategy**: PyMuPDF first (local, instant), MinerU as fallback (cloud AI). See [Tools Usage Guide](./tools/README.md)
-
-2. **Initial Communication (Eight Confirmations)**
- Conduct scope confirmation with Strategist, who will provide professional recommendations on these eight items:
- 1. **Canvas Format**: PPT/Xiaohongshu/WeChat Moments/Story, etc. (recommend based on usage scenario)
- 2. **Page Count**: Suggest reasonable page count based on content volume analysis
- 3. **Target Audience & Scenario**: Pre-judge based on document characteristics
- 4. **Design Style**: A) General Flexible B) General Consulting C) Top Consulting (MBB Level)
- 5. **Color Scheme**: Primary, secondary, accent colors (provide specific HEX values)
- 6. **Icon Method**: A) Emoji B) AI Generated C) Built-in Icon Library D) Custom Path
- 7. **Image Usage**: A) No images B) User provided C) AI Generated D) Placeholder reserved
- 8. **Typography**: Font combination (P1-P5 preset) + body font size baseline (14-20pt)
-
- 💡 Strategist will not only ask questions but also proactively provide professional recommendations for your reference or confirmation
-
-3. **Get Planning**
- Strategist analyzes content and generates Design Specification and Content Outline, with different focuses based on selected style:
- - General Flexible: Visual layout specifications (canvas adaptation, typography system)
- - General Consulting: Structured layout (MECE decomposition, data visualization)
- - Top Consulting: Professional expression methodology (SCQA, Pyramid Principle, 5 core techniques)
-
-4. **Page-by-Page Generation**
- Use the corresponding Executor role to generate each SVG page
-
-5. **Optimization Polish** (Optional)
- Use Optimizer_CRAP for CRAP principle optimization
-
-6. **Post-processing** (Recommended)
-
- ```bash
- python3 tools/finalize_svg.py <project_path> # Execute all post-processing
- ```
-
-7. **Export for Use**
- ```bash
- # Export to PPTX
- python3 tools/svg_to_pptx.py <project_path> -s final # Use svg_final (recommended)
- python3 tools/svg_to_pptx.py <project_path> # Use svg_output (original version)
- ```
- Or embed SVG files directly into other presentation environments
-
-### Example Dialogue Flow
-
+[Executor] - Two-Phase Generation
+ ├── Visual Construction Phase: Generate all SVG pages consecutively
+ └── Logic Construction Phase: Batch generate speaker notes → notes/
+ ↓
+[Optimizer_CRAP] (Optional)
+ ↓
+[Post-processing] → finalize_svg.py → svg_to_pptx.py (auto-embeds notes)
+ ↓
+Output: SVG + PPTX
```
-User: I have a market analysis report that needs to be made into a presentation
-
-Strategist: Before I start analyzing your content, I need to complete eight confirmations:
-
-1. Canvas Format: [Recommended] PPT 16:9 (1280×720), suitable for business presentation scenarios
-
-2. Page Count: [Recommended] 8-10 pages, ensure each core topic has sufficient display space
-
-3. Target Audience & Scenario: [Recommended] Strategic analysis material for corporate middle and senior management,
- suitable for quarterly/annual strategic meetings
-
-4. Design Style: [Recommended] C) Top Consulting Style (MBB Level),
- reflects data-driven and professional authority
-
-5. Color Scheme: [Recommended]
- - Primary: #005587 (McKinsey Blue) - Professional, trustworthy
- - Secondary: #E8E8E8 (Light Gray) - Background, white space
- - Accent: #FF6B35 (Vibrant Orange) - Data highlights, emphasis
-
-6. Icon Method: [Recommended] C) Built-in Icon Library, professional and clean
-7. Image Usage: [Recommended] A) No images, data reports focus on charts
+> 📖 For detailed workflow, see [Workflow Tutorial](./docs/workflow_tutorial.md) and [Role Definitions](./roles/README.md)
-8. Typography: [Recommended] P1 preset (Microsoft YaHei + Arial), body 18pt baseline
-
-User: I agree with your recommendations
-
-Strategist: [Analyzes content, generates complete design specification and content outline...]
-
-User: Great planning! Please generate page 1: Cover
+---
-Executor_Consultant_Top: [Generates page 1 SVG code...]
+## 🛠️ Common Commands
-User: Please continue to generate page 2
+```bash
+# Initialize project
+python3 tools/project_manager.py init <project_name> --format ppt169
-Executor_Consultant_Top: [Generates page 2 SVG code...]
+# PDF to Markdown
+python3 tools/pdf_to_md.py <PDF_file>
-User: Page 2 is important, please optimize visual effects using CRAP principles
+# Post-process SVG
+python3 tools/finalize_svg.py <project_path>
-Optimizer_CRAP:
-I will analyze page 2 and apply CRAP principles:
-1. Alignment: Ensure all elements strictly align to grid
-2. Contrast: Increase size difference between numbers and labels
-3. Repetition: Unify card styles
-4. Proximity: Group related data more closely
-[Outputs optimized yh_slide_02.svg...]
+# Export PPTX
+python3 tools/svg_to_pptx.py <project_path> -s final
```
-💡 **Tip**: Check the example projects in the `examples/` directory to understand the complete project implementation process and final results.
-
-## Design Styles
-
-### General Flexible Style
-
-- Use Cases: General business presentations, education training, team reports
-- Design Features: Flexible layout, rich colors, easy to customize
-- Content Structure: Clear logical hierarchy and visual guidance
-
-### General Consulting Style
-
-- Use Cases: Business reports, project reports, client presentations
-- Design Features: Clean and clear, data visualization, professional feel
-- Typical Elements: KPI dashboards, data charts, MECE decomposition
-
-### Top Consulting Style (MBB Level)
-
-- Use Cases: Strategic reports, board presentations, high-end client proposals
-- Design Features: Clean and professional, data-driven, emphasizes insights
-- Reference Standards: McKinsey, Bain, BCG and other top consulting firms
-- **5 Core Techniques**: Data contextualization, SCQA framework, Pyramid Principle, strategic use of color, chart vs table selection
-- Typical Elements: Matrix diagrams, timelines, KPI dashboards, waterfall charts, driver trees
-
-## Technical Specifications
-
-### SVG Parameters
-
-- **Canvas Size**: Auto-adapts based on selected format (see [Canvas Format Specifications](./docs/canvas_formats.md))
- - PPT 16:9: 1280×720
- - PPT 4:3: 1024×768
- - Xiaohongshu: 1242×1660
- - WeChat Moments: 1080×1080
- - Story: 1080×1920
- - More formats...
-- **ViewBox**: Matches canvas size
-- **Background**: Defined using `<rect>` element
-- **Text**: `<foreignObject>` disabled, use `<tspan>` for manual line breaks
-- **Fonts**: Use the font scheme specified in the Design Specification (see [Font Selection](./docs/design_guidelines.md#font-selection))
-
-### PPT Compatibility Rules (Must Follow)
+> 📖 For complete tool documentation, see [Tools Usage Guide](./tools/README.md)
-To ensure consistent results after PPT export, transparency must use standard notation:
-
-| ❌ Prohibited | ✅ Correct |
-| ------------------------------ | -------------------------------------------------------------------------- |
-| `fill="rgba(255,255,255,0.1)"` | `fill="#FFFFFF" fill-opacity="0.1"` |
-| `<g opacity="0.2">...</g>` | Set transparency individually for each child element |
-| `<image opacity="0.3"/>` | Add mask layer after image `<rect fill="background-color" opacity="0.7"/>` |
-
-> 📌 **Remember**: PPT doesn't recognize rgba, group opacity, or image opacity
-
-### Layout Specifications
-
-#### General Flexible Style
-
-- **Margins**: Auto-adjust based on canvas ratio (landscape 40-60px, portrait 60-120px)
-- **Card Size**: Dynamically calculated based on canvas height and layout method
-- **Spacing**: 20-60px (adjust based on canvas size)
-
-#### High-End Consulting Style
-
-- Follow consulting industry best practices
-- Emphasize white space and visual breathing room
-- Data charts occupy main visual area
-- Auto-adapt to different canvas ratios
-
-### Color Schemes
-
-#### Consulting Style Primary Colors
-
-- Deloitte Blue: `#0076A8`
-- McKinsey Blue: `#005587`
-- BCG Dark Blue: `#003F6C`
-
-#### General Color Principles
-
-- Provide primary, secondary and base tones
-- Support light/dark themes
-- Use HEX color values
+---
-## Project Structure
+## 📁 Project Structure
```
ppt-master/
-├── README.md # Project documentation
-├── LICENSE # License file
-├── .gitignore # Git ignore rules
-│
-├── roles/ # AI role definitions (Do not test/write examples in this directory)
-│ ├── README.md # Role overview and workflow
-│ ├── Strategist.md # Strategist role definition
-│ ├── Image_Generator.md # Image Generator role definition (conditionally triggered)
-│ ├── Executor_General.md # General Executor role definition
-│ ├── Executor_Consultant.md # General Consulting Executor role definition
-│ ├── Executor_Consultant_Top.md # Top Consulting Executor role definition (MBB Level)
-│ └── Optimizer_CRAP.md # CRAP Optimizer role definition
-│
-├── examples/ # Examples folder (each example in separate directory)
-│ └── <project_name>_<format>_<YYYYMMDD>/
-│ ├── README.md
-│ ├── 设计规范与内容大纲.md / design_specification.md
-│ ├── preview.html (optional)
-│ └── svg_output/
-│
-├── docs/ # Documentation center
-│ ├── canvas_formats.md # Canvas format specifications
-│ ├── design_guidelines.md # Detailed design guide (colors, typography, layout)
-│ ├── svg_image_embedding.md # SVG image embedding guide
-│ ├── workflow_tutorial.md # Workflow tutorial (practical case demonstration)
-│ └── quick_reference.md # Quick reference guide (cheat sheet)
-│
-├── templates/ # Standardized template library
-│ ├── charts/ # Chart templates (13 types: KPI, bar, line, etc.)
-│ │ ├── README.md # Chart template usage instructions
-│ │ ├── preview.html # Online preview all templates
-│ │ └── *.svg # 13 chart template files
-│ └── icons/ # Icon library (640+ vector icons)
-│ └── README.md # Icon library usage instructions
-│
-├── tools/ # Utility tools
-│ ├── README.md # Tools documentation
-│ ├── project_manager.py # Project management tool
-│ ├── svg_quality_checker.py # SVG quality check
-│ ├── batch_validate.py # Batch validation tool
-│ ├── finalize_svg.py # Finalization processing (embed icons + fix image aspect + embed images)
-│ ├── embed_icons.py # Icon embedding tool
-│ ├── embed_images.py # Image embedding tool
-│ ├── fix_image_aspect.py # Image aspect ratio fix tool (prevent stretching in PPT)
-│ ├── flatten_tspan.py # tspan flattening tool
-│ └── svg_to_pptx.py # SVG to PPTX tool (native vector embedding)
-│
-└── projects/ # User project workspace (work in progress)
- └── <your_project_name>_<YYYYMMDD>/
-
-**Important**: All project folders must end with date suffix, format `_YYYYMMDD` (e.g.: `_20251012`)
-
-```
-
-## Best Practices
-
-### Content Preparation
-
-1. **Clear Logical Structure** - Ensure source document has clear sections and key points
-2. **Sufficient Data Preparation** - Provide specific numbers and data support
-3. **Visual Element Suggestions** - Pre-consider chart types and layout needs
-
-### Design Process
-
-1. **Thorough Communication** - Confirm all design parameters with Strategist
- - 💡 Strategist will proactively provide professional recommendations, consider these suggestions carefully
- - 📋 If you have different ideas, discuss and adjust with Strategist's recommendations
-2. **Page-by-Page Verification** - Check results after generating each page
-3. **Timely Optimization** - Use Optimizer_CRAP to improve quality of key pages
-4. **Maintain Consistency** - Ensure unified style across the entire slide deck
-
-### Output Management
-
-1. **File Naming** - Use clear naming rules (e.g.: `01_cover.svg`)
-2. **Version Control** - Save versions of each iteration
-3. **Format Conversion** - Convert to PNG or PDF as needed
-4. **Project Organization** - Place each presentation project in `projects/` directory, including design specifications and SVG output
-
-## More Examples
-
-This repository is an **AI workflow framework**, providing complete role definitions, templates and toolsets.
-
-### 📂 Project Structure
-
-Example projects should be located in the `examples/` directory, using the following structure:
-
-```
-examples/
-└── <project_name>_<format>_<YYYYMMDD>/
- ├── 设计规范与内容大纲.md
- ├── images/ # Image resources
- ├── svg_output/ # Original SVG (with placeholders)
- └── svg_final/ # Final SVG (icons/images embedded)
+├── roles/ # AI role definitions (6 professional roles)
+├── docs/ # Documentation center (tutorials, design guides, format specs)
+├── templates/ # Template library (chart templates + 640+ icons)
+├── tools/ # Toolset (project management, conversion, processing)
+├── examples/ # Example projects (15 complete cases)
+└── projects/ # User project workspace
```
-### 🔍 Preview SVG
-
-```bash
-# Preview with local server
-python3 -m http.server --directory examples/<project>/svg_final 8000
-# Then visit http://localhost:8000
-```
-
-### 🚀 Start Your Project
-
-#### Using Project Management Tool (Recommended)
-
-```bash
-# 1. Initialize new project
-python3 tools/project_manager.py init my_project --format ppt169
-
-# 2. Edit generated design specification file
-# projects/my_project_ppt169_20251116/设计规范与内容大纲.md
-
-# 3. Use AI roles to generate SVG files to svg_output/ directory
-
-# 4. Validate project structure
-python3 tools/project_manager.py validate projects/my_project_ppt169_20251116
-```
-
-#### Manual Project Creation
-
-Reference the example structure, create your own project in the `projects/` directory:
-
-```
-projects/
-└── your_project_name_format_YYYYMMDD/ # Must add format and date suffix
- ├── README.md # Project description
- ├── 设计规范与内容大纲.md # Design specification generated by Strategist
- ├── 来源文档.md # Source document (optional)
- ├── preview.html # Preview page (auto-generated)
- └── svg_output/ # Generated SVG files
- ├── 01_cover.svg
- ├── 02_xxx.svg
- └── ...
-```
-
-**Important Naming Rules**:
-
-- Project folder name format: `{project_name}_{format}_{YYYYMMDD}`
-- format: `ppt169`, `ppt43`, `wechat`, `xiaohongshu`, `story`, etc.
-- Date uses 8-digit format, e.g., `20251116` for November 16, 2025
-- Example: `my_presentation_ppt169_20251116`
-
-For detailed naming conventions, please refer to the examples above
-
-## FAQ
-
-<details>
-<summary><b>Q: How to use the generated SVG files?</b></summary>
-
-A: SVG files can be:
-
-- Opened directly in browser to view
-- Embedded into HTML pages
-- Edited with design tools (e.g., Figma, Adobe Illustrator)
-- Converted to PNG/PDF format for traditional presentation software
+---
-</details>
+## ❓ FAQ
<details>
-<summary><b>Q: What's the difference between the executors?</b></summary>
-
-A:
+<summary><b>Q: How to use generated SVG files?</b></summary>
-- **Executor_General**: For general scenarios, provides flexible layout and rich visual choices
-- **Executor_Consultant**: For general consulting scenarios, clean and clear data visualization
-- **Executor_Consultant_Top**: For top consulting scenarios (MBB Level), uses 5 core expression techniques
+- Open directly in browser to view
+- Export to PowerPoint using `svg_to_pptx.py`
+- Embed in HTML pages or edit with design tools
</details>
<details>
-<summary><b>Q: When is Image_Generator used?</b></summary>
+<summary><b>Q: What's the difference between the three Executors?</b></summary>
-A: Image_Generator is only triggered when you select "C) AI Generated" for the image method during Strategist's eight confirmations. It generates optimized prompts and images before the Executor phase, so Executor can directly reference the generated images.
+- **Executor_General**: General scenarios, flexible layout
+- **Executor_Consultant**: General consulting, data visualization
+- **Executor_Consultant_Top**: Top consulting (MBB level), 5 core techniques
</details>
<details>
<summary><b>Q: Is Optimizer_CRAP required?</b></summary>
-A: No, it's not required. If the SVG generated by Executor already meets your needs, you can skip the optimization step. Optimizer is mainly used to further enhance the visual quality of key pages.
+No. Only use it when you need to optimize the visual effects of key pages.
</details>
-<details>
-<summary><b>Q: Can I customize the color scheme?</b></summary>
-
-A: Yes! When communicating with Strategist, clearly state your brand colors or preferred color scheme, and Strategist will adjust the design specification accordingly.
+> 📖 For more questions, see [Workflow Tutorial](./docs/workflow_tutorial.md#faq)
-</details>
-
-## Contributing Guide
+---
-We welcome contributions of all kinds!
+## 🤝 Contributing
-### How to Contribute
+Contributions are welcome!
1. Fork this repository
-2. Create feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to branch (`git push origin feature/AmazingFeature`)
-5. Open Pull Request
-
-### Contribution Areas
-
-- 🎨 Add new design style templates
-- 📊 Expand chart types and visualization components
-- 📝 Improve documentation and tutorials
-- 🐛 Report bugs and issues
-- 💡 Suggest new features
-- 🌍 Multi-language support
-- 📁 Share your project cases to `examples/` directory
-
-## Roadmap
-
-### ✅ Completed
-
-- [x] Established complete role system and workflow
-- [x] Implemented general and consulting design styles
-- [x] Multi-format canvas support (PPT 16:9/4:3, Xiaohongshu, WeChat Moments, Story and 10+ formats)
-- [x] Project management toolset (initialization, validation, quality check, batch processing)
-- [x] Standardized chart template library (33 chart types)
-- [x] 640+ vector icon library (sourced from SVG Repo)
-- [x] Strategist proactive recommendation feature (upgraded from passive questioning to proactive advisor)
-- [x] **Example project library** (15 projects, 229 SVG pages, covering consulting/general/creative styles)
-- [x] Online example showcase ([Slides Gallery](https://notes.36sjs.com/pages/ppt/slides-library.html))
-
-### 📋 Planned
-
-- [ ] Develop interactive configuration tool
-- [ ] Support animations and interactivity
-- [ ] Web interface development
-- [ ] API interface design
-- [ ] GitHub Actions CI/CD integration
-
-## 🛠️ Toolset
-
-PPT Master provides a complete set of tools to simplify project management and content generation workflows.
-
-### Project Management Tool (`project_manager.py`)
-
-One-stop tool for creating, validating and managing projects:
-
-```bash
-# Initialize new project
-python3 tools/project_manager.py init <project_name> --format ppt169
-
-# Validate project structure
-python3 tools/project_manager.py validate <project_path>
-
-# View project information
-python3 tools/project_manager.py info <project_path>
-```
-
-Supported canvas formats: `ppt169`, `ppt43`, `wechat`, `xiaohongshu`, `moments`, `story`, `banner`, `a4`
-
-### SVG Quality Check Tool (`svg_quality_checker.py`)
-
-Check if SVG files comply with project technical specifications:
-
-```bash
-# Check single file or directory
-python3 tools/svg_quality_checker.py examples/project/svg_output
-
-# Check all projects
-python3 tools/svg_quality_checker.py --all examples
-
-# Specify expected format
-python3 tools/svg_quality_checker.py examples/project --format ppt169
-```
-
-**Check Items**: viewBox attribute, prohibited elements (foreignObject), font usage, width/height consistency, text wrapping method, file size
-
-### Batch Validation Tool (`batch_validate.py`)
-
-Check structural integrity of multiple projects at once:
-
-```bash
-# Validate single directory
-python3 tools/batch_validate.py examples
-
-# Validate all projects
-python3 tools/batch_validate.py --all
-
-# Export report
-python3 tools/batch_validate.py examples --export
-```
-
-### Examples Index Generator (`generate_examples_index.py`)
-
-Automatically scan examples directory and generate README.md index file:
-
-```bash
-python3 tools/generate_examples_index.py
-```
-
-### Post-processing Tool (`finalize_svg.py`)
-
-Unified post-processing entry, performs icon embedding, image aspect ratio fixing, image embedding, text flattening, round corners to Path:
+2. Create your branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
-```bash
-# Run directly, no parameters needed
-python3 tools/finalize_svg.py <project_path>
-```
-
-**Processing Steps**:
-
-1. Embed icons - Replace `<use data-icon="..."/>` with actual icons
-2. Fix image aspect ratio - Prevent image stretching when converting to shapes in PPT ✨
-3. Embed images - Convert external images to Base64
-4. Text flattening - Convert `<tspan>` to independent `<text>`
-5. Round corners to Path - Convert `<rect rx="..."/>` to `<path>`
-
-**Note**: Generation phase should still use `<tspan>` for manual line breaks, post-processing will auto-flatten.
-
-### SVG to PPTX Tool (`svg_to_pptx.py`)
-
-Batch convert SVG files to PowerPoint presentations (native SVG vector embedding):
-
-```bash
-# Use final version (recommended)
-python3 tools/svg_to_pptx.py <project_path> -s final
-
-# Use original version
-python3 tools/svg_to_pptx.py <project_path>
-
-# Specify output file
-python3 tools/svg_to_pptx.py <project_path> -s final -o output.pptx
-```
-
-**Features**: SVG embedded as native vector format, maintains editability, requires PowerPoint 2016+ to view.
-
-### Error Message Helper (`error_helper.py`)
-
-Provides friendly error messages and specific fix suggestions:
-
-```bash
-# View all error types
-python3 tools/error_helper.py
-
-# View solution for specific error
-python3 tools/error_helper.py missing_readme
-```
+**Contribution Areas**: 🎨 Design templates · 📊 Chart components · 📝 Documentation · 🐛 Bug reports · 💡 Feature suggestions
---
-📖 **Detailed Documentation**: [Tools Usage Guide](./tools/README.md)
-
## 📄 License
This project is licensed under the [MIT License](LICENSE).
-You are free to:
-
-- ✅ Commercial use
-- ✅ Modify source code
-- ✅ Distribute and sublicense
-- ✅ Private use
-
-But you must:
-
-- 📋 Retain copyright notice
-- 📋 Retain license notice
-
## 🙏 Acknowledgments
-Thanks to the following open source projects:
-
-- [SVG Repo](https://www.svgrepo.com/) - Beautiful open source icon library (640+ icons included in this project)
-- [Robin Williams](<https://en.wikipedia.org/wiki/Robin_Williams_(author)>) - Creator of CRAP design principles
-- McKinsey, Boston Consulting, Bain and other top consulting firms - Design inspiration sources
+- [SVG Repo](https://www.svgrepo.com/) - Open source icon library
+- [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author)) - CRAP design principles
+- McKinsey, Boston Consulting, Bain - Design inspiration
## 📮 Contact
- **Issue**: [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
- **GitHub**: [@hugohe3](https://github.com/hugohe3)
-- **Project Link**: [https://github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)
+
+---
## 🌟 Star History