zotio

Zotero 的信任与自动化层

文档： 开始使用 · 命令 · MCP 服务 · 安全写入 · 工作流

zotio 为人类、脚本和 MCP Agent 提供本地优先的搜索与审计、预览优先的写入，以及带有来源标记且范围受限的 Zotero 知识库上下文。

**快速验证：**先检查捆绑的知识库，再尝试对自己的数据使用 zotio。

brew install orgmentem/tap/zotio        # or grab a signed binary from Releases
zotio demo                              # bundled library: 34 classic papers, one genuinely retracted
ZOTIO_DEMO=1 zotio --data-source local items retract-check  # check every DOI against Retraction Watch data

KEY         STATUS      TYPE        NOTICE DOI                     DATE        SOURCE            TITLE
WAKEFLD98   correction  correction  10.1016/s0140-6736(04)15715-2  2004-03-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
WAKEFLD98   retracted   retraction  10.1016/s0140-6736(10)60175-4  2010-02-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
FAIR002016  correction  addendum    10.1038/s41597-019-0009-6      2019-03-19  publisher         The FAIR Guiding Principles for Scientific Da...
Checked 21 DOI-bearing items; 3 update notices flagged; 2 DOI(s) not registered with CrossRef.

这段演示展示了捆绑的知识库如何检测出已撤稿的 Wakefield 1998 年 MMR 论文，无需安装 Zotero，也无需 API 密钥（检查时会实时查询 Crossref）。 zotio demo --reset 会删除并重新填充演示知识库，将其恢复到原始状态。若要移除它，请删除演示报告中以 db_path 打印出的路径所对应的 demo.db 文件。

打开条目时，Zotero 本身也会根据同一份 Retraction Watch 数据，将已撤稿条目标记为红色警示。zotio 在桌面应用之外还提供了这些功能：检测更正和关注声明、生成可供脚本使用的整库报告，以及提供能让 CI 判定失败的退出代码。

将它指向你的真实知识库：

zotio init                                         # guided setup: detect Zotero, key, first sync, health check
zotio items retract-check                          # the same check, against your real library
zotio library health --for citation --fail-on high # fit to cite? (exit 11 if not)
zotio items bibcheck thesis.tex --fail-on-unknown  # every \cite{} resolves? (exit 11 if not)

为什么选择 zotio

Zotero 的图形界面非常适合阅读和引用。但当你需要大规模操作文献库时，就会非常棘手：找出所有缺少 PDF 的文章，在投稿前发现重复的 \cite{} 键，导出一周的高亮内容，让 Obsidian 库保持同步，或为 AI Agent 提供可信的上下文。现有的命令行工具和 pyzotero 只提供原始 API 访问能力，之后你还得自己编写衔接代码，并承担相应风险。

zotio 提供了这套衔接能力，并具备以下特性：

• 读取在本地完成。 将 zotio 指向正在运行的桌面应用：无需 API 密钥，也不会往返云端；还可以离线对已同步的镜像进行操作。
• 写入前先预览。 每次修改都会先显示计划，然后才会实际执行。安全阈值可以限制影响范围；不可逆操作需要明确选择启用；仅追加的日志可用于撤销可逆操作。
• 上下文有界且带有来源标记。 每条结果都会说明其来源和新鲜度，让人或 Agent 知道是否可信。zotio 绝不会调用大模型；它会整理上下文并控制其预算，然后将上下文交给模型。

当图形界面操作起来过于繁琐时，就该使用它：找出会影响后续工作的隐患，安全地修复它们，经审核后导入内容，并为 Agent 提供值得信赖的操作界面。

工作原理

读取始终在本机完成。写入方式根据操作意图而定：创建新条目（及其附件/PDF）时优先使用本地桌面连接器（localhost:23119，无需密钥——与浏览器中的“保存到 Zotero”按钮使用同一通道）；而字段编辑、删除、丰富数据、标签操作、移动，以及 collections 创建/更新则通过 Zotero Web API 处理，需要配置密钥。连接器路径是一种优先选项：只有在个人文献库且桌面应用正在运行时，--via auto 才会使用连接器，否则会回退到 Web API（群组文献库始终通过云端处理）。对于现有条目的 attachments add，--via connector 会明确指定桌面路径，但仍需要 Web API 密钥才能将文件移动到目标位置。写入前先预览；应用更改时，条目更新会从 Web 写入目标读取其版本。受支持的已应用更改会更新现有本地镜像，因此后续读取无需再次同步即可看到更改。

