288 lines
9.0 KiB
Markdown
288 lines
9.0 KiB
Markdown
# 美术 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 # 技术选型文档（本文件）
|
||
```
|