第一次提交

2026-03-13 14:20:58 +08:00
commit 80d9b50587
16 changed files with 3832 additions and 0 deletions
--- a/USAGE_GUIDE.md
+++ b/USAGE_GUIDE.md
@@ -0,0 +1,243 @@
+# 多智能体系统使用指南
+
+## 📋 目录结构
+
+```
+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 日志
+
+---
+
+**祝您使用愉快！** 🎉