随时运行 zotio doctor，即可查看连接状态、缓存新鲜度，以及说明写回是否可用或当前为只读模式的 writes: 行。

旗舰功能：library health

用一条命令回答一个实际问题——“这个文献库适合我接下来要做的事吗？”——取代六项独立审计。

library health 将现有检查（citekey 冲突、重复项、缺失元数据、标签漂移、损坏的附件）整合为一份按优先级排序、带有问题类型的报告。你可以通过 --for 选择“就绪”的定义：

$ zotio library health --for quick
Health: needs attention
Scope: library · 846 top-level items (2103 mirrored rows) · source local · synced 1d ago · preset quick

High (13)
  [duplicate_candidates] doi="10.1002/bdm.2118" (2 items)
  [duplicate_candidates] title="Social psychology" (3 items)
  ... 11 more

Skipped (precondition unmet)
  broken_attachment_file — live check (needs Zotero desktop running); off by default.
    Fix: zotio library health --for quick --verify-files

Remediation plan (preview-first)
  duplicate_candidates — zotio items duplicates resolve --doi (preview first; add --yes after review)

以下三个特性使它适合用作门禁：

• 可拦截 CI。 如果未达到要求，--fail-on critical|high|info|any|none 会以 11 退出——可将它加入提交前钩子。若本地镜像已过期，--require-fresh 24h 会以 12 退出。
• 报告无法检查的内容。 需要桌面应用的检查（损坏的附件）会显示为醒目的跳过提示，并提供解决办法。如果该跳过项会影响门禁，运行会以 9 退出（需要设置），而不是通过。
• 指向真正的修复工具。 问题会包含 recommended_action，指出确切的现有命令（items enrich、items duplicates resolve、tags audit fix）。library health 报告问题；指定的命令负责修复问题。

为你的参考文献列表设置 CI

--badge 会将任何健康检查结果渲染为 shields.io 端点 JSON 工件——healthy 显示绿色，有问题时显示黄色，门禁失败时显示红色，setup required 显示橙色：

# .github/workflows/bibliography.yml (excerpt)
- run: zotio sync
- run: zotio library health --for citation --fail-on high --badge > badge.json
  # exit 11 fails the job when the bar isn't met; badge.json says why
# publish badge.json anywhere shields can reach (gh-pages, gist, artifact host), then:
#   https://img.shields.io/endpoint?url=https://<you>.github.io/<repo>/badge.json

你的论文或综述仓库会获得一个实时的 bibliography | healthy 徽章——一旦出现 citekey 冲突或重复项，构建就会失败。添加 --check-retractions，将门禁扩展到已撤稿论文（Crossref 的 Retraction Watch 数据）；再用 zotio items bibcheck paper.tex --fail-on-unknown 检查手稿本身。zotio-action 将这一流程打包在一起——安装、同步、设置门禁，并与基线进行差异比较，从而只在出现新问题时失败（指南）。

查看实际运行效果：zotio 自己的文档部署会从维护者实际使用的 Zotero 文献库生成并发布一个实时徽章（工作流，指南）。

默认安全：写入引擎

变更信封写入——items enrich、tags audit fix、items duplicates resolve、items preprint-check fix、items create/update/move/delete/add-to-collection、collections create/update/delete/move 和 import apply——共用一种计划和结果格式。

