# research_assistant_demo

**Repository Path**: zero108/research_assistant_demo

## Basic Information

- **Project Name**: research_assistant_demo
- **Description**: 基于 LangGraph 的多智能体编排：模拟「专家访谈」，将研究主题整理为结构化 Markdown 报告。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: langgraph

## README

# AI 深度研究报告生成器

基于 LangGraph 的多智能体编排：模拟「专家对话」，将研究主题整理为结构化 Markdown 报告。仓库包含 **Python 后端**（LangGraph 图与 Dev Server）与 **Vue 3 前端**（流式进度与报告查看）。

## 目录

- [最短上手](#最短上手)
- [核心思路](#核心思路)
- [工作流概览](#工作流概览)
- [界面预览](#界面预览)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [快速开始（后端）](#快速开始（后端）)
- [前端](#前端)
- [可调参数（后端）](#可调参数（后端）)
- [架构与实现要点](#架构与实现要点)

## 最短上手

先完成一次后端的环境与依赖安装，并配置后端凭证（名称与示例见 `backend/env.example`；详见 [快速开始（后端）](#快速开始（后端）)）。然后使用两个终端：

**终端 1 — 后端**

```bash
cd backend
langgraph dev --host 0.0.0.0 --port 8124 --no-browser
```

**终端 2 — 前端**

```bash
cd frontend
npm install
npm run dev
```

浏览器访问 <http://localhost:5173>。

## 核心思路

根据用户输入的主题，系统自动组建虚拟专家团队，并行完成多轮对话（提问、检索、作答），再合并章节并生成终稿。

## 工作流概览

```
主题输入
  └─► 生成专家团队
        └─► [并行] 专家多轮对话（提问 → 搜索 → 作答）
        └─► [并行] 撰写报告三大部分
        └─► 合并为最终报告
```

## 界面预览

以下为 Web 端生成报告时的界面示意

![Web 界面：输入主题、进度步骤、专家团队与详细日志](docs/images/readme_ui_preview.png)



## 技术栈

### 后端与 API

| 类别 | 技术 |
|------|------|
| AI 编排 | LangGraph |
| 搜索 | Tavily Search API |
| API | LangGraph CLI Dev Server |


### 前端

| 层级 | 技术 |
|------|------|
| 框架 | Vue 3 |
| 构建 | Vite |
| 语言 | TypeScript（strict） |

## 目录结构

```
research_assistant_demo/
├── backend/
│   ├── env.example            # 运行前凭证
│   ├── src/graph.py           # 图与节点逻辑
│   ├── test/                  # SDK 测试与生成报告输出目录
│   ├── langgraph.json         # LangGraph 服务注册
│   └── requirements.txt             
├── frontend/                  # 详见下文「前端」
└── README.md
```

## 快速开始（后端）

### 1. 环境与依赖

```bash
cd research_assistant_demo
uv venv -p 3.11
# Windows: .venv\Scripts\activate
source .venv/bin/activate
cd backend
uv pip install -r requirements.txt
```

### 2. 运行前凭证（配环境变量）

见 `backend/env.example`

### 3. 运行方式

**直接跑图**

```bash
python backend/src/graph.py
```

**LangGraph Dev Server（前端与 SDK 默认连此地址）**

```bash
cd backend
langgraph dev --port 8124 --no-browser
```

图名：`research_assistant_self`（见 `langgraph.json`）。

**SDK 流式测试**

```bash
python backend/test/test_client_v1.py
```

报告默认写入：`backend/test/generated_report/report_<topic>_<timestamp>.md`。

## 前端

Vue 3 单页应用：输入研究主题，通过 LangGraph Dev Server 的流式接口展示进度、专家状态与活动记录，终稿在弹窗中在线阅读（Markdown 渲染）。

### 环境要求

- Node.js ≥ 18（推荐 22.x）
- 启动后端（见「快速开始（后端）」）

### 安装与 npm 脚本

```bash
cd frontend
npm install
npm run dev      # 开发：http://localhost:5173
npm run build    # 生产构建，产出 dist/
```

### `frontend/` 目录说明

```
frontend/
├── index.html
├── vite.config.ts
├── package.json
├── tsconfig*.json
└── src/
    ├── main.ts
    ├── App.vue
    ├── style.css
    ├── types/
    ├── stores/research.ts
    ├── composables/
    │   ├── useSSE.ts
    │   └── useProgress.ts
    ├── components/
    │   ├── layout/TopWarningBar.vue
    │   ├── input/TopicInput.vue、ConnectionStatus.vue
    │   ├── progress/
    │   ├── log/ActivityLog.vue
    │   ├── report/ReportViewerModal.vue
    │   └── common/Toast*.vue
    └── utils/constants.ts、markdown.ts、toast.ts
```

未使用 Vue Router，所有界面在同一页内根据状态切换。

### 与后端约定

- 创建线程：`POST /api/threads`
- 流式运行：`POST /api/threads/{thread_id}/runs/stream`
- 请求体与 LangGraph OpenAPI 一致：例如 `assistant_id: research_assistant_self`，`stream_mode` 使用服务端允许的枚举值，子图细粒度使用字段 `stream_subgraphs`（具体以当前 `openapi.json` 为准）。
- 流式响应按 SSE 解析；`event` 若以 `updates` 开头（含带子图前缀的形态），统一按节点更新处理并写入 Store。

### 功能概览

- 研究主题输入与长度校验、停止生成、查看报告
- 顶部会话提示（刷新丢失数据）
- 四阶段步骤条与全局进度（单调递增）
- 专家卡片状态与「详细进度」列表（随生成流程展开）
- 终稿在 Modal 中在线阅读
- Toast 提示、断线自动重试（有次数与间隔上限）、错误时保留已输入主题

### 注意事项

- 与后端一致：内存模式下刷新页面或重启服务会丢失运行态；重连会发起新的 run，并重置与本次运行相关的展示数据。

## 可调参数（后端）

在 `backend/src/graph.py` 顶部常量区直接修改：

| 常量 | 默认 | 作用 |
|------|------|------|
| `MAX_SEARCH_RESULTS` | 2 | 每次 Tavily 返回条数 |
| `DEFAULT_MAX_TURNS` | 2 | 每位专家最大对话轮数 |
| `MODEL_NAME` | `deepseek-chat` | LLM 模型名 |

`max_experts` 在调用时通过 `initial_state` 传入，不是上述常量。

## 架构与实现要点

- **单一图定义**：`backend/src/graph.py` 包含全部状态机、节点与图构建。
- **注册图名**：`research_assistant_self`（`langgraph.json` 注册；SDK / 前端请求里的 `assistant_id` 须一致）。
- **两张图**：`interview_graph`（单个专家对话-子图）与主图 `graph`；`langgraph.json` 导出的是主图 `graph`。
- **导入即初始化**：模块被 import 时会创建 `llm`、`tavily_search` 与两张图，因此 **import 前** 环境变量必须已就绪。
- **持久化**：`PostgresSaver` 已预留但未启用，当前为内存模式，**重启 Dev Server 或进程后运行状态丢失**。
- **并发**：多位专家各自多轮对话通过 `Send` 并行分发，改动并发路由时留意 `route_node2`。

### 开发与 SDK 注意

- `graph.py` 中的 `interview_graph`、`graph` 为模块级变量，供 `langgraph.json` 引用，**勿删除或改名破坏导出**。
- `test_client_v1.py` 里 `client.runs.stream` 的第一个参数为 `None`（非 thread id）是**有意设计**。