# DSH LitResearch

**科学文献深度调研 MCP Server + DeepSeek Harness（DSH）插件。** 跨 Europe PMC、Semantic Scholar、PubMed、OpenAlex、arXiv、Crossref 等 8+ 学术数据源递归检索，回答科学问题并产出**带引用溯源、带证据等级、带红队审查评分、带成本明细**的深度调研报告。

English: a DeepResearch-style MCP server & DSH plugin for scientific literature — recursive multi-source search, outline-first two-phase workflow, citation verification, red-team review, and cited Markdown/HTML reports (zh/en).

---

## 功能特性

| 能力 | 说明 |
|---|---|
| **两阶段工作流** | `plan_research` 先生成大纲（子问题 + 检索词）→ **必须经用户确认**（含「8 秒内确认自动拦截」防跳过门禁）→ `execute_research` 执行 |
| **递归深度调研** | 规划 → 并行检索 → 粗排 → 提炼 → 反思补充检索 → 综合成稿；`breadth`（子问题数）× `depth`（递归层数）可调 |
| **引文三级校验** | L1 DOI 存在性（Crossref）／ L2 结论-引文一致性 NLI（支持/矛盾/无关/无法核验四分类）／ L3 证据等级 |
| **红队对抗审查** | 规则检查 + LLM 审查 + 五维 rubric 评分（覆盖度/争议/引用有效性/断言克制度/时效性），fail 触发**分类化最小修复循环**（JSON edits 逐条应用，不全文重写） |
| **奠基文献召回** | LLM 列出领域公认奠基文献 → Crossref 题名验证防幻觉 → 补入文献池并强制覆盖 |
| **元数据回填** | OpenAlex（type 判定综述/原创的权威信号）+ Crossref（DOI/卷期页/期刊）双向补全，429/5xx 指数退避重试 |
| **文献池去重** | DOI 归一化 + 预印本↔正式版版本合并 + **题名相似度合并**（跨来源重复条目） |
| **断点续跑** | 检索/撰写完成即落盘检查点；任务失败重跑自动跳过已完成阶段，不重复烧 token |
| **交付物双模式** | `full`（正文+审稿附录）／ `clean`（正文干净稿，红队/概览/校对独立成 `<slug>-review.md`） |
| **行文校对** | 术语一致性（如 FcγRIIIa/FcγRIIIA 混用）+ 超长句/重复标点/括号引号不配对启发式检测 |
| **进度可视化** | 11 阶段加权进度条（plan→search→…→export）+ 心跳保活 + 阶段级 ETA |
| **任务持久化** | SQLite 任务状态机：创建/查询/列表/删除/恢复中断任务 |
| **报告输出** | Markdown / 自包含 HTML（内嵌 SVG 图表）/ JSON；zh / en 双语；按模型 token 计价的成本明细 |
| **可选增强** | OA 全文深读 `read_paper`、引文滚雪球 `get_citations`、Sci-Hub 兜底、机构 EZProxy / TDM API |

**质量实测**（同一主题「B 细胞发育与抗体 Fc 效应机制」修复前后复跑对比）：红队五维评分 **67.6/fail → 87.1/pass**，其中引用有效性 0/20 → 19.5/20；空号文献表、跨来源重复条目、综述误标等问题在本版本中已修复。

---

## 安装

### 方式一：作为 DSH 插件（聊天框内直接使用，推荐）

前置：Python ≥ 3.10、`pip`（或 `uv`）。

```bash
git clone https://github.com/Wang-JQ77/dsh-litresearch.git
cd dsh-litresearch
pip install -e .          # 或 uv sync
```

然后接入 DSH：

1. 打开 `plugin/cordis.patch.yml`，把 `command` / `args` 改为你本机的解释器与 `launcher.py` 绝对路径（文件内有注释示例）；
2. 将 `plugin/` 目录按 DSH 插件机制挂载（DSH settings 的 plugins 引用该目录，或复制到 DSH 插件目录）；
3. 重启 DSH，聊天框出现 LitResearch 开关即接入成功。

### 方式二：通用 MCP Client（stdio）

```bash
pipx install dsh-litresearch      # 或 uv tool install dsh-litresearch
# 在任意支持 MCP 的客户端中注册 stdio 命令：dsh-litresearch
```

### 方式三：源码运行（开发）

```bash
git clone https://github.com/Wang-JQ77/dsh-litresearch.git
cd dsh-litresearch
uv sync                                 # 或 pip install -e .
cp .env.example .env                    # 填入 LLM Key
uv run dsh-litresearch             # stdio 模式启动
```

---

## 配置

LLM 使用任意 **OpenAI 兼容端点**（DeepSeek / 智谱 BigModel / OpenRouter / 自建网关均可）。两处配置，优先级：`~/.dsh-litresearch/settings.json` > 仓库根 `.env` > 默认值。

**`.env`（单 Provider，最简）**

