# 美术 Agent 工具 — 技术选型

> 本文档记录所有技术选型决策，与 [DECISIONS.md](DECISIONS.md) 配合使用。

---

## 选型总览

| 维度 | 选定方案 | 备选 |
|---|---|---|
| 前端框架 | Next.js (React) | — |
| 后端框架 | Python FastAPI | — |
| Agent 框架 | 自建 Agent Loop + OpenAI Function Calling | — |
| 数据库 | PostgreSQL | — |
| 对象存储 | MVP 本地文件系统 → 后期迁移云端 OSS | Cloudflare R2 / 阿里云 OSS |
| 图像生成 API | Replicate（首选），做抽象层方便扩展 | fal.ai / Stability AI / 国内 API |
| 部署方案 | Vercel (前端) + Railway (后端) | Docker + 云服务器 |
| 异步任务 | MVP 用 asyncio + SSE → 后期 Celery + Redis | — |

---

## 1. 前端 — Next.js (React)

**选型理由：**

- Vercel AI SDK 原生支持流式对话和 Tool Use，是目前对 AI Chat UI 支持最成熟的方案
- shadcn/ui + Tailwind CSS 提供美观且高度可定制的组件库
- 社区有大量 AI Chat 界面组件可复用，降低开发成本
- App Router 支持服务端组件和流式渲染，适合对话场景
- 后续扩展到 3D 预览时，React 生态的 Three.js 集成（react-three-fiber）也很成熟

**关键依赖：**

| 包名 | 用途 |
|---|---|
| `next` | 框架核心 |
| `ai` (Vercel AI SDK) | 流式对话、Tool Use 前端支持 |
| `shadcn/ui` + `tailwindcss` | UI 组件库 |
| `react-dropzone` | 参考图 / 资源文件上传 |
| `zustand` | 轻量客户端状态管理 |

---

## 2. 后端 — Python FastAPI

**选型理由：**

- AI/ML 生态最强：Agent 编排、图像处理库（Pillow、OpenCV）、所有主流 AI SDK 都有 Python 客户端
- FastAPI 异步性能优秀，原生支持 async/await，适合处理 AI API 调用的 I/O 等待
- Pydantic 数据校验与 OpenAI Function Calling 的 JSON Schema 天然契合
- 后处理 Pipeline（去背景、超分等）的库和工具以 Python 为主

**关键依赖：**

| 包名 | 用途 |
|---|---|
| `fastapi` + `uvicorn` | Web 框架 + ASGI 服务器 |
| `openai` | OpenAI API 客户端（GPT 对话 + Function Calling） |
| `replicate` | Replicate API 客户端（图像生成） |
| `sqlalchemy` + `asyncpg` | PostgreSQL 异步 ORM |
| `pydantic` | 数据校验（FastAPI 内置） |
| `sse-starlette` | SSE 流式推送 |
| `python-frontmatter` | 解析 Skill/Rules Markdown 的 YAML frontmatter |
| `Pillow` | 图像基础处理 |

---

## 3. Agent 框架 — 自建 Agent Loop

**选型理由：**

- 美术类 Agent 逻辑高度专业化（多图编排、风格上下文、审美反馈循环），通用框架（LangChain 等）的厚抽象层反而是负担
- Cursor 和 Claude Code 都是自建 Agent Loop，验证了这条路在专业化场景下的可行性
- 直接使用 OpenAI Function Calling / Tool Use 协议，轻量且可控
- 工具注册通过 Skill 文件声明式定义，保持扩展性

**Agent Loop 核心流程：**

```
接收用户消息
  → 加载会话上下文 + 项目风格配置
  → 加载匹配的 Skills / Rules
  → 调用 LLM（带 tools 定义）
  → LLM 返回文本 → 流式返回给前端
  → LLM 返回 tool_call → 执行工具 → 结果回传 LLM → 继续循环
  → 保存上下文到 Memory
  → 等待下一条消息
```

**初始工具集：**

| 工具名 | 功能 |
|---|---|
| `generate_image` | 调用 Replicate 生成图片 |
| `get_style` | 查询风格库（Prompt 模板 / LoRA） |
| `apply_style_ref` | 使用参考图进行风格迁移 |
| `export_asset` | 导出为指定格式（MVP 仅 PNG） |

---

## 4. 数据库 — PostgreSQL

**选型理由：**

- JSONB 类型兼顾结构化查询和半结构化数据存储（Skill 配置、风格参数、对话上下文等）
- pgvector 扩展为未来风格相似度检索留路（根据参考图 embedding 找相似风格）
- 成熟稳定，从开发到生产都可靠
- Railway 和大部分云平台都提供托管 PostgreSQL

**主要表设计方向：**

| 表 | 存储内容 |
|---|---|
| `users` | 用户账户 |
| `projects` | 项目配置（全局风格、默认参数） |
| `conversations` | 会话元数据 |
| `messages` | 对话消息（含工具调用记录） |
| `styles` | 风格库（Prompt 模板 / LoRA 元数据） |
| `generated_assets` | 生成资源记录（关联存储路径） |

