230 lines
7.4 KiB
Markdown
230 lines
7.4 KiB
Markdown
# MVP 最小流程 — 端到端跑通计划
|
||
|
||
> 目标：用最小代码量跑通一条完整闭环，快速暴露集成问题。
|
||
|
||
---
|
||
|
||
## 范围
|
||
|
||
**包含：**
|
||
- 用户通过对话描述需求，LLM 理解意图并调用图像生成
|
||
- 用户可上传参考图引导生成风格
|
||
- 多轮对话迭代修改
|
||
- 生成 1-4 张候选图，用户可下载保存到本地
|
||
- SSE 流式推送（实时看到 AI 回复和生成进度）
|
||
|
||
**刻意砍掉（后续再加）：**
|
||
- 数据库 / 持久化（用内存存对话历史）
|
||
- Skill / Rules 扩展机制
|
||
- 风格模板 / 风格库
|
||
- 用户认证
|
||
- 云端部署（先本地跑通）
|
||
|
||
---
|
||
|
||
## 数据流
|
||
|
||
```
|
||
用户输入文字 + 可选参考图
|
||
→ 前端 POST /api/chat（消息 + 图片）
|
||
→ 后端 Agent Loop
|
||
→ 调用 OpenAI GPT（带 tools 定义）
|
||
→ GPT 返回 tool_call: generate_image
|
||
→ 调用 Replicate API（Flux 模型）
|
||
→ 图片下载到本地 generated/ 目录
|
||
→ 工具结果回传 GPT
|
||
→ GPT 生成最终文字回复
|
||
→ SSE 流式推送给前端
|
||
→ 前端展示文字 + 图片网格（带下载按钮）
|
||
```
|
||
|
||
---
|
||
|
||
## 准备工作：API Key
|
||
|
||
### OpenAI API Key
|
||
1. 访问 https://platform.openai.com/signup 注册
|
||
2. https://platform.openai.com/api-keys 创建 Key
|
||
3. 需预充值（最低 $5），模型用 GPT-4o-mini（便宜够用）
|
||
|
||
### Replicate API Token
|
||
1. 访问 https://replicate.com/signin 用 GitHub 登录
|
||
2. https://replicate.com/account/api-tokens 创建 Token
|
||
3. 新用户有免费额度
|
||
|
||
---
|
||
|
||
## 实施步骤与完成状态
|
||
|
||
### Step 1：项目脚手架 — 已完成
|
||
|
||
- [x] 后端：`art-agent/backend/`，Python + FastAPI
|
||
- [x] 前端：`art-agent/frontend/`，Next.js + TypeScript + Tailwind CSS v4
|
||
- [x] 配置：`.env.example` 放 API Key 模板
|
||
- [x] Python 虚拟环境已创建并安装依赖
|
||
- [x] Node.js v24.14.1 已安装（通过 winget）
|
||
- [x] 前端 npm 依赖已安装（46 个包）
|
||
|
||
### Step 2：后端核心 API — 已完成
|
||
|
||
- [x] `POST /api/chat` — 接收消息 + 可选图片，调用 Agent Loop，SSE 流式返回
|
||
- [x] `/uploads/{filename}` — 通过 StaticFiles 提供上传的参考图
|
||
- [x] `/generated/{filename}` — 通过 StaticFiles 提供生成的图片
|
||
- [x] `/health` — 健康检查端点
|
||
- [x] CORS 中间件已配置（允许所有来源）
|
||
- [x] 后端启动验证通过（健康检查返回 `{"status": "ok"}`）
|
||
|
||
### Step 3：Agent Loop — 已完成
|
||
|
||
- [x] 硬编码 system prompt（美术助手角色，中文交流，英文 prompt 生成）
|
||
- [x] 定义 `generate_image` 工具（prompt、num_images）
|
||
- [x] Agent 循环：LLM 调用 → tool_call → 执行 → 结果回传 → 继续（最多 5 轮）
|
||
- [x] 流式输出：text_delta / tool_start / image_result / done / error 事件
|
||
- [x] 参考图通过 GPT-4o-mini vision 能力理解（附加为 image_url）
|
||
- [x] OpenAI 客户端延迟初始化（避免无 Key 时导入失败）
|
||
|
||
### Step 4：Replicate 图像生成 — 已完成
|
||
|
||
- [x] 封装 Replicate API 调用
|
||
- [x] 模型：`black-forest-labs/flux-schnell`（快速版）
|
||
- [x] 生成图片异步下载到本地 `generated/` 目录
|
||
- [x] 返回本地可访问 URL
|
||
|
||
### Step 5：前端 Chat UI — 已完成
|
||
|
||
- [x] 主页面 `page.tsx`：对话消息区域 + 底部输入框
|
||
- [x] `ChatMessages` 组件：渲染历史消息 + 流式生成中的消息
|
||
- [x] `ChatInput` 组件：文字输入 + 参考图上传 + 预览 + 发送按钮
|
||
- [x] `ImageGrid` 组件：候选图网格展示 + 悬停显示"保存"按钮
|
||
- [x] 欢迎页面：3 个快捷提示按钮
|
||
- [x] 暗色主题 UI
|
||
- [x] 加载状态：跳动圆点 + 脉冲状态指示
|
||
|
||
### Step 6：SSE 对接 — 已完成
|
||
|
||
- [x] `lib/api.ts`：SSE 流式读取封装为 AsyncGenerator
|
||
- [x] 事件解析：text_delta / tool_start / image_result / done / error
|
||
- [x] 图片 URL 相对路径转换（`getImageUrl` 工具函数）
|
||
- [x] 消息通过 FormData 发送（支持同时上传文本和图片）
|
||
|
||
### Step 7：端到端验证 — 进行中
|
||
|
||
- [x] 后端启动验证通过
|
||
- [ ] 前端启动验证（需配置好 API Key 后完整测试）
|
||
- [ ] 完整对话流程验证
|
||
- [ ] 参考图上传流程验证
|
||
- [ ] 图片下载功能验证
|
||
|
||
---
|
||
|
||
## 环境搭建记录
|
||
|
||
### 已安装的环境
|
||
|
||
| 工具 | 版本 | 安装方式 |
|
||
|---|---|---|
|
||
| Python | 3.12.5 | 系统已有 |
|
||
| Node.js | 24.14.1 (LTS) | winget 安装 |
|
||
| npm | 11.11.0 | 随 Node.js |
|
||
|
||
### 遇到的问题及解决
|
||
|
||
1. **OpenAI 客户端模块加载时初始化失败** — 无 API Key 时 `AsyncOpenAI()` 会抛异常。
|
||
解决：改为延迟初始化，在 `run_agent_loop` 函数内部创建客户端。
|
||
|
||
2. **PowerShell 不支持 `&&` 操作符** — 旧版 PowerShell 的语法限制。
|
||
解决：使用分号 `;` 或分两条命令执行。
|
||
|
||
3. **PowerShell 脚本执行策略限制** — 默认禁止运行 `.ps1` 脚本，导致 `npm` 无法执行。
|
||
解决：`Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`
|
||
|
||
---
|
||
|
||
## 验证标准
|
||
|
||
1. 输入"画一个赛博朋克风格的游戏退出按钮" → AI 回复 + 生成图片
|
||
2. 点击下载按钮 → 图片保存到本地
|
||
3. 输入"颜色再暗一些，加点霓虹光效" → 迭代后新图片
|
||
4. 上传参考图 + "参考这张图的风格" → 受参考图引导的图片
|
||
|
||
---
|
||
|
||
## 启动命令
|
||
|
||
### 后端
|
||
|
||
```powershell
|
||
cd d:\GIT_HOME\EPEEAIKit\art-agent\backend
|
||
.\venv\Scripts\activate
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
### 前端
|
||
|
||
```powershell
|
||
cd d:\GIT_HOME\EPEEAIKit\art-agent\frontend
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:3000
|
||
|
||
---
|
||
|
||
## 文件清单
|
||
|
||
```
|
||
art-agent/
|
||
README.md # 项目说明和启动指南
|
||
|
||
backend/
|
||
.env.example # API Key 模板
|
||
.env # 实际 API Key（已配置，不入 Git）
|
||
requirements.txt # Python 依赖（9 个包）
|
||
venv/ # Python 虚拟环境（不入 Git）
|
||
uploads/ # 用户上传的参考图
|
||
generated/ # AI 生成的图片缓存
|
||
app/
|
||
__init__.py
|
||
main.py # FastAPI 入口 + CORS + 静态文件
|
||
api/
|
||
__init__.py
|
||
chat.py # POST /api/chat 端点
|
||
agent/
|
||
__init__.py
|
||
loop.py # Agent Loop 主循环（SSE 流式）
|
||
tools.py # 工具定义（generate_image）
|
||
services/
|
||
__init__.py
|
||
image_gen.py # Replicate API 封装
|
||
|
||
frontend/
|
||
.env.local # 后端 API 地址配置
|
||
package.json # npm 依赖
|
||
tsconfig.json # TypeScript 配置
|
||
next.config.ts # Next.js 配置
|
||
postcss.config.mjs # PostCSS / Tailwind 配置
|
||
node_modules/ # npm 依赖（不入 Git）
|
||
src/
|
||
app/
|
||
page.tsx # 主页面（含 SSE 对接逻辑）
|
||
layout.tsx # 根布局
|
||
globals.css # 全局样式（暗色主题）
|
||
components/
|
||
chat/
|
||
chat-messages.tsx # 对话消息列表
|
||
chat-input.tsx # 输入框 + 参考图上传
|
||
image-grid.tsx # 图片网格 + 下载按钮
|
||
lib/
|
||
api.ts # 后端 API 调用 + SSE 解析
|
||
|
||
docs/
|
||
art-agent/
|
||
DECISIONS.md # 产品决策文档（5 个核心问题）
|
||
TECH-STACK.md # 技术选型文档（8 个维度）
|
||
MVP-PLAN.md # 本文件：MVP 实施计划与记录
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
详见 [TECH-STACK.md](TECH-STACK.md)
|