# 美术 Agent 工具 — 核心决策记录

> 本文档记录了产品规划阶段讨论确认的所有核心决策，作为后续设计与开发的基准。

---

## 1. 产品形态

**决定：Chat-first Web App**

- 以对话为核心交互方式的 Web 应用
- 浏览器访问，无需安装
- 主界面是对话框，但在需要时展开画布、图片网格、参数面板等辅助 UI
- 远期可包装为 Electron 桌面应用（但不影响当前架构选型）

---

## 2. 核心交互模型

### 基本流程

用户描述需求 → LLM 理解意图 → 生成候选图 → 展示并等待反馈 → 迭代或确认

### 候选图

- 用户可自行决定每次生成几张候选图

### 审美表达方式（按阶段）

| 阶段 | 方式 |
|---|---|
| MVP | 语言描述、选择题式（多选一）、参考图上传 |
| Phase 2 | 图上标注（圈出区域 + 局部重绘） |

### 上下文系统

- 需要记忆系统：项目级全局风格 + 会话级当前任务上下文
- 开发者侧：类似 Cursor 的 Skill/Rules 扩展机制，方便动态调整 Agent 行为
- 用户侧：自定义能力暂缓

---

## 3. AI 能力层架构

### LLM 对话层

- 主力：OpenAI GPT 系列（GPT-4o 等）
- 备选：Anthropic Claude
- 做抽象接口层，方便切换和新增模型

### 图像生成后端

- 云端 API（不做本地部署）
- 候选平台：Replicate / fal.ai / Stability API 等
- 同样做抽象接口，按需对接不同服务

### Agent Core 引擎

- 不硬编码业务逻辑
- 通过 Markdown 格式的 Skill 文件定义能力（类似 Cursor SKILL.md）
- 通过 Markdown 格式的 Rules 文件定义全局约束/偏好
- 开发者可随时添加/修改 Skill 和 Rules，无需改核心代码

### 架构分层

```
前端 (Chat-first Web App)
  ├── 对话界面
  ├── 候选图展示/选择
  ├── 参考图上传
  └── 资源管理面板

后端服务
  ├── API Gateway
  ├── Agent Core 引擎
  │   ├── Skill Registry（能力注册表）
  │   ├── Rules Engine（规则引擎）
  │   └── Memory System（记忆系统）
  └── Task Queue（异步任务队列）

AI 能力层（云端 API）
  ├── LLM 服务（GPT / Claude / ...）
  ├── 图像生成 API
  ├── LoRA 训练 API
  └── 后处理服务（去背景、超分等）

存储层
  ├── 数据库（用户数据、会话历史、项目配置）
  ├── 对象存储 OSS（生成图、参考图、导出资源）
  └── 风格库（LoRA 权重、Prompt 模板）
```

---

## 4. 风格管理系统

### 风格定义三种方式（按优先级递进）

| 优先级 | 方式 | 说明 |
|---|---|---|
| MVP | Prompt 模板 | 开发者用精调的描述词定义风格，最简单 |
| MVP | 参考图风格迁移 | 用户上传参考图实时引导生成，无需训练 |
| Phase 2 | LoRA 训练 | 上传 5-15 张参考图训练专属风格模型，效果最强 |

### 风格库结构

- **两层共享**：个人风格 + 团队共享风格
- **预置风格**：MVP 不做，后续迭代加入常用游戏风格
- 每个风格包含：元数据 / 参考图集 / LoRA 权重（如有）/ Sample 图 / 推荐参数

---

## 5. 资源产出 Pipeline

### MVP 范围（最小可用）

- 对话生成单张图 + 迭代修改
- 导出格式：PNG
- 不含批量产出、去背景、超分等后处理

### Phase 2 扩展

- 去背景/透明化
- 超分辨率放大
- 尺寸规范适配（多分辨率导出）
- 批量产出（同风格系列资源）
- 更多导出格式（SVG / WebP）

---

## MVP 范围总结

**MVP 核心功能清单：**

1. Chat-first Web App 基础界面（对话框 + 图片展示区）
2. 用户通过自然语言描述需求，LLM 理解意图并生成图片
3. 多张候选图展示，用户选择/反馈/迭代
4. 参考图上传（引导风格方向）
5. Prompt 模板风格 + 参考图风格迁移
6. 基础记忆系统（会话上下文 + 项目级风格配置）
7. 开发者 Skill/Rules 扩展机制
8. PNG 格式导出

**Phase 2 扩展方向：**

- LoRA 训练
- 图上标注 + 局部重绘
- 批量产出
- 高级后处理 Pipeline
- 预置风格库
- 多格式导出
- 团队协作增强（权限、审核等）
- 3D / 场景资源（远期）

---

## 技术栈选型（已确定）

> 详细选型理由和依赖清单见 [TECH-STACK.md](TECH-STACK.md)

- [x] 前端框架 — **Next.js (React)** + Vercel AI SDK + shadcn/ui
- [x] 后端框架 — **Python FastAPI**
- [x] Agent 框架 — **自建 Agent Loop** + OpenAI Function Calling
- [x] 数据库 — **PostgreSQL**（JSONB + pgvector 预留）
- [x] 对象存储 — **MVP 本地文件系统**，后期迁移 Cloudflare R2 / 阿里云 OSS
- [x] 图像生成 API — **Replicate**（首选），做抽象层方便扩展
- [x] 部署方案 — **Vercel** (前端) + **Railway** (后端)
- [x] 异步任务 — **asyncio + SSE**（MVP），后期 Celery + Redis