diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 5c7e1ce7..00000000 --- a/README.en.md +++ /dev/null @@ -1,294 +0,0 @@ -

- 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/README.md b/README.md index 493b86b5..92709419 100644 --- a/README.md +++ b/README.md @@ -8,98 +8,99 @@ [![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) -**简体中文** · [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 `，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 ` 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 ` | | **Claude Code** | `.claude/skills/` | `/pf-deep ` | | **Cursor** | `.cursor/skills/` | `/pf-deep ` | @@ -108,193 +109,186 @@ PaperForge 的精读功能通过 AI Agent 执行。核心机制是 **触发词** | **Codex** | `.codex/skills/` | `$pf-deep ` | | **Cline** | `.clinerules/` | `/pf-deep ` | -> **关键理解**：`/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` → 保存到 `/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 `/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 ` | 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-deep ` 或 `精读 ` | Keshav 三阶段组会式精读，结果写入 formal note | OCR 完成、analyze 为 true | -| 问答 | `/pf-paper ` 或 `文献问答 ` | 交互式论文 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 - ↓ Agent 识别触发词 → 加载 literature-qa Skill → 三阶段精读 -笔记里出现 ## 🔍 精读 区域 - ↓（如需额外问答） -打开 Agent → 输入 /pf-paper - ↓ 交互式 Q&A -输入 /pf-end 保存讨论记录 +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 视图展示讨论卡片 +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. diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 00000000..75f9ff3c --- /dev/null +++ b/README.zh.md @@ -0,0 +1,300 @@ +

+ 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) + +**简体中文** · [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 `，Agent 识别到触发词后自动加载 `literature-qa` Skill 来定位论文并执行精读。 + +安装向导会把 Skill 文件部署到对应位置： + +| Agent | Skill 安装位置 | 触发词示例 | +|-------|---------------|-----------| +| **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 ` | + +> **关键理解**：`/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` → 保存到 `/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 ` 或 `精读 ` | Keshav 三阶段组会式精读，结果写入 formal note | OCR 完成、analyze 为 true | +| 问答 | `/pf-paper ` 或 `文献问答 ` | 交互式论文 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 + ↓ Agent 识别触发词 → 加载 literature-qa Skill → 三阶段精读 +笔记里出现 ## 🔍 精读 区域 + ↓（如需额外问答） +打开 Agent → 输入 /pf-paper + ↓ 交互式 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/) 等开源项目构建。 diff --git a/docs/superpowers/specs/2026-05-14-dashboard-copy-metadata-design.md b/docs/superpowers/specs/2026-05-14-dashboard-copy-metadata-design.md new file mode 100644 index 00000000..aee4eeac --- /dev/null +++ b/docs/superpowers/specs/2026-05-14-dashboard-copy-metadata-design.md @@ -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 diff --git a/paperforge/plugin/styles.css b/paperforge/plugin/styles.css index 31f0725b..8c0682ea 100644 --- a/paperforge/plugin/styles.css +++ b/paperforge/plugin/styles.css @@ -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; }