名称： zotero
描述： 通过 Web API 管理 Zotero 文献库。支持搜索、列表、通过 DOI/ISBN/PMID 添加条目（含查重检测）、删除/移至回收站、更新元数据和标签、以 BibTeX/RIS/CSL-JSON 格式导出、从文件批量添加、检查 PDF 附件、交叉引用引文、通过 CrossRef 查找缺失的 DOI、获取开放获取 PDF。支持 --json 输出以便脚本处理。适用于用户询问学术参考文献、引文管理、文献库、论文 PDF、参考文献导出或 Zotero 相关操作。
元数据： {"clawdbot":{"emoji":"📚","requires":{"env":["ZOTERO_API_KEY","ZOTERO_USER_ID"]},"primaryEnv":"ZOTERO_API_KEY"}}

Zotero 技能

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

设置

需要设置两个环境变量：

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

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

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

CROSSREF_EMAIL   — 您的邮箱（可选；未设置时使用备用方案）

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

CLI 脚本

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

python3 scripts/zotero.py <命令> [选项]

命令

全局标志

• --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 "标签1,标签2" — 创建条目时添加标签
• --force — 添加命令时跳过重复检测

工作流程

通过 DOI 添加论文

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "综述"
# 如果已在库中会发出警告。使用 `--force` 覆盖。

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

从文件批量添加

# 每行一个标识符，# 开头为注释
python3 zotero.py batch-add dois.txt --type doi --tags "已导入"

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

导出参考文献

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

更新标签/元数据

python3 zotero.py update ITEMKEY --add-tags "重要" --remove-tags "未读"
python3 zotero.py update ITEMKEY --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

从文本中提取 作者 (年份) 模式并与文献库匹配。

查找缺失的 DOI

# 试运行（默认）— 显示匹配项但不写入任何内容
python3 zotero.py find-dois --limit 20

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

# 按收藏夹筛选
python3 zotero.py find-dois --collection COLLKEY --apply

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

获取开放获取 PDF

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

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

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

# 上传到 Zotero 存储而非链接 URL
python3 zotero.py fetch-pdfs --upload --limit 10

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

按顺序尝试三个合法的 OA 来源：Unpaywall → Semantic Scholar → DOI 内容协商。默认创建链接 URL 附件（无需 Zotero 存储配额）。使用 --upload 将 PDF 完整上传到 Zotero 存储。使用 --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 位字母数字（例如 VNPN6FHT）。ISBN 必须具有有效的校验和。
• check-pdfs 会获取所有条目；对于大型文献库（500+ 条目），可能较慢
• fetch-pdfs 也会处理所有条目 — 对于大型文献库，请使用 --collection 限定范围
• 速率限制较为宽松；批量添加在条目之间有 1 秒延迟
• 常见错误及故障排除，请参阅 references/troubleshooting.md