shiyong.qin/EPEEAIKit

Fork 0

Files

Shin@HOME 9b053e302b 大活

2026-04-12 01:02:14 +08:00

9.0 KiB

Raw Blame History

美术 Agent 工具 — 技术选型

本文档记录所有技术选型决策，与 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

抽象接口设计：

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 的风格训练做好准备

抽象层设计：

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：

---
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          # 技术选型文档（本文件）

9.0 KiB Raw Blame History Unescape Escape

美术 Agent 工具 — 技术选型

选型总览

1. 前端 — Next.js (React)

2. 后端 — Python FastAPI

3. Agent 框架 — 自建 Agent Loop

4. 数据库 — PostgreSQL

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

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

7. 部署方案 — Vercel + Railway

8. 异步任务 — asyncio + SSE

前后端通信协议

Skill / Rules 文件格式

项目目录结构

9.0 KiB

Raw Blame History