SlideFlow - 高质量自动化PPT生成系统

English | 简体中文

SlideFlow 是一个由 LangGraph 工作流驱动的自动化 PPT 生成系统。基于用户提供的主题，它执行深度网络搜索以收集实时内容，结合预定义的 HTML 模板，最终生成具有可编辑元素的视觉表达力强的 PPTX 文件。

🚀 核心功能

• LangGraph 工作流编排: 使用状态机模式管理 PPT 生成的各个阶段（大纲生成、深度搜索、图像检索、HTML 渲染、PDF 合成和 PPT 转换）。
• 深度网络搜索: 不仅生成大纲，还对每个章节进行深度搜索，确保内容丰富且最新。
• 高保真可编辑 PPTX:
  • 可编辑文本: 生成的 PPT 中的文本是实际的文本框，允许直接修改字体、大小和内容。
  • 可编辑图像: 所有图像（包括插图和背景）都是独立的图像形状，可以移动、缩放和替换。
  • 矢量化图标处理: 自动识别 PDF/HTML 中的图标字体（如 MaterialIcons），并将其提取为高分辨率透明图像，确保样式与网页版本完全匹配。
• 多模板支持（少量样本）: 通过 few_shot 目录快速扩展设计风格。
• 实时日志与预览流: 支持通过 Flask Stream 实时输出 LLM 提示、节点日志和HTML 幻灯片预览，在生成过程中提供即时视觉反馈。
• 即时任务控制: 包含“停止”按钮，可以立即停止后端生成过程，防止不必要的资源消耗。
• 动态资产收集: 在搜索过程中实时显示高清图像，并内置错误处理机制以应对断链问题。
• 响应式仪表板 UI: 重新设计的 12 列网格布局，优先展示生成内容和预览，并带有固定日志控制台以便持续监控。

🎨 前端特性与交互

该系统采用现代响应式仪表板设计，通过 SSE（服务器发送事件）与后端实时同步，提供无缝用户体验：

• 可视化旅程时间线: 从“初始化”到“最终导出”的 7 个核心阶段的实时跟踪。支持并行阶段可视化，清晰指示哪些任务正在并行运行。
• 章节级并行可视化: 对并行章节生成和细粒度幻灯片级别的实时进度监控（图像搜索和 HTML 生成）。
• 实时幻灯片预览: 集成缩放 Iframe 预览系统，允许用户在生成过程中浏览生成的 HTML 幻灯片。
• 智能资产画廊: 按幻灯片分组显示检索到的高清图像，提供即时的视觉方向反馈。
• 任务持久性和恢复: 使用 localStorage 维护会话状态。即使页面刷新或意外关闭后，系统也能自动恢复进度和日志。
• 动态下载管理: 完成后生成指向后端绝对路径的安全下载链接，根据主题匹配提供智能回退机制，确保可靠的文件访问。
• 实时技术日志: 右侧的固定控制台流式传输 LLM 提示和系统日志，使生成过程完全透明。

🏗️ 架构设计

系统分为几个核心模块：

1. 工作流编排 (core/ppt_graph.py)

使用 LangGraph 定义六个核心节点：

• search_outline: 生成初始大纲。
• chapter_content: 对章节进行深度搜索并生成详细页面内容。
• page_generation: 协调每个页面的并行图像搜索和 HTML 生成。- pdf_synthesis: 使用 Playwright 将 HTML 转换为高精度 PDF。
• html_to_pptx: 直接将网页元素转换为最终的 PPTX。

2. HTML 到 PPTX 的转换 (core/utils/html_to_ppt.py)

这是核心技术亮点之一，实现了：

• 元素提取：区分背景、图像和文本块。
• 图标合并：解决 PDF/HTML 中图标字符分割的问题。
• 背景擦除：在生成背景图像时自动擦除文本和前景图像，以防止 PPT 中出现重影。
• 字体匹配：自动将网页字体映射到适当的本地字体（例如 Noto Sans SC）。

3. 服务器端 (main.py)

基于 Flask 的 API 服务支持：

• generate_full_ppt_stream: 流式生成接口。
• 动态模板加载。
• 统一的任务文件夹管理。

4. 前端交互层 (web/static/js/app.js)

前端使用纯 JavaScript 构建，以实现最大性能并消除构建步骤的开销。核心技术包括：

