py -m venv .venv
.venv\Scripts\python -m pip install -e ".[test,ui]"

Deep Research/
├─ mcp_server.py                 # MCP 接口层：四个工具和 stdio 入口
├─ app.py                        # Web 界面层：可选 Streamlit 入口
├─ service/                      # 任务与持久化层
│  ├─ report_service.py          # 状态机、后台队列和报告生命周期
│  └─ report_store.py            # SQLite、章节检查点和任务恢复
├─ research/                     # 研究执行层
│  ├─ engine.py                  # 大纲、逐章研究和汇总编排
│  ├─ nodes.py                   # 模型、搜索、写作和引用节点
│  ├─ prompts.py                 # 大模型提示词
│  ├─ models.py                  # 章节、查询和报告状态模型
│  └─ utils.py                   # 搜索提供商与来源处理函数
├─ tests/                        # 自动化测试
├─ reports/                      # 本地报告产物（不会提交到 Git）
├─ configuration.py             # 环境变量及默认运行配置
├─ pyproject.toml                # Python 打包、依赖和命令入口
├─ requirements.txt              # 传统依赖清单
└─ .env.example                 # 环境变量模板

.venv\Scripts\deep-research-mcp.exe

{
  "mcpServers": {
    "deep-research": {
      "command": "D:\\Deep Research\\.venv\\Scripts\\deep-research-mcp.exe",
      "env": {
        "DEEPSEEK_API_KEY": "由客户端安全注入",
        "TAVILY_API_KEY": "可选",
        "DEEP_RESEARCH_DATA_DIR": "D:\\Deep Research Data"
      }
    }
  }
}

flowchart LR
    U[用户或 AI 客户端] --> E[入口层<br/>mcp_server.py / app.py]
    E --> S[任务层<br/>service/]
    S --> R[研究层<br/>research/]
    S <--> D[(SQLite)]
    R --> X[模型与搜索服务]
    S --> O[Markdown 报告]

flowchart LR
    C[MCP 客户端] --> P[create_report_plan<br/>创建大纲]
    P --> U[update_report_outline<br/>修改并确认]
    U --> G[generate_report<br/>加入后台队列]
    G --> Q[get_report<br/>查询进度和结果]
    Q -. 未完成时继续查询 .-> Q

flowchart LR
    A[ReportService<br/>校验请求] --> B[后台任务队列]
    B --> C[逐章调用研究引擎]
    C --> D[ReportStore<br/>保存章节检查点]
    D --> E{全部完成?}
    E -->|否| C
    E -->|是| F[保存 Markdown<br/>状态 completed]
    C -. 失败 .-> G[状态 failed<br/>允许重试]

flowchart LR
    A[engine.py<br/>选择当前章节] --> B{需要研究?}
    B -->|是| C[nodes.py<br/>生成查询并搜索]
    B -->|否| D[nodes.py<br/>直接写作]
    C --> E[nodes.py<br/>撰写章节]
    D --> F[返回章节内容]
    E --> F
    F --> G[汇总章节<br/>处理引用]

flowchart LR
    A[输入研究主题] --> B[编辑并确认大纲]
    B --> C[启动后台生成]
    C --> D[刷新任务进度]
    D --> E[查看或下载报告]

.venv\Scripts\python -m pytest
.venv\Scripts\python -m mcp dev mcp_server.py