• 默认先预览。 你会得到一个零变更的计划／结果信封。--yes 会应用变更；--dry-run 始终优先。
• 预览会预测应用结果。 它会执行相同的读取，并评估与 --yes 相同的门槛（--max-changes、--allow-destructive、本地输入检查）。如果应用会拒绝某个预览，该预览会输出 ok:false 和 error:{code,message}，并以应用时会使用的代码退出。只有使用 --allow-destructive 时，破坏性预览才会显示 ok:true；预览和应用遇到冲突时都会以 1 退出。
• --dry-run 完全不会写入。 不会写入 Zotero，不会创建本地文件或 .lock 同级文件，不会保存配置，也不会回写镜像。仍会执行读取，且 --deliver 仍会路由命令的输出。sync、watch 和 init 不支持预览，使用 --dry-run 时会以退出码 2 拒绝执行。
• --agent 不会自动应用变更。 Agent 模式会设置 JSON 和非交互式默认值，但写入仍需显式指定 --yes。
• 门槛会限制影响范围。 --max-changes 默认为 500（--agent 下为 50）；不可逆操作（合并、永久删除、删除集合、creators rename、creators audit fix、vault resolve --keep-vault|--keep-remote）未指定 --allow-destructive 时会拒绝执行。
• 读取时可见自己的写入。 支持变更信封的写入在应用时会更新已有的本地镜像；后续读取镜像无需再次执行 sync，即可看到变更。
• 记录日志且可撤销。 每次已应用的变更信封运行都会以只追加方式记录（journal list / journal show）。journal undo <run-id> 会撤销可逆操作（标签重命名、集合成员变更、items enrich 写入 DOI／摘要／引文相关字段／标签——同时也会从 Extra 中移除来源信息行；以及创建操作，撤销时会将新建条目移入废纸篓；items delete 移入废纸篓和 items restore 运行则通过反向切换来撤销），并会明确拒绝处理其余操作（合并、永久删除、其他字段覆盖），而不是猜测如何撤销。Vault 写入使用相同的 --yes 审批门槛，但有单独的逐笔记报告，且不会写入日志。
• 本地状态命令。 会销毁本地状态的命令默认先预览，使用 --yes 应用：auth logout 和 profile delete。只会创建本地状态的命令则直接应用：auth set-token 和 profile save。

导入而不弄乱库

通过审核检查点批量导入参考文献。只有在你审核并（如有需要）编辑清单后，import apply 才会写入。

zotio import scan ~/Downloads/papers          # read-only: triage new vs duplicate vs attach-candidate
zotio import resolve ~/Downloads/papers > manifest.json   # resolve DOIs → editable manifest
#   ... review and edit manifest.json ...
zotio import apply manifest.json --dry-run     # preview the writes
zotio import apply manifest.json --yes         # schema-valid creation via the Web API

• 扫描会将一个文件夹中的 PDF 与现有文库进行比对分类——从文件名或 PDF 字节中提取 DOI——因此不会重复导入已有条目。
• 解析会将扫描结果转换为可编辑的 JSON 清单，并通过 CrossRef 补全待创建条目的信息。这是人工审核环节。
• 应用会创建符合架构的条目，默认先预览，并明确遵循 --attach-mode none|linked-file|stored 契约。stored 会上传文件字节：--via connector 会在同一个会话中将条目及其文件交给 Zotero 桌面端，而直接使用 Web API 的路径则受文件存储前置条件保护（可使用 --allow-zotero-cloud 覆盖）。

resolve 会通过 DOI 获取元数据（使用 CrossRef；对于预印本 PDF，还会执行 arXiv 到 DOI 的查询）；它不会解析 PMID 或 ISBN。一次性导入器可直接接收这些标识符：import doi|pmid|arxiv|isbn|url|file|pdf。使用 --to 指定目标集合键。

无冲突保险的知识库往返同步

让 Obsidian 或 Logseq 知识库与 Zotero 双向保持同步——绝不覆盖你的文字。

zotio vault sync              # preview: shows the notes it would write
zotio vault sync --yes        # Zotero → one Markdown note per item (idempotent)
zotio vault push --dry-run    # your ## Notes region → a managed Zotero child note
zotio vault pull --dry-run    # remote note edits → your ## Notes region (fast-forward only)

