介绍
# Zotero Skill
通过 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，零外部依赖）。
```bash python3 scripts/zotero.py <command> [options] ```
### 命令
| 命令 | 描述 | 示例 | |---------|-------------|---------| | `items` | 列出顶层条目 | `zotero.py items --limit 50` | | `search` | 按查询搜索 | `zotero.py search "cognitive load"` | | `get` | 获取完整条目详情 + 附件 | `zotero.py get ITEMKEY` | | `collections` | 列出所有合集 | `zotero.py collections` | | `tags` | 列出所有标签 | `zotero.py tags` | | `children` | 列出条目的附件/笔记 | `zotero.py children ITEMKEY` | | `add-doi` | 通过 DOI 添加条目（启用去重） | `zotero.py add-doi 10.1234/example` | | `add-isbn` | 通过 ISBN 添加条目（启用去重） | `zotero.py add-isbn 978-0-123456-78-9` | | `add-pmid` | 通过 PubMed ID 添加条目 | `zotero.py add-pmid 12345678` | | `delete` | 将条目移至回收站（默认可恢复） | `zotero.py delete KEY1 KEY2 --yes` | | `update` | 修改条目元数据/标签 | `zotero.py update KEY --add-tags "new"` | | `export` | 导出为 BibTeX/RIS/CSL-JSON | `zotero.py export --format bibtex` | | `batch-add` | 从文件批量添加条目 | `zotero.py batch-add dois.txt --type doi` | | `check-pdfs` | 报告哪些条目拥有/缺少 PDF | `zotero.py check-pdfs` | | `crossref` | 将引文与库进行匹配 | `zotero.py crossref bibliography.txt` | | `find-dois` | 通过 CrossRef 查找并添加缺失的 DOI | `zotero.py find-dois --limit 10` | | `fetch-pdfs` | 为条目获取开放获取 PDF | `zotero.py fetch-pdfs --dry-run` |
### 全局标志
- `--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 添加论文
```bash python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review" # Warns if already in library. Use --force to override. ```
重复检测：将 DOI 转换为元数据，按第一作者搜索库，比较 DOI 字段。
### 从文件批量添加
```bash # One identifier per line, # for comments python3 zotero.py batch-add dois.txt --type doi --tags "imported" ```
跳过重复项。报告摘要：已添加/已跳过/已失败。
### 导出参考文献
```bash python3 zotero.py export --format bibtex --output refs.bib python3 zotero.py export --format csljson --collection COLLKEY ```
### 更新标签/元数据
```bash 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 ```
### 删除条目
```bash python3 zotero.py delete KEY1 KEY2 --yes # Trash (recoverable, default) python3 zotero.py delete KEY1 --permanent --yes # Permanent delete ```
### 交叉验证引文
```bash python3 zotero.py crossref my-paper.txt ```
从文本中提取 `Author (Year)` 模式并与库匹配。
### 查找缺失的 DOI
```bash # 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 的 journalArticle 和 conferencePaper 条目，查询 CrossRef，并通过标题相似度（>85%）、年份精确匹配和第一作者姓氏进行匹配。默认为试运行——使用 `--apply` 写入更改。仅修补 DOI 字段；绝不触碰其他元数据。CrossRef 请求之间有 1 秒延迟（使用 mailto 的礼善池）。
### 获取开放获取 PDF
```bash # 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 ```
按顺序尝试三个合法的 OA 来源：Unpaywall → Semantic Scholar → DOI 内容协商。默认创建链接 URL 附件（无需 Zotero 存储空间配额）。使用 `--upload` 将完整文件上传到 Zotero 存储。使用 `--download-dir` 同时在本地保存 PDF。
**来源：** `unpaywall`, `semanticscholar`, `doi`（默认：全部三个）
**速率限制：** Unpaywall/Semantic Scholar 请求之间间隔 1 秒，DOI 请求之间间隔 2 秒。
### 使用 JSON 进行脚本编写
```bash 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` 限制范围 - 速率限制很宽松；batch-add 在条目之间包含 1 秒延迟 - 有关常见错误和故障排除，请参阅 [references/troubleshooting.md](references/troubleshooting.md)