SuperAPI AI 工具集

pyzotero

写作与研究

查看项目

更新于 10-21 16:19

技能介绍

用途

pyzotero 是 Zotero API v3 的 Python 封装库,用于以编程方式管理 Zotero 文献库。它可以读取条目和分类、创建与更新参考文献、上传附件、管理标签,以及导出引文。当前上游版本为 pyzotero 1.13.0(PyPI,2026 年 5 月),官方文档位于 pyzotero.readthedocs.io。

认证设置

所需凭据可从 https://www.zotero.org/settings/keys 获取:

  • User ID:页面中显示为 "Your userID for use in API calls"
  • API Key:在 https://www.zotero.org/settings/keys/new 创建
  • Library ID:群组库为群组 URL 中 /groups/ 之后的整数

凭据可存入环境变量或 .env 文件:

ZOTERO_LIBRARY_ID=your_user_id
ZOTERO_API_KEY=your_api_key
ZOTERO_LIBRARY_TYPE=user  # or "group"

完整设置细节见 references/authentication.md。

安装

uv add pyzotero              # Web API client
uv add "pyzotero[cli]"       # + local CLI (Zotero 7)
uv add "pyzotero[mcp]"       # + MCP server for LLM clients (Zotero 7)

快速开始

import os
from pyzotero import Zotero

zot = Zotero(
    library_id=os.environ['ZOTERO_LIBRARY_ID'],
    library_type=os.environ.get('ZOTERO_LIBRARY_TYPE', 'user'),
    api_key=os.environ['ZOTERO_API_KEY'],
)

# Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10)
for item in items:
    print(item['data']['title'], item['data']['itemType'])

# Search by keyword
results = zot.items(q='machine learning', limit=20)

# Retrieve all items (use everything() for complete results)
all_items = zot.everything(zot.items())

核心概念

  • 一个 Zotero 实例绑定单个文献库(用户库或群组库),所有方法都作用于该库。
  • 条目数据位于 item['data'],可访问 item['data']['title']、item['data']['creators'] 等字段。
  • pyzotero 默认返回 100 条(API 默认 25 条)。使用 zot.everything(zot.items()) 获取全部条目。
  • 写入方法成功时返回 True,失败时抛出 ZoteroError。

参考文件

文件 内容
references/authentication.md 凭据、库类型、本地模式
references/read-api.md 获取条目、分类、标签、群组
references/search-params.md 过滤、排序、搜索参数
references/write-api.md 创建、更新、删除条目
references/collections.md 分类 CRUD 操作
references/tags.md 标签访问与管理
references/files-attachments.md 文件下载与附件上传
references/exports.md BibTeX、CSL-JSON、参考文献导出
references/pagination.md follow()、everything()、生成器
references/full-text.md 全文内容索引与访问
references/saved-searches.md 保存的搜索管理
references/cli.md 命令行界面(本地 Zotero 7)
references/mcp.md 面向 LLM 客户端的 MCP 服务器(本地 Zotero 7)
references/error-handling.md 错误与异常处理

常见模式

获取并修改条目:

item = zot.item('ITEMKEY')
item['data']['title'] = 'New Title'
zot.update_item(item)

从模板创建条目:

template = zot.item_template('journalArticle')
template['title'] = 'My Paper'
template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
zot.create_items([template])

导出为 BibTeX:

zot.add_parameters(format='bibtex')
bibtex = zot.top(limit=50)
# bibtex is a bibtexparser BibDatabase object
print(bibtex.entries)

本地模式(只读,无需 API Key):

zot = Zotero(library_id='123456', library_type='user', local=True)
items = zot.items()

本地 Zotero 7(CLI 或 MCP,无需 API Key)

如需搜索本地运行的 Zotero 桌面应用(包括 PDF 全文搜索),应使用 CLI 或 MCP 服务器而非 Web API。两者都要求 Zotero 7 并启用本地 API 访问。详见 references/cli.md 与 references/mcp.md。

智能体操作流程

  1. 检查环境:确认研究问题、数据库、日期范围和纳入标准。
  2. 明确输入:从数据或用户处确认格式、标识符和参数。对任何会改变结果的取值,应询问而非猜测。
  3. 先小规模运行:在单个数据库上用窄查询运行搜索,检查结果是否相关。
  4. 使用上述说明和参考文件执行完整任务。
  5. 验证结果:每条参考文献都来自具有可解析标识符的真实记录;记录计数和搜索字符串。
  6. 报告:说明运行了什么(版本、命令、参数)、检查了什么,以及仍不确定的内容。

异常处理:

情况 处理
API 限流或返回错误 退避重试、减小批量大小或切换数据库,并报告缺口
说明中的函数、标志或端点在已安装版本中缺失 查阅已安装版本自身的文档(help()、--help、官方文档),调整后告知用户。绝不臆造 API
必需输入、标识符或参数不明确 询问用户,或在运行前明确说明假设

完整性规则

  • 绝不编造结果、参数、标识符、引文或统计数据。无法运行或验证的内容应如实说明。
  • 绝不总结未获取的论文;绝不凭记忆引用。
  • 此处版本相关细节可能已过时:请对照已安装版本的官方文档确认。
  • 涉及花钱、消耗共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前,先征得同意。

相关技能

  • reference-manager-interop:在 Zotero、Mendeley、EndNote、JabRef、Paperpile 与写作工具(LaTeX/BibTeX、Word、Google Docs 等)之间迁移和同步文献库。
  • citation-management:搜索 OpenAlex、PubMed 和 Google Scholar,通过 CrossRef、PubMed 等从 DOI、PMID、PMCID、arXiv ID 和 URL 提取元数据。
  • literature-review:通过搜索 PubMed、arXiv、bioRxiv 和 Semantic Scholar(以及通过 parallel-cli 进行网络搜索)执行系统性文献综述与筛选。