论文批量下载 QiuShanLing/dsh-paper-fetch

dsh-paper-fetch

中文 · English

DSH（DeepSeek Harness）插件：从你所在机构图书馆订阅的数据库（IEEE Xplore / EI）按 DOI 或链接批量下载论文 PDF。它自己开一个专用 Chrome 走真实浏览器会话，串行限速、断点续传；机构登录失效时用会话内问题卡 + Windows 系统通知提醒你。

前提条件（先看这条）

- 你所在机构订阅了 IEEE Xplore / EI，并且你能用机构身份登录（CARSI 统一身份认证等）。
没有订阅就用不了。 本插件不绕过付费墙 —— 它的作用等价于你自己在 IEEE 页面上点「Download PDF」，只是把这件事批量、可续传地做掉。
- 插件不接触你的学号密码：登录只发生在它弹出的 Chrome 窗口里，插件只复用那个浏览器自己的会话。
- Windows + 本地已装 Google Chrome（自动探测，或用环境变量 PAPER_FETCH_CHROME 指定 chrome.exe）。

为什么要真的开一个 Chrome：IEEE 对裸 HTTP 请求和非浏览器 UA 直接返回 418，必须用真实浏览器；而 Chrome 的登录 cookie 无法离线解密，所以插件用自己独占的配置目录起一个实例，登录和下载共用它，不碰你日常用的 Chrome。设计取舍与实测记录见 docs/design-notes.md。

快速安装（命令行，推荐）

1. 打开终端，跑（dsh 不在 PATH 时用完整路径 %LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd）：

dsh plugin --profile desktop add github:QiuShanLing/dsh-paper-fetch

dsh plugin --profile <name> 后面的参数会原样转发给该 profile 目录里的 pnpm，所以 add <包> 直接跟在后面即可。从 GitHub 装需要本机有 git 与可用网络；如果仓库是私有的，还得确保本机 git 已经能访问它（配好 SSH key 或凭据），否则 pnpm 拉不下来。
2. 确认 dsh.profile.bundles 里有 dsh-paper-fetch：打开 %USERPROFILE%\.dsh\profiles\desktop\package.json 看一眼，没有就手工加进 dsh.profile.bundles 数组。

这一步不能省。据 DSH 0.2.0-rc.2 的实现，dsh plugin 只是把参数转发给 pnpm， 跑完不会回写 dsh.profile.bundles（负责回写的 reconcileProfilePlugins 在该版本的安装包里没有任何调用者）。漏掉它的表现就是「依赖装了但插件加载不到」。你若是别的 DSH 版本，以实际为准 ——打开 package.json 查一眼最稳。
3. 重启 DeepSeek Harness（配置改动要重启才生效）。
4. 对模型说一句：用 paper_status 自检一下论文下载插件。看到输出目录、Chrome、IEEE 那几行就装好了。

手动安装 / 本地开发（install.ps1）

要把本地目录（而不是 GitHub 上的版本）挂进 profile、或者命令行不可用时，用插件自带的脚本：

1. 先关掉 DeepSeek Harness。
2. 在插件目录里跑：

cd <本插件目录>
.\install.ps1 -DryRun # 试运行：只打印要改什么，不写文件、不装依赖 .\install.ps1 # 正式安装

它会做三件事：把本插件以 link: 形式加进 %USERPROFILE%\.dsh\profiles\desktop\package.json 的 dependencies；并把 dsh-paper-fetch 写进 dsh.profile.bundles（也就是替你做了上面第 2 步那次检查）；最后用 DSH 自带的 node + pnpm 跑一次 pnpm install。
原 package.json 会先备份为 .bak-paper-fetch-<时间戳>。
3. 重启 DeepSeek Harness，然后同样用 paper_status 自检。

快速上手

1. 对模型说 用 paper_login 打开登录窗口，在弹出的专用 Chrome 里用机构身份登录（建议走 CARSI）。
这个窗口就是后面下载用的那个 Chrome 实例 —— 会话 cookie 只在内存里，关掉窗口等于掉登录，让它留在后台。
2. 把 DOI（或 IEEE 链接、或 arnumber 编号）丢给模型，例如：

用 paper_fetch 下载这几个 DOI： 10.1109/TAP.2019.2953969 10.1109/JSAC.2020.3000000

不确定能不能下时，先说「先 dryRun，只解析元数据」。
3. PDF 落在哪：默认 %USERPROFILE%\Desktop\papers。可以在 paper_fetch 里传 outDir 覆盖，也可以改 ~/.dsh/paper-fetch/config.json 里的 outDir（传参会写回这个文件）。
同名文件会自动加 (2)；已经下过的会被自动跳过，想重下就加 force。

工具速查

- paper_fetch —— 批量下载。items（DOI / IEEE 链接 / arnumber，必填）、outDir、 maxItems、minDelaySeconds / maxDelaySeconds、force、dryRun、askOnLogin、 source（ieee | ei）。
默认每篇间隔 5–9 秒随机、单次最多 20 篇（保护你的账号）；同一时间只允许一个下载任务。
可识别的输入：DOI、doi.org 链接、ieeexplore.ieee.org 链接、6–9 位纯数字编号；
- paper_status —— 自检：Chrome 会话、Clash 直连规则是否生效、出口 IP、IEEE 是否 418、历史下载统计。出任何问题先跑它。
- paper_login —— 打开专用 Chrome 做机构登录（source、ask），随后复检授权状态。
- paper_sources —— 列出/探测数据库来源（probe=true 探 EI 页面，exportRecords=true 从 EI 结果页抽题录 DOI）。
- paper_clash_rules —— 检查/写入学术库「直连」规则（install=true 才写；幂等，删掉规则文件即回滚）。只改那一个规则文件，不动代理配置的其它内容。

常见问题与故障排查