• SSE 通信：使用 EventSource 进行单向流式传输，从前端接收实时进度更新、图像 URL 和 HTML 内容。
• 状态机同步：维护一个客户端状态机，该状态机镜像后端 LangGraph 节点，确保 UI 时间线与执行完全同步。
• 动态 DOM 渲染：利用 Tailwind CSS 高效地更新 UI，为大规模并行生成任务提供实时反馈。
• 响应式预览：使用 CSS Transform Scale 提供跨各种屏幕分辨率的完美缩放幻灯片预览。

🔌 MCP 模式指南

SlideFlow 支持通过 模型上下文协议 (MCP) 将其强大的 PPT 生成能力暴露给任何启用了 MCP 的代理（如 Claude Desktop）。

1. 配置 MCP 服务器

在您的代理配置文件（例如 claude_desktop_config.json）中添加以下内容：

{

  "mcpServers": {

    "slideflow": {

      "command": "python",

      "args": ["/absolute/path/to/SlideFlow/mcp_server.py"]

    }

  }

}

2. 推荐的代理提示

为了获得最佳效果，请使用以下系统提示来配置您的代理：

你是一个 PPT 编排器。你的目标是使用 slideflow 工具创建结构化、深入且专业的 PPT。

1. 结构：必须包括封面、目录、章节幻灯片、每个章节的多个内容幻灯片以及结束幻灯片。
2. 深度：每章至少生成 2-3 张详细的内容幻灯片，以确保专业价值。
3. 交付：合成完成后，你必须向用户提供 PDF 和 PPTX 文件的 Markdown 下载链接。

🛠️ 安装与运行

1. 环境设置

确保已安装 Python 3.10 或更高版本。

# Clone the repository (if not already done)

git clone <repository-url>

cd SlideFlow



# Install dependencies

pip install -r requirements.txt



# Install Playwright browser cores

playwright install chromium

2. 配置 API 密钥

系统支持两种操作模式，具有不同的配置要求：

• MCP 模式（模型上下文协议）：作为工具暴露给外部代理（例如 Claude Desktop）。
  • 仅需嵌入配置：用于 search_vector_db 和 RAG 工具。
  • 无需 LLM 配置：代理使用客户端配置的 LLM 进行推理和规划。
• Web 应用程序模式：使用提供的 Web 界面生成 PPT。
  • 需要 LLM 和嵌入配置：后端工作流程调用 LLM 生成内容。

根据 config/config.json.example 创建 config/config.json：

cp config/config.json.example config/config.json

然后编辑 config/config.json：

{

    "emb_api_key": "YOUR_EMBEDDING_API_KEY",

    "emb_base_url": "YOUR_EMBEDDING_BASE_URL",

    "embedding_model": "YOUR_EMBEDDING_MODEL_ID",



    "api_key": "YOUR_LLM_API_KEY (Web App Only)",

    "base_url": "YOUR_LLM_BASE_URL (Web App Only)",

    "model": "YOUR_LLM_MODEL_ID (Web App Only)"

}

注意：config/config.json 包含敏感信息，并通过 .gitignore 被 Git 忽略。

3. 启动服务

# Start Web Service (Default port 5001)
python main.py

# Start MCP Service (Model Context Protocol)
python mcp_server.py

原子工具（MCP）

通过 mcp_server.py 暴露的原子功能可以直接被 LLMs（例如 Claude Desktop）调用。这些工具设计为无状态和原子性的，允许外部代理编排工作流程。

可用工具：

1. list_available_templates() -> List[str]* 获取所有可用PPT样式模板的列表（例如，company_report、junior_math）。

2. get_template_reference(template_name, page_type) -> str

   • 获取特定模板中指定页面类型的HTML/CSS结构参考。

3. get_generation_guidelines(page_type) -> str

   • 获取不同PPT页面类型的写作标准和系统提示建议。

4. initialize_task_workspace(task_id: str) -> str

   • 为新的PPT任务创建一个独立的工作空间目录，并返回绝对路径。

5. search_images(query: str, count: int = 5) -> List[Dict]

   • 搜索高清背景图片并返回优化后的幻灯片URL和元数据。

6. save_html_to_workspace(html_content, file_name, task_id) -> str

   • 将代理生成的幻灯片HTML代码保存到任务工作空间中。

7. list_workspace_files(task_id: str) -> List[str]

   • 列出当前工作空间中所有已保存的HTML文件，以便跟踪进度。

8. synthesize_final_documents(task_id: str) -> Dict[str, str]

   • 一键将工作空间中的所有HTML文件编译成最终的PDF和PPTX文档。

9. read_pdf_text(pdf_path: str) -> str

   • 从本地PDF中提取原始文本，用于RAG上下文注入。

