yilewang/llm-for-zotero · 上手攻略

  • 仓库：yilewang/llm-for-zotero
  • 链接：https://github.com/yilewang/llm-for-zotero
  • 分类：academic-writing
  • 作者：Tom
  • 更新：2026-07-13

一、这是什么

llm-for-zotero 是一个Zotero 阅读器插件，将大语言模型直接嵌入 Zotero 的 PDF 阅读界面，让你可以直接在 Zotero 里和论文对话、做摘要、查证据、比对多篇文献，并把研究笔记导出到 Obsidian、Logseq 等本地知识库。

简单说：Zotero 里的 ChatPDF，但不只是 Chat——还能自动整理进你的 PKM 系统。

支持多种后端：OpenAI API、local OpenAI-compatible 模型、ChatGPT Web（无需 API key）、Codex App Server（ChatGPT Plus 用户专用）、Claude Code（实验性）。

二、解决什么问题

  • PDF 对话：不用把论文导出到 ChatGPT 或 Claude，在 Zotero 里直接问
  • 引用可溯源：LLM 的回答带页码级引用，点击直接跳回 Zotero 原文位置
  • 文献管理无缝衔接：笔记直接写进 Zotero Note，或同步到 Obsidian/Logseq
  • Agent Mode：不仅能聊天，还能搜索文献库、更新标签、整理文献——用 LLM 帮你做文献管理
  • MinerU 高保真解析：表格、公式、图表用 MinerU 提取，比直接 OCR 更准确

三、快速安装

方式一：直接安装 XPI（最简，推荐）

# 1. 从 GitHub Releases 下载最新的 .xpi 文件
# https://github.com/yilewang/llm-for-zotero/releases

# 2. Zotero 中打开：Tools -> Add-ons
#    -> 点击齿轮图标 -> "Install Add-on From File"
#    -> 选择下载的 .xpi 文件

# 3. 重启 Zotero

# 4. 打开 Preferences -> llm-for-zotero
#    配置 Provider（API / WebChat / Codex / Claude Code）
#    填入 Base URL、Key、Model，点击 Test Connection

方式二：开发版 / 从源码构建

# 1. 克隆仓库
git clone https://github.com/yilewang/llm-for-zotero.git
cd llm-for-zotero

# 2. 构建 XPI（需要 Node.js）
npm install
npm run build

# 3. 在 Zotero 中按上述步骤安装生成的 .xpi

⚠️ 注意：Zotero 7 和 Zotero 6 的插件 API 不兼容，请确认你安装的是匹配你的 Zotero 版本的 release。

四、核心用法

4.1 基础 Chat（PDF 对话）

  1. 在 Zotero 中打开任意 PDF
  2. 在右侧工具栏找到 LLM Assistant 图标并点击
  3. 直接用自然语言提问，例如： - "这篇论文的主要贡献是什么？" - "方法部分的创新点在哪里？" - "实验结果如何支撑作者的结论？"

LLM 会基于当前 PDF 内容作答，点击回答中的引用可直接跳转到 Zotero 原文对应段落。

实用快捷操作： - 选中文字 → 右键 → "Add to chat"：将选中文本加入对话上下文 - 截取图表截图 → 上传：让 LLM 分析图表 - 上传本地文件：支持 PDF、DOCX、PPTX、TXT、Markdown（最多 10 个） - 按 / 引用其他论文：在多论文标签页下，用 / 引用其他 Zotero 中的 PDF 作为背景知识

4.2 Agent Mode（Beta，推荐进阶用户）

Agent Mode 让 LLM 可以对你的文献库进行读写操作（需在设置中开启）。

开启方式：Preferences -> llm-for-zotero → 启用 Agent Mode → 重启 Zotero → 在上下文栏切换 Agent (beta) 按钮。

Agent Mode 的核心能力：

