Zotero 技能

通过 REST API v3 与 Zotero 个人或群组文献库进行交互。

设置

需要设置两个环境变量：

ZOTERO_API_KEY   — Create at https://www.zotero.org/settings/keys/new
ZOTERO_USER_ID   — Found on the same page (numeric, not username)

对于群组文献库，请设置ZOTERO_GROUP_ID而非ZOTERO_USER_ID。

用于 CrossRef/Unpaywall 礼貌池的可选环境变量（提高 DOI 查找成功率）：

CROSSREF_EMAIL   — Your email (optional; uses fallback if unset)

如果缺少凭证，请告知用户所需信息，并引导他们前往密钥创建页面。

CLI 脚本

所有操作均使用scripts/zotero.py（Python 3，无外部依赖）。

python3 scripts/zotero.py <command> [options]

命令

全局标志

• --json— 以JSON格式输出，而非人类可读格式（适用于items、search、get命令）

常用选项

• --limit N— 返回的最大项目数（默认为25）
• --sort FIELD— 按dateModified（修改日期）、title（标题）、creator（创建者）、date（日期）排序
• --direction asc|desc— 排序方向
• --collection KEY— 按集合筛选或添加到集合
• --type TYPE— 按项目类型筛选（journalArticle期刊文章、book书籍、conferencePaper会议论文等）
• --tags "tag1,tag2"— 创建项目时添加标签
• --force— 在添加命令时跳过重复检测

工作流程

通过DOI添加论文

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review"
# Warns if already in library. Use --force to override.

重复检测：将DOI转换为元数据，按第一作者搜索资料库，比较DOI字段。

从文件批量添加

# One identifier per line, # for comments
python3 zotero.py batch-add dois.txt --type doi --tags "imported"

跳过重复项。报告摘要：已添加/已跳过/已失败。

导出参考文献

python3 zotero.py export --format bibtex --output refs.bib
python3 zotero.py export --format csljson --collection COLLKEY

更新标签/元数据

python3 zotero.py update ITEMKEY --add-tags "important" --remove-tags "unread"
python3 zotero.py update ITEMKEY --title "Corrected Title" --date "2024"
python3 zotero.py update ITEMKEY --doi "10.1234/example"
python3 zotero.py update ITEMKEY --url "https://example.com/paper"
python3 zotero.py update ITEMKEY --add-collection COLLKEY

删除条目

python3 zotero.py delete KEY1 KEY2 --yes           # Trash (recoverable, default)
python3 zotero.py delete KEY1 --permanent --yes    # Permanent delete

交叉引用引文

python3 zotero.py crossref my-paper.txt

提取作者（年份）从文本中提取模式并与资料库匹配。

查找缺失的DOI

# Dry run (default) — show matches without writing anything
python3 zotero.py find-dois --limit 20

# Actually write DOIs to Zotero
python3 zotero.py find-dois --apply

# Filter by collection
python3 zotero.py find-dois --collection COLLKEY --apply

扫描缺失DOI的期刊文章和会议论文条目，查询CrossRef，并通过标题相似度（>85%）、确切年份和第一作者姓氏进行匹配。默认情况下为试运行——使用--apply以执行写入。仅修补DOI字段；绝不触碰其他元数据。在CrossRef请求之间有1秒延迟（使用带邮件地址的礼貌池）。

获取开放获取PDF

# Dry run — show which PDFs are available and from where
python3 zotero.py fetch-pdfs --dry-run --limit 10

# Fetch and attach as linked URLs (no storage quota used)
python3 zotero.py fetch-pdfs --limit 20

# Also save PDFs locally
python3 zotero.py fetch-pdfs --download-dir ./pdfs

# Upload to Zotero storage instead of linked URL
python3 zotero.py fetch-pdfs --upload --limit 10

# Only try specific sources
python3 zotero.py fetch-pdfs --sources unpaywall,semanticscholar

按顺序尝试三个合法的开放获取来源：Unpaywall → Semantic Scholar → DOI内容协商。默认情况下创建链接的URL附件（无需Zotero存储配额）。使用--upload用于 完整上传至Zotero存储的S3。使用--download-dir也可将PDF本地保存。

来源： unpaywall、semanticscholar、doi（默认：三者全部）

速率限制：Unpaywall/Semantic Scholar请求间隔1秒，DOI请求间隔2秒。

JSON脚本编写

python3 zotero.py --json items --limit 100 | jq '.items[].DOI'
python3 zotero.py --json get ITEMKEY | jq '.title'

注意事项

• 零依赖——仅使用Python 3标准库（urllib、json、argparse）
• 写入操作需要具有写入权限的API密钥
• 如果Zotero翻译服务器宕机（503），DOI查找将回退至CrossRef
• 输入验证：DOI必须为10.xxxx/...格式。项目键为8位字母数字（例如，VNPN6FHTISBN必须通过校验和验证。
• check-pdfs会获取所有条目；对于大型库（500+条），这可能会很慢
• fetch-pdfs也会处理所有条目——对于大型库，请使用--collection参数来限定范围
• 频率限制较为宽松；批量添加时会在条目间加入1秒延迟
• 常见错误及故障排除请参阅references/troubleshooting.md