Agentic科研服务平台
项目背景
暂无项目背景
STAR 过程
情境（Situation）：在人工智能技术迅猛发展的今天，大语言模型（LLM）已经展现出在知识问答、文本生成、逻辑推理等方面的惊人能力。然而在学术研究领域，研究人员面临的信息获取与知识处理困境并没有因此得到根本解决。一个典型的博士生或科研工作者，每周需要花费 15-25 小时在文献检索、论文精读、对比分析、综述撰写、数据实验等重复性认知劳动上。现有的学术搜索引擎（Google Scholar、Semantic Scholar、arXiv、PubMed 等）虽然解决了"找得到"的问题，却无法解决"看得懂、理得清、写得出"的深层需求。另一方面，通用 AI 助手（如 ChatGPT）在面对学术场景时存在三个致命缺陷：第一，无法系统性地接入多源学术数据库进行可追溯的文献检索；第二，生成的回答缺乏准确的证据引用，存在严重的"幻觉"问题；第三，不支持结构化的多步骤研究工作流（如 QA→证据检索→答案生成→质量评判→人类复审的闭环）。 与此同时，科研团队协作场景中的痛点同样突出。一个实验室通常有多名学生和研究人员围绕同一课题开展工作，但论文收藏、笔记标注、文献综述、Wiki 知识沉淀等环节长期处于"工具有余、整合不足"的状态——每个人各自使用 Zotero、Notion、Obsidian 等工具，形成了一座座信息孤岛。项目负责人无法统一把控团队的知识资产，新成员加入时需要花费数周时间重新阅读大量文献才能上手。 从技术可行性的角度审视，2024-2025 年间出现了几个关键的使能条件：LangGraph 等 AI 编排框架的成熟使得多步骤 Agent 工作流可以被可靠地构建和执行；OpenAI 兼容 API 的普及使得 LLM 调用不再被单一厂商锁定；OpenAlex、Semantic Scholar 等学术 API 提供了开放的结构化文献数据；Spring Boot 3 + React 18 的全栈技术栈已经高度成熟。这些技术条件的汇聚，使得构建一个"从文献检索到知识沉淀"全链路 AI 研究助手平台成为可实现的工程目标。 本项目正是在这样的背景下启动的——旨在构建一个面向学术研究团队的、多服务架构的 AI 研究助手平台，将大语言模型与学术搜索 API 深度整合，通过 LangGraph 编排多步骤 AI 工作流，并提供从文献检索、论文精读、对比分析、Related Work 生成、数据分析到 Wiki 知识库沉淀的全链路支持。
任务（Task）：本项目的核心任务是构建一个名为 **Research Agent** 的增量可执行研究智能体平台，具体需要完成以下工程目标： **第一，实现六种核心 AI 工作流。** 平台需要支持：(1) **QA 工作流**——基于用户问题与指定论文集合，检索相关证据并生成带引用的答案；(2) **Compare 工作流**——对多篇论文进行多维度的结构化对比分析，并支持 BibTeX 格式导出；(3) **Related Work 工作流**——根据主题关键词自动生成文献综述，内建 LLM 评判与人类复审循环，支持迭代修订；(4) **Compute 工作流**——支持 Python 代码执行、表格数据分析、图表生成与 Jupyter Notebook 模板执行；(5) **Library 工作流**——支持跨多源学术 API 的论文搜索、去重、保存与个人论文库管理；(6) **Wiki 工作流**——根据论文或主题自动生成结构化 Wiki 知识条目。所有工作流需内建 LLM-as-Judge 质量评判机制，从正确性、证据基础、引文一致性、完整性、清晰度等维度自动评估输出质量。 **第二，构建三层微服务架构。** 前端采用 React 18 + TypeScript + Vite 构建 17 个交互组件与 9 个页面，通过 SSE 实现任务执行状态的实时推送；中台采用 Spring Boot 3.3.4 + Java 17 负责用户认证授权（Google/GitHub OAuth2 + JWT）、研究项目管理（CRUD + 三级别角色共享）、工作流编排分发、论文库管理、Wiki 知识库管理、通知系统以及 Python Agent 回调接收；AI 引擎采用 Python FastAPI + LangGraph 实现 7 种工作流图、22 个图节点、27 个功能工具、18 个第三方集成。 **第三，建立灵活的 Provider Mode 系统。** 每个外部依赖（LLM、学术 API、向量存储、对象存储、Trace 存储、Java 客户端等）都通过 `mock / real / hybrid` 三级模式进行抽象。开发阶段使用 mock 模式可以完全不依赖外部服务运行全部工作流；生产环境强制 real 模式确保真实数据链路；hybrid 模式提供优雅降级。这要求设计一套清晰的环境变量配置体系与模式校验机制。 **第四，实现完整的可观测性体系。** 需要构建三层 Trace 系统（Emitter → Recorder → TraceStore），支持内存、文件、混合三种存储后端，提供 Trace 查询、事件列表、指标聚合的能力；需要实现 LLM 调用的治理追踪（模型名称、Prompt 版本、Token 消耗、费用估算）；需要支持 Eval Runner 的多模型多 Prompt 变体对比评测。 **第五，建立 Java-Python 协作的回调架构。** Java 作为编排器和状态存储，Python 作为执行引擎。Python 在执行过程中需要通过 HTTP 回调向 Java 报告任务状态变更、步骤执行、产物创建等进度信息，Java 通过 SSE 实时推送给前端。整个链路需要处理异步并发、乐观锁冲突、幂等性保障等分布式系统常见问题。
行动（Action）：项目的实施遵循"领域建模先行、核心引擎突破、微服务集成、全链路贯通"的四阶段路线： **第一阶段：领域建模与架构设计。** 团队首先使用 Pydantic 2.8 定义了 `AgentState` 核心领域模型——一个包含约 90 个字段的大型状态对象，涵盖工作流路由、论文检索、文档准备、证据管理、问答生成、评判结果、计算任务、产物管理、人工复审等全部环节的状态。这一设计确保了 LangGraph 工作流中各节点间的类型安全与数据传递的一致性。同时设计了 15 张表的数据库模型（users、research_project、project_member、paper、uploaded_file、research_document、library_paper、wiki_entry、agent_task、agent_step、agent_event、artifact、judge_result、notification、idempotency_record），通过 Flyway 进行 6 个版本的增量迁移管理。在架构层面确定了 Nginx → Java Spring Boot → Python FastAPI 的三层服务拓扑以及容器间通信方案。 **第二阶段：LangGraph 工作流引擎构建。** 这是整个项目的核心。团队基于 LangGraph 0.2.20 的 StateGraph API 构建了 7 种工作流图，每种工作流通过 `run_node()` 统一包装图节点，自动获得重试机制、检查点存储、可观测性事件发射和 Java 客户端同步的能力。实现了 `intent_router`（意图识别与路由节点）、`search_node`（并行搜索 5 个学术 API 节点）、`resolve_identity_node`（论文去重与标识解析节点）、`prepare_documents`（PDF 下载→解析→分块→向量索引节点）、`ask_node`（证据检索 + LLM 生成节点）、`judge_node`（LLM 五维度质量评判节点）、`compose_node`（最终答案组装节点）、`observability_node`（Trace 指标记录节点）等 22 个图节点。同时构建了 27 个工具函数，覆盖学术搜索（8 个）、文档处理（5 个）、计算分析（4 个）、评判（2 个）、知识合成（3 个）、可观测性（2 个）、论文库（2 个）、Wiki（1 个）共 8 个类别。 **第三阶段：微服务全栈集成。** Java 后端实现了 12 个 REST 控制器和 12 个业务服务，完整的 Spring Security + OAuth2 + JWT 认证链路，以及基于 `@Async` + `ThreadPoolTaskExecutor` 的异步工作流分发机制。前端使用 React 18 + TypeScript 构建了认证上下文（AuthContext）、SSE Reducer 状态管理、10 个 API 服务函数，以及 TaskTimeline、ToolCallCard、JudgeResultPanel、TraceMetricsPanel 等 17 个 UI 组件。Nginx 配置实现了静态文件服务、`/api/*` 反向代理与 SPA 回退的三合一部署方案。 **第四阶段：质量保障与部署。** 建立了三层测试体系——Python 单元测试（工具函数、图节点、评判管线）、集成测试（工作流端到端）、前端测试（API 客户端、服务函数、组件）。配置了 GitHub Actions 四 Job CI/CD 流水线（lint-test + build + docker-build）。通过 Docker Compose 实现了一键部署的 4 服务编排（frontend + java-backend + python-agent + postgres），并编写了详细的环境变量配置指南、运行指南、技术文档、前端接口文档、数据库设计文档共 5 份工程文档。
结果（Result）：经过系统性的工程实施，Research Agent 平台取得了以下可量化的成果： **功能完整性方面：** 平台成功实现了全部 6 种 AI 工作流的端到端运行。QA 工作流可在 30-90 秒内完成从问题输入到带引用答案输出的全流程，每项证据均附带来源论文、段落定位与置信度标注。Compare 工作流支持从 5+ 维度（方法论、实验结果、创新点、局限性、适用场景）进行多论文并行对比，并自动生成标准 BibTeX 导出。Related Work 工作流内建 LLM 自动评判→人类复审→定向修订的闭环，最大修订次数可配置。Compute 工作流完整支持 Python 代码沙箱执行、matplotlib/seaborn 图表生成、pandas 表格分析、Jupyter Notebook 模板执行 4 种计算模式。所有工作流均支持可选的 Judge 质量评判与完整的 Trace 执行追踪。 **架构灵活性与可扩展性方面：** Provider Mode 系统被证明是一个关键的架构决策。通过 `mock / real / hybrid` 三级抽象，开发人员可以在不配置任何外部 API 密钥的情况下完整运行和调试全部工作流；切换到 real 模式时可以无缝接入 OpenAI、Azure、火山引擎等任意 OpenAI 兼容 API；hybrid 模式提供了真实调用失败时的优雅降级。18 个第三方集成的标准化接口设计使得添加新的学术搜索引擎或 LLM 提供商仅需实现对应的 Provider 接口，无需修改任何核心工作流代码。 **协作与知识管理方面：** 平台实现了完整的研究团队协作功能——三级角色权限（OWNER/EDITOR/VIEWER）的项目成员管理、论文库的收藏与笔记标签系统、基于论文或主题自动生成结构化 Wiki 条目的知识沉淀机制、以及任务完成/失败/项目共享等事件驱动的通知系统。这使得一个实验室的集体知识不再分散在各成员的本地工具中，而是统一沉淀在平台的知识库内。 **可观测性与质量保障方面：** 三层 Trace 系统实现了对每次工作流执行的完整记录——包含每个图节点的输入输出摘要、每个工具调用的参数与返回值、LLM 调用的模型/Token/费用、Judge 评判的各维度评分等。Trace 查看器提供了从任务创建到最终答案的全链路时间线回放。Eval Runner 支持对不同模型变体和 Prompt 变体进行系统性的 A/B 对比评测，为 Prompt 优化和模型选型提供了数据驱动的决策依据。 **工程交付物方面：** 项目产出包括：约 220+ Python 源文件、80+ Java 源文件、60+ TypeScript/TSX 源文件、6 个 Flyway 数据库迁移脚本、5 份完整的技术文档（总计约 11 万字）、GitHub Actions CI/CD 流水线、以及 Docker Compose 一键部署配置。平台在 mock 模式下可实现"零外部依赖"的完整本地运行，在 real 模式下支持从开发环境到生产环境的平滑迁移。
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 # 详细技术文档