Pyzotero 搜索与请求参数完全指南：掌握 Zotero Web API 的过滤、排序与分页-育师

Pyzotero 搜索与请求参数完全指南：掌握 Zotero Web API 的过滤、排序与分页

【免费下载链接】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

Zotero 是科研人员管理文献的核心工具，而 pyzotero 是操作 Zotero API v3 的 Python 客户端。本文聚焦 pyzotero 的"搜索与请求参数"体系：如何使用q、qmode、tag、itemType等参数精准检索文献，如何设置排序与分页，以及如何借助add_parameters()全局配置、导出格式参数和全文本检索，在 scientific-agent-skills 仓库的 pyzotero 技能上下文中构建可复用的文献自动化工作流。读完本文，你将掌握从一行查询到复杂过滤条件的完整参数语法，并能与实际代码无缝衔接。

参数的两种传递方式：行内参数与全局参数

pyzotero 的所有搜索参数既可以临时指定，也可以设为全局默认。原文档 search-params.md 明确了两者的区别：

# 行内参数：仅对当前这一次调用生效 results = zot.items(q='climate change', limit=50, sort='date', direction='desc') # 全局参数：之后的所有调用默认生效，行内参数会覆盖全局值 zot.add_parameters(limit=50, sort='dateAdded') results = zot.items() # 使用全局 limit=50、sort='dateAdded'

关键行为：add_parameters()设置的参数会被持久保存，直到下一次调用中显式覆盖为止。文档特别指出"set globally (overridden by inline params on the next call)"——即下一调用中如果同时传入同名行内参数，行内参数优先。这一机制非常适合在脚本开头统一声明分页、排序或导出格式，然后在具体查询时只覆盖个别维度。

从 SKILL.md 可以看到该技能要求 Python 3.10+ 与 pyzotero 1.13+，并建议通过uv add pyzotero安装 Web API 客户端、uv add "pyzotero[cli]"或uv add "pyzotero[mcp]"获取本地 Zotero 7 的扩展能力。认证方面需要ZOTERO_API_KEY与ZOTERO_LIBRARY_ID环境变量，详见 authentication.md。

可用参数完整对照表

原文档给出了 pyzotero Read API 支持的完整参数清单，这是构造任意查询的"语法字典"：

参数	类型	说明
`q`	str	快速搜索——默认只匹配标题和创建者字段
`qmode`	str	`'titleCreatorYear'`（默认）或`'everything'`（全文本）
`itemType`	str	按条目类型过滤，可配合搜索运算符
`tag`	str 或 list	按标签过滤；多个标签为 AND 逻辑
`since`	int	只返回该库版本之后修改过的对象
`sort`	str	排序字段（见下方"排序字段"）
`direction`	str	`'asc'`或`'desc'`
`limit`	int	1–100，或`None`（表示不限制）
`start`	int	结果集的偏移量（配合 limit 做分页）
`format`	str	响应格式（详见 exports.md）
`itemKey`	str	逗号分隔的条目 key（最多 50 个）
`content`	str	`'bib'`、`'html'`、`'citation'`或某种导出格式
`style`	str	CSL 引文样式名（与`content='bib'`配合使用）
`linkwrap`	str	设为`'1'`时在书目输出的 URL 外包一层`<a>`标签

其中几个参数值得单独展开：

qmode='everything'与全文本搜索：默认的'titleCreatorYear'只检索标题、创建者和年份；'everything'会进入 Zotero 的全文本索引。这在 full-text.md 中有更完整的说明——不仅可以通过 API 用zot.items(q='protein folding', qmode='everything', limit=20)搜索，还可以用zot.fulltext_item('ATTACHMENTKEY')读取某个附件的已索引全文内容，或借助本地 CLI 的pyzotero search -q "CRISPR gene editing" --fulltext对本地 Zotero 7 的 PDF 全文进行检索。
itemKey：一次最多 50 个 key，等价于 Read API 中的批量获取能力。对应地，pyzotero 还提供了zot.get_subset(['KEY1', 'KEY2', 'KEY3'])方法（见 read-api.md）。
since：增量同步的基石。配合 pagination.md 中的性能建议——"对于上千条目的文库，用since=version只取改动过的条目"，以及zot.last_modified_version()、zot.item_versions(since=1000)等方法，可以高效构建同步管线。
format/content/style：决定响应是 JSON 对象、BibTeX、CSL-JSON 还是格式化书目，详见本文"结合导出参数输出文献"一节。

