ZotPilot

---

v0.5.0 — 调研工作流

这个版本的核心变化：agent 现在能真正帮你收集论文，而不只是搜索已有的库。

新增的 Connector 浏览器扩展让 agent 通过你自己的 Chrome 会话保存论文。好处是实际的：机构订阅的 PDF 也能一起拿到。你挂着学校 VPN 或者在校园网，把一批 DOI 或 arXiv 号交给 agent，它帮你全部存进 Zotero，连带 PDF，不用一篇一篇手动操作。

完整的调研工作流用 /ztp-research 触发：OpenAlex 搜索候选 → 确认名单 → Connector 入库 → 自动打标签、分集合 → 逐篇报告，全程由 agent 推进。

这个版本还把 MCP 工具从 33 个精简到 18 个，修了一批边界 bug，并加固了增量索引，让它在中断后能从断点正确恢复。

---

快速开始

pip install zotpilot
zotpilot setup                 # 交互式配置 + 自动部署 skills + 注册 MCP
# 重启你的 AI 客户端

然后跟 agent 说「搜我库里关于 X 的论文」或「帮我调研 Y 方向」。它会按流程把 18 个 MCP 工具和 4 个 packaged skill 串起来完成任务。

前置：Zotero 8（已安装并至少启动过一次）· Python 3.10+ · 支持的 AI Agent 客户端（Claude Code / Codex / OpenCode）。入库工作流还需要 Connector 浏览器扩展。

ZotPilot 会把 Codex packaged skills 部署到 ~/.agents/skills。旧的 $CODEX_HOME/skills（默认通常是 ~/.codex/skills）只是 Codex 兼容路径；如果你的 Codex 桌面环境显示该路径，它不是 ZotPilot 的部署目标。

---

能做什么

ZotPilot 由三部分组成：

组件	作用
MCP Server	18 个原子工具：语义搜索、引用图谱、入库、标签 / 集合 / 笔记管理
Connector	Chrome 扩展。agent 通过你的浏览器会话保存论文，保留机构订阅 PDF
Agent Skills	把工具串成完整研究流程，不只是单次调用

4 个 skill 覆盖研究流程

Skill	做什么
ztp-research	本地库 + OpenAlex 检索 → 候选确认 → Connector 入库 → 自动打标签 / 分集合 → 逐篇报告
ztp-review	基于库内论文做综述、聚类、比较、初稿整理
ztp-profile	分析文献库主题分布、期刊层次、时间跨度、标签使用
ztp-setup	指导 agent 调用 zotpilot setup / upgrade / doctor 做安装、更新、排错。它不是 CLI 命令本身

5 个核心能力

能力	不一样在哪
语义搜索	按意思搜，不只关键词匹配。结果精确到章节段落
一步入库	DOI / arXiv / URL 混合输入 → Connector 浏览器保存 → 验证 → 必要时回退
引用图谱	OpenAlex 查引用链，并在引用论文里搜特定观点
批量整理	语义匹配 → 打标签、分集合、写笔记，同步回 Zotero
学术检索	OpenAlex 全参数检索，可直接喂给入库流程

---

和其他方案的区别

	语义搜索	章节定位	入库 + 整理	引用图谱	安装
Zotero 原生	✗	✗	✗	✗	—
把 PDF 喂给 AI	✓	✗	✗	✗	手动
自己搭 RAG	✓	看实现	✗	✗	数小时
zotero-mcp	✓	✗	部分	✗	~5 min
ZotPilot	✓	✓	✓（Connector）	✓	~5 min

不一样的地方主要在于：入库走真实浏览器会话和 Zotero translator，机构订阅的 PDF 也能一起拿到；引用数据来自 OpenAlex；排序和重排细节放在下面的工作原理里。

---

安装详情

Provider	体验	离线	获取 API Key
Gemini	高质量默认	✗	Google AI Studio
DashScope	适合中国网络环境	✗	阿里云百炼
Local	基本够用	✓	不需要

选定后不建议换。向量维度不同，换模型要 zotpilot index --force 重建。 选 local 只把 ZotPilot 切到本地嵌入模式；本地模型在首次实际调用 embeddings 时才下载，不在 setup 阶段预下载。 DashScope 默认使用 OpenAI-compatible embedding endpoint；如需 DashScope 原生 document / query 非对称检索语义，可运行 zotpilot config set dashscope_embedding_endpoint native，然后 zotpilot index --force 重建索引。

非交互式（agent 驱动）：

zotpilot setup --non-interactive --provider gemini   # 或 dashscope / local

配置模型分两层：

