GGboya/dsh-paper-reader

dsh-paper-reader

npm version
npm downloads
license
GitHub stars

English: README_EN.md

DeepSeek Harness (dsh) 插件：论文伴读工作台 —— PDF 转录 / 检索 + 原生对话伴读 + 内置阅读器。

👉 普通用户不用看这一页。 如果你只是想装一个能用的 App，请直接去 PaperReader 论文伴读桌面版 —— 那是把本插件预装好的桌面应用，下载 DMG 拖进「应用程序」就能用，不需要任何环境。本仓库面向的是想自己装插件、或想改代码的用户。

功能迁移自本地独立产品 pdfqa（Go 实现的论文伴读工具）。原则：agent 循环 / 模型层 / 会话持久化全部交给 dsh 框架，插件只做「转录 + 检索 + 阅读器 UI」的薄壳组合。

安装后不改动官方界面 —— 侧栏底部多一行「📚 论文伴读」开关，点击才进入伴读模式（左侧变为文献库树），再点即还原官方工作区列表：

演示：选中即问 → 回答带页码 → 点页码跳回 PDF 并高亮原文

默认安装：官方侧栏原样，只多一行开关

伴读模式：文献库 + PDF 阅读器 + 原生对话

功能

- 📚 侧栏文献库树：「论文伴读」模式开启时接管工作区侧栏，专题 → 论文两级；支持新建专题、上传 PDF（默认关闭，不覆盖官方界面）
- 💬 原生对话伴读：点击论文即在右侧打开它的 dsh 原生会话（流式 / 工具卡 / 用量条全是官方 UI）；默认只呈现当前对话，对话列头部的 🕐 下拉回看历史对话（真实标题+日期，点哪条进哪条），＋ 新建对话
- 🔗 会话绑定论文：会话 id 编码文献身份，工具调用自动定位当前论文——直接在输入框提问无需点名论文，回答必带页码
- 🤖 专用 agent preset「论文伴读」：paper 会话自动使用专用 preset —— 像老师一样带读：制定分步阅读计划（每步带页码和思考题）→ 逐节指导、点评 → 出题检验、逐题批改 → 成绩与薄弱点记入 .study.json 学习档案，跨会话累积；快速问答（选中即问）则直接回答，不上课
- 📖 PDF 阅读器居中：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局
- 💬 选中即问：阅读器里选中文字 → 弹出提问框 → 注入当前会话，原生对话区实时回答
- 📍 引用定位：回答里的「第 N 页」可点击，平滑跳回 PDF 对应页并闪烁
- 🀄 中英切换：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 translate 端点；无需预装 Python——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS / Linux / Windows，约几分钟），全程落在用户目录
- 🔍 PDF 转录 + 检索：本地提取（pdf.js，纯 Node 无需 Python），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；可选接入 TypeSafe/Jev 语义重排（设置面板填端点即启用，不配置时退回纯关键词排序）；兼容 pdfqa 的 data/ 缓存布局（旧缓存读取时自动补建页码索引）

安装

方式一：PaperReader 桌面版（一键安装，推荐普通用户）

PaperReader 是把本插件预装好的桌面应用（基于社区桌面客户端 DSH Desktop 打包）：

1. 从 Releases 下载 DMG（macOS Universal,Intel / M 系列芯片都行；Windows 版打包中）
2. 打开 DMG，把 PaperReader 拖进「应用程序」
3. 首次打开用 右键 → 打开（免签名发布，只弹这一次）；首次启动有几分钟一次性初始化

打开就是文献库 + 阅读器 + 伴读对话，不用再执行任何命令。

方式二：已有 DSH Desktop，自己装插件

如果你已经在用 DSH Desktop（社区的 DeepSeek Harness 桌面客户端，macOS / Windows，开箱即用，不需要装 Node.js），可以把本插件装进去：

1. 下载安装 DSH Desktop 并启动
2. 托盘菜单 → Open DSH Terminal（终端里自带 dsh/pnpm，只对那个终端生效）
3. 执行 dsh plugin add @ggboy123/dsh-paper-reader@1.1.0
4. 退出并重开 DSH Desktop（插件变更要重启才进 Loader 组合）

已在 DSH Desktop 2.0.13（内置 dsh 0.1.5-rc.2）上实测通过：侧栏文献库、PDF 阅读器、选中即问、页码跳转、原生对话伴读、翻译引擎自动安装（uv + Python + babeldoc 全程落在用户目录）全部可用。
注意：Desktop 的 desktop profile 被 Electron 独占管理，外部 CLI 直接 dsh plugin --profile desktop add 会被拒（managed exclusively by the Electron application）——必须从 Desktop 自己的终端进。

方式三：命令行 dsh（开发者）

dsh plugin --profile web add @ggboy123/dsh-paper-reader

