# 项目说明

> 成果物01 · 赛道一：Agent开发实战赛 · 新规项目

---

## 一、项目性质声明

**新规项目**。本项目为全新选题，从零构建。

---

## 二、项目概述

### 选题背景

公司内部日常工作中，汇报材料和培训资料的 PPT 制作占用了大量时间。以 AI 推进部为例，每月需要制作多份面向不同受众的 PPT，从搭框架、写内容到排版美化，单份耗时常以小时计。随着 AI Agent 技术的成熟，这类重复性文档工作正是 Agent 最适合解决的场景。

### 要解决的问题

让非技术员工通过简单的 Web 界面，输入文字内容后一键生成专业 PPT，并支持通过自然语言对话对生成结果进行修改。聚焦两大场景：**社内汇报、社内培训**。

---

## 三、整体功能说明

### 核心交互流程

```mermaid
flowchart TD
    A[用户注册 / 登录] --> B[进入个人工作台]
    B --> C[显示历史记录与偏好<br/>Agent 认出你是谁]
    C --> D[输入文字内容]
    D --> E[选择场景<br/>社内汇报 / 社内培训]
    E --> F[选择配色风格]
    F --> G["Agent 感知与规划<br/>（分析内容 → 规划页面结构）"]
    G --> H["Agent 行动<br/>（一键生成 PPTX）"]
    H --> I[下载 PPTX]
    I --> J{满意吗？}
    J -->|满意| K[完成]
    J -->|不满意| L["AI 对话修改<br/>（自然语言提修改意见）"]
    L --> M["Agent 理解指令<br/>（局部重新生成）"]
    M --> I
    K --> N[所有版本自动存档]
    M --> N
    N --> O[随时回溯任意历史版本]
```

### 功能清单

| 功能 | 说明 |
|------|------|
| **用户系统** | 注册/登录，SQLite 存储用户信息，登录后展示个人历史记录与偏好 |
| **场景选择** | 支持两大场景：社内汇报、社内培训，Agent 据此调整内容结构和设计风格 |
| **配色风格** | 预设多套配色方案（商务蓝、极简白、深色科技等），用户自选 |
| **一键生成** | 输入文字内容后，Agent 自动完成"分析→规划→生成→导出 PPTX"全流程 |
| **AI 对话修改** | 生成后可通过自然语言提出修改意见，Agent 理解意图并局部修正 |
| **历史记录** | 保存与 AI 交互过程中的多版本历史（含每次修改前后的 PPT 版本），支持回溯和复用 |

---

## 四、效果预期

| 维度 | 目标 |
|------|------|
| **效率提升** | 单份 PPT 从"数小时"压缩到"分钟级" |
| **降低门槛** | 不需要 PowerPoint 操作技巧，输入文字即可 |
| **质量稳定** | 统一的模板和配色系统，确保输出风格专业一致 |
| **Agent 闭环** | 完整演示"感知→规划→行动→记忆"的 Agent 工作流 |

---

## 五、团队分工

| 成员 | 角色 | 职责 |
|------|------|------|
| **张华丹** | 项目负责人 | 需求定义、产品设计、AI 协作开发、测试验收、答辩 |
| **孙亚菲** | 测试顾问 | 功能测试、使用反馈、文档审阅 |

---

## 六、技术路线概要

| 维度 | 选择 |
|------|------|
| **开发工具** | OpenCode + DeepSeek（完全免费，大赛推荐） |
| **核心引擎** | aura-ppt（plan.json → PPTX 确定性渲染，项目内副本） |
| **Agent 核心** | Python（感知→规划→行动→记忆四层 + LLM 内容规划） |
| **前端界面** | HTML + JS（轻量 Web 界面） |
| **数据存储** | SQLite（用户信息 + 历史记录 + 个人偏好存储） |
| **项目周期** | 6 个月（6月-11月），对齐赛道一赛程 |

---

## 七、安装与运行

### 环境要求

| 项 | 要求 |
|----|------|
| Python | 3.10+ |
| 操作系统 | Windows / macOS / Linux |
| 大模型 | 免费方案复用 `opencode serve`（零 Key），或配置 OpenAI 兼容接口（DeepSeek 等） |

### 安装步骤

```bash
pip install -r requirements.txt
python -m src.db.init          # 初始化 SQLite 数据库
```

### 运行方法

```bash
python src/web/app.py          # 启动 Web 服务，默认 http://127.0.0.1:5000
```

浏览器访问 `http://127.0.0.1:5000` → 注册/登录 → 输入文字 → 选择场景与配色 → 一键生成 PPTX → 支持 AI 对话修改与多版本回溯。

### 依赖清单

见 `requirements.txt`：flask、python-pptx、werkzeug、PyMuPDF、mammoth、markdownify、beautifulsoup4、openpyxl。

### API 密钥配置

本项目默认走**零 Key 方案**：`LLM_BACKEND=opencode` 复用本机 `opencode serve`（默认 `http://127.0.0.1:4096`）。如需切换 DeepSeek 等 OpenAI 兼容接口，通过环境变量配置（不硬编码进源码）：

```bash
export LLM_BACKEND=openai
export OPENAI_API_BASE=https://api.deepseek.com
export OPENAI_API_KEY=sk-xxxxxxxx
export OPENAI_MODEL=deepseek-chat
```

所有可选配置项（引擎路径、模板模式、配图策略、并发上限等）均经环境变量注入，见 `config.py`。