mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 17:00:23 +00:00
62ec89441c
- Replace paperforge selection-sync/index-refresh with paperforge sync - Replace paperforge ocr run with paperforge ocr - Replace /LD-deep, /LD-paper with /pf-deep, /pf-paper - Add v1.1 -> v1.2 command migration table to AGENTS.md - Update README.md, docs/INSTALLATION.md, docs/setup-guide.md
230 lines
6 KiB
Markdown
230 lines
6 KiB
Markdown
# PaperForge Lite 安装与配置指南
|
||
|
||
> 本文档是 [setup_wizard.py](../setup_wizard.py) 的补充说明。如果 TUI 向导中的文字指引不够直观，请参考本页的详细步骤。
|
||
>
|
||
> 本文档中的截图保存在 `docs/images/` 目录下，向导中点击"查看安装截图"按钮可直接打开。
|
||
|
||
---
|
||
|
||
## 第一步：安装 Zotero
|
||
|
||
Zotero 是免费的文献管理软件，用于收集、组织和引用文献。
|
||
|
||
**向导截图**：`docs/images/zotero-install.png`
|
||
|
||
### 下载安装
|
||
|
||
1. 访问 https://www.zotero.org/download/
|
||
2. 下载对应系统的安装包
|
||
3. 按向导完成安装
|
||
|
||
### 验证安装
|
||
|
||
安装完成后，确认可以正常打开 Zotero 主界面。
|
||
|
||
---
|
||
|
||
## 第二步：安装 Better BibTeX 插件
|
||
|
||
Better BibTeX (BBT) 是 Zotero 的插件，用于生成可供 PaperForge 读取的 JSON 导出。
|
||
|
||
**向导截图**：`docs/images/bbt-install.png`
|
||
|
||
### 下载插件
|
||
|
||
1. 访问 https://retorque.re/zotero-better-bibtex/
|
||
2. 找到最新版本的 `.xpi` 文件并下载
|
||
|
||
### 安装到 Zotero
|
||
|
||
```
|
||
Zotero
|
||
└─ 工具(Tools)
|
||
└─ 插件(Plugins)
|
||
└─ [齿轮图标]
|
||
└─ Install Plugin From File...
|
||
└─ [选择下载的 .xpi 文件]
|
||
└─ [重启 Zotero]
|
||
```
|
||
|
||
**Windows 详细步骤：**
|
||
|
||
1. 打开 Zotero
|
||
2. 菜单栏点击 `工具(Tools)` → `插件(Plugins)`
|
||
3. 在插件管理器右上角点击齿轮图标
|
||
4. 选择 `Install Plugin From File...`
|
||
5. 浏览到下载的 `.xpi` 文件，选中后点击打开
|
||
6. 提示安装成功，重启 Zotero
|
||
|
||
**macOS 详细步骤：**
|
||
|
||
1. 打开 Zotero
|
||
2. 菜单栏 `Zotero` → `Preferences` → `Plugins`
|
||
3. 点击齿轮图标 → `Install Plugin From File...`
|
||
4. 选择 `.xpi` 文件
|
||
5. 重启 Zotero
|
||
|
||
### 验证安装
|
||
|
||
重启后，打开 `工具(Tools)` 菜单，确认出现 `Better BibTeX` 子菜单。
|
||
|
||
---
|
||
|
||
## 第三步：配置 Better BibTeX 自动导出
|
||
|
||
这是最关键的一步。每个导出的 JSON 文件将对应一个 Obsidian Base 视图。
|
||
|
||
**向导截图**：`docs/images/json-export.png`
|
||
|
||
### 理解 JSON 与 Base 的关系
|
||
|
||
```
|
||
你的 Zotero 收藏夹结构：
|
||
├── 骨科
|
||
├── 运动医学
|
||
└── 综述
|
||
|
||
Better BibTeX 导出后：
|
||
├── exports/骨科.json
|
||
├── exports/运动医学.json
|
||
└── exports/综述.json
|
||
|
||
PaperForge 自动生成：
|
||
├── <resources_dir>/<control_dir>/library-records/骨科/
|
||
├── <resources_dir>/<control_dir>/library-records/运动医学/
|
||
└── <resources_dir>/<control_dir>/library-records/综述/
|
||
```
|
||
|
||
**规则：一个 JSON 文件 = 一个 Base 视图 = 一个文献分类**
|
||
|
||
### 配置自动导出
|
||
|
||
**步骤一：设置自动导出模式**
|
||
|
||
```
|
||
Zotero
|
||
└─ 编辑(Edit)
|
||
└─ 首选项(Preferences)
|
||
└─ Better BibTeX（左侧边栏）
|
||
└─ [勾选] Automatic export: On Change
|
||
```
|
||
|
||
**步骤二：导出第一个 JSON**
|
||
|
||
```
|
||
Zotero
|
||
└─ 文件(File)
|
||
└─ 导出库(Export Library...)
|
||
├─ 格式(Format): Better BibLaTeX ★ 重要！不是 BibTeX
|
||
├─ 勾选 [Keep updated] ★ 必须勾选
|
||
├─ 文件名: 骨科.json ★ 建议用中文名，好识别
|
||
└─ 保存位置: {你的Vault}/<system_dir>/PaperForge/exports/
|
||
└─ [保存]
|
||
```
|
||
|
||
**Windows 详细步骤：**
|
||
|
||
1. 在 Zotero 左侧选择你要导出的收藏夹（如"骨科"）
|
||
2. 菜单栏 `文件(File)` → `导出库(Export Library...)`
|
||
3. 格式下拉框选择 `Better BibLaTeX`
|
||
4. 勾选右下角的 `Keep updated`
|
||
5. 点击 `...` 选择保存位置，导航到：
|
||
```
|
||
{你的Vault根目录}/<system_dir>/PaperForge/exports/
|
||
```
|
||
6. 文件名填写收藏夹名称，如 `骨科.json`
|
||
7. 点击保存
|
||
|
||
**重复上述步骤**，为每个需要管理的收藏夹导出 JSON。
|
||
|
||
### 验证导出
|
||
|
||
导出完成后，检查文件：
|
||
|
||
```bash
|
||
ls <system_dir>/PaperForge/exports/
|
||
# 应该看到: 骨科.json 运动医学.json ...
|
||
```
|
||
|
||
打开任意 JSON 文件，确认包含类似以下结构：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"citationKey": "XXXXX",
|
||
"title": "论文标题",
|
||
"year": 2024,
|
||
...
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 第四步：运行 PaperForge 工作流
|
||
|
||
完成上述配置后，回到 Vault 根目录，运行：
|
||
|
||
```bash
|
||
# 1. 同步 Zotero 文献，创建状态记录
|
||
paperforge sync
|
||
```
|
||
|
||
> **备选方式**（直接调用 worker 脚本）：
|
||
> 先运行 `pip install -e .` 安装 paperforge 工具，然后：
|
||
> ```bash
|
||
> python $(paperforge paths --json | python -c "import json,sys; print(json.load(sys.stdin)['worker_script'])") --vault . sync
|
||
> ```
|
||
|
||
此时你应该看到：
|
||
- `<resources_dir>/<control_dir>/library-records/` 下出现状态记录文件
|
||
- `<resources_dir>/<literature_dir>/` 下出现正式笔记
|
||
- `<resources_dir>/<control_dir>/library-records/` 下出现状态记录文件
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 导出格式选错成 BibTeX 怎么办？
|
||
|
||
重新导出，务必选择 `Better BibLaTeX`。BibTeX 格式缺少 citation key 等必要字段。
|
||
|
||
### Q: JSON 文件很大，导出慢？
|
||
|
||
正常。大型文献库的 JSON 可能几十 MB，导出需要几十秒。勾选 `Keep updated` 后，后续只有新增/修改的条目会更新。
|
||
|
||
### Q: 可以导出多个收藏夹吗？
|
||
|
||
可以，而且推荐这样做。每个收藏夹导出一个 JSON，PaperForge 会为每个 JSON 创建一个独立的 Base 视图。例如：
|
||
- `骨科.json` → `骨科.base`
|
||
- `运动医学.json` → `运动医学.base`
|
||
|
||
### Q: 如何添加新的收藏夹？
|
||
|
||
1. 在 Zotero 中创建新收藏夹并添加文献
|
||
2. 按照步骤三导出新的 JSON
|
||
3. 重新运行 `paperforge sync`
|
||
|
||
### Q: 修改了收藏夹名称？
|
||
|
||
1. 在 Zotero 中修改收藏夹名称
|
||
2. 重新导出 JSON（可以覆盖原文件或导出为新文件）
|
||
3. 如果导出了新文件名的 JSON，旧文件可以手动删除
|
||
4. 重新运行 `paperforge sync`
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
配置完成后，阅读 `AGENTS.md` 了解完整工作流，或运行 TUI 向导：
|
||
|
||
```bash
|
||
python setup_wizard.py --vault .
|
||
```
|
||
|
||
---
|
||
|
||
*PaperForge Lite | 安装指南*
|
||
|
||
|
||
|