基于对话生成前端页面的AI Agent系统，采用MCP（Model-Context-Protocol）架构，实现从自然语言到可运行代码的完整自动化流程。

• 🤖 智能代码生成：通过自然语言对话生成前端页面代码
• 🛡️ 安全沙箱执行：基于Docker的隔离环境，安全执行所有代码
• 🔄 自动构建部署：自动构建项目并实时预览结果
• 🔧 错误自动修复：构建失败时智能分析和修复错误
• 📝 版本控制集成：深度集成Git，支持版本切换、追溯和下载
• 💻 专业IDE体验：集成文件树、Monaco编辑器和实时预览

• 🎯 双LLM架构：deepseek-r1（需求分析）+ Gemini-Flash-2.5（代码生成）
• ⚡ 极速响应：基于Vite的快速构建，秒级预览
• 🎨 美观界面：现代IDE风格UI，深色主题
• 📦 一键部署：Docker Compose一键启动所有服务
• 🔌 RESTful API：完整的API接口，支持二次开发

┌─────────────────────────────────────────────────────────────┐
│                         用户界面层                              │
│  React + TypeScript + Vite + Monaco Editor + Tailwind CSS   │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP/WebSocket
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                         API网关层                              │
│                    FastAPI + CORS + 验证                       │
└──────────────────────────┬──────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  需求分析层    │  │  代码生成层    │  │  工作区管理   │
│  deepseek-r1  │  │   Gemini      │  │  Docker + Git │
└───────────────┘  └───────────────┘  └───────────────┘

技术	版本	用途
Python	3.11+	主要编程语言
FastAPI	0.109+	Web框架
Docker	Latest	容器化执行环境
GitPython	Latest	程序化版本控制
httpx	Latest	异步HTTP客户端
pydantic	Latest	数据验证

技术	版本	用途
React	18+	UI框架
TypeScript	5+	类型安全
Vite	5+	构建工具
Tailwind CSS	3+	CSS框架
Monaco Editor	Latest	代码编辑器
Zustand	4+	状态管理
TanStack Query	5+	数据获取

确保你的环境已安装以下软件：

软件	最低版本	检查命令
Docker	20.10+	docker --version
Docker Compose	2.0+	docker compose version
Python	3.11+	python --version
Node.js	18+	node --version

本项目需要以下API密钥（均有免费额度）：

1. DeepSeek API Key - 获取地址

   • 注册并登录
   • 进入API管理页面
   • 创建新密钥

2. Gemini API Key - 获取地址

   • 登录Google账号
   • 创建新项目
   • 生成API密钥

# 1. 克隆仓库
git clone <repository-url>
cd ai-agent

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的API密钥

# 3. 启动所有服务
docker compose up -d

# 4. 查看服务状态
docker compose ps

# 5. 查看日志
docker compose logs -f

服务启动后：

• 前端：http://localhost:5173
• 后端API：http://localhost:8000
• API文档：http://localhost:8000/docs

# 1. 克隆仓库
git clone <repository-url>
cd ai-agent

# 2. 运行启动脚本
chmod +x start.sh
./start.sh

后端服务（终端1）

cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入API密钥

# 启动服务
python main.py

前端服务（终端2）

cd frontend

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 启动开发服务器
npm run dev

# Docker Compose
docker compose down

# 手动启动：在终端按 Ctrl+C

1. 打开应用

   • 访问 http://localhost:5173
   • 你将看到一个三栏IDE风格的界面：
     • 左侧：对话面板 + 版本历史
     • 中间：文件树 + 代码编辑器
     • 右侧：实时预览

2. 输入需求

   • 在左下角的聊天框中输入你的需求
   • 示例：

     创建一个蓝色的登录按钮
     创建一个计数器应用
     创建一个待办事项列表
     

3. AI处理

   • 系统自动分析你的需求（deepseek-r1）
   • 生成代码（Gemini）
   • 写入Docker沙箱
   • 自动构建项目
   • 启动预览服务

4. 查看结果

   • 右侧预览面板自动显示生成的页面
   • 中间文件树显示所有生成的文件
   • 点击文件可在编辑器中查看代码

用户：把按钮改成红色
用户：添加一个计数器功能
用户：修改背景为深色

• 查看历史：左侧版本历史面板显示所有Git提交
• 切换版本：点击任意版本的"切换"按钮
• 下载代码：点击版本历史右上角的"下载"按钮，或单个版本的下载图标

• 点击文件树中的文件
• 在中间的Monaco编辑器中查看和修改代码
• 支持语法高亮、自动补全等IDE功能

• 刷新预览：点击预览面板的刷新按钮
• 新标签页：点击"在新标签页打开"按钮
• 全屏预览：点击全屏按钮切换全屏模式