每条笔记都有一个受管理区域（frontmatter，以及标题、摘要和批注的围栏区块，每次同步都会刷新）和一个你的区域（## Notes，其中的文字原样保留）。回写仅支持快进：如果两边都有更改，zotio 绝不会盲目合并，而是会在 _vault-zotero-conflicts/ 下写入可供审阅的冲突文件并报告冲突，让你主动处理分歧（vault resolve --keep-vault | --keep-remote | --recreate），而不是悄悄覆盖。执行 vault audit，可在任何推送前进行只读预检查。

在 ~/.config/zotio/config.toml 中配置一次知识库（--vault 标志可覆盖此配置）：

[vault]
root = "~/Vaults/dev"    # ~ is expanded; base output dir
notes_dir = "Zotero"     # notes land in <root>/<notes_dir>
format = "obsidian"      # or "logseq"

GUI 和 pyzotero 无法提供的更多功能

文献库整理、完整性与分析

• items retract-check — 使用 Crossref 的 Retraction Watch 数据检查每个 DOI：包括撤稿、关注声明和更正，以及相关通知的 DOI 和日期。使用 --check-retractions 将其纳入 library health 检查门槛。（此功能会访问网络。）
• collections gaps — 引文图谱缺口分析：找出你的文献库缺失但被你的文集引用次数最多的论文，并按引用次数排序（OpenCitations + Semantic Scholar），然后用 import doi 导入。（也会访问网络。）
• items bibcheck <manuscript> — 从 .tex 或 pandoc Markdown 中解析 \cite{}/@citekey，或读取 .docx 和 .odt 文件中的 Zotero 引文字段，并在你的文献库中解析每个键——标记未知键和有歧义的键；如果某个未知键有足够接近的匹配项，还会附上文献库中最接近的键作为建议，让单字符拼写错误得到明确的修正建议，而不必手动搜索 .bib。--fail-on-unknown 会为 CI 返回退出码 11。--check-retractions 还会通过 CrossRef（网络）查询每篇引用文献的 DOI，并在引用行报告撤稿（严重）和关注声明（高）。查询失败时会报告为已跳过，并在使用 --fail-on 时返回退出码 9。
• tags audit — 按大小写或变体差异对标签分组，并显示条目数和可直接运行的合并命令。在一个实际包含 840 个标签的文献库中，一次运行就发现了 53 组重复标签。
• library stats — 一条命令即可查看仪表板：按类型和年份统计条目、热门出版平台、PDF 覆盖率，以及使用 --added-by month|year 查看可选的导入时间分组。
• items audit — 统计并列出缺少 PDF、摘要、DOI、标签或引文核心字段的条目；--verify-files 会检查 PDF 是否确实存在于磁盘上。
• items duplicates — 按 DOI 或标题检测可能重复的条目（不包括附件和笔记），然后用 duplicates resolve 安全合并。
• items citekey-conflicts — 在 Better BibTeX 键导致 LaTeX 构建失败前，找出缺失或重复的键。
• items find — 在导入重复条目之前，通过 DOI、ISBN、PMID、arXiv ID、引文键、URL、OpenAlex 作品 ID 或精确标题，在本地镜像中查找条目。标题匹配不受大小写、空格、引号和破折号样式或末尾句点影响，因此从参考文献列表粘贴的标题也能找到对应条目。如果所有查询条件均无匹配项，会单独列出文献库中最接近的标题或键及其评分，因此可以区分拼写错误和文献缺失；这些只是待确认的建议，并非匹配结果。各选择条件采用 OR 逻辑，因此如果一次查询通过其他条件找到匹配项，就不会为未匹配的条件报告近似结果。

阅读与综合

