ZotPilot
AI-powered Zotero research assistant — MCP server + agent skill
Install / Use
/learn @xunhe730/ZotPilotREADME
这是什么
ZotPilot 是一个 MCP server，给你的 Zotero 文献库加上语义搜索、引用图谱查询和 AI 辅助整理功能。附带 Agent Skill 提供安装引导和使用指南。
具体来说，它在你本地的 Zotero 数据上建了一套向量索引，然后通过 MCP 协议暴露 32 个工具给 AI agent。AI 可以按意思搜论文（不是关键词匹配）、定位到具体章节段落、查谁引了谁、帮你打标签分类、读写笔记和批注。论文数据不离开你的电脑。支持 No-RAG 模式——不配置 embedding 也能使用元数据搜索、笔记、标签等基础功能。
为什么要做这个
写 Related Work 的时候，你记得读过一篇关于"睡眠纺锤波与记忆巩固"的研究，但在 Zotero 里搜不到。因为你记的是概念，Zotero 只匹配原文词汇。搜 "memory consolidation during sleep" 找不到写 "sleep spindle-dependent replay" 的论文，虽然说的是一回事。
除了搜索，还有几个问题 Zotero 解决不了：
- "哪些论文的 Results 里报告了 N400 效应？"——只能逐篇打开 PDF 翻
- 你知道某篇论文有个准确率对比表，但搜不到表格内容
- "谁引用了这篇？他们怎么评价？"——要手动去 Google Scholar 查
- 按主题给 200 篇论文打标签、分类到集合——纯体力活
快速开始
方式一：让 agent 帮你装
把这段话复制给你的 AI agent：
帮我安装 ZotPilot skill：clone https://github.com/xunhe730/ZotPilot.git 到我的 skills 目录，然后帮我配置 Zotero 文献库。
Agent 会 clone 仓库、装 CLI、配好 Zotero、注册 MCP 服务器。重启一次就能用。
Skills 目录（clone 目标）：
| 平台 | 目标路径 |
|------|----------|
| Claude Code | ~/.claude/skills/zotpilot |
| Codex CLI | ~/.agents/skills/zotpilot |
| OpenCode | ~/.config/opencode/skills/zotpilot |
| Gemini CLI | ~/.gemini/skills/zotpilot |
| Cursor | ~/.cursor/skills/zotpilot |
| Windsurf | ~/.codeium/windsurf/skills/zotpilot |
方式二：手动装
1. Clone 到 skills 目录（Tier 1 平台，有 Skill 支持）：
# Claude Code
git clone https://github.com/xunhe730/ZotPilot.git ~/.claude/skills/zotpilot
# Codex CLI
git clone https://github.com/xunhe730/ZotPilot.git ~/.agents/skills/zotpilot
# OpenCode
git clone https://github.com/xunhe730/ZotPilot.git ~/.config/opencode/skills/zotpilot
# Gemini CLI
git clone https://github.com/xunhe730/ZotPilot.git ~/.gemini/skills/zotpilot
# Cursor
git clone https://github.com/xunhe730/ZotPilot.git ~/.cursor/skills/zotpilot
# Windsurf
git clone https://github.com/xunhe730/ZotPilot.git ~/.codeium/windsurf/skills/zotpilot
2. 注册 MCP 服务器：
Windows 用户：将下方命令中的
python3替换为python
有两种方式传 API key 给 MCP 服务器：
方式 A（推荐）：设环境变量。 在 shell profile 里 export GEMINI_API_KEY=<key>，服务器启动时自动读取。key 不进 shell history，不写入配置文件。适合 Claude Code / Codex / Gemini CLI 等从终端启动的客户端。
方式 B（兼容性备选）：注册时通过 CLI 参数传入。 register 会把 key 写进 MCP 客户端配置文件，客户端启动时注入给服务器。所有 MCP 客户端都支持（包括 Cursor / Windsurf 等不继承 shell 环境变量的 IDE）。注意：key 会留在 shell history 和配置文件明文中。
# 推荐：先设环境变量，再注册
export GEMINI_API_KEY=<key>
python3 scripts/run.py register # Tier 1（源码安装）
zotpilot register # Tier 2（pip/uv 安装）
# 兼容性备选：通过 CLI 参数传 key（IDE 客户端可能需要）
python3 scripts/run.py register --gemini-key <key> # Tier 1
zotpilot register --gemini-key <key> # Tier 2
# 指定平台：
python3 scripts/run.py register --platform claude-code # 或: zotpilot register --platform claude-code
支持：Claude Code、Codex CLI、OpenCode、Gemini CLI、Cursor、Windsurf。
3. 重启你的 AI agent。
4.（可选）启用写操作 — 搜索和引用装好就能用，打标签、建集合需要 Zotero Web API 密钥：
- 打开 zotero.org/settings/keys
- 记下页面顶部的 数字 User ID（例如
12345678，不是用户名） - 点 "Create new private key"，勾上 "Allow library access" 和 "Allow write access"，复制 key
- 保存凭证（推荐：写入 config 文件，对所有 MCP 客户端生效）：
zotpilot config set zotero_user_id 12345678 # 数字 ID，不是用户名
zotpilot config set zotero_api_key YOUR_KEY
⚠️ Key 以明文存储在
~/.config/zotpilot/config.json（Windows:%APPDATA%\zotpilot\config.json）。 确保该目录不被 git 追踪。
验证配置：
zotpilot doctor # 应显示 [source: config file] ✓
环境变量（仅对当前 shell session 有效）：
export ZOTERO_USER_ID=12345678
export ZOTERO_API_KEY=YOUR_KEY
环境变量优先级高于 config 文件。在 .zshrc / .bashrc 里 export 可持久化，但 IDE 客户端（Cursor/Windsurf）可能读不到 shell 环境变量。
通过 register 注册时写入 MCP 配置（旧方式）：
# Tier 1（源码安装）— 重新注册时带上所有已有的 key，否则会丢失：
python3 scripts/run.py register --gemini-key <gemini密钥> --zotero-api-key <zotero密钥> --zotero-user-id <用户ID>
# Tier 2（pip/uv 安装）：
zotpilot register --gemini-key <gemini密钥> --zotero-api-key <zotero密钥> --zotero-user-id <用户ID>
</details>注意：
register会整体替换 MCP 配置中的 ZotPilot 条目。如果之前注册时带了--gemini-key，重新注册时也要带上，否则会丢失嵌入 API 密钥。推荐改用config set避免此问题。
不配也行，搜索和引用照常用，只有标签和集合管理需要。
第一次用会发生什么
你说"搜我的 Zotero"时，Skill 会走一遍安装流程：
- 检测到缺少
zotpilot命令，自动安装（优先uv tool install，失败则 fallback 到pip install） - 检测 Zotero 数据目录，问你选哪个嵌入模型
- 注册 MCP 服务器（如果还没注册的话）
- 你重启一次，MCP 工具生效
- 索引论文，每篇 2-5 秒
- 之后直接问就行
嵌入模型有三个选项：
| 模型 | API Key | 质量 | 离线 | 默认维度 |
|------|:---:|------|:---:|------|
| Gemini gemini-embedding-001 | 是（免费额度） | MTEB 68.32 | 否 | 768 |
| DashScope text-embedding-v4 | 是（免费额度） | MTEB 68.36 / C-MTEB 70.14 | 否 | 1024 |
| Local all-MiniLM-L6-v2 | 本地部署（免费） | MTEB ~56 | 是 | 384 |
注意：选了之后不好换。三个模型的向量维度不一样，换模型要 zotpilot index --force 全部重新索引。先想好再选。
实际用起来是什么样
语义搜索：
"sleep spindle 与记忆巩固的关系"
返回 3 篇论文，虽然原文用的是 "spindle-dependent replay"。Zotero 搜不到这个。
按章节定位：
"哪些论文的 Results 里报告了 N400 效应？"
只返回 Results 章节的段落，带 [Author2022, p.12] 引用。Introduction 和 References 里随口提到的不会出现在结果里。Q1 期刊的结果排前面。
批量整理：
"给所有深度学习论文打标签，移到 DL Methods 集合"
语义搜索匹配到 28 篇，自动打标签、建集合、同步回 Zotero。超过 5 篇会先问你确认。
引用探索：
"谁引用了 Wang 2022？他们怎么评价局限性？"
通过 OpenAlex 找到 15 篇引用论文，在里面搜批评段落。
搜表格：
"找比较不同模型准确率的表格"
搜 PDF 里提取出来的表头、单元格数据、表标题。
和其他方案的区别
| 方案 | 语义搜索 | 知道章节结构 | 能帮你整理 | 引用图谱 | 安装耗时 | |------|:-:|:-:|:-:|:-:|--------| | Zotero 自带搜索 | 否 | 否 | 否 | 否 | 无 | | 把 PDF 喂给 AI | 是 | 否（章节信息丢了） | 否 | 否 | 手动，受 token 限制 | | 自己搭 RAG | 是 | 看你怎么搭 | 否 | 否 | 几小时起步 | | ZotPilot | 是 | 是 | 是 | 是（OpenAlex） | 约 5 分钟 |
和自建 RAG 比，ZotPilot 的区别在于搜到之后它知道这段话在 Results 还是 Methods 里，发在 Q1 期刊还是 workshop，据此调整排序。排序公式是 相似度^0.7 × 章节权重 × 期刊质量。加上表格搜索、引用图谱和 Zotero 写操作，基本覆盖了文献研究的主要流程。
常用命令
| 你说什么 | 发生什么 | |---------|---------| | "搜索我的论文，关于 X" | 语义搜索所有已索引论文 | | "我有哪些关于 X 的文献？" | 按主题返回论文列表 | | "找某作者关于 Y 的论文" | 精确词匹配 + 论文详情 | | "展示比较 X 的表格" | 搜索 PDF 里提取的表格内容 | | "谁引用了这篇论文？" | 通过 OpenAlex 查引用 | | "给这些论文打上 X 标签" | 通过 Zotero Web API 加标签 | | "创建一个叫 X 的集合" | 创建 Zotero 文件夹 | | "索引了多少论文？" | 索引状态检查 |
如何更新
v0.3.0+ 用户（推荐）：
zotpilot update
自动探测你的安装方式（uv / pip / editable），同时更新 CLI 和所有平台的 skill 目录。
| 标志 | 用途 |
|------|------|
| --check | 只查是否有新版本，不安装 |
| --dry-run | 预览所有操作，不执行任何更改 |
| --cli-only | 只更新 CLI，跳过 skill 目录 |
| --skill-only | 只更新 skill 目录，跳过 CLI |
Skill 目录升级前会自动检查：符号链接、脏工作树、非 ZotPilot 仓库会被跳过并打印警告，不会误操作。
v0.2 及更早版本用户（手动升级到最新版）：
# pip / uv 安装
uv tool upgrade zotpilot
# 或
pip install --upgrade zotpilot
# git clone 安装（skill 目录）
# 进入你的 skill 目录（各平台路径见"快速开始"章节）
cd <your-skill-dir>/zotpilot
git pull
32 个 MCP 工具
<details> <summary>搜索（7 个）</summary>| 工具 | 说明 |
|------|------|
| search_papers | 语义搜索，可以按章节、期刊加权 |
| search_topic | 按主题找论文，结果按文档去重 |
| search_boolean | 精确词匹配（AND/OR） |
| advanced_search | 多条件元数据搜索（年份/作者/标签/集合等），无需索引 |
| search_tables | 搜表格内容 |
| search_figures | 搜图表标题 |
| get_passage_context | 展开某个结果的上下文 |
| 工具 | 说明 |
|------|------|
| get_library_overview | 列出所有论文和索引状态 |
| get_paper_details | 看一篇论文的完整元数据 |
| list_collections | 列出所有文件夹 |
| get_collection_papers | 看某个文件夹里的论文 |
| list_tags | 列出所有标签 |
| get_index_stats | 索引状态：多少篇、多少 chunk |
| get_notes | 读取和搜索笔记 |
| get_feeds | 列出 RSS 订阅或获取订阅条目 |
| get_annotations | 读取高亮和评论（需要 ZOTERO_API_KEY） |
| 工具 | 说明 |
|------|------|
| add_item_tags / remove_item_tags | 加/删标签（单篇） |
| set_item_tags | 替换全部标签（单篇） |
| add_to_collection / remove_from_collection | 移进/移出文件夹（单篇） |
| create_collection | 建文件夹 |
| create_note | 给论文添加笔记（需要 ZOTERO_API_KEY） |
| batch_tags(action="add\|set\|remove") | 批量标签操作（最多 100 篇） |
| batch_collections(action="add\|remove") | 批量文件夹操作（最多 100 篇） |
| 工具 | 说明 |
|------|------|
| find_citing_papers | 谁引了这篇（OpenAlex） |
| find_references | 这篇引了谁 |
| get_citation_count | 被引次数 |
| 工具 | 说明 |
|------|------|
| index_library | 索引新论文（增量，支持分批：batch_size=20，循环调用直到 has_more=false） |
| get_index_stats | 查看索引状态（文档数、分块数） |
| switch_library | 列出/切换文献库（支持群组库） |
| get_reranking_config | 看排序权重 |
| get_vision_costs | 看视觉 API 用量 |
工作原理
ZotPilot 的核心是一个 MCP server，通过 SKILL.md 提供安装和使用指导，scripts/run.py 负责自动安装和跨平台注册。AI agent 加载后会启动 MCP server，暴露 32 个工具。
索引（跑一次）
Zotero SQLite ──→ PDF 提取 ──→ 分块 + 章节分类 ──→ 向量嵌入 ──→ Chr
