diff --git a/README.en.md b/README.en.md index e5868a7c..f75bdbd3 100644 --- a/README.en.md +++ b/README.en.md @@ -10,142 +10,265 @@ [简体中文](README.md) · **English** -> **Forge Knowledge, Empower Insight.** +> **铸知识为器，启洞见之明。 — 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. +PaperForge brings your Zotero library into Obsidian. Sync papers, run OCR, extract figures, and do AI-assisted deep reading — all inside a single vault. -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. +--- -```text -Download plugin → Enable in Obsidian → Open wizard → Fill config → Click Install → Done +## 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.4.17 → Python Package v1.4.17 ✓ Matched ``` -## What PaperForge Does +- If it says "Not installed" → click **Sync Runtime**, or run manually: + ```bash + pip install --upgrade git+https://github.com/LLLin000/PaperForge.git@1.4.17 + ``` +- If it says "Mismatch" → the versions are out of sync. Click "Sync Runtime" to pull the matching package version. -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 | +## 3. How Python Interpreter Resolution Works -## Why It Feels Different +PaperForge needs to find a working Python on your system. It searches in this order: -- **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. +| 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 | -## Install +> 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. -See [INSTALLATION.md](INSTALLATION.md) for the complete installation guide. +--- -## Architecture +## 4. Setup Wizard — What Each Step Means + +`Ctrl+P` → `PaperForge: Run Setup 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. Choose your platform, and the wizard deploys the command files to the right location. + +| Agent | Files deployed to | Prefix | How to trigger deep reading | +|-------|------------------|--------|---------------------------| +| **OpenCode** | `.opencode/command/` + `.opencode/skills/` | `/` | Open OpenCode, type `/pf-deep ` | +| **Claude Code** | `.claude/skills/` | `/` | Open Claude Code, type `/pf-deep ` | +| **Cursor** | `.cursor/skills/` | `/` | Open Cursor AI Chat, type `/pf-deep ` | +| **GitHub Copilot** | `.github/skills/` | `/` | Open Copilot Chat, type `/pf-deep ` | +| **Windsurf** | `.windsurf/skills/` | `/` | Open Windsurf, type `/pf-deep ` | +| **Codex** | `.codex/skills/` | `$` | Open Codex, type `$pf-deep ` | +| **Cline** | `.clinerules/` | `/` | Open Cline, type `/pf-deep ` | + +> Important: `/pf-deep` and `/pf-paper` are **NOT terminal commands**. You must first launch the Agent application, then type the command into that Agent's chat input. The Agent will invoke PaperForge's deep reading scripts to analyze your paper. + +### 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` | `99_System` | Root for PaperForge internal data. Contains `exports/` (Zotero JSON exports), `ocr/` (OCR results), `config/`. You rarely need to open this manually. | +| `resources_dir` | `03_Resources` | Resources root. Your formal literature notes live under this directory, inside `literature_dir`. | +| `literature_dir` | `Literature` | Where formal literature notes (`.md` files with frontmatter) are saved by `paperforge sync`. This is where you read and edit your notes. | +| `control_dir` | `LiteratureControl` | Internal control data directory. Stores index cards and library records. No manual access needed. | +| `base_dir` | `05_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**: `Ctrl+P` → `PaperForge: Run Setup 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 + +All mechanical operations from the Dashboard: + +| What you want | How | +|---------------|-----| +| Open dashboard | `Ctrl+P` → `PaperForge: Open Dashboard` | +| Sync library | Dashboard → `Sync Library` | +| Run OCR | Dashboard → `Run OCR` | +| Check health | Dashboard → `Run Doctor` | + +### AI Deep Reading (Requires Agent) + +| Command | Does | Prerequisites | +|---------|------|--------------| +| `/pf-deep ` | Full three-pass deep reading | OCR done, analyze set to true | +| `/pf-paper ` | Quick paper summary | Formal note exists | +| `/pf-sync` | Agent syncs Zotero for you | Installed | +| `/pf-ocr` | Agent runs OCR for you | Installed | +| `/pf-status` | Agent checks system status | Installed | + +> **How to use**: Launch your chosen Agent app (OpenCode / Claude Code / Cursor / ...), then type these commands into its chat input. 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 +``` + +--- + +## 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 git+https://github.com/LLLin000/PaperForge.git +``` + +--- + +## 10. Architecture ``` paperforge/ -├── core/ Contract layer — PFResult/PFError, ErrorCode enum, state machine -│ ├── result.py PFResult/PFError serialization (JSON round-trip) -│ ├── errors.py ErrorCode enum (centralized error codes) -│ └── state.py OcrStatus/PdfStatus/Lifecycle + ALLOWED_TRANSITIONS -├── adapters/ Adapter layer — independently testable modules -│ ├── bbt.py Better BibTeX JSON parsing -│ ├── zotero_paths.py Zotero attachment path normalization -│ └── obsidian_frontmatter.py Frontmatter read/write (YAML parser) -├── services/ Service layer — orchestrates adapters -│ └── sync_service.py SyncService class -├── setup/ Setup layer — 6 focused classes -│ ├── plan.py SetupPlan (orchestration) -│ ├── checker.py SetupChecker (precondition validation) -│ ├── config_writer.py ConfigWriter (atomic write) -│ ├── vault.py VaultInitializer (directories/junction) -│ ├── runtime.py RuntimeInstaller (pip install) -│ └── agent.py AgentInstaller (skill deployment) -├── schema/ Field registry -│ └── field_registry.yaml 44 field definitions -├── doctor/ Diagnostic validation -│ └── field_validator.py Field completeness + drift detection -├── worker/ Worker layer — mechanical tasks -│ ├── sync.py Dispatch shell (thinned by 57 lines) -│ ├── status.py Status + doctor checks -│ ├── ocr.py OCR pipeline -│ └── ... -├── commands/ CLI dispatch layer -└── plugin/ Obsidian plugin +├── 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 ``` -All CLI commands output unified PFResult JSON: `{ok, command, version, data, error}` via `--json` flag. `paperforge doctor` validates field schema consistency and detects data drift. - -## 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 ` | -| **Quick Query** | `/pf-paper ` | - -### 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 ` | Full 3-pass deep reading | OCR complete | -| `/pf-paper ` | 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](docs/setup-guide.md) | Full setup walkthrough | -| [Installation Guide](INSTALLATION.md) | Full install reference | -| [Post-Install Guide](AGENTS.md) | First-use workflow guide | -| [Changelog](CHANGELOG.md) | Version history | -| [Contributing](CONTRIBUTING.md) | Dev setup and conventions | +--- ## License @@ -153,18 +276,4 @@ All CLI commands output unified PFResult JSON: `{ok, command, version, data, err ## Acknowledgments -PaperForge builds on excellent open-source foundations: - -| Project | Role | -|---------|------| -| [PaddleOCR / PaddleOCR-VL](https://github.com/PaddlePaddle/PaddleOCR) | PDF OCR, layout detection, and figure extraction | -| [Obsidian](https://obsidian.md) | Knowledge workspace and plugin host | -| [Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) | Metadata auto-export | -| [PyMuPDF (fitz)](https://github.com/pymupdf/PyMuPDF) | Local PDF validation and sanitization | -| [requests](https://github.com/psf/requests) | OCR API client | -| [tenacity](https://github.com/jd/tenacity) | Retry logic | -| [Pillow](https://python-pillow.org) | Figure image processing | -| [tqdm](https://github.com/tqdm/tqdm) | Progress bars | -| [textual](https://github.com/Textualize/textual) | TUI components | - -> PaperForge aims to turn scattered papers, figures, and notes into research assets you can actually work with. +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/README.md b/README.md index dccc9953..dc8c9f8f 100644 --- a/README.md +++ b/README.md @@ -10,168 +10,240 @@ **简体中文** · [English](README.en.md) -> **铸知识为器，启洞见之明。** +> **铸知识为器，启洞见之明。 — Forge Knowledge, Empower Insight.** + +PaperForge 让你在 Obsidian 里管理 Zotero 文献。同步、OCR 全文提取、图表解析、AI 精读，全在一个 Vault 里完成。 + +--- + +## 0. 先理解它是什么 + +PaperForge **不是一个纯 Obsidian 插件**。它有两部分： + +| 部分 | 是什么 | 干什么 | 装在哪 | +|------|--------|--------|--------| +| Obsidian 插件 | `main.js` + `manifest.json` + `styles.css` | Dashboard、按钮、设置界面 | Vault 的 `.obsidian/plugins/paperforge/` | +| Python 包 | `paperforge` | 同步、OCR、Doctor、修复 | 系统 Python 环境 (`pip install`) | + +插件是**壳**，Python 包是**引擎**。插件里的按钮点了之后，实际是调用 Python 命令行去干活。 + +**所以装完插件之后，必须在设置里确认 Python 包也已安装，并且版本一致。** + +--- + +## 1. 安装 Obsidian 插件 + +### 方式一：BRAT（推荐） + +1. 在 Obsidian 社区插件市场搜索安装 **BRAT**（Beta Reviewer's Auto-update Tester） +2. 打开 BRAT 设置 → `Add Beta Plugin` +3. 填入仓库地址：`https://github.com/LLLin000/PaperForge` +4. BRAT 会自动下载最新 Release 的 `main.js`、`manifest.json`、`styles.css` 并安装 +5. 在 Obsidian 设置 → 社区插件 → 启用 PaperForge + +> BRAT 能自动检测 GitHub Release 更新，不需要手动下载。 + +### 方式二：手动下载 + +1. 打开 [Releases](https://github.com/LLLin000/PaperForge/releases) 页面 +2. 下载最新版本的三个文件：`main.js`、`manifest.json`、`styles.css` +3. 在 Vault 里创建文件夹 `.obsidian/plugins/paperforge/` +4. 把三个文件放进去 +5. 重启 Obsidian → 设置 → 社区插件 → 启用 PaperForge + +> 手动安装不会自动更新，每次新版本需要重新下载替换。 + +--- + +## 2. 安装 Python 包 + +插件装好后，打开 PaperForge 设置页面。你会看到 **运行时状态** 区域： + +``` +插件 v1.4.17 → Python 包 v1.4.17 ✓ 匹配 +``` + +- 如果显示"未安装" → 点击 **同步运行时** 按钮，或者自己在终端执行： + ```bash + pip install --upgrade git+https://github.com/LLLin000/PaperForge.git@1.4.17 + ``` +- 如果显示"版本不匹配" → 说明插件版本和 Python 包版本不一致。点"同步运行时"会自动拉取与插件版本匹配的 Python 包。 + +--- + +## 3. Python 解释器识别逻辑 + +PaperForge 需要找到你系统里的 Python。它按以下顺序查找，找到就用： + +| 优先级 | 来源 | 说明 | +|--------|------|------| +| 1 | **你手动指定** | 设置 → `自定义 Python 路径`，填入完整路径（如 `C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\python.exe`）。**这是最可靠的方式。** | +| 2 | **venv 自动检测** | 自动扫描 Vault 根目录下的 `.paperforge-test-venv`、`.venv`、`venv` 里的 Python | +| 3 | **系统自动检测** | 依次尝试 `py -3`、`python`、`python3`，用 `--version` 验证，挑第一个能用的 | +| 4 | **兜底** | 以上都找不到，回退到 `python` | + +> 如果你系统里有多个 Python（比如系统自带的 3.9 + 自己装的 3.11），**强烈建议在设置里手动指定路径**，避免跑错环境。 > -> **Forge Knowledge, Empower Insight.** +> 设置里的 **验证** 按钮会立即测试当前选中的解释器，显示它能不能用、是什么版本。 -PaperForge 是一个面向研究者的 Obsidian 文献工作台。 -它针对 Zotero，把零散材料整理为可检索、可追问、可精读的结构化知识资产。 +--- -从同步文献，到抽取全文与图表，再到 AI 深读与批判性梳理，整条链路尽量留在同一个知识环境里完成。 +## 4. 安装向导参数说明 -```text -下载插件 → 在 Obsidian 启用 → 打开安装向导 → 填写配置 → 点击安装 → 开始使用 -``` +`Ctrl+P` → `PaperForge: Run Setup Wizard` 会引导你配置以下内容。每一步都解释在这里，免得你填的时候不知道是什么意思。 -## 从文献到洞见 +### 4.1 Vault 路径 +你当前打开的 Obsidian Vault 根目录。安装向导自动检测，一般不用改。 -PaperForge 不是单纯的 OCR 工具，也不只是 Zotero 到 Obsidian 的搬运脚本。 -它更像一座知识炉：把原始论文、附件和图表炼成真正能被研究流程使用的材料。 +### 4.2 AI Agent 平台 -| 层级 | 产出 | 用途 | -|------|------|------| -| **索引卡片** | 带结构化 frontmatter 的记录（标题、作者、期刊、DOI、标签、摘要） | 搜索、浏览、Base 视图筛选 | -| **全文语料** | OCR 提取的 `fulltext.md` | 提供给 LLM、RAG、检索问答 | -| **图表数据库** | 图表图片、caption 与 figure-map | 多模态分析、图表定位、证据追踪 | -| **精读笔记** | AI 三阶段分析、图表解读、批判评估 | 文献综述、研究设计、写作准备 | +PaperForge 的精读功能通过 AI Agent 执行（如 `/pf-deep` 命令）。你需要选择你使用的 Agent 平台，安装向导会把对应的命令文件部署到正确位置。 -## 为什么值得试试 +| Agent | 命令文件放在 | 前缀 | 如何触发精读 | +|-------|-------------|------|------------| +| **OpenCode** | `.opencode/command/` + `.opencode/skills/` | `/` | 打开 OpenCode，输入 `/pf-deep ` | +| **Claude Code** | `.claude/skills/` | `/` | 打开 Claude Code，输入 `/pf-deep ` | +| **Cursor** | `.cursor/skills/` | `/` | 打开 Cursor 的 AI Chat，输入 `/pf-deep ` | +| **GitHub Copilot** | `.github/skills/` | `/` | 打开 Copilot Chat，输入 `/pf-deep ` | +| **Windsurf** | `.windsurf/skills/` | `/` | 打开 Windsurf，输入 `/pf-deep ` | +| **Codex** | `.codex/skills/` | `$` | 打开 Codex，输入 `$pf-deep ` | +| **Cline** | `.clinerules/` | `/` | 打开 Cline，输入 `/pf-deep ` | -- **安装路径短**：插件安装 + 向导配置，不要求用户长期在终端里维护流水线。 -- **工作流完整**：同步、OCR、图表、精读、Agent 命令都围绕同一个 Vault 组织。 -- **对 AI 友好**：输出不是一堆散文件，而是适合检索、提问、精读和后续写作的结构化资产。 -- **保留研究现场**：PaperForge 不取代 Zotero 与 Obsidian，而是把它们接成一条可持续使用的研究链。 +> 注意：`/pf-deep` 和 `/pf-paper` **不是在终端里执行的命令**。你需要先启动对应的 Agent 应用（比如打开 OpenCode），然后在这个 Agent 的对话输入框里输入命令，Agent 才会调用 PaperForge 的精读脚本去分析你的论文。 -## 安装 +### 4.3 目录命名 -完整安装指南请参见 [INSTALLATION.md](INSTALLATION.md)。 +安装向导会问你几个目录叫什么名字。这些都是给你自己看的，用来组织 Vault 里的文件结构。**大部分情况用默认值就行。** -## 架构 - -``` -paperforge/ -├── core/ 契约层 —— PFResult/PFError 数据契约、ErrorCode 枚举、状态机 -│ ├── result.py PFResult/PFError 序列化 -│ ├── errors.py ErrorCode 枚举（集中错误码） -│ └── state.py OcrStatus/PdfStatus/Lifecycle 状态机 + 合法迁移规则 -├── adapters/ 适配器层 —— 独立可测的模块化组件 -│ ├── bbt.py Better BibTeX JSON 解析 -│ ├── zotero_paths.py Zotero 附件路径规范化 -│ └── obsidian_frontmatter.py Frontmatter 读写（YAML 解析器） -├── services/ 服务层 —— 编排适配器 -│ └── sync_service.py SyncService 类 -├── setup/ 安装层 —— 6 个独立类 -│ ├── plan.py SetupPlan（编排） -│ ├── checker.py SetupChecker（前置检查） -│ ├── config_writer.py ConfigWriter（原子写入） -│ ├── vault.py VaultInitializer（目录/链接） -│ ├── runtime.py RuntimeInstaller（pip 安装） -│ └── agent.py AgentInstaller（技能部署） -├── schema/ 字段注册表 -│ └── field_registry.yaml 44 字段定义 -├── doctor/ 诊断校验 -│ └── field_validator.py 字段完整性 + 漂移检测 -├── worker/ 工人层 —— 机械劳动 -│ ├── sync.py 调度壳（-57 行） -│ ├── status.py 状态 + doctor 检查 -│ ├── ocr.py OCR 流水线 -│ └── ... -├── commands/ CLI 分发层 -└── plugin/ Obsidian 插件 -``` - -所有 CLI 命令通过 PFResult 契约输出统一 JSON 格式：`{ok, command, version, data, error}`。`doctor` 可以校验字段注册表一致性，检测数据漂移。 - -## 使用方式 - -全部核心流程都可以从 Obsidian 内启动。 - -| 操作 | 方式 | -|------|------| -| **打开 Dashboard** | `Ctrl+P` → `PaperForge: Open Dashboard`，或点击左侧图标 | -| **同步文献** | Dashboard → `Sync Library`，从 Zotero 拉取数据并生成笔记 | -| **运行 OCR** | Dashboard → `Run OCR`，提取 PDF 全文与图表 | -| **AI 精读** | `/pf-deep `，执行三阶段深度分析 | -| **快速问答** | `/pf-paper `，对单篇论文快速提问 | - -### Dashboard - -