排序字段（Sort Fields）

sort参数接受以下字段名，direction决定升序（'asc'）还是降序（'desc'）：

dateAdded、dateModified、title、creator、type、date、publisher、publicationTitle、journalAbbreviation、language、accessDate、libraryCatalog、callNumber、rights、addedBy、numItems、tags

典型用法是"按日期倒序获取最新文献"：zot.items(q='CRISPR', sort='date', direction='desc', limit=20)。注意sort与direction是相互配合的字段——仅设sort而忘记direction，会得到默认的升序结果。

标签搜索语法（Tag Search Syntax）

tag参数支持单标签、多标签 AND、OR 逻辑以及排除语法：

# 单个标签 zot.items(tag='machine learning') # 多个标签——AND 逻辑（条目必须同时拥有所有标签） zot.items(tag=['climate', 'adaptation']) # OR 逻辑（条目拥有任一标签即可） zot.items(tag='climate OR adaptation') # 排除某个标签（前面加负号） zot.items(tag='-retracted')

两种多标签写法：传 Python list 表示 AND（全都要有）；传单个字符串并用OR分隔表示并集。负号前缀-用于排除。这与 Zotero 桌面端的标签过滤逻辑一致，适合"筛选待读文献但剔除已撤稿条目"这类场景。标签相关的更多操作（如zot.tags()列出文库全部标签、zot.item_tags('ITEMKEY')查看单条目的标签）见 read-api.md 与 tags.md。

条目类型过滤（Item Type Filtering）

itemType支持单类型、多类型 OR 与排除语法：

# 单一类型 zot.items(itemType='journalArticle') # OR 多个类型（用 || 分隔） zot.items(itemType='journalArticle || book') # 排除某个类型（负号前缀） zot.items(itemType='-note')

Zotero 的条目类型体系非常庞大，原文档完整列出如下常用类型：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常与q、tag、sort组合使用。例如"检索 2020 年后的 preprint"：zot.items(q='protein', itemType='preprint', sort='date', direction='desc')。注意||是 OR 运算符，与标签语法中的OR关键字不同，使用时不要混淆。

组合查询实战示例

原文档给出了四组可直接运行的组合示例，覆盖了"关键词+类型+排序""增量同步""分页偏移""全文本检索"四种典型需求：

# 最近匹配查询的期刊论文，按日期排序（倒序） zot.items(q='CRISPR', itemType='journalArticle', sort='date', direction='desc', limit=20) # 自某个已知库版本以来新增的条目 zot.items(since=4000) # 带特定标签的条目，用 start 做分页偏移 zot.items(tag='to-read', limit=25, start=25) # 全文本搜索 zot.items(q='gene editing', qmode='everything', limit=10)

关于分页的补充：limit上限为 100，但 pyzotero 默认返回 100 条（API 默认 25，见 SKILL.md 的 Core Concepts）。当结果超过一页时，除了手动使用start+limit翻页（pagination.md 给出了page_size循环写法），更推荐以下内置迭代器：

# everything()：自动取完所有结果（会串行发出多次请求） all_results = zot.everything(zot.items(q='machine learning', itemType='journalArticle')) # follow()：手动逐页推进，耗尽时抛 StopIteration first_batch = zot.top(limit=25) second_batch = zot.follow() # makeiter()：把任何返回多条的调用包装成生成器 gen = zot.makeiter(zot.top(limit=25)) page1 = next(gen)

对上千条目的文库，everything()会串行多次调用 API，耗时较长；此时优先用since做增量，而不是全量拉取。

结合导出参数输出文献

搜索参数中的format、content、style、linkwrap决定了查询结果的"呈现形态"，这一点与 exports.md 直接联动：

