lllin000_PaperForge/docs

Better BibTeX 配置指南

什么是 Better BibTeX

Better BibTeX (BBT) 是一个 Zotero 插件，用于生成和管理 citation key，并支持自动导出 JSON 格式的文献库。

为什么需要 BBT

PaperForge 通过 BBT 的 JSON 导出功能获取文献信息：

• citation key（zotero_key）
• 标题、作者、年份
• DOI、期刊、摘要
• PDF 附件路径

没有 BBT 导出，selection-sync 无法检测到 Zotero 中的新文献。

---

配置步骤

Step 1: 安装 Better BibTeX 插件

1. 打开 Zotero
2. 进入 Edit → Preferences → Plugins
3. 搜索 "Better BibTeX"
4. 安装并重启 Zotero

Step 2: 配置自动导出

1. Zotero → Edit → Preferences → Better BibTeX

2. 勾选 "Keep updated"（保持更新）—— 这会让 Zotero 在每次添加/修改文献时自动更新 JSON 文件

3. 选择导出格式：Better BibLaTeX 或 Better BibTeX（二者皆可）

4. 导出路径设置为：

   {你的Vault路径}/{system_dir}/PaperForge/exports/library.json
   

   其中 {system_dir} 默认是 99_System，可以通过 paperforge.json 自定义。

   完整路径示例（Windows）：

   D:\MyVault\99_System\PaperForge\exports\library.json
   

   完整路径示例（macOS/Linux）：

   /Users/name/MyVault/99_System/PaperForge/exports/library.json
   

5. 点击 OK，JSON 文件会自动生成并保持同步

Step 3: 验证配置

1. 在 Zotero 中手动触发一次导出（右击收藏夹 → Export...）
2. 确认 JSON 文件已生成且包含文献数据
3. 运行验证命令：

   paperforge doctor
   

   检查输出中的 "BBT 导出" 部分，确认显示 [PASS]

---

使用 paperforge doctor 验证

paperforge doctor

输出示例（正常情况）：

[PASS] BBT 导出 — library.json 正常 (25 条)

输出示例（有问题）：

[FAIL] BBT 导出 — library.json 不存在
修复步骤:
  - BBT 导出: 在 Zotero Better BibTeX 设置中配置导出路径

---

常见问题

Q: 导出路径填什么？

A: 完整路径 = {Vault根目录}/{system_dir}/PaperForge/exports/library.json

示例：D:\MyVault\99_System\PaperForge\exports\library.json

如果不确定 system_dir 是什么，运行 paperforge paths 查看。

Q: "Keep updated" 是什么？

A: 勾选后，每次添加/修改文献时 Zotero 会自动更新 JSON 文件。强烈建议勾选，否则需要手动导出。

Q: JSON 文件是空的怎么办？

A: 检查以下几点：

1. 确认 Zotero 中有文献
2. 确认导出了 PDF 附件的文献（没有 PDF 的文献可能不会被某些 BBT 格式导出）
3. 检查 Zotero → Better BibTeX preferences 中的导出格式设置

Q: citation key 是什么？

A: citation key 是文献的唯一标识符，例如 Smith2024AI。BBT 根据作者、年份、标题自动生成。PaperForge 用它作为 zotero_key 来关联文献。

Q: BBT 导出的 JSON 格式是什么样的？

A: JSON 是一个数组，每个元素包含文献元数据：

[
  {
    "key": "Smith2024AI",
    "title": "Example Paper Title",
    "authors": [{"family": "Smith", "given": "John"}],
    "year": 2024,
    "DOI": "10.xxxx/xxxxx",
    ...
  },
  ...
]

Q: 可以在多台电脑上使用同一个导出路径吗？

A: 不建议。JSON 导出路径应该指向本地 vault 目录，由 Zotero 自动维护。如果使用网络共享路径，可能导致文件锁定或同步问题。