EPEEAIKit/docs/art-agent/MVP-PLAN.md

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：项目脚手架 — 已完成

• 后端：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

遇到的问题及解决

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. 上传参考图 + "参考这张图的风格" → 受参考图引导的图片

---

启动命令

后端

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

访问 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