Skip to content

OpenDCAI/OpenResearchFlow

BranchesTags

Repository files navigation

OpenResearchFlow

English | 中文

OpenResearchFlow 是面向科研自动化的 agentic workspace，目标是把研究问题、 论文材料和实验结果证据转化为可执行实验方案、可运行实验仓库、论文初稿、 图表、标题、论文评审和参考文献质量检查报告。

OpenResearchFlow architecture

目录

项目定位

OpenResearchFlow 聚焦 paper-to-experiment-to-paper 闭环：

  1. 从目标研究问题生成并验证研究想法。
  2. 将高潜力想法转化为实验计划和实现工作区。
  3. 执行快速验证和完整实验阶段。
  4. 生成论文草稿、图表、标题、论文评审和参考文献质量报告。

当前真正使用的后端模块位于 backend/src/modules：

  • idea_gen_v2
  • idea2exp
  • exp_gen_v2
  • exp_run
  • draft_gen
  • paper2figure
  • paper2title
  • papercheck，也就是产品讨论中的 paper2check
  • review_gen

其他模块目录是历史版本或兼容代码，除非被上述 active modules 显式调用， 否则不应作为当前产品能力展示。

系统架构

OpenResearchFlow 由 Next.js 前端、FastAPI gateway 和 Python workflow modules 组成。前端负责模块入口、run 创建、状态展示、artifact 查看和 workspace Runtime/API Key 配置；后端负责任务编排、模型调用、实验执行和 artifact 持久化。

frontend/
  src/app/                  Next.js app routes
  src/app/workspace/        workspace pages for module run management
  src/core/                 typed API clients, loaders, hooks, and utilities

backend/
  src/gateway/              FastAPI run-management and artifact APIs
  src/modules/              active workflow modules and historical modules
  src/agents/               lead-agent runtime and thread state
  src/tools/, src/sandbox/  tool and execution infrastructure

典型 run flow：

Workspace page or home module launcher
  -> FastAPI gateway run API
  -> backend/src/modules/<module>/workflow.py
  -> backend/output/<module>/...
  -> event logs, reports, and artifacts loaded back into the frontend

本地默认端口：前端 http://127.0.0.1:3001，gateway http://127.0.0.1:8101。 前端通过 next.config.js 把 /api/* 转发到 gateway，因此浏览器侧无需单独配置 后端地址。

快速开始

下面是从零到能在浏览器里跑通流水线的最短路径。

1. 安装本地工具

需要 node、pnpm、uv、curl。运行 LaTeX 真实编译（Draft Gen 导出 PDF）还需 要一个 LaTeX 引擎，macOS/Homebrew 推荐 tectonic：

make check            # 检查 node / pnpm / uv / curl 是否就绪
brew install tectonic # 可选：Draft Gen 渲染 PDF 时需要

2. 安装依赖

make install          # backend: uv sync;  frontend: pnpm install

3. 生成本地配置文件

make config

make config 会从安全模板复制出三份本地配置（已存在则不覆盖）：

生成文件 来源模板 作用
.env .env.example 后端配置主入口，填写 LLM / 检索 / 解析等 API Key
frontend/.env frontend/.env.example 前端本地覆盖项，通常无需修改
config.yaml config.example.yaml gateway/模块运行参数

4. 配置 LLM API Key

编辑根目录 .env，至少填好 LLM provider（见 下一节）。如果只想先看界面，可以跳过这一步直接跑 Mock Demo。

5. 启动服务

make demo             # 可选：写入无需 API Key 的 mock 数据
make dev              # 启动 gateway + 前端

打开 http://127.0.0.1:3001/workspace 即可开始使用。

配置 LLM 与 API Key

后端配置集中在 根目录 .env（由 make config 从 .env.example 生成）。 模板按依赖类型分块，只需填写你实际要用的 provider，其余留空即可。

提示：前端的 Runtime/API Keys 设置页可以在浏览器里临时覆盖部分模型/服务参数， 适合快速试用；但仍直接读取环境变量的后端模块需要在 .env 中提供对应值。 不要把私有 API Key 写进 frontend/.env。

必填：LLM provider

绝大多数生成类模块（idea_gen_v2、idea2exp、exp_gen_v2、draft_gen、 paper2title、review_gen）都依赖 LLM provider。在 .env 中至少填写一组：

# 项目自有/兼容网关
DF_API_URL=https://your-llm-gateway/v1
DF_API_KEY=sk-...

# 或 OpenAI 兼容端点
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...

