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

refactor(roles): 精简README为索引,去除AGENTS重复内容

hugohe3990af6a144f3
diff --git a/AGENTS.md b/AGENTS.md
index 1f727dd8..db7b9154 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -225,54 +225,27 @@ python3 tools/svg_to_pptx.py <项目路径> -s final
> ⚠️ **优化提示**:仅在完整初版产出后考虑 Optimizer;若优化过,请重新运行后处理与导出以保持产物一致。
---
-
## 源内容自动处理(强制触发)
-### ⚠️ 强制规则:识别到源内容时必须立即调用工具
-
-当用户消息中出现以下内容时,**必须立即调用对应工具**,不得忽视或仅做文字回复:
-
-| 用户提供的内容 | 识别特征 | 必须调用的工具 | 示例命令 |
-| -------------------------- | ----------------------------------- | --------------------------------- | --------------------------------------- |
-| **PDF 文件** | `.pdf` 扩展名或用户明确提及"PDF" | `pdf_to_md.py` | `python3 tools/pdf_to_md.py <文件路径>` |
-| **网页链接** | `http://` 或 `https://` 开头的 URL | `web_to_md.py` 或 `web_to_md.cjs` | `python3 tools/web_to_md.py <URL>` |
-| **已转换的 Markdown 文件** | `.md` 扩展名,在 `projects/` 目录下 | 直接使用 `view_file` 读取 | `view_file <路径>` |
+> 📖 **详细工作流程**:参见 `.agent/workflows/generate-ppt.md`
-### 执行流程
-
-```
-用户提供 PDF/URL
- │
- ▼
- 识别源内容类型
- │
- ├─ PDF → 立即运行 python3 tools/pdf_to_md.py <路径>
- │
- ├─ URL → 立即运行 python3 tools/web_to_md.py <URL>
- │ (微信/高防站点用 node tools/web_to_md.cjs <URL>)
- │
- └─ Markdown → 使用 view_file 读取内容
- │
- ▼
- 创建项目文件夹(python3 tools/project_manager.py init <名称> --format <格式>)
- │
- ▼
- 询问模板选项(A 使用已有 / B 不使用 / C 生成新模板)
- │
- ▼
- 切换到 Strategist 角色,开始八项确认
-```
+### 强制规则
-### 禁止行为
+当用户提供 PDF 文件或网页链接时,**必须立即调用工具转换**:
-> ❌ **禁止**:用户提供 PDF/URL 后,仅回复"请问您是否需要我使用工具转换?"
-> ❌ **禁止**:用户提供 PDF/URL 后,仅解释工具的用法而不实际调用
-> ❌ **禁止**:等待用户明确说"请转换"才开始处理
+| 源内容 | 工具 | 命令 |
+|--------|------|------|
+| PDF | `pdf_to_md.py` | `python3 tools/pdf_to_md.py <文件>` |
+| 网页 | `web_to_md.py` | `python3 tools/web_to_md.py <URL>` |
+| 微信/高防 | `web_to_md.cjs` | `node tools/web_to_md.cjs <URL>` |
-### 正确行为
+**禁止行为**:
+- ❌ 识别到 PDF/URL 后仅询问"是否需要转换"
+- ❌ 等待用户明确说"请转换"才处理
-> ✅ **正确**:识别到 PDF/URL 后,立即调用工具转换,然后创建项目文件夹
-> ✅ **正确**:工具执行完成后,读取转换结果,询问模板选项,再进入八项确认流程
+**正确行为**:
+- ✅ 识别到 PDF/URL 后立即调用工具
+- ✅ 转换完成后创建项目 → 询问模板选项 → 进入策略师
---
diff --git a/roles/README.md b/roles/README.md
index d02b5b57..8010a25f 100644
--- a/roles/README.md
+++ b/roles/README.md
@@ -1,402 +1,43 @@
# AI 角色定义
-本文件夹包含 PPT Master 系统的核心 AI 角色定义文档。所有角色均支持**多种画布格式**,包括演示文稿、社交媒体、营销物料等。
+本文件夹包含 PPT Master 系统的核心 AI 角色定义文档。
-## 角色概览
+> 📖 **完整工作流程和使用指南**:请参阅 [AGENTS.md](../AGENTS.md)
-| 角色 | 文件 | 主要职责 | 输入 | 输出 | 支持格式 |
-| ------------------ | ---------------------------------------------------------- | ------------------------------ | ------------ | ------------------ | -------- |
-| **策略师** | [Strategist.md](./Strategist.md) | 内容分析与设计规划 | 源文档 | 设计规范与内容大纲 | 所有格式 |
-| **模板设计师** | [Template_Designer.md](./Template_Designer.md) | 页面模板生成(可选) | 设计规范 | 页面模板 SVG | 所有格式 |
-| **图片生成师** | [Image_Generator.md](./Image_Generator.md) | AI 图片生成(条件触发) | 图片资源清单 | 图片文件 + 提示词 | 所有格式 |
-| **通用执行师** | [Executor_General.md](./Executor_General.md) | 生成通用灵活风格 SVG | 设计规范 | SVG 代码 | 所有格式 |
-| **咨询执行师** | [Executor_Consultant.md](./Executor_Consultant.md) | 生成一般咨询风格 SVG | 设计规范 | SVG 代码 | 所有格式 |
-| **顶级咨询执行师** | [Executor_Consultant_Top.md](./Executor_Consultant_Top.md) | 生成顶级咨询风格 SVG(MBB 级) | 设计规范 | SVG 代码 | 所有格式 |
-| **CRAP 优化师** | [Optimizer_CRAP.md](./Optimizer_CRAP.md) | 基于 CRAP 原则优化 | SVG 代码 | 优化后的 SVG | 所有格式 |
+## 角色速查表
-### 支持的画布格式
+| 角色 | 文件 | 职责 | 触发条件 |
+|------|------|------|----------|
+| **策略师** | [Strategist.md](./Strategist.md) | 八项确认 + 设计规范 | 项目启动时(必须) |
+| **模板设计师** | [Template_Designer.md](./Template_Designer.md) | 生成页面模板 | 选择「C) 生成新模板」 |
+| **图片生成师** | [Image_Generator.md](./Image_Generator.md) | AI 图片生成 | 图片方式含「C) AI 生成」 |
+| **通用执行师** | [Executor_General.md](./Executor_General.md) | 通用灵活风格 SVG | 选择「A) 通用灵活」 |
+| **咨询执行师** | [Executor_Consultant.md](./Executor_Consultant.md) | 一般咨询风格 SVG | 选择「B) 一般咨询」 |
+| **顶级咨询执行师** | [Executor_Consultant_Top.md](./Executor_Consultant_Top.md) | MBB 级咨询风格 SVG | 选择「C) 顶级咨询」 |
+| **CRAP 优化师** | [Optimizer_CRAP.md](./Optimizer_CRAP.md) | 视觉质量优化 | 用户要求优化(可选) |
+
+## 支持的画布格式
- **演示文稿**: PPT 16:9 (1280×720)、PPT 4:3 (1024×768)
- **社交媒体**: 小红书 (1242×1660)、朋友圈 (1080×1080)、Story (1080×1920)
-- **营销物料**: 公众号头图 (900×383)、横版海报 (1920×1080)、竖版海报 (1080×1920)
-- **更多格式**: 详见 [画布格式规范](../docs/canvas_formats.md)
-
-## 工作流程
-
-```
-用户输入文档
- ↓
-[源内容转换] pdf_to_md.py / web_to_md.py(如需要)
- ↓
-[创建项目文件夹] project_manager.py init <名称> --format <格式>
- ↓
-[模板选项] 询问用户选择(必须在策略师之前确认)
- │
- ├─ A) 使用已有模板 → 复制模板到项目 templates/ → 进入策略师(参考模板设计)
- ├─ B) 不使用模板 → 进入策略师
- └─ C) 生成新模板 → 进入策略师(大纲完成后调用 Template_Designer)
- ↓
-[策略师 Strategist](八项确认必须完成,不可跳过)
- ↓ 生成《设计规范与内容大纲》
- │
- ├─ 模板选项 = C(生成新模板)?
- │ │
- │ YES → [Template_Designer] 模板设计师
- │ │
- │ NO ─────────────────────────────────┤
- │ │
- ├─ 图片方式包含「C) AI 生成」? │
- │ │ │
- │ YES → [Image_Generator] 图片生成师 │
- │ ↓ 生成图片到 images/ │
- │ │ │
- │ NO ─────────────────────────────────┤
- │ │
- ▼ ▼
-[Executor] 执行师(根据模板选项决定是否遵循模板)
- ↓ 逐页生成SVG代码 → svg_output/
- ↓
-后处理工具(默认由 AI 自动执行,必要时可手动调用)
- ├── finalize_svg.py → svg_final/ (嵌入图标 + 修复图片宽高比 + 嵌入图片 + 文本扁平化 + 圆角转Path)
- └── svg_to_pptx.py → output.pptx (导出 PowerPoint)
- ↓
-[Optimizer_CRAP] 优化师 (可选,仅在完整初版后不满意时使用)
- ↓ CRAP原则优化(优化后需重新运行后处理与导出)
-```
-
-> **注意**:
->
-> - 模板阶段是可选的,用户可选择使用已有模板、生成新模板或不使用模板
-> - Image_Generator 是串行环节,仅当图片方式**包含**「AI 生成」时触发,图片归集完成后才进入 Executor 阶段
-
-## 角色详解
-
-### 1️⃣ Strategist (策略师)
-
-**何时使用**: 项目开始时
-
-**⚠️ 重要提醒**:
-在使用 Strategist 角色时,**务必首先完成八项确认**。这是工作流程的首要步骤,必须在内容分析之前完成:
-
-1. 📐 **画布格式**: 根据使用场景推荐最适合的画布格式(PPT/小红书/朋友圈等)
-2. 📊 **页数范围**: 根据内容量建议合理的页数范围
-3. 🎯 **目标受众与场景**: 基于文档特征判断目标受众和使用场景
-4. 🎨 **设计风格**: 推荐最适合的设计风格(A 通用灵活 / B 一般咨询 / C 顶级咨询)
-5. 🎨 **配色方案**: 给出主导色、辅助色、强调色的 HEX 色值
-6. 🔣 **图标方式**: A) Emoji B) AI生成 C) 内置图标库 D) 自定义路径
-7. 🖼️ **图片使用**: A) 不使用 B) 用户提供 C) AI生成 D) 占位符预留
-8. 📝 **排版方案**: 字体组合(P1-P5预设)+ 正文字号基准(18-24px)
-
-💡 **主动建议**: Strategist 不仅提出问题,还会提供专业建议供用户参考或确认
-
-**核心能力**:
-
-- **初始沟通**: 完成八项确认(画布格式、页数、受众场景、风格、配色、图标、图片、排版)
-- 智能解构源文档内容
-- 确定设计风格(通用灵活 / 一般咨询 / 顶级咨询)
-- 制定完整的色彩方案
-- 规划页面序列和布局
-- 定义排版体系
-
-**关键输出**: 《演示文稿设计规范与内容大纲》
-
-📄 [查看完整定义](./Strategist.md)
-
----
-
-### 1️⃣+ Template_Designer (模板设计师)
-
-**何时使用**: 用户选择「B) 生成新模板」时
-
-**触发条件**: 可选角色,仅当用户需要生成新模板时调用
-
-**核心能力**:
-
-- 根据设计规范生成 4 个核心模板(封面、章节页、内容页、结束页)
-- 可选生成目录页模板
-- 使用占位符标记可替换内容
-- 确保模板遵循设计规范的配色、字体、布局
-
-**输入**: 《设计规范与内容大纲》
-
-**输出**:
-
-- 4 个核心模板 SVG 文件
-- 可选:目录页模板
-- 保存到项目 `templates/` 目录
-
-📄 [查看完整定义](./Template_Designer.md)
-
----
-
-### 1️⃣++ Image_Generator (图片生成师)
-
-**何时使用**: Strategist 初次沟通中用户选择的图片方式**包含**「C) AI 生成」时(如 C、B+C、C+D)
-
-**触发条件**: 仅当需要 AI 生成图片时调用,是 Strategist 和 Executor 之间的**串行环节**
-
-**核心能力**:
-
-- 分析「图片资源清单」中的待生成图片
-- 为每张图片生成优化的提示词
-- 提示词同时作为图片描述/alt 文本
-- 通过 AI 工具生成图片(自动或手动)
-- 将图片保存到 `项目/images/` 目录
-
-**输入**: 设计规范(含图片资源清单)
-
-**输出**:
-
-- 优化后的图片提示词
-- 生成的图片文件
-- 更新后的图片资源清单
-
-**工作流位置**:
-
-```
-Strategist → Image_Generator → Executor
- ↑ ↑
- (本角色) (图片已就绪)
-```
-
-📄 [查看完整定义](./Image_Generator.md)
-
----
-
-### 2️⃣ Executor_General (通用执行师)
-
-**何时使用**: 采用通用灵活风格时
-
-**核心能力**:
-
-- 严格遵循 Strategist 的设计规范
-- 逐页生成 SVG 代码
-- 动态调整视觉平衡
-- 支持迭代修改
-
-**技术特点**:
-
-- 画布尺寸: 根据已选画布格式自动适配(详见 `docs/canvas_formats.md`)
-- 使用 `<tspan>` 手动换行
-- 强制卡片高度规则
-- **禁止**: `clipPath`, `mask`, `<style>`, `class`, `id`, 外部 CSS, `<foreignObject>`, `<symbol>+<use>`, `textPath`, `@font-face`, `<animate*>` / `<set>`, `<script>` / 事件属性, `marker` / `marker-end`, `<iframe>`
-
-📄 [查看完整定义](./Executor_General.md)
-
----
-
-### 3️⃣ Executor_Consultant (一般咨询执行师)
-
-**何时使用**: 采用一般咨询风格时
-
-**核心能力**:
-
-- 基础咨询风格的数据可视化设计
-- KPI 仪表盘和图表优化
-- 专业配色方案应用
-
-**设计特点**:
-
-- 简洁、清晰、数据可视化
-- 使用图表呈现关键信息
-- 融入行业标准的设计元素
-- **禁止**: `clipPath`, `mask`, `<style>`, `class`, `id`, 外部 CSS, `<foreignObject>`, `<symbol>+<use>`, `textPath`, `@font-face`, `<animate*>` / `<set>`, `<script>` / 事件属性, `marker` / `marker-end`, `<iframe>`
-
-📄 [查看完整定义](./Executor_Consultant.md)
-
----
-
-### 3️⃣+ Executor_Consultant_Top (顶级咨询执行师)
-
-**何时使用**: 采用顶级咨询风格(MBB 级)时
+- **营销物料**: 公众号头图 (900×383)、横版/竖版海报
-**核心能力**:
+详见 [画布格式规范](../docs/canvas_formats.md)
-- 采用麦肯锡、贝恩、BCG 等顶尖咨询公司风格
-- **5 大核心表达技巧**:
- 1. 数据情境化(永不孤立呈现)
- 2. SCQA 框架(叙事结构)
- 3. 金字塔原则(结论先行)
- 4. 颜色的战略性使用
- 5. 图表 vs 表格选择矩阵
+## 执行师选择速查
-**设计特点**:
-
-- 简洁、高端、数据驱动
-- 每个数据点都有对比参照
-- 结论先行,核心信息在标题位置
-- 配色服务于信息传达
-- **禁止**: `clipPath`, `mask`, `<style>`, `class`, `id`, 外部 CSS, `<foreignObject>`, `<symbol>+<use>`, `textPath`, `@font-face`, `<animate*>` / `<set>`, `<script>` / 事件属性, `marker` / `marker-end`, `<iframe>`
-
-📄 [查看完整定义](./Executor_Consultant_Top.md)
-
----
-
-### 4️⃣ Optimizer_CRAP (CRAP 优化师)
-
-**何时使用**: 需要进一步优化视觉质量时
-
-**核心能力**:
-
-- 基于 CRAP 四大设计原则分析和优化
-- 诊断视觉问题
-- 重构 SVG 代码
-- 提升专业度和清晰度
-- **禁止**: `clipPath`, `mask`, `<style>`, `class`, `id`, 外部 CSS, `<foreignObject>`, `<symbol>+<use>`, `textPath`, `@font-face`, `<animate*>` / `<set>`, `<script>` / 事件属性, `marker` / `marker-end`, `<iframe>`
-
-**四大原则**:
-
-1. **Contrast (对比)** - 创造视觉层次
-2. **Repetition (重复)** - 统一视觉风格
-3. **Alignment (对齐)** - 建立视觉连接
-4. **Proximity (亲密性)** - 组织信息关系
-
-📄 [查看完整定义](./Optimizer_CRAP.md)
-
----
-
-## 执行师角色选择指南
-
-根据 PPT 类型和使用场景,快速选择合适的执行师角色:
-
-### 按 PPT 类型选择
-
-| PPT 类型 | 推荐角色 | 说明 |
-| --------------------- | ---------------------------- | ---------------------------------- |
-| **商业咨询报告** | Executor_Consultant_Top | MBB 级风格,数据情境化,金字塔原则 |
-| **财务分析/数据报告** | Executor_Consultant_Top | 专业图表,严谨配色,结论先行 |
-| **工作进展汇报** | Executor_Consultant | 简洁清晰,数据可视化为主 |
-| **政府工作报告** | Executor_Consultant | 数据导向,逻辑层次分明 |
-| **招商/文旅推介** | Executor_General(图文风格) | 全幅大图 + 渐变蒙版 + 文字叠加 |
-| **企业品牌宣传** | Executor_General(图文风格) | 视觉冲击力强,图片为主角 |
-| **产品发布/发布会** | Executor_General | 灵活布局,支持多种视觉风格 |
-| **培训课件/教程** | Executor_General | 结构清晰,可搭配图表和图片 |
-| **内部团队分享** | Executor_General | 快速生成,风格灵活 |
-
-### 三个执行师核心特点对比
-
-| 特点 | Executor_General | Executor_Consultant | Executor_Consultant_Top |
-| ------------ | ------------------ | ------------------- | ----------------------- |
-| **定位** | 通用灵活 | 一般咨询 | 顶级咨询(MBB 级) |
-| **视觉风格** | 视觉驱动,图文并重 | 数据驱动,简洁专业 | 数据驱动,高端克制 |
-| **图片使用** | 可大量使用 | 以图表为主 | 以图表为主 |
-| **典型布局** | 全幅大图/自由布局 | KPI 仪表盘/双栏对比 | 金字塔结构/MECE 分解 |
-| **适合场景** | 宣传、展示、培训 | 汇报、分析、提案 | 战略、董事会、高管汇报 |
-
-### Executor_General 风格变体
-
-Executor_General 支持多种风格变体,通过 **Strategist 生成的《设计规范》** 来控制:
-
-#### 1️⃣ 图文结合风格
-
-适用于视觉冲击力为主的宣传展示类 PPT。
-
-| 设计要素 | 说明 |
-| -------------- | -------------------------------- |
-| **全幅背景图** | 铺满画布,作为视觉主体 |
-| **渐变蒙版** | 左侧/底部/整体暗化,确保文字可读 |
-| **文字叠加** | 在蒙版保护区域内布局标题和正文 |
-| **高对比度** | 文字与背景对比度 ≥ 4.5:1 |
-
-**典型应用**:文旅推介、招商宣传、企业形象、活动海报
-
-#### 2️⃣ 极简演讲风格(Keynote 风)
-
-适用于演讲型、产品发布类 PPT,借鉴 Apple / TED 风格。
-
-| 设计要素 | 说明 |
-| ------------ | ---------------------------- |
-| **大留白** | 页面留白 ≥ 50%,让内容"呼吸" |
-| **单点聚焦** | 每页只传达一个核心信息 |
-| **极简配色** | 黑/白/灰 + 1 个强调色 |
-| **超大标题** | 标题字号 72px+,正文精简或无 |
-
-**典型应用**:产品发布、演讲型 PPT、TED 风格分享
-
-#### 3️⃣ 创意设计风格
-
-适用于需要打破常规、展现设计感的场景。
-
-| 设计要素 | 说明 |
-| -------------- | ------------------------------ |
-| **非对称布局** | 打破网格,使用斜线、不规则形状 |
-| **大胆配色** | 高饱和度、渐变色、撞色组合 |
-| **装饰元素** | 几何图形、线条、动态感元素 |
-| **艺术字体** | 手写体、展示型字体 |
-
-**典型应用**:广告提案、设计作品集、创意展示
-
-> 💡 **提示**:风格变体由 Strategist 在《设计规范》中定义,Executor_General 按规范执行。无需切换角色。
-
----
-
-## 使用建议
-
-### 基本流程
-
-1. 从 **Strategist** 开始,**首先完成八项确认**
- - 画布格式、页数范围、目标受众与场景、设计风格、配色方案、图标方式、图片使用、排版方案
- - Strategist 会为每项主动提供专业建议
- - 用户可以接受建议或提出调整
-2. 让 Strategist 生成完整的设计规范与内容大纲
-3. **如果图片方式包含「C) AI 生成」**(如 C、B+C、C+D),调用 **Image_Generator** 完成图片生成
- - 图片归集到 `images/` 目录后,再进入下一步
-4. 根据确认的风格选择 **Executor_General** / **Executor_Consultant** / **Executor_Consultant_Top**
-5. 逐页生成 SVG
-6. (可选)使用 **Optimizer_CRAP** 优化关键页面
-
-### 最佳实践
-
-- ⭐ **首要步骤**: 使用 Strategist 时,必须先完成八项确认
-- 💡 **接受建议**: Strategist 会基于内容分析提供专业建议,认真考虑这些建议
-- ✅ 充分与 Strategist 沟通,确保规范完整
-- ✅ 每生成一页都验证效果
-- ✅ 保持所有页面风格统一
-- ✅ 关键页面使用 Optimizer 提升质量
-- ✅ 保存规范文档供后续参考
-
-### 常见场景
-
-**场景 1: 董事会/战略报告**
-→ Strategist (选 C 顶级咨询风格) → Executor_Consultant_Top → Optimizer_CRAP
-
-**场景 2: 商务报告/项目汇报**
-→ Strategist (选 B 一般咨询风格) → Executor_Consultant
-
-**场景 3: 团队分享/培训材料**
-→ Strategist (选 A 通用风格) → Executor_General
-
-**场景 4: 快速迭代**
-→ Strategist → Executor → 修改 → Executor (重新生成)
-
-**场景 5: 需要 AI 生成图片的演示**
-→ Strategist (图片方式包含 C) → **Image_Generator** → Executor → Optimizer_CRAP
-
-## 扩展与定制
-
-### 自定义角色
-
-如果需要特定行业的风格(如科技、金融、教育),可以基于现有角色创建变体。
-
-### 角色组合
-
-可以混合使用不同风格的 Executor,例如封面使用咨询风格,内容页使用通用风格。
+| PPT 类型 | 推荐角色 |
+|----------|----------|
+| 商业咨询/财务分析 | Executor_Consultant_Top |
+| 工作汇报/政府报告 | Executor_Consultant |
+| 招商推介/品牌宣传 | Executor_General(图文风格) |
+| 培训课件/团队分享 | Executor_General |
## 相关文档
-- [主 README](../README.md) - 项目整体介绍
-- [设计指南](../docs/design_guidelines.md) - 详细设计规范
-- [工作流教程](../docs/workflow_tutorial.md) - 实战案例教程
-- [快速参考](../docs/quick_reference.md) - 速查手册
-
-## 反馈与改进
-
-如果你在使用这些角色时有任何建议或发现问题,欢迎:
-
-- 提交 Issue
-- 发起 Discussion
-- 提交 Pull Request
-
----
-
-让 AI 角色帮你创造专业的演示文稿!✨
+| 文档 | 说明 |
+|------|------|
+| [AGENTS.md](../AGENTS.md) | 完整工作流程、角色切换协议、技术约束 |
+| [设计指南](../docs/design_guidelines.md) | 配色、字体、布局详细规范 |
+| [工作流教程](../docs/workflow_tutorial.md) | 实战案例 |
+| [快速参考](../docs/quick_reference.md) | 速查手册 |