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: 同步文档架构与 AGENTS.md

hugohe35152007de8b1
diff --git a/README.md b/README.md
index 6c6713da..46dae3e1 100644
--- a/README.md
+++ b/README.md
@@ -164,9 +164,14 @@ PPT Master 是一个创新的 AI 辅助视觉内容创作系统,通过多角
### 快速概览
```
-用户输入文档
+用户输入 (PDF/URL/Markdown)
↓
-[Strategist] 策略师 - 内容规划与设计规范
+[源内容转换] 自动触发
+ ├─ PDF → pdf_to_md.py
+ ├─ URL → web_to_md.py / web_to_md.cjs
+ └─ MD → 直接读取
+ ↓
+[Strategist] 策略师 - 八项确认与设计规范
│
├─ 图片方式包含「AI 生成」?
│ │
@@ -181,12 +186,12 @@ PPT Master 是一个创新的 AI 辅助视觉内容创作系统,通过多角
↓
SVG 文件 (svg_output/)
↓
-后处理工具(用户自行调用)
+后处理工具(自动执行)
├── finalize_svg.py → svg_final/(嵌入图标 + 修复图片宽高比 + 嵌入图片 + 文本扁平化 + 圆角转Path)
└── svg_to_pptx.py → output.pptx(导出 PowerPoint + 嵌入演讲者备注)
```
-> **注意**: Image_Generator 是串行环节,图片归集完成后才进入 Executor 阶段。
+> **注意**: 源内容转换是强制触发的,识别到 PDF/URL 后必须立即调用工具。Image_Generator 是串行环节,图片归集完成后才进入 Executor 阶段。
### 完整工作流程图
@@ -304,7 +309,7 @@ graph TD
5. 🎨 **配色方案**: 给出主导色、辅助色、强调色的具体 HEX 色值
6. 🔣 **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
7. 🖼️ **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
- 8. 📝 **字体方案**: 根据内容特征推荐字体组合(标题/正文/强调)
+ 8. 📝 **排版方案**: 字体组合(P1-P5预设或自定义)+ 正文字号基准(14-20pt)
- **智能解构**: 将源文档拆解并重组为清晰的页面序列
- **色彩方案**: 提出完整的配色方案(主导色、辅助色、基础色调)
- **布局规划**: 规划页面序列和推荐布局方案
@@ -445,7 +450,7 @@ graph TD
5. **配色方案**: 主导色、辅助色、强调色(提供具体 HEX 色值)
6. **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
7. **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
- 8. **字体方案**: 根据内容特征推荐字体组合(标题/正文/强调)
+ 8. **排版方案**: 字体组合(P1-P5预设)+ 正文字号基准(14-20pt)
💡 Strategist 不仅会提出问题,还会主动提供专业建议供你参考或确认
@@ -500,6 +505,8 @@ Strategist: 在开始分析您的内容之前,我需要先完成八项确认
7. 图片使用:[建议] A) 不使用图片,数据报告以图表为主
+8. 排版方案:[建议] P1 预设(微软雅黑+Arial),正文 18pt 基准
+
用户: 同意你的建议
Strategist: [分析内容,生成完整的设计规范与内容大纲...]
diff --git a/README_EN.md b/README_EN.md
index f268eed8..4d88ebc0 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -164,15 +164,20 @@ PPT Master is an innovative AI-assisted visual content creation system that achi
### Quick Overview
```
-User Input Document
+User Input (PDF/URL/Markdown)
↓
-[Strategist] - Content Planning & Design Specifications
+[Source Content Conversion] Auto-triggered
+ ├─ PDF → pdf_to_md.py
+ ├─ URL → web_to_md.py / web_to_md.cjs
+ └─ MD → Direct read
↓
+[Strategist] - Eight Confirmations & Design Specifications
+ │
├─ Image Method = "C) AI Generated"?
│ │
│ YES → [Image_Generator] - Generate images to images/
│ │
- │ NO ──────────────────────────────────────┐
+ │ NO ──────────────────────────────────────────┐
│ │
▼ ▼
[Executor_General / Executor_Consultant / Executor_Consultant_Top] - SVG Code Generation
@@ -181,12 +186,12 @@ User Input Document
↓
SVG Files (svg_output/)
↓
-Post-processing Tools (User invoked)
+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**: Image_Generator is a sequential step, only triggered when "AI Generated" images are selected. Images must be collected before entering Executor phase.
+> **Note**: Source content conversion is mandatory - tools must be called immediately upon detecting PDF/URL. Image_Generator is a sequential step, images must be collected before entering Executor phase.
### Complete Workflow Diagram
@@ -304,7 +309,7 @@ graph TD
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. 📝 **Font Scheme**: Recommend font combinations based on content characteristics (Title/Body/Emphasis)
+ 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
@@ -453,7 +458,7 @@ graph TD
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. **Font Scheme**: Recommend font combinations based on content characteristics (Title/Body/Emphasis)
+ 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
@@ -508,6 +513,8 @@ Strategist: Before I start analyzing your content, I need to complete eight conf
7. Image Usage: [Recommended] A) No images, data reports focus on charts
+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...]
diff --git a/docs/quick_reference.md b/docs/quick_reference.md
index a045091c..bd490922 100644
--- a/docs/quick_reference.md
+++ b/docs/quick_reference.md
@@ -33,7 +33,7 @@
- [ ] 配色方案(主导色、辅助色、强调色的 HEX 色值)
- [ ] **图标方式**(A Emoji / B AI生成 / C 内置图标库 / D 自定义路径)
- [ ] **图片使用**(A 不使用 / B 用户提供 / C AI生成 / D 占位符预留)
- - [ ] **字体方案**(根据内容特征推荐字体组合:标题/正文/强调)
+ - [ ] **排版方案**(字体组合 P1-P5 + 正文字号基准 14-20pt)
- [ ] 等待 Strategist 生成设计规范
- [ ] 仔细检查并确认设计规范
- [ ] **创建项目文件夹**:`python3 tools/project_manager.py init <名称> --format <格式>`
diff --git a/docs/workflow_tutorial.md b/docs/workflow_tutorial.md
index 6933ad22..037d5072 100644
--- a/docs/workflow_tutorial.md
+++ b/docs/workflow_tutorial.md
@@ -34,11 +34,22 @@
┌──────────────┐
│ 用户输入 │
- │ 源文档 │
+ │ PDF/URL/MD │
└──────┬───────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
+│ 阶段 0: 源内容转换(强制触发) │
+│ ┌──────────────────────────────────────────────────────────────────────┐ │
+│ │ PDF → python3 tools/pdf_to_md.py <文件路径> │ │
+│ │ URL → python3 tools/web_to_md.py <URL> │ │
+│ │ (微信/高防站点用 node tools/web_to_md.cjs <URL>) │ │
+│ │ MD → 直接读取 │ │
+│ └──────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
│ 阶段 1: 策略规划 │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Strategist (策略师) │ │
@@ -51,7 +62,7 @@
│ │ │ ├── 5. 配色方案建议 (HEX 色值) │ │ │
│ │ │ ├── 6. 图标方式 (Emoji/AI生成/图标库/自定义) │ │ │
│ │ │ ├── 7. 图片使用 (不使用/用户提供/AI生成/占位符) │ │ │
-│ │ │ └── 8. 字体方案 (标题/正文/强调字体组合) │ │ │
+│ │ │ └── 8. 排版方案 (字体组合 + 字号基准 14-20pt) │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
@@ -215,6 +226,7 @@
| 阶段 | 角色 | 关键动作 | 输出物 |
| ----------------- | --------------- | ----------------------------------------- | ---------------------- |
+| **0. 源内容转换** | (自动) | PDF/URL 转 Markdown(强制触发) | 源内容.md |
| **1. 策略规划** | Strategist | 八项确认、内容分析、规范编制 | 《设计规范与内容大纲》 |
| **1.5. 图片生成** | Image_Generator | 生成提示词、AI 生图、归集图片(条件触发) | images/\*.png |
| **2. SVG 生成** | Executor | 逐页生成 SVG 代码 | slide_XX_xxx.svg |
@@ -222,6 +234,7 @@
**注意事项**:
+- 阶段 0 是**强制触发**:识别到 PDF/URL 后必须立即调用转换工具
- 阶段 1 的八项确认是**强制要求**,不可跳过
- 阶段 1.5 仅当图片方式**包含**「C) AI 生成」时触发(如 C、B+C、C+D 等组合),是**串行环节**,图片归集完成后才进入阶段 2
- 阶段 2 根据风格选择使用不同的 Executor
@@ -316,8 +329,8 @@
7. 图片使用:
[建议] A) 不使用图片,数据报告以图表和数据可视化为主。
-8. 字体方案:
- [建议] P1 方案(微软雅黑 + Arial),现代简洁同时保持专业感。
+8. 排版方案:
+ [建议] P1 方案(微软雅黑 + Arial),正文 18pt 基准,现代简洁同时保持专业感。
```
**你的回应:**
diff --git a/roles/README.md b/roles/README.md
index 46015369..e9f2e7af 100644
--- a/roles/README.md
+++ b/roles/README.md
@@ -67,13 +67,13 @@ SVG 文件 (svg_output/)
5. 🎨 **配色方案**: 给出主导色、辅助色、强调色的 HEX 色值
6. 🔣 **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
7. 🖼️ **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
-8. 📝 **字体方案**: 根据内容特征推荐字体组合(标题/正文/强调)
+8. 📝 **排版方案**: 字体组合(P1-P5预设)+ 正文字号基准(14-20pt)
💡 **主动建议**: Strategist 不仅提出问题,还会提供专业建议供用户参考或确认
**核心能力**:
-- **初始沟通**: 完成八项确认(画布格式、页数、受众场景、风格、配色、图标、图片、字体)
+- **初始沟通**: 完成八项确认(画布格式、页数、受众场景、风格、配色、图标、图片、排版)
- 智能解构源文档内容
- 确定设计风格(通用灵活 / 一般咨询 / 顶级咨询)
- 制定完整的色彩方案
@@ -287,7 +287,7 @@ Executor_General 支持多种风格变体,通过 **Strategist 生成的《设
### 基本流程
1. 从 **Strategist** 开始,**首先完成八项确认**
- - 画布格式、页数范围、目标受众与场景、设计风格、配色方案、图标方式、图片使用、字体方案
+ - 画布格式、页数范围、目标受众与场景、设计风格、配色方案、图标方式、图片使用、排版方案
- Strategist 会为每项主动提供专业建议
- 用户可以接受建议或提出调整
2. 让 Strategist 生成完整的设计规范与内容大纲