# 设计文档

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

---

## 一、场景描述与业务价值

### 场景说明

本项目聚焦公司内部两大高频 PPT 场景：

| 场景 | 描述 | 典型用途 |
|------|------|---------|
| **社内汇报** | 面向团队/本部的进展报告与提案 | 项目周报、改善方案汇报、团队建设进度 |
| **社内培训** | 面向同事的技术/方法论知识传授 | 工具教学、技术培训、新流程讲解 |

详细场景规范见 `事前调查/02-场景规范/社内汇报与培训PPT规范.md`。

### 业务价值

| 维度 | 当前痛点 | Agent 方案效果 |
|------|---------|---------------|
| **效率** | 单份 PPT 从搭框架到排版耗时数小时 | 文字输入后分钟级生成 |
| **门槛** | 需要 PowerPoint 操作技巧和设计感 | 无需任何 PPT 技能，输入文字即可 |
| **一致性** | 各人风格不统一，交付质量参差 | 统一模板和配色系统，风格稳定专业 |
| **迭代** | 修改需手动逐页调整 | AI 对话一句话改，多版本自动存档 |

---

## 二、开发范式流程图

> 本图描述团队使用 AI 进行开发的完整工作流。图中步骤名将在 AI 使用日志的"范式步骤"列中一一对应，供评委对照验证。

```mermaid
flowchart LR
    A[需求澄清] --> B[AI 生成方案]
    B --> C[人工审核确认]
    C --> D[AI 编码实现]
    D --> E[测试验证]
    E --> F{通过？}
    F -->|是| G[功能完成]
    F -->|否| H[反馈 AI 修正]
    H --> C
    G --> I[文档更新]
    I --> J[下一功能]
```

**范式步骤说明**：

| 步骤 | 说明 | 对应日志验证 |
|------|------|------------|
| 需求澄清 | 用户用自然语言描述功能需求，AI 追问确认细节 | 日志中标记"需求澄清"的记录 |
| AI 生成方案 | AI 给出修改方案或新功能设计，用户审阅 | 日志中标记"AI生成方案"的记录 |
| 人工审核确认 | 用户回复"ok"确认方案，或提出修改意见 | 用户回复记录 |
| AI 编码实现 | AI 修改/创建代码文件，遵循"先确认后修改"原则 | 日志中"涉及文件"列 + "AI编码"标记 |
| 测试验证 | 用户或测试顾问运行功能、检查输出、对比预期 | 实验报告中的测试用例记录 |
| 反馈迭代 | 发现问题后描述给 AI，AI 修正后重新验证 | 同一功能的多次编码记录形成闭环 |

---

## 三、Agent 架构图

> 赛道一要求：Agent 必须能自主完成"感知→规划→行动"业务闭环。

```mermaid
flowchart TD
    subgraph 前端["Web 交互界面（HTML + JS）"]
        A1[用户注册 / 登录]
        A2[输入文字内容]
        A3[选择场景：社内汇报 / 社内培训]
        A4[选择配色风格]
        A5[下载 PPTX]
        A6[AI 对话修改]
        A7[查看历史记录]
    end

    subgraph 感知["感知层（Perception）"]
        B1[解析输入文字]
        B2[识别场景选择]
        B3[读取用户偏好]
    end

    subgraph 规划["规划层（Planning）"]
        C1[场景 → 模板匹配]
        C2[内容 → 页面分配]
        C3[偏好 → 配色应用]
    end

    subgraph 行动["行动层（Action）"]
        D1[LLM 内容规划 → 生成 plan.json]
        D2[调用 aura-ppt 渲染引擎]
        D3[plan.json → PPTX 确定性渲染]
        D4[内容保真验证 + 导出 PPTX]
        D5[AI 对话修改重新生成]
    end

    subgraph 记忆["记忆层（Memory）"]
        E1[(SQLite 用户表)]
        E2[(SQLite 历史记录表)]
        E3[(SQLite 偏好表)]
    end

    A1 --> B3
    A2 --> B1
    A3 --> B2
    A4 --> B3
    B1 --> C2
    B2 --> C1
    B3 --> C3
    C1 --> D1
    C2 --> D1
    C3 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> D4
    D4 --> A5
    D4 --> E2
    A6 --> B1
    D5 --> A5
    A7 --> E2
    E2 --> A7
    E3 --> B3
```

---

## 四、架构说明

### 组件划分

| 层 | 技术实现 | 核心职责 |
|------|---------|---------|
| **前端** | HTML + JavaScript | 用户交互：登录、输入、场景/配色选择、下载、对话、历史浏览 |
| **感知层** | Python | 解析用户输入文字内容，识别场景选择，读取用户历史偏好 |
| **规划层** | Python | 根据场景匹配对应模板结构，分配页数，应用配色方案 |
| **行动层** | Python + aura-ppt | LLM 生成 plan.json 页面规划，调用 aura-ppt 确定性渲染 PPTX |
| **记忆层** | SQLite | 存储用户信息、生成历史（多版本）、个人偏好（配色/场景） |

### 数据流

```
用户输入 → 感知层（解析+识别） → 规划层（LLM 内容规划）
  → 行动层（plan.json → aura-ppt → PPTX）
  → 输出下载 + 写入记忆层

对话修改时：
用户指令 → 感知层 → 规划层（局部方案） → 行动层（重新生成指定页） → 新版本写入记忆层
```

### 关键设计决策

| 决策 | 内容 | 理由 |
|------|------|------|
| **引擎选型** | 包装 aura-ppt，不改内核 | plan.json → PPTX 确定性渲染，本地 python-pptx 零云端依赖 |
| **场景结构** | 汇报/培训两套预定义模板 | 从社内标杆 PPT 中提炼，确保结构符合公司标准 |
| **配色系统** | 白底 + 商务蓝色系 | 用户偏好明确，与公司社内报告风格一致 |
| **AI 对话修改** | 局部重新生成，非全文重跑 | 减少 Token 消耗，响应更快 |
| **多版本存档** | 每次修改生成新版本，保留旧版 | 支持用户回溯到任意历史版本 |
| **开发方式** | 先给方案确认，再改文件 | 用户习惯约定，避免返工 |

---

## 五、工具/API 清单

| 工具 / API | 用途 | 调用方式 |
|-----------|------|---------|
| **aura-ppt** | PPT 生成核心引擎（plan.json → PPTX 确定性渲染） | Python subprocess 调用 CLI |
| **python-pptx** | PPTX 文件渲染与读写 | Python 库（pip install） |
| **DeepSeek API** | AI 对话修改的自然语言理解 | HTTP API 调用 |
| **Flask** | Web 服务框架（路由、模板、API） | Python 库（pip install） |
| **SQLite3** | 用户信息、历史记录、偏好数据存储 | Python 内置模块 |
| **OpenCode** | AI 辅助开发工具 | CLI 终端工具 |

---

## 六、参考依据

| 类别 | 文件 | 用途 |
|------|------|------|
| 场景规范 | `事前调查/02-场景规范/社内汇报与培训PPT规范.md` | 汇报和培训的结构模板与内容规范 |
| 竞品分析 | `参考资料/竞品分析/竞品清单.md` | 赛道格局分析与定位参考 |
| 试跑成果 | `事前调查/01.试跑现有工具/ppt-master/` | ppt-master v2.0 验证数据 |
| 大赛要求 | `2026年讯和技术大赛-参赛者手册` | 成果物格式与评审标准 |