From bcd0934117cdb46df52938f0f11ff8cc58c204f7 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Tue, 28 Apr 2026 01:06:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20all=20doc=20references=20?= =?UTF-8?q?=E2=80=94=20README,=20INSTALLATION.md,=20AGENTS.md=20for=20v1.4?= =?UTF-8?q?.1=20pip-first=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 22 +++---- README.md | 11 ++-- docs/INSTALLATION.md | 153 ++++++++----------------------------------- 3 files changed, 45 insertions(+), 141 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5c18b874..d487c9fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # PaperForge Lite - Agent Guide -> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [INSTALLATION.md](docs/INSTALLATION.md)。 +> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [setup-guide.md](docs/setup-guide.md) 或快速版 [INSTALLATION.md](docs/INSTALLATION.md)。 --- @@ -10,7 +10,7 @@ [ ] Zotero 已安装 + Better BibTeX 插件已启用 [ ] Better BibTeX 已配置自动导出 JSON（见下方配置） [ ] Obsidian 已打开当前 Vault -[ ] Python 依赖已安装 (pip install requests pymupdf pillow) +[ ] PaperForge 已安装 (pip install git+https://github.com/LLLin000/PaperForge.git) [ ] PaddleOCR API Key 已配置（在 .env 中） [ ] 目录结构已创建（setup.py 会自动完成） [ ] Zotero 数据目录已链接到 /Zotero @@ -518,24 +518,24 @@ paperforge update #### 方式 3：手动更新 +**推荐：自动更新** +```bash +paperforge update +``` +系统会自动检测安装方式并执行对应的更新命令。 + **pip 安装用户：** ```bash -pip install --upgrade paperforge +pip install --upgrade git+https://github.com/LLLin000/PaperForge.git ``` -**pip editable 安装用户：** +**pip editable / git clone 用户：** ```bash -cd 你的Vault路径 +cd 你的仓库目录 git pull origin master pip install -e . ``` -**git clone 用户：** -```bash -cd 你的Vault路径 -git pull origin master -``` - #### 方式 4：手动复制（最后手段） ```bash diff --git a/README.md b/README.md index d49965b0..86db293a 100644 --- a/README.md +++ b/README.md @@ -110,11 +110,12 @@ pip install --upgrade git+https://github.com/LLLin000/PaperForge.git ## 文档 -- [安装指南](docs/INSTALLATION.md) -- [安装后指南](AGENTS.md) -- [变更日志](CHANGELOG.md) -- [贡献指南](CONTRIBUTING.md) -- [v1.4 迁移说明](docs/MIGRATION-v1.4.md) +- [📖 详细安装配置指南](docs/setup-guide.md) — 从零开始的完整教程 +- [⚡ 快速安装指南](docs/INSTALLATION.md) — 简洁版安装步骤 +- [📋 安装后指南](AGENTS.md) — 第一次使用必看 +- [📝 变更日志](CHANGELOG.md) — 版本历史 +- [🤝 贡献指南](CONTRIBUTING.md) — 开发环境搭建 +- [📎 v1.4 迁移说明](docs/MIGRATION-v1.4.md) — 从旧版升级 ## License diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index d1e717de..01dfd1dd 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,148 +1,51 @@ -# PaperForge 安装指南 +# PaperForge Lite 快速安装指南 -## 推荐方式：交互式安装向导 - -PaperForge 提供图形化安装向导，引导你完成全部配置： - -```bash -# 1. 克隆仓库 -git clone https://github.com/LLLin000/PaperForge.git -cd PaperForge - -# 2. 运行向导（pip install -e . 由向导自动执行） -python setup_wizard.py --vault /path/to/your/vault -``` - -向导会按步骤引导你： -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 | +> 详细版教程（含截图和每个步骤的说明）请见 [setup-guide.md](setup-guide.md)。 --- -## 手动安装（备用） +## 前置条件 -如果向导无法运行，可以手动安装： - -### Step 1: 安装依赖 - -```bash -pip install requests pymupdf pillow -``` - -### Step 2: 创建目录结构 - -```bash -mkdir -p "{vault_path}//PaperForge/ocr" -mkdir -p "{vault_path}//PaperForge/worker/scripts" -mkdir -p "{vault_path}//Zotero" -mkdir -p "{vault_path}///library-records" -``` - -### Step 3: 链接 Zotero 数据目录 - -**Windows** (管理员终端): -```cmd -mklink /J "{vault_path}\\Zotero" "C:\Users\\Zotero" -``` - -**macOS/Linux**: -```bash -ln -s "~/Zotero" "{vault_path}//Zotero" -``` - -### Step 4: 配置 .env - -创建 `{vault_path}/.env`: -``` -PADDLEOCR_API_TOKEN=your_api_token_here -PADDLEOCR_JOB_URL=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs -``` - -### Step 5: 部署脚本 - -```bash -cp pipeline/worker/scripts/literature_pipeline.py "{vault_path}//PaperForge/worker/scripts/" -cp -r skills/literature-qa "{vault_path}//" -cp AGENTS.md "{vault_path}/AGENTS.md" -``` +- Python 3.10+ +- Zotero + Better BibTeX 插件 +- Obsidian +- PaddleOCR API Key（[申请地址](https://paddleocr.baidu.com)） --- -## 安装后验证 +## 安装（推荐方式：pip） -运行向导后，验证安装： +```powershell +# 1. 安装 +pip install git+https://github.com/LLLin000/PaperForge.git -```bash -cd "{vault_path}" - -# 验证 PaperForge 路径配置 -paperforge paths - -# 验证系统状态 -paperforge status +# 2. 运行安装向导 +paperforge setup ``` -预期输出（`paperforge status`）： -``` -PaperForge Lite v1.2.0 -Vault: /path/to/your/vault -Status: OK -``` - -**备选方式**（直接调用 worker 脚本）： -```bash -# 先获取 worker 脚本路径 -python -m pip install -e . -python $(python -c "import json; print(json.load(open('paperforge.json'))['paperforge_path'] + '/worker/scripts/literature_pipeline.py')" --vault . status -``` - -**如果 `paperforge` 命令未注册**，使用 fallback： -```bash -python -m paperforge -``` -例如：`python -m paperforge status` +向导会引导你完成 Vault 配置、Zotero 链接、API Key 设置。 --- -## 故障排除 +## Better BibTeX 配置 -### Zotero 未找到 -- 确认 Zotero 已安装 -- 检查数据目录路径（Zotero → Edit → Preferences → Advanced → Files and Folders） -- 向导中手动输入正确的数据目录路径 +1. Zotero → Edit → Preferences → Better BibTeX +2. 勾选 **"Keep updated"** +3. 格式：Better BibLaTeX +4. 导出路径：`{你的Vault}/[system_dir]/PaperForge/exports/library.json` +5. 点击 OK -### 权限被拒绝（Windows） -- 以管理员身份运行终端来创建 Junction -- 或手动创建 Junction：`mklink /J "目标" "源"` +--- -### Better BibTeX 未安装 -- Zotero → 工具 → 插件 → 齿轮图标 → Install Plugin From File... -- 下载地址：https://retorque.re/zotero-better-bibtex/ +## 验证安装 + +```powershell +paperforge doctor # 诊断所有组件 +paperforge status # 查看系统状态 +``` --- ## 下一步 -安装完成后： - -1. **同步文献**：运行 `paperforge sync` 检测 Zotero 中的文献 -2. **标记精读**：在 Obsidian 中设置 `do_ocr: true` 和 `analyze: true` -3. **运行 OCR**：执行 `paperforge ocr` 处理 PDF -4. **开始精读**：使用 `/pf-deep ` 生成结构化阅读笔记 - -详细用法参见 [AGENTS.md](../AGENTS.md)。 +详细使用流程见 [setup-guide.md](setup-guide.md#6-首次使用流程)。