# 快速开始指南

## 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
```

---

祝你研究顺利！🚀