mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
docs: update README and INSTALLATION for wizard-based setup
This commit is contained in:
Research Assistant
parent
47b5661c2d
commit
d72bf76f08
2 changed files with 160 additions and 177 deletions
109
README.md
109
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 <zotero_key> # 完整三阶段精读
|
||||
/LD-paper <zotero_key> # 快速摘要
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -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\<User>\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\<User>\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 <zotero_key>` 生成结构化阅读笔记
|
||||
|
||||
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 <zotero_key>` to generate structured reading notes
|
||||
|
||||
Read the [Workflow Guide](../README.md) for detailed usage instructions.
|
||||
详细用法参见 [AGENTS.md](../AGENTS.md)。
|
||||
|
|
|
|||
Loading…
Reference in a new issue