From 53736ab841cc716acd468d3f0eaedbd60bbd8ce7 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Sat, 16 May 2026 00:57:34 +0800 Subject: [PATCH] fix: i18n hardcoded English, use cached Python, execFile for pip/cache --- README.en.md | 294 ++++++++++++++++++++++++++++++++++++++ paperforge/plugin/main.js | 45 +++--- 2 files changed, 321 insertions(+), 18 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 00000000..5c7e1ce7 --- /dev/null +++ b/README.en.md @@ -0,0 +1,294 @@ +

+ PaperForge banner +

+ +# PaperForge + +[![Version](https://img.shields.io/github/v/release/LLLin000/PaperForge?style=for-the-badge&label=version)](https://github.com/LLLin000/PaperForge/releases) +[![Python](https://img.shields.io/pypi/pyversions/paperforge?style=for-the-badge&logo=python&logoColor=white&color=3775A9)](https://python.org) +[![License](https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgreen?style=for-the-badge)](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 ` 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 ` | +| **Claude Code** | `.claude/skills/` | `/pf-deep ` | +| **Cursor** | `.cursor/skills/` | `/pf-deep ` | +| **GitHub Copilot** | `.github/skills/` | `/pf-deep ` | +| **Windsurf** | `.windsurf/skills/` | `/pf-deep ` | +| **Codex** | `.codex/skills/` | `$pf-deep ` | +| **Cline** | `.clinerules/` | `/pf-deep ` | + +> **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 `/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 ` | 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 ` | 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 + ↓ Agent performs three-pass deep reading +## 🔍 Deep Reading section appears in the note + ↓ (for additional Q&A) +Open Agent → type /pf-paper + ↓ 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. diff --git a/paperforge/plugin/main.js b/paperforge/plugin/main.js index 0ec93ac7..4a99c23d 100644 --- a/paperforge/plugin/main.js +++ b/paperforge/plugin/main.js @@ -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) => {