From d72bf76f08b90c32efac131453e4fabf6147f298 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Wed, 22 Apr 2026 23:36:26 +0800 Subject: [PATCH] docs: update README and INSTALLATION for wizard-based setup --- README.md | 109 +++++++++++++++------ docs/INSTALLATION.md | 228 +++++++++++++++---------------------------- 2 files changed, 160 insertions(+), 177 deletions(-) diff --git a/README.md b/README.md index 0d965eec..8295f948 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,102 @@ -# Literature Workflow for Medical Research +# PaperForge Lite 基于 Obsidian + Zotero + PaddleOCR 的医学文献精读工作流，支持自动 OCR、深度阅读笔记生成和队列管理。 -## 快速开始 - -### 方式一：让 Agent 帮你配置（推荐） - -复制以下内容，粘贴给你的 AI Agent，它会自动完成全部配置： - ``` -Install and configure the literature workflow by following the instructions here: -https://raw.githubusercontent.com/YOUR-USERNAME/YOUR-REPO/main/docs/INSTALLATION.md + ______ ___ ______ _________________ ___________ _____ _____ + | ___ \/ _ \ | ___ \ ___| ___ \ ___| _ | ___ \ __ \| ___| + | |_/ / /_\ \| |_/ / |__ | |_/ / |_ | | | | |_/ / | \/| |__ + | __/| _ || __/| __|| /| _| | | | | /| | __ | __| + | | | | | || | | |___| |\ \| | \ \_/ / |\ \| |_\ \| |___ + \_| \_| |_/\_| \____/\_| \_\_| \___/\_| \_|\____/\____/ ``` -Agent 会问你几个问题，然后自动完成安装、配置和验证。 +## 快速开始（推荐方式） -### 方式二：手动安装 - -需要： -- Python 3.10+ -- Zotero（安装 Better BibTex 插件） -- Obsidian -- PaddleOCR API Key +**PaperForge 提供交互式安装向导，引导你完成全部配置：** ```bash # 1. 克隆仓库 -git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git -cd YOUR-REPO +git clone https://github.com/LLLin000/PaperForge.git +cd PaperForge -# 2. 安装 Python 依赖 +# 2. 安装依赖 pip install -r requirements.txt -# 3. 运行安装脚本 -python setup.py +# 3. 运行向导（交互式，按步骤引导） +python setup_wizard.py --vault /path/to/your/vault ``` +向导会自动完成： +- 检测 Python 环境和依赖 +- 配置 Vault 目录结构（可自定义名称） +- 链接 Zotero 数据目录 +- 检测 Better BibTeX 插件 +- 配置 JSON 自动导出 +- 部署工作流脚本和 Agent 命令 +- 创建 .env 配置文件 + ## 功能特性 -- `/LD-deep` — 深度精读（Keshav 三阶段阅读法） -- 自动 OCR 提取（PaddleOCR-VL API） -- 图表类型智能识别（20 种图表类型自动检测） -- 图表质量审查指南（14 种图表类型的专业审查清单） -- Zotero 双向同步 -- 文献队列管理（Base 集成） +- **交互式安装向导** — 步骤引导，自动检测，安全验证 +- **`/LD-deep`** — 深度精读（Keshav 三阶段阅读法） +- **自动 OCR 提取** — PaddleOCR-VL API 提取全文和图表 +- **图表类型智能识别** — 20 种图表类型自动检测 +- **图表质量审查指南** — 14 种图表类型的专业审查清单 +- **Zotero 双向同步** — Better BibTeX 自动导出 +- **文献队列管理** — Obsidian Base 集成 +- **自动更新** — `python literature_pipeline.py --vault . update` + +## 安装要求 + +- Python 3.10+ +- Zotero + Better BibTeX 插件 +- Obsidian +- PaddleOCR API Key（安装后配置） + +## 目录结构 + +``` +your-vault/ +├── 03_Resources/ # 可自定义名称 +│ └── LiteratureControl/ +│ └── library-records/ # 文献状态跟踪 +├── 99_System/ # 可自定义名称 +│ ├── PaperForge/ +│ │ ├── exports/ # Zotero JSON 导出 +│ │ ├── ocr/ # OCR 结果 +│ │ └── worker/scripts/ +│ │ └── literature_pipeline.py +│ └── Zotero/ # Junction 到 Zotero 数据目录 +├── .opencode/skills/ # Agent Skill 目录（根据平台） +│ └── literature-qa/ +│ ├── scripts/ld_deep.py +│ ├── prompt_deep_subagent.md +│ └── chart-reading/ # 14 种图表阅读指南 +├── .env # API Key 配置 +├── paperforge.json # 版本配置 +└── AGENTS.md # 安装后指南 +``` ## 文档 -- [安装指南](docs/INSTALLATION.md) -- [使用指南](docs/USAGE.md) +- [安装指南](docs/INSTALLATION.md) — 详细安装步骤 +- [安装后指南](AGENTS.md) — 第一次使用必看 +- [设置向导](setup_wizard.py) — 交互式配置工具 + +## 核心命令 + +```bash +# Worker 命令 +python 99_System/PaperForge/worker/scripts/literature_pipeline.py --vault . selection-sync +python 99_System/PaperForge/worker/scripts/literature_pipeline.py --vault . index-refresh +python 99_System/PaperForge/worker/scripts/literature_pipeline.py --vault . ocr +python 99_System/PaperForge/worker/scripts/literature_pipeline.py --vault . status + +# Agent 命令（在 OpenCode 中使用） +/LD-deep # 完整三阶段精读 +/LD-paper # 快速摘要 +``` ## License diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 0ad607d3..31e905cd 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,200 +1,134 @@ -# Installation Guide +# PaperForge 安装指南 -## For LLM Agents +## 推荐方式：交互式安装向导 -If you're an LLM Agent helping set up this literature workflow, welcome. You'll help your user install the pipeline and configure their Zotero/Obsidian integration. - -**Tell the user**: Paste this to your agent to auto-configure: -``` -Install and configure the literature workflow by following the instructions here: -https://raw.githubusercontent.com/YOUR-USERNAME/YOUR-REPO/main/docs/INSTALLATION.md -``` - ---- - -### Step 0: Ask User About Their Setup - -Ask the user these questions to determine configuration: - -1. **Do you have Zotero installed?** - - If **yes**: Where is your Zotero data directory? (usually `C:\Users\\Zotero` on Windows or `~/Zotero` on macOS/Linux) - - If **no**: Install Zotero first from https://www.zotero.org/download/ and install the **Better BibTeX** plugin - -2. **Is your Zotero storage directory in a different location?** - - Default: same as data directory - - If **different path**: ask for the full path to the `storage` folder - -3. **Do you have Obsidian installed?** - - If **yes**: Where is your vault located? (e.g., `D:\L\Med\Research`) - - If **no**: Ask them to install Obsidian and create a vault first - -4. **Do you have a PaddleOCR API key?** - - If **yes**: ask for the API key - - If **no**: Direct them to https://paddleocr.baidu.com/ to apply for one - -5. **Do you have Python 3.10+ installed?** - - If **yes**: proceed - - If **no**: Ask them to install Python 3.10+ from https://python.org - -**Configuration summary**: -- Zotero path: `{zotero_path}` -- Zotero storage path: `{storage_path}` (may equal zotero_path) -- Obsidian vault path: `{vault_path}` -- PaddleOCR API key: `{ocr_api_key}` - ---- - -### Step 1: Install Dependencies - -Run in the terminal (spawn a subagent if needed): +PaperForge 提供图形化安装向导，引导你完成全部配置： ```bash -pip install requests pymupdf pillow pytest +# 1. 克隆仓库 +git clone https://github.com/LLLin000/PaperForge.git +cd PaperForge + +# 2. 安装依赖 +pip install -r requirements.txt + +# 3. 运行向导 +python setup_wizard.py --vault /path/to/your/vault ``` -If using Poetry: -```bash -poetry add requests pymupdf pillow pytest -``` +向导会按步骤引导你： +1. **选择 Agent 平台** — OpenCode / Cursor / Claude Code 等 +2. **检查 Python 环境** — 自动检测版本和依赖 +3. **配置 Vault 目录** — 自定义系统目录和资源目录名称 +4. **链接 Zotero 数据目录** — 自动创建 Junction +5. **检测 Better BibTeX** — 确认插件已安装 +6. **配置 JSON 导出** — 设置自动导出路径和"保持更新" +7. **一键部署** — 自动复制脚本、创建配置、验证完整性 + +### 前置条件 + +| 工具 | 用途 | 获取方式 | +|------|------|----------| +| Python 3.10+ | 运行工作流脚本 | https://python.org | +| Zotero | 文献管理 | https://zotero.org | +| Better BibTeX | Zotero 插件，生成 citation key 和 JSON 导出 | https://retorque.re/zotero-better-bibtex/ | +| Obsidian | 笔记软件 | https://obsidian.md | +| PaddleOCR API Key | OCR 服务 | https://paddleocr.baidu.com | --- -### Step 2: Create Directory Structure +## 手动安装（备用） -Create the following directories in the Obsidian vault: +如果向导无法运行，可以手动安装： + +### Step 1: 安装依赖 + +```bash +pip install requests pymupdf pillow +``` + +### Step 2: 创建目录结构 ```bash mkdir -p "{vault_path}/99_System/PaperForge/ocr" mkdir -p "{vault_path}/99_System/PaperForge/worker/scripts" mkdir -p "{vault_path}/99_System/Zotero" -mkdir -p "{vault_path}/03_Resources/Literature" -mkdir -p "{vault_path}/00_Inbox" +mkdir -p "{vault_path}/03_Resources/LiteratureControl/library-records" ``` ---- +### Step 3: 链接 Zotero 数据目录 -### Step 3: Configure Zotero Integration - -#### Option A: Junction/Symlink (Recommended) - -**Windows** (admin terminal): +**Windows** (管理员终端): ```cmd -mklink /J "{vault_path}\99_System\Zotero" "{zotero_path}" +mklink /J "{vault_path}\99_System\Zotero" "C:\Users\\Zotero" ``` **macOS/Linux**: ```bash -ln -s "{zotero_path}" "{vault_path}/99_System/Zotero" +ln -s "~/Zotero" "{vault_path}/99_System/Zotero" ``` -#### Option B: Config file (if symlink not possible) +### Step 4: 配置 .env -Create `{vault_path}/.env`: +创建 `{vault_path}/.env`: ``` -ZOTERO_DATA_DIR={zotero_path} -ZOTERO_STORAGE_DIR={storage_path} +PADDLEOCR_API_KEY=your_api_key_here +PADDLEOCR_API_URL=https://api.paddleocr.baidu.com/api/v1/ocr ``` ---- - -### Step 4: Configure OCR Pipeline - -Create `{vault_path}/.env` (or append if exists): -``` -PADDLEOCR_API_KEY={ocr_api_key} -PADDLEOCR_API_URL=https://paddleocr.baidu.com/api/v1/ocr -``` - ---- - -### Step 5: Install Workflow Scripts - -Copy the following files from the repository to your vault: +### Step 5: 部署脚本 ```bash -# Copy scripts -cp -r scripts/* "{vault_path}/99_System/PaperForge/worker/scripts/" - -# Copy AGENTS.md +cp pipeline/worker/scripts/literature_pipeline.py "{vault_path}/99_System/PaperForge/worker/scripts/" +cp -r skills/literature-qa "{vault_path}/.opencode/skills/" cp AGENTS.md "{vault_path}/AGENTS.md" ``` --- -### Step 6: Verify Setup +## 安装后验证 -Run validation: +运行向导后，验证安装： ```bash cd "{vault_path}" -python 99_System/PaperForge/worker/scripts/validate_setup.py +python 99_System/PaperForge/worker/scripts/literature_pipeline.py --vault . status ``` -This checks: -- [ ] Zotero SQLite accessible -- [ ] OCR directory writable -- [ ] Required Python packages installed -- [ ] AGENTS.md exists -- [ ] Directory structure correct +预期输出： +``` +PaperForge Lite v1.2.0 +Vault: /path/to/your/vault +Status: OK +``` --- -### Step 7: Configure AGENTS.md +## 故障排除 -Edit `{vault_path}/AGENTS.md`: +### Zotero 未找到 +- 确认 Zotero 已安装 +- 检查数据目录路径（Zotero → Edit → Preferences → Advanced → Files and Folders） +- 向导中手动输入正确的数据目录路径 -1. Update the vault path references -2. Set your preferred output language (default: Simplified Chinese) -3. Configure any custom collection paths +### 权限被拒绝（Windows） +- 以管理员身份运行终端来创建 Junction +- 或手动创建 Junction：`mklink /J "目标" "源"` + +### Better BibTeX 未安装 +- Zotero → 工具 → 插件 → 齿轮图标 → Install Plugin From File... +- 下载地址：https://retorque.re/zotero-better-bibtex/ --- -## For Humans +## 下一步 -### Quick Start +安装完成后： -1. **Prerequisites**: - - Python 3.10+ - - Zotero + Better BibTeX plugin - - Obsidian - - PaddleOCR API key +1. **同步文献**：运行 selection-sync 检测 Zotero 中的文献 +2. **生成笔记**：运行 index-refresh 创建正式文献笔记 +3. **标记精读**：在 Obsidian 中设置 `do_ocr: true` 和 `analyze: true` +4. **运行 OCR**：执行 ocr 命令处理 PDF +5. **开始精读**：使用 `/LD-deep ` 生成结构化阅读笔记 -2. **Run the installer**: - ```bash - python setup.py - ``` - This interactive script will ask you the same questions as above and configure everything automatically. - -3. **Verify**: - ```bash - python 99_System/PaperForge/worker/scripts/validate_setup.py - ``` - ---- - -## Troubleshooting - -### Zotero not found -- Ensure Zotero is installed -- Check the data directory path (Edit → Preferences → Advanced → Files and Folders) - -### Permission denied on Windows -- Run terminal as Administrator for junction creation -- Or use Option B (config file) instead - -### Better BibTeX not installed -- In Zotero: Tools → Plugins → Install plugin from file -- Download from https://github.com/retorquere/zotero-better-bibtex/releases - ---- - -## Next Steps - -After installation: - -1. **Index your library**: Run the index-refresh worker to create formal notes for existing papers -2. **Queue papers for analysis**: Use the Base system to mark papers for deep reading -3. **Run OCR**: The OCR worker processes queued papers automatically -4. **Start deep reading**: Use `/LD-deep ` to generate structured reading notes - -Read the [Workflow Guide](../README.md) for detailed usage instructions. +详细用法参见 [AGENTS.md](../AGENTS.md)。