mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
97a2875d48
Separate audiences: README as navigation entry, getting-started as canonical tutorial, troubleshooting as failure recovery, AGENTS as agent-only operating contract, COMMANDS as pure reference, maintainer-guide for release/versioning/architecture.
115 lines
4.3 KiB
Markdown
115 lines
4.3 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: Community Plugin Browser (Recommended)
|
|
|
|
1. Open Obsidian → `Settings` → `Community plugins` → `Browse`
|
|
2. Search for **PaperForge**
|
|
3. Click `Install`, then `Enable`
|
|
|
|
> Community plugins auto-update through Obsidian. No extra steps needed.
|
|
|
|
### Option B: BRAT
|
|
|
|
If you need beta versions or the plugin hasn't appeared in search yet:
|
|
|
|
1. Install **BRAT** from the Obsidian community plugin browser
|
|
2. Open BRAT settings → `Add Beta Plugin`
|
|
3. Enter: `https://github.com/LLLin000/PaperForge`
|
|
4. Enable PaperForge in Settings → Community Plugins
|
|
|
|
### Option C: 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. Quickstart
|
|
|
|
```bash
|
|
# 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/
|
|
# 2. Sync
|
|
paperforge sync
|
|
|
|
# 3. Mark a paper for OCR in its frontmatter: do_ocr: true
|
|
# 4. Run OCR
|
|
paperforge ocr
|
|
|
|
# 5. Mark for deep reading: analyze: true
|
|
# 6. In your Agent chat:
|
|
/pf-deep <zotero_key>
|
|
```
|
|
|
|
---
|
|
|
|
## 文档导航
|
|
|
|
| 你想做什么 | 去看 |
|
|
| ------------------------------------------ | ------------------------------ |
|
|
| 完整教程，从安装到精读 | [使用教程](docs/getting-started.md) |
|
|
| 遇到问题了 | [故障排除](docs/troubleshooting.md) |
|
|
| 查某个命令 | [命令参考](docs/COMMANDS.md) |
|
|
| 如何升级 | [更新指南](docs/update-upgrade.md) |
|
|
| 架构 / 维护 / 发布 | [架构文档](docs/ARCHITECTURE.md) |
|
|
| AI Agent 协作 | [AGENTS.md](AGENTS.md) |
|
|
|
|
---
|
|
|
|
## 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.
|