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-skillsPyzotero 是 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 7Pyzotero 的 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如下模式访问对象API Key最佳适用场景Web APIZotero(...)远程库同步必需自动化、批量 CRUD、群组库CLIpyzotero[cli]本地 Zotero 7不需要Shell 脚本、快速本地搜索MCPpyzotero[mcp]本地 Zotero 7不需要沙箱应用中的 LLM Agent安装与免安装运行CLI 以 pyzotero 的 extras 形式发布推荐用uv管理# 作为项目依赖安装会同时安装 CLI 入口 uv add pyzotero[cli] # 或者完全不安装直接用 uvx 临时运行 uvx --from pyzotero[cli] pyzotero search -q your queryuvx --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 中itemTypejournalArticle || book的搜索语法表达的是同一种语义。--tag可重复出现多值之间为 AND交集逻辑即条目必须同时拥有全部指定标签这与 API 中tag[climate, adaptation]的行为一致。若需要 OR 语义API 侧可用tagclimate OR adaptation表达而排除某个标签用tag-retracted。--fulltext命中时返回的是父级书目条目parent bibliographic items而非原始附件raw attachments。也就是说你在全文里搜到某篇 PDF 里的关键词返回的是这篇文章的元数据条目而不是那个附件对象——这样可以直接拿到完整书目信息。这与 full-text.md 中“CLI 提供对本地索引 PDF 的全文搜索”的描述以及 API 侧qmodeeverything的搜索行为互为印证。--limit/--offset用于分页。API 侧对应的参数是limit1–100None表示默认与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 --jsonchildren对应 Read API 中的zot.children(PARENTKEY)用于取回某条目的附件与笔记等子条目subset的“最多 50 个”上限与 Web API 的itemKey参数限制一致见 search-params.mdcomma-separated item keys, up to 50read-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 itemtypesZotero 的条目类型非常丰富。参考 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.mdJSON 输出让 CLI 与 Python 客户端可以无缝衔接——CLI 的 JSON 结果几乎可以直接喂给后续脚本处理。与 Python 客户端 / MCP 的协同工作流CLI 并非孤立存在它与 pyzotero 的另外两条访问路径互补本地 Python 只读模式authentication.mdZotero(library_id436, library_typeuser, localTrue)可在 Python 中直接读本地库但仅支持读请求且能力不如 CLI 丰富MCP 服务器mcp.mduvx --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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考