AgentOS Base v7.0

分布式多智能体编排平台 —— 从单 Agent 对话到多 Agent 协同工作流

---

核心功能

多智能体工作流引擎 基于 LangGraph 状态图编排多 Agent 协同：Planner 拆解任务 → Supervisor 调度 → Executor 并行执行。支持可视化 DAG 画布拖拽编排，实时流式输出。	AI 图像创作工坊 集成 Gemini / DALL-E / Qwen / Midjourney / Flux 五大模型，支持文生图、图像编辑、AI 换装试衣。统一的多模型切换与对比体验。
RAG 知识库检索增强 基于 Milvus 向量数据库的文档检索管线：PDF/Word/音频多格式解析 → 分块嵌入 → 语义检索 → 幻觉评分过滤 → 上下文注入。	Temporal 分布式任务编排 长时间运行任务（视频生成、批量处理）通过 Temporal Workflow 调度，支持重试、超时、断点续跑。Worker 可水平扩缩容。
MCP 工具协议集成 实现 Model Context Protocol 标准，动态发现与注册外部工具（浏览器操控、金融数据、代码沙箱），Agent 按需调用。	更多功能模块 智能 PPT 生成 · 量化回测分析 · 时尚换装工坊 · 资产素材库 · WebSocket 实时协同 · 项目空间管理

---

产品截图

多智能体工作流 DAG 画布	AI 图像批量生成
Agent 自动拆解任务为 DAG 节点，支持并行执行与状态追踪	多模型并发生图，画布自由编排，支持 Gemini / DALL-E / Flux 等

FashionAI 智能试衣	Agent 对话交互
上传服装图片一键试穿，预设风格模板，支持自然语言描述	Agent Alita 驱动的对话式工作流，实时流式输出

图像工坊无限画布	Agent 智能任务规划
无限画布自由拖拽排布，多张图像同时生成与对比	Agent 自动分析需求，规划工作流节点与模型分配策略

Agent 实时生成	批量任务执行与调试
对话指令触发工作流，实时显示节点生成进度	批量任务提交与执行状态追踪，内置 Agent Manager 调试面板

---

系统架构

                    ┌─────────────┐
                    │   Nginx     │  :80
                    │  (Gateway)  │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     ┌────────▼────────┐    ┌──────────▼──────────┐
     │  React Frontend │    │   FastAPI Backend    │
     │  (Vite + TS)    │    │   (Async, REST/WS)  │
     │  :5173          │    │   :3002              │
     └─────────────────┘    └──────────┬──────────┘
                                       │
                 ┌─────────────────────┼─────────────────────┐
                 │                     │                     │
      ┌──────────▼──────┐  ┌──────────▼──────┐  ┌──────────▼──────┐
      │   LangGraph     │  │   Temporal       │  │   MCP Server    │
      │   Agent Engine  │  │   Workflow Engine │  │   Tool Registry │
      │                 │  │                   │  │                 │
      │ Planner         │  │ Media Workflow    │  │ Browser Control │
      │ Supervisor      │  │ Session Sync      │  │ Finance Data    │
      │ Executor        │  │ Batch Processing  │  │ Code Sandbox    │
      └────────┬────────┘  └────────┬─────────┘  └─────────────────┘
               │                    │
      ┌────────▼────────────────────▼────────┐
      │          Service Layer               │
      │  RAG Pipeline │ File Storage │ LLM   │
      │  Session Mgmt │ Project Mgmt │ Cache │
      └────────────────────┬─────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
   ┌─────▼─────┐   ┌──────▼──────┐   ┌──────▼──────┐
   │ PostgreSQL │   │    Redis    │   │   Milvus    │
   │   16       │   │    7        │   │  (Vector)   │
   └───────────┘   └─────────────┘   └─────────────┘

目录结构

AgentOS_Base_v7.0/
├── backend/                    # Python 后端
│   ├── app/
│   │   ├── api/v1/             # RESTful + WebSocket 端点
│   │   ├── agents/langgraph/   # LangGraph 多智能体 (Planner/Supervisor/Executor)
│   │   ├── services/           # 业务层 (RAG, Session, Project, File)
│   │   ├── workflows/          # Temporal Workflow 定义
│   │   ├── skills/             # 技能插件 (PPT, 金融分析)
│   │   ├── core/               # 配置、数据库、缓存、LLM 客户端
│   │   └── worker.py           # Temporal Worker 入口
│   ├── alembic/                # 数据库迁移
│   └── tests/
├── frontend/                   # React 前端
│   ├── components/             # UI 组件 (Canvas, Chat, Workflow)
│   ├── pages/                  # 路由页面 (13 个功能模块)
│   ├── hooks/                  # 自定义 Hooks (WebSocket, Agent 事件)
│   ├── services/               # API 客户端 + Agent SDK
│   └── contexts/               # 全局状态 (Auth, MultiSelect)
├── mcp-server/                 # MCP 工具服务
├── scripts/                    # 启动/部署/诊断脚本
├── deploy/k8s/                 # Kubernetes Helm Chart
├── docker-compose.yml
├── Makefile
└── .env.example                # 环境变量模板

