SlideForage-人工智能演示生成系统
智能全栈平台，使用具有模型上下文协议（MCP）集成的代理架构，从自然语言提示中自主创建专业PowerPoint演示文稿。
状态： 生产就绪| 版本： 1.0.0 | 更新： 2026年4月
______________________________________________________________________
什么是SlideForage？
SlideForage是一个完整的AI驱动的演示文稿生成系统，可以将简单的文本提示转换为完全格式化、样式化的PowerPoint演示文稿。该系统智能地规划、构建和交付演示文稿，无需人工干预。
核心思想
Your Prompt: "Create a 5-slide presentation on machine learning"
↓
[Intelligent Agent]
↓
(Plans structure, searches web,
builds slides, applies theme)
↓
Output: presentation_20240405_123045.pptx
(Ready to download/edit)是什么让它与众不同
- 🧠 智能规划 -Agent在执行之前计划整个演示结构
- 🌐 实时Web内容 -集成网络搜索，为每张幻灯片提供最新的相关信息
- 🔧 多个MCP服务器 -4台专用服务器和16个工具处理不同的方面
- 💪 稳健的错误处理 -如果任何服务出现故障，它会优雅地降级，但仍会提供部分演示
- 🔐 安全认证 -基于JWT的用户身份验证与会话管理
- 🎨 专业造型 -内置主题（默认，海洋，森林，日落，午夜）
______________________________________________________________________
🚀 快速演示
1.用户请求
User Input: "Create a 5-slide presentation on climate change"2.代理计划（1-2秒）
Agent analyzes prompt and generates plan:
Slide 1: Introduction to Climate Change
Slide 2: Causes & Greenhouse Gases
Slide 3: Global Effects & Impacts
Slide 4: Solutions & Mitigation Strategies
Slide 5: Individual & Collective Action3.演示楼（3-5秒）
Agent executes 5-phase pipeline:
✓ Phase 1: PLAN structure
✓ Phase 2: CREATE PowerPoint file
✓ Phase 3: BUILD slides with web content
✓ Phase 4: APPLY professional theme
✓ Phase 5: SAVE to disk4.结果
Output: presentation_20240405_153042.pptx
Status: Ready for download
User can:
• Download the PPTX file
• Edit in PowerPoint
• Share with others
• View in history______________________________________________________________________
🏗️ 架构概述
高级系统图
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js + React) │
│ • Landing Page • Auth (login/register) │
│ • Dashboard • Job History • Settings │
│ • Download Files • Real-time Status Updates │
└────────────────────────┬────────────────────────────────────┘
│ HTTP/REST (Port 3000)
↓
┌─────────────────────────────────────────────────────────────┐
│ BACKEND (FastAPI + Python) │
│ • Auth Layer (JWT) │
│ • Agent Engine (5-phase agentic loop) │
│ • Job Manager & Database │
│ • MCP Client (communicates with 4 servers) │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────┼────────────────┬────────────────┐
↓ ↓ ↓ ↓
┌────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PPT Server │ │ Web Search │ │ Filesystem │ │ Theme Server │
│ (6 tools) │ │ (2 tools) │ │ (4 tools) │ │ (4 tools) │
└────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│ │ │ │
└────────────────┴────────────────┴────────────────┘
│
┌────────────────┴──────────────┐
↓ ↓
┌──────────────┐ ┌──────────────────┐
│ SQLite/ │ │ Output Directory │
│ PostgreSQL │ │ │
│ (User & Job │ │ Generated PPTX │
│ tracking) │ │ Files │
└──────────────┘ └──────────────────┘组件交互流程
1. USER REGISTRATION/LOGIN
Frontend → Backend Auth → JWT Token → User Session in DB
2. PPT GENERATION REQUEST
Frontend (Prompt) → Backend → Agent Engine
3. AGENT EXECUTION (5 Phases)
a) PLANNING - Agent plans slide structure
b) CREATE - Initialize PowerPoint
c) BUILD SLIDES - Add slides with content from web search
d) APPLY THEME - Style the presentation
e) SAVE & OUTPUT - Save PPTX to outputs folder
4. RESULT DELIVERY
Backend → Frontend → PPTX Download______________________________________________________________________
📁 项目结构
ppt-agent/
│
├── README.md # Root documentation (you are here)
│
├── agent/ # Backend (FastAPI + Agent)
│ ├── README.md # Detailed backend documentation
│ ├── main.py # FastAPI application & routes
│ ├── agent_engine.py # 5-phase agentic loop
│ ├── mcp_client.py # MCP server communication
│ ├── models.py # Database models (User, Job, Session)
│ ├── auth.py # JWT & authentication logic
│ ├── config.py # Environment configuration
│ ├── db.py # Database utilities
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment template
│ └── output/ # Generated PPTX files
│
├── frontend/ # Frontend (Next.js + React)
│ ├── README.md # Frontend documentation
│ ├── package.json # Node dependencies
│ ├── next.config.js # Next.js configuration
│ ├── tailwind.config.ts # Tailwind CSS config
│ ├── tsconfig.json # TypeScript config
│ ├── app/ # Next.js App Router
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Landing page
│ │ ├── (auth)/ # Auth routes
│ │ │ ├── login/page.tsx
│ │ │ └── register/page.tsx
│ │ └── (protected)/ # Protected routes
│ │ ├── dashboard/page.tsx # Main PPT generator
│ │ ├── history/page.tsx # Job history
│ │ └── settings/page.tsx # Settings
│ ├── components/ # React components
│ │ ├── auth/ # Auth components
│ │ ├── ppt/ # PPT components
│ │ │ ├── PromptInput.tsx
│ │ │ ├── GenerationStatus.tsx
│ │ │ └── HistoryList.tsx
│ │ ├── layout/ # Layout components
│ │ └── ui/ # shadcn/ui components
│ ├── context/ # React context
│ ├── hooks/ # Custom hooks
│ ├── lib/ # Utilities
│ └── styles/ # Global styles
│
├── mcp/ # MCP Servers
│ ├── README.md # MCP documentation
│ └── servers/ # 4 specialized servers
│ ├── 1.ppt_server.py # PowerPoint manipulation
│ ├── 2.web_search_server.py # Web search functionality
│ ├── 3.filesystem_server.py # File I/O operations
│ ├── 4.theme_server.py # Theming & styling
│ ├── requirements.txt
│ └── __init__.py
│
└── outputs/ # Generated presentations
└── presentation_*.pptx # Output files (git ignored)______________________________________________________________________
🚀 快速开始
先决条件
- Python 3.9+ （用于后端）
- Node.js 18+ （前端）
- npm或纱线 （包管理器）
设置分为5个步骤
步骤1：克隆和导航
cd ppt-agent步骤2：后端设置
cd agent
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Setup environment
cp .env.example .env
# Edit .env with your configuration
# Initialize database
python -c "from models import init_db; init_db()"
# Start backend
python main.py✅ 后端正在运行http://localhost:8000
步骤3:MCP服务器设置
cd mcp/servers
# Create virtual environment
python -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Servers auto-start when backend runs步骤4：前端设置
cd frontend
# Install dependencies
npm install
# Start development server
npm run dev✅ 前端正在运行http://localhost:3000
步骤5：访问应用程序
Landing Page: http://localhost:3000
API Docs (Swagger): http://localhost:8000/docs
Health Check: http://localhost:8000/health______________________________________________________________________
🔧 系统组件
1. 前端（Next.js+React）
用于用户交互的现代、响应式web界面。
主要特点：
- ✅ 用户注册和身份验证
- ✅ 交互式提示输入与验证
- ✅ 实时发电状态显示
- ✅ PPTX下载功能
- ✅ 使用过滤器跟踪作业历史
- ✅ 响应式设计（移动友好）
- ✅ 暗模式支持
技术：
- Next.js 16（React 19）
- TypeScript用于类型安全
- 顺风CSS+shadcn/ui
- Zod用于表单验证
- 用于API通信的Axios
请参阅： 前端自述
______________________________________________________________________
2. 后端（FastAPI+Python）
负责编排演示文稿生成的智能代理。
关键部件：
- FastAPI服务器 -用于前端通信的HTTP API
- 代理引擎 -5相代理回路（计划→ 创建→ 构建→ 主题→ SAVE)
- MCP客户端 -与4台MCP服务器通信，以实现分布式执行
- 身份验证层 -基于JWT的bcrypt身份验证
- 数据库层 -用户和作业管理（SQLite/PPostgreSQL）
主要特点：
- ✅ 执行前智能幻灯片规划
- ✅ 优雅的错误处理和部分结果
- ✅ 失败操作的重试逻辑
- ✅ 针对真实内容的Web搜索集成
- ✅ 用于调试的全面日志记录
请参阅： 代理自述
______________________________________________________________________
3. MCP服务器（Python）
四个专门负责不同职责的微型服务。
服务器故障：
| 服务器 | 用途 | 工具 | 语言 |
|---|---|---|---|
| PPT服务器 | PowerPoint创建和操作 | 6个工具 | Python |
| 2.网络搜索服务器 | 实时内容抓取 | 2个工具 | Python |
| 3.文件系统服务器 | 文件I/O操作 | 4个工具 | Python |
| 4.主题服务器 | 演示样式 | 4个工具 | Python |
总计： 4台服务器|16个工具|专业的关注点分离
请参阅： MCP自述文件
______________________________________________________________________
✨ 主要特点
1. 智能规划
- Agent在创建前分析提示并计划整个幻灯片结构
- 确保连贯、组织良好的演示
- 防止随机/断开的幻灯片生成
2. 实时内容
- 集成DuckDuckGo网络搜索
- 获取每个幻灯片主题的当前信息
- 自动提供引用的最新内容
3. 专业输出
- PPTX格式 -用于编辑的原生PowerPoint格式
- 内置主题 -5个专业主题（默认、海洋、森林、日落、午夜）
- 自定义样式 -配色方案、字体、布局
- 品牌一致性 -所有幻灯片的统一设计
4. 稳健的错误处理
- 失败操作的重试逻辑（3次回退尝试）
- 如果网络搜索失败，性能会下降
- 部分故障时的部分演示交付
- 用于调试的全面日志记录
5. 用户管理
- 安全注册和登录
- 基于JWT的身份验证（24小时令牌）
- 每个用户的作业历史跟踪
- 每用户输出隔离
______________________________________________________________________
🛠️ 技术栈
后端
Framework: FastAPI (Python)
Database: SQLite (dev) / PostgreSQL (prod)
Auth: JWT + bcrypt
PowerPoint: python-pptx
Web Search: DuckDuckGo Search
Protocol: Model Context Protocol (MCP)
Server: Uvicorn
ORM: SQLAlchemy前端
Framework: Next.js 16 (React 19)
Language: TypeScript
Styling: Tailwind CSS + shadcn/ui
HTTP: Axios
Forms: React Hook Form + Zod
UI Toolkit: Radix UI components
Icons: Lucide React
Notifications: Sonner开发运维
Containerization: Docker (ready for deployment)
Package Manager: npm (frontend), pip (backend)
Version Control: Git
Database: SQLite (dev), PostgreSQL (production)______________________________________________________________________
📦 部署
发展（地方）
# Terminal 1 - Backend
cd agent
python main.py # http://localhost:8000
# Terminal 2 - Frontend
cd frontend
npm run dev # http://localhost:3000生产
请参阅详细的部署指南：
部署前检查表：
- \[\]启用HTTPS/TLS
- \[\]更改.env中的SECRET_KEY
- \[\]使用PostgreSQL而不是SQLite
- \[\]正确配置CORS
- \[\]设置日志轮换
- \[\]配置生产环境变量
______________________________________________________________________
👨💻 发展
运行所有组件
# Terminal 1 - Backend
cd agent
python main.py
# Terminal 2 - Frontend
cd frontend
npm run dev访问http://localhost:3000访问应用程序。
环境变量
后端（.env）
# Server
HOST=0.0.0.0
PORT=8000
DEBUG=False
# Database
DATABASE_URL=sqlite:///./ppt_agent.db
# Security (CHANGE IN PRODUCTION!)
SECRET_KEY=your-super-secret-key-here
# MCP Servers
MCP_SERVERS_PATH=../mcp/servers
# Optional: HuggingFace token
HF_TOKEN=optional-token前端（.env.local）
# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000
# Optional: App name
NEXT_PUBLIC_APP_NAME=SlideForage代码质量
# Backend
cd agent
flake8 . # Linting
black . # Formatting
# Frontend
cd frontend
npm run lint # ESLint
npm run format # Prettier______________________________________________________________________
📊 API终点
关键端点的快速参考：
认证
POST /register # Create account
POST /login # Get JWT tokenPPT生成
POST /create-ppt # Generate presentation
GET /download/{filename} # Download PPTX
GET /jobs # Get user's job history
GET /jobs/{job_id} # Get specific job status系统
GET /health # System health check
GET /docs # Swagger UI (interactive)
GET /redoc # ReDoc (alternative docs)API完整文档可在以下网址获取： http://localhost:8000/docs
______________________________________________________________________
🐛 故障排除
后端无法启动
# Check Python version
python --version # Should be 3.9+
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
# Check MCP servers path
ls ../mcp/servers/前端无法构建
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
# Check Node version
node --version # Should be 18+无法从前端访问后端
# Check backend is running
curl http://localhost:8000/health
# Verify frontend API URL
cat .env.local | grep NEXT_PUBLIC_API_URLMCP服务器没有响应
# Check if servers are running
ps aux | grep python
# Test MCP server directly
python mcp/servers/1.ppt_server.py______________________________________________________________________
📞 支持和资源
文档
获取帮助
- 查看您模块的相关README
- 查看故障排除部分
- 检查应用程序日志
- 验证配置文件
______________________________________________________________________
🎉 快速链接
| 资源 | 链接 |
|---|---|
| 代理文档 | 代理/README.md |
| 前端文档 | 前端/README.md |
| MCP文件 | mcp/README.md |
| API文件 | http://localhost:8000/docs |
| 实时应用程序 | http://localhost:3000 |
______________________________________________________________________
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
制作❤️ 用于智能演示生成