dsh-plugin-litsearch 0.3.0 → 0.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -34
- package/client/client.js +1382 -760
- package/lib/host/export/bibtex.js +1 -4
- package/lib/host/export/common.d.ts +0 -2
- package/lib/host/export/common.js +0 -7
- package/lib/host/export/csv.js +1 -5
- package/lib/host/export/markdown.d.ts +1 -1
- package/lib/host/export/markdown.js +9 -26
- package/lib/host/export/ris.js +1 -4
- package/lib/host/paths.d.ts +1 -1
- package/lib/host/paths.js +1 -1
- package/lib/host/pdf/store.d.ts +5 -3
- package/lib/host/pdf/store.js +50 -17
- package/lib/host/router.js +80 -78
- package/lib/host/tasks/service.d.ts +10 -8
- package/lib/host/tasks/service.js +86 -31
- package/lib/host/tasks/states.d.ts +1 -3
- package/lib/host/tasks/states.js +2 -66
- package/lib/host/tasks/stats.js +3 -0
- package/lib/host/tasks/summary.js +1 -1
- package/lib/host/tools.d.ts +1 -1
- package/lib/host/tools.js +6 -29
- package/lib/search/oa.d.ts +8 -0
- package/lib/search/oa.js +53 -6
- package/lib/search/types.d.ts +18 -9
- package/lib/search/types.js +4 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,42 +1,79 @@
|
|
|
1
1
|
# dsh-plugin-litsearch
|
|
2
2
|
|
|
3
|
-
**给 DSH
|
|
3
|
+
**给 DSH 装一个免费的文献检索助手。**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
不用注册账号、不用申请密钥、也不用另外启动什么服务。装上以后,AI 可以直接帮你查公开学术文献;你也可以在 DSH 右侧栏用同样的数据源自己查,看到感兴趣的论文,点一下就能交给 AI 接着读。
|
|
6
6
|
|
|
7
|
-
>
|
|
7
|
+
> 当前版本 **v0.3.0**:七个免费文献来源,外加可选的谷歌学术;支持一次写多条检索式、反复调整条件重搜、自动去重、筛选与图表概览、边读边筛与分组、PDF 预览下载、同步到 Zotero、导出台账与批量加入对话。
|
|
8
|
+
>
|
|
9
|
+
> 下面的「能做什么」是写给使用者的;再往后的安装、配置、数据目录、架构等章节面向开发者和运维。
|
|
8
10
|
|
|
9
11
|
## 能做什么
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
13
|
+
一句话:**你想弄明白一个题目,插件帮你把散在各处的论文找齐、理清、读上,还能随时叫 AI 接着聊。**
|
|
14
|
+
|
|
15
|
+
### 第一次用,三步就够
|
|
16
|
+
|
|
17
|
+
1. 在 DSH 右侧栏点开「文献检索」,输入想找的东西(比如「GLP-1 与心血管结局」),选好年份、语言,点检索。
|
|
18
|
+
2. 结果按来源列出来,每篇能看到标题、作者、年份、被引次数,以及「能不能免费下载全文」。
|
|
19
|
+
3. 看到有用的,点「加入对话」,AI 就能基于这篇帮你总结、比较或写提纲。
|
|
20
|
+
|
|
21
|
+
也可以直接在聊天里让 AI 去找,结果同样出现在右侧栏,你随时能接手。
|
|
22
|
+
|
|
23
|
+
### 找得全,也找得准
|
|
24
|
+
|
|
25
|
+
- **一次问好几个方向**:可以同时写几条检索式(比如一条查药物、一条查副作用),各起个名字、随时单独开关;重复出现的论文会自动合并,不会看两遍。
|
|
26
|
+
- **想查哪些网站就勾哪些**:年份、语言、文献类型、只看能免费下载的、按相关度 / 被引次数 / 年份排序,都能当场调。
|
|
27
|
+
- **复杂检索式也不怕**:医学检索里常见的字段标签、AND / OR 这类写法,界面会提示哪些网站只认大白话,必要时可以单独给某个网站写一条更合适的检索式。
|
|
28
|
+
- **默认全都免费**:PubMed、Europe PMC、OpenAlex、Crossref、Semantic Scholar、arXiv、PubTator 这七个来源都不用注册、不用付费、不用申请密钥。想要覆盖更广,可以另外填一个 SerpAPI 密钥启用「谷歌学术」(每月有免费额度,默认关闭)。
|
|
29
|
+
- **网站忙的时候不用管**:某个来源限流了会自动排队等一会儿再试,只影响它自己,其他来源照常出结果;网络偶尔抖动也会自动重试一次。设置页里可以逐个开关来源、填可选密钥、点按钮测试通不通。NCBI 和 Semantic Scholar 可以选填密钥换更高额度。
|
|
30
|
+
|
|
31
|
+
### 每次调整都留得下痕迹
|
|
32
|
+
|
|
33
|
+
- **一个题目 = 一个任务**:做过的题目都自动保存,随时回来接着看;任务列表里能打开、改名、删除。一个聊天窗口只跟一个任务,切换任务会原位替换,不会越开越多窗口。
|
|
34
|
+
- **不满意就改条件重搜**:检索完成后仍可直接改检索式、来源、年份、语言、排序等,一键重跑,不用从头新建。每次重跑记为任务里的新的一轮。
|
|
35
|
+
- **每一轮都查得到**:任务页右上角的历史图标会按时间列出「谁发起的、当时用了什么条件、找到多少篇、有没有跑完」,看中哪一轮可以照它的条件再跑一次。
|
|
36
|
+
- **换新对话也能续上**:点任务页的「加入对话」,把任务名和当前条件放进输入框,新会话里 AI 就知道是接着这个题目继续查,而不是另起炉灶。
|
|
37
|
+
- **AI 在聊天里发起新一轮时,右侧栏会自动刷新并给出提醒**,不用手动去点。
|
|
38
|
+
|
|
39
|
+
### 结果看得明白
|
|
40
|
+
|
|
41
|
+
- **一眼看清整批文献**:「概览」页用环形图、折线图和双色条展示一共找到多少、筛到哪一步、多少篇有全文,以及年份、来源、类型、语言、作者怎么分布;图上任意一块都能点,直接筛出对应的论文。
|
|
42
|
+
- **想筛就筛**:按关键词、来源、年份、类型、语言、有没有全文、读没读过来过滤,结果一页一页翻,篇数多也不会挤成一团。
|
|
43
|
+
- **想细看就单独打开**:每篇论文有自己的页面,完整摘要、编号、PDF 与网页版全文都集中在一处;有 PMID 的论文还能看到系统标出的基因、疾病、化学物等关键词。
|
|
44
|
+
- **全文有没有,一本账**:「全文」页按整批结果统计,列出哪些能免费下、哪些需要订阅、哪些被出版社拦了、哪些已经下载好;点数字就能看清单,再批量下载或存进 Zotero,还能把这份清单带回结果页继续筛。
|
|
45
|
+
|
|
46
|
+
### 读过的都记得住
|
|
47
|
+
|
|
48
|
+
- 每篇可以标「没读 / 读过 / 纳入 / 排除」;同一任务里还能建「研究分组」,按「为什么读」归类并导出分层报告。
|
|
49
|
+
- 换一轮检索也不会丢:标过的筛读状态会跟着论文一直保留。
|
|
50
|
+
- 可以拿当前结果和某个旧任务对比,看新增了哪些、共有哪些、少了哪些,并把「新增」一键整批标成纳入。
|
|
51
|
+
- 批量操作都在勾选后完成:批量改筛读状态、归入或移出分组、下载 PDF、存 Zotero、按选中导出。排序右侧有「本页全选 / 取消全选」,本页全选是累加,翻页或改排序都不会丢失已选文献,累计数量一直显示在工具栏上。
|
|
52
|
+
|
|
53
|
+
### 全文和参考文献库都接得上
|
|
54
|
+
|
|
55
|
+
- 能免费下载的 PDF 可以直接在结果里预览,或下载到电脑(默认放在当前工作目录的 `dsh-litsearch/` 文件夹,文件名带作者、年份、标题,好认好找)。没有 PDF 但有 PMC 编号时,会给出排版好的网页版全文。
|
|
56
|
+
- 批量下载会把「需手动获取」和「失败」分开统计:出版商要求订阅、登录或人机验证时,后台程序拿不到 PDF(浏览器因为带着会话和机构授权反而能打开),这类文献会给出原因,点卡片上的 PDF / DOI 链接在浏览器打开后手动另存即可。
|
|
57
|
+
- 电脑上开着 Zotero 桌面端的话,可以一键把选中的论文连同 PDF 存进去;没连上、存了一半失败、或分类只读,都会明确告诉你,并保留一条只含本次条目的 RIS 导出作为备用。
|
|
58
|
+
- 要交给别的软件用,可以导出 CSV 表格、RIS、BibTeX 或 Markdown 报告;按当前筛选或只按勾选的条目都行。
|
|
59
|
+
|
|
60
|
+
### 和 AI 接着聊
|
|
61
|
+
|
|
62
|
+
- 点「加入对话」,论文会变成输入框里的一个小卡片(胶囊),鼠标停上去就能看到标题、出处和摘要;发送后 AI 拿到的是完整信息。一次勾多篇会合成一个卡片,按顺序编号。
|
|
63
|
+
- 整个任务也能「加入对话」,方便在新会话里明确续接同一个任务。
|
|
64
|
+
- **不会自动发送,也不会自作主张再搜一轮**:每轮结束后 AI 只给「怎么把检索改得更好」的建议,是否继续由你决定。
|
|
30
65
|
|
|
31
66
|
## 搜索任务与轮次
|
|
32
67
|
|
|
33
|
-
|
|
68
|
+
> 这一节解释「任务 / 轮次」背后的规则,主要给想了解细节或做调试的人看。日常使用只需记住:**一个研究主题 = 一个任务 = 一个右侧栏 tab;一个对话只保留一个任务 tab。** 一次检索不满意时,在同一个任务里调整条件再搜一轮,而不是新开一个任务。
|
|
69
|
+
|
|
70
|
+
具体规则:
|
|
34
71
|
|
|
35
72
|
- 模型第一次检索会新建任务并用 `title` 自己命名;后续检索默认复用「当前任务」,在同一任务内开新一轮,任务 id 与 tab 都不变。模型也可以显式传 `taskId` 复用指定任务,或在用户明确要求时传 `newTask: true` 新建。
|
|
36
73
|
- **每个对话在右侧栏只开一个任务 tab。** 切换任务从任务列表(主页 / 任务页右上角)进行:点开另一个任务时,会原位替换当前任务 tab,而不是并排再开一个。切回某个对话时,面板里打开的那个任务就是该对话当前的任务。
|
|
37
74
|
- **建议不同的检索任务使用不同对话。** 一个对话跟进一个任务,上下文和任务一一对应,模型不用猜「现在在改哪个任务」;要在一个新对话里续接已有任务,点任务页的「加入对话」把任务 id 与当前条件写进草稿即可。
|
|
38
75
|
- 模型在执行检索或任务操作前,可先调用 `literature_task`(`action=current`)读取这个对话当前的任务:标题、id、状态、检索式、完整条件、轮次与筛读漏斗。没有任务时会明确返回「当前没有任务」,避免误建新任务。
|
|
39
|
-
- 每次执行记为一条 `SearchRound`:时间、检索条件快照、发起方(模型 / 面板)、原始与去重命中数、已加载篇数、结束状态。**只记元数据,不保存文献列表**;当前结果始终是最新一轮,已标过的已读 / 纳入 /
|
|
76
|
+
- 每次执行记为一条 `SearchRound`:时间、检索条件快照、发起方(模型 / 面板)、原始与去重命中数、已加载篇数、结束状态。**只记元数据,不保存文献列表**;当前结果始终是最新一轮,已标过的已读 / 纳入 / 排除按 paperId 跨轮保留。每任务最多保留最近 30 轮,落盘时自动裁剪。
|
|
40
77
|
- 轮次可通过任务页右上角历史图标(时间轴)查看,也可用 `literature_task rounds` 或 `GET /tasks/:id/rounds` 读取。
|
|
41
78
|
- **每轮结束模型只给「如何完善检索」的建议,不会自行发起下一轮**:工具描述与每次返回尾句都写死这条约束,`literature_task run` 这条旁路同样受限。用户看过结果后,在右侧栏改条件重跑、或在对话里明确要求调整,才进入下一轮。
|
|
42
79
|
|
|
@@ -58,21 +95,23 @@ dsh plugin --profile <profile> add dsh-plugin-litsearch
|
|
|
58
95
|
|
|
59
96
|
| 字段 | 说明 | 默认 |
|
|
60
97
|
|---|---|---|
|
|
61
|
-
| `contactEmail` | 联系邮箱,作为 OpenAlex / Crossref / NCBI 的 polite pool
|
|
98
|
+
| `contactEmail` | 联系邮箱,作为 OpenAlex / Crossref / NCBI 的 polite pool 标识;**填写后还会启用 Unpaywall**,按 DOI 补全开放获取 PDF 地址,明显提升批量下载成功率 | 空 |
|
|
62
99
|
| `ncbiApiKey` | 可选,PubMed E-utilities 额度 3 → 10 次/秒;界面不回显 | 空 |
|
|
63
100
|
| `s2ApiKey` | 可选,Semantic Scholar 配额;界面不回显 | 空 |
|
|
101
|
+
| `serpApiKey` | 可选,启用「谷歌学术」来源(SerpAPI 每月 250 次免费额度,超出需付费);留空时该来源不可选且默认关闭 | 空 |
|
|
64
102
|
| `pubmedIntervalMs` / `s2IntervalMs` / `arxivIntervalMs` | 各源最小请求间隔 | 350 / 3000 / 3000 |
|
|
65
103
|
| `defaultPageSize` | 每个来源默认取多少条 | 20 |
|
|
66
104
|
| `requestTimeoutMs` | 单次上游请求超时(毫秒);Europe PMC 检索另有 25000 下限 | 20000 |
|
|
67
|
-
| `defaultSources` / `defaultSort` / `defaultLanguage` |
|
|
105
|
+
| `defaultSources` / `defaultSort` / `defaultLanguage` | 新任务默认勾选的数据源、排序与语言;设置页按来源分组,可逐个开关(至少保留一个) | 七个免费源 / 相关度 / 不限 |
|
|
68
106
|
| `autoOpenTaskTab` / `maxTaskTabs` | 模型发起检索后自动打开 / 聚焦任务 tab;每个对话只保留一个任务 tab,打开新任务会替换旧的。`maxTaskTabs` 为自动打开的兜底上限(按最近真实打开过的 tab 计数,30 分钟后释放名额) | 开 / 5 |
|
|
69
107
|
| `taskRetentionDays` / `taskRetentionCount` / `taskMaxPapers` | 未保留任务保留天数、保留条数、单任务结果上限(在任务列表中可标记「保留」跳过清理) | 90 / 120 / 1500 |
|
|
70
108
|
| `pdfRoot` / `pdfMaxMb` / `autoDownloadPdf` | PDF 保存目录、单文件上限(MB)、检索完成后自动下载;`pdfRoot` 留空时落在当前会话工作目录下的 `dsh-litsearch/` | 跟随工作目录 / 30 / 关 |
|
|
109
|
+
| `pdfCacheMaxMb` | 内部 PDF 去重缓存总量上限(MB),超出时从最旧文件开始清理;0 表示不自动清理 | 512 |
|
|
71
110
|
| `enableEpmcFulltext` | 没有 PDF 时用 Europe PMC JATS 全文兜底为可读 HTML | 开 |
|
|
72
111
|
| `zoteroEnabled` / `zoteroBaseUrl` | 启用 Zotero 同步及 connector 地址(只允许本机回环) | 开 / `http://127.0.0.1:23119` |
|
|
73
112
|
| `zoteroAttachPdf` / `zoteroTag` | 同步时附带 PDF、附加标签 | 开 / `dsh-litsearch` |
|
|
74
113
|
|
|
75
|
-
|
|
114
|
+
设置页按数据源分成一组组,每组内含开关、可选密钥、限流参数与探活按钮;关闭的来源不再作为新检索的默认来源。另有诊断与清理:逐源查看最近成功 / 失败与限流冷却;测试 PDF 下载目录可写性;测试 Zotero connector 连接并读取当前选中分类;按任务 / PDF 缓存 / 全部三种范围清理文件。
|
|
76
115
|
|
|
77
116
|
## 数据目录
|
|
78
117
|
|
|
@@ -81,14 +120,14 @@ dsh plugin --profile <profile> add dsh-plugin-litsearch
|
|
|
81
120
|
```
|
|
82
121
|
$DSH_HOME/storages/dsh-plugin-litsearch/
|
|
83
122
|
├── tasks/index.json # 任务摘要索引(缺失时按任务文件重建)
|
|
84
|
-
├── tasks/<taskId>.json #
|
|
123
|
+
├── tasks/<taskId>.json # 单任务全量元数据:条件、轮次、结果、分组、筛读状态
|
|
85
124
|
├── current.json # 当前任务绑定
|
|
86
125
|
├── out/<taskId>/ # CSV / RIS / BibTeX / Markdown 导出
|
|
87
|
-
└── pdfs/<sha256>.pdf # PDF
|
|
126
|
+
└── pdfs/<sha256>.pdf # PDF 去重缓存(受 pdfCacheMaxMb 约束)
|
|
88
127
|
```
|
|
89
128
|
|
|
90
129
|
- `DSH_HOME` 由宿主注入,未设置时回落 `~/.dsh`;设置页「存储目录」展示当前实际生效的路径。
|
|
91
|
-
- 旧版本的数据写在 `~/.dsh/dsh-litsearch
|
|
130
|
+
- 旧版本的数据写在 `~/.dsh/dsh-litsearch/`。首次启动时若新目录为空而旧目录有任务,会把任务、导出文件与缓存**复制**到新目录并重建索引,**旧目录原样保留作备份**;新目录已有任务时不再迁移,复制失败则暂时回退到旧目录读取,不会丢筛读状态。
|
|
92
131
|
- **PDF 可读文件不在这里**:它由 `pdfRoot` 决定;未显式配置时落在当前会话工作目录下的 `dsh-litsearch/`(读不到工作目录时才回落到旧默认 `~/Downloads/dsh-litsearch`)。任务里记录的 `pdfFile` 是该目录下的绝对路径,升级不影响已下载的文件;只有内部去重缓存 `pdfs/` 随任务目录一起搬迁。
|
|
93
132
|
|
|
94
133
|
## Zotero 同步
|
|
@@ -99,13 +138,15 @@ $DSH_HOME/storages/dsh-plugin-litsearch/
|
|
|
99
138
|
2. 在「设置 → 高级」中允许其他应用与本机通信(若该版本提供此开关);
|
|
100
139
|
3. 如有需要,先在 Zotero 里选中目标分类——未选中时条目会保存到「我的文库」。
|
|
101
140
|
|
|
102
|
-
|
|
141
|
+
同步会写入条目元数据、分组名(作为标签)与可选 PDF 附件。连接失败、当前分类不可写附件、单篇条目或附件失败都会在界面给出对应提示;分类只读时只保存条目,不尝试上传 PDF。同步失败或部分失败时,任务页会保留一条 RIS 导出入口(只含本次同步的条目),可先导出备用。
|
|
103
142
|
|
|
104
143
|
## 隐私
|
|
105
144
|
|
|
106
145
|
- 检索词会发送给所选数据源(PubMed、Europe PMC、OpenAlex、Crossref、Semantic Scholar、arXiv、PubTator)的公开 API。
|
|
146
|
+
- 配置了 `contactEmail` 后,下载 PDF 会用 DOI 和该邮箱查询 Unpaywall(`api.unpaywall.org`)以寻找开放获取副本;不配置则不发这项请求。
|
|
147
|
+
- 启用「谷歌学术」时,检索词会经第三方服务 SerpAPI 转发,并受其使用条款与额度约束;该来源默认关闭。
|
|
107
148
|
- PDF 下载与 Zotero 连接都只在本机进行;Zotero connector 仅允许回环地址。
|
|
108
|
-
- API Key
|
|
149
|
+
- 各类 API Key(含 `serpApiKey`)只保存在本机配置文件(明文)中,界面不回显、不写日志。
|
|
109
150
|
|
|
110
151
|
## 本地开发
|
|
111
152
|
|
|
@@ -129,7 +170,7 @@ dsh --profile litsearch
|
|
|
129
170
|
## 架构
|
|
130
171
|
|
|
131
172
|
- `src/search/`:数据源无关的检索层(类型、聚合、身份合并、查询适配、限流、健康状态)。
|
|
132
|
-
- `src/search/providers
|
|
173
|
+
- `src/search/providers/`:每家 API 一个 provider,新增数据源只需实现 `Provider` 并注册;其中 `googlescholar` 为需自备密钥的可选源。
|
|
133
174
|
- `src/host/`:`/dsh-litsearch/api/*` 端点、任务执行 / 持久化 / 统计 / 导出、模型侧工具注册。
|
|
134
175
|
- `src/host/paths.ts`:`$DSH_HOME` 解析、统一存储区路径、旧目录一次性迁移与失败回退。
|
|
135
176
|
- `src/host/pdf/`:PDF 候选链、SSRF 防护的抓取与本地缓存、可读文件名、Europe PMC 全文兜底。
|
|
@@ -143,7 +184,7 @@ dsh --profile litsearch
|
|
|
143
184
|
- [x] Semantic Scholar
|
|
144
185
|
- [x] 多检索式与跨式去重
|
|
145
186
|
- [x] 结果筛选、排序与概览统计
|
|
146
|
-
- [x]
|
|
187
|
+
- [x] 筛读、分组与任务对比
|
|
147
188
|
- [x] 续页加载与导出(CSV / RIS / BibTeX / Markdown)
|
|
148
189
|
- [x] PDF 预览 / 下载、Europe PMC 全文兜底、全文台账
|
|
149
190
|
- [x] Zotero 同步与批量操作
|
|
@@ -151,6 +192,7 @@ dsh --profile litsearch
|
|
|
151
192
|
- [x] 独立论文页、PubTator 实体与数据源语法提示
|
|
152
193
|
- [x] 对比视图整批纳入、Zotero 失败回退 RIS
|
|
153
194
|
- [x] Unpaywall(按 DOI 补全开放获取全文地址;需配置 `contactEmail`)
|
|
195
|
+
- [x] 谷歌学术(可选源,需自备 SerpAPI Key)与设置页数据源开关
|
|
154
196
|
- [ ] DOAJ
|
|
155
197
|
|
|
156
198
|
## License
|