mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 17:00:23 +00:00
294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
<p align="center">
|
|
<img src="docs/images/paperforge-banner.png" alt="PaperForge banner" width="100%" />
|
|
</p>
|
|
|
|
# PaperForge
|
|
|
|
[](https://github.com/LLLin000/PaperForge/releases)
|
|
[](https://python.org)
|
|
[](LICENSE)
|
|
|
|
[简体中文](README.zh.md) · **English**
|
|
|
|
> **铸知识为器，启洞见之明。 — Forge Knowledge, Empower Insight.**
|
|
|
|
PaperForge brings your Zotero library into Obsidian. Sync papers, run OCR, extract figures, and do AI-assisted deep reading — all inside a single vault.
|
|
|
|
---
|
|
|
|
## 0. What PaperForge Is
|
|
|
|
PaperForge is **not just an Obsidian plugin**. It has two parts:
|
|
|
|
| Part | What | Does | Where |
|
|
|------|------|------|-------|
|
|
| Obsidian Plugin | `main.js` + `manifest.json` + `styles.css` | Dashboard, buttons, settings UI | `.obsidian/plugins/paperforge/` in your vault |
|
|
| Python Package | `paperforge` | Sync, OCR, Doctor, repair | Your system Python (`pip install`) |
|
|
|
|
The plugin is the **interface**. The Python package is the **engine**. Every button you click in the plugin actually runs a Python command behind the scenes.
|
|
|
|
**After installing the plugin, you MUST verify that the Python package is also installed and version-matched.**
|
|
|
|
---
|
|
|
|
## 1. Install the Obsidian Plugin
|
|
|
|
### Option A: BRAT (Recommended)
|
|
|
|
1. Install **BRAT** from the Obsidian community plugin browser
|
|
2. Open BRAT settings → `Add Beta Plugin`
|
|
3. Enter: `https://github.com/LLLin000/PaperForge`
|
|
4. BRAT downloads the latest `main.js`, `manifest.json`, and `styles.css` and installs them
|
|
5. Settings → Community Plugins → enable PaperForge
|
|
|
|
> BRAT auto-detects GitHub Release updates. No manual downloads needed.
|
|
|
|
### Option B: Manual Download
|
|
|
|
1. Go to [Releases](https://github.com/LLLin000/PaperForge/releases)
|
|
2. Download the three files: `main.js`, `manifest.json`, `styles.css`
|
|
3. Create `.obsidian/plugins/paperforge/` in your vault
|
|
4. Put the three files there
|
|
5. Restart Obsidian → Settings → Community Plugins → enable PaperForge
|
|
|
|
> Manual install does not auto-update. You'll need to re-download for each new version.
|
|
|
|
---
|
|
|
|
## 2. Install the Python Package
|
|
|
|
After enabling the plugin, open the PaperForge settings tab. You'll see a **Runtime Status** section:
|
|
|
|
```
|
|
Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched
|
|
```
|
|
|
|
- If it says "Not installed" → click **Open Wizard** to re-run the setup process
|
|
- If it says "Mismatch" → the Python package auto-updates when the plugin updates. If it didn't succeed, click **Update Runtime** to manually trigger
|
|
|
|
---
|
|
|
|
## 3. How Python Interpreter Resolution Works
|
|
|
|
PaperForge needs to find a working Python on your system. It searches in this order:
|
|
|
|
| Priority | Source | Description |
|
|
|----------|--------|-------------|
|
|
| 1 | **Manual override** | Settings → `Custom Python Path`, enter the full path (e.g., `C:\Users\you\...\python.exe`). **This is the most reliable method.** |
|
|
| 2 | **venv auto-detect** | Scans `.paperforge-test-venv`, `.venv`, `venv` under your vault root |
|
|
| 3 | **System auto-detect** | Tries `py -3`, `python`, `python3` in order, verifies with `--version` |
|
|
| 4 | **Fallback** | Defaults to `python` if nothing else works |
|
|
|
|
> If you have multiple Python installations (e.g., system 3.9 + self-installed 3.11), **strongly recommend setting a manual path** in settings to avoid hitting the wrong one.
|
|
>
|
|
> The **Validate** button in settings immediately tests the resolved interpreter and shows its version.
|
|
|
|
---
|
|
|
|
## 4. Setup Wizard — What Each Step Means
|
|
|
|
Open the plugin settings panel (`Settings` → `Community plugins` → `PaperForge`) and click the **Open Wizard** button. The wizard walks you through configuration. Here's what every step does.
|
|
|
|
### 4.1 Vault Path
|
|
|
|
Your Obsidian vault root. Auto-detected, usually no need to change.
|
|
|
|
### 4.2 AI Agent Platform
|
|
|
|
PaperForge's deep reading features run through an AI Agent. The core mechanism is **trigger phrases**, not registered plugins: you type `/pf-deep <key>` directly into the Agent chat, and the Agent recognizes the trigger and loads the `literature-qa` Skill automatically.
|
|
|
|
The setup wizard deploys Skill files to the correct location:
|
|
|
|
| Agent | Skill location | Trigger example |
|
|
|-------|---------------|-----------------|
|
|
| **OpenCode** | `.opencode/skills/` + `.opencode/command/` | `/pf-deep <key>` |
|
|
| **Claude Code** | `.claude/skills/` | `/pf-deep <key>` |
|
|
| **Cursor** | `.cursor/skills/` | `/pf-deep <key>` |
|
|
| **GitHub Copilot** | `.github/skills/` | `/pf-deep <key>` |
|
|
| **Windsurf** | `.windsurf/skills/` | `/pf-deep <key>` |
|
|
| **Codex** | `.codex/skills/` | `$pf-deep <key>` |
|
|
| **Cline** | `.clinerules/` | `/pf-deep <key>` |
|
|
|
|
> **Key concept**: `/pf-deep` is NOT a plugin you install on the Agent platform — it's a Skill file deployed inside your Vault. Once the setup wizard copies the files into place, the Agent auto-discovers the triggers on startup. You type the trigger phrase just like any other chat input.
|
|
|
|
### 4.3 Directory Names
|
|
|
|
The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.**
|
|
|
|
| Parameter | Default | Purpose |
|
|
|-----------|---------|---------|
|
|
| `system_dir` | `System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. |
|
|
| `resources_dir` | `Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. |
|
|
| `literature_dir` | `Literature` | Formal literature notes directory. `paperforge sync` generates frontmatter `.md` notes here. |
|
|
| `base_dir` | `Bases` | Obsidian Base view definitions. Dashboard filters ("Pending OCR", "Ready to Read", etc.) are stored here. |
|
|
|
|
### 4.4 PaddleOCR API Token
|
|
|
|
OCR requires a PaddleOCR API key. Configured in `.env`:
|
|
|
|
```
|
|
PADDLEOCR_API_TOKEN=your-api-key
|
|
```
|
|
|
|
The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default.
|
|
|
|
### 4.5 Zotero Data Directory
|
|
|
|
PaperForge creates a junction (Windows) or symlink (macOS/Linux) linking your Zotero data directory into the vault. This is how Obsidian wikilinks resolve to PDF files.
|
|
|
|
The wizard auto-detects your Zotero installation. If detection fails, manually enter the path to your Zotero data directory — the folder that contains the `storage/` subdirectory (not the Zotero executable).
|
|
|
|
### 4.6 What Happens During Setup
|
|
|
|
After confirming your choices, the wizard automatically:
|
|
- Creates all needed directory structures
|
|
- Deploys Agent command files to the correct locations
|
|
- Installs Obsidian plugin files
|
|
- Creates the Zotero junction/symlink
|
|
- Writes `paperforge.json` and `.env`
|
|
|
|
The process is **incremental** — if files already exist in the chosen directories, the wizard only adds what's missing and never deletes existing content.
|
|
|
|
---
|
|
|
|
## 5. First-Time Setup Checklist
|
|
|
|
1. **Version match**: Settings → Runtime Status → confirm plugin and Python package match
|
|
2. **Python path**: Settings → Validate button → confirm it's the Python you want
|
|
3. **Setup wizard**: Settings → PaperForge → Open Wizard
|
|
4. **PaddleOCR key**: Enter your API token in `.env` (wizard guides this)
|
|
5. **Export from Zotero**: Right-click your library → `Export...` → format `Better BibTeX JSON` → check `Keep updated` → save to `<system_dir>/PaperForge/exports/`
|
|
6. **Run Doctor**: Dashboard → `Run Doctor` → all checks should pass
|
|
|
|
---
|
|
|
|
## 6. Daily Use
|
|
|
|
### Dashboard (Three-Mode Views)
|
|
|
|
`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views:
|
|
|
|
| View | Purpose |
|
|
|------|---------|
|
|
| **Global** | System homepage: run Sync, OCR, Doctor, and other mechanical operations |
|
|
| **Collection** | Batch workspace: browse paper queues by domain, batch tagging |
|
|
| **Per-paper** | Reading companion: `do_ocr` / `analyze` toggle checkboxes, discussion record cards |
|
|
|
|
> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed.
|
|
|
|
### AI Deep Reading & Q&A (Requires Agent)
|
|
|
|
Launch your Agent app and type commands into its chat input. **The more specific you are about the paper (Zotero Key, title, DOI), the faster the Agent locates it.**
|
|
|
|
| Route | Command | Does | Trigger examples | Prerequisites |
|
|
|-------|---------|------|-----------------|--------------|
|
|
| Deep Read | `/pf-deep <key>` | Keshav three-pass deep reading, writes to formal note | `deep read XX`, `walk me through`, `journal club` | OCR done, analyze: true |
|
|
| Q&A | `/pf-paper <key>` | Interactive paper Q&A, OCR not required | `take a look at XX`, `what does this paper say` | Formal note exists |
|
|
| Archive | `/pf-end` | Save current `/pf-paper` Q&A session | `save`, `end discussion` | During `/pf-paper` session |
|
|
|
|
### `/pf-end` Details
|
|
|
|
- `/pf-end` only applies to `/pf-paper` Q&A sessions. Deep reading (`/pf-deep`) writes directly to the formal note and does not need `/pf-end`.
|
|
- When executed, two files are created in the paper's workspace:
|
|
- `discussion.md` — human-readable Q&A discussion record
|
|
- `discussion.json` — structured Q&A data (with timestamps, source tags)
|
|
- Dashboard **Per-paper** view automatically displays these as discussion record cards
|
|
|
|
> Command prefixes vary by platform (mostly `/`, Codex uses `$`).
|
|
|
|
---
|
|
|
|
## 7. Full Workflow
|
|
|
|
```
|
|
Add paper to Zotero
|
|
↓ Better BibTeX auto-exports JSON to exports/
|
|
Dashboard → Sync Library
|
|
↓ Generates formal note (in Literature/, with frontmatter metadata)
|
|
Set do_ocr: true in the note's frontmatter
|
|
↓
|
|
Dashboard → Run OCR
|
|
↓ PaddleOCR extracts full text + figures → ocr/ directory
|
|
Set analyze: true in the note's frontmatter
|
|
↓
|
|
Open Agent → type /pf-deep <zotero_key>
|
|
↓ Agent performs three-pass deep reading
|
|
## 🔍 Deep Reading section appears in the note
|
|
↓ (for additional Q&A)
|
|
Open Agent → type /pf-paper <zotero_key>
|
|
↓ Interactive Q&A
|
|
Type /pf-end to save the discussion record
|
|
↓
|
|
Dashboard Per-paper view shows discussion cards
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Troubleshooting
|
|
|
|
### Plugin fails to load
|
|
|
|
- Confirm `.obsidian/plugins/paperforge/` has `main.js`, `manifest.json`, `styles.css`
|
|
- If upgrading via BRAT from an old version: delete the entire `paperforge` plugin folder and let BRAT re-download
|
|
- Open Developer Console (`Ctrl+Shift+I`) and check the red errors
|
|
|
|
### "Sync Runtime" doesn't update the version
|
|
|
|
- The plugin may be calling a different Python than your terminal. Check Settings → Python path
|
|
- Try with `--no-cache-dir` to bypass pip cache
|
|
- Confirm `https://github.com/LLLin000/PaperForge` is reachable
|
|
|
|
### OCR stays pending
|
|
|
|
- Confirm `.env` has `PADDLEOCR_API_TOKEN`
|
|
- Run `paperforge ocr --diagnose` to check API connectivity
|
|
- PDF paths may be broken: run `paperforge repair --fix-paths`
|
|
|
|
### No notes generated after sync
|
|
|
|
- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`?
|
|
- Run `paperforge doctor` to find which step failed
|
|
|
|
### /pf-deep command does nothing
|
|
|
|
- Make sure you're running it in your Agent app, not a terminal
|
|
- Confirm OCR is done (`ocr_status: done`)
|
|
- Confirm `analyze` is set to `true`
|
|
|
|
---
|
|
|
|
## 9. Updating
|
|
|
|
BRAT auto-detects plugin updates. For the Python package:
|
|
|
|
```bash
|
|
paperforge update
|
|
# or
|
|
pip install --upgrade paperforge
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Architecture
|
|
|
|
```
|
|
paperforge/
|
|
├── core/ Contract layer — PFResult/ErrorCode/state machine
|
|
├── adapters/ Adapter layer — BBT parsing, paths, frontmatter I/O
|
|
├── services/ Service layer — SyncService orchestration
|
|
├── worker/ Worker layer — OCR, status, repair
|
|
├── commands/ CLI dispatch
|
|
├── setup/ Setup wizard (directories, agent deployment, Zotero linking)
|
|
├── plugin/ Obsidian plugin (Dashboard, settings panel)
|
|
└── schema/ Field registry
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Non-commercial use only.
|
|
|
|
## Acknowledgments
|
|
|
|
Built on [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR), [Obsidian](https://obsidian.md), [Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/), and other great open-source projects.
|