# BibTeX 导出（format='bibtex' 时返回 bibtexparser 的 BibDatabase 对象） zot.add_parameters(format='bibtex') bibtex_db = zot.top(limit=50) for entry in bibtex_db.entries: print(entry.get('title'), entry.get('author')) # CSL-JSON 导出 zot.add_parameters(content='csljson', limit=50) csl_items = zot.items() # APA 格式书目（content='bib' + style） zot.add_parameters(content='bib', style='apa') bib_entries = zot.items(limit=50) # 返回 HTML <div> 字符串列表 # 文内引用（content='citation'） zot.add_parameters(content='citation', style='apa') citations = zot.items(limit=50) # 返回 HTML <span> 列表 # RIS 导出并写入文件 zot.add_parameters(content='ris', limit=50) ris_data = zot.items() with open('library.ris', 'w', encoding='utf-8') as f: f.write('\n'.join(ris_data))

可用的content导出格式还包括rdf_dc（Dublin Core RDF）、rdf_zotero、biblatex、wikipedia（维基百科引文模板）等。两条硬性约束：其一，format='bib'会移除limit参数，API 强制单次最多 150 条；其二，以导出格式作为content时必须显式提供limit，且不支持同时请求多种导出格式。style接受 Zotero 样式库中的任意 CSL 名称，例如'chicago-author-date'、'vancouver'、'ieee'、'nature'等；linkwrap='1'则会在书目输出的 URL 外套上<a>标签，便于直接嵌入 HTML 页面。

另外，format='keys'和format='versions'还提供了轻量级的键与版本提取方式：

# 只取条目 key（换行分隔的字符串） zot.add_parameters(format='keys') keys = zot.items().strip().split('\n') # 取 {key: version} 版本字典，用于同步判断 zot.add_parameters(format='versions') versions = zot.items()

搜索参数在科学文献工作流中的典型组合

将本文的参数语法与 pyzotero 技能的其他能力（read-api.md、saved-searches.md、write-api.md）组合，可以搭建完整的文献自动化管线。一个典型流程如下：

精确检索：zot.items(q='CRISPR gene editing', itemType='journalArticle', tag='priority', qmode='everything', sort='dateAdded', direction='desc', limit=100)——一次调用同时限定关键词、类型、标签与全文本检索。
增量同步：用since只拉取新修改条目，配合zot.last_modified_version()记录检查点。
导出与入库：将命中结果以 BibTeX 或 RIS 格式导出，供 LaTeX 或 EndNote 使用。
反馈更新：通过zot.add_parameters()全局设置limit与sort，随后逐条处理并调用写接口更新状态（例如剔除已读标签）。

对于需要"保存复杂过滤条件"的场合，Zotero 还支持服务端保存搜索：zot.saved_search('ML Papers', conditions)可创建由多个条件（title contains、tag is、date isAfter等）组合的保存搜索，并用zot.show_operators()、zot.show_conditions()动态发现可用运算符——详见 saved-searches.md。

常见陷阱与最佳实践

结合 error-handling.md 与全技能文档，使用搜索参数时有几点值得注意：

limit的上限：API 层面 1–100 是安全区间；format='bib'场景下上限变为 150，且该格式会移除limit参数。
分页偏移的代价：start越大会导致 API 查询越慢，长列表优先用everything()/follow()/makeiter()，不要手动循环start。
多标签语义：list 传入 = AND，字符串OR= 并集；负号-用于排除，三者语义不同。
qmode的默认行为：不传时只搜标题与创建者，需要全文检索务必显式指定qmode='everything'。
since配合版本号：since接受的是 Zotero 库的 version 号（整数），可通过zot.last_modified_version()获取最新版本作为同步基准。

小结

pyzotero 的搜索参数系统以q/qmode/itemType/tag/since/sort/direction/limit/start为核心，配合add_parameters()的全局机制与format/content/style/linkwrap等输出控制参数，覆盖了从单次精确查询到大规模增量同步的完整需求。本文内容全部围绕 search-params.md 展开，并结合仓库中的 SKILL.md、read-api.md、exports.md、pagination.md、full-text.md、authentication.md 与 saved-searches.md 进行了源码级补充。读者可以直接将上述代码粘贴到配置好ZOTERO_LIBRARY_ID、ZOTERO_API_KEY的环境中运行，构建属于自己的文献检索与科研自动化工作流。