技能介绍

要解决什么问题

Zotero 桌面端适合手工整理文献，但批量同步、与脚本/流水线对接、或从自有系统写入条目时，需要走 Zotero Web API v3。直接拼 HTTP 请求要处理认证、分页、条目 JSON 结构（含 creators、附件键等），维护成本不低。

技能如何工作

Pyzotero 把 API 封装成 Python 对象：实例绑定一个库（个人或群组），方法都针对该库执行。

读：条目、集合、标签、群组信息；可用搜索/过滤参数（见 references/search-params.md）；默认分页约 100 条，用 zot.everything(zot.items()) 拉全量。
写：创建/更新/删除条目；集合与标签管理；附件上传（references/files-attachments.md）。成功返回 True，失败抛出 ZoteroError。
导出：BibTeX、CSL-JSON 等（references/exports.md）。
本地只读：无需 API 密钥的本地模式，适合离线读库。

条目正文在 item['data'] 里，例如 item['data']['title']、item['data']['creators']。技能内 references/ 按主题拆分（认证、读/写 API、分页 follow()/everything()、全文索引、CLI、错误处理等），按任务查对应文档即可。

适用边界与注意点

写入与在线库操作依赖 用户 ID、API 密钥（及群组库的 库 ID），需按 references/authentication.md 配置环境变量或 .env。
大规模同步时注意 API 限流与分页，不要假设一次 items() 即全库。
本地模式能力以只读为主，不能替代需写回云端的自动化场景。