crewai/README.md

# SDLC Agent Demo - 多智能体端到端软件交付协同系统

基于 **CrewAI + Qwen3.5-flash + FastAPI(SSE)** 构建的企业级研发提效演示系统，模拟从需求分析→测试用例→代码实现的完整 SDLC 流程。

## 📋 项目特性

- ✅ **多智能体协同**：PM Agent、QA Agent、Dev Agent 顺序流水线作业
- ✅ **实时进度追踪**：SSE流式输出各阶段执行状态
- ✅ **Qwen3.5-flash**：通过 DashScope OpenAI 兼容 API 调用
- ✅ **现代化前端**：Vue3 + TailwindCSS + 代码高亮
- ✅ **任务持久化**：内存级任务状态管理
- ✅ **Docker 支持**：一键容器化部署

## 🏗️ 系统架构

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  PM Agent   │────▶│  QA Agent    │────▶│  Dev Agent  │
│ 需求分析师  │     │ 测试架构师   │     │ 全栈工程师  │
└─────────────┘     └──────────────┘     └─────────────┘
       │                    │                      │
       ▼                    ▼                      ▼
   SRS 文档            测试用例              业务代码
```

## 📁 项目结构

```
sdlc_agent_demo/
├── main.py                 # FastAPI 入口
├── agents/
│   ├── __init__.py
│   ├── pm_agent.py         # PM 智能体定义
│   ├── qa_agent.py         # QA 智能体定义
│   └── dev_agent.py        # Dev 智能体定义
├── crews/
│   └── sdlc_crew.py        # CrewAI 编排逻辑
├── models/
│   └── qwen_config.py      # Qwen3.5-flash 配置
├── static/
│   └── index.html          # 测试页面
├── requirements.txt
├── .env.example            # 环境变量模板
├── Dockerfile
└── README.md
```

## 🚀 快速启动

### 方法一：本地运行

#### 1. 创建虚拟环境

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

#### 2. 安装依赖

```bash
pip install -r requirements.txt
```

#### 3. 配置环境变量

```bash
# 复制模板
cp .env.example .env

# 编辑 .env 文件，填入你的 DashScope API Key
# 获取 API Key: https://dashscope.console.aliyun.com/
```

**.env 文件内容：**
```env
DASHSCOPE_API_KEY=your_dashscope_api_key_here
QWEN_MODEL=qwen3.5-flash
HOST=0.0.0.0
PORT=8000
```

#### 4. 启动服务

```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

#### 5. 访问测试页面

打开浏览器访问：http://localhost:8000/static/index.html

### 方法二：Docker 运行

#### 1. 构建镜像

```bash
docker build -t sdlc-agent-demo .
```

#### 2. 运行容器

```bash
docker run -d \
  -p 8000:8000 \
  -e DASHSCOPE_API_KEY=your_api_key \
  --name sdlc-demo \
  sdlc-agent-demo
```

#### 3. 访问服务

http://localhost:8000/static/index.html

## 📡 API 接口

### 1. 启动 SDLC 流程

**请求：**
```http
POST /api/v1/sdlc/start
Content-Type: application/json

{
  "requirement": "开发一个用户管理系统，支持增删改查功能"
}
```

**响应：**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}
```

### 2. SSE流式进度

**请求：**
```http
GET /api/v1/sdlc/stream/{task_id}
Accept: text/event-stream
```

**SSE事件格式：**
```javascript
event: pm_start
data: {"stage": "需求分析", "status": "started", "timestamp": "2026-01-15T10:30:00Z"}

event: pm_complete
data: {"stage": "需求分析", "content": "SRS 文档...", "status": "completed", "timestamp": "2026-01-15T10:35:00Z"}

event: final_result
data: {"stage": "交付完成", "status": "success", ...}
```

### 3. 查询任务状态

```http
GET /api/v1/sdlc/status/{task_id}
```

### 4. 获取任务结果

```http
GET /api/v1/sdlc/result/{task_id}
```

## 🤖 智能体角色

### PM Agent（产品经理）
- **角色**：资深产品需求分析师
- **职责**：将用户需求转化为结构化 SRS 文档
- **输出**：功能性需求、非功能性需求、验收标准

### QA Agent（测试工程师）
- **角色**：高级测试架构师
- **职责**：根据 SRS 生成自动化测试用例
- **输出**：Pytest 测试脚本、测试场景

### Dev Agent（开发工程师）
- **角色**：全栈软件工程师
- **职责**：根据 SRS 和测试用例实现业务代码
- **输出**：可运行的 Python 代码模块

## 💡 使用示例

### 示例需求输入

```
开发一个在线书签管理系统，需要包含以下功能：
1. 用户注册和登录（支持邮箱验证）
2. 书签的添加、编辑、删除
3. 书签分类和标签管理
4. 书签搜索功能
5. 导出/导入书签（HTML 格式）
6. 响应式设计，支持移动端访问

性能要求：
- 页面加载时间 < 2 秒
- 支持并发用户数 > 1000
```

### 预期输出

1. **PM Agent** → 软件需求规格说明书（包含功能列表、验收标准）
2. **QA Agent** → Pytest 测试用例（覆盖所有核心功能）
3. **Dev Agent** → 完整的 Python 实现代码（FastAPI + SQLite）

## 🔧 配置说明

### 模型配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `QWEN_MODEL` | `qwen3.5-flash` | 模型名称 |
| `QWEN_TEMPERATURE` | `0.7` | 温度参数 (0-1) |
| `QWEN_MAX_TOKENS` | `4096` | 最大生成长度 |

### 服务器配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8000` | 监听端口 |
| `LOG_LEVEL` | `info` | 日志级别 |

## 🧪 测试与验证

### API 测试（使用 curl）

```bash
# 1. 启动任务
curl -X POST http://localhost:8000/api/v1/sdlc/start \
  -H "Content-Type: application/json" \
  -d '{"requirement": "开发一个简单的待办事项应用"}'

# 2. 查看 SSE流（新终端）
curl -N http://localhost:8000/api/v1/sdlc/stream/{task_id}

# 3. 健康检查
curl http://localhost:8000/health
```

## ⚠️ 注意事项

1. **API Key 安全**：不要将 `.env` 文件提交到版本控制系统
2. **网络要求**：需要访问 DashScope API 服务
3. **资源消耗**：每个任务约消耗 10,000-50,000 tokens
4. **超时设置**：SSE 连接默认超时 120 秒，可根据需要调整

## 🛠️ 故障排查

### 问题 1：无法连接到 DashScope API

**解决方案：**
- 检查 API Key 是否正确
- 确认网络连接正常
- 验证账户余额充足

### 问题 2：SSE 连接中断

**解决方案：**
- 检查防火墙设置
- 增加超时时间
- 启用前端自动重连机制

### 问题 3：智能体输出质量不佳

**解决方案：**
- 调整 Temperature 参数（降低随机性）
- 优化 Prompt 描述
- 增加上下文约束

## 📝 许可证

本项目仅供学习和演示用途。

## 🔗 相关链接

- [CrewAI 官方文档](https://docs.crewai.com/)
- [DashScope 控制台](https://dashscope.console.aliyun.com/)
- [FastAPI 文档](https://fastapi.tiangolo.com/)
- [Vue3 文档](https://vuejs.org/)

---

**Built with ❤️ using CrewAI + Qwen3.5-flash + FastAPI**