scientific-agent-skills 项目中的 Pyzotero CLI 实战指南：在 Zotero 7 本地库上完成搜索、全文检索与文献管理

scientific-agent-skills 项目中的 Pyzotero CLI 实战指南：在 Zotero 7 本地库上完成搜索、全文检索与文献管理

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

Pyzotero 是 Python 生态中封装 Zotero API v3 的经典客户端。在 scientific-agent-skills 仓库的 pyzotero 技能中，除了面向远程 Web API 的 Python 客户端外，还随附了一个可选的命令行接口（CLI）。本指南以 CLI 参考文档为主体，完整讲解该 CLI 的安装、配置、搜索、单条文献读取、集合与标签管理、全文检索、DOI 索引等全部命令，并结合仓库中配套的 SKILL.md、认证文档、全文检索文档与 MCP 文档进行源码级佐证。读完本文，你将能直接用一行命令对本地 Zotero 资料库执行标题/元数据搜索、PDF 全文搜索、按条目类型与标签过滤、导出 JSON 供脚本或 Agent 消费，并理解它与 Web API、MCP 三种访问方式的适用边界。

与 Web API 的本质区别：连接的是本地 Zotero 7

Pyzotero 的 CLI 并不走远程 Web API，而是直连你本机的Zotero 7 桌面应用：

• 它需要 Zotero 桌面版正在运行；
• 需要在 Zotero 中开启本地 API 访问，路径为：Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero；
• 无需 Zotero API Key 与 Library ID 凭证，天然适合没有密钥的脚本环境与沙箱化 Agent。

这一点在仓库中有多处印证：SKILL.md的 compatibility 字段写明“Optional CLI and MCP extras require Zotero 7 with local API access enabled”，而 authentication.md 的 Local Mode 一节也强调本地模式“仅支持读请求”（read-only）。因此 CLI 适合做快速本地检索与管道处理，而不是远程库同步或批量写入。

三种访问方式的官方定位（来自 mcp.md）如下：

安装与免安装运行

CLI 以 pyzotero 的 extras 形式发布，推荐用uv管理：

# 作为项目依赖安装（会同时安装 CLI 入口） uv add "pyzotero[cli]" # 或者完全不安装，直接用 uvx 临时运行 uvx --from "pyzotero[cli]" pyzotero search -q "your query"

uvx --from模式适合一次性任务或 CI 管道，免去污染全局环境的顾虑。仓库 SKILL.md 的 Installation 一节也给出了同一套 extras 体系：

uv add pyzotero # Web API 客户端（远程 API） uv add "pyzotero[cli]" # + 本地 CLI（需要 Zotero 7） uv add "pyzotero[mcp]" # + MCP 服务器（供 LLM 客户端使用，也需要 Zotero 7）

搜索（search）命令：从标题元数据到 PDF 全文

search是 CLI 最核心的子命令。默认情况下，它只检索顶层条目的标题与元数据字段；加上--fulltext后会把检索范围扩展到PDF 全文内容（由本地 Zotero 索引提供）。

# 1) 搜索标题和元数据 pyzotero search -q "machine learning" # 2) 全文搜索（包含 PDF 内容） pyzotero search -q "climate change" --fulltext # 3) 按条目类型过滤（可重复，OR 逻辑） pyzotero search -q "methodology" --itemtype journalArticle --itemtype book # 4) 按标签过滤（可重复，AND 逻辑） pyzotero search -q "evolution" --tag "reviewed" --tag "high-priority" # 5) 在指定集合内搜索 pyzotero search --collection ABC123 -q "test" # 6) 分页 pyzotero search -q "deep learning" --limit 20 --offset 40 # 7) 输出为 JSON（便于机器处理 / 管道） pyzotero search -q "protein" --json

参数与过滤逻辑的深层语义

• --itemtype可重复出现，多值之间为 OR（并集）逻辑；对应 Web API 侧，search-params.md 中itemType='journalArticle || book'的搜索语法表达的是同一种语义。
• --tag可重复出现，多值之间为 AND（交集）逻辑，即条目必须同时拥有全部指定标签；这与 API 中tag=['climate', 'adaptation']的行为一致。若需要 OR 语义，API 侧可用tag='climate OR adaptation'表达，而排除某个标签用tag='-retracted'。
• --fulltext命中时返回的是父级书目条目（parent bibliographic items），而非原始附件（raw attachments）。也就是说，你在全文里搜到某篇 PDF 里的关键词，返回的是这篇文章的元数据条目，而不是那个附件对象——这样可以直接拿到完整书目信息。这与 full-text.md 中“CLI 提供对本地索引 PDF 的全文搜索”的描述以及 API 侧qmode='everything'的搜索行为互为印证。
• --limit/--offset用于分页。API 侧对应的参数是limit（1–100，None表示默认）与start（结果集偏移），CLI 沿用同一套语义。

搜索行为速查（官方原文要点）

• 默认搜索只覆盖顶层条目的标题与元数据字段；
• --fulltext扩展到 PDF 内容，结果显示父级书目条目（非原始附件）；
• 多个--tag使用 AND 逻辑；
• 多个--itemtype使用 OR 逻辑。

读取单条与批量条目：item / children / subset

当搜索命中或你知道条目 key 时，可以直接按 key 读取：

# 获取单个条目 pyzotero item ABC123 # 输出为 JSON pyzotero item ABC123 --json # 获取子条目（附件、笔记） pyzotero children ABC123 --json # 一次获取多个条目（最多 50 个） pyzotero subset ABC123 DEF456 GHI789 --json

