mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
No description
9691d68970
- Add paper_root, main_note_path, fulltext_path, deep_reading_path, ai_path to _build_entry() result dict (Phase 22 paper workspace layout, D-12) - Mirror workspace path fields in formal note frontmatter for Base views (D-14) - Add --rebuild-index flag to cli.py sync command parser - Thread rebuild_index parameter through commands/sync.py -> run_index_refresh() - Existing system paths (ocr_path, meta_path, note_path) preserved (D-13) - All 14 existing tests pass |
||
|---|---|---|
| .planning | ||
| command | ||
| docs | ||
| paperforge | ||
| scripts | ||
| tests | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| manifest.json | ||
| paperforge.json | ||
| pyproject.toml | ||
| README.en.md | ||
| README.md | ||
| README.zh-CN.md | ||
| requirements.txt | ||
| setup_wizard.py | ||
| token-usage-output.txt | ||
PaperForge
简体中文 · English
Forge Knowledge, Empower Insight.
PaperForge is an Obsidian-based literature workspace for researchers. It turns Zotero libraries, PDFs, figures, and OCR output into structured notes, searchable corpora, and AI-ready reading workflows.
The tone of the project is inspired by a forge: raw papers go in, usable knowledge assets come out. The product itself stays practical, installation-focused, and built for real research work.
Download plugin → Enable in Obsidian → Open wizard → Fill config → Click Install → Done
What PaperForge Does
PaperForge connects the full path from source literature to structured insight.
| Layer | Output | Use it for |
|---|---|---|
| Index cards | Structured metadata records with frontmatter | Search, browse, Base views |
| Full-text corpus | OCR-generated fulltext.md |
LLM workflows, RAG, QA |
| Figure database | Figure images, captions, and figure maps | Multimodal analysis and evidence tracing |
| Deep reading notes | 3-pass AI analysis with chart review and critique | Reviews, synthesis, writing prep |
Why It Feels Different
- Short setup path: plugin install plus guided wizard, not a terminal-heavy onboarding.
- Full workflow: sync, OCR, figures, notes, and agent commands live around the same vault.
- AI-ready outputs: not just files, but research assets that are easy to retrieve, inspect, and reuse.
- Built around existing tools: PaperForge extends Zotero and Obsidian instead of replacing them.
Install
Obsidian Plugin (Recommended)
- Download the plugin files from the latest release.
- Copy them into
vault/.obsidian/plugins/paperforge/. - Enable
PaperForgein Obsidian community plugins. - Open the settings page and click
打开安装向导. - Follow the 5-step wizard: Overview → Directory Config → Agent & Keys → Install → Done.
The wizard auto-detects Python, Zotero, and Better BibTeX before installation starts.
Prerequisites
| Software | Purpose | Get it |
|---|---|---|
| Python 3.9+ | Run PaperForge CLI and backend tasks | https://python.org |
| Zotero | Literature management | https://zotero.org |
| Better BibTeX | Auto-export metadata as JSON | https://retorque.re/zotero-better-bibtex/ |
| PaddleOCR Key | OCR text and layout extraction | https://aistudio.baidu.com/paddleocr |
CLI (Advanced)
cd /path/to/your/vault
pip install git+https://github.com/LLLin000/PaperForge.git
python -m paperforge setup --headless --agent opencode --paddleocr-key <key>
Usage
| Action | How |
|---|---|
| Open Dashboard | Ctrl+P → PaperForge: Open Dashboard, or click the sidebar icon |
| Sync Literature | Dashboard → Sync Library |
| Run OCR | Dashboard → Run OCR |
| Deep Read | /pf-deep <zotero_key> |
| Quick Query | /pf-paper <zotero_key> |
Dashboard
Commands
Obsidian Commands
| Command | Description |
|---|---|
PaperForge: Open Dashboard |
Open the status panel and quick actions |
PaperForge: Sync Library |
Sync Zotero and generate notes |
PaperForge: Run OCR |
Extract full text and figures |
Agent Commands
| Command | Description | Requires |
|---|---|---|
/pf-deep <key> |
Full 3-pass deep reading | OCR complete |
/pf-paper <key> |
Quick paper QA | Formal note exists |
/pf-sync |
Sync Zotero | Installed |
/pf-ocr |
Run OCR | Installed |
/pf-status |
System status | Installed |
CLI Commands
| Command | Description |
|---|---|
paperforge sync |
Sync Zotero and generate notes |
paperforge ocr |
Run OCR |
paperforge status |
Show system overview |
paperforge doctor |
Diagnose configuration |
paperforge update |
Update PaperForge |
Supported Agent Platforms
| Platform | Agent Commands | Setup |
|---|---|---|
| OpenCode | Full /pf-* support |
.opencode/command/ + .opencode/skills/ |
| Claude Code | /pf-deep, /pf-paper |
.claude/skills/ |
| Cursor | /pf-deep, /pf-paper |
.cursor/skills/ |
| GitHub Copilot | /pf-deep, /pf-paper |
.github/skills/ |
| Windsurf | /pf-deep, /pf-paper |
.windsurf/skills/ |
| Codex | $pf-deep, $pf-paper |
.codex/skills/ |
| Cline | /pf-deep, /pf-paper |
.clinerules/ |
Docs
| Document | Content |
|---|---|
| Setup Guide | Full setup walkthrough |
| Quick Install | Short install path |
| Post-Install Guide | First-use workflow guide |
| Changelog | Version history |
| Contributing | Dev setup and conventions |
License
CC BY-NC-SA 4.0. Non-commercial use only.
Acknowledgments
PaperForge builds on excellent open-source foundations:
| Project | Role |
|---|---|
| PaddleOCR / PaddleOCR-VL | PDF OCR, layout detection, and figure extraction |
| Obsidian | Knowledge workspace and plugin host |
| Better BibTeX for Zotero | Metadata auto-export |
| PyMuPDF (fitz) | Local PDF validation and sanitization |
| requests | OCR API client |
| tenacity | Retry logic |
| Pillow | Figure image processing |
| tqdm | Progress bars |
| textual | TUI components |
PaperForge aims to turn scattered papers, figures, and notes into research assets you can actually work with.