# mini-agent

**Repository Path**: lu147721/mini-agent

## Basic Information

- **Project Name**: mini-agent
- **Description**: Q 版拼豆图纸生成 Agent 工作台：用户上传图片 + 描述需求，AI 理解主体后生成 Q 版候选图 → 拼豆友好稿 → 本地引擎输出 1:1 拼豆图纸、图和 BOM（物料清单）。不是聊天机器人，而是一个"多媒体 Agent 工作台"。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Q版拼豆 Agent

一个面向“照片转拼豆图纸”的多模态 Agent 项目：上传图片和自然语言需求后，可以生成 Q版候选图、原图直出图纸、拼豆友好稿、真实色号施工图、BOM 采购清单和按需下载文件。

> 当前主项目目录：`pindou-agent/`

![工作台总览](pindou-agent/images/d9ab102f55d8d0e0b6c48836a2e8e5c5.png)

## 项目定位

```text
用户图片 + 描述
  -> 主体分析 / 抠图
  -> 需求解析
  -> Q版路线：生成候选图，等待用户选择
  -> 直出路线：跳过候选，直接转图纸
  -> 拼豆友好稿
  -> 本地图纸引擎
  -> 真实色卡映射
  -> 可拼度评分 / 自动返工
  -> 图纸 + BOM + PDF/CSV/TXT/PNG 按需下载
```

这个项目不是普通图片滤镜，也不是让大模型直接“编色号”。最终图纸由本地确定性图纸引擎生成，输出颜色必须来自真实 MARD 拼豆色卡。

## 核心功能

- Q版候选生成：支持多张候选图，用户选择后再生成最终拼豆图纸。
- 原图直出：不走 Q版候选，直接把上传图片转换成拼豆图纸。
- LangGraph 人工介入：Q版候选后使用 `interrupt/resume` 暂停和恢复。
- 图纸规格：支持 `50x50`、`70x70`、`100x100` 和自定义矩形宽高。
- 主体抠图：Q版路线和直出路线都可以单独配置是否抠主体，默认开启。
- 白底不铺豆：白底/透明背景默认转为空格，不进入 BOM。
- 真实色号：基于 MARD 色卡、感知色差匹配、限色、孤立杂点清理和低频色合并。
- 交付文件：施工图 PNG、无色号效果图 PNG、分页 PDF、BOM CSV、逐行摆豆 TXT、JSON 数据。
- 单格编辑：支持按行列换色、擦除和补豆，并自动刷新图纸和 BOM。
- 历史记录：任务列表分页展示，详情页按阶段回看文件和图片。
- 工程化能力：Redis 队列、PostgreSQL 元数据、阿里云 OSS 文件存储、API/worker 拆分、队列监控、Provider 限流、取消/重试/超时。

## 界面截图

### Q版候选选择

![Q版候选选择](pindou-agent/images/4ec62df2519d648f43592d3d37120d44.png)

### 拼豆施工图与按需下载

![拼豆施工图](pindou-agent/images/4d9e94b433fb4d4545d0112b9282e997.png)

### 历史任务列表

![历史任务列表](pindou-agent/images/649142f623e3d76d5db6deaf46db32ed.png)

### 历史任务详情与 OSS 文件档案

![历史任务详情](pindou-agent/images/892fed9b29649dfb41213f420b722927.png)

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | React 19、TypeScript、Vite、Tailwind CSS、lucide-react |
| 后端 | Python 3.12、FastAPI、Pydantic、LangChain、LangGraph |
| 图纸引擎 | Pillow、本地色卡量化、MARD 色卡、感知色差匹配 |
| 队列 | Redis |
| 数据库 | PostgreSQL、SQLAlchemy、Alembic |
| 文件存储 | 本地加工缓存、阿里云 OSS |
| AI Provider | OpenAI 兼容接口，可配置文本/视觉/生图/分割 Provider |

## 目录结构

```text
mini-agent/
  README.md
  pindou-agent/
    backend/        # FastAPI、LangGraph、图纸引擎、任务服务
    frontend/       # React 图片工作台
    docs/           # 需求、技术设计、架构、存储方案、路线图
    images/         # README 截图
    scripts/        # 跨平台启动脚本
```

## 本地启动

### 1. 准备环境

需要先安装：

- Python 3.12+
- Node.js 20+
- Docker Desktop

复制环境变量模板：

