Skip to content

SETUP.md

Latest commit

 

History

History
197 lines (158 loc) · 4.29 KB

SETUP.md

File metadata and controls

197 lines (158 loc) · 4.29 KB

DeepResearch Agent - 设置指南

项目结构

deepresearch-agent/
├── backend/                 # Python FastAPI 后端
│   ├── app/
│   │   ├── api/            # API 路由
│   │   ├── models/         # 数据模型
│   │   ├── middleware/     # 中间件
│   │   └── main.py         # 主应用
│   └── requirements.txt    # Python 依赖
├── frontend/               # React 前端
│   ├── src/
│   │   ├── components/     # React 组件
│   │   ├── pages/          # 页面组件
│   │   ├── services/       # API 和 WebSocket 服务
│   │   └── App.js          # 主应用
│   └── package.json        # Node.js 依赖
├── README.md               # 项目说明
├── MODULES.md              # 模块详细说明
└── start_backend.py        # 后端启动脚本

快速开始

1. 环境要求

  • Python 3.9+
  • Node.js 16+
  • npm 或 yarn

2. 后端设置

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

# 启动后端服务器
cd ..
python start_backend.py

后端将在 http://localhost:8000 启动

3. 前端设置

# 安装 Node.js 依赖
cd frontend
npm install

# 启动前端开发服务器
npm start

前端将在 http://localhost:3000 启动

功能特性

已实现功能

✅ 后端 API

  • FastAPI 框架
  • WebSocket 实时通信
  • 研究会话管理
  • 聊天接口
  • 报告生成和管理
  • RESTful API 设计

✅ 前端界面

  • React 18 + Material-UI
  • 响应式设计
  • 实时聊天界面
  • 研究进度跟踪
  • 报告查看和管理
  • WebSocket 集成

✅ 核心模块

  • 研究会话管理
  • 实时进度更新
  • 聊天机器人交互
  • 报告生成系统
  • 用户界面导航

待实现功能

🔄 AI 集成

  • LLM 模型集成 (OpenAI/本地模型)
  • 智能查询分析
  • 内容总结和分析

🔄 数据源集成

  • 网页爬虫
  • 学术数据库
  • 新闻 API
  • 搜索引擎集成

🔄 高级功能

  • 用户认证系统
  • 数据库持久化
  • 缓存系统
  • 部署配置

API 接口

研究 API

  • POST /api/research/start - 开始新研究
  • GET /api/research/{id}/status - 获取研究状态
  • PUT /api/research/{id}/pause - 暂停研究
  • DELETE /api/research/{id} - 取消研究

聊天 API

  • POST /api/chat/message - 发送聊天消息
  • GET /api/chat/history/{session_id} - 获取聊天历史

报告 API

  • GET /api/reports/ - 获取报告列表
  • GET /api/reports/{id} - 获取特定报告
  • POST /api/reports/{id}/export - 导出报告

WebSocket 事件

  • chat_message - 聊天消息
  • start_research - 开始研究
  • research_progress - 研究进度更新
  • research_completed - 研究完成

开发指南

添加新的 API 端点

  1. 在 backend/app/api/ 中创建新的路由文件
  2. 在 backend/app/main.py 中注册路由
  3. 在 frontend/src/services/api.js 中添加对应的客户端方法

添加新的前端页面

  1. 在 frontend/src/pages/ 中创建新页面组件
  2. 在 frontend/src/App.js 中添加路由
  3. 在 frontend/src/components/Navbar.js 中添加导航链接

WebSocket 消息处理

  1. 在后端 main.py 的 websocket_endpoint 中处理新消息类型
  2. 在前端 websocket.js 中添加对应的事件处理

测试

后端测试

cd backend
python -m pytest tests/

前端测试

cd frontend
npm test

部署

Docker 部署

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

生产环境

  1. 设置环境变量
  2. 配置数据库连接
  3. 设置 Redis 缓存
  4. 配置 HTTPS
  5. 设置负载均衡

故障排除

常见问题

  1. 端口冲突: 确保 8000 和 3000 端口未被占用
  2. 依赖安装失败: 检查 Python 和 Node.js 版本
  3. WebSocket 连接失败: 检查防火墙设置
  4. CORS 错误: 确保后端 CORS 配置正确

日志查看

  • 后端日志: 控制台输出
  • 前端日志: 浏览器开发者工具
  • WebSocket 日志: 网络标签页

贡献指南

  1. Fork 项目
  2. 创建功能分支
  3. 提交更改
  4. 推送到分支
  5. 创建 Pull Request

许可证

MIT License - 详见 LICENSE 文件