# 默认生成模型与语言
IDEA_GEN_MODEL=gpt-4o
IDEA_GEN_LANGUAGE=zh

按需填写：其余能力

依赖类型 关键变量 相关模块
论文/网页检索 SEMANTIC_SCHOLAR_API_KEY、AI4SCHOLAR_API_KEY、SERPAPI_API_KEY、TAVILY_API_KEY idea_gen_v2、idea2exp、draft_gen、papercheck、review_gen
PDF 解析 MINERU_API_TOKEN（或本地 MinerU 服务） idea2exp、draft_gen、paper2figure、review_gen
图像生成 TEXT_API_URL / TEXT_API_KEY、IMAGE_API_URL / IMAGE_API_KEY paper2figure
实验执行 agents PAPERAGENT_EXP_RUN_CODEX_*、PAPERAGENT_EXP_RUN_CC_* exp_run
ExpGen 规划/生成/评估 agents EXP_GEN_PLAN_*、EXP_GEN_GEN_*、EXP_GEN_EVAL_* exp_gen_v2
仓库访问 GITHUB_TOKEN、EXP_GEN_GITHUB_TOKEN exp_gen_v2、exp_run

.env.example 中每一块都有注释说明用途，更多细节见 docs/open-source/runtime-config.md。 .env、.env.cc 等本地密钥文件不要提交到 git。

启动与停止服务

make dev 实际调用 scripts/start-services.sh，它会：

  1. 检查 uv、pnpm、curl 是否就绪；
  2. 在 backend/ 用 uv run uvicorn 启动 gateway，并等待 /health 就绪；
  3. 在 frontend/ 用 pnpm next dev 启动前端，并等待 /workspace 就绪；
  4. 把日志写到 logs/，进程 PID 写到 logs/pids/。
make dev                       # 等价于 ./scripts/start-services.sh
./scripts/start-services.sh    # 也可直接运行脚本

如果使用 conda 环境：

conda run -n pzw-dev make demo
conda run -n pzw-dev make dev

启动成功后脚本会打印前端、gateway 地址和各 workspace 路由入口。

常用脚本与端口覆盖：

./scripts/check-services.sh    # 查看 gateway / 前端是否在运行
./scripts/stop-services.sh     # 停止服务（make stop 同效）
make clean                     # 停止服务并清理本地日志

# 端口被占用时可临时覆盖（默认 3001 / 8101）
FRONTEND_PORT=4001 GATEWAY_PORT=9101 make dev

查看实时日志：

tail -f logs/frontend.log
tail -f logs/gateway.log

一键 Mock Demo

开源用户可以在不配置任何 API key 的情况下查看完整 OpenResearchFlow 流水线：

make config
make demo
make dev

打开：

  • 首页：http://127.0.0.1:3001
  • Mock 起点：http://127.0.0.1:3001/workspace/idea-gen/openresearchflow-mock-idea-001
  • Idea2Exp：http://127.0.0.1:3001/workspace/idea2exp/openresearchflow-mock-idea2exp-001
  • ExpGen V2：http://127.0.0.1:3001/workspace/exp-gen_v2/openresearchflow-mock-expgen-001
  • ExpRun：http://127.0.0.1:3001/workspace/exp-run/openresearchflow-mock-exprun-001
  • Draft Gen：http://127.0.0.1:3001/workspace/draft-gen/openresearchflow-mock-draft-001
  • Mock 终点：http://127.0.0.1:3001/workspace/review-gen/openresearchflow-mock-review-001

make demo 会写入确定性的 mock runs，覆盖 idea_gen_v2 -> idea2exp -> exp_gen_v2 -> exp_run -> draft_gen -> papercheck -> review_gen 的主要产物，并提供 draft_gen 到 paper2figure、paper2title 的 PDF 导入数据。详细说明见 docs/open-source/demo.md。

功能模块

