crewai/QUICKSTART.md

# SDLC Agent Demo - 快速使用指南

## 项目概述

这是一个基于 **CrewAI + Qwen3.5-flash + FastAPI(SSE)** 的多智能体软件交付协同系统演示项目。

### 核心功能

- ✅ **PM Agent** - 将用户需求转化为结构化 SRS 文档
- ✅ **QA Agent** - 根据 SRS 生成自动化测试用例
- ✅ **Dev Agent** - 根据需求和测试用例实现业务代码
- ✅ **SSE 实时流** - 实时展示各智能体执行进度
- ✅ **现代化 UI** - Vue3 + TailwindCSS 单页面应用

---

## 快速启动（3 步）

### 步骤 1: 配置 API Key

```bash
# 复制环境变量模板
copy .env.example .env

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

**.env 文件内容：**
```env
DASHSCOPE_API_KEY=sk-your-api-key-here
QWEN_MODEL=qwen3.5-flash
HOST=0.0.0.0
PORT=8000
```

### 步骤 2: 启动服务

**方式 A: 使用启动脚本（Windows）**
```bash
start.bat
```

**方式 B: 手动启动**
```bash
# 激活虚拟环境（如果有）
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# 启动 FastAPI 服务
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 步骤 3: 访问应用

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

---

## 使用示例

### 输入需求示例

在首页输入框中输入以下需求：

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

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

### 预期输出

系统将依次执行：

1. **PM Agent** → 生成《软件需求规格说明书 (SRS)》
   - 功能性需求清单
   - 非功能性需求（性能、安全等）
   - 验收标准

2. **QA Agent** → 生成《测试方案与用例》
   - Pytest 测试脚本框架
   - 测试场景描述
   - 测试数据准备

3. **Dev Agent** → 生成《业务代码实现》
   - 完整的 Python 代码模块
   - 数据模型定义
   - API 接口设计

---

## API 接口说明

### 1. 启动任务

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

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

### 2. SSE流式进度

```bash
curl -N http://localhost:8000/api/v1/sdlc/stream/{task_id}
```

**事件类型：**
- `pm_start` / `pm_complete` - PM 阶段开始/完成
- `qa_start` / `qa_complete` - QA 阶段开始/完成
- `dev_start` / `dev_complete` - Dev 阶段开始/完成
- `final_result` - 最终结果
- `error` - 错误处理

### 3. 查询状态

```bash
curl http://localhost:8000/api/v1/sdlc/status/{task_id}
curl http://localhost:8000/api/v1/sdlc/result/{task_id}
```

---

## Docker 部署

### 构建镜像

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

### 运行容器

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

### 访问服务

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

---

## 常见问题

### Q1: 如何获取 DashScope API Key？

访问 https://dashscope.console.aliyun.com/ 注册账号并创建 API Key。

### Q2: 支持其他模型吗？

可以修改 `.env` 中的 `QWEN_MODEL` 参数，使用其他 OpenAI 兼容的模型。

### Q3: SSE 连接中断怎么办？

- 检查防火墙设置
- 增加超时时间（修改 `main.py` 中的 timeout 参数）
- 前端已自动实现重连机制

### Q4: 输出质量不佳？

- 调整 Temperature 参数（降低随机性）
- 优化 Prompt 描述
- 增加更详细的上下文约束

---

## 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| AI 框架 | CrewAI | >=0.85.0 |
| 大模型 | Qwen3.5-flash | via DashScope |
| Web 框架 | FastAPI | >=0.109.0 |
| 实时通信 | SSE | sse-starlette |
| 前端 | Vue3 | 3.x |
| UI 框架 | TailwindCSS | 3.x |
| 代码高亮 | Highlight.js | 11.9.0 |

---

## 项目结构

```
sdlc_agent_demo/
├── main.py                 # FastAPI 入口
├── agents/
│   ├── pm_agent.py         # PM 智能体
│   ├── qa_agent.py         # QA 智能体
│   └── dev_agent.py        # Dev 智能体
├── crews/
│   └── sdlc_crew.py        # 编排逻辑
├── models/
│   └── qwen_config.py      # 模型配置
├── static/
│   └── index.html          # 前端页面
├── .env.example            # 环境变量模板
├── Dockerfile              # Docker 配置
├── requirements.txt        # Python 依赖
└── README.md               # 详细文档
```

---

## 下一步计划

- [ ] 支持多任务并行处理
- [ ] 添加任务历史记录
- [ ] 集成代码执行沙箱
- [ ] 支持更多模型后端
- [ ] 添加认证授权机制

---

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