zotio

zotio 是一款命令行工具和 MCP 服务器，定位为 Zotero 参考文献文库的信任与自动化层。它面向需要大规模操作文库而非通过桌面 GUI 的用户：查找缺失 PDF、在提交前发现重复引用键、导出标注、同步笔记知识库，或为 AI 代理提供有界上下文。 架构与数据访问 读取在本地进行：zotio 与 localhost 上运行的 Zotero 桌面 API 以及一个已同步的 SQLite 镜像通信，无需 API 密钥，并可针对已同步副本离线工作。写入按意图拆分。创建带附件的新条目时优先使用本地桌面连接器，也就是浏览器“Save to Zotero”按钮使用的同一通道；而字段编辑、删除、补全、标签操作、移动以及分类创建/更新则走 Zotero Web API，需要配置密钥。连接器路径被描述为一种偏好而非保证：自动路由仅在桌面运行且为个人文库时使用它，否则回退到 Web API；群组文库始终走云端。补全和导入引用的外部服务包括 CrossRef、OpenAlex、Semantic Scholar、Unpaywall 和 OpenCitations。doctor 命令报告连通性、缓存新鲜度以及回写是否可用。 写入安全 所有写入命令共享同一个变更信封。默认为预览；--yes 应用更改，--dry-run 始终优先。代理模式设置 JSON 和非交互默认值，但不会自动应用写入。门禁用于限制影响范围：--max-changes 默认为 500，代理模式下为 50；合并、永久删除和清空回收站等不可逆操作需要显式的 --allow-destructive 标志。已应用的写入会重放到本地镜像，因此后续读取无需再次同步即可看到更改。每次已应用运行都会记录到仅追加日志；journal undo 会撤销可逆操作，包括标签重命名、分类归属和创建，但拒绝合并、删除和字段覆盖。 文库健康与 CI 旗舰的文库健康命令将现有检查（citekey 冲突、重复、元数据缺失、标签漂移、附件损坏）组合成一份排序的、带发现类型的报告。--for 标志选择预设：quick、citation、systematic-review、vault 或 all。发现项带有 recommended_action，指明修复它们的命令。该命令支持用 --fail-on 进行 CI 门禁，未达标时退出码 11；--require-fresh 在镜像过时时退出码 12。需要桌面应用的检查会变成醒目跳过并给出补救措施，而不是静默消失；与门禁相关的跳过退出码为 9。--badge 选项渲染 shields.io 端点 JSON 工件。配套的 GitHub Action 将安装、同步、门禁和基线差异比较打包在一起。 其他能力 撤稿检查根据 Crossref 的 Retraction Watch 数据验证 DOI，涵盖撤稿、关切声明和更正。馆藏缺口分析对文库中缺失的高被引论文进行排序。书目检查解析 LaTeX 或 pandoc 引用，并标记未知或有歧义的键。标签审计将大小写和变体重复项分组，并提供可直接运行的合并命令。还包括文库统计、条目审计、重复检测和 citekey 冲突检测。阅读与综合功能包括用于交接给 LLM 的有界摘要包（zotio 本身不调用模型）、标注导出与搜索、阅读列表生命周期、笔记模板、深度链接，以及带可分享 SVG 卡片的年度回顾。补全功能从外部提供商填充缺失的 DOI、摘要和引用字段，并附加开放获取 PDF，同时在 Extra 字段记录来源。预印本检查将 arXiv 记录升级为已出版期刊 DOI。导出选项包括 CSL-JSON、BibTeX、BibLaTeX、RIS，以及带内容锁文件的可恢复 JSONL 快照。sync、watch 和 tail 保持镜像新鲜，schema drift 检测 Zotero 升级后的架构变更。 导入与知识库工作流 批量导入经过 scan、resolve 和 apply 阶段，以可编辑的 JSON 清单作为人工审查检查点。知识库同步使 Obsidian 或 Logseq 知识库与 Zotero 双向保持一致，使用受管区域和用户文字区域，采用仅快进式回写和可审查冲突产物，而非静默合并。 代理集成 --agent 标志提供 JSON、紧凑、非交互输出。capabilities 命令公开命令注册表，标注操作、数据源、写入目标、破坏性和前置条件。agent-context 命令描述 CLI，which 命令将自然语言查询解析为命令，变更信封和退出码被文档化为稳定契约。MCP 服务器二进制文件随 CLI 一同分发。 分发 在 macOS 和 Linux 上可通过 Homebrew 安装，GitHub release 包提供 deb、rpm 和 apk，在 Windows 上可通过 WinGet 或 Scoop 安装。CLI、代理技能和 MCP 服务器可独立安装。项目采用 MIT 许可，使用 Go 编写。