DSH Zotero Reader
DeepSeek Harness 的本地 Zotero 论文阅读插件。在同一个工作区里阅读 PDF、浏览连续文本、双击定位原文，并使用 DSH 当前模型解释文字和图片。
下载发布包 · 反馈问题 · 首次配置指导
当前版本 0.3.0，主要在 Windows 桌面端验证。依赖 DSH 的会话、右侧栏和附件接口，其他版本或平台需验证兼容性。这是安装到 DSH 的插件，不是 Zotero 的 .xpi 扩展。
功能
| 功能 | 说明 |
|---|
| Zotero 文献库 | 按文件夹组织和折叠，搜索文献，显示当前打开的论文 |
| PDF 阅读 | 连续滚动、缩放、全文搜索、章节目录、缩略图 |
| 文本阅读 | 连续向下滚动、统一字号调整、默认收起章节目录 |
| 双击定位跳转 | PDF 双击切到对应文本，文本双击回到原 PDF 的对应区域 |
| 划词工具条 | 星星直接解释、翻译、高亮、下划线、删除线、复制和引用 |
| 图片与截图 | 文本图片右键操作；PDF 和文本均支持矩形截图 |
| 独立标记 | PDF 与文本分别保存高亮，互不覆盖 |
| 中英对照 | 按页翻译正文，优先处理当前阅读页 |
| MinerU 增强 | 当前页或整篇增强、本地缓存、切换解析结果、取消任务 |
安装
需要已安装的 DSH 和 Zotero。只阅读 PDF 无需 Python；生成文本需要 PyMuPDF，MinerU 与整篇 PDF 翻译属于可选能力。
Release 发布包
- 在 Releases 下载
.tgz 插件包。
- 在 DSH 插件管理中添加发布包的下载链接，或下载到本机后的包路径。
- 启用插件，重启 DSH，在侧栏打开 论文阅读。
支持命令行的 DSH 安装也可使用：
dsh plugin --profile desktop add "https://github.com/Hydralune/dsh-zotero-reader/releases/download/v0.4.0/ggboy123-dsh-zotero-reader-0.4.0.tgz"
Web profile 将 desktop 改为 web。安装后检查启用状态，并重启相应 profile。
发布包包含 dist/ 和 lib/client.js，不需要用户自行编译。当前未以 Hydralune 名义发布到 npm，不要把 GitHub 仓库名当作 npm 包名安装。包内保留 @ggboy123/dsh-zotero-reader 这一兼容标识，GitHub 版本由本仓库维护。
从源码开发安装
需要 Node.js 22.19+ 或 24+，完整版本约束见 package.json。
git clone https://github.com/Hydralune/dsh-zotero-reader.git
cd dsh-zotero-reader
npm install --legacy-peer-deps
npm run typecheck
npm run build
npm test
在 DSH 插件管理中添加该目录的绝对路径，启用并重启。组合层配置见 cordis.patch.yml。仓库保留运行所需的构建产物；修改源码后需要重新构建。
首次配置
首次打开会显示初始化窗口；后续不会每次强制引导。需要调整时，从顶部 初始化配置 重新打开。
- 检测 Zotero：默认读取用户目录下的
Zotero，其中应包含 zotero.sqlite 与 storage/。
- 选择解析器：基础文本使用 PyMuPDF，需要复杂版面增强时再安装 MinerU。
- 选择翻译方式：复用 DSH 当前模型，或填写独立 OpenAI 兼容端点的 Base URL、模型名和 API Key。
- 点击 重新检测，确认所需能力可用，再点击 完成设置。
点击 交给 Agent 配置，可以将 SETUP-AGENT.md 中的指导放入 DSH 对话。发送后，由 Agent 检查环境、说明依赖并询问 API 偏好。该按钮不会自动完成所有安装，也不会替用户申请 Key；Key 可以在本机初始化窗口填写。
自定义 Zotero 目录的组合层示例：
- insert:
- id: dsh-zotero-reader
name: '@ggboy123/dsh-zotero-reader'
config:
zoteroDir: 'D:/Library/Zotero'
请替换为自己的真实数据目录，不要另建一个空目录冒充文献库。
阅读与双击跳转
先在 DSH 打开或选择一个会话，再从侧栏进入 论文阅读。阅读器停靠在右侧，对话保留在原来的会话区域。
- 文献：展开文件夹、搜索标题/作者/年份，点击条目打开论文。当前论文会显示为选中状态。
- 目录：按章节定位；文本端目录默认收起，可手动展开。
- 缩略图：快速找到目标 PDF 页面。
- PDF / 文本：切换原版式与连续文本视图。
双击在 PDF 与文本之间定位
| 当前视图 | 操作 | 结果 |
|---|
| PDF | 在目标文字位置双击 | 切换到文本视图，定位到对应页和邻近段落 |
| 文本 | 双击段落 | 回到原始 PDF，定位并短暂标示原文区域 |
| 文本中的原文图片、表格或公式 | 双击图片区域 | 回到 PDF 中的对应区域 |
定位提示约 0.5 秒淡出，不会保存成永久高亮。普通拖动用于划词选择，视图定位使用双击，避免单击干扰选中。
双击跳转需要处于文字选中模式。 截图模式会接管点击与拖动，请先切回文字模式。定位精度依赖解析结果的页码和区域坐标；扫描件或缺少坐标的外部导入结果，可能只能定位到页面或邻近段落。
划词、解释与引用
一键解读整篇论文
顶栏的「文档＋星星」图标只占一个按钮位置。单击即可把当前原始 PDF、逐页全文、本地路径和解读规则发送到当前会话；PDF 与文本视图均可使用。已有解析结果会复用，未解析时直接提取 PDF 文字，不会为此启动 MinerU。
- 默认快捷键：
Alt+Shift+S（在非输入区域使用）。
- 右键图标打开编辑面板；键盘聚焦按钮后也可按
Alt+Enter。
- 可修改完整提示词、录入新快捷键、清除快捷键或恢复默认，保存后在本机保留。
- 默认采用通用学术解读框架，覆盖摘要与结论翻译、结构、背景问题、假设、创新、证据链、方法结果、论述质量、局限价值，以及约 150 字总结、20 字以内核心贡献和关键词。
解读使用独立发送路径，保留聊天输入框里的未发送文字、附件和其他待引用。全文说明与原始 PDF 会一起发送，图表、公式和扫描页以 PDF 原页为准。
选中文字
在 PDF 或文本中拖动选择文字，会出现浮动工具条。
| 按钮 | 行为 |
|---|
| 星星：解释 | 直接发送给 DSH 当前会话的 AI，询问内容含义及其在论文中的作用，无需再输入问题 |
| 翻译 | 显示选中段落的中文翻译 |
| 高亮 / 下划线 / 删除线 | 保存当前视图的标记，支持选色 |
| 复制 | 复制选中文字 |
| 引号：引用 | 将内容附加到对话草稿，等待用户发送 |
待引用长条
选中文字时，对话输入框显示灰色 待引用 摘要。点击勾或工具条的引号后，转为正常颜色的 已引用 长条；点击 × 可移除。
可以继续输入自己的问题再发送；如果直接发送引用，附件中提供默认解释要求。界面只显示来源、页码和摘要，不展开完整提示词。内容在底层使用 DSH 原生附件传递。
星星直接发送，引号只准备引用。 直接解释使用独立提交路径，不会把输入框里其他未发送的问题和附件一起发送，也不会覆盖它们。会话、上传或模型提交失败时会显示错误。
PDF 与文本端的高亮分别保存；双击定位产生的短暂提示，也与手动高亮分开。
图片右键与截图
文本图片右键
对已加载的原文图片右击，可以选择：
- 解释：直接发送图片给 AI。
- 引用：将图片及来源附加到当前问题。
- 复制图片：复制 PNG 到剪贴板。
- 下载图片：保存 PNG。
以原图显示的表格和公式也支持同样操作。图片加载中请稍候；双击图片可以回到 PDF 查看原图。
矩形截图
- 在 PDF 或文本工具栏切换到 截图选中模式。
- 按住鼠标左键拖动，形成矩形区域。
- 框选后出现灰色待引用截图条，可以勾选确认引用，也可直接点击工具条的星星解释。
- 工具条同时支持引用、复制、下载和取消。
截图模式下普通划词与双击跳转暂停。图片解释取决于 DSH 当前模型及其图片处理能力。
文本解析：PyMuPDF 与 MinerU
建议先使用 PyMuPDF 快速原文 开始阅读，对复杂页面再增强。文本可以连续向下滚动，不需要逐页切换才能阅读后续内容。
在文本工具栏打开 解析方式：
- 快速原文 · PyMuPDF：切换到基础文本。
- MinerU · 打开增强全文：有缓存时直接恢复增强结果；没有缓存时才启动整篇解析。
- 重新解析当前页：只增强当前页，保留其他页面已有内容。
- 重新解析整篇：明确重新处理全文。
增强结果保存在本地。切回 PyMuPDF 不会删除 MinerU 结果，再次打开论文也优先读取已保存的增强版本。进度提示可隐藏，任务可以取消。
当前接入并验证的 MinerU 版本为 4.1.5，初始化中可选择 Flash / Basic / Standard / Advanced。冷启动需要加载模型，复杂公式与整篇解析可能较慢；GPU 也不保证每页更快，首次运行还可能需要下载模型。
图表和独立公式优先保留原 PDF 区域，以减少符号识别或表格重排错误。正文支持 Markdown、公式和部分 MinerU HTML 格式标签。复杂版面仍可能裁切不完整，不能保证所有论文都完美解析。
| 环境变量 | 用途 |
|---|
LR_PYTHON | 基础文本解析的 Python 解释器 |
LR_MINERU_PYTHON | 独立 MinerU 解释器 |
LR_PDF2ZH_PYTHON | 可选的 pdf2zh 解释器 |
DSH_HOME | DSH 数据根目录，默认是用户目录下的 .dsh |
推荐将依赖安装在 <DSH_HOME>/.dsh-lr-reader/env/ 独立环境中。环境变量更改后需重启 DSH。安装与 Windows DirectML 冲突排查见 首次配置指导。
翻译与导入 PDF
文本中英对照
在文本视图开启 中英对照，按页翻译，优先当前页并预取相邻页。原文可以先阅读，不必等待整篇完成。字号按钮统一调整正文大小，章节目录可按需展开。
保留版式的整篇 PDF 翻译
整篇译文 PDF 使用可选的 pdf2zh v1 环境，需要独立的 OpenAI 兼容端点。它与文本逐页翻译是不同的处理路径；不需要整篇译文时可以不安装。速度、字体和版式质量受引擎、文档与 API 服务影响。
导入新 PDF
在文献抽屉选择目标位置，点击 导入 PDF。需要运行中的 Zotero 桌面端，本机 Connector 服务使用 127.0.0.1:23119。文件经 Zotero 导入文献库后，插件重新扫描并尝试生成基础文本。
插件不直接改写 zotero.sqlite；同步到其他设备仍由 Zotero 自身的账户与同步设置负责。
数据与隐私
<DSH_HOME>/.dsh-lr-reader/
env/ 可选的独立 Python 环境
md/ 基础文本、MinerU 结果与翻译缓存
notes/ PDF 高亮与文本标记
setup.json 首次配置状态与解析偏好
welcome-seen 首次引导记录
pdf2zh.json 独立 API 的 Base URL、模型与 Key
- 基础解析和本地 MinerU 在本机运行；文献默认从本机 Zotero 读取。
- 引用附件由 DSH 管理。点击解释、提交引用或启动翻译后，相关内容会进入对应模型流程；是否发往云端取决于用户选择的服务。
- API Key 保存在本机文件中，不随插件发布。本地配置不是加密保险箱，请勿提交到 Git。
- 删除插件不会自动删除 Zotero 文献。备份或迁移阅读标记时，也应保留插件数据目录。
常见问题
没有文献？ 检查 zoteroDir 是否包含数据库与 storage/，再重新扫描。列表以有 PDF 附件的条目为主。
文本无法生成？ 打开初始化重新检测 PyMuPDF，或指定 LR_PYTHON。只安装插件不会自动安装 Python 和模型。
MinerU 太慢？ 先读 PyMuPDF 文本，再增强当前页；已有结果使用“打开增强全文”，不要反复点击重新解析。
双击不跳转？ 退出截图模式，确认文本已生成。外部导入结果缺少坐标时，精确定位受限。
星星提示没有会话？ 在 DSH 打开会话或选择工作区，并配置可用模型。
无法复制图片？ 当前桌面或浏览器需支持图片剪贴板写入，也可先下载 PNG。
升级后还是旧按钮？ 完全重启 DSH，检查插件的版本和启用状态。
提交 Issue 时请附上 DSH/插件版本、系统、解析器版本、复现步骤与脱敏截图，不要提交 API Key 或未经授权公开的论文。
开发与验证
npm run typecheck
npm run build
npm test
# 可选：使用自己有权使用的 PDF 验证解析
npm run test:markdown -- /absolute/path/to/sample.pdf
# 生成可安装包
npm pack
客户端源码在 src/client/，宿主逻辑在 src/*.ts，Python 桥接脚本在 scripts/。开发预览和契约测试页面在 test/，预览 bundle 不进入发布包。
单元测试与浏览器模拟检查交互、解析数据和提交契约，不能替代实际 DSH 环境验证；上游升级后尤其应复核插槽、会话绑定和模型接口。
许可与致谢
使用 MIT License，保留原作者 GGboya 的版权声明，Hydralune 维护本仓库的扩展和修复。项目沿用了 dsh-paper-reader 的插件基础与相关设计，并参考 LightRead 的选区几何处理思路。
第三方依赖许可见 THIRD_PARTY_NOTICES.md 和 vendor/LICENSE-*。
