DeepRead 是一个免费、开源的 Zotero 插件，支持 Zotero 7–10。它把 Vibero 的 AI 精读能力做成了普通插件，可以直接装进官方 Zotero 使用：
- 不需要账号、积分或订阅。 解析和大模型服务都用你自己的 API Key。
- PDF 内容只发往你在设置里配置的服务。 插件不会连接其他任何服务器。
当前版本 v1.1.1，各版本的改动见 更新日志。
- 从 Releases 下载
deepread-x.y.z.xpi，在 Zotero 的「工具 → 插件」里从文件安装（详见下方「安装」）。 - 打开「设置 → DeepRead」，选一个大模型预设，填入 API Key，点「测试连接」。PDF 解析默认使用内置解析，不需要额外配置。
- 打开一篇 PDF，点工具栏上的「AI 精读」。完成后：
- 页边卡片会显示每一段的摘要和 AI 讲解，并用彩色标签标出这段的作用（背景、方法、结果等）；
- 工具栏下方的全文结构条显示各章节和阅读进度，点击可跳转；
- 每张图表旁边有一张图表卡片，附 AI 写的读图步骤；
- 鼠标停在段落上会显示译文：双栏论文显示在另一栏的同一高度，单栏论文显示在该段下方，大小和原段一样；
- 单击段落展开卡片，再次单击收起；
- 在卡片上点「✎」可以写下「我的理解」，点「AI」可以就这一段提问；
- 横条上的「阅读深度」可切换全文 / 重点 / 只看边注；鼠标停在引用和图表引用上会弹出说明；侧栏「阅读问题」给出 5 个问题和答案出处；
- 「带读」默认关闭，可在「功能」菜单启用，让 Agent（本地 Codex / Claude Code、远程 API 或导入的结果）带你按 定位 → 骨架 → 方法 → 证据 → 带走 五步读；
- 工具栏的「功能」菜单可以逐项打开或关闭这些功能。
| 功能 | 说明 |
|---|---|
| 「功能」菜单 | 阅读器工具栏上的「功能 n/m ▾」可以逐项勾选：页边卡片、悬停翻译、要点高亮、全文结构条、图表卡片、速读分层、悬停查证、问题导向、带读。 • 菜单顶部选「仅本文」只改当前论文，选「设为默认」改所有论文的默认设置 • 卡片字号和宽度、重新精读、生成 AI 讲解、设置、删除本文精读结果也在这里 |
| AI 精读 | 在阅读器工具栏点「AI 精读」，插件会依次完成以下步骤： • 解析 PDF 结构 • 把每个段落对齐到原文位置 • 逐页调用大模型，为每段生成摘要和要点，并给出每个要点的翻译 • 再逐页为每段写一段「AI 讲解」（用通俗的话讲这段在说什么、为什么重要、关键术语和符号的含义），边生成边填进页边卡片 |
| 悬停段落卡片 | 关闭页边卡片时，鼠标停在段落上，旁边会弹出卡片，显示段落摘要、AI 讲解、要点和折叠的译文： • 悬停某个要点，会高亮它在原文中对应的句子 • 点击要点可以切换重要度（普通 / 蓝色 / 红色），重要的要点会在 PDF 中一直高亮显示 |
| 悬停翻译 | 鼠标停在段落上，该段会加框，并显示译文，不遮挡原文： • 双栏论文：左栏段落的译文显示在右栏同一高度，右栏段落的译文显示在左栏 • 单栏论文：显示在段落正下方（下方放不下时显示在上方） • 译文框与原文等宽、尽量等高；先收紧行距，再适度缩小字号（最多约 18%，且不低于原字号与 9 CSS px 中的较小值），仍超长时可在框内滚动查看全文 • 根据原文分别保留段落、列表项、项目符号、粗体／斜体、首行缩进和悬挂缩进；同一解析框内的两个段落不再压成一段 • 图注单独定位，不再按图片高度放大文字 • 自动检查跨页或被插图打断的正文；模型确认属于同一段后联合翻译，悬停任一端显示同一份完整译文，两处原文分别定位，图注保持独立 按住 Alt 临时隐藏；拖动选字时不显示。可在「功能」菜单里关闭 |
| 点击段落打开卡片 | 精读后单击 PDF 里的段落，页边上该段的卡片会展开成完整卡片，并滚动到可见位置；还没有 AI 讲解的段落会当场生成。单击页面空白处收起。关闭页边卡片时，改为在段落旁固定显示悬浮卡片 |
| 速读卡 | 右侧栏显示 5 部分速读卡：论文标题、研究背景、核心创新点、实验结果、结论与价值。点击其中的要点，会跳回它对应的原文 |
| AI 大纲 | 右侧栏按需生成层级大纲，每一节附一句总结，点击可以跳转到该节 |
| AI 对话 | 基于全文（含页码）回答问题： • 同时参考每段的 AI 讲解和你写的「我的理解」，回答会引用对应的段落块，如 (p. 3 ¶2)，点击即跳到该段并打开它的卡片• 回答里的 (p. N) 可以点击跳转• 支持 Markdown 和 LaTeX 公式 • 对话按文献保存在本地 |
| 页边卡片 | 默认开启，可在「功能」菜单中关闭。开启后： • 每张卡片对齐对应段落，滚动和缩放时跟随。卡片主体是这一段的 AI 讲解，下面是要点；译文作为一部分默认折叠，点「▸ 译文」展开（可在设置里改为默认展开） • 连续几段讲同一件事时，AI 会把它们合并成一张卡片（标题旁标着「2 段」等），单击其中任一段打开，再次单击收起；明显截断的连续片段也会自动合并，可用「合／拆」手动修正。自动片段合并可在设置里关闭 • 默认「卡片保持展开」：打开的卡片不会因为点了别处而收起，再次点击对应原文块或单击卡片标题收起；「功能」菜单里可以一键收起全部 • 左右卡片栏顶部的小按钮可以把卡片栏收成一条窄边（例如打开右侧 AI 对话时），点窄边恢复 • 卡片左侧色带和实色标签标出这段的作用：背景灰蓝、空白橙、已有工作金、贡献紫、方法蓝、结果绿、局限红；深色模式保留区别。折叠的卡片会显示「理解」小标记 • 卡片分布在 PDF 两侧：左栏段落的卡片在左边，右栏段落的卡片在右边；单栏论文只用右侧。可在「功能」菜单或设置里改为全部放在右侧 • 卡片字号和宽度可在「功能」菜单或设置里调整，也可以拖动卡片栏靠近 PDF 的边缘调宽 • 单击摘要展开或收起卡片；双击摘要可以直接编辑；「讲」重新生成 AI 讲解 • 悬停卡片会在原文中高亮对应段落 • 卡片可以隐藏，隐藏后可在菜单里恢复。之前精读过的论文可在「功能」菜单里点「生成 AI 讲解」补上 |
| 速读分层 | 横条上的「阅读深度」： • 全文：正常显示 • 重点：次要段落淡化，重点段落的关键句加下划线，次要卡片收成一行 • 只看边注：正文淡化，所有卡片收成一行摘要 • 显示本页和全文的预计阅读时间；「下一个重点 ↓」或按 N / Shift+N 在重点段落之间跳转；「读图…」直接选择图表，先核对图注与证据 |
| 悬停查证 | 和页边卡片互相独立。鼠标停在： • 引用编号上：显示参考文献的标题、作者、年份和本文引用次数；如果已在你的 Zotero 文库中，可以直接打开 • 「Fig. 3」「Table 1」上：显示图表缩略图和读图步骤 |
| 阅读目标与记录 | 在「阅读问题」顶部选择判断相关性／理解方法／核对证据／准备复现，写下自己的目标，并直接打开相关章节或图表。个人目标、自测回答、图表证据和段落笔记可复制或存为 Zotero 笔记。重新精读会保留个人记录；段落笔记仅按原文唯一匹配重新定位，无法匹配的仍可查看和导出。 |
| 问题导向 | 精读后 AI 回答 5 个阅读问题（要解决什么问题、方法核心、关键设计、证据、局限），并标出答案所在段落： • 侧栏「阅读问题」：点段落标签跳到原文；可以输入自己的问题；可选「自测」先写自己的解释，再展开 AI 答案核对 • 卡片上显示 Q1、Q2 等标记，结构条上标出答案位置 • 工具栏「问题 n/5」显示已读到答案的问题数；可以设置读到时再揭晓答案 |
| 带读 | 工具栏「带读」打开右侧的带读面板，五步： • ① 定位：真正的主张、研究路径还原、阅读顺序、带着 3 个问题读 • ② 骨架：背景 → 空白 → 已有方案 → 贡献 → 主张，主张标出已证 / 部分 / 未证；术语账本 • ③ 方法：部件承重判断、核心思想三层、公式手算 • ④ 证据：证据链、边界检查、措辞强度 • ⑤ 带走：一句话总结、研究想法和 16 节精读卡，可存为 Zotero 笔记 每一条都链接到原文段落；带读的判断也显示在页边卡片上。由设置里的 ③ Agent 通道生成：本地 Codex / Claude Code（配合 nature-paper-xray、nature-paper-card 技能）、远程 API，或导入现成结果 |
| 自动高亮密度 | 在「功能」菜单选择本文的自动高亮密度：仅手动／少量／标准／更多。推荐优先考虑模型重要度，并参考阅读目标；切换密度保留手动标记和手动取消。 |
| 荧光笔 | 单击卡片上的要点，会依次换成第 1、2……种荧光笔颜色，最后再点一次清除，PDF 里对应的句子也会用同一颜色高亮。颜色的数量（1–6 种）和颜色本身可在「功能」菜单或设置里修改 |
| 全文结构条 | 工具栏下方的一条章节横条：每节按篇幅占位、按类型着色（引言、方法、实验、讨论、参考文献等）。 • 已读部分用深色填充，右侧显示「已读 x%」，当前章节加描边 • 点击某一节，跳到该节标题 |
| 图表卡片 | 每张图和每个表格在旁边的页边生成一张卡片（图为琥珀色，表为青绿色），拆成多个子图的图会合并成一张： • 图号、标题、正文提到它的次数和缩略图 • AI 写的 2–4 步读图步骤：先看什么、再对比什么、最后得出什么结论 • 单击正文中提到「图 3(b)」的段落，对应卡片会高亮，并标出与 (b) 相关的那一步 • 单击卡片跳到原图 • 「我的证据笔记」记录比较与测量、观察结果、结论与限制；AI 读图步骤默认折叠，可写下自己的判断后再展开 |
| 我的理解 | 在页边卡片上点「✎」，可以写下自己对这一段的理解、疑问或联想： • 「我的理解」始终展开显示，不会折叠 |
| 选段翻译 / 问 AI | 选中文字后，弹出菜单里多出两个按钮： •「翻译」：显示译文后可以复制，或存为高亮批注 •「问 AI」：把选中内容作为引用发进 AI 对话 |
- 从 Releases 下载最新的
deepread-x.y.z.xpi。 - 在 Zotero 中打开「工具 → 插件」，点齿轮图标，选「从文件安装附加组件…」，然后选中这个
.xpi文件。
之后会自动更新：Zotero 大约每天检查一次插件更新。想立即更新，可以在「工具 → 插件」里点齿轮，选「检查更新」。
也可以自己构建：npm install && npm run vendor && npm run build，产物在 build/ 目录下。
设置页分为三个通道：① 精读 API、② 文档解析、③ Agent，另有「功能模块」和「阅读」两组选项。
任何 OpenAI 兼容接口都可以用。插件内置了以下服务的预设：
- DeepSeek
- 阿里云百炼
- 智谱
- 火山方舟
- 硅基流动
- OpenRouter
- OpenAI
- Ollama 本地
选好预设后填 API Key 即可，然后点「测试连接」确认。
可以保存多组配置（例如一组 DeepSeek、一组本地 Ollama），点配置卡片即可切换，类似 CC Switch。用「+ 添加」「复制」「删除」管理配置，在「配置名称」里重命名。精读、AI 讲解、图表卡片、翻译和对话都使用当前选中的配置。
关于「JSON 模式」：
- 默认选
json_object，兼容性最好。 - 如果服务商支持严格 JSON Schema，可以改成
json_schema。 - 如果服务商不支持你选的模式，插件会自动降级。
有四种方式，点卡片选择，默认使用内置文字层：
- 内置文字层（推荐）：直接用 PDF 自带的文字层识别段落、标题、图表和公式。不需要任何服务，免费、离线、一篇论文约 1 秒。扫描版 PDF 没有文字层，无法使用精读功能。
- GROBID 本地服务：专为学术论文设计，只需 CPU 和约 1–2 GB 内存。用 Docker 启动：
scripts/grobid.sh start（当前用户需要在 docker 组里）。服务地址默认是http://127.0.0.1:8070。 - MinerU 官方 API：在 https://mineru.net/apiManage 申请 Token 后填入。免费额度以官网为准。
- 自建或第三方 MinerU 兼容服务：填入
mineru-api的地址（插件会调用POST /file_parse）。如果服务需要鉴权，再填 Token。
选中的服务连不上或出错时，会自动改用内置文字层，精读不会中断。
「带读」由这个通道生成，四种方式任选：
- Codex / Claude Code（本地）：点「带读 → 运行带读」后，DeepRead 在数据目录下建一个工作目录，写入论文文本
paper.md（每段带[p. 3 ¶2]标签），再运行本机的 Codex 或 Claude Code。Agent 按勾选的技能（默认 nature-paper-xray、nature-paper-card）写出xray.md和paper-card.md。- 默认命令：
codex exec --skip-git-repo-check --sandbox workspace-write --cd {workdir} {prompt}，以及claude -p {prompt} --permission-mode acceptEdits --allowedTools … --add-dir {skills}。 - 「命令」一栏可以改成完整路径或自己的参数，
{prompt}、{workdir}、{skills}会被替换。 - Agent 用它自己的账号和模型，PDF 只在本机交给它。
- 默认命令：
- 远程 API：填一个 OpenAI 兼容接口和模型（可以和精读 API 不同，例如更强的推理模型），一次请求写出长文和精读卡。
- 导入：选择一个已有的精读卡 / 长文 Markdown，或 DeepRead 的带读 JSON。
- 生成的 Markdown 最后由「精读 API」整理成五步，并对应到原文段落。
「检测」会检查命令和技能文件是否存在，不会运行任何程序；只有在带读面板里点「运行带读」才会启动 Agent。超时默认 10 分钟。
- 功能模块：页边卡片、悬停翻译、全文结构条、图表卡片对所有论文的默认开关。单篇论文可以在阅读器工具栏的「功能」菜单里单独打开或关闭。
- 选择摘要、讲解和翻译的输出语言。
- 选择是否显示高亮和悬停卡片。
- 页边卡片：卡片宽度（200–520 px）、卡片字号（10–18 px）、卡片位置（自动，或全部放在右侧）、精读后是否自动生成每段的 AI 讲解、卡片是否保持展开、是否把相关段落合并为一张卡片、荧光笔颜色、译文是否默认展开。
- PDF 解析：内置解析和 GROBID 都免费。只有使用 MinerU 官方 API 时，才按页计费或计入免费额度。
- 大模型：
- 精读：每页 1 次请求生成摘要、要点和译文；另有 1 次请求生成速读卡，1 次请求过滤作者信息块。
- 续段合并：仅对跨页／跨图的候选边界追加确认与联合翻译请求，每批最多 4 组；旧缓存首次打开时自动补处理，成功检查后不会重复请求。模型不能确认时保留分段；失败不影响原译文。
- AI 讲解：精读后每页再发 1 次请求（可以在设置里关闭自动生成）。单段重新生成或补生成，每段 1 次请求。
- 图表卡片：精读后为全部图表生成读图步骤，每 6 张图表 1 次请求。关闭图表卡片就不会发送。
- 问题导向：精读后 1 次请求生成 5 个问题；自己提的问题每个 1 次请求。
- 悬停查证：引用和图表查证不需要大模型请求。
- 带读：本地 Codex / Claude Code 用它们自己的账号计费；远程 API 每次带读 1 次（较长的）请求；之后精读 API 再用 1 次请求整理成五步。导入结果只需要整理这 1 次。
- 选段翻译：每次 1 次请求。
- AI 大纲需要你手动生成，每次 1 次请求。
- AI 对话每发一句消耗一次请求。上下文默认最多带 12 万字符，包括全文和各段的 AI 讲解；可以在设置里调小。
| 数据 | 位置 |
|---|---|
| 精读结果、AI 讲解、读图步骤、阅读问题、带读、我的理解和对话 | Zotero 数据目录下的 deepread.sqlite |
PDF 解析结果（content_list.json、full.md） |
Zotero 数据目录下的 deepread/mineru/<库ID>_<条目Key>/ |
带读的工作目录（paper.md、Agent 写出的 xray.md、paper-card.md） |
Zotero 数据目录下的 deepread/agent/<库ID>_<条目Key>/<时间>/ |
| API Key | Zotero 本机偏好设置，以明文保存 |
要删除某篇文献的结果，在工具栏「功能」菜单中选「删除本文精读结果」。
npm install && npm run vendor # 拷贝 marked / KaTeX 到 addon/content/lib
npm test # 全部单元测试（CI 也运行这一组）
python3 test/build-fixture.py # 生成离线测试用的 MinerU 夹具
scripts/e2e.sh test/e2e/basic.js # 在隔离的无头 Zotero 10 中跑端到端测试（假 MinerU + 假大模型）
scripts/e2e.sh test/e2e/ui.js # 设置页 / 工具栏 UI
scripts/e2e.sh test/e2e/cards.js # AI 讲解卡片、卡片大小、悬停翻译、对话上下文
scripts/e2e.sh test/e2e/interact.js # 悬停翻译排版、单击段落打开卡片
scripts/e2e.sh test/e2e/v08.js # 「功能」菜单、段落角色、全文结构条、图表卡片、解析回退
E2E_PARSER=builtin E2E_PDF2=$PWD/test/fixtures/twocol/<双栏论文>.pdf scripts/e2e.sh test/e2e/v081.js # 双栏悬停翻译、合并卡片、保持展开、荧光笔、收起卡片栏
E2E_PARSER=builtin scripts/e2e.sh test/e2e/v09.js # 速读分层、悬停查证、问题导向
scripts/e2e.sh test/e2e/v10.js # 带读：本地 Agent（test/fake-agent.mjs 代替 Codex）、远程 API、导入、取消与失败、存为笔记
E2E_BASE_XPI=old.xpi E2E_UPDATE_XPI=new.xpi scripts/e2e.sh test/e2e/upgrade.js # 带着打开的 PDF 原地升级
E2E_SKIP_SERVICES=1 E2E_PDF="$PWD/test/fixtures/reading/typography.pdf" scripts/e2e.sh test/e2e/readingFlow.js # 阅读体验与功能移除回归
npm run build # 打包 build/deepread-<version>.xpi
npm run release -- X.Y.Z # 发布新版本：测试 → 打包 → GitHub Release → 更新 update.json发布前先在 CHANGELOG.md 里写好 ## vX.Y.Z 一节。发布脚本会把这一节放进 GitHub Release 的说明。
端到端测试共用 .test-profile/，不要同时运行多个。
自动更新：manifest.json 中的 update_url 指向本仓库 main 分支上的 update.json。发布脚本会先上传 .xpi，再在 update.json 里登记这个版本，避免出现指向不存在文件的更新链接。
端到端测试使用 .test-profile/ 下独立的配置目录和数据目录，不会读写你自己的 Zotero 资料库。
原文结构保留与 RetainPDF 参考实现见 TRANSLATION_LAYOUT.md。旧缓存会自动恢复结构，缺失的分段译文沿用现有 API 按需补齐。
阅读方法的网络调研见 READING_METHODS.md，实现与验证边界见 READING_EXPERIENCE.md。旧精读缓存的字号修复即时生效；原文强调、图注精确定位和模型要点重要度需要「重新精读」生成新结果。旧缓存的卡片合并、点击收起、框尺寸适配和本地推荐高亮即时生效；跨页／跨图的联合翻译会在已有精读 API 可用时自动补齐，无需整篇重新解析。
各模块的约定和接口见 docs/DEV_NOTES.md，流水线移植说明见 docs/PIPELINE_PORT.md。
- 本插件采用 AGPL-3.0-or-later 许可，见
LICENSE。 - 解析与提示词流水线移植自 Vibero。Vibero 是 Zotero 的 AGPL-3.0 分支，著作权归原作者所有。本插件不使用 Vibero 的名称、标识或任何服务。
- 本插件基于 Zotero（AGPL-3.0）开发。
- 打包了 marked（MIT）和 KaTeX（MIT）两个第三方库，详见
NOTICE.md。 - v0.4–v0.5 的整篇翻译借鉴并移植了 ReadFlow / RetainPDF（MIT）的部分实现，这部分在 v0.6.0 中已移除，代码保留在
v0.5.0标签中。v1.1.1 的悬停翻译适配了 RetainPDF 的结构与缩进规则，归属和 MIT 许可见NOTICE.md。