• zotpilot setup 写共享本地配置到 macOS / Linux 的 ~/.config/zotpilot/config.json，或 Windows 的 %APPDATA%\zotpilot\config.json，并自动部署 skills / 注册 MCP
• zotpilot config set 管理共享配置；API key 也会写入同一个 config.json
• zotpilot upgrade 升级 CLI，并刷新 packaged skills / 同步 MCP runtime
• API key 不写入 Claude / Codex / OpenCode 的客户端配置

环境变量仍可作为临时 override，优先级高于 config.json：

export GEMINI_API_KEY=<your-key>           # 或 DASHSCOPE_API_KEY
export ANTHROPIC_API_KEY=<your-key>        # 可选：复杂表格视觉提取

config.json 可能包含 API key。不要提交、公开粘贴或同步到不可信位置；共享机器上优先用交互式 zotpilot setup 输入密钥，避免把 key 留在 shell history。

推荐顺序：

zotpilot setup                         # 交互式：会询问 embedding key 以及 Zotero User ID / API key（可跳过）
# 或
zotpilot setup --non-interactive --provider gemini

之后如果需要修改配置：

zotpilot config set gemini_api_key <key>
zotpilot config set zotero_user_id <id>
zotpilot config set zotero_api_key <key>
zotpilot setup

可选：openalex_email 不是密钥，只是 OpenAlex 联系邮箱。配置后 OpenAlex 相关搜索 / 引文查询能走 polite pool（约 10 req/s；未配置通常约 1 req/s）：

zotpilot config set openalex_email you@example.com

入库工作流默认只说明 Chrome：

1. 打开 最新 Release，下载 zotpilot-connector-v*.zip 并解压
2. Chrome 地址栏打开 chrome://extensions/
3. 打开右上角开发者模式
4. 点击加载已解压的扩展程序
5. 选择包含 manifest.json 的目录
6. 工具栏出现 Zotero 图标即安装成功

ZotPilot Connector 是官方 Zotero Connector 的 fork。两者可共存：官方扩展处理手动保存，ZotPilot Connector 处理 agent 调用。

Connector 升级：

1. 重新下载最新 Release zip
2. 打开 chrome://extensions/
3. 在已加载的 ZotPilot Connector 上点刷新

搜索和引用无需额外凭据。写操作需要 Zotero Web API 密钥：

1. 打开 zotero.org/settings/keys
2. 记下页面顶部的数字 User ID
3. 创建 private key，勾选 "Allow library access" + "Allow write access"

zotpilot config set zotero_user_id 12345678
zotpilot config set zotero_api_key YOUR_KEY
zotpilot setup
zotpilot doctor

迁移旧的客户端内嵌 secret：

zotpilot config migrate-secrets

zotpilot doctor     # 诊断配置 / 环境 / MCP 注册
zotpilot status     # 索引状态

MCP 工具或 Skill 没出现？重新运行 zotpilot setup 并重启 agent。高级用户如果只想刷新 agent 集成，可用 zotpilot install。

---

使用模式与示例

直接自然语言交互

适合简单、单步、目标清晰的任务，直接对 agent 说即可：

• “搜我库里关于 X 的论文”
• “哪些论文的 Results 里提到 Y？”
• “谁引用了这篇？”
• “索引了多少论文？”

这类请求通常会直接调用单个或少量 MCP 工具完成。

常见例子：

你说	agent 做
「搜我的论文，关于 X」	语义搜索已索引论文
「哪些论文的 Results 里提到 Y？」	按章节 + 关键词定位段落
「找比较模型准确率的表格」	搜 PDF 提取的表格内容
「谁引用了这篇？怎么评价？」	OpenAlex 查引用 → 搜观点段落
「索引了多少论文？」	索引状态检查

ztp-* workflow

适合多阶段、容易跑偏、需要 agent 按顺序推进的任务，建议显式触发 workflow：

• ztp-research
  • “/ztp-research 帮我调研 X 方向最近的重要论文，并把值得收的入到 Zotero 里”
• ztp-review
  • “/ztp-review 基于我库里的论文整理一版关于 X 的综述框架”
• ztp-profile
  • “/ztp-profile 看看我这个库主要在研究什么，再决定怎么整理”
• ztp-setup
  • “/ztp-setup 检查 ZotPilot 配置”

这类任务更适合让 agent 显式进入 skill 工作流，因为它们通常涉及搜索、筛选、入库、整理、汇报等多个阶段。

工作原理

索引（跑一次）
Zotero SQLite ──→ PDF 提取 ──→ 分块 + 章节分类 ──→ 向量嵌入 ──→ ChromaDB

