ResearchBrain

English | 한국어

ResearchBrain은 Windows를 위한 로컬 우선 연구 지식 워크벤치로, 문헌의 발견, 수집, 관리, 읽기, 분석, 검색, 조사 및 인용을 중심으로 원시 자료에서 추적 가능한 연구 결론까지의 통합 워크플로를 제공합니다.

Zotero의 서지 레코드, 컬렉션, 태그 및 PDF를 증분 미러링할 수 있을 뿐만 아니라 DOI 일괄 가져오기 및 Crossref, OpenAlex, arXiv, PubMed 등의 소스를 통해 문헌을 발견하고,合规적인 오픈 소스에서 전문을 가져올 수 있습니다. 가져온 문헌은 DOI 등의 식별자로 중복 제거되며, PDF는 직접 읽을 수 있고 MinerU 또는 PyMuPDF를 통해 페이지 번호와 섹션 위치가 포함된 Markdown으로 변환됩니다. 서지 레코드, 초록 및 전문이 각각 벡터화되어 로컬 검색, 로컬 우선의 온라인 보충 및 전범위 조사에 사용할 수 있습니다. 각 답변에는 원문 증거, 페이지 번호 또는 온라인 출처가 보존되며, 온라인에서 발견된 문헌은 계속 라이브러리로 가져올 수 있고, 이전 세션은 복구할 수 있으며, 참고 문헌은 CSL-JSON, BibTeX, RIS, DOI 목록 또는 Markdown으로 내보낼 수 있으며, MCP를 통해 Codex 등의 클라이언트에서 호출할 수 있습니다.

서지 레코드, PDF, 분석 결과물, 벡터 인덱스 및 대화 기록은 기본적으로 로컬에 저장됩니다. 사용자가 온라인 검색을 활성화하거나 MiniMax, DeepSeek를 호출할 때만 해당 요청이 전송됩니다. 애플리케이션은 Windows 11에서 독립적으로 실행되며 WSL, gbrain, Docker 또는 PostgreSQL에 의존하지 않습니다.

현재 0.1.8 alpha입니다. 핵심 연구 루프는 실행 가능하지만 Zotero의 완전한 대체는 아닙니다.

핵심 기능

• 로컬 문헌 라이브러리: 독립 라이브러리 또는 Zotero 읽기 전용 미러; Zotero library version에 따라 서지 레코드, 저자, 컬렉션, 태그 및 PDF 첨부 파일을 증분 동기화하며 초록 벡터화 상태와 PDF 전문 벡터화 상태를 각각 표시합니다.

• 식별 및 증분 판단: 표준화된 DOI/PMCID/PMID/arXiv로 문헌을 식별하고 SHA-256으로 PDF를 식별합니다. 서지 레코드만 있음, 초록 색인 완료, PDF 저장 완료, PDF 분석 완료, 전문 색인 완료의 다섯 가지 상태를 명확히 구분합니다.

• 문헌 수집: 일괄 DOI, Crossref 메타데이터, Crossref/OpenAlex/arXiv/PubMed 온라인 검색, 다중 식별자 중복 제거, DOI 없는 레코드도 가져올 수 있습니다.

• 법적 전문: Unpaywall, OpenAlex, PMC 및 개방형 라이선스가 있는 Crossref 링크를 통해 PDF를 찾고, 이미 오픈으로 확인된 랜딩 페이지에서 PDF를 추출합니다. 후보가 실패하면 자동으로 폴백하며, 수동으로 PDF를 첨부할 수 있습니다.

• PDF 분석: MinerU 우선, PyMuPDF 폴백, Markdown, 구조화된 JSON, 페이지 번호, 섹션 및 그림 위치를 출력합니다.

• 로컬 검색: MiniMax embo-01이 서지 레코드, 초록 및 PDF 전문을 동시에 벡터화하고, LanceDB가 전문, 벡터 및 RRF 융합 정렬을 제공합니다. 빈 라이브러리도 명확한 준비 상태 설명을 반환합니다.