操作类型 具体例子
库搜索 "搜索近三年关于 RAG 的论文"
论文读取 "阅读这篇论文的方法部分"
元数据管理 "给所有未分类的论文加上 'AI' 标签"（需确认）
笔记撰写 "为这篇论文写一段摘要并存入 Obsidian"
文献导入 "搜索并导入 Attention is All You Need"
集合管理 "把这批论文移入新建的 'LLM-Survey' 集合"

会话安全机制：Agent Mode 设计为"读操作无限制，写操作需确认，可撤销"——每次写操作（如打标签、改元数据）都会弹出确认卡，可在同一会话内撤销最近 10 次写操作。

4.3 文件笔记（Obsidian / Logseq 同步）

# 在 Preferences -> llm-for-zotero -> Notes Directory 配置：

# 配置项说明：
# Nickname          → 对话中如何称呼这个目录（如 "Obsidian"）
# Notes Directory   → 绝对路径，如 /Users/me/MyVault
# Default Folder    → 新笔记存放的子文件夹，如 Logs
# Attachments Folder → 笔记中图片的存放位置，如 Logs/imgs

# 使用示例（在聊天中）：
"Summarize this paper and save it to Obsidian."

# LLM 会自动：
# 1. 收集论文元数据（标题、作者、年份、DOI）
# 2. 生成带 YAML frontmatter 的 Markdown 笔记
# 3. 若启用了 MinerU，从 PDF 复制相关图片到 Attachments Folder
# 4. 保存到 Default Folder

笔记格式使用 Pandoc citation 语法 [@citekey]，兼容 Obsidian Zotero Integration 插件。

4.4 多后端配置详解

OpenAI / OpenAI-Compatible API（最通用）：

# Preferences -> llm-for-zotero -> AI Providers
# 填入：
Provider: OpenAI / OpenAI-Compatible
API Base URL: https://api.openai.com/v1  # 或你的代理地址
API Key: sk-...
Model: gpt-4o  # 支持自定义模型名

ChatGPT Web（无需 API Key，适合没有 API 访问权限的用户）：

  • 在 Zotero AI Providers 设置中选择 "WebChat"
  • 浏览器登录 ChatGPT
  • 通过 WebChat 协议同步会话

Codex App Server（ChatGPT Plus 用户推荐路径）：

# 1. 安装 Codex CLI
npm install -g @openai/codex
# macOS 也可：brew install --cask codex

# 2. 登录
codex login

# 3. Zotero 中：Preferences -> llm-for-zotero -> Agent tab
#    勾选 Enable Codex App Server integration
#    选择默认模型和推理级别
#    点击 Test Connection

# 4. 聊天头部的 Codex 按钮切换到 Codex 对话系统

⚠️ Codex App Server 和 Claude Code Mode 在 Agent Tab 中互斥，启用一个需先关闭另一个。

Claude Code（实验性，需要额外配置桥接）：

# 1. 安装 Claude Code CLI
# https://code.claude.com/docs/en/installation.md

# 2. 安装桥接适配器
git clone https://github.com/jianghao-zhang/cc-llm4zotero-adapter.git
cd cc-llm4zotero-adapter
npm install
npm run build
npm run serve:bridge

# 3. 验证桥接运行
curl -fsS http://127.0.0.1:19787/healthz

# 4. Zotero 中：Preferences -> llm-for-zotero -> Agent tab
#    Enable Claude Code integration: On
#    Bridge URL: http://127.0.0.1:19787
#    Default Model: sonnet
#    Default Reasoning: auto

⚠️ Claude Code Mode 当前不支持 Zotero 原生 API 操作（如读 item 状态、写笔记、打标签），建议用内置 Agent Mode 代替。

4.5 MinerU PDF 解析（高质量论文理解）

MinerU 是高保真 PDF 解析引擎，能提取表格、公式、图表，比 Zotero 内置 PDF 解析效果好很多。

# 云端模式（推荐先体验）：
# Preferences -> llm-for-zotero -> MinerU
# 勾选 Enable MinerU，保持 Cloud Mode
# 可选填入个人 API Key（mineru.net 免费账户）
# ⚠️ 内置 API 可能于 2026 年 6 月后不再维护，建议尽早申请个人 Key

# 本地模式（需要 GPU）：
# 1. 安装 MinerU：参考 https://github.com/opendatalab/MinerU
# 2. 运行 mineru-api 服务器（默认 http://127.0.0.1:8000）
# 3. Zotero 中勾选 Use local MinerU server，配置 Base URL
# 4. 选择 Backend：pipeline（通用，CPU 友好）/ vlm（高准确率，需 GPU）/ hybrid（高准确率，多语言）

MinerU 解析结果会缓存到本地，新对话自动使用解析后的内容。

五、典型适用场景

场景 说明
论文快速泛读 打开 PDF → 问 LLM 摘要 → 判断是否值得精读
证据定位 "论文中哪段支撑了这个结论？" → 直接跳转原段落
文献对比 同时打开多篇论文，让 LLM 对比它们的方法差异
文献综述写作 用 Agent Mode 搜库、读论文、整理到 Obsidian，形成综述素材
实验室组会准备 让 Agent 读一批论文，生成研究现状报告
Meta-Analysis 用 evidence-based-qa skill 追踪某结论在不同论文中的支撑情况

六、坑与注意

  1. Zotero 版本兼容：确认 Zotero 7 vs 6，安装对应版本的 .xpi
  2. Agent Mode 默认关闭：需要手动在 Preferences 中启用，否则只有基础 Chat 功能
  3. 写操作需主动确认：Agent Mode 的标签、元数据修改每次都会弹出确认，批量操作时需注意点确认
  4. Claude Code Mode 功能受限：实验性，不支持 Zotero 原生写操作，如需完整功能建议用内置 Agent Mode
  5. MinerU 本地模式慢：VLM/Hybrid Backend 首解析需要下载模型，GPU 显存建议 8GB+
  6. 会话上下文有限：长对话会触发上下文压缩，插件会自动将旧对话打包，但要注意关键信息可能被"压掉"
  7. Codex token 刷新：Legacy Codex Auth 模式下，若遇 401 需手动刷新 token；App Server 路径更稳定
  8. 隐私注意：云端 API 模式会将 PDF 内容发送给第三方 LLM 提供商，敏感论文建议用本地模型

七、与同类对比

方案 类型 优势 劣势
llm-for-zotero Zotero 插件 深度集成 Zotero、引用可跳转、笔记同步 仅限 Zotero 用户
Zotero GPT Zotero 插件 成熟度高 功能相对单一
ChatPDF / Humata 在线服务 无需安装 数据外传、不与文献库整合
Paperpal / Trinka 学术写作辅助 专注于英文润色 不是研究助手
Obsidian + Zotero Integration 本地方案 笔记管理强大 无 LLM 对话能力，需配合其他工具

llm-for-zotero 的差异化在于：Zotero 原生阅读器内的对话式研究体验 + 端到端的文献到笔记工作流。

八、一句话推荐结论

如果你用 Zotero 管理文献，同时希望在读论文时随时能"问一句"、写完直接归档到 Obsidian——这个插件是目前把这两件事打通得最顺滑的方案，建议先装 XPI 体验基础 Chat，觉得顺手再逐步解锁 Agent Mode 和 Obsidian 同步。

信息来源： - GitHub README（完整安装、配置、多后端详解） - llm-for-zotero 英文文档：https://yilewang.github.io/llm-for-zotero - llm-for-zotero 中文文档：https://yilewang.github.io/llm-for-zotero/zh/

不确定处： - MinerU 内置 API 的具体下线时间（README 提 2026 年 6 月），建议关注 mineru.net 官方公告 - Codex App Server 的具体模型 ID 格式（README 示例 gpt-5.5 可能是占位符），建议以 Codex CLI 实际返回为准 - cc-llm4zotero-adapter 桥接项目的长期维护状态（第三方仓库），建议提前了解其 GitHub 更新频率