7.4 KiB
7.4 KiB
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
- 访问 https://platform.openai.com/signup 注册
- https://platform.openai.com/api-keys 创建 Key
- 需预充值（最低 $5），模型用 GPT-4o-mini（便宜够用）
Replicate API Token
- 访问 https://replicate.com/signin 用 GitHub 登录
- https://replicate.com/account/api-tokens 创建 Token
- 新用户有免费额度
实施步骤与完成状态
Step 1：项目脚手架 — 已完成
- 后端：
art-agent/backend/，Python + FastAPI - 前端：
art-agent/frontend/，Next.js + TypeScript + Tailwind CSS v4 - 配置：
.env.example放 API Key 模板 - Python 虚拟环境已创建并安装依赖
- Node.js v24.14.1 已安装（通过 winget）
- 前端 npm 依赖已安装（46 个包）
Step 2：后端核心 API — 已完成
POST /api/chat— 接收消息 + 可选图片，调用 Agent Loop，SSE 流式返回/uploads/{filename}— 通过 StaticFiles 提供上传的参考图/generated/{filename}— 通过 StaticFiles 提供生成的图片/health— 健康检查端点- CORS 中间件已配置（允许所有来源）
- 后端启动验证通过（健康检查返回
{"status": "ok"}）
Step 3：Agent Loop — 已完成
- 硬编码 system prompt（美术助手角色，中文交流，英文 prompt 生成）
- 定义
generate_image工具（prompt、num_images） - Agent 循环：LLM 调用 → tool_call → 执行 → 结果回传 → 继续（最多 5 轮）
- 流式输出：text_delta / tool_start / image_result / done / error 事件
- 参考图通过 GPT-4o-mini vision 能力理解（附加为 image_url）
- OpenAI 客户端延迟初始化（避免无 Key 时导入失败）
Step 4：Replicate 图像生成 — 已完成
- 封装 Replicate API 调用
- 模型：
black-forest-labs/flux-schnell（快速版） - 生成图片异步下载到本地
generated/目录 - 返回本地可访问 URL
Step 5：前端 Chat UI — 已完成
- 主页面
page.tsx：对话消息区域 + 底部输入框 ChatMessages组件：渲染历史消息 + 流式生成中的消息ChatInput组件：文字输入 + 参考图上传 + 预览 + 发送按钮ImageGrid组件：候选图网格展示 + 悬停显示"保存"按钮- 欢迎页面：3 个快捷提示按钮
- 暗色主题 UI
- 加载状态：跳动圆点 + 脉冲状态指示
Step 6：SSE 对接 — 已完成
lib/api.ts：SSE 流式读取封装为 AsyncGenerator- 事件解析：text_delta / tool_start / image_result / done / error
- 图片 URL 相对路径转换（
getImageUrl工具函数） - 消息通过 FormData 发送（支持同时上传文本和图片）
Step 7：端到端验证 — 进行中
- 后端启动验证通过
- 前端启动验证（需配置好 API Key 后完整测试）
- 完整对话流程验证
- 参考图上传流程验证
- 图片下载功能验证
环境搭建记录
已安装的环境
| 工具 | 版本 | 安装方式 |
|---|---|---|
| Python | 3.12.5 | 系统已有 |
| Node.js | 24.14.1 (LTS) | winget 安装 |
| npm | 11.11.0 | 随 Node.js |
遇到的问题及解决
-
OpenAI 客户端模块加载时初始化失败 — 无 API Key 时
AsyncOpenAI()会抛异常。 解决：改为延迟初始化，在run_agent_loop函数内部创建客户端。 -
PowerShell 不支持
&&操作符 — 旧版 PowerShell 的语法限制。 解决：使用分号;或分两条命令执行。 -
PowerShell 脚本执行策略限制 — 默认禁止运行
.ps1脚本，导致npm无法执行。 解决：Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
验证标准
- 输入"画一个赛博朋克风格的游戏退出按钮" → AI 回复 + 生成图片
- 点击下载按钮 → 图片保存到本地
- 输入"颜色再暗一些，加点霓虹光效" → 迭代后新图片
- 上传参考图 + "参考这张图的风格" → 受参考图引导的图片
启动命令
后端
cd d:\GIT_HOME\EPEEAIKit\art-agent\backend
.\venv\Scripts\activate
uvicorn app.main:app --reload --port 8000
前端
cd d:\GIT_HOME\EPEEAIKit\art-agent\frontend
npm run dev
文件清单
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 实施计划与记录