first commit

QUICKSTART.md

@@ -0,0 +1,211 @@
+# 快速开始指南
+
+## 1. 环境准备
+
+### 激活虚拟环境
+
+```bash
+# 如果虚拟环境不存在，先创建
+conda create -n deep_research_env python=3.11
+conda activate deep_research_env
+```
+
+### 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+## 2. 配置API密钥
+
+编辑 `.env` 文件，填写你的API密钥：
+
+```bash
+# DashScope API配置（阿里云Qwen模型）
+DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
+
+# Tavily搜索API配置
+TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 获取API密钥
+
+- **DashScope**: https://dashscope.aliyun.com/
+  1. 注册/登录阿里云账号
+  2. 开通通义千问服务
+  3. 获取API Key
+
+- **Tavily**: https://tavily.com/
+  1. 注册账号
+  2. 获取免费API Key（支持1000次/月）
+
+## 3. 验证安装
+
+运行测试脚本验证环境：
+
+```bash
+# Windows Git Bash
+export PYTHONIOENCODING=utf-8 && python tests/test_phase1_setup.py
+
+# Linux/Mac
+python tests/test_phase1_setup.py
+```
+
+如果所有测试通过，说明环境配置成功！
+
+## 4. 开始使用
+
+### 基础用法
+
+```bash
+# 执行研究（standard模式）
+python -m src.main research "Python asyncio最佳实践"
+```
+
+### 高级用法
+
+```bash
+# 使用deep模式进行深度研究
+python -m src.main research "量子计算最新进展" --depth deep
+
+# 指定学术格式
+python -m src.main research "机器学习可解释性" --format academic
+
+# 保存报告到指定路径
+python -m src.main research "微服务架构设计" --output report.md
+
+# quick模式（快速研究，约2分钟）
+python -m src.main research "Docker容器化" --depth quick
+```
+
+### 其他命令
+
+```bash
+# 查看配置
+python -m src.main config --show
+
+# 查看历史记录
+python -m src.main history
+
+# 查看指定历史记录
+python -m src.main history --view research_20251031_120000
+
+# 恢复之前的研究
+python -m src.main resume research_20251031_120000
+```
+
+## 5. 深度模式说明
+
+| 模式 | 迭代轮次 | 目标来源数 | 置信度目标 | 预期时长 | 适用场景 |
+|------|---------|-----------|-----------|---------|---------|
+| **quick** | 1-2 | 5-10 | 0.6 | ~2分钟 | 快速了解、简单问题 |
+| **standard** | 2-3 | 10-20 | 0.7 | ~5分钟 | 日常研究、平衡速度和质量 |
+| **deep** | 3-5 | 20-40 | 0.8 | ~10分钟 | 重要决策、高质量要求 |
+
+## 6. 报告格式说明
+
+- **technical** - 技术报告格式，面向开发者
+  - 包含代码示例
+  - 最佳实践
+  - 常见问题
+
+- **academic** - 学术报告格式，面向研究者
+  - 结构化摘要
+  - 文献综述
+  - 引用规范
+
+- **auto** - 自动选择格式（根据问题类型）
+  - 技术问题 → technical
+  - 学术问题 → academic
+
+## 7. 常见问题
+
+### Q1: API调用失败怎么办？
+
+检查：
+1. API密钥是否正确配置
+2. 网络连接是否正常
+3. API额度是否充足
+
+### Q2: 研究结果置信度低怎么办？
+
+解决方案：
+1. 使用更高的深度模式（deep）
+2. 尝试不同的问题表述
+3. 检查是否有高质量来源
+
+### Q3: 如何提高研究质量？
+
+建议：
+1. 使用deep模式
+2. 提供更具体的问题
+3. 使用英文问题（可获取更多高质量来源）
+4. 设置更低的min-tier（如1或2）
+
+### Q4: 如何查看详细的执行日志？
+
+在代码中设置verbose=True：
+```python
+from src.agents.coordinator import run_research
+
+result = run_research(
+    question="你的问题",
+    verbose=True  # 显示详细日志
+)
+```
+
+## 8. 示例场景
+
+### 场景1: 学习新技术
+
+```bash
+# 快速了解技术概念
+python -m src.main research "什么是Rust所有权系统" --depth quick
+
+# 深入学习技术细节
+python -m src.main research "Rust所有权系统实现原理" --depth deep
+```
+
+### 场景2: 技术选型
+
+```bash
+# 对比不同技术方案
+python -m src.main research "gRPC vs REST API比较" --depth standard --format technical
+```
+
+### 场景3: 学术研究
+
+```bash
+# 学术文献综述
+python -m src.main research "Transformer模型发展历程" --depth deep --format academic
+```
+
+### 场景4: 问题排查
+
+```bash
+# 快速查找解决方案
+python -m src.main research "Python内存泄漏排查方法" --depth quick
+```
+
+## 9. 下一步
+
+- 查看 [README.md](README.md) 了解项目架构
+- 查看 [需求文档_V1.md](需求文档_V1.md) 了解功能详情
+- 查看 [开发文档_V1.md](开发文档_V1.md) 了解技术实现
+- 运行测试：`python -m pytest tests/`
+
+## 10. 获取帮助
+
+```bash
+# 查看帮助
+python -m src.main --help
+
+# 查看specific命令帮助
+python -m src.main research --help
+python -m src.main config --help
+python -m src.main history --help
+```
+
+---
+
+祝你研究顺利！🚀