ProjectsMay 9, 202611 分钟/阅读时间
Agentic科研服务平台 - Project Detail
Research Agent — 项目概要描述
最后更新: 2026-05-02
1. 项目定位
Research Agent 是一个多服务 AI 研究助手平台，帮助研究人员高效完成文献检索、论文精读、对比分析、Related Work 生成、数据分析、论文库管理和知识沉淀等任务。平台将大语言模型（LLM）与学术搜索 API 深度整合，通过 LangGraph 编排多步骤 AI 工作流，并提供实时执行追踪。
2. 核心功能
2.1 用户认证
- 支持 Google 和 GitHub OAuth2 社交登录
- JWT 无状态认证，Token 有效期 24 小时
- 登录后前端存储 Token，所有 API 请求自动携带
2.2 研究项目管理
- 创建、删除研究项目
- 向项目添加成员，支持 OWNER / EDITOR / VIEWER 三级角色
- 项目内集中管理文件、论文、工作流任务
2.3 六种 AI 工作流
| 工作流 | 功能 | 典型输入 → 输出 |
|---|---|---|
| QA | 基于论文回答研究问题 | 问题 + 论文列表 → 有证据引用的答案 + 质量评判 |
| Compare | 多篇论文对比分析 | 论文列表 → 多维度对比报告 + BibTeX 导出 |
| Related Work | 生成文献综述 | 主题关键词 → Related Work 文本（含修订循环） |
| Compute | 数据分析与可视化 | 代码/表格/绘图参数 → 执行结果 + 图表/Notebook |
| Library | 搜索并保存论文 | 搜索查询 → 去重后的论文列表 → 保存至个人库 |
| Wiki | 自动生成知识条目 | 论文/主题 → 结构化 Wiki 条目（7 节/6 节模板） |
每种工作流均可开启 Judge 评判，由 LLM 自动评估结果质量（正确性、证据基础、引文一致性、完整性、清晰度）。
2.4 论文库管理
- 上传文件（PDF 等）并自动解析、索引
- 搜索并保存论文（支持幂等性 Key）
- 列出、查看、删除收藏的论文
- 添加笔记和标签
2.5 Wiki 知识库
- 按论文或主题自动生成结构化 Wiki 条目
- 条目包含多章节 Markdown 正文、标签、关联论文/条目链接
- 支持按类型（PAPER / TOPIC）和标签过滤浏览
2.6 实时执行追踪
- SSE 实时推送: 前端通过 EventSource 订阅任务状态、步骤执行、产物生成
- Trace 查看器: 完整的执行轨迹回放（步骤时间线、工具调用、Judge 评分、可观测性指标）
- 产物管理: 下载/预览任务生成的图表、BibTeX、Notebook 等文件
2.7 通知系统
- 任务完成/失败、项目共享等事件自动生成通知
- 未读计数轮询（30 秒间隔）
- 支持单条/全部标记已读
3. 技术架构
3.1 整体架构
┌──────────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ React 18 + TypeScript + Vite │
└────────────────────────────┬─────────────────────────────────────┘
│ HTTPS / HTTP
▼
┌────────────────────────────┴─────────────────────────────────────┐
│ Frontend (Nginx :80) │
│ 静态文件服务 + /api/* 反向代理 │
└────────────────────────────┬─────────────────────────────────────┘
│ /api/* (JWT Bearer Token)
▼
┌────────────────────────────┴─────────────────────────────────────┐
│ Java Backend (Spring Boot 3.3.4 :8080) │
│ │
│ 认证授权 │ 项目管理 │ 工作流编排 │ 论文库 │ Wiki │
│ OAuth2 │ CRUD │ 任务分发 │ CRUD │ CRUD │
│ + JWT │ + 共享 │ SSE 推送 │ + 文件 │ │
│ │
│ 数据持久化：Spring Data JPA + Flyway 迁移 │
└──────┬───────────────────────────────┬───────────────────────────┘
│ SQL (JDBC) │ HTTP REST
▼ │ POST /workflows/*
┌──────┴──────────┐ ┌─────────┴───────────────────────────┐
│ PostgreSQL │ │ Python Agent (FastAPI :8000) │
│ :5432 │ │ │
│ │ │ LangGraph 工作流引擎 │
│ 15 张表 │ │ 7 种工作流 · 22 个图节点 · 27 个工具│
│ │ │ │
│ │ │ LLM 集成 │ 学术搜索 API │
│ │ │ OpenAI │ OpenAlex / arXiv │
│ │ │ 兼容 API │ Semantic Scholar 等 │
│ │ │ │
│ │ │ 向量存储 │ 产物管理 │
│ │ │ ChromaDB │ 本地文件系统 │
└──────────────────┘ └─────────────────────────────────────┘
3.2 技术选型
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端框架 | React 18.3 + TypeScript 5.6 | 17 个组件，React Router 客户端路由 |
| 前端构建 | Vite 5.4 | 快速 HMR，生产构建 |
| 前端实时 | EventSource (SSE) | 任务执行状态实时推送 |
| API 网关 | Nginx 1.25 | 静态服务 + 反向代理 |
| 业务中台 | Spring Boot 3.3.4 + Java 17 | 认证、项目、工作流编排、REST API |
| 安全框架 | Spring Security + OAuth2 + JWT | 社交登录 + 无状态 Token |
| ORM | Spring Data JPA + Hibernate | 实体映射，ddl-auto: validate |
| 数据库迁移 | Flyway | 6 个版本迁移脚本 |
| 数据库 | PostgreSQL 16 (生产) / H2 (开发) | UUID 主键，CLOB 存 JSON |
| AI 编排 | LangGraph 0.2.20 | StateGraph 构建 7 种工作流 |
| Web 框架 | FastAPI 0.111 | Python 异步 REST API |
| 数据验证 | Pydantic 2.8 | AgentState ~90 字段 + 请求/响应 Schema |
| LLM 调用 | 自定义 urllib 客户端 | OpenAI 兼容 API，速率限制，指数退避 |
| 学术搜索 | OpenAlex / arXiv / Semantic Scholar / PubMed / DBLP / Crossref | 并行搜索，DOI 去重 |
| PDF 解析 | pdfplumber 0.10 | 结构化内容提取 |
| 数据分析 | pandas 2.2 + matplotlib 3.8 | 表格分析 + 图表生成 |
| 向量存储 | ChromaDB 0.5 | 可选，支持语义检索 |
| 部署编排 | Docker Compose | 4 服务 + 3 命名卷 |
| CI/CD | GitHub Actions | 4 Job 流水线（lint-test + build + docker-build） |
3.3 核心设计模式
Provider Mode 系统: Python 后端的每个外部依赖（LLM、学术 API、向量存储、Java 客户端等）都通过 mock / real / hybrid 模式控制。开发时使用 mock 模式无需外部服务，生产环境强制 real 模式。
回调架构: Java 和 Python 之间采用回调模式——Java 是编排器/状态存储，Python 是执行引擎。Python 在执行过程中通过 HTTP 回调向 Java 报告进度。
图节点包装器: LangGraph 的每个节点通过 run_node() 统一包装，自动获得重试、检查点、可观测性发射和 Java 客户端同步能力。
4. 工作流执行流程
以 QA 工作流为例：
1. 用户输入问题 + 选择论文 → 前端 POST /api/workflows/qa
2. Java 创建 AgentTask，@Async 转发至 Python
3. Python LangGraph 执行:
a. intent_router: 分析意图，路由至文档管线
b. search_node: 并行搜索 5 个学术 API
c. resolve_identity_node: 论文去重与标识解析
d. prepare_documents: 下载 PDF → 解析 → 分块 → 向量索引
e. ask_node: 检索相关证据 + LLM 生成回答
f. judge_node: LLM 评估回答质量（5 维度评分）
g. compose_node: 组装最终答案 + Judge 评分
h. observability_node: 记录 Trace 指标
4. 执行过程中逐步回调 Java 更新步骤/事件
5. Java 通过 SSE 将实时状态推送给前端
6. 前端 TaskDetailPage 展示执行时间线 + 最终答案
5. 部署方式
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env: 设置 LLM_API_KEY、JWT_SECRET、OAuth2 Client ID/Secret 等
# 2. 一键启动
docker compose up -d
# 3. 访问
# 前端: http://localhost
# Java API: http://localhost:8080
# Python API: http://localhost:8000
# Swagger: http://localhost:8000/docs
四个容器: frontend(Nginx:80) + java-backend(Spring Boot:8080) + python-agent(FastAPI:8000) + postgres(PostgreSQL:5432)
6. 项目结构速览
research_agent/
├── frontend/ # React 18 + TypeScript + Vite 前端
│ ├── src/
│ │ ├── api/ # API 客户端 + 服务函数 + SSE Reducer
│ │ ├── components/ # 17 个 UI 组件
│ │ ├── context/ # Auth React Context
│ │ ├── pages/ # 9 个页面
│ │ └── types/ # TypeScript 类型契约
│ └── nginx.conf # Nginx 反向代理 + SPA 回退
├── java-backend/ # Spring Boot 3.3.4 Java 中台
│ └── src/main/
│ ├── java/com/research/agent/
│ │ ├── controller/ # 12 个 REST 控制器
│ │ ├── service/ # 12 个业务服务
│ │ ├── entity/ # 15 个 JPA 实体
│ │ ├── repository/ # 15 个数据仓库
│ │ ├── dto/ # 请求/响应 DTO
│ │ └── config/ # 安全、JWT、CORS、异步配置
│ └── resources/db/migration/ # 6 个 Flyway SQL 迁移
├── app/ # FastAPI 应用入口 + API Schema
├── domain/ # Pydantic 领域模型
├── graph/ # LangGraph 工作流 + 22 个图节点
├── tools/ # 27 个工具（8 类别）
├── integrations/ # 18 个第三方集成
├── judge/ # LLM 评判管线
├── observability/ # 三层可观测性系统
├── prompts/ # 7 个 LLM Prompt 模板
├── tests/ # 单元测试 + 集成测试
├── scripts/ # 开发环境引导 + E2E 脚本
├── docker-compose.yml # 4 服务编排
└── TECHNICAL_DOCUMENTATION.md # 详细技术文档