查询（每次）
Agent ──→ MCP 工具 ───┬── 语义搜索 ──→ ChromaDB ──→ 章节感知重排序
                      ├── 引用图谱 ──→ OpenAlex
                      ├── 文献浏览 ──→ Zotero SQLite（只读）
                      ├── 写操作   ──→ Zotero Web API ──→ 同步回 Zotero
                      └── 入库     ──→ Bridge + Connector ──→ Zotero Desktop

• 索引：SQLite 以 mode=ro&immutable=1 只读打开；PyMuPDF 提取 PDF 全文、表格、图表；按学术章节分块；嵌入存入 ChromaDB。增量索引会跳过已完成项目。
• 搜索：查询向量化 → ChromaDB 余弦相似度 → 章节感知重排序 + 期刊质量加权。
• 入库：Agent → 本地 bridge (127.0.0.1:2619) → Chrome Connector → Zotero Desktop。
• 写操作：标签 / 集合 / 笔记通过 Zotero Web API（Pyzotero），自动同步回客户端。

类别	工具
搜索	search_papers、search_topic、search_boolean、advanced_search
阅读	get_passage_context、get_paper_details、get_notes、get_annotations、browse_library、profile_library
发现	search_academic_databases
入库	ingest_by_identifiers
整理	manage_tags、manage_collections、create_note
引用	get_citations
索引	index_library、get_index_stats

search_papers 支持 section_type 参数搜表格 / 图表。ingest_by_identifiers 接受 DOI / arXiv ID / URL 混合输入。

PyPI 安装的 zotpilot（wheel 内含 skills + references）
├── src/zotpilot/skills/
├── references/
└── connector/

# 配置 / 索引位置
# macOS / Linux
~/.config/zotpilot/config.json
~/.local/share/zotpilot/chroma/

# Windows
%APPDATA%\zotpilot\config.json
%APPDATA%\zotpilot\chroma\

---

更新

zotpilot upgrade

升级当前 ZotPilot CLI、刷新 packaged skill 文件、同步 MCP runtime 配置。

命令 / 选项	用途
upgrade 或 update（不带参数）	升级 CLI + 刷新 skills + 同步 runtime
--check	只检查版本（始终 exit 0）
--dry-run	预览 runtime drift 和更新动作
--cli-only	只升级 CLI 包
--skill-only	只刷新 skills 和 runtime 注册
--re-register	即使没有 drift，也强制刷新客户端注册
--migrate-secrets	同步 runtime 前，迁移旧客户端内嵌 secrets

---

FAQ

不会。SQLite 用 mode=ro&immutable=1 打开，物理上写不进去。标签 / 集合 / 笔记走 Zotero 官方 Web API，变更正常同步回客户端。

能，只读模式不冲突。

Claude Code、Codex、OpenCode。这三家是我们官方支持的客户端，Skill 部署、MCP 注册、升级同步都针对它们做了适配。

Gemini 免费额度约 1,000 请求/天，够索引几百篇；超出后 $0.15/百万 token。DashScope 新用户 100 万 token 免费。Local 模型完全离线免费。

每篇 2–5 秒，300 篇约 15 分钟。用 zotpilot index --limit 10 先试试，跑过的自动跳过。

• 扫描版自动 OCR（需装 Tesseract：macOS brew install tesseract tesseract-lang，Ubuntu sudo apt install tesseract-ocr）
• 超过 40 页默认跳过（--max-pages 可调），--item-key 可单独索引
• 可选：Claude Haiku 修复复杂表格（需 ANTHROPIC_API_KEY）

能。嵌入选 --provider local，不配写操作 key，全部本地跑。搜索、浏览、索引都不需要网络。

OpenAlex。没 DOI 的论文无法查引用，但语义搜索和标签管理不受影响。

---

出了问题

症状	怎么办
找不到 Skill	zotpilot setup 然后重启 agent
zotpilot: command not found	先 pip install zotpilot
MCP 工具没出来	zotpilot setup 然后重启 agent
搜出来是空的	先跑 zotpilot index
GEMINI_API_KEY not set	export GEMINI_API_KEY=<key> 或改用 setup --provider local
不知道哪出了问题	zotpilot doctor

更多见 troubleshooting.md。

---

git clone https://github.com/xunhe730/ZotPilot.git
cd ZotPilot
pip install -e ".[dev]"

zotpilot setup
python -m pytest
python -m ruff check src/ tests/

Connector 开发：

cd connector
npm install
./build.sh -d

---