• items summarize — 为某个条目或条目集合整理一个有字数上限、可供综合分析的资料包（引文 + 摘要 + 你的注释 + 有长度上限的全文摘录 + 已知元数据缺失项 + 综合分析提示词），并交给任意大模型。zotio 负责控制字数，不会调用模型。使用 --focus "TERMS" 提出问题后，每个条目会改为附上与问题匹配的排序后 PDF 文本段落和注释，并提供条目和附件的键；--max-chars 限制段落长度，--max-annotations 限制注释数量——这样，第 30 页上的发现就能排在引言之前。若条目没有已同步的 PDF 文本，会明确说明，而不会报告“没有匹配项”。
• annotations export · annotations timeline · annotations search — 将高亮和笔记导出为 Markdown 或 JSON（annotations export --output|-o 会写入文件），可按日期排序或按文本搜索。
• reading-list — 使用 to-read 标签队列，通过 add → start → done 生命周期来筛选接下来要读的内容。
• items note-template — 为条目生成预填内容的 Obsidian/Logseq 阅读笔记。
• items open — 打印或打开指向条目、集合或 PDF 的 zotero:// 深层链接（跨平台）。
• library wrapped — 你的 Zotero 年度回顾：核心统计、带高峰高亮的月度节奏、类型构成比例条、亮点（最忙的一天、最长连续记录、冷门发现、注释最多的论文、热门标签）、热门发表平台和作者全名、PDF 覆盖情况——还可通过 --card-style overview|rhythm|picks|cycle 生成四种布局的可分享 SVG 卡片（下方卡片采用 cycle 布局，在全部三种布局间交叉淡入淡出）：

信息补全（读取外部 API，写入 Zotero）

• items enrich — 从 CrossRef → OpenAlex → Semantic Scholar 补全缺失的 DOI 和摘要；从 CrossRef 补全缺失的引文字段；从 Unpaywall 添加开放获取 PDF；并在每个条目的 Extra 字段中记录来源信息。--missing-citation 仅补全条目类型支持的空白字段，包括由数据提供方支持的卷、期和页码。--missing-mesh 会将 PubMed MeSH 描述词作为自动生成的 mesh/<descriptor> 标签，为具有 PMID 或 PubMed 可识别的 DOI 的条目提供建议；默认仅预览，若 PubMed 服务中断则报告错误。--validate 会报告与 CrossRef 数据相比的标题、年份和渲染字段差异，以及 OpenCitations 中的 DOI 注册失败情况，不会写入任何内容。
• items preprint-check — 查找现已拥有已发表 CrossRef 记录的 arXiv 预印本；preprint-check fix 会使用期刊 DOI 升级这些条目——先预览、记录操作日志，且绝不会覆盖冲突的 DOI。

导出与可复现性

• items bibliography — 使用 CSL 样式呈现共享范围，或将其导出为 CSL-JSON、BibTeX、BibLaTeX 或 RIS。CSL-JSON 使用唯一的 Better BibTeX 引用键，供 Pandoc 和 Quarto 使用。--manuscript paper.tex（或使用 Zotero 插件编写的 .docx/.odt）只导出文稿中引用的条目——对于导出格式，按首次引用顺序排列；而使用 CSL 呈现的 bib 则按其样式排序——遇到未知或有歧义的引用键时会拒绝执行（退出码为 11）。--scope 接受使用 AND 连接的群组，例如 collection:KEY AND tag:NAME。
• collections export — 将整个集合及其所有子集合导出为一个 BibTeX、RIS 或 CSL-JSON 文件。递归纳入该子树中的条目；文件不包含集合层级信息。
• export snapshot — 以可复现、可恢复且完整分页的方式导出（默认使用 JSONL；--format bibtex|ris|csljson），并生成 <output>.manifest.json 内容清单（经排序的 key+version + sha256），用于检测变动并便于干净地移交审阅。

新鲜度与架构

• sync · watch · tail — 填充镜像、通过定期增量同步保持最新，或实时流式传输变更。watch --health 会在各轮之间对比 library health，并将新发现报告到标准输出或 webhook——变动出现的当轮即可获知。添加 --health-check-preprints，还可监控库中的 arXiv 预印本：预印本新增已发表记录后，会作为 preprint_published 发现报告一次。结果会按 --health-preprint-recheck 缓存（默认 7d，至少 1h）；提供方失败时会记录为跳过，绝不会视为一切正常。
• schema drift — Zotero 升级后，根据已保存的基线检测条目类型、字段和创作者字段的变更。

为 Agent 构建

zotio 会发布机器可读的信任模型，让 MCP 主机、CI 任务或 Shell 脚本在采取行动之前发现哪些操作安全、数据是否新鲜，以及哪些内容可写。

