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。DSH 只加载 dsh.profile.bundles 里列出的 插件，而 dsh plugin 只写 dependencies、不回写 bundles。装完跑一次插件自带的检查 （幂等，改动前先备份 package.json）：

   $plug = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-paper-fetch"
   node "$plug\lib\cli.mjs" fix-bundles     # 没有就补进 dsh.profile.bundles
   node "$plug\lib\cli.mjs" doctor          # 状态 + 三项安装态自检
   

   GUI（插件管理界面）安装同样要跑这一步 —— 它也只写 dependencies。不补 bundles 的表现就是 「依赖装了但插件加载不到」：工具列表里看不到 paper_*。

3. 重启 DeepSeek Harness（配置改动要重启才生效）。

4. 对模型说一句：用 paper_status 自检一下论文下载插件。看到输出目录、Chrome、IEEE 那几行就装好了。

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

要把本地目录（而不是 GitHub 上的版本）挂进 profile、或者命令行不可用时，用插件自带的脚本 （install.ps1 随包发布；从 GitHub 装的插件在 %USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-paper-fetch\ 里也有一份）：

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 很值：一次调用就能确认 DOI ↔ 标题对不对，而且不落任何文件。

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 位纯数字编号； EI 链接不在这里下（见「已知限制」）。
• 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 才写；幂等， 删掉规则文件即回滚）。只改那一个规则文件，不动代理配置的其它内容。

常见问题与故障排查

工具列表里看不到 paper_*

这是安装失败的第一大表现，不是权限问题：插件没进 dsh.profile.bundles，DSH 就不会加载它， 工具自然也不存在 —— 此时 paper_status 也调不到，请直接在终端里跑 CLI 自检：

$plug = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-paper-fetch"
node "$plug\lib\cli.mjs" doctor            # 报出 profile / bundles / 登录态
node "$plug\lib\cli.mjs" fix-bundles       # 幂等补齐 bundles（先备份）

补完重启 DeepSeek Harness，工具才会出现。

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：

$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 不会加载新代码（原因见该文档）。