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-skillsZotero 是科研人员管理文献的核心工具而 pyzotero 是操作 Zotero API v3 的 Python 客户端。本文聚焦 pyzotero 的搜索与请求参数体系如何使用q、qmode、tag、itemType等参数精准检索文献如何设置排序与分页以及如何借助add_parameters()全局配置、导出格式参数和全文本检索在 scientific-agent-skills 仓库的 pyzotero 技能上下文中构建可复用的文献自动化工作流。读完本文你将掌握从一行查询到复杂过滤条件的完整参数语法并能与实际代码无缝衔接。参数的两种传递方式行内参数与全局参数pyzotero 的所有搜索参数既可以临时指定也可以设为全局默认。原文档 search-params.md 明确了两者的区别# 行内参数仅对当前这一次调用生效 results zot.items(qclimate change, limit50, sortdate, directiondesc) # 全局参数之后的所有调用默认生效行内参数会覆盖全局值 zot.add_parameters(limit50, sortdateAdded) results zot.items() # 使用全局 limit50、sortdateAdded关键行为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 支持的完整参数清单这是构造任意查询的语法字典参数类型说明qstr快速搜索——默认只匹配标题和创建者字段qmodestrtitleCreatorYear默认或everything全文本itemTypestr按条目类型过滤可配合搜索运算符tagstr 或 list按标签过滤多个标签为 AND 逻辑sinceint只返回该库版本之后修改过的对象sortstr排序字段见下方排序字段directionstrasc或desclimitint1–100或None表示不限制startint结果集的偏移量配合 limit 做分页formatstr响应格式详见 exports.mditemKeystr逗号分隔的条目 key最多 50 个contentstrbib、html、citation或某种导出格式stylestrCSL 引文样式名与contentbib配合使用linkwrapstr设为1时在书目输出的 URL 外包一层a标签其中几个参数值得单独展开qmodeeverything与全文本搜索默认的titleCreatorYear只检索标题、创建者和年份everything会进入 Zotero 的全文本索引。这在 full-text.md 中有更完整的说明——不仅可以通过 API 用zot.items(qprotein folding, qmodeeverything, limit20)搜索还可以用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 中的性能建议——对于上千条目的文库用sinceversion只取改动过的条目以及zot.last_modified_version()、zot.item_versions(since1000)等方法可以高效构建同步管线。format/content/style决定响应是 JSON 对象、BibTeX、CSL-JSON 还是格式化书目详见本文结合导出参数输出文献一节。排序字段Sort Fieldssort参数接受以下字段名direction决定升序asc还是降序descdateAdded、dateModified、title、creator、type、date、publisher、publicationTitle、journalAbbreviation、language、accessDate、libraryCatalog、callNumber、rights、addedBy、numItems、tags典型用法是按日期倒序获取最新文献zot.items(qCRISPR, sortdate, directiondesc, limit20)。注意sort与direction是相互配合的字段——仅设sort而忘记direction会得到默认的升序结果。标签搜索语法Tag Search Syntaxtag参数支持单标签、多标签 AND、OR 逻辑以及排除语法# 单个标签 zot.items(tagmachine learning) # 多个标签——AND 逻辑条目必须同时拥有所有标签 zot.items(tag[climate, adaptation]) # OR 逻辑条目拥有任一标签即可 zot.items(tagclimate OR adaptation) # 排除某个标签前面加负号 zot.items(tag-retracted)两种多标签写法传 Python list 表示 AND全都要有传单个字符串并用OR分隔表示并集。负号前缀-用于排除。这与 Zotero 桌面端的标签过滤逻辑一致适合筛选待读文献但剔除已撤稿条目这类场景。标签相关的更多操作如zot.tags()列出文库全部标签、zot.item_tags(ITEMKEY)查看单条目的标签见 read-api.md 与 tags.md。条目类型过滤Item Type FilteringitemType支持单类型、多类型 OR 与排除语法# 单一类型 zot.items(itemTypejournalArticle) # OR 多个类型用 || 分隔 zot.items(itemTypejournalArticle || 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 年后的 preprintzot.items(qprotein, itemTypepreprint, sortdate, directiondesc)。注意||是 OR 运算符与标签语法中的OR关键字不同使用时不要混淆。组合查询实战示例原文档给出了四组可直接运行的组合示例覆盖了关键词类型排序增量同步分页偏移全文本检索四种典型需求# 最近匹配查询的期刊论文按日期排序倒序 zot.items(qCRISPR, itemTypejournalArticle, sortdate, directiondesc, limit20) # 自某个已知库版本以来新增的条目 zot.items(since4000) # 带特定标签的条目用 start 做分页偏移 zot.items(tagto-read, limit25, start25) # 全文本搜索 zot.items(qgene editing, qmodeeverything, limit10)关于分页的补充limit上限为 100但 pyzotero 默认返回 100 条API 默认 25见 SKILL.md 的 Core Concepts。当结果超过一页时除了手动使用startlimit翻页pagination.md 给出了page_size循环写法更推荐以下内置迭代器# everything()自动取完所有结果会串行发出多次请求 all_results zot.everything(zot.items(qmachine learning, itemTypejournalArticle)) # follow()手动逐页推进耗尽时抛 StopIteration first_batch zot.top(limit25) second_batch zot.follow() # makeiter()把任何返回多条的调用包装成生成器 gen zot.makeiter(zot.top(limit25)) page1 next(gen)对上千条目的文库everything()会串行多次调用 API耗时较长此时优先用since做增量而不是全量拉取。结合导出参数输出文献搜索参数中的format、content、style、linkwrap决定了查询结果的呈现形态这一点与 exports.md 直接联动# BibTeX 导出formatbibtex 时返回 bibtexparser 的 BibDatabase 对象 zot.add_parameters(formatbibtex) bibtex_db zot.top(limit50) for entry in bibtex_db.entries: print(entry.get(title), entry.get(author)) # CSL-JSON 导出 zot.add_parameters(contentcsljson, limit50) csl_items zot.items() # APA 格式书目contentbib style zot.add_parameters(contentbib, styleapa) bib_entries zot.items(limit50) # 返回 HTML div 字符串列表 # 文内引用contentcitation zot.add_parameters(contentcitation, styleapa) citations zot.items(limit50) # 返回 HTML span 列表 # RIS 导出并写入文件 zot.add_parameters(contentris, limit50) ris_data zot.items() with open(library.ris, w, encodingutf-8) as f: f.write(\n.join(ris_data))可用的content导出格式还包括rdf_dcDublin Core RDF、rdf_zotero、biblatex、wikipedia维基百科引文模板等。两条硬性约束其一formatbib会移除limit参数API 强制单次最多 150 条其二以导出格式作为content时必须显式提供limit且不支持同时请求多种导出格式。style接受 Zotero 样式库中的任意 CSL 名称例如chicago-author-date、vancouver、ieee、nature等linkwrap1则会在书目输出的 URL 外套上a标签便于直接嵌入 HTML 页面。另外formatkeys和formatversions还提供了轻量级的键与版本提取方式# 只取条目 key换行分隔的字符串 zot.add_parameters(formatkeys) keys zot.items().strip().split(\n) # 取 {key: version} 版本字典用于同步判断 zot.add_parameters(formatversions) versions zot.items()搜索参数在科学文献工作流中的典型组合将本文的参数语法与 pyzotero 技能的其他能力read-api.md、saved-searches.md、write-api.md组合可以搭建完整的文献自动化管线。一个典型流程如下精确检索zot.items(qCRISPR gene editing, itemTypejournalArticle, tagpriority, qmodeeverything, sortdateAdded, directiondesc, limit100)——一次调用同时限定关键词、类型、标签与全文本检索。增量同步用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 是安全区间formatbib场景下上限变为 150且该格式会移除limit参数。分页偏移的代价start越大会导致 API 查询越慢长列表优先用everything()/follow()/makeiter()不要手动循环start。多标签语义list 传入 AND字符串OR 并集负号-用于排除三者语义不同。qmode的默认行为不传时只搜标题与创建者需要全文检索务必显式指定qmodeeverything。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的环境中运行构建属于自己的文献检索与科研自动化工作流。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考