• --agent：任何命令都可使用此标志，启用 JSON、紧凑输出、非交互模式且不使用颜色。（它不会自动应用写入。）在 --json/--agent 模式下，类型化错误会在标准输出上打印一个扁平的 JSON 对象 {kind, code, message, hint?}；失败的变更会保留其 ok:false 信封；若 which 未找到匹配项，则打印 {"matches":[]} 并以状态码 2 退出。
• capabilities — 完整的命令注册表，每条命令都标有 operation、data_sources、write_target、destructive 和 requires 前置条件。具有多条写入路径的命令还会列出每条路径的目标和前置条件。
• agent-context — 对整个 CLI 的结构化描述，其中包含命令注册表和发现提示、exit_codes 表、仅列出一次（不按命令重复列出）的 global_flags，以及解释三态 mcp:read-only 注解的 annotation_semantics。
• which "<capability in your words>" — 将自然语言查询解析为执行相应操作的命令。
• 稳定的信封 — 所有命令共用一种变更计划/结果结构、一种发现项结构和一份退出码契约。

范围语法 — 读取、审计、导出、补全和全文搜索共用一套选择语法（search QUERY --fulltext --scope collection:KEY 会在指定集合内进行排序和限制）：

collection:KEY   tag:NAME   query:TEXT   item:KEY   saved-search:KEY
<arm> AND <arm>   # intersection, e.g. collection:KEY AND tag:NAME

使用 AND（大写字母，两侧各有一个空格）连接多个条件，只选择匹配每个条件的项目，例如 zotio items enrich --missing-doi --scope 'collection:ABCD1234 AND tag:include'。文本只会在 AND 后面跟着另一个条件时拆分，因此 query:trust AND safety 会保留为一个查询。library 不能作为交集中的条件（退出码 2）。如果无法评估已保存搜索条件，则会以退出码 9 拒绝执行，而不会将其视为空结果。

Zotero 桌面应用在响应时会评估 saved-search:KEY。当桌面应用不可访问或拒绝本地 API 访问时，zotio 会根据本地镜像评估已同步的搜索定义，并打印一行 notice:；--data-source live 会关闭回退。本地评估器支持文本字段、创建者、标签、集合、条目类型和日期条件，并支持任一/全部条件组合及子条目标志。若搜索使用任何其他条件（全文、笔记、嵌套搜索），则会以退出码 9 退出并指出该条件。

退出码（同一张表也位于 SKILL.md 和 agent-context --json 的 exit_codes 中）：

显式指定 --help 时，退出码为 0。

安装

zotio 由三个可独立安装的部分组成：CLI（引擎——所有操作都通过它运行）、Agent 技能（在编码 Agent 中驱动 CLI）和 MCP 服务（向 Claude Desktop 等 MCP 主机公开 CLI）。大多数人只需要 CLI；可以根据所选 Agent 添加技能或 MCP 服务。

1. CLI — zotio

Homebrew（macOS）：

brew install orgmentem/tap/zotio

这会同时安装 zotio 和 zotio-mcp MCP 服务；brew upgrade 会跟进新版本。

**Linux（deb / rpm / apk）：**没有 apt/dnf/pacman 软件源——软件包是 GitHub release 附件。使用 dpkg -i、rpm -i 或 apk add --allow-untrusted 安装；安装指南提供了一段命令，可解析最新版本和你的架构。

**Windows（WinGet / Scoop）：**运行 winget install OrgMentem.zotio，或运行 scoop bucket add orgmentem https://github.com/OrgMentem/scoop-bucket && scoop install zotio。 两者都会安装 zotio 和 zotio-mcp。Microsoft 合并版本更新期间，WinGet 可能会在发布后短暂提供旧版本；Scoop 则会立即更新。

**预编译二进制文件：**每个 GitHub release 都提供适用于 macOS、Linux 和 Windows（amd64/arm64）的压缩包，其中包含由 cosign 签名的校验和与 SBOM。解压后将 zotio 放到 PATH 中；在 macOS 上清除 Gatekeeper 隔离标记（xattr -d com.apple.quarantine zotio），在 Unix 上运行 chmod +x zotio。

