English | 简体中文 | Installation Guide
All Resophy code is built using Cursor (Sonnet 4.5/Auto) generation with manual verification
12.11.1.mp4
In this era of information explosion, researchers often feel overwhelmed when facing massive amounts of papers. How to quickly extract the essence and understand cutting-edge achievements has become a pain point for every researcher. Resophy was born with the intention of helping you bid farewell to inefficient paper reading, empowering researchers, and making paper reading more efficient and intelligent 📚⚡.
Resophy is a fully open-source, Vibe Coding-oriented modern paper reader that helps you quickly understand the core content of papers through a simple tech stack (HTML + JavaScript + Python Flask) and AI features 🤖💡. From automatic translation to paper parsing, from intelligent recommendations to one-click Zotero import, Resophy provides a one-stop solution for your paper reading needs 📑✨. Most importantly, you can customize features at any time through Vibe Coding, creating a paper assistant tailored to you 🎨🛠️.
- Resophy - Core Features
- Main Service (Resophy Core): HTML + JavaScript + Python Flask backend service, providing core features such as paper management, classification, and search
- AI Services include:
- LLM Server: LLM inference service for AI translation, interpretation, and arXiv paper analysis (optional, supports local deployment or remote API)
- MinerU Server: Document parsing service for PDF to Markdown parsing (optional, for AI features)
Resophy uses uv for dependency management and supports separated deployment architecture. You can deploy Resophy main service and AI servers on different machines. For installation and configuration instructions, please refer to:
| System | Documentation |
|---|---|
| Windows / Mac / Linux | Installation Guide |
In this section, we briefly introduce some usage methods of Resophy
| Configuration Module | Location | Main Features | Usage |
|---|---|---|---|
| 📸 User Settings | Settings Interface → "User" Tab | • Avatar upload • Username setting • Reading heatmap color theme • Recent reading records |
1. Click avatar in top right corner 2. Enter "User" tab 3. Upload avatar, set username, select color 4. Auto-save settings |
| 🤖 Agentic Settings | Settings Interface → "Agentic" Tab | • LLM API configuration (model name, URL, key) • MinerU server configuration • AI interpretation prompt customization |
1. Enter "Agentic" tab 2. Configure LLM API and MinerU address 3. (Optional) Customize prompts 4. Test connection and save |
| 📰 Daily arXiv | Settings Interface → "Daily arXiv" Tab | • arXiv category configuration (cs.CV, cs.AI, etc.) • Crawling settings (retention days, check interval) • Keyword list (for intelligent classification) • Institution configuration |
1. Enter "Daily arXiv" tab 2. Add arXiv categories 3. Configure crawling parameters and keywords 4. (Optional) Add custom institutions 5. Save settings |
| 📥 Zotero Import | Settings Interface → "Import" Tab | • Target directory selection • RDF file drag-and-drop upload • Import progress display • Import result statistics |
1. Export from Zotero as RDF format 2. Enter "Import" tab 3. (Optional) Select target directory 4. Drag and drop RDF file 5. View import progress and results |
Expand for Detailed Introduction
Feature Details:
- Avatar Upload: Click avatar area to upload custom avatar, supports preview and cropping
- Username Setting: Enter username (default: Paper Reader)
- Reading Heatmap Color: Select color theme (green/blue/rose pink) for visualizing daily reading time
- Recent Reading Records: Display list of recently read papers for quick access to history
Feature Details:
- LLM API Configuration:
- Model Name: Enter model name (e.g.,
Qwen3-4B-Instruct-2507) - Base URL: Enter API address (local:
http://0.0.0.0:6002/v1or remote API) - API Key: Enter access key
- Test Button: Verify API connection
- Model Name: Enter model name (e.g.,
- MinerU Server Configuration: Enter server address (e.g.,
http://0.0.0.0:6001) for PDF parsing - AI Interpretation Prompt: Large text editor for customizing System Prompt, controlling AI interpretation generation style
Purpose: Unified AI feature configuration for translation, interpretation, Daily arXiv, and all other AI features
Feature Details:
- arXiv Category Configuration: Add/delete category tags (cs.CV, cs.AI, etc.), provides quick buttons for common categories
- Crawling Settings: Paper retention days (1-30 days), check interval (5-60 minutes)
- Keyword List: Add keyword tags, set maximum number of keywords (1-3), for AI automatic classification
- Institution Configuration: Add custom institutions, supports editing abbreviations and full name variants
Feature Details:
- Target Directory Selection: Dropdown menu to select import location (optional, default root directory)
- File Upload Area: Large drag-and-drop upload area, supports dragging
.rdffiles - Import Progress Display: Progress bar, status text, cancel button
- Import Result Statistics: Success/failure/skip/duplicate counts
Usage Steps:
- Export library from Zotero as RDF format
- Enter "Import" tab in Resophy settings interface
- (Optional) Select target directory
- Drag RDF file to upload area
- System automatically parses and imports papers, displays import progress and results
View Basic Operations
| Operation Module | Main Features | Usage |
|---|---|---|
| 📚 Paper Management | • Upload papers (drag PDF or enter arXiv URL) • Category management (create/rename/delete categories, move papers) • Full-text search (title, author, abstract) |
1. Drag PDF to upload area or enter arXiv URL 2. Manage category structure with left category tree 3. Use top search box for full-text search |
| 📖 Paper Viewing | • View paper details • PDF reader • Automatic reading time recording |
1. Click paper card to enter details page 2. View metadata and abstract 3. Click "View PDF" to open reader |
| ✏️ Metadata Management | • Edit paper information (title, author, abstract, etc.) • Add notes and tags • Manage BibTeX citations • Set links (GitHub, homepage) |
1. Enter paper details page 2. Click "Edit" button 3. Modify information and save |
| 📈 Reading History | • Automatic reading time recording • Reading heatmap (visualize daily reading statistics) • Recent reading records |
View reading heatmap and recent reading list in user settings |
| 📥 Export Function | • Export paper library as JSON format • Includes metadata and category structure |
1. Enter settings interface 2. Select export scope 3. Download JSON file |
📝 Automatic Paper Metadata Retrieval:
When uploading papers (via arXiv URL or dragging PDF), the system automatically retrieves paper metadata:
-
Get Basic Information via arXiv API:
- Call arXiv API to get paper title, authors, abstract, year, etc.
- Download PDF file
-
Get BibTeX via DBLP API:
- Use paper title and author information to call DBLP API
- Attempt to get more accurate BibTeX citation format
- If DBLP retrieval succeeds, use DBLP BibTeX; otherwise use arXiv BibTeX
-
Processing Flow for Drag-and-Drop PDF Upload:
- System attempts to extract arXiv ID from filename or PDF metadata
- If arXiv ID is found, call arXiv API to get information
- Asynchronously call DBLP API in background to update BibTeX
View AI Translation
Implementation Method:
Resophy's AI translation feature uses the Babeldoc tool to implement PDF bilingual translation:
-
Call babeldoc:
- Pass configured LLM API information (model, URL, key)
-
Translation Process:
- babeldoc reads original PDF file
- Call LLM API for translation (supports OpenAI-compatible interface)
- Generate bilingual PDF (
.zh.dual.pdf), original and Chinese translation displayed side by side
Usage:
- Select a paper in main interface
- Click "AI Translation" button
- System executes translation task in background
- After translation completes, view bilingual PDF in paper details page
View AI Interpretation
Implementation Method:
Resophy's AI interpretation feature uses a two-step process to deeply analyze paper content:
-
Parse PDF to Markdown:
- Use MinerU tool to parse PDF into structured Markdown
- Connect to configured MinerU server (supports vLLM deployment)
- Preserve images, tables, and other elements, generate high-quality Markdown document
-
LLM Deep Interpretation:
- Use
openailibrary to call LLM API (supports OpenAI-compatible interface) - Use Markdown content as input, combined with custom System Prompt
- LLM generates structured interpretation report (summary, methods, experiments, conclusions, etc.)
- Supports custom prompts to control interpretation style and content format
- Use
Usage:
- Select a paper, click "AI Interpretation" button
- System starts background task:
- Step 1: MinerU parses PDF to Markdown
- Step 2: LLM deeply analyzes and generates interpretation report
- View progress and logs in "Interpretation Tasks" page
- After interpretation completes, click paper to enter interpretation view for detailed analysis
View Daily arXiv Feature
Implementation Method:
Daily arXiv feature automatically crawls latest arXiv papers and uses AI for intelligent analysis and filtering:
-
Paper Crawling:
- Use
arxivPython library to crawl papers from specified categories - Supports scheduled automatic checking (configurable check interval)
- Organize papers by date and category
- Use
-
AI Feature Application:
a. Institution Information Extraction:
- Use
openailibrary to call LLM API - Extract institution names (affiliations) from PDF first page text
- Extract institution countries
- Extract project homepage and GitHub repository URL
- Supports institution name standardization and abbreviation recognition
b. Abstract Summary and Keyword Extraction:
- Use
openailibrary to call LLM API - Generate Chinese summary (100-200 words) from paper English abstract
- Select keywords (1-3) that best represent paper type from preset keyword list
- Keywords used for subsequent intelligent filtering and classification
- Use
-
Intelligent Filtering:
- Filter papers based on configured keyword list
- Filter papers based on institution information
- Supports custom institution mapping and standardization
-
Background Tasks:
- Scheduled automatic checking for new papers (configurable interval)
- Background PDF file download
- Asynchronous AI analysis task execution
- Automatic cleanup of expired papers (configurable retention days)
Usage:
- Configure arXiv categories (e.g., cs.CV, cs.AI) in settings
- Set keyword list and filtering conditions
- Click "Daily arXiv" button to get today's papers
- System automatically crawls, downloads, and analyzes papers
- Browse matching paper list, batch import to reading list
Resophy adopts the Vibe Coding development philosophy, which means you can easily customize and extend features through natural language conversations with AI Coding Agent. No need to deeply understand complex code structures, just describe your needs, and AI will help you implement them.
vibecoding1.mp4
Using Vibe Coding to customize features is very simple, just two steps:
When conversing with Coding Agent, first enter the following prompt:
Please understand the functionality of this paper reading platform
This prompt will make AI automatically analyze the entire codebase structure, features, and implementation methods, establishing comprehensive understanding of the project. AI will:
- Analyze project architecture (frontend HTML/JS + backend Flask)
- Understand core feature modules (paper management, AI translation, AI interpretation, Daily arXiv, etc.)
- Familiarize with code organization (routes, utility functions, data models, etc.)
- Master existing code style and design patterns
After AI understands the codebase, you can directly describe the features you want to implement. For example:
Example 1: Add Dark Mode
Please add a dark mode for me, add a button in the top right corner, click to switch to dark mode, convenient for reading papers in dim light
Example 2: Add Paper Tag Feature
I want to add a paper tag feature, can add multiple tags to each paper, and can filter papers by tags
Example 3: Export as BibTeX
Please add a feature to export selected papers as BibTeX format file
Example 4: Custom Shortcuts
I want to add keyboard shortcuts, like pressing 'j' and 'k' keys to navigate up and down in the paper list
Understanding the project structure helps you better describe your needs. Resophy adopts a clear layered architecture:
Resophy/
├── app.py # Flask application entry, route registration
├── resophy/
│ ├── core/ # Core data models
│ │ ├── base_paper.py # Paper data model
│ │ ├── paper_store.py # Paper storage management
│ │ └── search_index.py # Full-text search index
│ ├── routes/ # Route handlers
│ │ ├── basic_routes/ # Basic feature routes (paper operations, categories, search, etc.)
│ │ └── agent_routes/ # AI feature routes (translation, interpretation)
│ └── tools/ # Utility functions
│ ├── basic_tools/ # Basic tools (arXiv, PDF processing, category management, etc.)
│ └── agent_tools/ # AI tools (translation, interpretation)
├── templates/ # HTML templates
│ ├── index.html # Main interface
│ ├── pdf_viewer.html # PDF reader
│ └── analysis_viewer.html # AI interpretation viewer
├── static/
│ ├── css/
│ │ └── style.css # Style file
│ └── js/
│ └── app.js # Frontend JavaScript
└── papers/ # Paper storage directory (user data)
Key Concepts:
- Routes: Handle HTTP requests, define API endpoints
- Utility Functions (Tools): Encapsulate business logic, can be called by routes
- Data Models (Core): Define data structures (such as
Paperclass) - Frontend (Templates + Static): User interface and interaction logic
To help AI better understand your needs, it's recommended to include in the prompt:
- Feature Description: Clearly explain what feature to implement
- Interaction Method: Describe how users operate (click button, shortcuts, menu, etc.)
- Interface Location: Specify where the feature is in the interface (top right corner, sidebar, paper card, etc.)
- Data Storage: Whether user preferences need to be saved (such as dark mode toggle)
- Special Requirements: If there are special styles, animation effects, etc., explain them together
Good Prompt Example:
Please add a dark mode feature for me:
1. Add a moon icon button in the top right navigation bar (next to avatar button)
2. Click to switch to dark theme, icon changes to sun
3. Click again to switch back to light theme
4. User preference settings need to be saved, automatically restore after page refresh
5. Dark theme needs to adapt to all interface elements (navigation bar, sidebar, paper cards, settings page, etc.)
The following are some common customization need examples, you can refer to these ideas:
| Feature | Prompt Example |
|---|---|
| Theme Customization | "Please add a theme selector, support multiple color themes (blue, green, purple), users can select in settings" |
| Export Function | "Add a feature to export paper list as CSV file, including title, author, year, and other information" |
| Batch Operations | "Implement batch marking feature, can simultaneously add favorite marks or tags to multiple papers" |
| Search Enhancement | "Enhance search function, support combined search by year range, author, keywords" |
| Reading Statistics | "Add reading statistics panel, display total reading time, number of papers read, most frequently read categories, etc." |
| Quick Actions | "Add right-click menu, right-click on paper card to quickly execute translation, interpretation, delete, and other operations" |
- Code Style: AI will automatically follow the project's existing code style, maintaining consistency
- Testing Recommendations: After adding new features, it's recommended to manually test to ensure functionality is normal
- Compatibility: If core features are modified, pay attention to check if existing features are affected
- Data Backup: Before adding features that may affect data, it's recommended to backup the
papers/directory first
Resophy uses the CC BY-NC 4.0 open source license, please refer to the LICENSE file.