模块 主要作用 典型输入 关键输出 前端展示
idea_gen_v2 生成研究 seeds、hypotheses、ideas、验证证据、批判和最终报告。 研究目标、领域、目标会议、run 策略 idea report、stage artifacts、validation evidence Idea Gen
idea2exp 将 idea card 和上游证据转成结构化实验计划，并补充检索/论文抽取证据。 idea card、相关论文、parser/search credentials experiment plan、extracted evidence Idea2Exp
exp_gen_v2 以 milestone 为单位生成实验实现方案、代码工作区、review 和 handoff artifacts。 idea/experiment plan、参考仓库、生成约束 milestone workspace、repo plan、handoff artifacts ExpGen V2
exp_run 执行快速验证和完整实验，生成结果分析、质量门禁和最终报告。 generated repo、run matrix、agent runtime credentials smoke-test results、full run outputs、final report ExpRun
draft_gen 根据 idea、experiment、parse、reference artifacts 生成并验证论文草稿。 idea artifacts、experiment artifacts、references、parsed paper context LaTeX draft、section artifacts、citation checks Draft Gen
paper2figure 根据论文上下文、表格和 related-work evidence 生成图表或概念图。 paper text、table text、image/text model credentials figure assets、review artifacts Paper2Figure
paper2title 根据论文正文生成简洁的英文论文标题。 paper body text、title-generation model candidate title Paper2Title
papercheck 解析 BibTeX/PDF references，执行静态和可选在线检查，输出参考文献健康报告。 BibTeX/PDF references、online-check settings reference-quality report Paper Check
review_gen 解析论文 PDF，围绕创新性、技术正确性、实验严谨性、写作清晰度和影响力生成评审。 paper PDF、language、paper-search settings、extra context review report、annotations、key references、related-work analysis Paper Review

每个模块都有单独的流程和架构说明页，且包含 Mermaid 流程图：

前端入口

首页 / 是 OpenResearchFlow 的模块总览页，展示当前 active modules、模块能力和 OpenResearchFlow 架构图。

workspace 侧边栏只展示当前需要面向用户开放的模块：

  • idea_gen_v2 展示为 Idea Gen
  • idea2exp 展示为 Idea2Exp
  • exp_gen_v2 展示为 ExpGen V2
  • exp_run 展示为 ExpRun
  • draft_gen 展示为 Draft Gen
  • papercheck 展示为 Paper Check
  • review_gen 展示为 Paper Review
  • paper2figure 展示为 Paper2Figure
  • paper2title 展示为 Paper2Title

DeerFlow 自带的 chat 功能和历史 preview modules 不属于当前 OpenResearchFlow 主导航。当前主工作台默认从 /workspace 跳转到 /workspace/idea-gen， 每个模块页面负责创建 run、导入上游 session、展示状态、查看 artifacts 和 打开模块级 Runtime/API Key 配置。

流水线衔接

OpenResearchFlow 支持从一个模块的 run 结果继续启动下游模块，减少手动复制路径和 上下文的工作：

idea_gen_v2 -> idea2exp -> exp_gen_v2 -> exp_run -> draft_gen
                                             |
                                             -> papercheck / review_gen
draft_gen -> paper2figure / paper2title

前端 handoff helpers 会把上游 run 的关键字段、artifact 路径和 summary 压缩为下游模块的初始输入。UpstreamSessionImporter 可在表单中导入已有 run， 通用 artifact preview 用同一套相对路径规则查看文本、JSON、PDF 和图片产物。

界面预览

下列截图来自 mock demo，无需任何 API key 即可在本地复现。

首页模块总览：

OpenResearchFlow 首页

模块 界面
Idea Gen Idea Gen
Idea2Exp Idea2Exp
ExpGen V2 ExpGen V2
ExpRun ExpRun
Draft Gen Draft Gen
Paper2Figure Paper2Figure
Paper2Title Paper2Title
Paper Check Paper Check
Paper Review Paper Review

Artifact 目录规范

模块产物统一落在：

backend/output/<module>/<run_id>/
  run.json
  events.jsonl
  <artifact files and directories>

run.json.artifacts 必须使用相对路径，前端 artifact preview 和下游 session import 都基于这些稳定路径工作。详细规范和各模块关键产物见 docs/open-source/artifact-contract.md。

本地开发

单独启动前端（gateway 已在别处运行时）：

cd frontend
pnpm dev

后端测试：

cd backend
uv run pytest tests/ -v

前端检查：

cd frontend
pnpm typecheck
pnpm lint

其他约定：

  • gateway APIs 挂载在 /api/... 下，本地开发时由 frontend/next.config.js 转发。
  • 模块 run artifacts 默认存储在 backend/output/<module>/...，除非模块支持显式 output path。
  • 长时间实验模块可能需要模型服务凭据、GitHub token、数据集访问权限或 CLI-agent 配置。
  • 本地 .env、.env.cc、生成输出和临时研究 artifacts 不应提交，除非它们被明确整 理为 docs 或 tests。
  • README 图片的可复现 image-generation prompts 保存在 docs/assets 中。

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

13 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages