dsh-research-desk 0.2.0 → 0.3.0
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 +313 -112
- package/bin/dsh-research-desk-mcp.mjs +17 -0
- package/index.json +5 -6
- package/lib/host.mjs +9 -3
- package/lib/mcp.mjs +5 -2
- package/lib/search.mjs +4 -2
- package/package.json +6 -1
package/README.md
CHANGED
|
@@ -1,171 +1,372 @@
|
|
|
1
1
|
# dsh-research-desk · 科研工作台
|
|
2
2
|
|
|
3
|
-
DeepSeek Harness
|
|
4
|
-
|
|
3
|
+
DeepSeek Harness 插件:给 agent 和研究者一个**就在侧栏里的科研工作台**——检索文献、维护阅读库、抓全文做带锚点的问答、推可证伪选题、写多视角综述、在受限目录里跑验证脚本、整库导出。
|
|
4
|
+
**每一条引文都回到原文逐字核对,对不上就剔除。**
|
|
5
5
|
|
|
6
|
-
-
|
|
6
|
+
- 包名 `dsh-research-desk`,版本 0.2.0,MIT,零运行时依赖,零构建步骤
|
|
7
7
|
- 宿主要求:DSH `>=0.2.1-rc.5 <0.3.0`,Node `>=22`
|
|
8
|
-
-
|
|
8
|
+
- 交付渠道:GitHub + npm + dshmarket(索引条目见 `index.json`)
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
## 1.
|
|
12
|
+
## 1. 一句话定位与解决的问题
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
生态真实形态是 8 层栈(L1 文献 / L2 综述 / L3 精读 / L4 选题假说 / L5 实验计算 / L6 可复现 / L7 写作出版 / L8 协作评审),
|
|
16
|
-
瓶颈在 L4(选题假说)与 L6(可复现),而这两层恰好是现有生态最薄弱的。
|
|
14
|
+
**一句话定位**:它把「查文献 → 精读 → 问答 → 选题 → 综述 → 验证计算 → 导出」这条科研工作流,做成 DeepSeek Harness 宿主里的一个侧栏面板加一个 agent 工具,两条入口共用同一份状态与同一套服务函数。
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
外加一条贯穿式约束:**引用必须可核验**。
|
|
16
|
+
它解决六个问题:
|
|
20
17
|
|
|
21
|
-
|
|
18
|
+
| 问题 | 做法 |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| 引用核查 | 模型给的每条引文逐字回原文片段比对,对不上的进 `unverified` 并从结论里剔除;检索没命中就根本不发模型请求 |
|
|
21
|
+
| 锚定阅读 | `read` 把全文切块入库(默认 1100 字符、重叠 160),答案里的每条引文都能指回 chunk、标题与原文链接 |
|
|
22
|
+
| 多视角综述 | 五个视角(方法学 / 证据 / 矛盾与争议 / 研究缺口 / 应用与影响)各写一节,各自带核验过的引文 |
|
|
23
|
+
| 选题假设 | 只用库内摘要推出选题,每个选题必须写出「缺口」与「能杀死它的最便宜实验」,不许声称机制已被证明 |
|
|
24
|
+
| 沙箱验证计算 | 只允许 `python` / `node`,`shell: false`、独立工作目录、超时上限、stdout/stderr 截断落盘;默认关闭 |
|
|
25
|
+
| 导出 | 一键产出 Markdown 清单、BibTeX、JSON;JSON 默认不含全文,密钥只导出「是否已配置」 |
|
|
22
26
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 2. 能力清单(九个面板页)
|
|
30
|
+
|
|
31
|
+
侧栏入口叫「科研工作台」,打开后是九个页签,顶部常驻「N 篇文献 · N 条选题 · N 篇草稿」。
|
|
32
|
+
|
|
33
|
+
### 2.1 检索(search)
|
|
34
|
+
|
|
35
|
+
- **输入**:检索式,加三个数据源勾选(arXiv / Europe PMC / OpenAlex);面板固定按单源 12 条请求。
|
|
36
|
+
- **输出**:结果卡片列表,每张卡带来源 / 年份 / venue / 引用数 chip、摘要、「加入文献库」按钮与原文链接。
|
|
37
|
+
- **限制**:三个源都免密钥;单源条数上限由设置 `maxResults` 决定(默认 15,宿主端夹在 1–40);某个源失败不阻断整体,失败原因出现在返回的 `errors` 里;只覆盖这三个开放源,不接付费库。
|
|
38
|
+
|
|
39
|
+
### 2.2 文献库(library)
|
|
40
|
+
|
|
41
|
+
- **输入**:检索结果「加入文献库」,以及卡片上的「抓取全文」「移出」「纳入问答」勾选。
|
|
42
|
+
- **输出**:文献卡片列表,带状态 chip(`new` / `reading` / `read` / `kept` / `dropped`)与片段数 chip(显示「N 段全文」或「仅摘要」)。
|
|
43
|
+
- **限制**:去重优先级是 DOI → arXiv id → PubMed id → 标题;只有抓过全文的文献才能支撑问答与综述;面板展示的摘要截到 1200 字、作者最多 12 位。
|
|
44
|
+
|
|
45
|
+
### 2.3 问答(ask)
|
|
46
|
+
|
|
47
|
+
- **输入**:一个问题,加上可选的「纳入问答」勾选(勾了只答这些文献,不勾就用库里全部已入库全文)。
|
|
48
|
+
- **输出**:答案卡片,分「已核验引文」(chunkId + 引文原文)与「剔除未通过核验的引文」计数;问答记录保留最近 200 条,面板显示最近 50 条。
|
|
49
|
+
- **限制**:只用已入库的全文段落作答;检索段落数由 `qa.limit` 控制(1–20,默认 8),命中阈值由 `qa.minScore` 控制(0–1,默认 0.6);`qa.shareFullText` 关闭时只用摘要;库里没有可用段落时直接报「还没有入库全文。先对文献执行 read,再提问。」
|
|
50
|
+
|
|
51
|
+
### 2.4 选题(hypothesis)
|
|
52
|
+
|
|
53
|
+
- **输入**:点一次「从文献库生成选题」,模型看到的是库里前 40 篇的标题与摘要(每篇摘要截到 1400 字)。
|
|
54
|
+
- **输出**:选题卡片,每张含标题、状态、理由、缺口、以及能杀死它的实验。
|
|
55
|
+
- **限制**:输入只有标题和摘要,**不可能**给出机制级结论;返回的证据 id 必须来自库内,否则被过滤掉;`privacy.shareAbstracts` 关闭时模型只看到标题行。
|
|
56
|
+
|
|
57
|
+
### 2.5 综述(review)
|
|
29
58
|
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
59
|
+
- **输入**:主题(留空则只按视角检索词检索)加五个视角勾选,默认开方法学 / 证据 / 矛盾与争议 / 研究缺口,「应用与影响」默认关。
|
|
60
|
+
- **输出**:每个视角一节正文,带该节引文与未核验条数;另有「只找研究缺口」按钮,缺口单独存成一篇综述(标题后缀「· 研究缺口」)。
|
|
61
|
+
- **限制**:只看已入库全文;每篇最多取 2 个片段,单篇综述的视角上限由 `review.maxSections` 控制(1–5,默认 4);某个视角没有可支撑段落时写「文献库中没有可支撑的段落。」并且不发模型请求;所有视角都撑不住时报「检索不到可支撑的段落,没有生成综述。」
|
|
62
|
+
|
|
63
|
+
### 2.6 实验(experiment)
|
|
64
|
+
|
|
65
|
+
- **输入**:实验标题、运行时(`python` / `node`)、代码。
|
|
66
|
+
- **输出**:运行结果卡片(退出码、耗时、标准输出、错误输出),以及实验记录列表(最近 10 条:状态、运行时、耗时、超时标记、退出码、stdout/stderr 各截到 4000 字符)。
|
|
67
|
+
- **限制**:必须先在设置里打开「允许调用外部工具」(`runner.enabled`),否则拒绝执行;只允许 python 与 node 两种运行时;超时由 `runner.timeoutSec` 控制(5–600 秒,默认 60);代码只落在插件数据目录下的 `runs` 文件夹。
|
|
68
|
+
|
|
69
|
+
### 2.7 草稿(draft)
|
|
70
|
+
|
|
71
|
+
- **输入**:一句写作要求(默认「写一个结构完整的论文大纲。」)。
|
|
72
|
+
- **输出**:草稿卡片,含标题、引用条数与可展开正文。
|
|
73
|
+
- **限制**:模型输入只有标题和摘要;每条主张必须标注库内文献 id,库撑不起的段落要求写「缺什么」而不是编;正文上限 60000 字符,库视图截到 20000 字符。
|
|
74
|
+
|
|
75
|
+
### 2.8 导出(export)
|
|
76
|
+
|
|
77
|
+
- **输入**:点一次「生成导出文件」,一次产出 md / bib / json 三种格式。
|
|
78
|
+
- **输出**:三个可下载文件 `research-desk-library.md`、`research-desk-library.bib`、`research-desk-library.json`。
|
|
79
|
+
- **限制**:JSON 默认不含全文片段(只留片段序号与标题);`secrets.*` 一律导出成 `{configured: true/false}`;Markdown 里综述部分分成「已核验引文」与「未通过核验的引文(已剔除)」两段。
|
|
80
|
+
|
|
81
|
+
### 2.9 设置(settings)
|
|
82
|
+
|
|
83
|
+
- **输入**:每条设置一张卡片(按类型给输入框或下拉),加「保存设置」与「恢复默认」两个按钮。
|
|
84
|
+
- **输出**:改完即时生效;非法值保留旧值并在消息里说明原因(如「设置没有保存:…」)。
|
|
85
|
+
- **限制**:只有 `SETTING_DEFS` 里声明过的键会被接受,未知键直接丢弃;密钥项只显示环境变量名与「该环境变量已设置 / 只保存环境变量名」。
|
|
35
86
|
|
|
36
87
|
---
|
|
37
88
|
|
|
38
|
-
##
|
|
89
|
+
## 3. 安装
|
|
39
90
|
|
|
40
|
-
|
|
91
|
+
三条路,任选其一。**安装前必须把桌面 profile 完全退出**(驻留中的宿主会占着插件目录,装完不生效)。装完重新打开宿主,侧栏出现「科研工作台」图标即为成功,也可以直接让 agent 调 `research_desk` 工具验证。
|
|
41
92
|
|
|
42
|
-
|
|
43
|
-
|---|---|---|
|
|
44
|
-
| `status` | 库内篇数、选题数、草稿数、当前默认模型 | — |
|
|
45
|
-
| `models` | 列出宿主可调用的模型 | — |
|
|
46
|
-
| `search` | 检索 arXiv / Europe PMC / OpenAlex(免密钥) | `query` `sources` `maxResults` |
|
|
47
|
-
| `add` | 把检索结果放进文献库(按 doi→arxiv→标题去重) | `papers[]` |
|
|
48
|
-
| `library` | 列出文献库、选题、草稿 | — |
|
|
49
|
-
| `read` | 拉全文并切成可检索片段存进库里 | `paperId` |
|
|
50
|
-
| `ask` | 只用库内全文回答,每条引文核验 | `question` `paperIds` |
|
|
51
|
-
| `hypothesis` | 从文献库推出可证伪选题 | — |
|
|
52
|
-
| `draft` | 生成论文大纲 | `instruction` |
|
|
53
|
-
| `remove` | 移出一篇文献 | `paperId` |
|
|
54
|
-
| `undo` | 撤销上一步 | — |
|
|
93
|
+
### 3.1 dshmarket 市场安装(推荐)
|
|
55
94
|
|
|
56
|
-
|
|
95
|
+
在 dshmarket 的插件市场里找到「科研工作台 / Research Desk」,一键安装。dshmarket 读取的正是精选列表 awesome-dsh-plugin 里的索引条目,版本与 npm 上的 `dsh-research-desk` 对应(当前 0.2.0)。
|
|
96
|
+
|
|
97
|
+
### 3.2 npm 规格名安装
|
|
98
|
+
|
|
99
|
+
在宿主插件页的规格名输入框填 `dsh-research-desk`;或者在终端里用 CLI(需要 `dsh` 在 PATH):
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
dsh plugin --profile desktop add dsh-research-desk
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 3.3 自定义索引安装
|
|
106
|
+
|
|
107
|
+
把仓库里的 `index.json` 放到任意可公开访问的地址(GitHub raw 或 jsDelivr 镜像都行),然后在桌面端「插件 → 实验性插件 → 自定义插件索引」里填这个 URL:
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
https://raw.githubusercontent.com/stallenlu/dsh-research-desk/main/index.json
|
|
111
|
+
https://cdn.jsdelivr.net/gh/stallenlu/dsh-research-desk@main/index.json
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
索引文件格式(format 1):
|
|
57
115
|
|
|
58
116
|
```json
|
|
59
|
-
{
|
|
117
|
+
{
|
|
118
|
+
"format": 1,
|
|
119
|
+
"title": { "en": "Research Desk", "zh": "科研工作台" },
|
|
120
|
+
"description": { "en": "...", "zh": "..." },
|
|
121
|
+
"metadata": { "categories": ["research", "literature", "productivity"] },
|
|
122
|
+
"plugins": [
|
|
123
|
+
{
|
|
124
|
+
"name": "dsh-research-desk",
|
|
125
|
+
"title": { "en": "Research Desk", "zh": "科研工作台" },
|
|
126
|
+
"description": { "en": "...", "zh": "..." },
|
|
127
|
+
"author": "stallenlu",
|
|
128
|
+
"homepage": "https://github.com/stallenlu/dsh-research-desk",
|
|
129
|
+
"repository": { "url": "https://github.com/stallenlu/dsh-research-desk" },
|
|
130
|
+
"metadata": { "category": "research", "keywords": ["research", "literature", "arxiv", "pubmed", "openalex", "科研", "文献"] },
|
|
131
|
+
"versions": [
|
|
132
|
+
{
|
|
133
|
+
"version": "0.2.0",
|
|
134
|
+
"publishTimestamp": "2026-11-18T01:00:00.000Z",
|
|
135
|
+
"source": { "type": "npm" },
|
|
136
|
+
"engines": { "dsh": ">=0.2.1-rc.5 <0.3.0" }
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
}
|
|
140
|
+
]
|
|
141
|
+
}
|
|
60
142
|
```
|
|
61
143
|
|
|
62
144
|
---
|
|
63
145
|
|
|
64
|
-
##
|
|
146
|
+
## 4. 设置
|
|
65
147
|
|
|
66
|
-
|
|
148
|
+
设置面板共 **22 项**,全部有默认值,改完即时生效,「恢复默认」一键还原。下面按用途分组。
|
|
67
149
|
|
|
68
|
-
|
|
69
|
-
|---|---|---|---|
|
|
70
|
-
| arXiv | `export.arxiv.org/api/query` | 预印本全文(TeX/HTML) | 自然语言检索用 AND 词链;AND 0 命中自动回退 OR 链 |
|
|
71
|
-
| Europe PMC | `ebi.ac.uk/europepmc/webservices/rest/search` | 生命科学 + PMC 全文 | 优先命中 PMC 全文 |
|
|
72
|
-
| OpenAlex | `api.openalex.org/works` | 全学科 + 引用数 + 摘要倒排索引 | 2026-02-13 起 polite pool 已废,`mailto` 改为可选、缺省不发 |
|
|
150
|
+
### 检索
|
|
73
151
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
152
|
+
| 键 | 含义 | 默认值 |
|
|
153
|
+
| --- | --- | --- |
|
|
154
|
+
| `sources` | 检索数据源(`arxiv` / `europepmc` / `openalex`) | 三个全开 |
|
|
155
|
+
| `maxResults` | 单源最大条数(1–40) | `15` |
|
|
77
156
|
|
|
78
|
-
|
|
79
|
-
Europe PMC 的 JATS 里混着 `journal-meta / contrib-group / ref-list` 等元数据噪声,会把
|
|
80
|
-
"pmc Innovation (Camb) … 4094 theinnov 101771342" 这种串混进正文开头,已在 `stripHtml()` 里剥掉。
|
|
157
|
+
### 模型(跨组生效)
|
|
81
158
|
|
|
82
|
-
|
|
159
|
+
| 键 | 含义 | 默认值 |
|
|
160
|
+
| --- | --- | --- |
|
|
161
|
+
| `model.route` | 覆盖宿主默认模型,格式 `provider/model` | 空(用宿主默认) |
|
|
162
|
+
|
|
163
|
+
### 问答
|
|
164
|
+
|
|
165
|
+
| 键 | 含义 | 默认值 |
|
|
166
|
+
| --- | --- | --- |
|
|
167
|
+
| `qa.limit` | 问答检索保留段落数(1–20) | `8` |
|
|
168
|
+
| `qa.minScore` | 检索命中相对阈值(0–1) | `0.6` |
|
|
169
|
+
| `qa.shareFullText` | 是否把全文片段送给模型 | `true`(关掉只用摘要) |
|
|
170
|
+
|
|
171
|
+
### 综述
|
|
172
|
+
|
|
173
|
+
| 键 | 含义 | 默认值 |
|
|
174
|
+
| --- | --- | --- |
|
|
175
|
+
| `review.perspectives` | 综述视角集合(`methodology` / `evidence` / `contradictions` / `gaps` / `applications`) | 方法学 + 证据 + 矛盾 + 缺口 |
|
|
176
|
+
| `review.maxSections` | 单篇综述视角上限(1–5) | `4` |
|
|
177
|
+
|
|
178
|
+
### 运行(外部工具)
|
|
179
|
+
|
|
180
|
+
| 键 | 含义 | 默认值 |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| `runner.enabled` | 是否允许调用外部工具 | `false`(关掉后所有实验命令都被拒绝) |
|
|
183
|
+
| `runner.pythonPath` | Python 解释器路径 | 空(自动探测) |
|
|
184
|
+
| `runner.nodePath` | Node 解释器路径 | 空(自动探测) |
|
|
185
|
+
| `runner.timeoutSec` | 单次调用超时秒数(5–600) | `60` |
|
|
186
|
+
| `runner.workDir` | 调用工作目录 | 空(用数据目录下的 `runs`) |
|
|
187
|
+
| `runner.allowInstall` | 是否允许安装外部包 | `false` |
|
|
188
|
+
| `runner.packages` | 预装包名,逗号分隔 | 空 |
|
|
189
|
+
|
|
190
|
+
### 统计
|
|
191
|
+
|
|
192
|
+
| 键 | 含义 | 默认值 |
|
|
193
|
+
| --- | --- | --- |
|
|
194
|
+
| `stats.alpha` | 显著性水平(0.0001–0.5) | `0.05` |
|
|
195
|
+
| `stats.adjust` | 多重比较校正(`none` / `holm` / `bonferroni`) | `holm` |
|
|
196
|
+
|
|
197
|
+
### 隐私
|
|
198
|
+
|
|
199
|
+
| 键 | 含义 | 默认值 |
|
|
200
|
+
| --- | --- | --- |
|
|
201
|
+
| `privacy.shareAbstracts` | 是否把摘要送给模型(影响选题与草稿) | `true` |
|
|
83
202
|
|
|
84
|
-
|
|
203
|
+
### 存储
|
|
85
204
|
|
|
86
|
-
|
|
205
|
+
| 键 | 含义 | 默认值 |
|
|
206
|
+
| --- | --- | --- |
|
|
207
|
+
| `storage.dataDir` | 数据落地目录 | 空(用 DSH_HOME 数据目录) |
|
|
87
208
|
|
|
88
|
-
|
|
89
|
-
桌面端「插件 → 实验性插件 → 自定义插件索引」填:
|
|
90
|
-
`https://raw.githubusercontent.com/<owner>/<repo>/main/index.json`
|
|
91
|
-
或 jsDelivr 镜像 `https://cdn.jsdelivr.net/gh/<owner>/<repo>@main/index.json`(最多晚 12 小时同步)。
|
|
92
|
-
2. **直装包名**:插件页输入 `dsh-research-desk`。
|
|
93
|
-
3. **命令行**(本机 `dsh` CLI 不在 PATH,需先补 PATH):
|
|
94
|
-
```bash
|
|
95
|
-
dsh plugin --profile desktop add dsh-research-desk
|
|
96
|
-
```
|
|
97
|
-
桌面 profile 必须**完全退出**再装,否则安装会静默不生效。
|
|
209
|
+
### 密钥
|
|
98
210
|
|
|
99
|
-
|
|
211
|
+
| 键 | 含义 | 默认值 |
|
|
212
|
+
| --- | --- | --- |
|
|
213
|
+
| `secrets.openalexKey` | OpenAlex 密钥的环境变量名 | 空 |
|
|
214
|
+
| `secrets.semanticScholarKey` | Semantic Scholar 密钥的环境变量名 | 空 |
|
|
215
|
+
| `secrets.openalexMailto` | OpenAlex 联系邮箱的环境变量名 | 空 |
|
|
216
|
+
|
|
217
|
+
> **密钥项怎么工作**:这三个设置**只保存环境变量的名字**(例如 `OPENALEX_API_KEY`),值在调用时从环境里读取。
|
|
218
|
+
> 变量名本身也不会出现在导出文件里(那里只留 `{configured: true/false}`),`state.json` 里存的同样只是名字——**密钥值从不落盘、不进任何导出**。
|
|
219
|
+
|
|
220
|
+
完整的键、类型、取值范围见 [docs/settings.md](docs/settings.md)。
|
|
100
221
|
|
|
101
222
|
---
|
|
102
223
|
|
|
103
|
-
## 5.
|
|
224
|
+
## 5. 工具调用
|
|
225
|
+
|
|
226
|
+
Agent 侧只有一个工具:`research_desk`(超时 300 秒,标记为并发安全)。全部能力靠 `action` 参数切换,共 18 个动作;返回体统一带 `ok` / `action` / `message`,多数动作还带 `count` 与最新的 `library` 视图。
|
|
227
|
+
|
|
228
|
+
| action | 作用 | 主要参数 |
|
|
229
|
+
| --- | --- | --- |
|
|
230
|
+
| `status` | 库内篇数、选题数、草稿数与当前默认模型 | — |
|
|
231
|
+
| `models` | 列出宿主可调用的模型 | — |
|
|
232
|
+
| `search` | 三源检索(免密钥) | `query`、`sources`、`maxResults` |
|
|
233
|
+
| `add` | 把文献放进文献库(自动去重) | `papers` |
|
|
234
|
+
| `library` | 列出文献库、选题、草稿、综述、实验与问答记录 | — |
|
|
235
|
+
| `read` | 抓全文并切成可检索片段入库 | `paperId` |
|
|
236
|
+
| `ask` | 只用库内全文回答,每条引文逐字核验 | `question`、`paperIds` |
|
|
237
|
+
| `hypothesis` | 从文献库推出可证伪选题 | — |
|
|
238
|
+
| `review` | 写多视角综述,逐条核验引文 | `topic`、`perspectives` |
|
|
239
|
+
| `gaps` | 只找研究缺口 | `topic` |
|
|
240
|
+
| `draft` | 写论文大纲 | `instruction` |
|
|
241
|
+
| `remove` | 移出一篇文献 | `paperId` |
|
|
242
|
+
| `undo` | 撤销上一步 | — |
|
|
243
|
+
| `settings` | 查看 / 修改 / 恢复默认设置 | `patch`、`reset` |
|
|
244
|
+
| `experiments` | 列出实验记录 | — |
|
|
245
|
+
| `run` | 在受限工作目录里跑 python 或 node | `title`、`runtime`、`code`、`packages`、`hypothesisId` |
|
|
246
|
+
| `stats` | 统计自查(t 检验、效应量、多重比较校正) | `kind`、`groupA`、`groupB`、`mu0`、`pvalues` |
|
|
247
|
+
| `export` | 导出 md / bib / json | `formats` |
|
|
248
|
+
|
|
249
|
+
参数取值:`sources` 是 `arxiv` / `europepmc` / `openalex`;`perspectives` 是 `methodology` / `evidence` / `contradictions` / `gaps` / `applications`;`runtime` 是 `python` / `node`;`kind` 是 `one-sample` / `two-sample-welch` / `paired`;`formats` 是 `md` / `bib` / `json`;`maxResults` 1–40(默认 12)。
|
|
104
250
|
|
|
251
|
+
调用示例:
|
|
252
|
+
|
|
253
|
+
```json
|
|
254
|
+
{ "action": "search", "query": "retrieval augmented generation evaluation", "sources": ["arxiv", "openalex"], "maxResults": 12 }
|
|
105
255
|
```
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
lib/desk.mjs 领域模型与唯一写路径(字段白名单、去重、操作集)
|
|
110
|
-
lib/store.mjs 原子落盘、mtime 重读、串行写队列、30 步 undo
|
|
111
|
-
lib/llm.mjs 模型路由与流式调用(block-end 聚合、sessionId 自带)
|
|
112
|
-
lib/client.js 侧栏面板(免构建 React.createElement)
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
{ "action": "ask", "question": "这些方法在检索阶段用了什么索引结构?", "paperIds": ["<library 里这篇文献的 id>"] }
|
|
113
259
|
```
|
|
114
260
|
|
|
115
|
-
|
|
116
|
-
|
|
261
|
+
```json
|
|
262
|
+
{ "action": "run", "title": "BM25 复现", "runtime": "python", "code": "print(sum(range(10)))", "hypothesisId": "<选题 id>" }
|
|
263
|
+
```
|
|
117
264
|
|
|
118
|
-
|
|
119
|
-
`C:/Users/<用户>/.dsh/research-desk/state.json`)。桌面端与 Web 端共享这一份。
|
|
120
|
-
写入是「临时文件 + rename」原子替换;每次写前按 mtime 重读,两个宿主进程同时跑不会互相覆盖;
|
|
121
|
-
撤销采用三方回滚(只回滚这一步真正改动的字段,别人之后的改动不动)。
|
|
265
|
+
---
|
|
122
266
|
|
|
123
|
-
|
|
124
|
-
- 侧栏只走同源 `POST /api/research-desk/`,并校验 `sec-fetch-site` 与 loopback 来源,非同源一律 403。
|
|
125
|
-
- 请求体上限 512 KB。
|
|
126
|
-
- 模型调用在会话外进行,必须自带 `sessionId`(`dsh-research-desk-<uuid>`),否则部分网关会报 `MissingSessionID`。
|
|
267
|
+
## 6. MCP
|
|
127
268
|
|
|
128
|
-
|
|
269
|
+
`lib/mcp.mjs` 同时提供一个 stdio 传输的 MCP server,让别的 agent 也能用同一份文献库。
|
|
129
270
|
|
|
130
|
-
|
|
271
|
+
- 协议版本 `2024-11-05`,服务名 `dsh-research-desk`,版本 `0.2.0`,能力声明为 `tools`。
|
|
272
|
+
- stdout 只走 JSON-RPC,诊断日志走 stderr;`notifications/initialized` 不回包。
|
|
273
|
+
- 与桌面面板共用同一个 `state.json` 与同一套 `applyOps` 写路径,**MCP 写入的内容在面板里立刻可见**。
|
|
274
|
+
|
|
275
|
+
| 工具 | 参数 |
|
|
276
|
+
| --- | --- |
|
|
277
|
+
| `research_search` | `query`(必填)、`sources`(`arxiv`/`europepmc`/`openalex`,缺省三个都查)、`maxResults`(1–40,缺省 10) |
|
|
278
|
+
| `research_library_list` | `status`(`new`/`reading`/`read`/`kept`/`dropped`)、`limit`(1–200,缺省 50) |
|
|
279
|
+
| `research_library_add` | `papers`(必填,数组;每篇至少 `title`,可选 `abstract`/`venue`/`year`/`doi`/`arxivId`/`pmid`/`pmcid`/`url`/`source`/`authors`/`tags`/`status`/`note`) |
|
|
280
|
+
| `research_library_remove` | `paperId`(必填,取自 `research_library_list`) |
|
|
281
|
+
| `research_export` | `format`(`markdown`/`json`/`bibtex`,缺省 `markdown`)、`paperIds`(缺省导出全部) |
|
|
282
|
+
|
|
283
|
+
启动命令(在插件目录里执行,已实测可用):
|
|
131
284
|
|
|
132
285
|
```bash
|
|
133
|
-
node
|
|
134
|
-
|
|
286
|
+
node -e "import('./lib/mcp.mjs').then(m => m.runMcpStdio())"
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
挂到别的 MCP 客户端上,用文件绝对路径最省事(`package.json` 的 `exports` 只暴露 `.` 与 `./client`,没有导出 `lib/mcp.mjs` 子路径):
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"mcpServers": {
|
|
294
|
+
"dsh-research-desk": {
|
|
295
|
+
"command": "node",
|
|
296
|
+
"args": ["-e", "import('file:///ABS/PATH/dsh-research-desk/lib/mcp.mjs').then(m => m.runMcpStdio())"]
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
}
|
|
135
300
|
```
|
|
136
301
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
302
|
+
数据目录默认同样是 `$DSH_HOME/research-desk`;要单独隔开就传 `dataDir`。
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## 7. 数据与安全边界
|
|
307
|
+
|
|
308
|
+
- **数据目录**:默认 `$DSH_HOME/research-desk/state.json`(`DSH_HOME` 未设时为 `~/.dsh/research-desk/state.json`,Windows 即 `C:\Users\<用户>\.dsh\research-desk\state.json`)。`storage.dataDir` 可以改落地目录。
|
|
309
|
+
- **读与写**:检索与全文抓取只做对外只读请求;写入只发生在 `state.json`(临时文件 + rename 原子替换)与 `runs` 工作目录;插件没有对外删除或上传接口。
|
|
310
|
+
- **外部命令**:`spawn(cmd, args, { shell: false })`,参数永远是数组,不拼 shell 字符串;只允许 `python` 与 `node`;脚本写进受限工作目录,工作目录必须落在允许根目录内(`runner.workDir`、数据目录、`storage.dataDir`),否则报「工作目录不在允许范围内:…」;解释器只拿到脚本文件路径这一个参数。
|
|
311
|
+
- **超时与日志**:超时由 `runner.timeoutSec` 控制(5–600 秒,默认 60),到点终止;stdout / stderr 落盘到 `<workDir>/logs/<脚本名>.stdout.log` 与 `<脚本名>.stderr.log`,返回值截到 20000 字符,实验记录里保存,界面显示截到 4000 字符。
|
|
312
|
+
- **装包**:默认关闭(`runner.allowInstall` 为 `false`);打开后只接受 `pip install` 与 `npm install` 两种形式,包名按 `/^[A-Za-z0-9@._-]+(\[[^\]]+\])?(==[0-9A-Za-z.*-]+)?$/` 校验,一次最多 20 个;Windows 上 npm 走 `node npm-cli.js`,同样不经过 shell。
|
|
313
|
+
- **HTTP 入口**:只接受 `POST /api/research-desk/`,非 POST 返回 405;同源检查要求回环地址,且 Origin 为空、是 `dsh-app://`、或指向回环地址,否则 403 `origin rejected`;请求体上限 512 KB,超限返回 `payload-too-large`。
|
|
314
|
+
- **密钥**:只存环境变量名,值在调用时从环境读取;`state.json` 与任何导出里都没有密钥值。
|
|
315
|
+
|
|
316
|
+
更细的边界见 [docs/security.md](docs/security.md)。
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 8. 引文可信性设计
|
|
321
|
+
|
|
322
|
+
四步,每一步都对应代码里的一处检查:
|
|
323
|
+
|
|
324
|
+
1. **要求逐字引用**:问答与综述的系统提示都写明「只能用检索到的段落」「逐字引用原文」「每个事实句标 `[S1]`/`[S2]` 段落标记」「缺什么就说缺什么,不许编」。
|
|
325
|
+
2. **逐条比对**:返回的每条引文必须在对应片段里逐字命中(`hit.text.includes(quote)`,综述侧允许空白归一后匹配)。
|
|
326
|
+
3. **对不上就剔除**:命中失败的引文进 `unverified` 列表并从结论里剔除,同时带上原因(`quote not present in source` / `no matching chunk` / 「引用与原文不一致」/「找不到对应段落」/「引文是空的」);面板和工具返回都显式给出剔除条数。
|
|
327
|
+
4. **没命中就不调模型**:检索为空时直接回答「库里没有能回答这个问题的段落」,一次模型请求都不发;综述某个视角没有可支撑段落时写「文献库中没有可支撑的段落。」,同样不发模型请求。
|
|
328
|
+
|
|
329
|
+
结论就是:**没有命中就不是答案,是一次诚实的「没找到」**。
|
|
143
330
|
|
|
144
331
|
---
|
|
145
332
|
|
|
146
|
-
##
|
|
333
|
+
## 9. 已知限制
|
|
147
334
|
|
|
148
|
-
-
|
|
149
|
-
|
|
150
|
-
-
|
|
151
|
-
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
-
|
|
155
|
-
- **检索覆盖有限**:三个源不等于全网。Google Scholar 无官方 API,Scopus / Web of Science 需付费订阅,本插件不接。
|
|
335
|
+
- **插件还没有在真实宿主会话里端到端安装验证过**:侧栏 slot 注册、工具注册、面板渲染都还是纸面推演,这是当前最大的未知项。
|
|
336
|
+
- **外部运行时依赖使用者自己的机器**:探测顺序是设置里的解释器路径 → 常见命令名(`python` / `python3` / `py -3` / `node`)→ DSH 自带运行时;探不到就没有执行环境。
|
|
337
|
+
- **综述与问答的质量取决于库里的全文覆盖**:只抓了摘要的文献不参与综述,也不参与引文核验。
|
|
338
|
+
- **导出的 JSON 默认不含全文片段**:只留片段序号与标题,正文留在本地库里。
|
|
339
|
+
- **没有多用户与权限模型**:状态是一份本地文件,没有账号、角色或协作冲突界面;撤销栈是单机的 30 步。
|
|
340
|
+
- **检索只覆盖三个开放源**:Google Scholar 没有官方 API,Scopus / Web of Science 需要付费订阅。
|
|
341
|
+
- **选题与草稿的输入只有标题和摘要**,做不了机制级结论。
|
|
156
342
|
|
|
157
343
|
---
|
|
158
344
|
|
|
159
|
-
##
|
|
345
|
+
## 10. 开发与测试
|
|
160
346
|
|
|
161
|
-
|
|
347
|
+
目录布局一行说明:`lib/` 是全部实现(host / search / qa / review / runner / export / desk / store / settings / stats / llm / mcp / client),`test/` 是 `node:test` 单测与两个联网探针脚本,`docs/` 是本文档目录,`index.json` 是 dshmarket 索引条目。
|
|
162
348
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
349
|
+
Windows 上 `node --test` 必须显式给出文件路径(不能只写目录),一次跑完全部单测:
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
node --test test/desk.test.mjs test/export.test.mjs test/mcp.test.mjs test/review.test.mjs test/runner.test.mjs test/search.test.mjs test/settings.test.mjs test/stats.test.mjs
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
共 88 个用例,当前全绿。两个探针脚本会真实联网,用来验证上游连通性:
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
node test/live-probe.mjs
|
|
359
|
+
node test/raw-probe.mjs
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
发布流程:
|
|
363
|
+
|
|
364
|
+
1. `npm publish`(包名 `dsh-research-desk`,主入口 `lib/host.mjs`,客户端入口 `lib/client.js`)。
|
|
365
|
+
2. GitHub 仓库 <https://github.com/stallenlu/dsh-research-desk> 维护 README、`docs/` 与 MIT LICENSE。
|
|
366
|
+
3. 向 awesome-dsh-plugin 精选列表提 PR 收录本插件——dshmarket 读取的就是这份精选列表;同时在 `index.json` 里更新版本号与发布时间。
|
|
367
|
+
|
|
368
|
+
---
|
|
168
369
|
|
|
169
|
-
## 许可证
|
|
370
|
+
## 11. 许可证
|
|
170
371
|
|
|
171
|
-
MIT
|
|
372
|
+
MIT,见 [LICENSE](LICENSE)。
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// dsh-research-desk — stdio MCP server.
|
|
3
|
+
//
|
|
4
|
+
// Usage: dsh-research-desk-mcp
|
|
5
|
+
//
|
|
6
|
+
// Reads JSON-RPC lines on stdin and writes JSON-RPC responses to stdout.
|
|
7
|
+
// Diagnostics go to stderr only: stdout carries JSON-RPC messages.
|
|
8
|
+
//
|
|
9
|
+
// The server reads and writes the same state file as the desktop panel, so a
|
|
10
|
+
// library built in the panel is visible to any agent attached to this server.
|
|
11
|
+
import { runMcpStdio } from '../lib/mcp.mjs'
|
|
12
|
+
|
|
13
|
+
runMcpStdio().catch((err) => {
|
|
14
|
+
const message = err && err.message ? err.message : String(err)
|
|
15
|
+
process.stderr.write('dsh-research-desk-mcp failed: ' + message + '\n')
|
|
16
|
+
process.exitCode = 1
|
|
17
|
+
})
|
package/index.json
CHANGED
|
@@ -10,9 +10,8 @@
|
|
|
10
10
|
},
|
|
11
11
|
"metadata": {
|
|
12
12
|
"categories": [
|
|
13
|
-
"
|
|
14
|
-
"
|
|
15
|
-
"productivity"
|
|
13
|
+
"tools",
|
|
14
|
+
"docs"
|
|
16
15
|
]
|
|
17
16
|
},
|
|
18
17
|
"plugins": [
|
|
@@ -32,7 +31,7 @@
|
|
|
32
31
|
"url": "https://github.com/stallenlu/dsh-research-desk"
|
|
33
32
|
},
|
|
34
33
|
"metadata": {
|
|
35
|
-
"category": "
|
|
34
|
+
"category": "tools",
|
|
36
35
|
"keywords": [
|
|
37
36
|
"research",
|
|
38
37
|
"literature",
|
|
@@ -53,8 +52,8 @@
|
|
|
53
52
|
},
|
|
54
53
|
"versions": [
|
|
55
54
|
{
|
|
56
|
-
"version": "0.
|
|
57
|
-
"publishTimestamp": "2026-11-18T01:
|
|
55
|
+
"version": "0.3.0",
|
|
56
|
+
"publishTimestamp": "2026-11-18T01:30:00.000Z",
|
|
58
57
|
"source": {
|
|
59
58
|
"type": "npm"
|
|
60
59
|
},
|
package/lib/host.mjs
CHANGED
|
@@ -334,8 +334,14 @@ export function createService(ctx) {
|
|
|
334
334
|
const query = cleanText(args.query, 500)
|
|
335
335
|
if (!query) return { ok: false, action: 'search', message: '检索词是空的。' }
|
|
336
336
|
const settings = readSettings(await readState())
|
|
337
|
-
|
|
338
|
-
|
|
337
|
+
// An explicitly empty list means "search no source at all". The settings
|
|
338
|
+
// help text promises exactly that, so an empty array must not silently fall
|
|
339
|
+
// back to the defaults. Only a missing argument falls back to the stored value.
|
|
340
|
+
const picked = Array.isArray(args.sources) ? args.sources : settings['sources']
|
|
341
|
+
const sources = Array.isArray(picked) ? picked : undefined
|
|
342
|
+
if (Array.isArray(sources) && !sources.length) {
|
|
343
|
+
return { ok: false, action: 'search', message: '没有选中任何数据源,检索没有执行。', papers: [], count: 0, errors: [] }
|
|
344
|
+
}
|
|
339
345
|
const maxResults = Math.min(Math.max(Number(args.maxResults) || Number(settings['maxResults']) || 12, 1), 40)
|
|
340
346
|
const mailto = resolveSecret(settings, 'secrets.openalexMailto')
|
|
341
347
|
const result = await search(query, { sources, maxResults, signal: args.signal, mailto: mailto ? mailto.value : '' })
|
|
@@ -378,7 +384,7 @@ export function createService(ctx) {
|
|
|
378
384
|
async library() {
|
|
379
385
|
const state = await readState()
|
|
380
386
|
const papers = (state.papers || []).map(publicPaper)
|
|
381
|
-
const lines = papers.length ? papers.map(p => '- [' + p.status + '] ' + p.title + (p.year ? ' (' + p.year + ')' : '') + ' · ' + (p.venue || '未知来源') + ' · ' + (p.chunks ? p.chunks + ' 段全文' : '仅摘要'))
|
|
387
|
+
const lines = papers.length ? papers.map(p => '- [' + p.status + '] ' + p.title + (p.year ? ' (' + p.year + ')' : '') + ' · ' + (p.venue || '未知来源') + ' · ' + (p.chunks ? p.chunks + ' 段全文' : '仅摘要')) : ['文献库是空的。']
|
|
382
388
|
return { ok: true, action: 'library', message: '文献库 ' + papers.length + ' 篇:\n' + lines.join('\n'), library: libraryView(state), count: papers.length }
|
|
383
389
|
},
|
|
384
390
|
async readPaper(args) {
|
package/lib/mcp.mjs
CHANGED
|
@@ -17,7 +17,7 @@ import { cleanText, isObject } from './util.mjs'
|
|
|
17
17
|
|
|
18
18
|
const PROTOCOL_VERSION = '2024-11-05'
|
|
19
19
|
const SERVER_NAME = 'dsh-research-desk'
|
|
20
|
-
const SERVER_VERSION = '0.
|
|
20
|
+
const SERVER_VERSION = '0.3.0'
|
|
21
21
|
const DATA_DIR_NAME = 'research-desk'
|
|
22
22
|
|
|
23
23
|
/**
|
|
@@ -206,7 +206,10 @@ export function createMcpServer({ dataDir, logger } = {}) {
|
|
|
206
206
|
async function doSearch(args) {
|
|
207
207
|
const query = cleanText(args.query, 500)
|
|
208
208
|
if (!query) return toolError('检索词是空的。')
|
|
209
|
-
|
|
209
|
+
// An explicitly empty list means "query no source"; only a missing argument
|
|
210
|
+
// means "use every source".
|
|
211
|
+
if (Array.isArray(args.sources) && !args.sources.length) return toolError('没有选中任何数据源,检索没有执行。')
|
|
212
|
+
const sources = Array.isArray(args.sources) ? args.sources.map(String) : undefined
|
|
210
213
|
const maxResults = Math.min(Math.max(Number(args.maxResults) || 10, 1), 40)
|
|
211
214
|
const result = await search(query, { sources, maxResults })
|
|
212
215
|
return toolResult({
|
package/lib/search.mjs
CHANGED
|
@@ -240,8 +240,10 @@ const RUNNERS = { arxiv: searchArxiv, europepmc: searchEuropePmc, openalex: sear
|
|
|
240
240
|
export async function search(query, options = {}) {
|
|
241
241
|
const text = String(query || '').trim()
|
|
242
242
|
if (!text) return { papers: [], errors: ['检索词是空的'] }
|
|
243
|
-
|
|
244
|
-
|
|
243
|
+
// An explicitly empty source list is honoured: it means "query nothing".
|
|
244
|
+
// Only a missing option falls back to every source.
|
|
245
|
+
const requested = Array.isArray(options.sources) ? options.sources : SOURCES
|
|
246
|
+
const sources = requested.filter(name => RUNNERS[name])
|
|
245
247
|
const max = Math.min(Math.max(Number(options.maxResults) || 10, 1), 40)
|
|
246
248
|
const settled = await Promise.all(sources.map(async name => {
|
|
247
249
|
try {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-research-desk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "DeepSeek Harness plugin: a research desk for literature discovery, anchored reading, multi-perspective review, hypothesis tracking, sandboxed verification runs and export.",
|
|
6
6
|
"homepage": "https://github.com/stallenlu/dsh-research-desk#readme",
|
|
@@ -14,8 +14,12 @@
|
|
|
14
14
|
"exports": {
|
|
15
15
|
".": "./lib/host.mjs",
|
|
16
16
|
"./client": "./lib/client.js",
|
|
17
|
+
"./mcp": "./lib/mcp.mjs",
|
|
17
18
|
"./package.json": "./package.json"
|
|
18
19
|
},
|
|
20
|
+
"bin": {
|
|
21
|
+
"dsh-research-desk-mcp": "./bin/dsh-research-desk-mcp.mjs"
|
|
22
|
+
},
|
|
19
23
|
"dsh": {
|
|
20
24
|
"bundle": {
|
|
21
25
|
"patch": "./cordis.patch.yml"
|
|
@@ -27,6 +31,7 @@
|
|
|
27
31
|
},
|
|
28
32
|
"files": [
|
|
29
33
|
"lib",
|
|
34
|
+
"bin",
|
|
30
35
|
"cordis.patch.yml",
|
|
31
36
|
"index.json",
|
|
32
37
|
"README.md",
|