shiyong.qin/EPEEAIKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

大活

Browse Source
This commit is contained in:
Shin@HOME
2026-04-12 01:02:14 +08:00
parent 509487f155
commit 9b053e302b
14085 changed files with 2680009 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
docs/art-agent/DECISIONS.md Normal file
View File

@@ -0,0 +1,168 @@
# 美术 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

229
docs/art-agent/MVP-PLAN.md Normal file
View File

@@ -0,0 +1,229 @@
# 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)

287
docs/art-agent/TECH-STACK.md Normal file
View File

@@ -0,0 +1,287 @@
# 美术 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 # 技术选型文档（本文件）
```