185 lines
6.6 KiB
Markdown
185 lines
6.6 KiB
Markdown
# 设计文档
|
||
|
||
> 成果物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年讯和技术大赛-参赛者手册` | 成果物格式与评审标准 |
|