pyzotero

pyzotero 技能概览

pyzotero 的作用

pyzotero 是面向 Zotero Web API v3 的 Python 客户端。pyzotero 技能可以帮助你无需手工拼接 API 调用，就能读写 Zotero 的条目、分类、标签、附件以及引文导出内容。

适合谁使用

它最适合做自动化参考文献管理、文献工作流，或类似 Zoterosync 的文库维护的人——尤其适合 Academic Research 场景下使用 pyzotero、脚本化整理参考文献，以及需要稳定 Zotero 集成的研究管线。

为什么值得安装这个技能

pyzotero 技能的核心价值，是把 Zotero 变成一个可编程的文献库后端。它不是一次性的 prompt，而是一套可重复执行的方法：你可以查询元数据、管理个人库或群组库、获取附件，并导出多种引文格式，而且出错的 API 调用会更少。

如何使用 pyzotero 技能

安装 pyzotero

直接安装 Python 包即可；只有在你需要搜索本地运行的 Zotero 桌面端时，才额外安装 CLI 依赖：

uv add pyzotero
uv add "pyzotero[cli]"

如果你是在评估 pyzotero 的安装方案，那么 CLI 只有在你想搜索本地正在运行的 Zotero 应用时才有用；纯远程 API 操作不需要它。

先提供正确的输入

一个高质量的 pyzotero 使用请求，应该包含：

• 文库类型：user 或 group
• 操作类型：read、create、update、delete、export 或 search
• 目标对象：item key、collection key、tag、attachment 或 saved search
• 输出格式：Python objects、JSON、BibTeX、CSL-JSON 或 HTML citations

示例 prompt 结构：

Use pyzotero to list items in my group library, filter to journal articles tagged reviewed, and export the results as CSL-JSON.

按这个顺序读取文件

为了更实用地完成设置，先读 SKILL.md，再按任务匹配下面这些定向参考文件：

• references/authentication.md：API key、user ID 和 local mode
• references/read-api.md 和 references/search-params.md：检索与过滤
• references/write-api.md：create/update/delete 工作流
• references/files-attachments.md 和 references/full-text.md：PDF 和索引
• references/exports.md：BibTeX、CSL-JSON 和引文输出
• references/error-handling.md：rate limits、冲突和无效字段

更好用 pyzotero 的实用工作流

1. 先确认你需要的是远程 API 访问，还是仅本地搜索。
2. 在调用方法前，先为正确的文库设置凭据。
3. 先做一次读操作测试，再扩展到批量操作。
4. 更新和删除时用 key，不要用标题。
5. 尽早加上分页或输出限制，这样结果才真正可用。

pyzotero 技能常见问题

pyzotero 只是给程序员用的吗？

不是。它在 Python 工作流里最有用，但只要你能完成简单安装并传入结构化输入，对非专业用户来说也不难上手。如果你只是偶尔需要手动导出引文，普通的 Zotero prompt 可能更省事。

pyzotero 同时支持个人库和群组库吗？

支持。pyzotero 技能两者都支持，但单个 Zotero 实例只绑定一个文库。这一点在你需要在个人库和共享的实验室或团队文库之间切换时尤其重要。

什么时候不该用 pyzotero？

如果你只想在 Zotero 里快速做一次性的引文格式化，或者你需要不依赖本地 Zotero 桌面端的全文搜索，就不该用 pyzotero。CLI 依赖本地 Zotero；而 API 并不提供同样的本地全文搜索行为。

pyzotero 适合 Academic Research 吗？

适合，尤其适合批量文献管理、参考文献清理、附件处理和可复现导出。如果你的任务主要是读论文，而不是整理或转换 Zotero 数据，它的帮助就没那么大。

如何改进 pyzotero 技能

把缺失的文库信息一次给全

最大的质量提升，来自一开始就把文库上下文说清楚。对于 pyzotero，要写明 library ID、这是 user 还是 group，以及你想用 local mode 还是远程 API。没有这些信息，输出往往会过于泛化，或者走错访问路径。

明确你想要的数据形状

直接说明你要的是单个 item、item 列表、collection tree、attachment metadata，还是导出文件。好的 pyzotero 输入看起来像这样：

• “只返回 keys 和 titles”
• “更新这些 item keys 的 abstractNote”
• “把前 50 条结果导出为 BibTeX”
• “找出全文里包含 gene editing 的 PDF”

注意常见失败模式

pyzotero 最常见的错误，是用标题代替 key、跳过认证配置，以及一次性批量写入太多内容。另一个常见问题，是误以为只靠 API 就能获得本地全文搜索。如果结果不对，先检查查询到底应该用条目元数据、全文，还是 collection 过滤条件。

在第一轮之后继续迭代

如果第一次输出范围太大，就通过补充 item type、tag 逻辑、collection key 或日期范围来收窄。如果第一次写入或更新风险较高，可以让 pyzotero 先 dry-run payload，或者在真正应用变更前先展示准确的 item fields。这是把 pyzotero 用到真实研究工作流里最快的改进方式。