obsidian-plugin/lllin000_PaperForge
1
0
Fork 0
mirror of https://github.com/lllin000/PaperForge.git synced 2026-07-22 17:00:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
No description
318 commits 4 branches 19 tags 51 MiB
Python 79%
TypeScript 12.9%
JavaScript 6.1%
CSS 1.7%
Shell 0.2%
Other 0.1%
Find a file
Research Assistant 566e9cf5fb fix: overhaul install flow clarity and non-destructive incremental setup 
- Move Better BibTeX auto-export to post-install step (exports dir created by setup)
- Clarify wizard overview: show resources_dir/literature_dir/control_dir hierarchy
- Fix post-install flow order: BBT export → enable plugin → dashboard → sync
- Split do_ocr and analyze marks into separate steps (OCR before deep-reading)
- Mark all literature flags via Base views, not manual file editing
- Make installer incremental: preserve existing files, only create missing ones
- Remove destructive junction/link deletion in TUI wizard
- Merge .env instead of overwriting; skip overwrite for AGENTS.md, docs, plugin
- Update TUI, headless, and plugin completion output to match corrected flow
- Add regression test for non-destructive setup behavior
2026-05-06 14:57:29 +08:00
.planning chore: bump version to v1.4.12 2026-04-30 14:12:45 +08:00
command fix: VaultStep.__init__ missing step_id and checker in super() call 2026-04-27 19:49:36 +08:00
docs fix: overhaul install flow clarity and non-destructive incremental setup 2026-05-06 14:57:29 +08:00
paperforge fix: overhaul install flow clarity and non-destructive incremental setup 2026-05-06 14:57:29 +08:00
scripts fix: bump.py creates tags without v prefix (Obsidian compatibility) 2026-05-01 12:17:14 +08:00
tests fix: overhaul install flow clarity and non-destructive incremental setup 2026-05-06 14:57:29 +08:00
.gitignore gitignore: add .worktrees/ 2026-04-28 16:02:04 +08:00
.pre-commit-config.yaml feat(17-dead-code-precommit): add ruff config, pre-commit hooks, Check 5, and OCR error context 2026-04-27 17:29:13 +08:00
AGENTS.md fix: overhaul install flow clarity and non-destructive incremental setup 2026-05-06 14:57:29 +08:00
CHANGELOG.md chore: bump version to v1.4.13 2026-05-01 11:14:59 +08:00
CONTRIBUTING.md chore: rename PaperForge Lite -> PaperForge across 27 files 2026-04-28 01:25:51 +08:00
LICENSE docs: add CC BY-NC-SA 4.0 license and acknowledgments 2026-05-01 11:37:50 +08:00
manifest.json fix: sync description across manifests; fix authorUrl to personal URL 2026-05-01 12:16:15 +08:00
paperforge.json refactor: __init__.py as single version source; pyproject.toml reads dynamically; paperforge.json drops version field 2026-04-28 22:41:48 +08:00
pyproject.toml fix: support pip-installed setup asset deployment and optional AGENTS guide 2026-05-06 11:57:02 +08:00
README.en.md feat: refine plugin onboarding copy and dashboard branding 2026-05-02 15:18:51 +08:00
README.md 更新 README.md 2026-05-02 17:17:16 +08:00
README.zh-CN.md docs: redesign README with banner and dashboard preview 2026-05-02 14:52:59 +08:00
requirements.txt fix: add textual to requirements.txt 2026-04-23 00:09:00 +08:00
setup_wizard.py chore: rename PaperForge Lite -> PaperForge across 27 files 2026-04-28 01:25:51 +08:00
token-usage-output.txt fix: restructure skills — separate pf-deep/pf-paper, add prefix substitution, create config_file on deploy 2026-04-28 18:33:11 +08:00

README.en.md

PaperForge banner

PaperForge

Version Python License

简体中文 · 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)

  1. Download the plugin files from the latest release.
  2. Copy them into vault/.obsidian/plugins/paperforge/.
  3. Enable PaperForge in Obsidian community plugins.
  4. Open the settings page and click 打开安装向导.
  5. 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

PaperForge 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.