# 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)