mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
fix: i18n hardcoded English, use cached Python, execFile for pip/cache
This commit is contained in:
Research Assistant
parent
e37c1b74ef
commit
b695c6b4cc
2 changed files with 321 additions and 18 deletions
294
README.en.md
Normal file
294
README.en.md
Normal file
|
|
@ -0,0 +1,294 @@
|
|||
<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.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.
|
||||
|
|
@ -699,6 +699,10 @@ Object.assign(LANG.en, {
|
|||
feat_memory_rebuilding: 'Rebuilding...',
|
||||
feat_memory_rebuild_done: 'Memory DB rebuilt.',
|
||||
feat_memory_rebuild_failed: 'Rebuild failed.',
|
||||
feat_installing_pkgs: 'Installing {pkgs}...',
|
||||
feat_model_changed_warn: 'Model changed ({0} -> {1}). Existing vectors are incompatible — rebuild required.',
|
||||
feat_cache_removed: 'Model cache removed.',
|
||||
feat_cache_remove_failed: 'Failed: {0}',
|
||||
});
|
||||
|
||||
/* ── LANG.zh: v1.12 runtime health, OCR queue, pf-deep, dashboard translations ── */
|
||||
|
|
@ -806,6 +810,10 @@ Object.assign(LANG.zh, {
|
|||
feat_memory_rebuilding: '重建中…',
|
||||
feat_memory_rebuild_done: '记忆数据库重建完成。',
|
||||
feat_memory_rebuild_failed: '重建失败。',
|
||||
feat_installing_pkgs: '正在安装 {pkgs}...',
|
||||
feat_model_changed_warn: '模型已更换（{0} -> {1}）。已有向量不兼容——需要重建。',
|
||||
feat_cache_removed: '模型缓存已清除。',
|
||||
feat_cache_remove_failed: '失败：{0}',
|
||||
});
|
||||
|
||||
function langFromApp(app) {
|
||||
|
|
@ -3324,30 +3332,31 @@ class PaperForgeSettingTab extends PluginSettingTab {
|
|||
.setCta()
|
||||
.onClick(async () => {
|
||||
const vp = this.app.vault.adapter.basePath;
|
||||
const pyResult = resolvePythonExecutable(vp, this.plugin.settings);
|
||||
if (!pyResult.path) { new Notice('No Python found.'); return; }
|
||||
const pyResult = memoryState.getCachedPython(vp, this.plugin.settings);
|
||||
if (!pyResult.path) { new Notice(t('feat_no_python')); return; }
|
||||
button.setButtonText(t('feat_installing'));
|
||||
button.setDisabled(true);
|
||||
const mode = this.plugin.settings.vector_db_mode || 'api';
|
||||
const pkgs = mode === 'api' ? 'openai' : 'chromadb sentence-transformers openai';
|
||||
const notice = new Notice('Installing ' + pkgs + '...', 0);
|
||||
const notice = new Notice(t('feat_installing_pkgs').replace('{pkgs}', pkgs), 0);
|
||||
try {
|
||||
const { exec } = require('child_process');
|
||||
const env = Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1', HF_ENDPOINT: this.plugin.settings.vector_db_hf_endpoint || 'https://hf-mirror.com', HF_TOKEN: this.plugin.settings.vector_db_hf_token || '' });
|
||||
const { execFile: execFileInstall } = require('node:child_process');
|
||||
const env = Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1', HF_ENDPOINT: this.plugin.settings.vector_db_hf_endpoint || 'https://hf-mirror.com', HF_TOKEN: this.plugin.settings.vector_db_hf_token || '' });
|
||||
const pkgsArg = pkgs.split(' ');
|
||||
await new Promise((resolve, reject) => {
|
||||
exec('"' + pyResult.path + '" -m pip install ' + pkgs, {
|
||||
encoding: 'utf-8', timeout: 300000, env: env,
|
||||
}, (error) => { error ? reject(error) : resolve(); });
|
||||
execFileInstall(pyResult.path, [...pyResult.extraArgs, '-m', 'pip', 'install', ...pkgsArg], {
|
||||
cwd: vp, timeout: 300000, env: env, windowsHide: true,
|
||||
}, (error, stdout, stderr) => { error ? reject(error) : resolve(); });
|
||||
});
|
||||
notice.hide();
|
||||
new Notice('Dependencies installed. Building vectors...');
|
||||
new Notice(t('feat_install_done'));
|
||||
// Auto-build after install
|
||||
this._vectorDepsOk = true;
|
||||
this._embedStatusText = memoryState.getVectorStatusText(vp);
|
||||
this.display();
|
||||
} catch (e) {
|
||||
notice.hide();
|
||||
new Notice('Install failed: ' + (e.stderr || e.message || e));
|
||||
new Notice(t('feat_install_failed') + (e.stderr || e.message || e));
|
||||
button.setButtonText(t('feat_retry_btn'));
|
||||
button.setDisabled(false);
|
||||
}
|
||||
|
|
@ -3370,7 +3379,7 @@ class PaperForgeSettingTab extends PluginSettingTab {
|
|||
if (modelChanged) {
|
||||
const warnEl = containerEl.createEl('div');
|
||||
warnEl.style.cssText = 'padding:8px 12px; margin:8px 0; background:var(--background-modifier-warning); border-radius:4px;';
|
||||
warnEl.setText(`Model changed (${lastModel} -> ${currentModel}). Existing vectors are incompatible — rebuild required.`);
|
||||
warnEl.setText(t('feat_model_changed_warn').replace('{0}', lastModel).replace('{1}', currentModel));
|
||||
}
|
||||
|
||||
// Mode selector
|
||||
|
|
@ -3456,17 +3465,17 @@ class PaperForgeSettingTab extends PluginSettingTab {
|
|||
button.setButtonText(t('feat_removing'));
|
||||
button.setDisabled(true);
|
||||
try {
|
||||
const pyResult = resolvePythonExecutable(vp, this.plugin.settings);
|
||||
const { exec } = require('child_process');
|
||||
const pyResult = memoryState.getCachedPython(vp, this.plugin.settings);
|
||||
const { execFile: execFileRm } = require('node:child_process');
|
||||
const env = Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' });
|
||||
await new Promise((resolve, reject) => {
|
||||
exec(`"${pyResult.path}" -c "import shutil, os; p=os.path.join(os.path.expanduser('~/.cache/huggingface/hub'), '${cacheName}'); shutil.rmtree(p,ignore_errors=True); print('done')"`, {
|
||||
encoding: 'utf-8', timeout: 30000, env: env
|
||||
execFileRm(pyResult.path, [...pyResult.extraArgs, '-c', 'import shutil, os; p=os.path.join(os.path.expanduser("~/.cache/huggingface/hub"), "' + cacheName + '"); shutil.rmtree(p,ignore_errors=True); print("done")'], {
|
||||
cwd: vp, timeout: 30000, env: env, windowsHide: true,
|
||||
}, (error) => error ? reject(error) : resolve());
|
||||
});
|
||||
new Notice('Model cache removed.');
|
||||
new Notice(t('feat_cache_removed'));
|
||||
} catch (e) {
|
||||
new Notice('Failed: ' + (e.stderr || e.message || e));
|
||||
new Notice(t('feat_cache_remove_failed').replace('{0}', e.stderr || e.message || String(e)));
|
||||
}
|
||||
this.display();
|
||||
});
|
||||
|
|
@ -3598,7 +3607,7 @@ class PaperForgeSettingTab extends PluginSettingTab {
|
|||
},
|
||||
onError: (err) => {
|
||||
this.plugin._embedProcess = null;
|
||||
new Notice('Build failed: ' + (err.message || err));
|
||||
new Notice(t('feat_build_failed') + ': ' + (err.message || err));
|
||||
this.display();
|
||||
},
|
||||
onClose: (code) => {
|
||||
|
|
|
|||
Loading…
Reference in a new issue