IEEE 返回 418 /「Unusual Traffic Detected」

先跑 paper_status，看 IEEE 那一行，以及 出口 IP 那一行（国内 / 国外出口分别是什么）。

插件已经用真实 Chrome 驱动、并给 headless 覆盖过 UA，正常情况下不该出现 418。如果仍然 418，最可能的原因是出口 IP 被 IEEE 标记——机房/代理 IP 比住宅 IP 容易被判成「异常流量」。
先换成本地或住宅出口再试一次。

要说清楚：加学术库直连规则改善的是「机构会话被代理轮换反复踢掉」，不是 418 的解法。 想加的话（对批量下载的稳定性有好处）：对模型说 用 paper_clash_rules 检查并写入学术库直连规则，然后去 Clash Party 配置页，对当前配置点一次「编辑规则 / 重新应用 / 保存」——它只在「应用配置」时才把规则文件合并进运行时配置，光写文件不生效。不用 Clash Party 也没关系： paper_clash_rules 会把规则文本打给你，手工贴到代理配置规则列表的最前面即可。
理由与实测过程见 docs/design-notes.md。

另外：连续遇到 418 时，插件会中断本次任务、不会继续硬刷——这是保护机制，不是故障。

提示登录失效，或者中途弹出一张问题卡

在弹出的专用 Chrome 里完成登录，然后在问题卡上选「已完成」，插件会接着把剩下几篇下完；同时会发一条 Windows 通知，防止你没盯着对话。登录态是会话 cookie，关掉那个 Chrome 窗口就会掉。

为什么下载这么慢

故意的。每篇之间随机等 5–9 秒、严格串行不并发，是为了不触发 IEEE 的滥用判定。系统性下载可能导致图书馆停掉整段机构授权，所以插件不会提供「加速」选项。

PDF 找不到 / 想看记录

- PDF：默认 %USERPROFILE%\Desktop\papers
- 下载记录（含每篇的落盘路径、大小、状态）：%USERPROFILE%\.dsh\paper-fetch\manifest.jsonl
- 运行日志：%USERPROFILE%\.dsh\paper-fetch\paper-fetch.log

卸载与回滚（三处，互不影响，可只回滚一处）

- Clash 直连规则：删掉 %APPDATA%\mihomo-party\rules\<配置id>.yaml，或只删掉里面那几行学术规则。
- 插件本身：
- 用命令行装的：dsh plugin --profile desktop remove dsh-paper-fetch，再从 dsh.profile.bundles 里删掉 dsh-paper-fetch（remove 走的是同一条转发路径，同样不替你回写 bundles），然后重启 DSH。
- 用 install.ps1 装的：在插件目录跑 .\install.ps1 -Uninstall（它会把依赖与 dsh.profile.bundles 一起清掉）。
- 手工也行：从 profile 的 package.json 里删掉 dsh-paper-fetch 依赖与 dsh.profile.bundles 条目，再 pnpm install。
- 插件数据：删掉 %USERPROFILE%\.dsh\paper-fetch\（配置、专用 Chrome 配置、下载记录、日志）。

已知限制（诚实清单）

1. EI 只取题录：Engineering Village 是文摘索引库，不托管全文 PDF。paper_sources 的题录/DOI 抽取是 best-effort，抽不到就返回空，不假装成功；拿到的 DOI 再交给 paper_fetch 从出版社（多为 IEEE Xplore）下载。
2. WebVPN 通道未实现：v1 依赖「机构直连 + CARSI」，WebVPN 需要 URL 改写，属于 v2。
3. 会话脆弱是 IEEE 的性质：就算一切正确，IEEE 仍会周期性要求重新认证。插件能自动重试一次，仍失败就按你的选择弹问题卡 + 系统通知，不会静默失败。
4. Clash 规则需要手动点一次「应用」：mihomo 的外部控制端口默认未开启，插件没有可用的运行时 API，因此无法热加载规则。
5. 页面解析依赖 IEEE 的页面结构：页面改版可能拿不到标题或 PDF 地址，此时会如实报「拿不到元数据」，不会静默存下一个坏文件。
6. v0.1.0 没有侧边栏面板：只提供上面这 5 个工具。

合规与反爬

- 绝不代管学校密码：登录只发生在弹出的网页里，插件只读取浏览器自己的会话。
- 串行 + 随机间隔（默认 5–9 秒）、单次上限（默认 20 篇）、遇到 418 或页面明确提示未登录/无权限时立即中断本次任务，不会继续硬刷。
- 不绕过付费墙：只在机构已订阅的授权范围内下载，等价于你自己点「Download PDF」。
- 对 IEEE 的系统性下载会被判定为滥用，可能通知图书馆停掉整段机构授权——这不是危言耸听，而是 IEEE 明文写在 418 页面上的处置方式。
- 仅限个人学术使用。

开发与测试

不需要 DSH 也能直接跑（需要 Chrome 的那几项要本机装了 Chrome）。用 DSH 自带的 node （<DSH 安装目录>\resources\runtime\\dependencies\node\bin\node.exe），或任何 Node ≥22：

powershell
$node = "<上面那个 node.exe 的路径>" & $node test\lossless-guard.test.mjs # 纯单元测试，不需要 Chrome & $node test\smoke-cdp.mjs # CDP 地基：启动、导航、原生下载落盘 & $node test\mock-host.mjs # 工具注册契约 + 下载全链路 & $node test\ieee-adapter-probe.mjs # 用真实 IEEE 页面验证适配器（需要网络）

也可以 npm run smoke（= smoke-cdp）和 npm run adapters（= ieee-adapter-probe）。

设计决策、实测过程与踩坑记录都在 docs/design-notes.md；改了插件源码必须完整重启 DSH，靠开关 bundle 不会加载新代码（原因见该文档）。