Zotero 技能

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

配置

需设置两个环境变量：

ZOTERO_API_KEY   — 在 https://www.zotero.org/settings/keys/new 创建
ZOTERO_USER_ID   — 在同一页面获取（纯数字，非用户名）

若操作群组文献库，请改用 ZOTERO_GROUP_ID 替代 ZOTERO_USER_ID。

可选环境变量，用于接入 CrossRef / Unpaywall 礼貌请求池（提升 DOI 查找成功率）：

CROSSREF_EMAIL   — 您的邮箱（可选；未设置时将使用默认回退机制）

若凭据缺失，请明确告知用户所需内容，并附上密钥创建页面链接。

CLI 脚本

所有操作均通过 scripts/zotero.py 执行（Python 3，无任何外部依赖）。

python3 scripts/zotero.py  [options]

命令

全局标志（Global Flags）

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

常用选项（Common Options）

• --limit N — 返回条目最大数量（默认为 25）
• --sort FIELD — 按字段排序：dateModified、title、creator、date
• --direction asc|desc — 排序方向
• --collection KEY — 按文集过滤，或向指定文集添加条目
• --type TYPE — 按条目类型过滤（如 journalArticle、book、conferencePaper 等）
• --tags "tag1,tag2" — 创建条目时添加标签
• --force — 在添加类命令中跳过重复检测

典型工作流（Workflows）

通过 DOI 添加一篇论文

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review"
# 若该文献已存在于库中，则发出警告。可使用 --force 覆盖。

重复检测逻辑：将 DOI 解析为元数据，在库中按第一作者搜索，并比对 DOI 字段。

从文件批量添加

# 每行一个标识符，以 # 开头的行为注释
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           # 移入回收站（可恢复，默认行为）
python3 zotero.py delete KEY1 --permanent --yes    # 永久删除

交叉引用引文

python3 zotero.py crossref my-paper.txt

从文本中提取 Author (Year) 类型模式，并在文献库中匹配对应条目。

查找缺失的 DOI

# 试运行（默认）——仅显示匹配结果，不写入任何变更
python3 zotero.py find-dois --limit 20

# 实际向 Zotero 写入 DOI
python3 zotero.py find-dois --apply

# 按文集过滤
python3 zotero.py find-dois --collection COLLKEY --apply

扫描缺失 DOI 的 journalArticle 和 conferencePaper 条目，调用 CrossRef 查询，并依据以下条件匹配：标题相似度 >85%、年份完全一致、第一作者姓氏完全一致。默认为试运行模式，需显式指定 --apply 才会写入；仅更新 DOI 字段，不修改其他元数据。CrossRef 请求之间有 1 秒延迟（配合礼貌请求池的 mailto 配置）。

获取开放获取 PDF

# 试运行 — 显示哪些 PDF 可获取及其来源
python3 zotero.py fetch-pdfs --dry-run --limit 10

# 获取并作为链接型附件添加（不占用 Zotero 存储配额）
python3 zotero.py fetch-pdfs --limit 20

# 同时将 PDF 保存至本地目录
python3 zotero.py fetch-pdfs --download-dir ./pdfs

# 上传至 Zotero 存储（而非仅添加链接）
python3 zotero.py fetch-pdfs --upload --limit 10

# 仅尝试指定来源
python3 zotero.py fetch-pdfs --sources unpaywall,semanticscholar

按顺序尝试三个合法的开放获取来源：Unpaywall → Semantic Scholar → DOI 内容协商（Content Negotiation）。默认创建链接型附件（不消耗 Zotero 存储配额）；使用 --upload 可将 PDF 完整上传至 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'

注意事项（Notes）

• 零依赖 —— 仅使用 Python 3 标准库（urllib、json、argparse）
• 写入操作需具备写权限的 API 密钥
• 若 Zotero 翻译服务器不可用（返回 HTTP 503），DOI 查询将自动回退至 CrossRef
• 输入校验： DOI 必须符合 10.xxxx/... 格式；条目 Key 为 8 位字母数字组合（例如 VNPN6FHT）；ISBN 必须通过校验和验证。
• check-pdfs 会拉取全部条目；对于大型文献库（500+ 条），该操作可能较慢
• fetch-pdfs 同样遍历全部条目；大型文献库建议配合 --collection 限定范围
• 速率限制较为宽松；batch-add 已内置每项之间 1 秒的延迟
• 常见错误与排障方法详见 references/troubleshooting.md