- PaperForge dashboard -

- -## 命令参考 - -### Obsidian 命令面板 - -| 命令 | 说明 | -|------|------| -| `PaperForge: Open Dashboard` | 打开状态面板与快捷操作 | -| `PaperForge: Sync Library` | 同步 Zotero 并生成笔记 | -| `PaperForge: Run OCR` | 提取全文和图表 | - -### Agent 命令 - -| 命令 | 说明 | 前置条件 | -|------|------|---------| -| `/pf-deep ` | 完整三阶段精读 | OCR 完成 | -| `/pf-paper ` | 快速文献问答 | 已有正式笔记 | -| `/pf-sync` | 同步 Zotero | 已安装 | -| `/pf-ocr` | 运行 OCR | 已安装 | -| `/pf-status` | 查看系统状态 | 已安装 | - -### CLI 命令 - -| 命令 | 说明 | -|------|------| -| `paperforge sync` | 同步 Zotero 并生成笔记 | -| `paperforge ocr` | 运行 OCR | -| `paperforge status` | 查看系统概览 | -| `paperforge doctor` | 诊断配置问题 | -| `paperforge update` | 更新 PaperForge | - -## 支持的 Agent 平台 - -| 平台 | Agent 命令 | 部署位置 | -|------|-----------|---------| -| **OpenCode** | 完整支持全部 `/pf-*` 命令 | `.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/` | - -在安装向导中选择你的平台，相关文件会自动部署。 - -## 配置 - -安装向导会处理绝大多数配置。默认生成的结构如下： - -```text -vault/ -├── paperforge.json ← 目录配置 + Agent 平台 -├── System/ -│ └── PaperForge/ -│ ├── .env ← PaddleOCR API Key -│ ├── exports/ ← Better BibTeX JSON 导出目录 -│ └── config/ ← domain-collections.json -├── Resources/ -│ ├── Notes/ ← 正文笔记（元数据 + 精读笔记） -│ └── Index_Cards/ ← 索引卡片（按领域组织） -└── Base/ ← Obsidian Base 视图 -``` - -可选环境变量： - -| 变量 | 默认值 | 说明 | +| 参数 | 默认值 | 作用 | |------|--------|------| -| `PADDLEOCR_API_TOKEN` | — | PaddleOCR API Key | -| `PAPERFORGE_LOG_LEVEL` | `INFO` | 日志级别 | +| `system_dir` | `99_System` | PaperForge 内部数据的总目录。下面会有 `exports/`（Zotero 导出的 JSON）、`ocr/`（OCR 结果）、`config/` 等子目录。你一般不需要手动进去看。 | +| `resources_dir` | `03_Resources` | 资源根目录。你的正式文献笔记就放在这里下面的 `literature_dir` 里。 | +| `literature_dir` | `Literature` | 正式文献笔记的目录。`paperforge sync` 生成的带 frontmatter 的 `.md` 笔记在这里。你日常阅读、编辑笔记都在这个目录。 | +| `control_dir` | `LiteratureControl` | 内部管理数据目录。存索引卡片、library records 等。普通用户不需要手动操作。 | +| `base_dir` | `05_Bases` | Obsidian Base 视图文件目录。Dashboard 里的筛选视图（"待 OCR"、"待精读"等）存在这里。 | -## 更新 +### 4.4 PaddleOCR API Token -默认可在 Obsidian 重启时自动更新，也可以手动执行： +OCR 功能需要 PaddleOCR 的 API。在 `.env` 文件里配置： + +``` +PADDLEOCR_API_TOKEN=你的API密钥 +``` + +安装向导会引导你填写，也可以之后手动在 Vault 根目录的 `.env` 文件里加。OCR URL 一般不需要改。 + +### 4.5 Zotero 数据目录 + +PaperForge 会创建一个 junction（Windows）或 symlink（macOS/Linux），把 Zotero 的数据目录连接到 Vault 里。这样 Obsidian 的 wikilink 才能找到 PDF 文件。 + +安装向导会自动检测 Zotero 的安装位置。如果检测失败，你需要手动指定 Zotero 数据目录的路径——也就是包含 `storage` 子目录的那个文件夹（不是 Zotero 程序本身）。 + +### 4.6 安装过程 + +确认配置后，安装向导会自动： +- 创建所有需要的目录结构 +- 把 Agent 命令文件部署到对应位置 +- 把 Obsidian 插件文件安装到位 +- 创建 Zotero junction/symlink +- 写入 `paperforge.json` 和 `.env` + +整个过程是**增量的** — 如果你选的目录里已经有文件，安装向导只会补充缺失的，不会删除已有内容。 + +--- + +## 5. 首次使用 + +1. **确认版本一致**：设置 → 运行时状态 → 确保插件和 Python 包版本一致 +2. **确认 Python 正确**：设置 → 验证按钮，确认连接的是你想要的 Python +3. **运行安装向导**：`Ctrl+P` → `PaperForge: Run Setup Wizard` +4. **配置 PaddleOCR**：在 `.env` 里填入 API Token（安装向导会引导你做这一步） +5. **在 Zotero 里导出文献**：右键要同步的文献库 → `导出...` → 格式选 `Better BibTeX JSON` → 勾选 `Keep updated` → 保存到 `/PaperForge/exports/` +6. **运行 Doctor**：Dashboard → `Run Doctor`，确认所有检查通过 + +--- + +## 6. 日常使用 + +所有机械操作都可以从 Obsidian Dashboard 完成： + +| 你要做什么 | 操作 | +|-----------|------| +| 打开控制面板 | `Ctrl+P` → `PaperForge: Open Dashboard` | +| 同步 Zotero 文献 | Dashboard → `Sync Library` | +| 运行 OCR | Dashboard → `Run OCR` | +| 检查系统状态 | Dashboard → `Run Doctor` | + +### AI 精读（需 Agent） + +| 命令 | 作用 | 前置条件 | +|------|------|---------| +| `/pf-deep ` | 完整三阶段精读 | OCR 完成、analyze 设为 true | +| `/pf-paper ` | 快速文献摘要 | 已有正式笔记 | +| `/pf-sync` | Agent 帮你同步 Zotero | 已安装 | +| `/pf-ocr` | Agent 帮你运行 OCR | 已安装 | +| `/pf-status` | Agent 帮你查看状态 | 已安装 | + +> **使用方式**：打开你选择的 Agent 应用（OpenCode / Claude Code / Cursor / …），在对话输入框里输入这些命令。不同的 Agent 前缀可能不同（大部分是 `/`，Codex 是 `$`）。 + +--- + +## 7. 完整工作流 + +``` +Zotero 添加论文 + ↓ Better BibTeX 自动导出 JSON 到 exports/ 目录 +Dashboard → Sync Library + ↓ 生成正式笔记（Literature/ 目录下，带 frontmatter 元数据） +在笔记 frontmatter 里把 do_ocr 设为 true + ↓ +Dashboard → Run OCR + ↓ PaddleOCR 提取全文 + 图表 → ocr/ 目录 +在笔记 frontmatter 里把 analyze 设为 true + ↓ +打开 Agent → 输入 /pf-deep + ↓ Agent 执行三阶段精读 +笔记里出现 ## 🔍 精读 区域 +``` + +--- + +## 8. 常见问题 + +### 插件加载失败（Cannot find module） + +- 确认 `.obsidian/plugins/paperforge/` 下有 `main.js`、`manifest.json`、`styles.css` 三个文件 +- 如果 BRAT 从旧版升级后出问题：删除整个 `paperforge` 插件文件夹，让 BRAT 重新下载 +- 打开 Developer Console（`Ctrl+Shift+I`）看红色报错 + +### "同步运行时" 点了还是旧版本 + +- 插件调用的 Python 可能和你终端用的是不同环境。检查设置 → Python 解释器路径 +- pip 缓存问题，用 `--no-cache-dir` 重装 +- 确认 `https://github.com/LLLin000/PaperForge` 网络能通 + +### OCR 一直 pending + +- 确认 `.env` 里有 `PADDLEOCR_API_TOKEN` +- 终端运行 `paperforge ocr --diagnose` 检查 API 连通性 +- PDF 路径可能不对：运行 `paperforge repair --fix-paths` + +### 同步后没有生成笔记 + +- Zotero Better BibTeX 是否配置了自动导出？JSON 是否在 `exports/` 目录？ +- 运行 `paperforge doctor` 看具体哪一步失败 + +### /pf-deep 命令没反应 + +- 确认你在 Agent 软件里执行，不是在终端 +- 确认 OCR 已完成（ocr_status: done） +- 确认 analyze 已设为 true + +--- + +## 9. 更新 + +BRAT 会自动检测插件更新。Python 包更新： ```bash paperforge update @@ -179,32 +251,28 @@ paperforge update pip install --upgrade git+https://github.com/LLLin000/PaperForge.git ``` -## 文档 +--- -| 文档 | 内容 | -|------|------| -| [安装后指南](AGENTS.md) | 首次使用与工作流说明 | -| [变更日志](CHANGELOG.md) | 版本历史 | -| [贡献指南](CONTRIBUTING.md) | 开发环境与协作约定 | +## 10. 架构 + +``` +paperforge/ +├── core/ 契约层 — PFResult/ErrorCode/状态机 +├── adapters/ 适配器层 — BBT 解析、路径、frontmatter +├── services/ 服务层 — SyncService 编排 +├── worker/ 工人层 — OCR、状态、修复 +├── commands/ CLI 分发 +├── setup/ 安装向导（目录创建、Agent 部署、Zotero 链接） +├── plugin/ Obsidian 插件（Dashboard、设置面板） +└── schema/ 字段注册表 +``` + +--- ## 协议 -[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)。 -仅限非商业使用，详见 [LICENSE](LICENSE)。 +[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)。仅限非商业使用。 ## 致谢 -PaperForge 站在这些优秀项目的肩膀上： - -| 项目 | 作用 | -|------|------| -| [PaddleOCR / PaddleOCR-VL](https://github.com/PaddlePaddle/PaddleOCR) | PDF OCR 引擎，负责文字提取、版面检测与图表分割 | -| [Obsidian](https://obsidian.md) | 知识工作台与插件宿主 | -| [Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) | 文献元数据自动导出 | -| [PyMuPDF (fitz)](https://github.com/pymupdf/PyMuPDF) | 本地 PDF 验证与净化 | -| [requests](https://github.com/psf/requests) | OCR API HTTP 客户端 | -| [tenacity](https://github.com/jd/tenacity) | 指数退避重试机制 | -| [Pillow](https://python-pillow.org) | 图表图片处理 | -| [tqdm](https://github.com/tqdm/tqdm) | 进度条 | - -> 把论文、PDF、图表与注释从零散材料炼成真正可用的知识器物，这就是 PaperForge 想做的事。 +基于 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)、[Obsidian](https://obsidian.md)、[Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) 等开源项目构建。