6 KiB
PaperForge Lite 安装与配置指南
本文档是 setup_wizard.py 的补充说明。如果 TUI 向导中的文字指引不够直观，请参考本页的详细步骤。
本文档中的截图保存在
docs/images/目录下，向导中点击"查看安装截图"按钮可直接打开。
第一步：安装 Zotero
Zotero 是免费的文献管理软件，用于收集、组织和引用文献。
向导截图：docs/images/zotero-install.png
下载安装
- 访问 https://www.zotero.org/download/
- 下载对应系统的安装包
- 按向导完成安装
验证安装
安装完成后，确认可以正常打开 Zotero 主界面。
第二步：安装 Better BibTeX 插件
Better BibTeX (BBT) 是 Zotero 的插件，用于生成可供 PaperForge 读取的 JSON 导出。
向导截图：docs/images/bbt-install.png
下载插件
- 访问 https://retorque.re/zotero-better-bibtex/
- 找到最新版本的
.xpi文件并下载
安装到 Zotero
Zotero
└─ 工具(Tools)
└─ 插件(Plugins)
└─ [齿轮图标]
└─ Install Plugin From File...
└─ [选择下载的 .xpi 文件]
└─ [重启 Zotero]
Windows 详细步骤：
- 打开 Zotero
- 菜单栏点击
工具(Tools)→插件(Plugins) - 在插件管理器右上角点击齿轮图标
- 选择
Install Plugin From File... - 浏览到下载的
.xpi文件，选中后点击打开 - 提示安装成功，重启 Zotero
macOS 详细步骤：
- 打开 Zotero
- 菜单栏
Zotero→Preferences→Plugins - 点击齿轮图标 →
Install Plugin From File... - 选择
.xpi文件 - 重启 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 详细步骤：
- 在 Zotero 左侧选择你要导出的收藏夹（如"骨科"）
- 菜单栏
文件(File)→导出库(Export Library...) - 格式下拉框选择
Better BibLaTeX - 勾选右下角的
Keep updated - 点击
...选择保存位置，导航到：{你的Vault根目录}/<system_dir>/PaperForge/exports/ - 文件名填写收藏夹名称，如
骨科.json - 点击保存
重复上述步骤，为每个需要管理的收藏夹导出 JSON。
验证导出
导出完成后，检查文件：
ls <system_dir>/PaperForge/exports/
# 应该看到: 骨科.json 运动医学.json ...
打开任意 JSON 文件，确认包含类似以下结构：
[
{
"citationKey": "XXXXX",
"title": "论文标题",
"year": 2024,
...
}
]
第四步：运行 PaperForge 工作流
完成上述配置后，回到 Vault 根目录，运行：
# 1. 同步 Zotero 文献，创建状态记录
paperforge sync
备选方式（直接调用 worker 脚本）： 先运行
pip install -e .安装 paperforge 工具，然后：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: 如何添加新的收藏夹？
- 在 Zotero 中创建新收藏夹并添加文献
- 按照步骤三导出新的 JSON
- 重新运行
paperforge sync
Q: 修改了收藏夹名称？
- 在 Zotero 中修改收藏夹名称
- 重新导出 JSON（可以覆盖原文件或导出为新文件）
- 如果导出了新文件名的 JSON，旧文件可以手动删除
- 重新运行
paperforge sync
下一步
配置完成后，阅读 AGENTS.md 了解完整工作流，或运行 TUI 向导：
python setup_wizard.py --vault .
PaperForge Lite | 安装指南