docs: sync all doc references — README, INSTALLATION.md, AGENTS.md for v1.4.1 pip-first flow

2026-07-22 06:50:53 +00:00 · 2026-04-28 01:06:58 +08:00 · 2026-04-28 01:06:58 +08:00 · bcd0934117
commit bcd0934117
parent 0a47a6e2ed
3 changed files with 45 additions and 141 deletions
--- 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 数据目录已链接到 <system_dir>/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
--- 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

--- 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}/<system_dir>/PaperForge/ocr"
-mkdir -p "{vault_path}/<system_dir>/PaperForge/worker/scripts"
-mkdir -p "{vault_path}/<system_dir>/Zotero"
-mkdir -p "{vault_path}/<resources_dir>/<control_dir>/library-records"
-```
-
-### Step 3: 链接 Zotero 数据目录
-
-**Windows** (管理员终端):
-```cmd
-mklink /J "{vault_path}\<system_dir>\Zotero" "C:\Users\<User>\Zotero"
-```
-
-**macOS/Linux**:
-```bash
-ln -s "~/Zotero" "{vault_path}/<system_dir>/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}/<system_dir>/PaperForge/worker/scripts/"
-cp -r skills/literature-qa "{vault_path}/<skill_dir>/"
-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 <command>
-```
-例如：`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 <zotero_key>` 生成结构化阅读笔记
-
-详细用法参见 [AGENTS.md](../AGENTS.md)。
+详细使用流程见 [setup-guide.md](setup-guide.md#6-首次使用流程)。