10. search_vector_db(query: str, pdf_paths: List[str] = None, top_k: int = 5) -> List[Dict]

    • 对PDF内容进行语义搜索，并支持即时索引。

工作流程阶段（与核心图对齐）：

1. [设置]：代理调用initialize_task_workspace(task_id)来创建项目目录。
2. [研究]：代理使用search_web(query)或search_vector_db(query)来收集事实数据。
3. [规划]：代理调用get_generation_guidelines("outline")并使用收集的数据生成结构化的JSON大纲。
4. [内容]：对于大纲中的每一章，代理调用get_generation_guidelines("chapter_content")将大纲扩展为详细的幻灯片内容。
5. [设计]：
   • 代理通过list_available_templates()选择一种样式。
   • 对于每张幻灯片，代理调用get_template_reference(template, page_type)获取HTML结构。
   • 代理调用search_images(keywords)获取视觉背景。
   • 代理生成最终的HTML并调用save_html_to_workspace(html, filename, task_id)。
6. [合成]：代理调用synchronize_final_documents(task_id)来编译PPTX。

推荐的代理提示

"你是一名专业的PPT协调员。你的任务是自主管理高质量演示文稿的端到端生命周期，反映结构化数据到设计的工作流程。

你的操作指南：

1. 阶段1：发现与设置：初始化任务工作空间。如果主题广泛，请使用研究工具（search_web、search_vector_db）来收集深入的上下文。
2. 阶段2：结构规划：检索“大纲”指南。结合你的研究创建一个逻辑性的、JSON格式的大纲（章节和摘要）。这是你的蓝图。
3. 阶段3：内容扩展：对于蓝图中的每一章，检索“章节内容”指南。将简短的摘要扩展为详细的要点和叙述流程。
4. 阶段4：视觉执行：
   • 选择与主题专业性相匹配的模板。
   • 完整结构要求：专业的PPT必须包括：封面 -> 目录 -> 章节页 -> 每章多个内容页 -> 下一章 -> ... -> 结束。
   • 深度内容生成：对于每个章节，至少生成2-3张详细的内容幻灯片，以确保深度和价值。
   • 对于每张计划中的幻灯片，获取HTML参考并找到高清背景图片。
   • 通过将扩展的内容和图片注入模板结构来生成最终的HTML。> * 重要：保存幻灯片时使用数字前缀（例如，00_cover.html，01_toc.html）以保持顺序。
5. 阶段5：合成与交付：一旦所有幻灯片都保存完毕，触发最终合成以生成PPTX和PDF文档。
   • 重要：成功合成后，您将收到pdf_link和pptx_link。
   • 必须：您必须直接向用户提供这些可点击的Markdown链接（例如，[下载PDF预览](file:///path/to/pdf) 和 [下载PPTX源文件](file:///path/to/pptx)）。

在最终合成之前，请始终使用list_workspace_files验证您的进度。您可以完全控制内容，但为了技术一致性，您必须遵循这一逻辑流程。

启动后，通过以下地址访问服务：http://localhost:5001

📂 项目结构

├── assets/

│   ├── templates/      # PPT template library (HTML/CSS), supports extensions

│   └── prompts/        # LLM prompts for each workflow node

├── core/

│   ├── nodes/          # LangGraph workflow node implementations

│   ├── utils/          # Core utility functions (PDF, PPT, Vector Search, etc.)

│   ├── ppt_graph.py    # LangGraph workflow definition logic

│   └── state.py        # State management and AsyncOpenAI client

├── routes/             # Flask blueprints for API routes

├── web/

│   ├── static/         # Frontend static assets (CSS, JS)

│   └── templates/      # Frontend HTML templates

├── tests/              # Unit and integration tests

├── config/

│   └── config.json     # API configuration

├── output/             # Generated PPT/PDF files

├── uploads/            # Temporary storage for uploaded PDFs

├── main.py             # Flask API entry point

├── mcp_server.py       # MCP service entry point (atomic tools)

└── requirements.txt    # Python dependencies list

🌍 多语言支持

前端支持中文和英文切换。点击右上角的语言切换按钮即可无缝切换。生成过程中的提示也会根据所选语言进行调整。

🎨 视觉增强逻辑

• 宽高比适应：智能选择基于搜索到的图片比例的HTML布局，以避免拉伸。
• 非重叠布局：优化后的提示确保文本和插图合理布局且不重叠。
• 高分辨率图标提取：以6倍比例渲染图标，确保即使在PPT中放大后仍保持清晰。