---

技术栈

层	技术	选型理由
前端	React 18 + Vite + TypeScript + Tailwind	高性能 SPA，HMR 热重载，类型安全
后端框架	FastAPI (async) + Pydantic v2	原生异步，自动 OpenAPI 文档，高性能
智能体编排	LangGraph 状态图	有向图建模 Agent 协作，支持条件分支、并行、人机交互中断
任务调度	Temporal (Workflow + Activities)	长任务持久化执行，自动重试，支持分布式 Worker 扩缩容
工具协议	MCP (Model Context Protocol)	标准化 Agent-Tool 交互，动态工具注册与发现
数据库	PostgreSQL 16 + SQLAlchemy Async ORM	ACID 事务，Alembic 迁移管理
向量检索	Milvus + 自研 RAG Pipeline	语义检索 + 幻觉评分 + 查询重写
缓存/消息	Redis 7 (Cache + Pub/Sub)	LLM 响应缓存，WebSocket 广播
实时通信	WebSocket (原生)	Agent 流式输出，画布协同
部署	Docker Compose / Kubernetes (Helm)	本地一键启动到云原生弹性伸缩

---

快速开始

前置要求

• Docker Desktop (推荐 4.x+) 且已启动
• Python 3.10+ (本地开发模式需要)
• Node.js 18+ + npm (本地开发模式需要)
• uv (Python 包管理，pip install uv)

环境配置

cp .env.example .env
# 编辑 .env，至少配置一个 AI 模型的 API Key
# 支持的模型：Gemini / OpenAI / Qwen / DeepSeek / Flux / Midjourney

方式一：混合开发模式（推荐本地开发）

Docker 运行基础设施（DB、Redis），前后端本地运行，支持热重载。

make start              # 默认 mode=single-dev

此命令会：

1. 启动 Docker 容器：PostgreSQL、Redis、PgBouncer 等
2. 在 iTerm 中自动打开分屏窗口运行后端 API (:3002) 和前端 (:5173)

启动后访问：http://localhost:5173

默认管理员账号：admin@example.com / Admin12345

方式二：Docker 全量容器化

make start mode=single  # 全量 Docker 容器化
make logs               # 查看日志
make stop               # 停止

启动后访问：前端 http://localhost | API 文档 http://localhost:3002/docs

方式三：纯手动启动

# 1. 基础设施
docker-compose up -d db redis

# 2. 后端
cd backend
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 3002 --reload

# 3. 前端（新终端）
cd frontend
npm install && npm run dev    # :5173

---

AI 模型配置

在 .env 中配置所需模型的 API Key，未配置的模型将在前端选择器中标记为「未配置」。

模型	功能	环境变量前缀
Google Gemini	文生图、图编辑、换装、LLM 对话	VITE_GEMINI_*
OpenAI DALL-E	文生图、图编辑	VITE_OPENAI_*
Qwen 通义千问	文生图、图编辑	VITE_QWEN_*
DeepSeek	LLM 对话、推理	VITE_DEEPSEEK_*
Flux	文生图	VITE_FLUX_*
GPT Image	文生图 (sora-image)	VITE_GPT_IMAGE_*
Midjourney	文生图	VITE_MIDJOURNEY_*
Imagen	文生图	VITE_IMAGEN_*
Sora / Veo	视频生成	VITE_SORA_* / VITE_VEO_*

详见 .env.example 中每个模型的完整配置说明。

---

Makefile 命令

命令	说明
make start	启动服务 (默认 mode=single-dev，混合开发)
make start mode=single	Docker 全量单体启动
make start mode=single-dev	Docker 基础设施 + 本地前后端
make start mode=cluster-dev	本地集群模式，worker_count=N 控制 Worker 数
make start mode=prod	生产部署 (Helm + values-prod.yaml)
make stop	停止服务并清理容器
make clean	深度清理（含数据卷）
make logs	查看容器日志
make status	查看容器状态
make secrets	交互式生成生产环境 Secrets
make init-prod	一键初始化生产环境 (Secrets + Deploy)

后端开发命令（backend/ 目录下）

命令	说明
make install	安装 Python 依赖 (含 dev 工具)
make dev	启动 API 服务 (:3002，热重载)
make worker	启动 Temporal Worker
make test	运行 Pytest 单元测试
make lint	Ruff 代码检查
make format	Ruff 自动格式化

