dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 peijiping
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# dsh-plugin-litsearch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**给 DSH 加一个免费的文献检索助手。**
+
+装上这个插件，大模型可以直接检索开放学术文献，你也可以在 DSH 右侧栏用同一套数据源检索，并把感兴趣的论文一键带进对话。无需账号、无需 API Key、无需本地服务。
+
+> 当前为 P4：七个免费数据源聚合，支持多检索式（可命名、启停、按源覆写）、去重、筛选与概览；可预览 / 下载开放获取 PDF、用 Europe PMC 兜底 HTML 全文、同步到本机 Zotero，并对结果做批量筛读、分组、备注、导出与批量插入对话。每篇论文还能打开独立论文页，查看 PubTator 实体标注；检索式带字段语法时会提示哪些源只按自然语言处理。
+
+## 能做什么
+
+- **模型侧检索**：内置 `literature_search`、`literature_sources`、`literature_task`、`literature_export` 四个工具，可提交多条检索式与年份、开放获取、文献类型等条件；任务可被读取、筛读、分组、对比、查看轮次历史与导出。同一主题的多轮检索复用同一个任务，不会连续弹出新 tab；一个对话只保留一个任务 tab，模型可在执行前用 `literature_task`（`action=current`）确认这个对话当前的任务。
+- **人侧检索**：右侧栏「文献检索」面板，可加多条检索式、勾选数据源，结果显示来源、被引与开放获取状态；任务自动保存，可随时回来继续。
+- **高级检索式编辑**：每条检索式可改自定义名称、单独启用 / 停用、并针对某个数据源写覆写式（例如 PubMed 用 MeSH、OpenAlex 用概念检索）；未覆写的源仍用主检索式。
+- **任务条件编辑**：任务完成后仍可在面板内「改条件」调整检索式、数据源、年份、开放获取、语言、类型、排序与每源条数，保存后一键重跑，无需新建任务。每次重跑都会记为任务内新的一轮。
+- **轮次历史时间轴**：任务页右上角历史图标打开时间轴，按时间列出每一轮的发起方、检索条件、命中数、完成状态；可一键把某一轮的条件回填后重跑。
+- **任务列表**：主页与任务页右上角都有任务列表图标，可打开、重命名、删除任意任务；从列表点开某任务即「进入」该任务，右侧栏原有的任务 tab 会被原位替换（一个对话只保留一个任务 tab），之后的模型检索默认落在这里。
+- **数据源语法提示**：检索式含字段标签或布尔语法时，提示 Semantic Scholar / PubTator 会按自然语言处理；数据源按钮悬浮可查看各自支持的语法，必要时用单源覆写保留查询意图。
+- **独立论文页**：任意结果可打开独立论文 tab，集中展示完整摘要、标识符、筛读 / 分组 / 备注 / 标签 / 必读序号、PDF 与 HTML 全文预览，并可插入对话。
+- **PubTator 实体**：有 PMID 的论文可查看 PubTator3 标注的基因、疾病、化学物等实体，按标准标识符去重并显示出现次数。
+- **筛选与概览**：结果可按关键词、来源、年份、类型、语言、人工筛读状态、缺全文、全文获取状态等条件过滤并排序；结果页顶部常驻全任务口径的全文覆盖横幅，可一键筛出缺全文或跳到全文台账；「概览」页展示漏斗、年份分布、来源与检索式贡献，点击即可反向筛选结果。
+- **筛读工作流**：每篇论文可标记未读 / 已读 / 纳入 / 排除，写备注、打标签、加入必读顺序；任务内可建「研究分组」，按为什么读归类，并导出分层报告。
+- **全文预览与下载**：在结果卡片里直接预览开放获取 PDF，或下载到本地；文件按「作者年份_标题_标识.pdf」命名，支持断点式 Range 读取。没有 PDF 但有 PMCID 时，用 Europe PMC 全文渲染可读 HTML。
+- **全文台账**：「全文」页按全任务口径（与概览一致、不受结果页筛选影响）列出覆盖率；状态数字可点击切换清单，缺全文、有全文直链、已下载、需订阅、被出版商拒绝、获取失败等各自成表，可分页加载、多选批量下载 PDF / 存入 Zotero，并可把当前清单带进结果页（会清空其他筛选，保证篇数一致）。
+- **Zotero 同步**：通过本机 Zotero 桌面端 connector 保存条目，可选同时附上 PDF；未连接 Zotero、同步失败、部分成功都会给出明确提示，并保留一条带当前条目范围的 RIS 导出入口。
+- **批量操作**：结果页与全文页均可多选后批量下载 PDF、存入 Zotero；结果页还支持批量改筛读状态、归入或移出分组、按选中导出。
+- **导出与对比**：按当前筛选或选中条目导出 CSV 台账、RIS、BibTeX、Markdown 报告；也可选一个旧任务做新增 / 共有 / 缺失对比，并把「新增」整批标记为纳入。
+- **带进对话**：点击「插入到对话」，把论文元数据与摘要写入当前会话草稿（不自动发送），模型可据此继续工作；勾选多篇后可一次插入，按序号编号。
+- **任务带入对话**：任务页的「带入对话」把任务 id、标题与当前检索条件写入会话草稿（不自动发送），在新会话里也能明确续接同一任务的下一轮，而不是新建任务。
+- **免费数据源**：全部无需付费或申请密钥；NCBI 与 Semantic Scholar 可选填 Key 提高额度。限流在本地按源串行排队：冷却期内排队等待而非报错，收到 429 会退避重试并自适应放大该源间隔，连续成功后回落；只有上游要求冷却过久才优雅跳过该源，此时任务不会变「部分完成」、面板也只给中性提示。单个源触发限流只影响该源。超时 / 临时网络故障会重试一次；Europe PMC 的 `resultType=core` 检索单独享有 25s 超时下限。
+
+## 搜索任务与轮次
+
+**一个研究主题 = 一个任务 = 一个右侧栏 tab；一个对话只保留一个任务 tab。** 一次检索不满意时，在同一个任务里调整条件再搜一轮，而不是新开一个任务：
+
+- 模型第一次检索会新建任务并用 `title` 自己命名；后续检索默认复用「当前任务」，在同一任务内开新一轮，任务 id 与 tab 都不变。模型也可以显式传 `taskId` 复用指定任务，或在用户明确要求时传 `newTask: true` 新建。
+- **每个对话在右侧栏只开一个任务 tab。** 切换任务从任务列表（主页 / 任务页右上角）进行：点开另一个任务时，会原位替换当前任务 tab，而不是并排再开一个。切回某个对话时，面板里打开的那个任务就是该对话当前的任务。
+- **建议不同的检索任务使用不同对话。** 一个对话跟进一个任务，上下文和任务一一对应，模型不用猜「现在在改哪个任务」；要在一个新对话里续接已有任务，点任务页的「带入对话」把任务 id 与当前条件写进草稿即可。
+- 模型在执行检索或任务操作前，可先调用 `literature_task`（`action=current`）读取这个对话当前的任务：标题、id、状态、检索式、完整条件、轮次与筛读漏斗。没有任务时会明确返回「当前没有任务」，避免误建新任务。
+- 每次执行记为一条 `SearchRound`：时间、检索条件快照、发起方（模型 / 面板）、原始与去重命中数、已加载篇数、结束状态。**只记元数据，不保存文献列表**；当前结果始终是最新一轮，已标过的已读 / 纳入 / 排除 / 备注按 paperId 跨轮保留。每任务最多保留最近 30 轮，落盘时自动裁剪。
+- 轮次可通过任务页右上角历史图标（时间轴）查看，也可用 `literature_task rounds` 或 `GET /tasks/:id/rounds` 读取。
+- **每轮结束模型只给「如何完善检索」的建议，不会自行发起下一轮**：工具描述与每次返回尾句都写死这条约束，`literature_task run` 这条旁路同样受限。用户看过结果后，在右侧栏改条件重跑、或在对话里明确要求调整，才进入下一轮。
+
+「当前任务」是持久化的最近一次使用或打开的任务：不按对话、也不按时间过期，宿主重启后仍会恢复；任务被删除时自动回退到最近更新的任务。模型每次运行任务都会请求客户端打开 / 聚焦对应 tab（可在设置中关闭自动打开），面板关着也会重新打开；聚焦请求只会送到发起检索的那个对话，不会抢占其他对话的面板。打开任务 tab、从任务列表切换、或切回已开着某任务的对话，都会把该任务设为「当前任务」。只有用户明确要求新建查询任务时才使用 `newTask`。
+
+## 安装
+
+要求 dsh ≥ 0.2.1-rc.3（`package.json` 的 `engines.dsh` 为 `>=0.2.1-rc.3 <0.3.0-0`）。
+
+```sh
+dsh plugin --profile <profile> add dsh-plugin-litsearch
+```
+
+包内是预构建产物（`lib/` + `client/client.js`），安装时不运行构建脚本。
+
+## 配置
+
+插件页 → `dsh-plugin-litsearch` → 配置（保存即生效）：
+
+| 字段 | 说明 | 默认 |
+|---|---|---|
+| `contactEmail` | 联系邮箱，作为 OpenAlex / Crossref / NCBI 的 polite pool 标识，留空也可用 | 空 |
+| `ncbiApiKey` | 可选，PubMed E-utilities 额度 3 → 10 次/秒；界面不回显 | 空 |
+| `s2ApiKey` | 可选，Semantic Scholar 配额；界面不回显 | 空 |
+| `pubmedIntervalMs` / `s2IntervalMs` / `arxivIntervalMs` | 各源最小请求间隔 | 350 / 3000 / 3000 |
+| `defaultPageSize` | 每个来源默认取多少条 | 20 |
+| `requestTimeoutMs` | 单次上游请求超时（毫秒）；Europe PMC 检索另有 25000 下限 | 20000 |
+| `defaultSources` / `defaultSort` / `defaultLanguage` | 新任务默认勾选的数据源、排序与语言 | 全部 / 相关度 / 不限 |
+| `autoOpenTaskTab` / `maxTaskTabs` | 模型发起检索后自动打开 / 聚焦任务 tab；每个对话只保留一个任务 tab，打开新任务会替换旧的。`maxTaskTabs` 为自动打开的兜底上限（按最近真实打开过的 tab 计数，30 分钟后释放名额） | 开 / 5 |
+| `taskRetentionDays` / `taskRetentionCount` / `taskMaxPapers` | 未置顶任务保留天数、保留条数、单任务结果上限 | 90 / 120 / 1500 |
+| `pdfRoot` / `pdfMaxMb` / `autoDownloadPdf` | PDF 保存目录、单文件上限（MB）、检索完成后自动下载 | `~/Downloads/dsh-litsearch` / 30 / 关 |
+| `enableEpmcFulltext` | 没有 PDF 时用 Europe PMC JATS 全文兜底为可读 HTML | 开 |
+| `zoteroEnabled` / `zoteroBaseUrl` | 启用 Zotero 同步及 connector 地址（只允许本机回环） | 开 / `http://127.0.0.1:23119` |
+| `zoteroAttachPdf` / `zoteroTag` | 同步时附带 PDF、附加标签 | 开 / `dsh-litsearch` |
+
+设置页还提供诊断与清理：逐源查看最近成功 / 失败与限流冷却并做探活；测试 PDF 下载目录可写性；测试 Zotero connector 连接并读取当前选中分类；按任务 / PDF 缓存 / 全部三种范围清理文件。
+
+## 数据目录
+
+任务的全部元数据都用本地 JSON 文件保存，位于平台统一存储区（不依赖数据库）：
+
+```
+$DSH_HOME/storages/dsh-plugin-litsearch/
+├── tasks/index.json        # 任务摘要索引（缺失时按任务文件重建）
+├── tasks/<taskId>.json     # 单任务全量元数据：条件、轮次、结果、分组、筛读状态、备注
+├── current.json            # 当前任务绑定
+├── out/<taskId>/           # CSV / RIS / BibTeX / Markdown 导出
+└── pdfs/<sha256>.pdf       # PDF 去重缓存
+```
+
+- `DSH_HOME` 由宿主注入，未设置时回落 `~/.dsh`；设置页「存储目录」展示当前实际生效的路径。
+- 旧版本的数据写在 `~/.dsh/dsh-litsearch/`。首次启动时若新目录为空而旧目录有任务，会把任务、导出文件与缓存**复制**到新目录并重建索引，**旧目录原样保留作备份**；新目录已有任务时不再迁移，复制失败则暂时回退到旧目录读取，不会丢标注。
+- **PDF 可读文件不在这里**：它由 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），任务里记录的 `pdfFile` 是该目录下的绝对路径，升级不影响已下载的文件；只有内部去重缓存 `pdfs/` 随任务目录一起搬迁。
+
+## Zotero 同步
+
+同步走 Zotero 桌面端自带的 connector（默认 `http://127.0.0.1:23119`），不需要 Web API Key：
+
+1. 启动 Zotero 桌面端，保持运行；
+2. 在「设置 → 高级」中允许其他应用与本机通信（若该版本提供此开关）；
+3. 如有需要，先在 Zotero 里选中目标分类——未选中时条目会保存到「我的文库」。
+
+同步会写入条目元数据、标签与可选 PDF 附件。连接失败、当前分类不可写附件、单篇条目或附件失败都会在界面给出对应提示；分类只读时只保存条目，不尝试上传 PDF。同步失败或部分失败时，任务页会保留一条 RIS 导出入口（只含本次同步的条目），可先导出备用。
+
+## 隐私
+
+- 检索词会发送给所选数据源（PubMed、Europe PMC、OpenAlex、Crossref、Semantic Scholar、arXiv、PubTator）的公开 API。
+- PDF 下载与 Zotero 连接都只在本机进行；Zotero connector 仅允许回环地址。
+- API Key 只保存在本机配置文件（明文）中，界面不回显、不写日志。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm build            # Host: src -> lib
+pnpm build:client     # Client: src/client -> client/client.js
+pnpm typecheck:client
+pnpm test             # node:test 单元测试（test/**/*.test.ts）
+```
+
+构建后用独立的本地 profile 启动调试：
+
+```bash
+pnpm build && pnpm build:client
+dsh --profile litsearch
+```
+
+该 profile 位于 `~/.dsh/profiles/litsearch`，通过 `link:` 指向本仓库，包含 `@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app` 与本插件，不会影响 demo 等其他测试 profile。
+
+## 架构
+
+- `src/search/`：数据源无关的检索层（类型、聚合、身份合并、查询适配、限流、健康状态）。
+- `src/search/providers/`：每家免费 API 一个 provider，新增数据源只需实现 `Provider` 并注册。
+- `src/host/`：`/dsh-litsearch/api/*` 端点、任务执行 / 持久化 / 统计 / 导出、模型侧工具注册。
+- `src/host/paths.ts`：`$DSH_HOME` 解析、统一存储区路径、旧目录一次性迁移与失败回退。
+- `src/host/pdf/`：PDF 候选链、SSRF 防护的抓取与本地缓存、可读文件名、Europe PMC 全文兜底。
+- `src/host/zotero/`：本机 Zotero connector 协议封装（探测、保存条目、上传附件）。
+- `src/client/`：右侧栏检索面板、任务 tab（结果 / 概览 / 分组 / 笔记 / 对比 / 全文）、独立论文 tab 与设置页。
+
+## 路线图
+
+- [x] arXiv（Atom XML）
+- [x] PubMed / Europe PMC
+- [x] Semantic Scholar
+- [x] 多检索式与跨式去重
+- [x] 结果筛选、排序与概览统计
+- [x] 筛读、分组、备注与任务对比
+- [x] 续页加载与导出（CSV / RIS / BibTeX / Markdown）
+- [x] PDF 预览 / 下载、Europe PMC 全文兜底、全文台账
+- [x] Zotero 同步与批量操作
+- [x] 高级检索式编辑、任务条件修改与批量插入对话
+- [x] 独立论文页、PubTator 实体与数据源语法提示
+- [x] 对比视图整批纳入、Zotero 失败回退 RIS
+- [x] Unpaywall（按 DOI 补全开放获取全文地址；需配置 `contactEmail`）
+- [ ] DOAJ
+
+## License
+
+MIT