文档	描述
开发指南	完整的开发与使用文档（推荐先看）
快速开始	5分钟上手指南
系统架构	MCP架构和详细设计
使用示例	常见场景和示例
部署指南	生产环境部署
贡献指南	如何参与开发
API文档	完整API参考

端点	方法	描述
/api/v1/chat	POST	发送聊天消息，生成代码
/api/v1/fix-error	POST	修复构建错误
/api/v1/versions	GET	获取版本历史
/api/v1/checkout	POST	切换版本
/api/v1/download	GET	下载代码（ZIP）
/api/v1/project-state	GET	获取项目状态
/api/v1/file-content	GET	获取文件内容
/api/v1/preview/{sessionId}	GET	预览页面

完整的交互式API文档：http://localhost:8000/docs

ai-agent/
├── backend/                    # 后端服务
│   ├── api/                   # API路由
│   │   └── router.py         # 端点定义
│   ├── config/                # 配置
│   │   └── settings.py       # 应用配置
│   ├── llm/                   # LLM客户端
│   │   ├── deepseek_client.py
│   │   └── gemini_client.py
│   ├── services/              # 业务逻辑
│   │   ├── agent_core.py     # 代理核心
│   │   └── workspace_manager.py  # 工作区管理
│   ├── Dockerfile            # Docker镜像
│   ├── requirements.txt       # Python依赖
│   └── main.py               # 应用入口
├── frontend/                  # 前端应用
│   ├── src/
│   │   ├── api/              # API客户端
│   │   ├── components/       # React组件
│   │   │   ├── ChatPanel.tsx
│   │   │   ├── CodeEditor.tsx
│   │   │   ├── PreviewPanel.tsx
│   │   │   ├── VersionHistory.tsx
│   │   │   └── Layout.tsx
│   │   ├── store/            # 状态管理
│   │   │   └── useStore.ts
│   │   ├── lib/              # 工具函数
│   │   ├── App.tsx           # 主应用
│   │   └── main.tsx          # 入口文件
│   ├── Dockerfile            # Docker镜像
│   ├── nginx.conf            # Nginx配置
│   ├── package.json          # Node依赖
│   └── vite.config.ts        # Vite配置
├── docs.md                   # 产品设计文档
├── ARCHITECTURE.md           # 系统架构
├── QUICKSTART.md             # 快速开始
├── EXAMPLES.md              # 使用示例
├── DEPLOYMENT.md            # 部署指南
├── CONTRIBUTING.md          # 贡献指南
├── .env.example             # 环境变量模板
└── docker-compose.yml       # Docker编排

# 基础配置
DEBUG=True                  # 调试模式
HOST=0.0.0.0               # 监听地址
PORT=8000                  # 监听端口

# LLM API密钥
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
GEMINI_API_KEY=AIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# CORS配置
CORS_ORIGINS=["http://localhost:5173","http://localhost:3000"]

# Docker配置
DOCKER_BASE_IMAGE=node:20-alpine
VITE_PORT=4173
PREVIEW_PORT_RANGE=(5000, 6000)

VITE_API_BASE_URL=http://localhost:8000

本系统采用多重安全措施：

• ✅ Docker沙箱 - 完全隔离的执行环境，防止恶意代码
• ✅ MCP架构 - 分离"大脑"与"执行器"，降低风险
• ✅ API网关 - 统一入口和认证
• ✅ 输入验证 - 严格的参数验证
• ✅ 速率限制 - 防止API滥用
• ✅ CORS控制 - 限制跨域访问

# 检查Docker状态
docker ps

# 查看容器日志
docker logs <container_id>

# 查看特定服务日志
docker compose logs backend
docker compose logs frontend

# 清理旧容器
docker ps -a | grep ai-agent | awk '{print $1}' | xargs docker rm -f

# 清理系统资源
docker system prune -a

# 查看应用日志
tail -f backend/logs/app.log

# 检查端口占用
lsof -i :8000  # Mac/Linux
netstat -ano | findstr :8000  # Windows

# 测试API连接
curl http://localhost:8000/health

# 清理缓存
cd frontend
rm -rf node_modules .vite
npm install

# 检查端口占用
lsof -i :5173

# 重新构建
npm run build

• 确认API密钥正确填入 .env 文件
• 检查API密钥是否有效且未过期
• 确认API额度未用完
• 重新启动服务使配置生效

欢迎贡献！请查看贡献指南了解详情。

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

• DeepSeek - 提供强大的推理能力
• Google Gemini - 提供优秀的代码生成能力
• Vite - 极速的前端构建工具
• FastAPI - 现代化的Python Web框架
• Monaco Editor - 强大的代码编辑器

• GitHub Issues: 提交问题
• 文档: 完整文档
• 邮箱: your-email@example.com

• React文档
• TypeScript文档
• FastAPI文档
• Docker文档
• Tailwind CSS文档

---

⭐ 如果这个项目对你有帮助，请给它一个星标！