从源代码构建：

git clone https://github.com/OrgMentem/zotio && cd zotio && go build -o zotio ./cmd/zotio

然后让 CLI 引导你完成设置——检测 Zotero、启用本地 API、选择性添加 Web API 密钥、首次同步以及运行健康检查：

zotio init

2. Agent 技能

这是一项专用技能，随本仓库一同提供，文件为 SKILL.md。它会教会编码 Agent 直接驱动 CLI（这是最高效的方式；中间无需 MCP 服务）。

推荐 — skills CLI（适用于 Claude Code、Cursor、Codex、Cline、opencode 及 40 多种 Agent）：

npx skills add OrgMentem/zotio          # detect your agents and install
npx skills add OrgMentem/zotio --list   # preview without installing
npx skills add OrgMentem/zotio -g       # install globally (all projects)

手动安装：

• **Claude Code：**将 SKILL.md 复制到 ~/.claude/skills/zotio/SKILL.md（或项目的 .claude/skills/zotio/）。
• **其他任意 Agent：**将其指向原始文件 — https://raw.githubusercontent.com/OrgMentem/zotio/main/SKILL.md — 或将文件内容粘贴到 Agent 的技能库中。

3. MCP 服务 — zotio-mcp

zotio-mcp 与 CLI 一同发布——macOS Homebrew cask 和每个发行版压缩包都包含这两个二进制文件。注册它：

# Claude Code
claude mcp add zotero zotio-mcp -e ZOTERO_API_KEY=<your-key>

对于 Claude Desktop，每个发行版都提供适用于各平台的 MCPB 捆绑包 — 下载适用于你平台的 .mcpb 文件，双击打开，Claude Desktop 会引导你完成安装。

{
  "mcpServers": {
    "zotero": {
      "command": "zotio-mcp",
      "env": { "ZOTERO_API_KEY": "<your-key>" }
    }
  }
}

对于只读的本地桌面使用，ZOTERO_API_KEY 是可选的（本地 API 无需密钥）；设置该变量即可启用写入操作并访问群组文库。

身份验证

读取会访问 localhost:23119 上的 Zotero 桌面应用；只要 Zotero 正在运行，就无需 API 密钥。首先在 Zotero 中启用本地 API：Settings → Advanced → "Allow other applications to communicate with Zotero."

通过本地桌面连接器创建新的个人库条目并同时保存其附件，可以不使用密钥。即使使用 --via connector，对现有条目执行 attachments add 也需要 Web API 密钥：该路径会通过 Web API 将新附件移至目标位置。

编辑写入（items update/delete/move、items enrich、tags 修改、vault push/pull/resolve、大多数 import apply 操作）会通过 Zotero Web API 执行，需要密钥。配置一次即可：

printf %s "$ZOTERO_API_KEY" | zotio auth set-token --stdin     # or export ZOTERO_API_KEY=<key>

请前往 https://www.zotero.org/settings/keys 生成密钥。首次执行 Web API 写入时，会在 stderr 输出一条一次性提示，说明目标位置。远程 Web API 读取（包括群组库）也需要密钥。受支持的 --data-source local 读取使用同步镜像，无需桌面应用或密钥。运行 zotio doctor，查看 writes: 行，了解是否支持写回。

使用

直接使用 CLI

# 1. Verify Zotero is running and reachable
zotio doctor

# 2. Sync your library to local SQLite for offline search + analytics
zotio sync

# 3. See the shape of your library
zotio library stats

# 4. Certify it for a citation handoff (exit 11 if it fails the bar)
zotio library health --for citation --fail-on high

# 5. Search offline
zotio search 'automation trust' --fulltext --data-source local --json

# 6. Export annotations since a date as JSON for synthesis
zotio annotations timeline --since 2026-05-01 --json > since-may.json

在编码 Agent 中使用 skill

按照上文安装后，在 Claude Code 中调用 /zotio <query>。该 skill 会直接驱动 CLI，这是最高效的方式，无需 MCP 服务介入。

在 Agent 宿主中使用 MCP 服务

