deepagents----/README.md

# 智能深度研究系统 (Deep Research System)

基于DeepAgents框架的智能深度研究系统，能够自动搜集信息、验证来源、交叉核对并生成高可信度的研究报告。

## 功能特性

- **7步核心流程**: 意图分析 → 并行搜索 → 来源验证 → 内容分析 → 置信度评估 → 迭代决策 → 报告生成
- **3种深度模式**: quick（2分钟）、standard（5分钟）、deep（10分钟）
- **来源分级**: Tier 1-4 分级，自动过滤低质量来源
- **置信度评估**: 基于来源可信度（50%）、交叉验证（30%）、时效性（20%）计算
- **并行搜索**: 使用ThreadPoolExecutor实现真正的并发搜索
- **降级运行**: 部分失败不影响整体流程

## 快速开始

### 1. 环境准备

#### 激活虚拟环境
```bash
conda activate deep_research_env
```

如果虚拟环境不存在，创建一个：
```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=your_dashscope_api_key_here

# Tavily搜索API配置
TAVILY_API_KEY=your_tavily_api_key_here
```

**获取API密钥：**
- DashScope: https://dashscope.aliyun.com/
- Tavily: https://tavily.com/

### 3. 验证安装

运行测试脚本验证Phase 1基础设施：

```bash
export PYTHONIOENCODING=utf-8 && python tests/test_phase1_setup.py
```

如果所有测试通过，说明环境配置成功！

### 4. 使用示例

```bash
# 执行研究（standard模式）
python src/main.py research "Python asyncio最佳实践"

# 使用deep模式
python src/main.py research "量子计算最新进展" --depth deep

# 指定格式和保存
python src/main.py research "机器学习模型部署" --format technical --save

# 查看历史记录
python src/main.py history

# 恢复之前的研究
python src/main.py resume <ID>
```

## 项目结构

```
deep_research/
├── .env                     # 环境变量（不提交）
├── .env.example             # 环境变量模板
├── .gitignore
├── requirements.txt
├── README.md
│
├── src/
│   ├── __init__.py
│   ├── config.py            # API配置
│   ├── main.py              # CLI入口
│   │
│   ├── agents/
│   │   ├── __init__.py
│   │   ├── coordinator.py   # ResearchCoordinator主Agent
│   │   └── subagents.py     # 6个SubAgent配置
│   │
│   ├── tools/
│   │   ├── __init__.py
│   │   └── search_tools.py  # batch_internet_search
│   │
│   └── cli/
│       ├── __init__.py
│       └── commands.py      # CLI命令
│
├── tests/
│   ├── test_phase1_setup.py  # Phase 1测试
│   ├── test_subagents.py
│   ├── test_tools.py
│   └── test_integration.py
│
└── outputs/                  # 研究报告输出目录
    └── .gitkeep
```

## 开发进度

- [x] Phase 1: 基础架构搭建
  - [x] 创建项目目录结构
  - [x] 创建requirements.txt和.env配置文件
  - [x] 实现src/config.py（API配置）
  - [x] 实现src/tools/search_tools.py（并行搜索工具）
  - [ ] 测试API连接和批量搜索功能

- [ ] Phase 2: SubAgent实现
  - [ ] 实现6个SubAgent配置
  - [ ] 编写单元测试
  - [ ] 代码审查

- [ ] Phase 3: 主Agent实现
  - [ ] 实现ResearchCoordinator
  - [ ] 测试迭代流程
  - [ ] 代码审查

- [ ] Phase 4: CLI和打磨
  - [ ] 实现CLI命令
  - [ ] 实现进度显示和错误处理
  - [ ] 编写用户文档和集成测试

## 技术架构

### Agent架构（1主 + 6子）

```
ResearchCoordinator (主Agent)
├── intent-analyzer (意图分析)
├── search-orchestrator (并行搜索)
├── source-validator (来源验证)
├── content-analyzer (内容分析)
├── confidence-evaluator (置信度评估)
└── report-generator (报告生成)
```

### 虚拟文件系统

```
/
├── question.txt
├── config.json
├── search_queries.json
├── iteration_1/
│   ├── search_results.json
│   ├── sources.json
│   ├── findings.json
│   └── confidence.json
├── iteration_decision.json
└── final_report.md
```

## 深度模式对比

| 模式 | 迭代轮次 | 目标来源数 | 置信度目标 | 并行搜索 | 预期时长 |
|------|---------|-----------|-----------|---------|---------|
| **quick** | 1-2 | 5-10 | 0.6 | 3 | ~2分钟 |
| **standard** | 2-3 | 10-20 | 0.7 | 5 | ~5分钟 |
| **deep** | 3-5 | 20-40 | 0.8 | 5 | ~10分钟 |

## 来源可信度分级

| Tier | 评分 | 技术类来源 | 学术类来源 |
|------|------|-----------|-----------|
| **1** | 0.9-1.0 | 官方文档、第一方GitHub、标准组织 | 同行评审期刊、高引用论文(>100) |
| **2** | 0.7-0.9 | MDN、Stack Overflow高分、大厂博客 | 会议论文、中等引用(10-100) |
| **3** | 0.5-0.7 | 高质量教程、维基百科、社区知识库 | - |
| **4** | 0.3-0.5 | 论坛讨论、个人博客、社交媒体 | - |

## 置信度计算公式

```
置信度 = 来源可信度×50% + 交叉验证×30% + 时效性×20%
```

## 技术栈

- **Agent框架**: DeepAgents
- **LLM**: Qwen-Max (通过DashScope API)
- **搜索**: Tavily API
- **CLI**: Click + Rich
- **并发**: ThreadPoolExecutor

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 相关文档

- [需求文档](需求文档_V1.md)
- [开发文档](开发文档_V1.md)
- [开发流程指南](开发流程指南.md)