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.mdindex 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.mdindex 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) | 速查手册 |