npm 包名走 @ggboy123 作用域：裸名 dsh-paper-reader 已被另一个插件占用（那是「输入文献、吐精读报告」的一次性分析工具，与本插件的「阅读器 + 会话伴读」定位不同）。
不要用 github:GGboya/dsh-paper-reader 安装 —— dist 不入库，git 安装会导致 profile 起不来（构建产物只随 npm 包分发）。

升级

已装过的用户升级必须带显式版本号——不带版本的 add 对已存在的依赖是 no-op（pnpm 按首次安装时记录的版本范围解析，不会追新）：

dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.1.0
重启 dsh web 生效；浏览器 Cmd+Shift+R 强刷，避免旧阅读器页面缓存

确认当前装的是哪个版本：

grep '"version"' ~/.dsh/profiles/web/node_modules/@ggboy123/dsh-paper-reader/package.json

pnpm 若开了供应链策略 minimumReleaseAge（发布 N 小时内的新包拒装）：要么等过窗口期，要么在 ~/.dsh/profiles/web/.npmrc 加一行 minimum-release-age-exclude[]=@ggboy123/dsh-paper-reader（只豁免本插件，不动全局策略）。

本地开发：

git clone https://github.com/GGboya/dsh-paper-reader
cd dsh-paper-reader && pnpm install && pnpm run build
dsh plugin --profile web add ./dsh-paper-reader   # 从父目录执行，或用绝对路径
dsh --profile web                                  # 侧栏变为文献库树

文献库目录默认 ~/.dsh-paper-reader/data；在 profile 的 cordis.patch.yml 里可改：

- id: dsh-paper-reader
config:
dataDir: /path/to/pdfqa/data   # 直接指向 pdfqa 文献库即可复用全部缓存
translate:                    # 可选：生成中文版（babeldoc）用的 OpenAI 兼容端点。
baseUrl: https://api.deepseek.com/v1   # 一般不用写在这里——阅读器里点「中」
apiKey: sk-...                          # 或右上角 ⚙ 可直接填，存到
model: deepseek-chat                    # ~/.dsh/.dsh-paper-reader/translate.json（0600）

中文版端点：优先在阅读器 UI 里填（点「中」→ 没配会自动弹表单，或点 ⚙）——填完会先测连接再落盘，不用重启。
上面的 translate 配置退为部署方默认值，仅当 UI 未配置时生效。babeldoc 只支持 OpenAI 协议端点，
Anthropic 协议的端点（如 api.kimi.com/coding/）不能直连。

翻译引擎零预装：找不到 babeldoc 时自动走 uv 链路安装——uv 独立二进制（GitHub Releases API 下载 + sha256 校验）→
uv 托管 Python 3.12 → uv pip install babeldoc，落在 ~/.dsh/.dsh-paper-reader/bin/ 与文献库同级 .venv-pdf2zh/，
不碰系统 Python。已装有 uv / babeldoc（含 pdfqa 的 .venv-pdf2zh）则直接复用。macOS / Linux / Windows 均支持自动安装（Windows 走 uv 的 zip 包 + 系统自带 tar 解包）。

伴读模式是按需开启的：默认不注册 sidebar.workspaces（官方工作区/会话列表原样），侧栏底部「📚 论文伴读」开关点击才接管，再点还原；模式选择记在 localStorage。退出模式时已打开的 PDF 页签和伴读会话不受影响。

架构

src/
index.ts      Cordis 壳：inject tools；webServer 等服务就绪后挂路由
tools.ts      5 个 agent 工具：list_papers / transcribe_pdf / search_paper / study_progress / study_update
host.ts       webServer 路由（/paper-reader/*），connection.requestRejection 鉴权；
sessionController.create/prompt（agentPreset=paper-reader）+ follow SSE 桥
library.ts    纯函数：文献库目录约定与解析
transcribe.ts 纯函数：pdf.js 提取 + 页码偏移表（视觉兜底后置）
search.ts     纯函数：分段 + 关键词打分 + 页码映射
study.ts      纯函数：学习档案（计划 + 检验成绩）读写
translate.ts  纯函数：babeldoc 调用（中文/中英对照 PDF 生成）
babeldoc-install.ts 纯函数：无 Python 环境时自动安装 babeldoc（uv → 托管 Python → venv）
translate-config.ts 纯函数：翻译端点配置读写（$DSH_HOME 下 0600）+ 保存前连接预检
rerank.ts     纯函数：search_paper 语义重排（TypeSafe/Jev，无凭据时退回关键词排序）
typesafe-config.ts 纯函数：TypeSafe 端点配置读写（与翻译配置同一套约定）
preset.ts     纯函数：自带 agent preset 安装到 $DSH_HOME/.agent-presets/
presets/paper-reader/  「论文伴读」agent preset（persona 完整提示词 + compaction）
reader/index.html      阅读器页面（pdf.js，独立于 React 宿主，iframe 承载）
lib/client.js          浏览器半边：文献库树(sidebar.workspaces 接管) + PDF 页签 + 主面板

许可证

MIT