# Deep Research

**Repository Path**: jamer/deep-research

## Basic Information

- **Project Name**: Deep Research
- **Description**: “规划-并行执行-交叉验证” 。真实生产的 “总编-记者-主编”三级网络。这个架构的精妙之处在于：模糊输入 → 拆解任务 → 并行搜集 → 交叉验证 → 综合定稿，全程自动流转，最终产出一份逻辑严谨、视角丰富的深度报告。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔬 Deep Research — 总编·记者·主编 三级深度研究网络

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.2+-green.svg)](https://github.com/langchain-ai/langgraph)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

基于 **LangGraph Send API** 的多智能体深度研究系统。输入一个主题，自动产出带观点、数据和案例的深度分析报告。

> **核心理念**：模糊输入 → 拆解任务 → 并行搜集 → 交叉验证 → 综合定稿

```
输入: "2026年AI制药行业现状"
        │
   ┌────▼────┐
   │  总编    │  DeepSeek — 拆解为 N 个结构化子任务
   │ Planner  │  (type / query / focus / search_strategy)
   └────┬────┘
        │ LangGraph Send 并行 fan-out
   ┌────▼────┐  ┌──────────┐  ┌──────────┐
   │ 记者 #1  │  │ 记者 #2   │  │ 记者 #3   │
   │ 市场规模  │  │ 技术进展  │  │ 政策监管   │
   └────┬────┘  └────┬─────┘  └────┬─────┘
        └────────────┼──────────────┘
              ┌──────▼──────┐
              │    主编      │  交叉验证 + 矛盾检测
              │   Reviewer   │  通过? → 定稿 | 矛盾? → 打回重查 (≤2轮)
              └──────┬──────┘
                     ▼
              深度分析报告 (Markdown)
```

## 🚀 快速开始

### 环境要求

- Python 3.11+
- DeepSeek API Key（或 OpenAI 兼容 API）
- Tavily Search API Key（[免费注册](https://tavily.com)，每月 1000 次）

### 安装

```bash
git clone https://gitee.com/jamer/deep-research.git
cd deep-research
pip install -e .
```

### 配置

```bash
cp .env.example .env
```

编辑 `.env`，至少填入：

```env
DEEPSEEK_API_KEY=sk-your-key-here
TAVILY_API_KEY=tvly-your-key-here
```

### 运行

```bash
# 命令行模式
python -m src.main run "2026年AI制药行业现状"
python -m src.main run "量子计算商业化进展" -o report.md --notify

# Web 模式（前端 + API）
python -m src.main serve --port 8000
# 打开 http://localhost:8000
```

## 🎭 三级角色

| 角色 | Agent | 默认模型 | 核心能力 |
|------|-------|---------|---------|
| **总编** | `planner` | `deepseek-chat` | 理解意图 → 制定研究大纲 → 拆解为 3~5 个结构化子任务 |
| **记者** ×N | `researcher` | `deepseek-chat` | 并行执行 — 多策略搜索 (single/multi/broad) + LLM 汇总 → 结构化 Finding |
| **主编** | `reviewer` | `deepseek-chat` | 交叉验证数据一致性 → 矛盾检测 → 定稿 or 打回重查 (≤2 轮) |

可通过 `.env` 为不同角色指定不同模型：

```env
PLANNER_MODEL=deepseek-chat      # 总编：强推理
RESEARCHER_MODEL=deepseek-chat   # 记者：可批量并行
REVIEWER_MODEL=deepseek-chat     # 主编：长上下文 + 逻辑校验
```

### 总编拆解的子任务示例

总编不只是"你去搜一下"，而是给出精确指令：

```json
{
  "id": 1,
  "type": "市场数据搜集",
  "query": "global AI drug discovery market size 2025 2026 funding rounds",
  "focus": "全球市场规模、增长率、头部公司融资额、区域分布",
  "search_strategy": "multi"
}
```

### 记者搜索策略

| 策略 | 说明 | 适用场景 |
|------|------|---------|
| `single` | 单轮精准搜索 | 明确的数据查询 |
| `multi` | 多轮渐进深入（默认） | 需要逐步聚焦的复杂主题 |
| `broad` | 宽泛搜集后按 focus 筛选 | 探索性调研 |

## 🖥️ Web 前端

`python -m src.main serve` 后打开 `http://localhost:8000`：

| 功能区 | 说明 |
|--------|------|
| 左侧栏 | 主题输入 + 语言/修订轮次设置 + 提交按钮 + 历史记录 |
| 右侧主面板 | 实时日志流 → 报告渲染 |
| 工具栏 | 📋 复制 / 💾 下载 Markdown / 📧 发送邮件 |
| 状态指示 | ⏳ 提交中 / ⟳ 运行中（实时日志） / ✅ 完成 / ❌ 失败 |

### 实时日志示例

研究执行时，前端每 2 秒轮询显示后端进度：

```
⟳ 流水线执行中…
[总编] 📋 拆解出 3 个子任务
  ↳ [1] 市场数据搜集
  ↳ [2] 技术进展调研
  ↳ [3] 政策监管梳理
[记者] 🔍 [1] 市场数据搜集 — high置信度 | 5数据点
  ↳ 全球AI制药市场2025年达$12.8亿
[记者] 🔍 [2] 技术进展调研 — medium置信度 | 3数据点
[记者] 🔍 [3] 政策监管梳理 — high置信度 | 4数据点
[主编] ✅ 定稿完成 — 4521 字符
```

## 📡 API 参考

### 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/research` | 同步研究（等待完成后返回） |
| `POST` | `/research/async` | 异步研究（立即返回 task_id） |
| `GET` | `/research/{task_id}` | 查询任务状态 + 实时日志 |
| `POST` | `/research/{task_id}/email` | 发送报告到邮箱 |
| `GET` | `/health` | 健康检查 |

### 请求示例

```bash
# 同步研究
curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "2026年AI制药行业现状", "language": "zh", "max_revisions": 2}'

# 异步研究
curl -X POST http://localhost:8000/research/async \
  -H "Content-Type: application/json" \
  -d '{"topic": "自动驾驶竞争格局"}'

# 查询进度
curl http://localhost:8000/research/{task_id}

# 发送邮件
curl -X POST http://localhost:8000/research/{task_id}/email
```

### 响应格式

```json
// GET /research/{task_id}
{
  "task_id": "a1b2c3d4",
  "topic": "2026年AI制药行业现状",
  "status": "completed",
  "report": "# 2026年AI制药行业现状 — 深度研究报告\n\n...",
  "log": [
    {"node": "planner", "msg": "📋 拆解出 3 个子任务", "detail": ["[1] 市场数据搜集", ...]},
    {"node": "researcher", "msg": "🔍 [1] 市场数据搜集 — high置信度", "detail": [...]},
    {"node": "reviewer", "msg": "✅ 定稿完成 — 4521 字符", "detail": []}
  ],
  "created_at": "2026-01-15T08:00:00",
  "completed_at": "2026-01-15T08:02:35"
}
```

## 📧 邮件通知

在 `.env` 中配置 SMTP：

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password    # Gmail 需用应用专用密码
SMTP_TO=receiver@example.com
```

三种触发方式：

| 方式 | 操作 |
|------|------|
| **Web 前端** | 报告完成后点击 `📧 发送邮件` 按钮 |
| **CLI** | `python -m src.main run "主题" --notify` |
| **API** | `POST /research/{task_id}/email?to_addrs=a@x.com` |

邮件为双版本（纯文本 + 深色主题 HTML），支持标题层级、加粗、代码块、引用、链接完整渲染。

## ⏰ 定时调度

```bash
# 每天早 8 点自动生成行业日报
python -m src.main schedule "AI行业日报"

# 或使用系统 cron
# 0 8 * * * cd /path/to/deep-research && python -m src.main run "AI日报" -o daily.md --notify
```

## 📁 项目结构

```
deep-research/
├── pyproject.toml              # 项目元数据 + 依赖
├── .env.example                # 环境变量模板
├── README.md                   # 本文件
├── frontend/
│   └── index.html              # Web 前端 SPA (内联 CSS/JS，零构建)
├── src/
│   ├── state.py                # ResearchState + ResearchTask/Finding/Contradiction 模型 + reducers
│   ├── graph.py                # LangGraph 编排 (Send fan-out + 打回循环 + 编译)
│   ├── main.py                 # CLI 入口 (run / serve / schedule)
│   ├── api.py                  # FastAPI 应用 (路由 + CORS + 静态文件挂载)
│   ├── agents/
│   │   ├── planner.py          # 总编节点 — 主题 → 结构化子任务
│   │   ├── researcher.py       # 记者节点 — 子任务 → 多策略搜索 → Finding
│   │   └── reviewer.py         # 主编节点 — 交叉验证 → 定稿 / 打回
│   ├── tools/
│   │   └── search.py           # Tavily 搜索 (single / multi / broad 三种策略)
│   └── notifications/
│       └── email.py            # SMTP 邮件 (纯文本 + 美观 HTML)
└── tests/
    └── test_pipeline.py        # 18 个集成测试
```

## 🧪 测试

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## 🏗️ 关键设计

### 并行 Fan-out（LangGraph Send API）

```python
def _assign_researchers(state) -> list[Send]:
    return [Send("researcher", {"current_task": t}) for t in state["tasks"]]
```

每个子任务独立派发一个记者，全部并行执行，互不阻塞。LangGraph 自动等待所有 Send 完成后再触发下游节点。

### 打回重查回路

```
reviewer → Send[修正任务] → researcher → reviewer → END
```

主编交叉验证发现矛盾后，生成修正任务并清空 `completed_tasks`，触发新一轮 Send 扇出。最多 2 轮（`max_revisions`），超限强制定稿。

### 并发安全 Reducer

```python
# 并行节点安全写入同一字段
completed_tasks: Annotated[List[int], _merge_lists]   # 去重合并
findings:       Annotated[List[dict], _merge_findings] # 按 task_id 覆盖
log:            Annotated[List[dict], _merge_lists]    # 追加日志
```

## 🔀 模式泛化

这个"规划 → 并行执行 → 交叉验证"的三级架构适用于：

| 领域 | 总编 | 记者 | 主编 |
|------|------|------|------|
| **竞品分析** | 拆解分析维度 | 搜集各竞品信息 | 对比汇总 |
| **文献综述** | 规划章节结构 | 检索各子领域论文 | 整合审校 |
| **代码审计** | 划分审计模块 | 审查各自模块代码 | 汇总漏洞报告 |
| **合同审查** | 拆分审查要点 | 核查条款/引用/判例 | 交叉验证 |
| **行业日报** | 确定覆盖范围 | 搜索当天新闻 | 综合定稿 |

## 📄 License

MIT