按照上文注册后，MCP 服务会提供一个命令编排接口（command_search / command_run），而非每个端点对应一个工具；Agent 可以像人类一样发现命令并驱动 CLI（参见 dev/adr/0001-mcp-command-surface.md；通过 ZOTIO_MCP_SURFACE 切换接口）。写入本地文件的命令支持 --dry-run，并提供 annotations search。工具提示来自能力注册表：只有破坏性命令和本地文件写入命令的 destructiveHint 才为 true；仅读取本地镜像的命令会报告 openWorldHint: false。它还通过资源提供 Zotero 上下文：zotero://context、zotero://agent-context、zotero://status、zotero://schema、zotero://freshness、zotero://health/{scope}、zotero://capabilities 和有界图谱资源（collections/{key}/tree、items/{key}/children|attachments|context）；此外还提供引导式提示词（prepare-library-health、prepare-import、sync-vault-safely、inspect-library、export-reading-notes、prepare-citation-export、synthesize）。

输出格式

zotio collections list                       # human table (JSON when piped)
zotio collections list --json                # JSON for scripting and agents
zotio collections list --json --select key,data.name   # only the fields you need
zotio collections list --dry-run             # no write of any kind; reads like this one still run
zotio collections list --agent               # JSON + compact + non-interactive + no color

此外还支持：--csv、--plain（不支持表格形式的命令会以退出码 2 拒绝这两种格式）、--quiet（不输出任何内容；退出码即为结果）、--compact 和 --deliver stdout|file:<path>|webhook:<url>。即使在 --dry-run 模式下，--deliver 也会路由命令输出。若 --select 指定的字段不在输出中，则以退出码 2 退出。

健康检查与故障排除

zotio doctor            # config, credentials, connectivity, cache freshness, writability
zotio desktop status    # is Zotero desktop running, and does its connector accept imports?

• doctor: connection refused — 打开 Zotero 桌面应用，并启用 Settings → Advanced → "Allow other applications to communicate with Zotero."
• items missing-pdf / analytics / 任何镜像读取命令以退出码 9 失败 — 本地镜像尚未同步。请先运行 zotio sync；synced_store 前置条件说明会提示这一点。
• annotations export 输出空白章节 — PDF 批注必须在 Zotero 内置 PDF 阅读器中创建，不能使用外部应用。
• citekey-conflicts 未找到任何键 — 请安装 Better BibTeX 扩展；引文键位于 extra 字段中。
• 身份验证错误（退出码 4） — 运行 zotio doctor 检查凭据；验证 echo $ZOTERO_API_KEY。

配置

配置文件：~/.config/zotio/config.toml。可在 [headers] 下设置静态请求标头；按命令设置的覆盖项优先级更高。

命令参考

运行 zotio --help 查看完整命令列表，或运行 zotio <command> --help 查看任意子命令的帮助。当你知道目标但不知道该用哪个命令时，可以直接向 CLI 询问：

zotio which "export bibtex for a collection"

兄弟项目：papio

zotio 用于管理和保护你的 Zotero 文库。papio 负责获取内容：它通过你平时使用的浏览器，从开放获取资源和你所在机构的订阅中查找并下载经过验证、带有来源追踪信息的 PDF，然后交由 zotio 进行预览优先的导入。如果你的文库中有条目没有 PDF，papio 就能为它们补上。

来源与灵感

通过研究以下项目和资源构建：

• cli-anything-zotero — TypeScript
• 54yyyu/zotero-mcp — Python
• pyzotero — Python
• kujenba/zotero-mcp — Python
• jbaiter/zotero-cli — Python
• dhondta/zotero-cli — Python
• Combjellyshen/ZoteroBridge — TypeScript
• RaulSimpetru/zotero-library-mcp — Python
• introfini/mcp-server-zotero-dev — TypeScript
• piiinpiiins/zotero-mcp-local — Python
• mcp-for-zotero — 托管服务

基于 MIT 许可协议授权。

Zotero 是 数字学术公司 的注册商标。zotio 是一个独立项目，与 Zotero 或数字学术公司无关联，也未获得其认可。