```bash
cd pindou-agent
cp backend/.env.example backend/.env
```

然后在 `backend/.env` 填入本地密钥。不要提交真实 `.env`。

关键配置：

```env
OPENAI_API_KEY=你的文本模型 Key
OPENAI_BASE_URL=https://www.fastaitoken.com/v1
OPENAI_MODEL=gpt-5.5

IMAGE_MODEL=gpt-image-2

JOB_QUEUE_BACKEND=redis
JOB_METADATA_BACKEND=postgres
ARTIFACT_STORAGE_BACKEND=local

# 接入 OSS 时再改成 oss，并补齐 OSS_*。
# ARTIFACT_STORAGE_BACKEND=oss
```

### 2. 安装依赖

macOS / Linux：

```bash
cd pindou-agent
./scripts/setup-backend.sh
cd frontend
npm install
```

Windows PowerShell：

```powershell
cd pindou-agent
.\scripts\setup-backend.ps1
.\scripts\setup-frontend.ps1
```

### 3. 启动后端 API

macOS / Linux：

```bash
cd pindou-agent
./scripts/dev-backend.sh
```

Windows PowerShell：

```powershell
cd pindou-agent
.\scripts\dev-backend.ps1
```

脚本会自动检查 Docker Desktop、Redis 和 PostgreSQL。如果本机暂时不想启动 Docker 基础设施，可以加 `--no-infra` 或 `-NoInfra`。

### 4. 启动 worker

Phase 8 后建议 API 和 worker 分进程运行。API 负责 HTTP/SSE/下载，worker 负责从 Redis 队列消费任务并执行 LangGraph。

macOS / Linux：

```bash
cd pindou-agent
./scripts/dev-worker.sh --process-count 1
```

Windows PowerShell：

```powershell
cd pindou-agent
.\scripts\dev-worker.ps1 -ProcessCount 1
```

### 5. 启动前端

macOS / Linux：

```bash
cd pindou-agent/frontend
npm run dev
```

Windows PowerShell：

```powershell
cd pindou-agent
.\scripts\dev-frontend.ps1
```

访问地址：

```text
前端工作台: http://127.0.0.1:5173
后端 API:  http://127.0.0.1:8000
Swagger:   http://127.0.0.1:8000/docs
```

## 常用命令

```bash
# 后端测试
cd pindou-agent/backend
PYTHONPATH=. .venv/bin/pytest

# 前端构建
cd pindou-agent/frontend
npm run build

# 本地缓存清理：只清理已上传 OSS 且超过 TTL 的加工缓存
cd pindou-agent/backend
./scripts/cleanup-cache.sh 604800
```

## 存储设计

生产化目标是：

- Redis：只放任务队列和短期状态。
- PostgreSQL：保存任务状态、事件、artifact 索引、Provider 运行记录、LangGraph checkpoint。
- OSS：保存原图、参考板、候选图、友好稿、图纸 PNG/PDF/CSV/TXT/JSON。
- `backend/storage`：只作为本地加工缓存、调试快照和 fallback，不作为最终业务数据源。

详细方案见：

- [PostgreSQL 与 OSS 存储工程化设计](pindou-agent/docs/POSTGRES_OSS_STORAGE_DESIGN.md)
- [架构与模块边界](pindou-agent/docs/ARCHITECTURE.md)

## 关键文档

- [需求文档](pindou-agent/docs/REQUIREMENTS.md)
- [技术设计](pindou-agent/docs/TECHNICAL_DESIGN.md)
- [路线图](pindou-agent/docs/ROADMAP.md)
- [PostgreSQL 与 OSS 存储工程化设计](pindou-agent/docs/POSTGRES_OSS_STORAGE_DESIGN.md)
- [前端线框图](pindou-agent/docs/UI_WIREFRAME.md)

## 当前进度

当前版本约为 `v0.9`，已完成从 MVP 到工程化运行的核心闭环：

- Q版候选生成和人工选择。
- 原图直出。
- 多规格拼豆图纸。
- BOM、PDF、CSV、逐行文本和图片按需下载。
- 历史列表与详情。
- PostgreSQL + OSS 存储升级。
- Redis 队列和 API/worker 拆分。
- Provider 限流、任务取消/重试/超时和队列监控。

后续重点会继续围绕生产部署、用户体系、权限、费用控制、图纸质量算法和更完整的监控告警推进。