From f6d4b54032a882f8b6407ed8c111f9cdda26fb22 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Fri, 8 May 2026 14:02:51 +0800 Subject: [PATCH] docs(54-002): delete pip-first docs, update README.md and AGENTS.md references - Delete docs/INSTALLATION.md (pip-first installation guide) - Delete docs/setup-guide.md (detailed installation guide) - Update README.md docs table: remove deleted file references - Update AGENTS.md: replace deleted doc links with plugin-first install guidance --- AGENTS.md | 2 +- README.md | 2 - docs/INSTALLATION.md | 67 ------ docs/setup-guide.md | 562 ------------------------------------------- 4 files changed, 1 insertion(+), 632 deletions(-) delete mode 100644 docs/INSTALLATION.md delete mode 100644 docs/setup-guide.md diff --git a/AGENTS.md b/AGENTS.md index 13fd7342..d0d04fea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # PaperForge - Agent Guide -> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [setup-guide.md](docs/setup-guide.md) 或快速版 [INSTALLATION.md](docs/INSTALLATION.md)。Docs 版本与 v1.4.13 对应。 +> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。如果还没有安装 PaperForge，请通过 Obsidian 插件市场安装，或查看 [README.md](README.md) 中的安装说明。Docs 版本与 v1.4.13 对应。 --- diff --git a/README.md b/README.md index 14e6ba95..f3078b8d 100644 --- a/README.md +++ b/README.md @@ -172,8 +172,6 @@ pip install --upgrade git+https://github.com/LLLin000/PaperForge.git | 文档 | 内容 | |------|------| -| [安装指南](docs/setup-guide.md) | 从零开始的完整教程 | -| [快速安装](docs/INSTALLATION.md) | 简洁版安装步骤 | | [安装后指南](AGENTS.md) | 首次使用与工作流说明 | | [变更日志](CHANGELOG.md) | 版本历史 | | [贡献指南](CONTRIBUTING.md) | 开发环境与协作约定 | diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index 9d1db7df..00000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,67 +0,0 @@ -# PaperForge 快速安装指南 - -> 详细版教程（含截图和每个步骤的说明）请见 [setup-guide.md](setup-guide.md)。 - ---- - -## 前置条件 - -- Python 3.10+ -- Zotero + Better BibTeX 插件 -- Obsidian -- PaddleOCR API Key（[申请地址](https://paddleocr.baidu.com)） - -> 安装向导是**增量式**的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会创建缺失的目录和文件，不会删除已有内容。 - ---- - -## 安装（推荐方式：pip） - -```powershell -# 1. 安装 -pip install git+https://github.com/LLLin000/PaperForge.git - -# 2. 运行安装向导（headless 模式，会把插件文件部署到当前 Vault） -paperforge setup --headless --agent opencode --paddleocr-key - -向导会自动完成环境检测、目录创建、文件部署和配置写入。如果已有配置文件，安装只做增量补充。 - -安装向导完成后，才进入 Obsidian 启用插件；启用之前不能打开 Dashboard。 - ---- - -## Better BibTeX 配置 - -这一步在 `paperforge setup --headless` 完成之后再做，因为导出目录要先由安装向导创建。 - -1. 打开 Zotero -2. 对你要同步的库或分类右键 → `Export...` / `导出...` -3. 格式选择 **Better BibTeX JSON** -4. 勾选 **"Keep updated"** -5. 导出到：`{你的Vault}/[system_dir]/PaperForge/exports/` -6. JSON 文件名会作为 Base 名称，例如：`library.json`、`骨科.json` - ---- - -## 验证安装 - -```powershell -paperforge status # 确认 setup 已经把 PaperForge 部署到当前 Vault -``` - -然后在 Obsidian 中： - -1. `Settings -> Community Plugins -> Installed -> PaperForge -> Enable` -2. 按 `Ctrl+P` 搜索 `PaperForge` - -之后再执行： - -```powershell -paperforge doctor # 诊断所有组件 -``` - ---- - -## 下一步 - -详细使用流程见 [setup-guide.md](setup-guide.md#6-首次使用流程)。 diff --git a/docs/setup-guide.md b/docs/setup-guide.md deleted file mode 100644 index 99414ea8..00000000 --- a/docs/setup-guide.md +++ /dev/null @@ -1,562 +0,0 @@ -# PaperForge 安装配置与使用指南 - -> 本文档面向**首次使用 PaperForge 的新用户**，从零开始覆盖安装、配置、使用全流程。 - ---- - -## 目录 - -1. [前置条件](#1-前置条件) -2. [安装 PaperForge](#2-安装-paperforge) -3. [运行安装向导](#3-运行安装向导) -4. [配置 Zotero 和 Better BibTeX](#4-配置-zotero-和-better-bibtex) -5. [验证安装](#5-验证安装) -6. [首次使用流程](#6-首次使用流程) -7. [日常使用命令](#7-日常使用命令) -8. [更新 PaperForge](#8-更新-paperforge) -9. [故障排除](#9-故障排除) - ---- - -## 1. 前置条件 - -### 1.1 需要安装的软件 - -| 软件 | 版本要求 | 用途 | 下载地址 | -|------|---------|------|---------| -| Python | 3.10+ | 运行 PaperForge | https://python.org/downloads/ | -| Zotero | 最新版 | 文献管理 | https://zotero.org/download/ | -| Better BibTeX | 最新版 | Zotero 插件 | https://retorque.re/zotero-better-bibtex/installation/ | -| Obsidian | 最新版 | 笔记软件 | https://obsidian.md/download/ | -| Git | 可选 | 手动更新 | https://git-scm.com/downloads/win | - -### 1.2 需要申请的 API Key - -- **PaddleOCR API Key**：用于 PDF 自动 OCR 提取 - - 访问 https://paddleocr.baidu.com - - 注册账号 → 创建应用 → 获取 API Token - - 免费额度通常足够个人使用 - -### 1.3 确认 Zotero 已有文献 - -在开始安装前，确保： -1. Zotero 已安装并打开过至少一次 -2. Zotero 中已有至少一篇带 PDF 附件的文献 -3. Better BibTeX 插件已安装（Zotero → 工具 → 插件 → 搜索 Better BibTeX） - -> 安装向导是**增量式**的：如果你选择的 Vault 或目录里已经有文件，PaperForge 只会创建缺失的目录和文件，不会删除已有内容。 - ---- - -## 2. 安装 PaperForge - -### 方式 A：pip 安装（推荐） - -打开 PowerShell（Windows）或终端（macOS/Linux）： - -```powershell -pip install git+https://github.com/LLLin000/PaperForge.git -``` - -验证安装： -```powershell -paperforge --help -``` - -如果看到命令列表，说明安装成功。 - -### 方式 B：一键安装脚本（Windows 新用户） - -如果不太熟悉命令行，使用一键脚本： - -```powershell -powershell -c "iwr -Uri https://raw.githubusercontent.com/LLLin000/PaperForge/master/scripts/install-paperforge.ps1 -OutFile install.ps1; ./install.ps1" -``` - -脚本会自动检查 Python、安装 PaperForge，然后提示运行 `paperforge setup --headless`。 - -### 方式 C：从源码安装（开发者用） - -```powershell -git clone https://github.com/LLLin000/PaperForge.git -cd PaperForge -pip install -e . -``` - ---- - -## 3. 运行安装向导 - -### 3.1 启动安装 - -PaperForge 安装向导以非交互模式（headless）运行，无需手动交互： - -```powershell -paperforge setup --headless --agent opencode --paddleocr-key -``` - -向导会自动完成以下步骤： -1. 环境检测（Python 版本、依赖包） -2. 创建目录结构（PaperForge 数据库目录、插件目录、文献笔记目录） -3. 部署 Worker 脚本和 Agent 技能文件 -4. 写入配置文件（paperforge.json、.env） -5. 注册 paperforge CLI -6. 验证安装完整性 - -如果已有配置文件，安装只做增量补充，不会覆盖已有内容。 - -> 提示：如果通过 Obsidian 插件安装，打开设置页 → 填写配置 → 点击"安装"， -> 插件会自动调用上述 headless 命令，无需在终端中手动执行。 - -这一步会把 PaperForge 需要的文件部署到当前 Vault，包括 `.obsidian/plugins/paperforge/`。在这一步完成之前，Obsidian 里还不能启用插件，也不能打开 Dashboard。 - -### 3.2 安装后文件结构 - -安装完成后，你的 vault 目录结构如下： - -``` -your-vault/ -├── [system_dir]/ # 你自定义的系统目录 -│ └── PaperForge/ -│ ├── exports/ # Better BibTeX JSON 导出（自动生成） -│ ├── ocr/ # OCR 结果（自动生成） -│ │ └── [zotero_key]/ # 每篇文献一个目录 -│ │ ├── meta.json # OCR 状态 -│ │ ├── fulltext.md # OCR 全文 -│ │ ├── images/ # 图表图片 -│ │ └── figure-map.json -│ ├── config/ -│ │ └── domain-collections.json -│ ├── worker/scripts/ # 工作流脚本 -│ └── .env # PaddleOCR API Key -│ -├── [resources_dir]/ # 你自定义的资源目录 -│ ├── [literature_dir]/ # 正式文献笔记（含 frontmatter 状态跟踪） -│ │ └── [domain]/ # 按 Zotero 分类 -│ │ └── [key] - [Title].md # 正式文献笔记 -│ -├── [base_dir]/ # Obsidian Base 视图 -│ └── [domain].base # 每个分类一个 Base -│ -├── [skill_dir]/ # Agent 技能 -│ └── literature-qa/ -│ ├── scripts/ld_deep.py -│ ├── prompt_deep_subagent.md -│ └── chart-reading/ # 19 种图表指南 -│ -├── .env # API Key（仅供 CLI 读取） -├── paperforge.json # 配置 -└── AGENTS.md # 本指南 -``` - ---- - -## 4. 配置 Zotero 和 Better BibTeX - -### 4.1 配置 Better BibTeX 自动导出 - -这一步要在安装向导完成后再做，因为 `exports/` 目录要先由安装流程创建。 - -这一步是关键——PaperForge 通过 Better BibTeX 的自动导出 JSON 来感知 Zotero 中的文献变化。 - -1. 打开 Zotero -2. 对你要同步的文献库或分类右键 → **Export... / 导出...** -3. **导出格式**：选择 **Better BibTeX JSON** -4. **勾选 "Keep updated"**（自动导出） -5. **导出路径**设置为： - ``` - {你的Vault路径}/[system_dir]/PaperForge/exports/library.json - ``` - 例如：`C:\MyVault\99_System\PaperForge\exports\library.json` -6. **点击保存** - -### 4.2 按分类导出（可选） - -如果你希望按 Zotero 收藏夹分类导出（推荐），可以： -1. 在 Zotero 中创建多个收藏夹（如：骨科、运动医学、肿瘤学） -2. 在每个收藏夹上右键 → **Export Collection...** -3. 导出为 Better BibLaTeX 格式 -4. 保存到 `exports/` 目录：`exports/骨科.json`、`exports/运动医学.json` -5. **勾选 "Keep updated"** - -这样 PaperForge 会按分类组织你的文献笔记。 - -### 4.3 验证 JSON 导出 - -检查导出文件是否生成： -```powershell -dir {vault_path}/[system_dir]/PaperForge/exports/*.json -``` -应该能看到 `.json` 文件。 - ---- - -## 5. 验证安装 - -### 5.1 运行诊断 - -```powershell -paperforge doctor -``` - -预期输出包含： -- Python 版本检测 ✓ -- Vault 结构检测 ✓ -- Zotero 检测 ✓ - -### 5.2 查看路径 - -```powershell -paperforge paths -``` - -显示所有 PaperForge 路径，确认目录结构正确。 - -### 5.3 查看状态 - -```powershell -paperforge status -``` - -显示系统概览，包括： -- PaperForge 版本 -- Vault 路径 -- 各目录状态 -- OCR 配置状态 - ---- - -## 6. 首次使用流程 - -### 6.1 同步 Zotero 文献 - -```powershell -paperforge sync -``` - -这个命令会读取 BBT JSON 导出，直接生成正式文献笔记 `Literature/[domain]/[key] - [Title].md`，并创建 Obsidian Base 视图。 - -预期输出： -``` -[INFO] Found 5 new items -[INFO] Created 骨科/XXXXXXX.md -[INFO] Generated 5 formal notes -``` - -### 6.2 在 Obsidian 中查看 - -打开 Obsidian，你应该能看到： -- `[resources_dir]/Literature/` 下有了文献笔记 -- `[base_dir]/` 下有了 `.base` 文件（Base 视图） -- 在 Obsidian 的 Base 插件中可以看到控制面板 - -### 6.3 在 Base 视图中标记 OCR - -在 Obsidian Base 视图中找到该文献，将 `do_ocr` 设为 `true`。保存后该文献会进入 OCR 队列。 - -### 6.4 运行 OCR - -```powershell -paperforge ocr -``` - -新版 `paperforge ocr` 是**一步到位**的： -1. **上传阶段**：将 PDF 上传到 PaddleOCR API -2. **等待阶段**：自动轮询，每 15 秒检查一次进度 -3. **下载阶段**：OCR 完成后自动下载全文和图表 -4. 全程不需要用户干预 - -预期输出： -``` -Processing OCR: 100%|████| 2/2 [00:00] -Uploading: 100%|████| 2/2 [00:01] -Waiting OCR: 100%|████| 2/2 [00:30] -ocr: updated 2 records -``` - -输出文件： -- `[system_dir]/PaperForge/ocr/[key]/fulltext.md` — 全文 -- `[system_dir]/PaperForge/ocr/[key]/images/` — 图表图片 -- `[system_dir]/PaperForge/ocr/[key]/meta.json` — OCR 元数据 -- `[system_dir]/PaperForge/ocr/[key]/figure-map.json` — 图表索引 - -### 6.5 在 Base 视图中标记精读 - -OCR 完成后，在 Obsidian Base 视图中找到该文献，将 `analyze` 设为 `true`。 - -### 6.6 执行精读 - -在 OpenCode 中（或你选择的 Agent 平台）输入： - -``` -/pf-deep XXXXXXX -``` - -Agent 会自动： - -**第 1 步：前置准备（prepare）** -- 检查正式笔记和 OCR 状态 -- 确认 OCR 已完成 -- 生成 figure-map 和 chart-type-map -- 插入 `## 🔍 精读` 骨架（包含所有 figure/table 的 callout 块） -- 每个 callout 块内有 6 个固定子标题 - -**第 2 步：Pass 1 概览** -- AI 填写"一句话总览"和"5 Cs 快速评估" - -**第 3 步：Pass 2 精读还原** -- AI 按顺序逐个填写 figure callout 块 -- 每块有固定子标题：图像定位、方法结果、质量审查、作者解释、我的理解、疑点 -- AI 读取 chart-type-map，参考对应的图表阅读指南 -- 每填写完一张图保存一次 -- **完成后自动检查**：顺序、图片边界、空块、缺失子标题 - -**第 4 步：Pass 3 深度理解** -- AI 编写假设挑战、结论评估、研究启发 - -**第 5 步：最终验证** -- 运行 validate-note 检查结构完整性 - -整个精读过程约 5-15 分钟（取决于论文长度），完成后在 Obsidian 中打开文献笔记即可看到 `## 🔍 精读` 区域。 - -### 6.6 快速摘要（不要求 OCR） - -如果只想看论文摘要而不需要完整精读： - -``` -/pf-paper XXXXXXX -``` - -这个命令不需要 OCR 完成，只要有正式笔记即可。 - ---- - -## 7. 日常使用命令 - -### 7.1 终端命令 - -| 命令 | 用途 | 说明 | -|------|------|------| -| `paperforge status` | 查看系统状态 | 诊断各组件健康度 | -| `paperforge sync` | 同步 Zotero 并生成笔记 | 新增/更新文献时运行 | -| `paperforge ocr` | 运行 OCR | 一步到位，等待完成后返回 | -| `paperforge ocr --diagnose` | 诊断 OCR 配置 | 检查 token/URL/API | -| `paperforge deep-reading` | 查看精读队列 | 显示可精读的文献列表 | -| `paperforge doctor` | 诊断整体配置 | 验证安装完整性 | -| `paperforge update` | 更新到最新版 | 自动检测安装方式 | -| `paperforge setup --headless` | 重新运行安装向导（headless 模式） | 修改配置时使用 | -| `paperforge --verbose` | 启用 DEBUG 日志 | 配合任意命令使用 | - -### 7.2 Agent 命令（在 OpenCode 中使用） - -| 命令 | 用途 | -|------|------| -| `/pf-deep ` | 完整三阶段精读 | -| `/pf-paper ` | 快速摘要 | -| `/pf-sync` | 同步 Zotero（Agent 解读状态） | -| `/pf-ocr` | 运行 OCR（Agent 检查队列） | -| `/pf-status` | 查看状态（Agent 解读诊断） | - -### 7.3 OCR 配置环境变量 - -| 环境变量 | 默认值 | 说明 | -|---------|--------|------| -| `PADDLEOCR_API_TOKEN` | — | PaddleOCR API Key | -| `PADDLEOCR_JOB_URL` | `https://paddleocr.aistudio-app.com/api/v2/ocr/jobs` | API 地址 | -| `PADDLEOCR_MODEL` | `PaddleOCR-VL-1.5` | OCR 模型 | -| `PADDLEOCR_MAX_ITEMS` | 3 | 并发 OCR 数 | -| `PAPERFORGE_RETRY_MAX` | 5 | 上传重试次数 | -| `PAPERFORGE_RETRY_BACKOFF` | 2.0 | 重试退避秒数 | -| `PAPERFORGE_POLL_MAX_CYCLES` | 20 | OCR 轮询最大次数 | -| `PAPERFORGE_POLL_INTERVAL` | 15 | 轮询间隔秒数 | -| `PAPERFORGE_ZOMBIE_TIMEOUT_MINUTES` | 30 | 僵尸任务超时（分钟） | -| `PAPERFORGE_LOG_LEVEL` | INFO | 日志级别 | - ---- - -## 8. 更新 PaperForge - -### 8.1 自动更新 - -```powershell -paperforge update -``` - -自动检测当前安装方式（pip / pip editable / git clone），执行对应的更新命令。 - -### 8.2 手动更新 - -**pip 安装用户：** -```powershell -pip install --upgrade git+https://github.com/LLLin000/PaperForge.git -``` - -**pip editable 安装用户：** -```powershell -cd {仓库目录} -git pull origin master -pip install -e . -``` - -**Windows 一键脚本：** -```powershell -.\scripts\install-paperforge.ps1 -Force -``` - -### 8.3 查看版本 - -```powershell -python -c "import paperforge; print(paperforge.__version__)" -``` - ---- - -## 9. 故障排除 - -### 9.1 paperforge 命令找不到 - -```powershell -# 检查 pip 安装 -pip list | findstr paperforge - -# 如果未安装，重新安装 -pip install git+https://github.com/LLLin000/PaperForge.git - -# 如果已安装但命令不在 PATH，使用 fallback -python -m paperforge status -``` - -### 9.2 同步后没有生成正式笔记 - -``` -# 检查 JSON 导出文件是否存在 -dir {vault}/[system_dir]/PaperForge/exports/*.json - -# 确认 JSON 文件有内容 -python -c "import json; d=json.loads(open('exports/library.json',encoding='utf-8').read()); print(len(d.get('items',[]) if isinstance(d,dict) else d),'items')" -``` - -**常见原因：** -- Better BibTeX 自动导出路径配置错误 -- JSON 文件为空 -- Zotero 中没有带 citation key 的条目 - -**修复：** -1. Zotero → Edit → Preferences → Better BibTeX → 确认"Keep updated"已勾选 -2. 确认导出路径正确 -3. 手动在 Zotero 中选一篇文献 → 右键 → Generate BibTeX key - -### 9.3 OCR 一直显示 pending - -``` -# 运行 OCR 诊断 -paperforge ocr --diagnose - -# 查看具体文献的 OCR 状态 -cat {vault}/[system_dir]/PaperForge/ocr/[key]/meta.json -``` - -**常见原因：** -- PaddleOCR API Key 未配置或无效 -- 网络连接问题（API 地址不可达） -- PDF 文件路径错误 - -**修复：** -- 检查 `.env` 中 `PADDLEOCR_API_TOKEN` 是否正确 -- 运行 `paperforge doctor` 查看整体状态 - -### 9.4 PDF 路径无法解析 - -``` -# 报错信息 -ERROR:paperforge.pdf_resolver:PDF path could not be resolved: storage:XXXX/filename.pdf -``` - -**原因**：Zotero 数据目录链接（junction/symlink）不正确。 - -**修复：** -1. 确认 Zotero 数据目录位置 -2. 重新创建 junction： -```powershell -# 删除旧的链接 -rmdir "{vault}/[system_dir]/Zotero" -# 创建新链接（管理员终端） -New-Item -ItemType Junction -Path "{vault}/[system_dir]/Zotero" -Target "C:\Users\用户名\Zotero" -``` - -或者： -```powershell -# 在 .env 中手动指定 Zotero 数据目录 -ZOTERO_DATA_DIR=C:\Users\用户名\Zotero -``` - -### 9.5 Base 视图不显示数据 - -- Base 视图需要手动刷新：在 Obsidian 中点击 Refresh 按钮 -- 或退出 Obsidian 重新打开 - -### 9.6 更新后出现异常 - -```powershell -# 查看完整日志 -paperforge status --verbose - -# 如果问题持续，重新安装 -pip install --force-reinstall git+https://github.com/LLLin000/PaperForge.git -``` - ---- - -## 附录 - -### A. Better BibTeX 配置参考 - -Zotero → Edit → Preferences → Better BibTeX： - -``` -☑ Keep updated -Export format: Better BibLaTeX -Export path: {vault}/[system_dir]/PaperForge/exports/library.json -Citation key format: [auth:lower]_[year] -``` - -### B. paperforge.json 参考 - -```json -{ - "name": "PaperForge-Lite", - "version": "1.4.1", - "repository": "https://github.com/LLLin000/PaperForge", - "system_dir": "99_System", - "resources_dir": "03_Resources", - "literature_dir": "Literature", - "control_dir": "LiteratureControl", - "base_dir": "05_Bases", - "auto_analyze_after_ocr": false, - "update": { - "channel": "stable", - "auto_check": true, - "check_interval_days": 7 - } -} -``` - -### C. .env 文件参考 - -``` -PADDLEOCR_API_TOKEN=your_api_token_here -PADDLEOCR_JOB_URL=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs -PADDLEOCR_MODEL=PaddleOCR-VL-1.5 -ZOTERO_DATA_DIR=C:\Users\用户名\Zotero -``` - -### D. 目录名称速查 - -| 配置项 | 默认值 | 用途 | -|-------|--------|------| -| system_dir | `99_System` | 系统文件 | -| resources_dir | `03_Resources` | 文献资源 | -| literature_dir | `Literature` | 正式笔记 | -| control_dir | `LiteratureControl` | 状态控制（v1.9+ 已废弃，状态移至 formal note） | -| base_dir | `05_Bases` | Obsidian Base | -| skill_dir | `.opencode/skills` | Agent 技能 |