---

部署

Docker Compose（个人 / 团队开发）

make start mode=single              # 个人/演示
make start mode=cluster-dev worker_count=5  # 团队开发，多 Worker

自建 K8s（Operator 模式）

适用于手动管理服务器，通过 Operator 在集群内部署有状态服务。

准备工作：

• 3 台 Linux 服务器（Ubuntu/Rocky），网络互通
• K3s 集群已安装，kubectl 可连接
• 本地已安装 helm

# 1. 安装 Operators（仅需一次）
kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.22/releases/cnpg-1.22.0.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml
helm repo add temporal https://go.temporal.io/helm-charts && helm repo update

# 2. 构建镜像
export REGISTRY="registry.cn-hangzhou.aliyuncs.com/your-org"
docker build -t $REGISTRY/api-python:latest -f docker/Dockerfile.target .
docker build -t $REGISTRY/gateway-nginx:latest -f docker/Dockerfile.frontend .
docker push $REGISTRY/api-python:latest && docker push $REGISTRY/gateway-nginx:latest

# 3. 部署
cd deploy/k8s
helm install studio . \
  --set global.environment=prod \
  --set database.mode=operator \
  --set temporal.mode=self-hosted \
  --set api.image.repository=$REGISTRY/api-python \
  --set gateway.image.repository=$REGISTRY/gateway-nginx

# 4. 验证
kubectl get pods
# 预期：studio-api-xxx, studio-gateway-xxx, studio-db-1/2/3, temporal-*

# 扩容 Worker
helm upgrade studio . --set worker.replicaCount=10

Serverless K8s（ACK Serverless / AWS Fargate）

适用于无需管理节点的 Serverless Kubernetes 环境，使用外部云服务存储数据。

云资源准备：

• RDS PostgreSQL Serverless 版
• Redis 托管版
• NAT Gateway（拉取公网镜像）

export REGISTRY="registry.cn-hangzhou.aliyuncs.com/your-org"
export DB_HOST="pgm-xxxx.pg.rds.aliyuncs.com"
export DB_PASS="MySecretPass123"
export REDIS_HOST="r-xxxx.redis.rds.aliyuncs.com"

cd deploy/k8s
helm install studio . \
  --set global.serverless.enabled=true \
  --set database.external.host=$DB_HOST \
  --set database.external.password=$DB_PASS \
  --set redis.enabled=false \
  --set redis.external.host=$REDIS_HOST \
  --set api.image.repository=$REGISTRY/api-python \
  --set gateway.image.repository=$REGISTRY/gateway-nginx

Serverless 优势：Worker 空闲时自动缩容到 0，计算费用归零。

部署方案对比

场景	方案	命令
个人/演示	Docker Compose 单体	make start mode=single
团队开发	Docker Compose 集群	make start mode=cluster-dev worker_count=5
生产 (自建 K8s)	Helm + CNPG Operator	make start mode=prod
生产 (Serverless)	Helm + 云托管服务	见上方 Serverless 部署

---

监控与运维

Docker Compose 模式下的服务端口：

服务	端口	说明
前端	5173 (开发) / 80 (生产)	React SPA
API	3002	FastAPI + OpenAPI 文档 (/docs)
PostgreSQL	5432	主数据库
Redis	6379	缓存/消息
Temporal UI	8080	工作流可视化
MinIO Console	9001	S3 对象存储管理
Grafana	3001	监控仪表盘
Jaeger	16686	分布式追踪

安全与密钥

生产环境通过 Docker Secrets 管理敏感信息：

Secret	路径
postgres_password	./.secrets/postgres_password
redis_password	./.secrets/redis_password
jwt_secret	./.secrets/jwt_secret

使用 make secrets 交互式生成。

---

开发规范

• 代码风格：Ruff lint + format（make lint / make format）
• 异步优先：所有 I/O 操作必须 async
• 服务分层：业务逻辑在 services/，不写在路由中
• 数据库变更：SQLAlchemy Async ORM + Alembic 迁移
• API 响应格式：统一使用 create_structured_error() (后端) 和 apiFetch (前端)
• 端口管理：新增服务前查阅 docs/PORT_REGISTRY.md，注册端口后使用环境变量引用
• 提交规范：Conventional Commits (feat: / fix: / refactor:)

git checkout -b feature/your-feature
git commit -m "feat: Add your feature"
git push origin feature/your-feature

---

贡献指南

1. Fork 仓库并 Clone 到本地
2. 安装依赖：后端 cd backend && make install，前端 cd frontend && npm install
3. 创建分支：git checkout -b feature/amazing-feature
4. 提交代码：遵循 Conventional Commits 规范
5. 推送并创建 Pull Request

---

License

MIT