```ini
DEEPSEEK_API_KEY=你的Key
DEEPSEEK_BASE_URL=https://api.deepseek.com        # 任意 OpenAI 兼容端点
DEEPSEEK_MODEL=deepseek-chat
S2_API_KEY=                                       # Semantic Scholar（强烈建议，保底 1 RPS）
NCBI_API_KEY=                                     # PubMed
OPENALEX_MAILTO=you@example.com                   # OpenAlex/Crossref polite pool（强烈建议）
CROSSREF_MAILTO=you@example.com
```

**`settings.json`（多 Provider 回退链 + 质量开关）**

```json
{
  "llm": { "providers": [ {"api_key": "...", "model": "...", "base_url": "..."} ] },
  "quality": {
    "metadata_enrichment": true,
    "landmark_recall": true,
    "proofread": true,
    "claim_validation": true,
    "controversy_detection": true,
    "critic_repair_rounds": 1
  },
  "report": { "language": "zh", "format": "markdown", "deliverable_style": "full" }
}
```

- `deliverable_style`: `full`（正文+审稿附录，默认）｜ `clean`（正文干净稿 + 独立 `-review.md` 审稿文件）
- Sci-Hub / 机构 EZProxy / Elsevier·Wiley TDM 等可选能力：插件内调用 `get_config_guide()` 查看申请与配置方式
- 报告落盘默认 `~/.dsh-litresearch/reports/`，可用 `DRS_REPORT_DIR` / `DRS_DB_PATH` 重定向

---

## MCP 工具一览

| 工具 | 说明 |
|---|---|
| `deep_research(question, breadth, depth, max_papers, sources, format, critique, track, language)` | 深度调研（直达模式），返回带引用报告 + `report_paths` + 成本摘要（异步 + 进度通知） |
| `plan_research(question, breadth, language, track)` | 两阶段第一步：生成大纲，返回 `job_id`，**不执行检索** |
| `execute_research(job_id, plan_override, depth, ..., confirm)` | 两阶段第二步：确认/修改大纲后执行；`confirm` 门禁见下 |
| `search_literature(query, sources, limit, mode)` | 跨源检索，返回归一化元数据 + 摘要 |
| `read_paper(doi/arxiv_id/pmid/pmcid, max_chunks)` | OA 全文获取并分块返回 |
| `get_citations(paper_id, direction, limit)` | 引文扩展（滚雪球） |
| `create/get/list/delete/recover_research_jobs` | 任务持久化状态机（含中断恢复） |
| `get_settings / set_settings / get_config_guide / get_status` | 插件设置、数据源健康检查 |

### 两阶段工作流（大纲先行确认）

```
① plan_research(question="……", breadth=5)
   → 返回 job_id + 大纲 + awaiting_user_confirmation=true
     （agent_instruction 要求把大纲完整展示给用户并停止）
② 用户确认/修改后：
   execute_research(job_id, confirm=true)                 # 原样确认
   execute_research(job_id, plan_override=[修改后大纲])    # 修改即确认
   ※ 大纲生成后 8 秒内的 confirm 会被自动拦截（防 agent 跳过用户直接执行），
     用户确认后再调用即可正常放行
```

---

## 数据源（8+）

Europe PMC · Semantic Scholar · PubMed · OpenAlex · arXiv · Crossref · bioRxiv/medRxiv（经 Europe PMC）· Google Scholar（可选 SerpAPI）。全文获取链：Europe PMC fullTextXML → arXiv → Unpaywall →（可选）Sci-Hub / 机构 EZProxy / TDM API。

---

## 致谢与参考项目

本项目的「规划 → 并行检索 → 提炼 → 反思递归补充 → 综合成稿」深度调研范式与引用溯源报告形态，在设计时参考了以下优秀开源项目（本项目为独立实现，非其分支）：

- [dzhng/deep-research](https://github.com/dzhng/deep-research) —— 递归式深度调研范式（广度/深度参数、缺口驱动的补充检索）
- [assafelovic/gpt-researcher](https://github.com/assafelovic/gpt-researcher) —— 带引用研究报告的生成与组织思路
- [stanford-oval/storm](https://github.com/stanford-oval/storm) —— 大纲驱动、引用规范的学术写作思路
- [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) —— MCP 服务端框架
- [allenai/SPECTER](https://github.com/allenai/SPECTER)（SPECTER2，`EMBEDDING_PROVIDER=specter2` 可选）—— 语义嵌入驱动的文献聚类与推荐

同时依赖并感谢 [rapidfuzz](https://github.com/rapidfuzz/RapidFuzz)、[scikit-learn](https://github.com/scikit-learn/scikit-learn)、[networkx](https://github.com/networkx/networkx)、[httpx](https://github.com/encode/httpx)、[pydantic](https://github.com/pydantic/pydantic) 等开源库。

---

## 法律与合规

- 全文获取默认仅使用 OA 渠道；Sci-Hub / 机构订阅功能默认关闭，启用需显式确认并遵守当地法律法规与机构政策。
- 报告由 LLM 生成，引用与结论请以所附 DOI 原文为准；L1–L3 校验降低但不消除错误引用风险。

## License

[MIT](LICENSE)