Metadata-Version: 2.4
Name: cnki-deepsearch
Version: 0.2.1
Summary: CNKI DeepSearch — 知网深搜 MCP 工具。拦截知网内部 REST API，一次页面访问获取摘要+参考文献+引证文献+相似论文+关键词权重七维数据。
Author: weileyao2005
License: MIT
Project-URL: Homepage, https://github.com/weileyao2005/cnki-deepsearch
Project-URL: Repository, https://github.com/weileyao2005/cnki-deepsearch
Project-URL: Issues, https://github.com/weileyao2005/cnki-deepsearch/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: lxml>=4.9
Requires-Dist: mcp<2,>=1.0
Requires-Dist: playwright>=1.40
Requires-Dist: pydantic>=2.0

# CNKI DeepSearch

> 知网深搜 — 一次搜索，七维数据。不只是摘要。

[![Version](https://img.shields.io/badge/version-0.2.0-blue)](https://github.com/weileyao2005/cnki-deepsearch)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-yellow)]()

**CNKI DeepSearch** 是一个知网学术搜索的 MCP (Model Context Protocol) 工具。在原有 `cnki-search-mcp` 的基础上，通过拦截 CNKI 内部 REST API，一次页面访问即可获取论文的**七个维度数据**：摘要、关键词、参考文献、引证文献、相似论文、关键词权重、引用统计。

---

## 与原版的区别

| 维度 | 原版 cnki-search-mcp | CNKI DeepSearch |
|------|---------------------|-----------------|
| 搜索 + 摘要 | ✅ | ✅ |
| 下载 PDF | ✅ | ✅ |
| 参考文献列表 | ❌ | ✅ 含标题/作者/来源/年份/URL |
| 引证文献列表 | ❌ | ✅ 谁引用了这篇论文 |
| 共引 / 二级引用 | ❌ | ✅ 间接引用关系 |
| 相似论文推荐 | ❌ | ✅ CNKI 算法推荐 |
| 关键词权重 | ❌ | ✅ PUC 权重排序 |
| 知识图谱推演 | ❌ | ✅ 论文→引用→论文 多层链条 |
| 浏览器保活 | ❌ | ✅ 同 session 不重启 |
| dual-mode | ❌ | ✅ basic(快) / full(全) |

---

## 安装

```bash
pip install cnki-deepsearch
```

> 详细配置见 [MCP 设置说明](#). 首次使用需完成 CNKI 验证码，cookie 自动保存后续无需重复验证。

---

## 工具列表

### `cnki_search_with_abstracts`（主力）

```
搜索 + 自动打开每篇论文获取详细信息

mode="full" (默认): 摘要 + 关键词 + 参考文献 + 引证文献 + 相似论文 + 关键词权重
mode="basic":        仅摘要 + 关键词（快，10篇约15秒）
```

### `cnki_get_citations`

```
获取单篇论文的引用网络：参考文献、引证文献、共引文献、二级引用
```

### `cnki_search` / `cnki_professional_search`

```
标准搜索 / 专业检索语法搜索
```

### `cnki_get_article` / `cnki_download`

```
获取单篇详情 / 下载 PDF
```

---

## 使用示例

### Full 模式搜索

```
用户: 搜索"流动穆斯林 教派"相关论文，max_results=3

Claude: [调用 cnki_search_with_abstracts(query="流动穆斯林 教派", max_results=3)]
```

返回结果示例（单篇论文）：

```json
{
  "title": "伊斯兰宗教传统的现代调适——以义乌穆斯林宗教实践为例",
  "authors": ["马艳"],
  "source": "北方民族大学学报(哲学社会科学版), 2012",
  "abstract": "伊斯兰教的宗教革新是一个在内部...",
  "keywords": ["流动穆斯林", "伊斯兰教本土化", "文化适应", "宗教革新"],
  "_counts": {
    "references": "6",
    "citations": "1",
    "co-references": "1725",
    "second-references": "216"
  },
  "references": [
    {
      "title": "伊斯兰文化",
      "authors": ["马明良"],
      "source": "甘肃人民出版社",
      "year": "2011",
      "url": "https://kns.cnki.net/kcms2/article/abstract?v=..."
    }
  ],
  "citations": [
    {
      "title": "城市穆斯林流动女工群体研究",
      "authors": ["马晓梅"],
      "source": "宁夏大学",
      "year": "2017",
      "type": "[D]"
    }
  ],
  "similar_articles": [
    {
      "title": "从塞姆石堆到资源博弈——中国东南穆斯林...",
      "source": "世界宗教研究",
      "year": "2026"
    }
  ],
  "keyword_domains": [
    {"keyword": "伊斯兰教", "weight": "19"},
    {"keyword": "流动穆斯林人口", "weight": "15"},
    {"keyword": "穆斯林", "weight": "13"}
  ]
}
```

### 知识图谱链条推演

```
用户: 从马艳的论文出发，沿着引证文献链条往下挖三层

Claude:
  马艳(2012) → 被引 ← 《城市穆斯林流动女工群体研究》(2017)
    → 参考文献 → 《伊斯兰教社会学》(2001, 被引661次)
      → 引证文献 → ...
```

通过论文的 `references` 和 `citations` 字段，可以无限层地沿着引用关系遍历知识图谱。

---

## 技术架构

```
┌─────────────────────────────────────────┐
│              MCP Server                  │
│  server.py  — 工具定义 + handler         │
├─────────────────────────────────────────┤
│           Browser Automation             │
│  browser.py — Playwright (Edge/Chromium) │
│  · 搜索导航 + 验证码处理                  │
│  · 页面滚动触发懒加载                     │
│  · 拦截 citation-api 响应                │
│  · 拦截 recommend/similar 响应            │
│  · 拦截 starter/domains 响应             │
│  · 浏览器单例 + 健康检查 + 自动重连       │
├─────────────────────────────────────────┤
│              Data Parsing                │
│  parser.py — BeautifulSoup + JSON        │
│  · parse_search_results()                │
│  · parse_article_detail()                │
│  · parse_citation_api_response()   ← NEW │
│  · parse_similar_articles()        ← NEW │
│  · parse_domains()                 ← NEW │
├─────────────────────────────────────────┤
│           Query Builder                  │
│  query_builder.py — CNKI 专业检索语法     │
└─────────────────────────────────────────┘
```

### 核心原理：API 拦截

CNKI 论文详情页在滚动到底部后，会自动调用内部 REST API：

```
restapi/citation-api/v1/literature/references    ← 参考文献
restapi/citation-api/v1/literature/citations     ← 引证文献
restapi/citation-api/v1/literature/quotations/metrics ← 引用统计
openapi/usercenter-api/v1/recommend/similar/articles ← 相似论文
restapi/citation-api/v1/literature/starter/domains    ← 关键词权重
```

我们通过 Playwright 的 `page.on("response")` 拦截这些响应，直接解析 JSON，完全避开 CNKI 的 DOM 懒加载、JS 重置、CSS 隐藏等反爬机制。

### 浏览器保活

```python
async def get_browser():
    if _browser is not None:
        if _browser._browser.is_connected():  # 健康检查
            return _browser                   # 复用
        _browser = None                       # 死了，重建
    _browser = await create_browser()         # 首次启动
    return _browser
```

同一 MCP session 内浏览器只启动一次，验证码只做一次。

---

## 探索历程

1. **DOM 方案（失败）**：尝试点击引用 Tab、MutationObserver 监听 DOM 变化、150ms 轮询 `div.list_item`。CNKI 的懒加载 + 数据闪现 1 秒后 JS 重置，DOM 方案全军覆没。

2. **全量抓包对比（转折）**：写脚本 dump 页面加载时的全部 130 条 HTTP 响应，对比"滚动到底部"和"不滚动"的差异。发现不滚动时 citation-api 调用量为 0，滚动后暴增到 17 条。确认引用数据走的是内部 REST API 而非 DOM 渲染。

3. **API 拦截方案（成功）**：不再碰 DOM，直接用 `page.on("response")` 拦截 citation-api、recommend/similar、starter/domains 三组端点的 JSON 响应。一次页面访问 6.5 秒拿完全部七个维度的数据。同时发现页面默认只加载参考文献，引证文献需要点一下 Tab 触发，其他间接引用同理。

4. **链条推演验证**：用搜到的论文 URL 直接跳转，获取其引用网络，再跳转，验证了"论文 A → 引证文献 → 论文 B → 参考文献 → 论文 C"的多层知识图谱遍历完全可行。

---

## License

MIT

## 致谢

- 原版 [cnki-search-mcp](https://github.com/CN-MRZZJ/cnki-search-mcp) 提供了搜索和浏览器自动化的基础框架
- CNKI（中国知网）提供了丰富的中文学术资源