• 증거 기반 질의응답: '로컬 전용', '로컬 우선 + 온라인', '전범위 조사' 지원; DeepSeek는 제공된 로컬 또는 온라인 증거 ID만 인용할 수 있습니다.

• 연속 대화: 라이브러리별로 모든 세션, 메시지 및 인용을 영구 저장하고 복구 가능; 현재 질문의 검색 가중치는 1.0, 최근 질문의 컨텍스트 검색 가중치는 0.25, 과거 모델 답변은 컨텍스트 이해에만 사용되며 증거 가중치는 항상 0입니다.

• Scholar 보충: 검색식을 브라우저의 Google Scholar에 직접 전달하여 불안정한 페이지 스크래핑에 의존하지 않습니다.

• 문헌 내보내기: CSL-JSON, BibTeX, RIS, DOI 목록 및 Markdown.

• Agent 연동: FastAPI, CLI, 데스크탑 앱 및 stdio MCP가 동일한 SQLite 및 LanceDB 데이터를 공유합니다.

Related MCP server: surveyHelper

설계 경계

• Zotero 미러는 단방향 읽기 전용이며 zotero.sqlite, 첨부 파일 또는 컬렉션에 쓰지 않습니다.

• Zotero Desktop Local API는 삭제 레코드 엔드포인트를 제공하지 않습니다. 추가, 수정 및 새 PDF/교체 PDF는 증분 동기화되지만, Zotero에서 삭제된 항목은 현재 미러에서 자동으로 삭제되지 않습니다.

• 자동 전문 가져오기는 Sci-Hub, LibGen 또는 유료 장벽 우회 서비스를 통합하지 않습니다.

• PDF, 서지 레코드, 벡터 라이브러리 및 채팅 기록은 기본적으로 로컬에 남습니다. MiniMax/DeepSeek를 호출할 때 관련 텍스트가 선택한 서비스 제공업체로 전송됩니다.

• 기본 설치 패키지에는 MinerU 모델이 포함되지 않습니다. MinerU를 구성하지 않으면 자동으로 PyMuPDF를 사용합니다.

• 0.1.x에는 고급 서지 레코드 편집, 복잡한 중복 항목 병합, PDF 주석 또는 팀 협업이 포함되지 않습니다.

자세한 내용은 개인정보 및 보안 경계 및 라이선스 설명을 참조하세요.

아키텍처

flowchart LR
  UI["Tauri + React"] --> API["FastAPI sidecar"]
  MCP["Codex / MCP client"] --> CORE["Shared services"]
  API --> CORE
  CORE --> DB["SQLite"]
  CORE --> IDX["LanceDB"]
  CORE --> OBJ["Content-addressed PDFs"]
  CORE --> ZOT["Zotero Local API"]
  CORE --> NET["Crossref / OpenAlex / arXiv / PubMed / Unpaywall"]
  CORE --> MODELS["MiniMax / DeepSeek"]

아키텍처 결정, 프로세스 모델 및 데이터 소유권에 대해서는 아키텍처 문서를 참조하세요.

소스 코드에서 실행

전제 조건

• Windows 11 x64

• Python 3.11

• Node.js 20

• Rust stable MSVC

• Visual Studio C++ Build Tools, WebView2 및 PowerShell 7 또는 Windows PowerShell

• uv 설치 권장

git clone git@github.com:cacity/ResearchBrain.git
cd ResearchBrain

uv venv --python 3.11
uv sync --all-extras --group dev
$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m researchbrain.cli init

cd desktop
npm ci
npm run tauri dev

로컬 API 및 브라우저 프런트엔드만 시작:

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m researchbrain.cli serve
cd desktop
npm run dev