---

## 5. 对象存储 — MVP 本地文件系统

**选型理由：**

- MVP 阶段减少外部依赖，加快开发速度
- 接口层做好抽象（`StorageBackend` 接口），后续一行配置切换到云端 OSS

**抽象接口设计：**

```python
class StorageBackend(ABC):
    async def upload(self, file: bytes, path: str) -> str: ...
    async def download(self, path: str) -> bytes: ...
    async def get_url(self, path: str) -> str: ...
    async def delete(self, path: str) -> None: ...
```

**后续迁移路径：**

- 海外用户 → Cloudflare R2（零出站费，S3 兼容 API）
- 国内用户 → 阿里云 OSS

---

## 6. 图像生成 API — Replicate（首选）

**选型理由：**

- 模型市场最丰富：Flux、Stable Diffusion 各版本、LoRA 训练 API 都有
- API 设计简洁，Python SDK 使用方便
- 按秒计费，成本透明可控
- 支持异步预测（prediction），天然适合长时间图像生成任务
- LoRA 训练 API 成熟，为 Phase 2 的风格训练做好准备

**抽象层设计：**

```python
class ImageGenerator(ABC):
    async def generate(self, prompt: str, params: GenerateParams) -> list[str]: ...
    async def generate_with_ref(self, prompt: str, ref_image: str, params: GenerateParams) -> list[str]: ...
    async def check_status(self, task_id: str) -> TaskStatus: ...
```

后续可实现 `ReplicateGenerator`、`FalAiGenerator` 等，通过配置切换。

---

## 7. 部署方案 — Vercel + Railway

**选型理由：**

- Vercel 对 Next.js 原生支持最佳（同一团队开发），零配置部署
- Railway 对 Python 服务部署简单，自动构建、自动扩缩，支持托管 PostgreSQL
- MVP 阶段不需要自管 Docker / K8s，节省运维精力
- 两者都支持 preview deployment（PR 预览），方便迭代

**部署拓扑：**

```
Vercel (前端)
  └── Next.js App
       └── 调用后端 API

Railway (后端)
  ├── FastAPI 服务
  └── PostgreSQL 数据库

Replicate (AI 服务)
  └── 图像生成 / LoRA 训练
```

---

## 8. 异步任务 — asyncio + SSE

**选型理由：**

- 图像生成等待 10-60 秒，Python asyncio 异步等待即可，不需要引入消息队列
- SSE（Server-Sent Events）实时推送生成进度和中间状态给前端
- 避免 MVP 阶段引入 Redis 依赖，保持架构简单
- 后期规模增大再引入 Celery + Redis 做任务持久化和重试

---

## 前后端通信协议

参考 Cursor / Claude Code 的 Agent 交互模式：

| 消息类型 | 方向 | 传输方式 | 说明 |
|---|---|---|---|
| 用户文本消息 | 前端 → 后端 | HTTP POST | 包含文本 + 可选附件（参考图） |
| LLM 流式文本 | 后端 → 前端 | SSE | 逐 token 推送 |
| 工具调用状态 | 后端 → 前端 | SSE | "正在生成图片..."、进度百分比 |
| 图片结果 | 后端 → 前端 | SSE | 结构化消息，包含图片 URL 列表 |
| 用户选择/反馈 | 前端 → 后端 | HTTP POST | 选择候选图 / 文字反馈 |

---

## Skill / Rules 文件格式

参考 Cursor 的方式，用 Markdown + YAML frontmatter：

```markdown
---
name: generate-ui-icon
description: 生成 UI 图标资源
triggers:
  - 图标
  - icon
  - 按钮图标
tools:
  - generate_image
  - remove_background
---

## 能力描述

当用户需要生成 UI 图标时触发本 Skill。

## 执行规则

1. 默认输出尺寸 512x512，PNG 格式，透明背景
2. 使用项目默认风格（如已设置）
3. 生成 4 张候选，展示给用户选择
```

---

## 项目目录结构

```
art-agent/
  frontend/                  # Next.js 前端
    src/
      app/                   # App Router 页面
      components/
        chat/                # 对话相关组件
        gallery/             # 图片网格 / 候选图选择
        style/               # 风格管理面板
        upload/              # 文件上传组件
      lib/                   # 工具函数
      stores/                # Zustand 状态管理

  backend/                   # Python FastAPI 后端
    app/
      api/                   # API 路由层
      agent/                 # Agent Loop 核心
        loop.py              # 主循环逻辑
        tools/               # 工具注册与实现
        memory.py            # 记忆系统
      skills/                # Skill / Rules 加载器
      models/                # SQLAlchemy 数据库模型
      services/              # AI 服务抽象层
        llm.py               # LLM 抽象接口
        image_gen.py         # 图像生成抽象接口
      storage/               # 文件存储抽象层
    skills/                  # Skill Markdown 文件目录
    rules/                   # Rules Markdown 文件目录
    tests/                   # 测试

  docs/
    art-agent/
      DECISIONS.md           # 产品决策文档
      TECH-STACK.md          # 技术选型文档（本文件）
```