crewai/USAGE_GUIDE.md

# 多智能体系统使用指南

## 📋 目录结构

```
AI_CrewAI/
├── generated_output/        # 生成的代码和文档输出目录
│   └── task_YYYYMMDD_HHMMSS/  # 每次任务的时间戳目录
│       ├── PRD_产品需求文档.md    # 产品需求文档
│       ├── QA_测试计划.md        # 测试计划文档
│       ├── Dev_技术方案.md       # 技术方案文档
│       ├── Final_交付报告.md     # 最终交付报告
│       └── events_log.json      # 完整事件日志
├── code_docs/              # 文档目录
├── example_usage.py        # 使用示例脚本
├── main.py                # FastAPI服务入口
└── USAGE_GUIDE.md         # 本文件
```

## 🚀 快速开始

### 1. 配置 API Key

编辑 `.env` 文件，设置您的阿里百炼 API Key：

```bash
DASHSCOPE_API_KEY=sk-your-actual-api-key-here
```

获取 API Key: https://dashscope.console.aliyun.com/

### 2. 安装依赖

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

### 3. 启动服务

**方式一：直接运行 Python**
```bash
python main.py
```

**方式二：使用 uvicorn**
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

### 4. 访问服务

- **API 文档**: http://localhost:8000/docs
- **测试 UI**: http://localhost:8000/test-ui

## 📝 使用方法

### 方法一：通过 Web UI（推荐）

1. 访问 http://localhost:8000/test-ui
2. 在输入框中输入您的需求，例如：
   ```
   开发一个简单的在线待办事项应用（Todo App），包含以下功能：
   1. 用户可以注册和登录
   2. 创建、编辑、删除待办事项
   3. 标记事项为完成/未完成
   4. 按优先级和截止日期排序
   5. 基本的搜索和过滤功能
   
   技术栈要求：
   - 后端：Python FastAPI
   - 数据库：SQLite
   - 前端：简单的 HTML/CSS/JavaScript
   ```
3. 点击"启动任务"按钮
4. 实时查看各 Agent 的执行过程
5. 完成后查看生成的文档

### 方法二：通过 API 调用

使用 curl 或任何 HTTP 客户端：

```bash
# 启动任务
curl -X POST http://localhost:8000/api/run_task \
  -H "Content-Type: application/json" \
  -d '{
    "user_requirement": "开发一个博客系统",
    "skip_confirmation": true
  }'

# 返回示例：
# {"task_id":"uuid","status":"started","message":"..."}
```

然后订阅 SSE 流：

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

### 方法三：使用示例脚本

运行提供的示例脚本：

```bash
python example_usage.py
```

这会自动保存生成的内容到 `generated_output/` 目录。

## 📊 生成的内容

每个任务会生成以下文档：

### 1. PRD_产品需求文档.md
- 项目概述
- 功能需求列表（按优先级）
- 用户故事和用例
- 验收标准
- 风险评估

### 2. QA_测试计划.md
- 测试策略
- 测试用例（正常场景 + 异常场景）
- 性能测试方案
- 自动化测试建议

### 3. Dev_技术方案.md
- 系统架构设计
- 技术栈选择
- 数据库 Schema
- API 接口设计
- 核心代码实现
- 部署方案

### 4. Final_交付报告.md
- 交付摘要
- 一致性检查
- 质量评估
- 风险提示
- 后续行动建议

## 🔍 查看生成的文件

生成的文件保存在 `generated_output/task_YYYYMMDD_HHMMSS/` 目录下。

**Windows 用户**：
```powershell
# 打开最新生成的目录
explorer (Get-ChildItem generated_output -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName
```

**Linux/Mac 用户**：
```bash
# 打开最新生成的目录
xdg-open $(ls -td generated_output/task_* | head -n1)  # Linux
open $(ls -td generated_output/task_* | head -n1)      # Mac
```

或者直接在文件管理器中浏览 `generated_output/` 目录。

## 💡 实用技巧

### 1. 实时监控任务进度

在另一个终端窗口查看日志：

```bash
# Docker Compose 方式
docker-compose logs -f multi-agent-system

# 直接运行
# 日志会自动输出到控制台
```

### 2. 自定义输出目录

修改 `example_usage.py` 中的 `output_dir` 参数：

```python
await save_generated_content(task_id, output_dir="my_custom_output")
```

### 3. 批量处理多个需求

创建批处理脚本：

```python
requirements = [
    "需求 1...",
    "需求 2...",
    "需求 3..."
]

for req in requirements:
    task_id = await run_multi_agent_task(user_requirement=req)
    await save_generated_content(task_id)
```

## ⚠️ 常见问题

### Q: 为什么没有生成文件？

**A**: 确保：
1. API Key 已正确配置
2. 网络连接正常
3. 任务执行完成（看到"任务执行完成"事件）

### Q: 生成的内容在哪里？

**A**: 
- 默认在 `generated_output/task_时间戳/` 目录
- 可以通过 Web UI 直接查看
- 或在控制台查找保存路径

### Q: 如何重新查看生成的内容？

**A**: 
1. 找到对应的任务时间戳目录
2. 打开相应的 .md 文件
3. 使用 Markdown 阅读器或 VS Code 查看

### Q: 可以修改生成的文档吗？

**A**: 当然可以！生成的文档是 Markdown 格式，可以使用任何文本编辑器修改。

## 🎯 最佳实践

1. **明确需求描述**：需求越详细，生成的文档越准确
2. **指定技术栈**：明确说明使用的技术和框架
3. **设定约束条件**：如性能要求、安全要求等
4. **迭代优化**：根据生成结果调整需求描述

## 📞 技术支持

如有问题，请查看：
- API 文档：http://localhost:8000/docs
- 项目 README：README.md
- 日志输出：控制台或 Docker 日志

---

**祝您使用愉快！** 🎉