zotero

Zotero API 技能

通过 Zotero 本地 HTTP 服务器（localhost:23119）和 REST API（api.zotero.org）执行文献管理操作。

前提条件

本地 API（仅在 Zotero 运行时可用）

Zotero 正在运行，并且已启用以下设置：

• Zotero > 首选项 > 高级 > 勾选「Allow other applications on this computer to communicate with Zotero」

连接检查：

curl -s http://localhost:23119/connector/ping

REST API（云端操作）

已设置环境变量：

• ZOTERO_API_KEY：API 密钥（在 https://www.zotero.org/settings/keys 创建）
• ZOTERO_USER_ID：用户 ID

连接检查：

curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" "https://api.zotero.org/keys/current"

命令

1. 批量导入 DOI（/zotero import）

/zotero import <DOI1> <DOI2> ...
/zotero import --file <doi_list.txt>
/zotero import --collection "コレクション名"

导入脚本：

bash ~/.claude/skills/zotero/scripts/zotero_import.sh --dois "10.1038/xxx,10.2196/yyy" [--collection "名前"]

处理流程：

1. 确认 Zotero 正在运行（/connector/ping）
2. 确定目标分类（未指定时使用当前选中的分类）
3. 对每个 DOI → 从 doi.org 获取 BibTeX（失败时回退到 CrossRef）
4. 向 /connector/import?session=<unique_id> 发送 POST 请求
5. 显示结果摘要

2. 手动导入 BibTeX（/zotero bibtex）

用于没有 DOI 的文献。直接导入 BibTeX 文件：

bash ~/.claude/skills/zotero/scripts/zotero_import.sh --bibtex /path/to/file.bib

DOI 不明时，通过 CrossRef API 搜索：

curl -s "https://api.crossref.org/works?query.bibliographic=著者名+キーワード&rows=5"

3. 分类列表（/zotero collections）

curl -s http://localhost:23119/api/users/0/collections | python3 -c "
import json, sys
for c in json.load(sys.stdin):
    d = c['data']
    print(f\"{d['key']}  {d['name']}\")"

4. 条目列表（/zotero list）

/zotero list                          # 現在選択中コレクション
/zotero list --collection "名前"      # 指定コレクション

5. 搜索条目（/zotero search）

/zotero search "AI psychosis"

REST API 操作

创建分类

curl -s -X POST \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/collections" \
  -d '[{"name": "コレクション名"}]'

更新分类

curl -s -X PUT \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/collections/COLLECTION_KEY" \
  -d '{"name": "新しい名前"}'

创建条目（每个请求最多 50 个）

curl -s -X POST \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
  -d '[{
    "itemType": "journalArticle",
    "title": "タイトル",
    "creators": [{"creatorType": "author", "firstName": "名", "lastName": "姓"}],
    "collections": ["COLLECTION_KEY"],
    "tags": [{"tag": "タグ名"}]
  }]'

部分更新条目（PATCH）

curl -s -X PATCH \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY" \
  -d '{"tags": [{"tag": "new-tag"}]}'

删除条目

curl -s -X DELETE \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY"

批量删除标签

curl -s -X DELETE \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "If-Unmodified-Since-Version: $VERSION" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/tags?tag=tag1+||+tag2"

群组文库

将所有端点中的 /users/<userID> 替换为 /groups/<groupID> 即可。

# 所属グループ一覧
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/groups"

搜索（REST API）

# キーワード検索
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items?q=keyword&qmode=titleCreatorYear"

# タグフィルタ（AND: 複数 tag、OR: || 区切り、NOT: - 接頭辞）
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  "https://api.zotero.org/users/$ZOTERO_USER_ID/items?tag=AI&tag=review"

API 概览

本地 API

端点	方法	用途
/connector/ping	GET/POST	确认是否正在运行
/connector/import?session=ID	POST	导入 BibTeX/RIS
/connector/getSelectedCollection	POST	获取当前选中的分类
/api/users/0/collections	GET	分类列表
/api/users/0/collections/:key/items	GET	条目列表
/api/users/0/items	GET	所有条目

REST API（api.zotero.org）

端点	方法	用途
/users/<id>/collections	GET/POST	分类列表/创建
/users/<id>/collections/<key>	PUT/DELETE	更新/删除分类
/users/<id>/items	GET/POST	条目列表/创建（最多 50 个）
/users/<id>/items/<key>	PUT/PATCH/DELETE	更新/删除条目
/users/<id>/tags	GET	标签列表
/users/<id>/tags?tag=...	DELETE	批量删除标签
/users/<id>/searches	GET/POST	已保存的搜索
/users/<id>/items/<key>/file	GET/POST/PATCH	附件
/users/<id>/groups	GET	群组列表
/groups/<id>/...	各种方法	群组操作

详情：references/api-endpoints.md

重要注意事项

本地 API

• 本地 API（/api/...） 仅支持 GET（只读）
• Connector API（/connector/...） 支持通过 POST 读写
• /connector/import 的 session 参数必须每次唯一（重复会导致 409 错误）
• 如果 BibTeX 中包含 Shell 特殊字符，请使用 --data-binary @file.bib 通过文件发送
• 导入的内容会保存到 Zotero UI 中当前选中的分类

REST API

• 身份验证：使用 Zotero-API-Key: <key> 请求头（推荐）
• 更新/删除时必须提供 If-Unmodified-Since-Version: <version>（未指定时返回 428）
• 批处理上限：每个请求最多 50 个
• 速率限制：依据 Backoff / 429 + Retry-After 处理
• 防止重复提交：使用 Zotero-Write-Token: <token> 请求头