自然语言驱动的多智能体 PPT 生成系统，支持交互式分步审阅、迭代修改和用户偏好记忆。
- 交互式审阅工作流 — 大纲、内容逐步生成，每步可在前端直接编辑 Markdown 后再继续
- 多轮对话意图解析 — 需求模糊时自动发起澄清问答，确认后继续流水线
- 迭代修改 — 生成完成后可用自然语言描述修改（"第3页换成对比表格"），智能识别修改范围
- 记忆系统 — 集成 Memoria，持久化用户风格偏好，下次生成时自动参考
- 插件化渲染引擎 — 表格、图表、图片、文本框各自独立插件，易于扩展新组件类型
- 组件级设计方案 — Design Advisor 为每页输出精确的组件位置（归一化坐标）和 Z-Order 层级
用户自然语言
↓
[交互式流水线 — 3阶段]
Stage 1: 意图解析 + 大纲规划
┣ Intent Parser — 解析主题/受众/风格/页数，检测需求模糊性
┗ Outline Planner — 规划幻灯片大纲（含布局建议、组件预期）
↓ 前端审阅大纲 Markdown，可编辑后确认
Stage 2: 内容撰写
┗ Content Writer — 逐页生成标题、要点、备注、表格/图表数据
↓ 前端审阅内容 Markdown，可编辑后确认
Stage 3: 设计 → 渲染
┣ Design Advisor — 全局主题 + 每页组件级设计规格（坐标/层级/样式）
┣ IR Builder — 组装 PPT 中间表示层 (PPT-IR)
┗ PPT Executor — 插件化渲染引擎 → 输出 .pptx
[编辑模式 — 单独触发]
┣ Edit Parser — 识别修改范围 (content/design/layout/outline/full)
┣ Content Patcher — 精确修改指定页面的文字/要点
┗ Layout Patcher — 修改页面布局类型
编辑 .env 文件（支持任何 OpenAI 兼容接口）：
LLM_API_KEY=sk-your-key-here
LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/ # Google Gemini 示例
LLM_MODEL=gemini-2.0-flash# 一键启动（自动处理 Docker 容器、环境变量、前后端服务）
bash scripts/service.sh start all
# 查看状态
bash scripts/service.sh status
# 重启后端（代码修改后）
bash scripts/service.sh restart ppt-agent访问 Web UI：http://localhost:8000
# Step 1: 提交生成请求
curl -X POST http://localhost:8000/api/v1/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "为管理层制作 AI 战略规划汇报，8页，深蓝商务风格，含市场数据对比表格"}'
# → 返回 {"task_id": "...", "session_id": "..."}
# Step 2: 轮询任务状态
curl http://localhost:8000/api/v1/tasks/{task_id}
# status: running → awaiting_outline_review → awaiting_content_review → completed
# Step 3a: 确认大纲（可传入修改后的 Markdown）
curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/outline/confirm \
-H "Content-Type: application/json" \
-d '{"outline_markdown": null}' # null = 使用原始大纲
# Step 3b: 确认内容
curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/content/confirm \
-H "Content-Type: application/json" \
-d '{"content_markdown": null}'
# 生成完成后文件自动保存至 ./output/<title>.pptxcurl -X POST http://localhost:8000/api/v1/sessions/{session_id}/modify \
-H "Content-Type: application/json" \
-d '{"prompt": "把第3页的要点缩减到3条，换成对比表格布局"}'curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/clarify \
-H "Content-Type: application/json" \
-d '{"answers": "目标受众是投资人，需要英文，10页左右"}'ppt-agent/
├── main.py # FastAPI 应用入口
├── requirements.txt
├── .env # 配置文件（不提交）
├── scripts/
│ └── service.sh # 统一服务管理脚本（start/stop/restart/status）
├── config/
│ └── settings.py # 应用配置 + 记忆系统工厂函数
├── app/
│ ├── agents/
│ │ ├── graph.py # LangGraph 流水线 + 阶段化独立函数
│ │ ├── schemas.py # 所有 Agent 的 Pydantic 输入/输出模型
│ │ └── prompts/ # 提示词模板库（每节点独立文件）
│ │ ├── _common.py # 公共约束片段（严格遵守规则/质量标准）
│ │ ├── intent_parser.py
│ │ ├── outline_planner.py
│ │ ├── content_writer.py
│ │ ├── design_advisor.py # 含画布坐标系说明和配色方案参考
│ │ ├── edit_parser.py
│ │ ├── content_patcher.py
│ │ └── layout_patcher.py
│ ├── engine/
│ │ ├── ppt_ir.py # PPT 中间表示层（含 layout_summary() 可视化）
│ │ ├── pptx_executor.py # 插件化渲染调度器
│ │ └── plugins/ # 形状渲染插件
│ │ ├── __init__.py # BaseShapePlugin + PluginRegistry
│ │ ├── textbox_plugin.py
│ │ ├── table_plugin.py # 支持表头背景色/边框色/奇偶行交替色
│ │ ├── chart_plugin.py
│ │ ├── image_plugin.py
│ │ └── shape_plugin.py
│ ├── memory/
│ │ ├── types.py # MemoryType / MemoryEntry
│ │ ├── manager.py # 记忆管理器（后端无关接口）
│ │ ├── summarizer.py # 零 Token 规则化摘要生成器
│ │ └── backends/
│ │ ├── base.py # 抽象基类
│ │ ├── null.py # 无操作后端（记忆关闭时）
│ │ ├── file.py # 本地 JSON 文件后端（开发用）
│ │ └── memoria.py # Memoria REST API 后端（生产用）
│ ├── llm/
│ │ └── client.py # LLM 客户端封装（get_llm / get_structured_llm）
│ ├── api/
│ │ ├── routes.py # REST API 路由（含阶段化流水线控制）
│ │ └── models.py # API 请求/响应 Pydantic 模型
│ └── web/
│ └── templates/
│ └── index.html # 交互式 Web UI（分步审阅状态机）
├── docs/
│ ├── context/ # AI 辅助开发知识索引
│ │ ├── MASTER_INDEX.md # 主路由文档
│ │ ├── SESSION_HANDOFF.md # 跨会话状态交接
│ │ ├── agent-pipeline.md # Agent 流水线详解
│ │ ├── api-web.md # API 和前端对应关系
│ │ ├── memory.md # 记忆系统架构
│ │ └── devops.md # 部署运维说明
│ └── architecture/
│ ├── e2e_traceability.md # 端到端可追踪性映射
│ └── page_map.md # 前端页面与代码对应关系
└── output/ # 生成的 PPTX 文件（不提交）
项目集成了 Memoria 作为持久记忆后端。
| 能力 | 说明 |
|---|---|
| 偏好记忆 | 每次生成后自动保存风格偏好（配色/字体/布局）到 Memoria，下次生成时注入提示词 |
| 会话摘要 | 会话结束时保存摘要（主题 + 修改历史），零 LLM Token 消耗 |
| 后端可换 | Strategy Pattern 实现，支持 Null / File / Memoria 三种后端 |
| Embedding | 优先使用本地 Ollama nomic-embed-text（768d），不可用时降级到 SiliconFlow API |
启用 / 关闭记忆系统（.env）：
MEMORIA_ENABLED=true # false = 使用 Null 后端，完全无副作用
MEMORIA_API_URL=http://localhost:8100任务 status 的完整流转：
pending
→ running # 意图解析 + 大纲规划中
→ clarifying # 需求模糊，等待用户补充 → POST /clarify
→ awaiting_outline_review # 大纲完成，等待确认 → POST /outline/confirm
→ running # 内容撰写中
→ awaiting_content_review # 内容完成，等待确认 → POST /content/confirm
→ running # 设计 + IR + 渲染中
→ completed # 完成，output_filename 可用
→ failed # 任何阶段出错
| 服务 | 用途 | 启动方式 |
|---|---|---|
| PPT Agent | 本项目主服务 | service.sh start ppt-agent |
| Memoria API | 记忆存储服务 | service.sh start memoria（需先启 MatrixOne） |
| MatrixOne | Memoria 的向量数据库 | service.sh start matrixone（Docker） |
| Ollama | 本地 Embedding 模型 | 系统独立运行，service.sh 自动检测 |
# 全部启动
bash scripts/service.sh start all
# 仅启动 PPT Agent（不使用记忆系统）
bash scripts/service.sh start ppt-agent