프로덕션 데스크탑 버전은 루프백 포트를 무작위로 선택하고 256비트 세션 토큰을 생성합니다. 개발 API는 기본적으로 127.0.0.1:8765를 사용하고, Vite는 기본적으로 127.0.0.1:1420을 사용합니다.

첫 번째 구성

1. '설정'에서 Crossref, Unpaywall, OpenAlex 및 PubMed에 사용할 연락처 이메일을 입력합니다.

2. 선택 사항: NCBI 및 OpenAlex API Key를 입력하여 더 안정적인 온라인 검색 할당량을 얻습니다.

3. Zotero 데이터 디렉터리를 확인합니다(예: %USERPROFILE%\Zotero). Zotero에서 로컬 API를 활성화합니다.

4. MiniMax 및 DeepSeek 키를 Windows Credential Manager에 저장합니다.

5. 선택 사항: MinerU를 설치하고 '설정 > 문서 분석'에서 mineru.exe의 전체 경로를 입력합니다.

6. 'Zotero 읽기 전용 미러' 라이브러리를 생성하고 'Zotero 감지'를 클릭한 후 첫 번째 동기화를 실행합니다. 이후 '증분 동기화'를 클릭하면 library version 워터마크 이후에 추가되거나 수정된 서지 레코드 및 PDF만 처리됩니다.

7. 동기화 통계에서 새 서지 레코드, PDF, 누락된 첨부 파일, 분석 및 벡터 수를 확인합니다. '작업' 페이지에서 실패한 작업을 일괄 재시도할 수 있습니다.

기본 데이터 디렉터리는 %LOCALAPPDATA%\ResearchBrain입니다:

ResearchBrain/
  config/settings.json       # 不含密钥的设置
  data/library.sqlite        # 题录、任务、对话和出处
  data/lancedb/              # 可重建检索索引
  library/objects/           # SHA-256 内容寻址 PDF
  artifacts/                 # Markdown、JSON 和图表产物
  runtime/                   # 可回滚外部组件

Codex 및 MCP

데스크탑 버전을 설치한 후 '설정 > Codex'에서 'MCP 등록'을 클릭하고 새 Codex 작업을 생성하여 호출합니다:

• list_libraries

• get_item

• search_library

• ask_library

• export_references

소스 코드 환경에서도 실행할 수 있습니다:

.\scripts\register_codex_mcp.ps1
codex.cmd mcp list

테스트 및 빌드

.\.venv\Scripts\python.exe -m ruff format --check --no-cache src tests scripts
.\.venv\Scripts\python.exe -m ruff check --no-cache src tests scripts
.\.venv\Scripts\python.exe -m pytest -p no:cacheprovider
cd desktop
npm run typecheck
npm run format:check

Windows 설치 패키지:

.\scripts\build_release.ps1

전체 개발, 테스트 및 릴리스 프로세스는 개발 가이드, 릴리스 가이드 및 GitHub 릴리스 체크리스트를 참조하세요.

저장소 구조

src/researchbrain/       Python 业务核心、API、CLI 和 MCP
desktop/src/             React/TypeScript 桌面界面
desktop/src-tauri/       Rust/Tauri 宿主和 sidecar 生命周期
src/researchbrain/migrations/  Alembic 数据库迁移
tests/                   Python 自动化测试
scripts/                 构建、注册、冒烟和视觉检查脚本
docs/                    架构、隐私、许可、路线图和开发文档
.github/                 CI、依赖更新和协作模板

기여하기

문제를 제출하기 전에 기여 가이드, 지원 설명 및 보안 정책을 읽어주세요. 개인 PDF, Zotero 데이터베이스, API 키, 브라우저 쿠키 또는 개인 경로가 포함된 로그를 업로드하지 마세요.

라이선스

프로젝트는 GNU Affero General Public License v3.0 only로 배포됩니다. PyMuPDF, MinerU 및 기타 타사 구성 요소는 각각의 라이선스를 유지합니다. 배포 전에 타사 라이선스 설명을 읽어야 합니다.