• children对应 Read API 中的zot.children('PARENTKEY')，用于取回某条目的附件与笔记等子条目；
• subset的“最多 50 个”上限与 Web API 的itemKey参数限制一致（见 search-params.md：comma-separated item keys, up to 50；read-api.md 中zot.get_subset([...])同样限制 50）。API 侧超过批量上限会抛TooManyRequests/TooManyItems之类的异常，详见 error-handling.md。

集合与标签：listcollections / tags

# 列出所有集合 pyzotero listcollections # 列出库中全部标签 pyzotero tags # 列出指定集合内的标签 pyzotero tags --collection ABC123

对应到 Python 客户端，分别是zot.collections()、zot.tags()与zot.collection_tags('ABC123')（见 read-api.md 与 collections.md）。--collection限定范围后，可以快速掌握某个专题集合打标概况，配合搜索的--collection参数形成“先看集合 → 再集合内检索”的完整工作流。

全文内容读取：fulltext

# 获取某附件的全文内容 pyzotero fulltext ABC123

该命令对应 Python 侧的zot.fulltext_item('ATTACHMENTKEY')。根据 full-text.md，返回结构形如：

{ "content": "Full text of the document...", "indexedPages": 50, "totalPages": 50 }

其中文本类文档会用indexedChars/totalChars代替页数字段。CLI 输出时同样会给出全文文本。注意：这里传入的 key 应是附件条目的 key（即某个 PDF 附件），而非其父级书目条目的 key。

条目类型枚举：itemtypes

# 列出所有可用条目类型 pyzotero itemtypes

Zotero 的条目类型非常丰富。参考 search-params.md 中的完整枚举，包括但不限于：journalArticle、book、bookSection、conferencePaper、thesis、report、dataset、preprint、note、attachment、webpage、patent、statute、case、hearing、interview、letter、manuscript、map、artwork、audioRecording、videoRecording、podcast、film、radioBroadcast、tvBroadcast、presentation、encyclopediaArticle、dictionaryEntry、forumPost、blogPost、instantMessage、email、document、computerProgram、bill、newspaperArticle、magazineArticle。在--itemtype过滤时，传入的值应与这里列出的名称完全一致。

DOI 索引：doiindex

# 获取完整的 DOI → key 映射（适合缓存） pyzotero doiindex > doi_cache.json # 返回 JSON 形如： # {"10.1038/s41592-024-02233-6": {"key": "ABC123", "doi": "..."}}

doiindex一次输出库中全部条目的 DOI 到条目 key 的映射，适合构建本地缓存：之后你可以仅凭 DOI 快速反查条目 key，再配合item/subset命令批量拉取元数据，避免重复全文搜索，大幅降低本地索引的查询开销。

输出格式：人类可读文本 vs JSON

• 默认输出为人类可读文本，包含标题、作者、日期、出版物、卷期、DOI、URL 以及 PDF 附件路径等字段——适合直接阅读或在终端里快速浏览结果；
• 加--json输出结构化 JSON，适合jq或 Python 脚本等管道消费。例如：

# 将搜索结果交给 jq 提取标题 pyzotero search -q "CRISPR" --json | jq -r '.[].title' # 构建 DOI 缓存 pyzotero doiindex > doi_cache.json

这与 pyzotero 整体“dict 即数据”的设计一致：API 侧条目数据都存放在item['data']中（见 read-api.md），JSON 输出让 CLI 与 Python 客户端可以无缝衔接——CLI 的 JSON 结果几乎可以直接喂给后续脚本处理。

与 Python 客户端 / MCP 的协同工作流

CLI 并非孤立存在，它与 pyzotero 的另外两条访问路径互补：

1. 本地 Python 只读模式（authentication.md）：Zotero(library_id='436', library_type='user', local=True)可在 Python 中直接读本地库，但仅支持读请求，且能力不如 CLI 丰富；
2. MCP 服务器（mcp.md）：uvx --from "pyzotero[mcp]" pyzotero-mcp把本地库搜索、get_item、get_children、list_collections、list_tags、get_fulltext等能力封装成 MCP 工具，供 Claude Desktop 等 LLM 客户端调用——CLI 的子命令集合与 MCP 工具集基本一一对应，说明这套命令设计是面向 Agent/LLM 场景统一规划的。

在 scientific-agent-skills 仓库中，pyzotero 技能被定位为“检索、创建、更新、删除条目、集合、标签与附件、导出引文、构建科研自动化工作流”的一体化能力（见 SKILL.md 的 description）。CLI 在其中承担的是“免密钥、免写代码、可脚本化”的快速检索入口。

局限与前提

使用 CLI 前请确认以下前提，避免踩坑：

• 必须运行 Zotero 7 桌面应用，并在 Settings → Advanced 中勾选“Allow other applications on this computer to communicate with Zotero”，否则 CLI 无法连接；
• CLI 面向本地库的读操作与检索，批量写入、群组库管理仍应使用 Web API 客户端（需要ZOTERO_API_KEY/ZOTERO_LIBRARY_ID环境变量，参见 authentication.md）；
• 若库规模很大，建议结合--limit/--offset分页或先用doiindex建立缓存，控制单次输出体量；
• 全文搜索依赖 Zotero 本地已经完成的全文索引，首次使用或刚导入大量 PDF 时索引可能尚未就绪。

至此，你已经掌握了 pyzotero CLI 的全部子命令、参数语义与底层对应关系：从search的过滤逻辑、item/children/subset的单条与批量读取，到listcollections/tags/fulltext/itemtypes/doiindex的辅助能力，再到 JSON 输出与 MCP/Web API 的协同方式。将这套命令写进 Shell 脚本或 Agent 工作流，即可在不触碰远程 API、不需要任何密钥的前提下，对本地 Zotero 知识库完成高效检索与元数据提取。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills