• 首页
• /
• llm-for-zotero 文档
• 在 GitHub 上查看 ↗

llm-for-zotero：面向 Zotero 文库的研究 Agent 系统

📖 English Documentation

llm-for-zotero 将大型语言模型带入 Zotero 阅读器，让您无需离开文库即可提问、总结论文、解读图表、比较文献并保存笔记。它支持常规 API 服务商、本地 OpenAI 兼容模型、WebChat、Codex App Server 和 Claude Code。

演示视频

观看如何在文库对话中使用 llm-for-zotero Agent 进行文献综述。

快速开始

1. 从 Releases 页面下载最新 .xpi 文件。
2. 在 Zotero 中打开 工具 → 附加组件 → 齿轮图标 → 从文件安装附加组件，选择该 .xpi 文件。
3. 重启 Zotero。
4. 打开 首选项 → llm-for-zotero，选择服务商，填写基础 URL、密钥和模型，然后点击测试连接。
5. 在 Zotero 中打开一篇 PDF，点击右侧工具栏的 LLM Assistant 图标。

如果您不想使用服务商 API 密钥，可以从 WebChat 或 Codex App Server 开始。

环境要求

• Zotero
• 一种模型后端：服务商 API 密钥、本地 OpenAI 兼容模型、WebChat、Codex App Server 或 Claude Code。
• WebChat 模式需要 Chromium 内核浏览器。
• 通过 npm 安装 Codex CLI 和使用 Claude Code 模式需要 Node.js 18+。macOS Codex cask 不需要单独安装 Node.js。
• 在 Agent 模式中使用通用网页搜索时：需要 Tavily 密钥、官方 DeepSeek 模型配置，或使用无需密钥的 AnySearch。
• 如果启用 MinerU 解析，建议使用个人 MinerU API 密钥或本地 mineru-api 服务。

选择配置方式

最新更新

v3.9.14

• 任务进度显示每个回答的来源。 侧边面板按问题列出 Agent 使用的论文和网页，以及它读取的段落。 点击在回答中显示即可跳到引用该来源的句子。 详见任务进度与来源。
• 网页回答标注来源：带编号的来源标记和回答末尾的来源标签，复制回答时也会保留。
• 按 Agent 分组的对话：窗口侧栏可以把对话分为 Agent、Codex 和 Claude 三组。
• 悬浮输入框：输入框悬浮在对话底部，并随输入内容增高。
• 按需启动本地 MinerU 服务：插件可在解析 PDF 时启动本地 MinerU 服务，并在空闲时停止。 详见使用本地 MinerU 服务。
• OpenCode Go 成为新的服务商预设。

v3.9.13

• 侧边面板：独立窗口最多可打开八个标签页，包括侧聊、历史对话和对话生成的所有内容。
• Agent 保存的文件会以预览卡片显示在回答下方，每篇论文都有自己的文件夹。 详见 Agent 保存的文件。
• 文库外的论文：Agent 可以根据 DOI、PubMed、PMC 或 arXiv ID 读取论文摘要和开放获取全文。
• Claude Code 无需额外配置：插件会自动启动和停止 Claude Code 所需的桥接服务。
• AI 编辑笔记时保留引用、高亮和图片。
• DeepSeek 搜索成为 Tavily 和 AnySearch 之外的新网页搜索选项。

更早的更新

• 使用统计：以本地仪表板汇总论文对话和文库对话活动，并提供时间筛选、活动与 Token 图表、模型明细、CSV 导出和重置功能。 详见使用统计。
• 内置网页与学术文献研究：Agent 可以搜索公开网页、读取来源页面，并将最新在线信息与 Zotero 文库中的证据结合起来。 回答可附带段落级来源卡片，同时活动轨迹会清楚区分通用网页结果与学术文献结果。 详见通用网页搜索。
• Codex App Server 是 ChatGPT Plus 用户推荐的 Codex 使用路径。它通过本地 codex app-server 运行时工作，并在 Agent 标签页中配置。
• Claude Code 模式（实验性）：使用您自己的 Claude Code 登录，将 Claude Code 作为 Zotero 内部独立的对话系统运行。它可以使用插件的 Zotero 工具读取您的文库，并在您批准后编辑笔记、标签、元数据和导入条目。详见 Claude Code 配置。
• 统一历史记录：Agent、Codex 和 Claude 的对话显示在同一个历史列表中。点击输入框中的运行时标记即可切换运行时；也可以通过斜杠菜单或直接用自然语言请求，附加之前的对话。
• WebChat 模式通过 Sync for Zotero 浏览器扩展支持 ChatGPT、DeepSeek 和 Google Gemini 网页同步。
• 文件笔记：笔记目录不再硬编码为 Obsidian。您可以配置任意本地 Markdown 目录，包括 Obsidian、Logseq 或普通文件夹。详见 文件笔记。
• Skills 技能系统：可自定义的引导文件会影响 Agent 的任务处理方式。内置 8 个技能，并支持创建自定义技能。详见 Skills 技能系统。
• 独立窗口模式：在专用窗口中打开助手，支持论文对话、文库对话和对话历史。
• 缓存感知的 Agent 模式：在较长研究回合中保留稳定的论文上下文、已读取证据和覆盖状态，并在上下文窗口拥挤时自动压缩旧对话历史。
• 引用跳转：在页码位置经过验证前保持保守的引用标签；基于原文片段的引用可跳回 Zotero 中匹配的段落。
• MinerU PDF 解析：高保真提取可更准确地保留表格、公式和图表，并支持云端 MinerU、本地 mineru-api 服务、批量解析、缓存修复、同步包、标签和解析过滤器。
• 精准图像提取：图像问答与图像笔记现在使用直接从原始 PDF 裁出的图像（以 MinerU 为索引），而非 MinerU 自身的图片，从而获得更清晰、更准确的图像。详见精准图像提取。

感谢 @jianghao-zhang 和 @boltma 对 Codex App Server、Claude Code 和文件上传工作流的重要贡献。

安装

1. 下载最新的 .xpi 安装包 前往 Releases 页面 下载最新的 .xpi 文件。

2. 在 Zotero 中安装插件 打开 Zotero → 工具 → 附加组件 → 点击齿轮图标 → 从文件安装附加组件 → 选择 .xpi 文件。

3. 重启 Zotero 重启 Zotero 完成安装。插件会在每次启动时自动检查更新。

配置

打开 首选项 → 切换到 llm-for-zotero 标签页。

1. 选择您的服务商（如 OpenAI、Gemini、DeepSeek）。
2. 填写 API 基础 URL、API 密钥 和模型名称。
3. 点击 测试连接 以验证配置。

支持的服务商与协议

预设服务商包括 OpenAI、Gemini、Anthropic、MiniMax、GLM、DeepSeek、Grok、Qwen、Kimi 和 GitHub Copilot。您也可以添加任意自定义 OpenAI 兼容 HTTP 端点，包括 Ollama、LM Studio、vLLM 或远程代理。

插件原生支持以下服务商协议：

支持的模型

任何提供 OpenAI 兼容 HTTP API 的模型均可使用，包括通过 Ollama、LM Studio 或 vLLM 本地部署的模型。

多服务商配置

您可以配置最多 10 个服务商组，每组包含多个模型，从而：

• 用多模态模型解读图表，用文本模型生成摘要。
• 通过多个模型交叉验证答案，获得更全面的理解。
• 在对话中随时通过模型选择器切换模型。

推理等级与超参数

对于支持的模型，您可以为每次请求设置推理等级：default、low、medium、high 或 xhigh，用于控制模型在回答前的思考深度。

其他可调参数：

使用指南

1. 在 Zotero 阅读器中打开任意 PDF。
2. 点击右侧工具栏中的 LLM 助手图标以打开侧栏。
3. 输入问题，例如“这篇论文的主要结论是什么？”

首条消息会将整篇论文作为上下文加载，后续问题则通过检索定位相关段落，保持对话快速且精准。

对话模式

插件支持三种对话模式：

界面控件

• 模型选择器 — 在对话中随时切换已配置的模型。
• 推理等级选择器 — 为当前请求选择推理深度。
• 字体缩放 — 将侧栏字体大小从 80% 调整至 180%。
• 自动滚动 — 自动滚动至最新消息。
• Token 用量 — 实时显示输入、输出及推理 Token 消耗。

带引用跳转的有据答案

提问时，模型会生成基于论文内容的答案。引用标签会在页码位置经过验证前保持保守；点击已验证的引用或基于原文片段的引用，即可跳回 Zotero 中匹配的段落，方便核实答案并快速定位相关内容。

论文摘要生成

数秒内为任意论文生成简洁摘要。摘要基于完整 PDF 全文生成，您可以自定义提示词，聚焦于研究方法、结果、启示或其他任何方面。

选中文本解释

选中 PDF 中任意复杂段落或专业术语，请模型为其解释。您最多可添加 5 条上下文（来自论文或之前的回答）以进一步细化解释。

可选弹窗会自动建议将选中文本添加到对话，不喜欢可在设置中关闭。

图表解读

截取任意图形、图表或示意图，请模型进行解读。每次最多支持 10 张截图，适合分析复杂的多面板图表或跨章节对比视觉内容。

跨论文对比

在不同标签页中打开多篇论文，并排对比。在输入框中输入 / 可引用其他已打开的论文作为额外上下文，单次对话最多可引用 10 篇论文，实现深度跨文献分析。

外部文档上传

从本地磁盘上传文档作为额外上下文，支持格式：

• PDF（每个文件最大 50 MB）
• DOCX（Word 文档）
• PPTX（PowerPoint 演示文稿）
• TXT（纯文本）
• Markdown（.md 文件）

保存至笔记

一键将任意回答或选中文本直接保存到 Zotero 笔记，与您现有的笔记工作流无缝集成，无需手动复制粘贴。

对话历史与导出

对话会自动保存到本地并与对应论文关联。您可以：

• 在历史记录面板中浏览过往对话。
• 将完整对话以 Markdown 格式导出到 Zotero 笔记。
• 导出内容包含选中文本、截图，以及正确渲染的 LaTeX 数学公式。

使用统计

打开 Zotero 设置/首选项 → llm-for-zotero → Usage，即可查看插件记录的使用活动。

使用 Overview、Paper chat 和 Library chat，可以在综合仪表板与两类对话的详细视图之间切换。 7d、30d 和 All 会筛选汇总、每日 Token 图表、模型明细和详细列表；活动热图则继续显示现有历史，最长为一年。

• Overview 显示问题总数、不同论文和对话数量、输入/输出 Token 总数、可在问题数与论文数之间切换的活动热图、每日 Token 用量，以及标明服务商或运行时和论文/文库对话占比的模型明细。
• Paper chat 列出提问最多的论文及其问题数和 Token 总数。
• Library chat 列出 Token 用量最高的对话及其问题数和 Token 总数。

该面板只报告 Token 用量，不估算费用。 对于 Usage 标签页推出前的对话，问题和论文活动会从已保存的消息中重建，而 Token 总数会明确标记为估算值，并根据已保存的提示词大小、助手回复和已保存的推理内容计算。 如果服务商没有报告 Token，面板会将相关回合标记为未报告，或显示破折号和原因说明，而不会将其当作零。 实时统计和历史重建都不包含 WebChat 回合。

使用统计仅保存在您自己的 Zotero 数据库中，此面板不会将其发送到其他地方。 Export CSV 会导出当前所选时间范围内的记录行；Reset statistics 会永久清除全部使用记录，但不会删除对话、笔记或论文。 重置后，先前从历史对话重建的记录不会再次生成。

自定义快捷预设

创建最多 10 个自定义预设，将常用提示词一键触发。内置预设包括：

• 总结 — 生成简洁摘要
• 关键要点 — 提取主要发现
• 研究方法 — 描述研究方法
• 局限性 — 识别不足或局限

您可以修改这些预设或添加自定义内容，以适配您的研究工作流。

独立窗口模式

在独立窗口中打开 LLM 助手，脱离 Zotero 阅读器侧栏。独立窗口提供全尺寸聊天界面，左侧配有可折叠的对话历史面板。

打开方式

功能特点

• 论文对话与文库对话 — 通过顶部标签页切换论文级对话和文库级对话。
• 对话列表 — 在左侧栏可排序的对话列表中浏览历史对话。您可以把对话分为可折叠的 Agent、Codex 和 Claude 三组，每组有自己的排序方式和用于新建对话的 + 按钮。置顶的论文保留在最上方，每篇论文保留自己的侧边面板标签页。
• 侧边面板 — 点击论文对话 | 文库对话一行末尾的按钮打开。它最多容纳八个标签页：
  • 侧聊：不离开主对话即可快速提问。侧聊能看到主对话，可以使用不同模型，且不会被保存。
  • 历史：在当前对话旁阅读之前的对话，可以引用它、添加它的论文，或将它设为主对话。
  • 其他：这篇论文的对话生成的所有内容，例如示意图、图像、网页、代码、计划和文件。点击前往对话可跳到生成它的消息。
  • 任务进度：每个问题使用的来源。详见任务进度与来源。

  对话中的示意图、代码、网页、图像、计划和文件都有一个 →| 按钮，可把它们移到独立的侧边面板标签页。 在回答中选中文本后选择 Quote in side chat，即可在侧聊中针对这段内容提问。

• 功能完全一致 — 阅读器侧栏中的所有功能（截图、文件上传、Agent 模式、快捷预设、引用选择器）在独立窗口中均可正常使用。
• 搜索 — 通过搜索浮层快速查找历史对话。

独立窗口打开时，阅读器侧栏面板会显示占位提示，提供聚焦窗口（将独立窗口置于前台）和关闭窗口并返回侧栏两个选项。

文件笔记

除了 Zotero 内置笔记外，Agent 还可以将研究笔记保存为您指定本地目录中的 Markdown 文件。插件不绑定任何特定笔记软件：可以指向 Obsidian 知识库、Logseq 图谱，或普通 .md 文件夹。

配置

打开 首选项 → llm-for-zotero，滚动到 Notes Directory 部分。

点击 Test Write Access 验证插件是否有权限写入该目录。

工作原理

使用您配置的昵称要求 Agent 写笔记，例如“总结这篇论文并保存到 Obsidian” 或 “把这篇记录到我的 Logseq”。Agent 将：

1. 采集内容：从论文中提取元数据、摘要、关键要点，并在可用时加入图表。
2. 编写 Markdown 笔记：遵循 write-note 技能中的约定。
3. 添加 YAML 前置信息：匹配 write-note 模板中的 title、created、tags、citekey、doi、journal；作者信息保留在正文中。
4. 嵌入提取的图像裁剪（按需）：嵌入直接从原始 PDF 裁出的精准图像，并将其复制到附件文件夹。详见精准图像提取。
5. 写入笔记：保存到 {notes_directory}/{default_folder}/{title}.md。

如果您希望笔记保存在 Zotero 内部，Agent 也可以通过 write-note 技能写入 Zotero 条目笔记。只需要求它“为这篇论文保存一条笔记”，不要提到外部笔记目录即可。

Zotero 笔记与文件笔记

笔记使用 Pandoc 引用语法（[@citekey]），兼容 Obsidian 的 Zotero Integration 和 Pandoc 插件，也适用于大多数 Markdown 阅读器。

用 Agent 编辑 Zotero 笔记

• 引用、PDF 高亮和图片保持完整。 Agent 会把它们看作占位符，例如 {{citation:3fa9c1 ("Smith", 2020, p. 42)}}；每次编辑都会放回原始内容，因此改写可以移动引用，但不会破坏引用。会删除这些内容的编辑会被拒绝，除非您明确要求删除。
• 可点击的引用。 请求页码引用时，Agent 会写入 {{cite item=123 page=42}}，它会变成与 Zotero 插入引用相同的引用：点击即可在对应页打开 PDF。
• 学习笔记填空。 引用块中的一行下划线（> ___）会变成分隔线；只由下划线组成的待办项（- [ ] ____）会保留复选框，作为填空。

通用网页搜索

从 v3.9.4 开始，Agent 模式可以在不离开 Zotero 的情况下检索公开网页。 Agent 可以搜索最新信息、打开选定来源页面进行针对性读取，并将这些发现与 Zotero 文库中的论文、笔记和元数据结合起来。 当问题依赖可能比论文或模型训练数据更新的信息时，这项功能特别有用，例如最新文档、机构页面、政策、产品信息或近期公开报道。

配置 Tavily

网页搜索可以使用 Tavily（默认）、AnySearch 或 DeepSeek。 Tavily 需要单独的 API 密钥，与模型服务商密钥相互独立。

1. 创建 Tavily 账户并获取 API 密钥。
2. 打开 Zotero → 首选项 → llm-for-zotero → Agent。
3. 在 Web search 中保留 Tavily，粘贴密钥，然后点击测试连接。
4. 启用 Agent 模式，然后提出需要最新或公开网页证据的问题。

网页搜索没有单独的开关。 当所选服务商可以运行时，web_search 和 web_read 工具会自动提供给 Agent。 WebChat、Codex 和 Claude Code 对话不使用这两个工具，而是使用各自的网页搜索。

其他搜索服务商

请在首选项 → llm-for-zotero → Agent → Web search 中选择服务商。 对于 AnySearch，Test search (sends a public query) 会发送一条固定的公开查询，并消耗配额。 DeepSeek 不会发送中转服务或其他主机的密钥。 每个服务商都会收到您的搜索词和 Agent 读取的网址。

Agent 可以完成什么

通用网页搜索与学术文献搜索相互补充，但不能互相替代。 当您需要最新文档、机构页面、公开解释、标准、政策或其他开放网页材料时，可使用网页搜索。 当您需要通过 OpenAlex、arXiv 和 Europe PMC 发现学术论文（并通过 Crossref 和 Semantic Scholar 查询元数据）时，可使用文献搜索。 Agent 会先查看当前论文和您的文库，只有在它们无法回答时才搜索外部来源。 对于范围较广的研究问题，Agent 可以同时使用两者，并与 Zotero 中已有的证据综合分析。

示例问题

• “使用最新网页来源检查这篇论文中的建议是否已经改变，并说明发生了哪些变化。”
• “将这篇论文与世界卫生组织最新公开指南进行对比，并把论文证据与网页证据分开呈现。”
• “调研表征漂移的最新进展，同时使用近期学术文献和可靠的公开研究页面。”
• “读取这个网址，将其中的观点与当前 Zotero 文集中的论文比较，并在每项陈述附近标注来源。”

一般情况下，您不需要指定搜索深度。 Agent 可以根据问题在基本搜索与高级搜索之间做出选择；如果覆盖范围比额度消耗更重要，也可以明确要求进行更广泛或更深入的搜索。

额度、隐私与核验

使用 Tavily 会消耗 Tavily 额度。 v3.9.4 首选项面板显示了发布时的额度规则：基本搜索消耗 1 个额度，高级搜索消耗 2 个额度，页面提取则按每 5 个成功读取的页面计费。 撰写本文时，Tavily 免费方案每月提供 1,000 个额度，且无需信用卡。 免费额度和价格可能调整，请查阅 Tavily 额度与价格文档，并以账户中显示的最新条款为准。

搜索词和请求读取的网址会发送至 Tavily，并受 Tavily 的隐私、数据保留和搜索索引政策约束。 显示结果时，Zotero 可能会从 Tavily 提供的公开网址加载网站图标。 请勿在网页搜索词中包含凭据、未公开材料、个人数据或其他敏感私密文本。

网页内容可能变化，不同来源也可能相互矛盾。 对于重要页面，请通过来源标记打开原始来源；在依赖高风险结论前，应先核验原文。

Agent 模式（Beta）

在普通对话中，模型根据您提供的上下文回答。 在 Agent 模式下，模型还可以使用工具：用于读取、搜索或修改 Zotero 文库的小型操作。 您用自然语言提出请求，Agent 自己决定使用哪些工具以及使用顺序。

规则很简单：只读取的工具直接运行；会修改内容的工具需要您批准，并且可以撤销。

Agent 的运行过程

1. 您提出请求。 例如：“找出这个文集中使用钙成像的论文，为它们添加标签，并写一条总结笔记。”
2. Agent 把请求拆成多个部分并逐一跟踪，长请求也不会漏掉步骤。
3. Agent 读取资料。 它搜索您的文库、阅读论文和笔记；只有文库无法回答时，才搜索外部来源。
4. Agent 提出修改。 添加标签、编辑元数据、写笔记或运行命令都会显示为确认卡片。您批准之前，什么都不会改变。
5. Agent 给出回答。 引用句末尾带有编号标记，任务进度面板会显示每个回答使用了哪些来源。
6. 您可以撤销。 让 Agent 撤销，它会从最新的开始撤销已记录的修改。

如果某个选择不明确，例如应该使用哪个文集，Agent 会先问您再继续。

较长的 Agent 运行具有缓存感知能力。插件会将稳定的 Zotero 上下文和已读取证据，与不断变化的聊天记录分开保存，跟踪哪些论文和段落已经被检查，并在模型上下文填满时自动压缩旧回合。后续问题可以在证据仍然相关时复用这些来源；当缺少所需来源或覆盖层级时，Agent 会重新读取。

任务进度与来源

任务进度在独立窗口的侧边面板标签页中打开。 每个问题对应一个区块，列出该问题使用的论文和网页。

• 对于文库中的论文，它先列出 Agent 读取的段落，再列出回答中使用这些段落的位置。
• 对于网页，它显示带网站图标的页面。网页链接会在侧边面板中打开。
• 在回答中显示会找到引用该来源的句子，将其高亮并滚动到该位置。

在信任一个回答之前，可以用它检查 Agent 读了什么。 它在论文对话和文库对话中都可以使用。

文库外的论文

Agent 可以根据 DOI、PubMed ID、PMC ID 或 arXiv ID 读取不在您文库中的论文。 它会读取完整摘要；如果论文是开放获取的，还会读取全文。 对于只提供 PDF 的论文，它会给出链接。 读取不会导入论文；如果想保留，请让 Agent 导入。

之前的对话

Agent 可以查找、读取并附加之前的对话，每次最多三个。 输入 / 并选择 Add past conversation，或者直接提问，例如“把上周我问网格细胞的那次对话加进来。” 这在 Agent、Codex 和 Claude 模式下都可以使用。

Agent 保存的文件

当 Agent 保存文件时，例如网页、Markdown 摘要、图片或表格，回答下方会显示预览卡片。 您可以从卡片中在全屏视图中打开文件、在文件夹中显示它，或把它移到侧边面板。 即使之后删除了文件，卡片也会保留，并提示文件已不存在。

每篇论文都有自己的保存文件夹。 在首选项 → llm-for-zotero → Agent → Saved files 中，您可以选择这些文件夹的位置。 Check folders 会列出这些文件夹及其大小，优先显示已删除论文的文件夹，并允许您删除不再需要的文件夹。

Agent 工具

您不需要自己调用这些工具，Agent 会自行选择。 这张表可以帮助您理解活动轨迹和确认卡片。

典型使用场景：

• 运行 Python 或 R 脚本分析从文库中提取的数据。
• 将元数据导出为 CSV/JSON 供外部处理。
• 调用命令行工具（如 pandoc、ffmpeg、pdftotext）作为 Agent 工作流的一部分。
• 动态编写并执行脚本，转换或可视化您的研究数据。
• 读取本地数据文件，并将结果写回 Zotero 笔记。

内置动作

Agent 为常见文库管理工作流提供高级动作，自动串联多个工具。

MCP 服务器

插件运行内置的 Model Context Protocol (MCP) 服务器，允许外部 AI Agent 和工具以编程方式与您的 Zotero 文库交互。

• 端点：http://localhost:23119/llm-for-zotero/mcp
• 协议：JSON-RPC 2.0（MCP v2024-11-05）
• 方法：initialize、tools/list、tools/call

这意味着您可以将任何兼容 MCP 的 AI Agent（如 Claude Desktop、Cursor、自定义 Agent）连接到您的 Zotero 文库，使用上述所有工具。

Agent 演示

多步骤工作流

Agent 可以串联多个工具完成复杂任务——例如查找论文、读取元数据、搜索相关文献并撰写摘要笔记。

查找相关论文

查找相关论文有两种方式：

• /discover_related 直接对当前论文运行 OpenAlex 搜索，不需要模型。它会打开 Recommendations、References 和 Citations 三个标签页，每个最多 20 篇论文。使用 /discover_related 30 可以修改数量，Load more 再加载 20 篇，Import selected 保存您选中的论文。
• 在对话中提问，例如“找一些相关论文”或“找 15 篇相关论文”。Agent 会为候选论文排序，并给出每篇的理由。如果没有指定数量，默认先给出五篇。使用 Find more 获取下一批，Import selected 保存您的选择。如果合适的论文较少，卡片会说明原因，而不是凑数。

自动应用标签

撰写笔记

安全与审批

所有写入操作均通过人机协作确认流程：

• Agent 提出一批变更建议（如添加标签、编辑元数据）。
• 您在审批表单中查看拟定变更。
• 您可以在任何变更生效前选择批准、拒绝或修改。
• 如有问题，请让 Agent 撤销；undo 工具会从最新开始撤销已记录的写入操作。
• 终端命令和文件操作同样需要明确审批后才会执行。

Skills 技能系统

Skills（技能）是可自定义的引导文件，用于调整 Agent 处理不同类型请求的方式。 技能告诉 Agent 如何完成任务，例如使用哪些工具以及按什么顺序；它不会增加新工具。 每个技能是一个 Markdown 文件，包含一段简短描述和一段指令正文。

内置技能

插件内置 8 个技能，覆盖常见的研究工作流。首次运行时会自动复制到您的技能文件夹。

工作原理

1. 每个回合开始时，Agent 只看到每个技能的名称和描述。
2. 如果 Agent 判断任务需要某个技能，它会调用 load_skill 读取完整指令。插件不会自动预先选择技能。
3. 如果您从 / 菜单中选择技能，插件会直接应用它。
4. 技能只在其文件允许的场景中生效，例如单篇论文或整个文库。
5. 已批准的计划会保留批准时的技能版本。

由于 Agent 根据描述选择技能，自定义技能中最重要的是写出清晰、准确的描述。

创建自定义技能

1. 打开独立窗口（Ctrl+Shift+L / macOS：Cmd+Shift+L）。
2. 点击顶部工具栏中的 Skills 图标打开技能管理面板。
3. 点击 ”+ New skill” 按钮创建模板文件。
4. 模板会在默认文本编辑器中打开，编辑头部字段和指令正文：

---
name: my-custom-skill
id: my-custom-skill
description: 描述这个技能的作用
version: 1
contexts: any
activation: auto
---

准确描述 Agent 应在何时、以何种方式使用这个工作流。

5. 保存文件。技能会立即加载——无需重启。

技能文件格式：

管理技能

• 左键点击面板中的技能可在默认文本编辑器中打开编辑。
• 右键点击技能弹出上下文菜单，包含在文件系统中显示和删除选项。
• 技能以 .md 文件形式存储在 {Zotero数据目录}/llm-for-zotero/skills/ 中。
• 如果您删除了内置技能，它将在重启后保持删除状态——插件尊重您的选择。插件更新中新增的内置技能会自动添加，但不会恢复您已删除的技能。

WebChat 配置（ChatGPT、DeepSeek & Gemini 网页同步）

WebChat 模式通过浏览器扩展将您的问题发送到 chatgpt.com、chat.deepseek.com 或 gemini.google.com，再把回复实时流式传回 Zotero。 它适合不想配置服务商 API 密钥、但想使用网页聊天服务的场景。

前置条件

• 您需要能够访问所选服务商的网站。 账号要求取决于网站与具体功能；Gemini 可能允许匿名文字对话，但上传 PDF 和读取对话历史可能需要登录。
• Chromium 内核浏览器，如 Chrome、Edge、Brave 或 Arc。

配置步骤

1. 下载浏览器扩展：

前往 github.com/yilewang/sync-for-zotero → Releases，下载最新的 extension.zip，解压到电脑上的文件夹。

2. 安装扩展（侧载）：

• 打开浏览器，访问 chrome://extensions
• 开启右上角的开发者模式
• 点击加载已解压的扩展程序，选择解压后的扩展文件夹
• “Sync for Zotero” 扩展应出现在扩展列表中

3. 配置插件：

打开 Zotero → 首选项 → llm-for-zotero：

4. 开始对话：

在浏览器中打开对应的 ChatGPT、DeepSeek 或 Google Gemini 标签页并保持打开。 使用 Gemini 时，请打开 gemini.google.com/app，并在 Gemini 网页端选择模型；Zotero 桥接不会更改网页端的模型选择。 在 Zotero 中，插件面板会显示 WebChat 指示器及连接状态点（绿色 = 已连接，红色 = 未检测到）。 输入问题并发送即可。

WebChat 功能

• PDF 附件 — 右键点击论文标签切换 PDF 发送状态（紫色 = 发送，灰色 = 跳过）。
• 截图 — 使用截图按钮将图片上下文附加到消息中。
• 对话历史 — 点击时钟图标浏览和加载过往网页端对话。
• 退出 — 点击 “Exit” 按钮返回常规 API 模式。

Gemini 注意事项

• 请配套使用最新版 llm-for-zotero 与 Sync for Zotero。 较旧的浏览器扩展不会声明 Gemini 支持，Zotero 会在发送请求前将其阻止。
• Gemini WebChat 每次请求可发送一个 PDF，也可以附加截图。 请等待附件预览加载完成后再发送。
• 如果 Gemini 输入框仍残留上一次尝试的附件，请先移除再重试。 如果 Zotero 提示无法核实是否已发送，请先检查 Gemini 标签页，以免重复提交同一提示词。
• Gemini 的回答与历史记录从网页渲染结果中读取，因此 Gemini 网站更新后，Sync for Zotero 适配器可能需要同步更新。

技术说明

• 插件在 Zotero 内置端口（23119）上嵌入轻量级 HTTP 中继服务器，浏览器扩展通过轮询该中继交换查询和响应。
• WebChat 模式下禁用 Agent 模式、斜杠命令（/）和引用选择器（@）。
• 推理/思考模式由网页端控制，而不是通过插件的推理切换按钮控制。

Codex 配置（ChatGPT Plus 订阅用户）

如果您拥有 ChatGPT Plus 订阅，可以通过 Codex CLI 登录，在插件中免单独 API 密钥使用 Codex 模型。

新用户应在 Agent 标签页中选择 Codex App Server。旧的 Codex Auth (Legacy) 路径仍可供现有用户使用，但计划在 app-server 验证稳定后逐步弃用。

• Codex App Server（推荐）：启动本地 codex app-server CLI，并通过 stdio 与其通信。这是第三方应用使用 Codex 的官方方式，也是新用户首选配置。该模式在 Agent 标签页中配置，并会在聊天标题栏显示独立的 Codex 按钮。
• Codex Auth (Legacy)：直接调用 ChatGPT/Codex Responses 后端。现有用户暂时可以保留该配置，但新用户应选择 Codex App Server。

特别感谢 @jianghao-zhang 贡献最初的 Codex Auth 集成，以及 @boltma 设计 Codex App Server 集成。

配置步骤

1. 安装 Codex CLI（一次性操作）：

# macOS / Linux（需要 Node.js 18+）
npm install -g @openai/codex

# macOS 替代方案（无需 Node.js）
brew install --cask codex

Windows 用户应在 PowerShell 或命令提示符中安装 Codex，而不是在 WSL 中安装，这样 Zotero MCP 才能使用 Windows 本地回环连接。

2. 登录 ChatGPT 账号：

codex login

浏览器窗口将自动打开——使用您的 ChatGPT Plus 账号登录。凭据保存至 ~/.codex/auth.json。

3. 在 Zotero 中启用 Codex App Server：

打开 Zotero → 首选项 → llm-for-zotero → Agent 标签页：

点击测试连接，验证 Zotero 能否启动 codex app-server，然后在聊天标题栏点击 Codex 按钮进入 Codex 对话系统。

Codex App Server 与 Claude Code 是 Agent 标签页中的互斥运行时模式。启用其中一个之前，需要先关闭另一个。

仍需旧方式的现有用户可以打开 AI Providers 标签页，选择 Codex Auth (Legacy)，API 地址保持 https://chatgpt.com/backend-api/codex/responses，模型名称保持不变，例如 gpt-5.5。

Codex Auth (Legacy) 技术说明

• 从 ~/.codex/auth.json（或 $CODEX_HOME/auth.json）读取本地凭据。
• 遇到 401 响应时自动尝试刷新 Token。
• 支持本地 PDF 内容定位和截图/图像输入。
• Legacy 直连模式暂不支持嵌入向量和 /files 上传流程。

Claude Code 配置（实验性）

Claude Code 模式会将 Claude Code 作为 Zotero 内部独立的对话系统运行。它复用侧栏和独立窗口界面，但拥有自己的 paper / open 范围状态、模型与推理设置、权限语义、斜杠命令和项目技能。Claude 对话会和其他对话显示在同一个历史列表中，并带有小的 Claude 标记。

特别感谢 @jianghao-zhang 开发了 Claude Code 集成及其桥接服务（cc-llm4zotero-adapter）。经作者同意，该桥接服务现已内置于插件中，代码位于 packages/claude-bridge。

前置条件

您的电脑上只需要准备两样东西，其余由插件完成。

• Node.js 18 或更新版本。 从 nodejs.org 下载（LTS 版本即可），或使用 NVM、Volta、Homebrew 等版本管理工具。可在终端中用 node --version 检查。
• 已安装并登录的 Claude Code。 请参考 Anthropic 官方的安装和认证指南。可以使用 Claude 订阅或 API 密钥。

1. 安装并登录 Claude Code

在终端中运行：

claude

按提示完成登录，然后关闭。只需操作一次。

2. 在 Zotero 中开启 Claude Code

打开 Zotero → 首选项 → llm-for-zotero → Agent 标签页，开启 Claude Code。推荐设置：

然后在聊天标题栏点击 Claude Code 按钮，或点击输入框中的运行时标记并选择 Claude，即可进入 Claude Code 模式。

这样就完成了。您不需要自己下载或启动桥接服务。Claude Code 模式开启时，Zotero 会启动一个小型辅助程序（“桥接服务”），把 Zotero 连接到您的 Claude Code。它只在您的电脑上运行，只响应 Zotero，并在您退出 Zotero 或关闭 Claude Code 时停止。如果从未开启 Claude Code，就不会额外运行任何程序。

Claude Code 设置顶部的 Bridge 区域会显示桥接服务是否在运行。遇到卡住时点击 Restart bridge，点击 Open log 查看桥接服务的日志。

除非您已经熟悉 Claude Code 的设置层级，否则建议保持 Config source 为 default。在 default 下，Claude Code 会同时使用您的用户级设置、Zotero 管理的项目级设置和每个对话的本地设置。其他选项：

• user-only：只使用本机的全局 Claude 设置。
• zotero-only：只使用 Zotero 管理的项目级和本地设置。

3. 如果无法使用

Bridge 状态行会用简单的话说明问题。常见原因：

从 Dock 或开始菜单打开的 Zotero，看到的程序不一定与终端相同。插件会在常见位置查找（NVM、Volta、Homebrew、~/.local/bin 和 Claude Code 安装程序的目录）；如果仍然找不到，可以使用上面两个路径设置。

高级选项

• Extra bridge options 会把命令行选项传给桥接服务，例如 --additional-directories ~/Papers 让 Claude 读取另一个文件夹，或 --append-system-prompt-file ~/zotero-claude.md。修改后请点击 Restart bridge。
• Use my own bridge 适用于自行运行桥接服务的用户，例如 Zotero 在 Windows 上运行而桥接服务在 WSL 中运行，或在另一台电脑上运行。此时 Zotero 会把 Claude 请求发送到 Bridge URL，不再启动自己的桥接服务。桥接服务的代码位于 packages/claude-bridge，手动运行方法见其 README。

从旧版 cc-llm4zotero-adapter 升级

早期版本需要单独的 cc-llm4zotero-adapter 仓库，以及 npm run serve:bridge 或 npm run daemon:*。现在已不再需要。您的 Claude Code 对话、技能和设置都会继续可用，因为新的桥接服务使用相同的 ~/Zotero/agent-runtime 和 ~/Zotero/agent-state 文件夹。

如果您安装过旧的 macOS 后台服务，可以保留，它不会造成干扰，但已不再使用。Zotero 发现它时会提示一次。要移除它，请在旧的适配器文件夹中运行：

npm run daemon:uninstall

如果已经删除了该文件夹，请改为运行下面两条命令：

launchctl bootout gui/$(id -u)/com.toha.ccbridge
rm ~/Library/LaunchAgents/com.toha.ccbridge.plist

4. Claude 项目技能与命令

Zotero 会在您的用户目录下创建 Claude 运行时根目录，通常类似：

~/Zotero/agent-runtime/profile-.../

共享 Claude 项目资产位于：

CLAUDE.md
.claude/settings.json
.claude/skills/
.claude/commands/

每个 Claude 对话还会在运行时 scopes/ 树下拥有自己的本地 .claude 文件夹，因此单个对话的本地覆盖不会泄漏到其他聊天。

模型与非 Anthropic 配置

Zotero 界面会加载 Claude Code 桥接服务提供的模型列表，并原样保留每个模型值，包括别名、明确的模型 ID、上下文窗口变体、自定义 provider 值和未来的模型系列。 聊天模型选择器会识别当前对话，因此模型发现使用与该回合相同的 .claude/settings.local.json 配置层级。 即使无法发现模型，模型首选项仍可编辑。 由 Claude Code 负责解析或拒绝所选模型值，并应用 provider 或代理配置。

MinerU PDF 解析

MinerU 是一款先进的 PDF 解析引擎，可从 PDF 中提取高保真 Markdown，同时保留表格、公式、图表和复杂版式——这些内容在标准文本提取中往往会被破坏。

解析结果会缓存在本地，并在后续对话中复用。启用 Auto-parse newly added items 后，新添加的 PDF 附件会在进入 Zotero 文库时发送给 MinerU 解析。如果不启用自动解析，也可以在 Manage Files 面板中手动解析选中或过滤后的 PDF。

MinerU 缓存是为 AI 准备的，不是第二套给人阅读的 PDF 界面。Zotero 仍然是阅读、标注和管理原始 PDF 的地方。MinerU 会生成模型更容易使用的结构化旁路材料：干净的 Markdown、章节范围、页码提示、表格、公式和提取出的图像资源。这样可以尽量不打扰原有 Zotero UI，同时为助手提供比普通 PDF 文本提取更好的论文上下文。

对于图像相关的问题，MinerU 充当定位每张图的索引，而模型实际看到的图像则是直接从原始 PDF 裁出的精准裁剪；详见精准图像提取。

启用方法

1. 打开 Zotero → 首选项 → llm-for-zotero。
2. 找到 MinerU 部分，勾选启用 MinerU。
3. 保持云端模式，或勾选 Use local MinerU server 使用本地模式。
4. 云端模式下，可选填入您自己的 MinerU API 密钥。
5. 本地模式下，运行自托管 mineru-api 服务；除非服务使用了其他地址，否则保持默认 Base URL http://127.0.0.1:8000。
6. 如果希望新导入的 PDF 自动解析，请勾选 Auto-parse newly added items。之后将 PDF 添加或导入 Zotero 文库，插件会通过 MinerU 解析新添加的 PDF 附件，并缓存结果供后续对话复用。

使用自有 API 密钥

MinerU 可通过内置 API 在没有密钥的情况下启动，但强烈建议配置个人密钥。内置 API 可能在 2026 年 6 月 1 日 之后不再受支持。

获取免费个人密钥：

1. 前往 mineru.net 注册账号。
2. 在账号设置中生成 API 密钥。
3. 将密钥粘贴到 Zotero → 首选项 → llm-for-zotero → MinerU。
4. 点击测试连接以验证。

提供个人 API 密钥后，插件将直接调用 https://mineru.net/api/v4。

使用本地 MinerU 服务

本地 MinerU 服务支持由 @renyong18 在 PR #152 中贡献。

本地模式会通过 POST /file_parse 将 PDF 发送到自托管 mineru-api 服务，并把返回的 ZIP 输出保存为与云端解析相同的本地缓存格式。默认 Base URL 为 http://127.0.0.1:8000。

本地模式前置条件：

1. 安装 MinerU 并运行 mineru-api；安装方式请参考 MinerU 文档。
2. 确保所需模型已经下载。mineru-api 会在首次请求时懒加载模型，因此启动服务后第一次解析，或切换 backend 后第一次解析，通常会比稳定状态更慢。

本地设置中可以选择 Backend：

• pipeline（默认）— 通用、多语言、对 CPU 更友好。
• vlm — 基于 VLM，对中英文文档准确率高，需要 GPU。
• hybrid — 较新的高准确率混合流程，支持多语言，需要本地算力。

Test Connection 只检查服务进程是否在 /health 响应；它不能保证所有模型已经预热完成。

自动启动和停止服务（由 @AkimioJR 在 #530 中贡献）：

• 输入启动服务的命令，例如 mineru-api。
• 插件在解析 PDF 时启动服务。
• 空闲一段时间后，插件会停止服务，以释放内存和显存。默认时间为 10 分钟。
• 首选项中会显示服务状态，并提供 Start 和 Stop 按钮。
• 退出 Zotero 时，服务也会停止。

使用默认 127.0.0.1 地址时，PDF 会留在本机。如果您把 Base URL 改为局域网或远程服务器，PDF 会被发送到该服务器。

暂停 / 取消限制： mineru-api 没有提供取消或 DELETE 端点，只提供 POST /file_parse、POST /tasks、GET /tasks/{id}、GET /tasks/{id}/result 和 GET /health。点击 Pause 后，插件会暂停队列并中止 HTTP 等待，但服务器上已经开始的解析仍会继续运行直到结束，GPU/CPU 计算不会立刻停止。如果需要立即中止，例如想立刻切换 backend，请自行重启 mineru-api 进程。

管理 MinerU 缓存

MinerU 首选项标签页包含 Manage Files 面板，用于维护已解析的 PDF 缓存：

• 按文集、标签、标题、作者、年份和添加日期浏览已缓存与未缓存的 PDF。
• 对所有可见文件、过滤后的文件或选中的文件开始解析。
• 当元数据或文件发生漂移时，修复本地 MinerU 缓存和已同步的缓存包。
• 从管理器中删除全部、过滤后、选中或单个条目的缓存。
• 使用标签过滤器，包括 Zotero 自动标签，选择哪些论文参与批量操作。

自动缓存管理是事件驱动的。插件监听 Zotero 条目添加事件，识别普通论文条目下的 PDF 附件或独立 PDF 附件，并在处理前短暂等待，让 Zotero 完成文件导入。如果 Zotero 条目已经出现，但 PDF 文件路径或父条目的附件列表还没准备好，队列会按短延迟重试，而不是立刻判定失败。已删除的附件会从队列移除，已经有缓存的 PDF 会被跳过。

自动队列和批量解析使用同一套过滤规则。它会跳过已经有本地 MinerU 缓存或可用同步包的 PDF，避免重复入队，并通过 MinerU 状态点显示 ready、processing 或 failed。普通元数据修改不会反复重解析已经完成的 PDF；modify 事件主要用于恢复正在处理、失败或文件尚未就绪的情况。

解析成功后，插件会在 Zotero 数据目录下的 llm-for-zotero-mineru/<attachmentId>/ 写入缓存。核心文件包括 full.md、manifest.json、content_list.json、提取出的图像等资源，以及记录来源的 _llm_source.json。manifest.json 是为 AI 访问设计的：它把章节标题映射到字符范围、页码提示和章节级图表，让 Agent 可以按问题读取 full.md 中相关片段，而不是每次都加载整篇论文。

写入 MinerU 缓存后，插件会清理该 PDF 旧的内存文本缓存和嵌入缓存。下一次提问会使用 MinerU 质量的文本块，并基于更好的解析文本重新生成检索数据。

高级解析过滤器可以在自动解析或批量解析前跳过文件：

• Skip files over N pages 控制 Start All、Start Filtered、Start Selected 和自动解析使用的最大页数。默认值为 100 页。
• Exclude PDFs by Filename 支持逗号分隔的子字符串，或用 /slashes/ 包裹的正则表达式，可用于排除翻译副本、补充材料或其他不希望自动解析的文件。

如果启用 Sync MinerU cache with Zotero file sync，插件可以创建包含 full.md、manifest.json、content_list.json 和提取资源的配套 ZIP 附件。同步是可选功能，默认关闭。已有本地缓存只会在您从 MinerU 标签页主动请求时同步；同步包也可以在需要时恢复缺失的本地缓存。修复流程会验证同步包的元数据和内容哈希，清理同一来源 PDF 的重复同步包，移除孤立的本地缓存，并从可用的同步 ZIP 中恢复本地缓存文件夹。

精准图像提取

当 Agent 模式回答关于某张图的问题，或保存讨论该图的笔记时，它会直接从原始 PDF 中裁剪出精准的高分辨率图像，仅将 MinerU 缓存用作索引。 只需提问 “图 3 展示了什么？”，Agent 便会从 MinerU 解析中定位该图，从原始 PDF 页面裁出干净的图像，并连同图注和各子图一起进行解读。

这与图表解读不同——后者由您自己截图。 在这里，Agent 会替您查找并裁剪图像，而保存图像到笔记时嵌入的也正是这些裁剪结果。

须知：

• 无需配置。 裁剪由插件按平台下载并管理的小型提取运行时生成，您无需自行安装 Python 或任何其他工具。
• 只提取图像，不含表格。 表格会从 MinerU 解析中以结构化 Markdown 文本读取，因此图像提取会刻意跳过表格。
• 需要 MinerU 缓存。 图像提取需先由 MinerU 解析该论文。若无缓存，Agent 会回退到仅使用图注和上下文文本，并明确告知无法提取图像。

隐私与数据流

• 标准服务商模式下，论文内容和用户消息会发送给您配置的模型服务商。
• 本地模型模式下，请求会发送到您配置的本地 OpenAI 兼容端点。
• WebChat 模式下，请求会通过浏览器扩展转发到 chatgpt.com、chat.deepseek.com 或 gemini.google.com。
• 云端 MinerU 模式下，被自动解析或手动解析选中的 PDF 会发送给 MinerU。
• 本地 MinerU 模式下，被自动解析或手动解析选中的 PDF 会发送到您配置的本地或远程 mineru-api 服务。
• 在 Codex App Server 和 Claude Code 模式下，请求会通过您本地安装的 codex 或 Claude Code 发送到 OpenAI 或 Anthropic。
• 使用通用网页搜索时，搜索词和 Agent 读取的网址会发送到您选择的服务商：Tavily、AnySearch 或 DeepSeek。
• 学术文献搜索会将搜索词和论文标识符发送到 OpenAlex、arXiv、Europe PMC、Crossref 和 Semantic Scholar。
• 对话历史、缓存的论文上下文、使用统计和 Agent 保存的文件由插件存储在本地。
• Agent 模式的写入操作会尽可能通过可审阅动作和会话内撤销机制处理。

故障排查

如果遇到 Bug 或难以判断的问题，请在 GitHub 上 提交 Issue。

路线图

• Agent 模式（beta）
• MinerU PDF 解析
• GitHub Copilot 认证
• WebChat 模式（ChatGPT、DeepSeek 和 Google Gemini 网页同步）
• 独立窗口模式（#78）
• 文件笔记（Obsidian、Logseq、任意 Markdown 目录）
• Claude Code 集成
• Codex App Server 集成
• 自定义技能
• 本地 MinerU 支持
• 跨设备同步（MinerU 缓存）
• Agent 记忆系统

常见问题

是否免费使用？

是的，插件完全免费且开源（AGPL v3）。您只需为调用所选服务商的 API 付费。使用 Codex App Server 时，ChatGPT Plus 订阅用户无需单独 API 密钥。

是否支持本地模型？

支持——任何提供 OpenAI 兼容 HTTP API 的模型均可使用，包括通过 Ollama、LM Studio、vLLM 等工具本地部署的模型。在设置中填写本地 API 地址和模型名称即可。

我的数据是否会用于训练模型？

插件本身不会训练模型。数据处理取决于您选择的后端：配置的 API 服务商、本地模型、WebChat、Codex、Claude Code 或 MinerU。

能否同时使用多个模型？

可以。配置最多 10 个服务商组，每组包含多个模型，通过模型选择器在对话中随时切换。

上下文检索是如何工作的？

首条消息会加载论文全文作为上下文，后续问题使用混合检索（BM25 + 嵌入向量搜索）并结合多样性优化，定位最相关段落，保持响应快速准确。

如何报告 Bug 或提交功能请求？

请在 GitHub 上 提交 Issue。

贡献与支持

欢迎贡献！无论是 Bug 反馈、功能请求还是 Pull Request——欢迎在 GitHub 上提交 Issue 或 PR。

如果本插件对您有帮助，欢迎：

• 在 GitHub 上给个 Star ⭐
• 请我喝杯咖啡
• 通过支付宝扫码捐赠：

Star 趋势