mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
spec: dashboard copy interaction + per-paper metadata enhancement
This commit is contained in:
Research Assistant
parent
caf7c10041
commit
eed48178fe
5 changed files with 636 additions and 460 deletions
294
README.en.md
294
README.en.md
|
|
@ -1,294 +0,0 @@
|
|||
<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.
|
||||
314
README.md
314
README.md
|
|
@ -8,98 +8,99 @@
|
|||
[](https://python.org)
|
||||
[](LICENSE)
|
||||
|
||||
**简体中文** · [English](README.en.md)
|
||||
[简体中文](README.zh.md) · **English**
|
||||
|
||||
> **铸知识为器，启洞见之明。 — Forge Knowledge, Empower Insight.**
|
||||
|
||||
PaperForge 让你在 Obsidian 里管理 Zotero 文献。同步、OCR 全文提取、图表解析、AI 精读，全在一个 Vault 里完成。
|
||||
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. 先理解它是什么
|
||||
## 0. What PaperForge Is
|
||||
|
||||
PaperForge **不是一个纯 Obsidian 插件**。它有两部分：
|
||||
PaperForge is **not just an Obsidian plugin**. It has two parts:
|
||||
|
||||
| 部分 | 是什么 | 干什么 | 装在哪 |
|
||||
|------|--------|--------|--------|
|
||||
| Obsidian 插件 | `main.js` + `manifest.json` + `styles.css` | Dashboard、按钮、设置界面 | Vault 的 `.obsidian/plugins/paperforge/` |
|
||||
| Python 包 | `paperforge` | 同步、OCR、Doctor、修复 | 系统 Python 环境 (`pip install`) |
|
||||
| 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`) |
|
||||
|
||||
插件是**壳**，Python 包是**引擎**。插件里的按钮点了之后，实际是调用 Python 命令行去干活。
|
||||
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.
|
||||
|
||||
**所以装完插件之后，必须在设置里确认 Python 包也已安装，并且版本一致。**
|
||||
**After installing the plugin, you MUST verify that the Python package is also installed and version-matched.**
|
||||
|
||||
---
|
||||
|
||||
## 1. 安装 Obsidian 插件
|
||||
## 1. Install the Obsidian Plugin
|
||||
|
||||
### 方式一：BRAT（推荐）
|
||||
### Option A: BRAT (Recommended)
|
||||
|
||||
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
|
||||
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 能自动检测 GitHub Release 更新，不需要手动下载。
|
||||
> BRAT auto-detects GitHub Release updates. No manual downloads needed.
|
||||
|
||||
### 方式二：手动下载
|
||||
### Option B: Manual Download
|
||||
|
||||
1. 打开 [Releases](https://github.com/LLLin000/PaperForge/releases) 页面
|
||||
2. 下载最新版本的三个文件：`main.js`、`manifest.json`、`styles.css`
|
||||
3. 在 Vault 里创建文件夹 `.obsidian/plugins/paperforge/`
|
||||
4. 把三个文件放进去
|
||||
5. 重启 Obsidian → 设置 → 社区插件 → 启用 PaperForge
|
||||
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. 安装 Python 包
|
||||
## 2. Install the Python Package
|
||||
|
||||
插件装好后，打开 PaperForge 设置页面。你会看到 **运行时状态** 区域：
|
||||
After enabling the plugin, open the PaperForge settings tab. You'll see a **Runtime Status** section:
|
||||
|
||||
```
|
||||
插件 v1.5.0 → Python 包 v1.5.0 ✓ 匹配
|
||||
Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched
|
||||
```
|
||||
|
||||
- 如果显示"未安装" → 在设置里确认 Python 解释器路径，然后点击 **验证** 重新检测
|
||||
- 如果显示"版本不匹配" → 插件更新时 Python 包会自动同步升级，如果没成功，点 **更新运行时** 手动触发
|
||||
- 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. Python 解释器识别逻辑
|
||||
## 3. How Python Interpreter Resolution Works
|
||||
|
||||
PaperForge 需要找到你系统里的 Python。它按以下顺序查找，找到就用：
|
||||
PaperForge needs to find a working Python on your system. It searches in this order:
|
||||
|
||||
| 优先级 | 来源 | 说明 |
|
||||
|--------|------|------|
|
||||
| 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` |
|
||||
| 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 |
|
||||
|
||||
> 如果你系统里有多个 Python（比如系统自带的 3.9 + 自己装的 3.11），**强烈建议在设置里手动指定路径**，避免跑错环境。
|
||||
> 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. 配置说明
|
||||
## 4. Setup Wizard — What Each Step Means
|
||||
|
||||
以下参数在**插件设置页面**中配置（设置 → 第三方插件 → PaperForge → 打开安装向导）。首次安装时基础配置已是正确默认值，一般不需要手动改。以下解释供你了解每个参数的作用：
|
||||
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 路径
|
||||
你当前打开的 Obsidian Vault 根目录。安装向导自动检测，一般不用改。
|
||||
### 4.1 Vault Path
|
||||
|
||||
### 4.2 AI Agent 平台
|
||||
Your Obsidian vault root. Auto-detected, usually no need to change.
|
||||
|
||||
PaperForge 的精读功能通过 AI Agent 执行。核心机制是 **触发词** 而非注册插件：你直接在 Agent 对话里输入 `/pf-deep <key>`，Agent 识别到触发词后自动加载 `literature-qa` Skill 来定位论文并执行精读。
|
||||
### 4.2 AI Agent Platform
|
||||
|
||||
安装向导会把 Skill 文件部署到对应位置：
|
||||
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.
|
||||
|
||||
| Agent | Skill 安装位置 | 触发词示例 |
|
||||
|-------|---------------|-----------|
|
||||
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>` |
|
||||
|
|
@ -108,193 +109,186 @@ PaperForge 的精读功能通过 AI Agent 执行。核心机制是 **触发词**
|
|||
| **Codex** | `.codex/skills/` | `$pf-deep <key>` |
|
||||
| **Cline** | `.clinerules/` | `/pf-deep <key>` |
|
||||
|
||||
> **关键理解**：`/pf-deep` 不是 Agent 平台的插件，而是部署在 Vault 里的 Skill 文件。安装向导把文件拷过去之后，Agent 启动时自动发现并识别这些触发词。你不需要在 Agent 平台里做任何"安装插件"的操作。
|
||||
> **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 目录命名
|
||||
### 4.3 Directory Names
|
||||
|
||||
安装向导会问你几个目录叫什么名字。这些都是给你自己看的，用来组织 Vault 里的文件结构。**大部分情况用默认值就行。**
|
||||
The wizard asks what to name several directories. These are for organizing files inside your vault. **Defaults work for most users.**
|
||||
|
||||
| 参数 | 默认值 | 作用 |
|
||||
|------|--------|------|
|
||||
| `system_dir` | `System` | PaperForge 内部数据的总目录。下面会有 `exports/`（Zotero 导出的 JSON）、`ocr/`（OCR 结果）、`config/` 等子目录。你一般不需要手动进去看。 |
|
||||
| `resources_dir` | `Resources` | 资源根目录。你的正式文献笔记就放在这里下面的 `literature_dir` 里。 |
|
||||
| `literature_dir` | `Literature` | 正式文献笔记的目录。`paperforge sync` 生成的带 frontmatter 的 `.md` 笔记在这里。你日常阅读、编辑笔记都在这个目录。 |
|
||||
| `base_dir` | `Bases` | Obsidian Base 视图文件目录。Dashboard 里的筛选视图（"待 OCR"、"待精读"等）存在这里。 |
|
||||
| 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 功能需要 PaddleOCR 的 API。在 `.env` 文件里配置：
|
||||
OCR requires a PaddleOCR API key. Configured in `.env`:
|
||||
|
||||
```
|
||||
PADDLEOCR_API_TOKEN=你的API密钥
|
||||
PADDLEOCR_API_TOKEN=your-api-key
|
||||
```
|
||||
|
||||
安装向导会引导你填写，也可以之后手动在 Vault 根目录的 `.env` 文件里加。OCR URL 一般不需要改。
|
||||
The wizard guides you through setting this. You can also edit `.env` later. The OCR URL usually stays at the default.
|
||||
|
||||
### 4.5 Zotero 数据目录
|
||||
### 4.5 Zotero Data Directory
|
||||
|
||||
PaperForge 会创建一个 junction（Windows）或 symlink（macOS/Linux），把 Zotero 的数据目录连接到 Vault 里。这样 Obsidian 的 wikilink 才能找到 PDF 文件。
|
||||
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.
|
||||
|
||||
安装向导会自动检测 Zotero 的安装位置。如果检测失败，你需要手动指定 Zotero 数据目录的路径——也就是包含 `storage` 子目录的那个文件夹（不是 Zotero 程序本身）。
|
||||
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 安装过程
|
||||
### 4.6 What Happens During Setup
|
||||
|
||||
确认配置后，安装向导会自动：
|
||||
- 创建所有需要的目录结构
|
||||
- 把 Agent 命令文件部署到对应位置
|
||||
- 把 Obsidian 插件文件安装到位
|
||||
- 创建 Zotero junction/symlink
|
||||
- 写入 `paperforge.json` 和 `.env`
|
||||
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. 首次使用
|
||||
## 5. First-Time Setup Checklist
|
||||
|
||||
1. **确认版本一致**：设置 → 运行时状态 → 确保插件和 Python 包版本一致
|
||||
2. **确认 Python 正确**：设置 → 验证按钮，确认连接的是你想要的 Python
|
||||
3. **配置 PaddleOCR**：在 Vault 根目录 `.env` 里填入 API Token
|
||||
4. **在 Zotero 里导出文献**：右键要同步的文献库 → `导出...` → 格式选 `Better BibTeX JSON` → 勾选 `Keep updated` → 保存到 `<system_dir>/PaperForge/exports/`
|
||||
5. **运行 Doctor**：Dashboard → `Run Doctor`，确认所有检查通过
|
||||
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. 日常使用
|
||||
## 6. Daily Use
|
||||
|
||||
### Dashboard（三模式视图）
|
||||
### Dashboard (Three-Mode Views)
|
||||
|
||||
`Ctrl+P` → `PaperForge: Open Dashboard` 打开控制面板，包含三种视图：
|
||||
`Ctrl+P` → `PaperForge: Open Dashboard` opens the control panel with three views:
|
||||
|
||||
| 视图 | 用途 |
|
||||
|------|------|
|
||||
| **Global** | 系统首页：运行 Sync、OCR、Doctor 等机械操作 |
|
||||
| **Collection** | 批量工作台：按领域查看文献队列、批量标记 |
|
||||
| **Per-paper** | 单篇阅读伴侣：`do_ocr` / `analyze` 切换复选框，讨论记录卡片 |
|
||||
| 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 |
|
||||
|
||||
> Dashboard 里的 PDF 文件会自动进入 Per-paper 模式，无需手动切换。
|
||||
> PDF files in the Dashboard automatically switch to Per-paper mode — no manual switching needed.
|
||||
|
||||
### AI 精读与问答（需 Agent）
|
||||
### AI Deep Reading & Q&A (Requires Agent)
|
||||
|
||||
打开 Agent 应用，直接输入触发词即可。Agent 识别到触发词后会自动加载 `literature-qa` Skill，按标准化流程定位论文并执行操作。
|
||||
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.**
|
||||
|
||||
**你对文献描述得越具体（Zotero Key、标题、DOI），Agent 定位越快。**
|
||||
| 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-deep <key>` 或 `精读 <key>` | Keshav 三阶段组会式精读，结果写入 formal note | OCR 完成、analyze 为 true |
|
||||
| 问答 | `/pf-paper <key>` 或 `文献问答 <key>` | 交互式论文 Q&A，不强制 OCR | 已有正式笔记 |
|
||||
| 存档 | `/pf-end` 或 `结束讨论` | 保存本次 `/pf-paper` 问答记录 | `/pf-paper` 会话中 |
|
||||
### `/pf-end` Details
|
||||
|
||||
> **两种触发方式等效**：你可以用 Agent 原生命令 `/pf-deep ABC12345`，也可以用自然语言 `精读 ABC12345`。Agent 识别到触发词后会自动加载 `literature-qa` Skill。
|
||||
- `/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
|
||||
|
||||
> `/pf-deep` 和 `/pf-paper` **不是终端命令**，也不是 Agent 平台的注册插件。它们是部署在 Vault 里的 Skill 文件的触发词。安装向导把 Skill 文件放到正确位置后，Agent 启动时自动发现。使用方式就是打开 Agent 对话，输入触发词 —— 和你在终端敲 `ls` 一样直接。
|
||||
|
||||
### `/pf-end` 详解
|
||||
|
||||
- `/pf-end` 仅对 `/pf-paper` 问答会话生效。精读（`/pf-deep`）的内容直接写入 formal note，不需要 `/pf-end`。
|
||||
- 执行后会在论文 workspace 下生成两个文件：
|
||||
- `discussion.md` — 人类可读的 Q&A 讨论记录
|
||||
- `discussion.json` — 结构化 Q&A 数据（含时间戳、来源标记）
|
||||
- Dashboard 的 **Per-paper** 视图会自动以讨论记录卡片形式展示这些记录
|
||||
|
||||
> 不同 Agent 的命令前缀可能不同（大部分是 `/`，Codex 是 `$`）。
|
||||
> Command prefixes vary by platform (mostly `/`, Codex uses `$`).
|
||||
|
||||
---
|
||||
|
||||
## 7. 完整工作流
|
||||
## 7. Full Workflow
|
||||
|
||||
```
|
||||
Zotero 添加论文
|
||||
↓ Better BibTeX 自动导出 JSON 到 exports/ 目录
|
||||
Add paper to Zotero
|
||||
↓ Better BibTeX auto-exports JSON to exports/
|
||||
Dashboard → Sync Library
|
||||
↓ 生成正式笔记（Literature/ 目录下，带 frontmatter 元数据）
|
||||
在笔记 frontmatter 里把 do_ocr 设为 true
|
||||
↓ Generates formal note (in Literature/, with frontmatter metadata)
|
||||
Set do_ocr: true in the note's frontmatter
|
||||
↓
|
||||
Dashboard → Run OCR
|
||||
↓ PaddleOCR 提取全文 + 图表 → ocr/ 目录
|
||||
在笔记 frontmatter 里把 analyze 设为 true
|
||||
↓ PaddleOCR extracts full text + figures → ocr/ directory
|
||||
Set analyze: true in the note's frontmatter
|
||||
↓
|
||||
打开 Agent → 输入 /pf-deep <zotero_key>
|
||||
↓ Agent 识别触发词 → 加载 literature-qa Skill → 三阶段精读
|
||||
笔记里出现 ## 🔍 精读 区域
|
||||
↓（如需额外问答）
|
||||
打开 Agent → 输入 /pf-paper <zotero_key>
|
||||
↓ 交互式 Q&A
|
||||
输入 /pf-end 保存讨论记录
|
||||
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 视图展示讨论卡片
|
||||
Dashboard Per-paper view shows discussion cards
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 常见问题
|
||||
## 8. Troubleshooting
|
||||
|
||||
### 插件加载失败（Cannot find module）
|
||||
### Plugin fails to load
|
||||
|
||||
- 确认 `.obsidian/plugins/paperforge/` 下有 `main.js`、`manifest.json`、`styles.css` 三个文件
|
||||
- 如果 BRAT 从旧版升级后出问题：删除整个 `paperforge` 插件文件夹，让 BRAT 重新下载
|
||||
- 打开 Developer Console（`Ctrl+Shift+I`）看红色报错
|
||||
- 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
|
||||
|
||||
- 插件调用的 Python 可能和你终端用的是不同环境。检查设置 → Python 解释器路径
|
||||
- pip 缓存问题，用 `--no-cache-dir` 重装
|
||||
- 确认 `https://github.com/LLLin000/PaperForge` 网络能通
|
||||
- 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 一直 pending
|
||||
### OCR stays pending
|
||||
|
||||
- 确认 `.env` 里有 `PADDLEOCR_API_TOKEN`
|
||||
- 终端运行 `paperforge ocr --diagnose` 检查 API 连通性
|
||||
- PDF 路径可能不对：运行 `paperforge repair --fix-paths`
|
||||
- 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
|
||||
|
||||
- Zotero Better BibTeX 是否配置了自动导出？JSON 是否在 `exports/` 目录？
|
||||
- 运行 `paperforge doctor` 看具体哪一步失败
|
||||
- 运行 `paperforge status` 查看系统状态总览
|
||||
- Is Better BibTeX auto-export configured in Zotero? Are JSON files in `exports/`?
|
||||
- Run `paperforge doctor` to find which step failed
|
||||
|
||||
### /pf-deep 触发词没反应
|
||||
### /pf-deep command does nothing
|
||||
|
||||
- 确认你在 **Agent 应用** 里输入，不是在终端
|
||||
- 确认安装向导已运行，Skill 文件已部署到正确的 Vault 目录
|
||||
- 确认 OCR 已完成（ocr_status: done）
|
||||
- 确认 analyze 已设为 true
|
||||
- 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. 更新
|
||||
## 9. Updating
|
||||
|
||||
BRAT 会自动检测插件更新。Python 包更新：
|
||||
BRAT auto-detects plugin updates. For the Python package:
|
||||
|
||||
```bash
|
||||
paperforge update
|
||||
# 或
|
||||
# or
|
||||
pip install --upgrade paperforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 架构
|
||||
## 10. Architecture
|
||||
|
||||
```
|
||||
paperforge/
|
||||
├── core/ 契约层 — PFResult/ErrorCode/状态机
|
||||
├── adapters/ 适配器层 — BBT 解析、路径、frontmatter
|
||||
├── services/ 服务层 — SyncService 编排
|
||||
├── worker/ 工人层 — OCR、状态、修复
|
||||
├── commands/ CLI 分发
|
||||
├── setup/ 安装向导（目录创建、Agent 部署、Zotero 链接）
|
||||
├── plugin/ Obsidian 插件（Dashboard、设置面板）
|
||||
└── schema/ 字段注册表
|
||||
├── 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/)。仅限非商业使用。
|
||||
[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Non-commercial use only.
|
||||
|
||||
## 致谢
|
||||
## Acknowledgments
|
||||
|
||||
基于 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)、[Obsidian](https://obsidian.md)、[Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) 等开源项目构建。
|
||||
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.
|
||||
|
|
|
|||
300
README.zh.md
Normal file
300
README.zh.md
Normal file
|
|
@ -0,0 +1,300 @@
|
|||
<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)
|
||||
|
||||
**简体中文** · [English](README.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.5.0 → Python 包 v1.5.0 ✓ 匹配
|
||||
```
|
||||
|
||||
- 如果显示"未安装" → 在设置里确认 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），**强烈建议在设置里手动指定路径**，避免跑错环境。
|
||||
>
|
||||
> 设置里的 **验证** 按钮会立即测试当前选中的解释器，显示它能不能用、是什么版本。
|
||||
|
||||
---
|
||||
|
||||
## 4. 配置说明
|
||||
|
||||
以下参数在**插件设置页面**中配置（设置 → 第三方插件 → PaperForge → 打开安装向导）。首次安装时基础配置已是正确默认值，一般不需要手动改。以下解释供你了解每个参数的作用：
|
||||
|
||||
### 4.1 Vault 路径
|
||||
你当前打开的 Obsidian Vault 根目录。安装向导自动检测，一般不用改。
|
||||
|
||||
### 4.2 AI Agent 平台
|
||||
|
||||
PaperForge 的精读功能通过 AI Agent 执行。核心机制是 **触发词** 而非注册插件：你直接在 Agent 对话里输入 `/pf-deep <key>`，Agent 识别到触发词后自动加载 `literature-qa` Skill 来定位论文并执行精读。
|
||||
|
||||
安装向导会把 Skill 文件部署到对应位置：
|
||||
|
||||
| Agent | Skill 安装位置 | 触发词示例 |
|
||||
|-------|---------------|-----------|
|
||||
| **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>` |
|
||||
|
||||
> **关键理解**：`/pf-deep` 不是 Agent 平台的插件，而是部署在 Vault 里的 Skill 文件。安装向导把文件拷过去之后，Agent 启动时自动发现并识别这些触发词。你不需要在 Agent 平台里做任何"安装插件"的操作。
|
||||
|
||||
### 4.3 目录命名
|
||||
|
||||
安装向导会问你几个目录叫什么名字。这些都是给你自己看的，用来组织 Vault 里的文件结构。**大部分情况用默认值就行。**
|
||||
|
||||
| 参数 | 默认值 | 作用 |
|
||||
|------|--------|------|
|
||||
| `system_dir` | `System` | PaperForge 内部数据的总目录。下面会有 `exports/`（Zotero 导出的 JSON）、`ocr/`（OCR 结果）、`config/` 等子目录。你一般不需要手动进去看。 |
|
||||
| `resources_dir` | `Resources` | 资源根目录。你的正式文献笔记就放在这里下面的 `literature_dir` 里。 |
|
||||
| `literature_dir` | `Literature` | 正式文献笔记的目录。`paperforge sync` 生成的带 frontmatter 的 `.md` 笔记在这里。你日常阅读、编辑笔记都在这个目录。 |
|
||||
| `base_dir` | `Bases` | Obsidian Base 视图文件目录。Dashboard 里的筛选视图（"待 OCR"、"待精读"等）存在这里。 |
|
||||
|
||||
### 4.4 PaddleOCR API Token
|
||||
|
||||
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. **配置 PaddleOCR**：在 Vault 根目录 `.env` 里填入 API Token
|
||||
4. **在 Zotero 里导出文献**：右键要同步的文献库 → `导出...` → 格式选 `Better BibTeX JSON` → 勾选 `Keep updated` → 保存到 `<system_dir>/PaperForge/exports/`
|
||||
5. **运行 Doctor**：Dashboard → `Run Doctor`，确认所有检查通过
|
||||
|
||||
---
|
||||
|
||||
## 6. 日常使用
|
||||
|
||||
### Dashboard（三模式视图）
|
||||
|
||||
`Ctrl+P` → `PaperForge: Open Dashboard` 打开控制面板，包含三种视图：
|
||||
|
||||
| 视图 | 用途 |
|
||||
|------|------|
|
||||
| **Global** | 系统首页：运行 Sync、OCR、Doctor 等机械操作 |
|
||||
| **Collection** | 批量工作台：按领域查看文献队列、批量标记 |
|
||||
| **Per-paper** | 单篇阅读伴侣：`do_ocr` / `analyze` 切换复选框，讨论记录卡片 |
|
||||
|
||||
> Dashboard 里的 PDF 文件会自动进入 Per-paper 模式，无需手动切换。
|
||||
|
||||
### AI 精读与问答（需 Agent）
|
||||
|
||||
打开 Agent 应用，直接输入触发词即可。Agent 识别到触发词后会自动加载 `literature-qa` Skill，按标准化流程定位论文并执行操作。
|
||||
|
||||
**你对文献描述得越具体（Zotero Key、标题、DOI），Agent 定位越快。**
|
||||
|
||||
| 路由 | 触发词 | 做什么 | 前置条件 |
|
||||
|------|--------|--------|---------|
|
||||
| 精读 | `/pf-deep <key>` 或 `精读 <key>` | Keshav 三阶段组会式精读，结果写入 formal note | OCR 完成、analyze 为 true |
|
||||
| 问答 | `/pf-paper <key>` 或 `文献问答 <key>` | 交互式论文 Q&A，不强制 OCR | 已有正式笔记 |
|
||||
| 存档 | `/pf-end` 或 `结束讨论` | 保存本次 `/pf-paper` 问答记录 | `/pf-paper` 会话中 |
|
||||
|
||||
> **两种触发方式等效**：你可以用 Agent 原生命令 `/pf-deep ABC12345`，也可以用自然语言 `精读 ABC12345`。Agent 识别到触发词后会自动加载 `literature-qa` Skill。
|
||||
|
||||
> `/pf-deep` 和 `/pf-paper` **不是终端命令**，也不是 Agent 平台的注册插件。它们是部署在 Vault 里的 Skill 文件的触发词。安装向导把 Skill 文件放到正确位置后，Agent 启动时自动发现。使用方式就是打开 Agent 对话，输入触发词 —— 和你在终端敲 `ls` 一样直接。
|
||||
|
||||
### `/pf-end` 详解
|
||||
|
||||
- `/pf-end` 仅对 `/pf-paper` 问答会话生效。精读（`/pf-deep`）的内容直接写入 formal note，不需要 `/pf-end`。
|
||||
- 执行后会在论文 workspace 下生成两个文件：
|
||||
- `discussion.md` — 人类可读的 Q&A 讨论记录
|
||||
- `discussion.json` — 结构化 Q&A 数据（含时间戳、来源标记）
|
||||
- Dashboard 的 **Per-paper** 视图会自动以讨论记录卡片形式展示这些记录
|
||||
|
||||
> 不同 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 <zotero_key>
|
||||
↓ Agent 识别触发词 → 加载 literature-qa Skill → 三阶段精读
|
||||
笔记里出现 ## 🔍 精读 区域
|
||||
↓（如需额外问答）
|
||||
打开 Agent → 输入 /pf-paper <zotero_key>
|
||||
↓ 交互式 Q&A
|
||||
输入 /pf-end 保存讨论记录
|
||||
↓
|
||||
Dashboard Per-paper 视图展示讨论卡片
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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` 看具体哪一步失败
|
||||
- 运行 `paperforge status` 查看系统状态总览
|
||||
|
||||
### /pf-deep 触发词没反应
|
||||
|
||||
- 确认你在 **Agent 应用** 里输入，不是在终端
|
||||
- 确认安装向导已运行，Skill 文件已部署到正确的 Vault 目录
|
||||
- 确认 OCR 已完成（ocr_status: done）
|
||||
- 确认 analyze 已设为 true
|
||||
|
||||
---
|
||||
|
||||
## 9. 更新
|
||||
|
||||
BRAT 会自动检测插件更新。Python 包更新：
|
||||
|
||||
```bash
|
||||
paperforge update
|
||||
# 或
|
||||
pip install --upgrade paperforge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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/)。仅限非商业使用。
|
||||
|
||||
## 致谢
|
||||
|
||||
基于 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)、[Obsidian](https://obsidian.md)、[Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/) 等开源项目构建。
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
# Dashboard Copy Interaction + Per-Paper Metadata Enhancement
|
||||
|
||||
> **Status:** Spec complete, awaiting implementation
|
||||
> **Date:** 2026-05-14
|
||||
> **Scope:** Plugin JS + CSS only (main.js + styles.css)
|
||||
|
||||
## Goal
|
||||
|
||||
Two UX improvements to the per-paper dashboard view:
|
||||
1. **Click-to-copy** for discrete metadata fields (single click → clipboard)
|
||||
2. **Text-selectable** for prose content areas (normal browser selection + copy)
|
||||
3. **Metadata enhancement** — add Journal / DOI / Zotero Key / Collection Path in a compact inline row below authors/year
|
||||
|
||||
---
|
||||
|
||||
## Design
|
||||
|
||||
### Per-Paper View Layout (after changes)
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ Efficacy of TXA in Reducing Blood Loss... [📋] │ ← Title, click-to-copy, copy icon on hover
|
||||
│ Tianli Xia, Hiroyasu Konno, Jeonghyun Ahn · 2016 │ ← Authors (click-to-copy) · Year
|
||||
│ │
|
||||
│ Cancer Research · DOI: 10.1158/... · Zotero: ABCDEFG 🔍 │ ← NEW meta-line (Zotero-style)
|
||||
│ 📂 Orthopedics / Spine │ ← NEW collection path (click-to-copy)
|
||||
│ │
|
||||
│ [PDF] [Fulltext] [OCR done] [Deep-read pending] │ ← existing status pills + file buttons
|
||||
│ │
|
||||
│ ## 🔍 精读 (article overview — text-selectable) │ ← existing, keep selectable
|
||||
│ ## 💬 Discussion (Q&A — text-selectable) │ ← existing, keep selectable
|
||||
│ ▶ Technical Details (health, paths — click-to-copy fields) │ ← existing, add copy-on-click
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Meta-Line CSS (from user-provided reference)
|
||||
|
||||
```css
|
||||
/* Metadata inline row — Zotero style */
|
||||
.paperforge-meta-line {
|
||||
margin-top: 8px;
|
||||
font-size: 13px;
|
||||
color: var(--text-muted);
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 6px 10px;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.paperforge-meta-item {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.paperforge-meta-key {
|
||||
color: var(--text-faint);
|
||||
margin-right: 4px;
|
||||
}
|
||||
|
||||
.paperforge-meta-value {
|
||||
color: var(--text-muted);
|
||||
}
|
||||
|
||||
.paperforge-meta-value.mono {
|
||||
font-family: var(--font-monospace);
|
||||
}
|
||||
|
||||
/* Clickable fields */
|
||||
.paperforge-meta-value.clickable,
|
||||
.paperforge-click-copy {
|
||||
cursor: pointer;
|
||||
border-bottom: 1px dashed var(--text-faint);
|
||||
transition: color 0.15s, border-color 0.15s;
|
||||
}
|
||||
|
||||
.paperforge-meta-value.clickable:hover,
|
||||
.paperforge-click-copy:hover {
|
||||
color: var(--text-accent);
|
||||
border-bottom-color: var(--text-accent);
|
||||
}
|
||||
|
||||
.paperforge-copy-icon {
|
||||
opacity: 0;
|
||||
margin-left: 4px;
|
||||
font-size: 11px;
|
||||
cursor: pointer;
|
||||
transition: opacity 0.15s;
|
||||
}
|
||||
.paperforge-click-copy:hover .paperforge-copy-icon {
|
||||
opacity: 0.6;
|
||||
}
|
||||
```
|
||||
|
||||
### Interaction Rules
|
||||
|
||||
| Field | Type | Click behavior |
|
||||
| ------------------ | -------- | -------------------------------------------------- |
|
||||
| Title | Copy | Click → copy full title; copy icon appears on hover |
|
||||
| Authors | Copy | Click → copy author string |
|
||||
| Journal | Display | Read-only, no copy |
|
||||
| DOI | Copy | Click → copy DOI; also link icon to doi.org |
|
||||
| Zotero Key | Copy | Click → copy key (monospace) |
|
||||
| Collection Path | Copy | Click → copy pipe-joined path |
|
||||
| PMID (if present) | Copy | Click → copy PMID |
|
||||
| Note Path | Copy | Inside Technical Details; click → copy path |
|
||||
| Fulltext Path | Copy | Inside Technical Details; click → copy path |
|
||||
| Article Overview | Select | Normal text selection, no click-to-copy |
|
||||
| Recent Discussion | Select | Normal text selection, no click-to-copy |
|
||||
| Technical Details | Mixed | Paths are click-to-copy; status text is selectable |
|
||||
|
||||
### Copy Feedback
|
||||
|
||||
On click → `navigator.clipboard.writeText(value)` then show a brief feedback:
|
||||
- Change field text to "Copied!" for 1 second, then restore
|
||||
- OR show a floating tooltip
|
||||
- Recommended: inline text change (simpler, no new element needed)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 1: Add CSS to styles.css
|
||||
- Add `.paperforge-meta-line`, `.paperforge-meta-item`, `.paperforge-meta-key`, `.paperforge-meta-value` rules
|
||||
- Add `.paperforge-click-copy` + `.paperforge-copy-icon` hover rules
|
||||
- Ensure existing content areas have no `user-select: none`
|
||||
|
||||
### Task 2: Render meta-line in _renderPaperMode
|
||||
- File: `paperforge/plugin/main.js`, in `PaperForgeStatusView._renderPaperMode()`
|
||||
- After authors/year rendering (~line 1591), insert meta-line div
|
||||
- Fields: Journal · DOI: xxx · Zotero: xxx · Collection: xxx
|
||||
- Source data: `entry.journal`, `entry.doi`, `entry.zotero_key`, `entry.collection_path`, `entry.pmid`
|
||||
- Add `paperforge-meta-value mono clickable` class to DOI, Zotero Key, PMID
|
||||
|
||||
### Task 3: Implement click-to-copy helper
|
||||
- Add `_makeClickCopy(el, value, displayText)` method to `PaperForgeStatusView`
|
||||
- Sets cursor:pointer, dashed border, onclick handler
|
||||
- On click: copy value, change text to "Copied!", setTimeout restore displayText
|
||||
- Apply to: title, authors, DOI, zotero_key, collection_path, pmid
|
||||
|
||||
### Task 4: Apply click-to-copy to Technical Details
|
||||
- File: `paperforge/plugin/main.js`, `_renderPaperTechnicalDetails()`
|
||||
- Make Note Path and Fulltext Path clickable
|
||||
- Use same `_makeClickCopy` helper
|
||||
|
||||
### Task 5: Add copy icon to title
|
||||
- Append a small 📋 span to the title element
|
||||
- Show on hover via CSS opacity transition
|
||||
|
||||
### Task 6: Verify text selection behavior
|
||||
- Confirm article overview, recent discussion, and tech details body text are NOT `user-select: none`
|
||||
- Remove any existing `user-select: none` from content areas (but keep on buttons/toggles)
|
||||
|
||||
---
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Changes |
|
||||
| ------------------------- | ---------------------------------------------------------- |
|
||||
| `paperforge/plugin/styles.css` | ~40 lines: meta-line + click-copy + copy-icon CSS |
|
||||
| `paperforge/plugin/main.js` | ~60 lines: meta-line rendering + _makeClickCopy() + wiring |
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Meta-line appears below authors/year in per-paper view: Journal · DOI · Zotero · Collection
|
||||
- [ ] DOI and Zotero Key are monospace, dashed-underline on hover, click to copy
|
||||
- [ ] Title shows copy icon on hover, click to copy full title
|
||||
- [ ] Authors click to copy
|
||||
- [ ] Collection path click to copy
|
||||
- [ ] Note Path / Fulltext Path in Technical Details click to copy
|
||||
- [ ] Article overview and Recent Discussion text remains freely selectable
|
||||
- [ ] "Copied!" feedback displays briefly on click
|
||||
- [ ] No regressions in global or collection modes
|
||||
- [ ] Works in both light and dark Obsidian themes
|
||||
|
|
@ -1584,15 +1584,15 @@
|
|||
}
|
||||
.paperforge-runtime-badge.match {
|
||||
background: var(--color-green, #4caf50);
|
||||
color: #fff;
|
||||
color: #ffffff;
|
||||
}
|
||||
.paperforge-runtime-badge.mismatch {
|
||||
background: var(--color-red, #f44336);
|
||||
color: #fff;
|
||||
color: #ffffff;
|
||||
}
|
||||
.paperforge-runtime-badge.missing {
|
||||
background: var(--color-orange, #ff9800);
|
||||
color: #fff;
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
/* ==========================================================================
|
||||
|
|
@ -1600,7 +1600,7 @@
|
|||
========================================================================== */
|
||||
.paperforge-drift-banner {
|
||||
background: var(--color-yellow, #ffc107);
|
||||
color: var(--background-primary, #000);
|
||||
color: var(--background-primary, #000000);
|
||||
padding: 8px 14px;
|
||||
border-radius: 6px;
|
||||
font-size: 0.9em;
|
||||
|
|
@ -1619,8 +1619,8 @@
|
|||
padding: 4px 12px;
|
||||
font-size: 0.85em;
|
||||
background: var(--interactive-normal, #e0e0e0);
|
||||
color: var(--text-normal, #000);
|
||||
border: 1px solid var(--background-modifier-border, #ccc);
|
||||
color: var(--text-normal, #000000);
|
||||
border: 1px solid var(--background-modifier-border, #cccccc);
|
||||
border-radius: 4px;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue