Skip to main content
Glama
scholar-search

scholar-search

by hui-xu-ai

文溯 · wensu

!!! 注意不要用机构或大学的IP自动化访问这些网站,可能面临来自他们的处罚 !!!

只读的文献题录检索服务,以 MCP 工具或按需 CLI 的形式提供给 AI 客户端。微内核 + 渠道插件:

  • 知网(CNKI) — 中文文献,中文检索式,17 个官方字段

  • Web of Science — 英文文献,TS= / ALL= 检索式,自带期刊影响因子(JCR),可筛选、可排序

万方、维普等以后按同一契约接入。

发行名 wensu(中文名「文溯」)。命令是 wensu,旧的 scholar-search 保留为兼容别名; Python 模块名仍是 scholar_search,运行期目录仍是 %LOCALAPPDATA%\scholar-search,老配置无需改动。

独立项目,非官方,与任何数据库运营方无隶属、合作或授权关系。

开放插件市场

它能做什么

  • 关键词检索:标题、作者、刊名、年份、被引、下载、详情链接

  • 专业检索式:知网官方 17 个字段(SU/TKA/KY/TI/FT/AU/FI/RP/AF/FU/AB/CO/RF/CLC/LY/DOI/CF), 支持 and/*、or/+、not/-、% 与括号

  • 翻页:每次 1 页,页码 1–3;每页 20 或 50 条

  • 排序:相关度 / 发表时间降序 / 被引降序

  • 单篇详情:摘要、关键词、作者单位、卷期页、DOI

  • 导出:RIS / EndNote 纯文本,保留页面给出的文献类型(期刊 / 学位论文 / 会议 / 图书 / 报纸…)

Related MCP server: CNKI Search MCP Server

它不做什么

  • 不下载 PDF / CAJ,不调用任何下载接口,不碰全文

  • 不把题录写入 Zotero / EndNote / Mendeley。只输出 RIS / EndNote 文本, 导入由你自己在软件里完成(原因见 ADR 0006)

  • 不破解验证码,遇到验证页立即停机,等你人工处理

  • 不做批量抓取,没有"爬全库"模式,日上限 300 次由内核强制

  • 不实现来源类型筛选(传了会明确报错);年份筛选只作用于本次已抓取的记录

安全边界

约束

值

动作词汇

固定九个:goto wait_for type click select read_html read_text scroll sleep

任意 JS

没有。扩展只认这九个动作,选择器由计划带下来

域名

白名单,由渠道 manifest 声明,内核与宿主双重校验

最小间隔

3000 ms 硬下限,外加 0–1.2 s 随机抖动,并发 1

单次计划

≤ 40 个动作 / ≤ 200 s

每日配额

300 个网络动作(读类动作不计数)

风控

验证页 / 验证码 / 403 / 登录跳转 → 立即终止,返回 blocked,冷却 24 h,不自动重试

凭证

零。不读也不存任何账号、Cookie、会话材料

工作原理

MCP 客户端 ──stdio / HTTP──▶ MCP server
                               │
                        内核:契约 / 策略 / 风控 / 计划 / 审计 / 缓存
                               │
                        渠道插件 channels/cnki/ 与 channels/webofscience/
                               │
                     桥接适配器 ──TCP(loopback+token)──▶ 原生宿主
                                                          │
                                                    stdio │ 浏览器原生消息
                                                          ▼
                                                       扩展 ──▶ 你的浏览器

你不需要开调试端口,也不需要交出浏览器控制权:扩展只做九个通用动作, 站点知识(选择器、流程、解析)全部在 Python 侧的渠道插件里。

快速开始

前置:Windows、Python 3.11+、Edge(或 Chrome)。浏览器侧目前只在 Windows 上提供。

# 1) 装包(已发布到 PyPI;离线时用 Releases 里的 wheel)
pip install wensu

# 2) 一条命令装好浏览器资源与原生宿主
wensu setup

# 3) 装扩展(只需一次):edge://extensions → 开发者模式
#    → 加载解压缩的扩展 → 选 wensu setup 打印的 extension 目录
#    扩展 ID 由 manifest 里的 key 固定,恒为 gmaimbocfjkolcpljeekjcomakipoaph

# 4) 验证
wensu status

wensu setup 把资源放到 %LOCALAPPDATA%\scholar-search\browser,注册 Edge/Chrome 的原生宿主,并打印 扩展目录;它不写系统目录,也不需要管理员权限。想自己指定位置或只复制资源,用 wensu setup --target <目录> / wensu setup --no-host。

status 里 bridge_ready: true 就通了。

更细的步骤(新建独立 Edge 环境、多浏览器、扩展 ID 对不上等)见 浏览器环境与扩展。让 agent 帮你装,见 skills/scholar-install。

接入 MCP 客户端

stdio 方式(Claude Desktop、Cursor 等用 JSON 配置的客户端;Codex 用 config.toml,见 Codex 接入):

{
  "mcpServers": {
    "wensu": {
      "command": "wensu",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

HTTP 方式(本地回环 + 令牌):

wensu serve --transport http --host 127.0.0.1 --port 8765

令牌在首次启动时写入 %LOCALAPPDATA%\scholar-search\http-token,请求带 Authorization: Bearer <token>,端点 http://127.0.0.1:8765/mcp。 细节见 docs/integration/dsh.md。

工具

工具

参数

返回

search

query(关键词或专业检索式)、channel、page 1–3、limit 1–50、sort、year_from/year_to、fields、count_only

total、page、page_count、records[]、quota_charged

detail

url(search 返回的链接或裸 DOI)、channel、include_abstract、fields

单条完整题录(含摘要、DOI、卷期页)

detail_many

urls[]、include_abstract、fields

results[]、ok_count、failed_count;遇风控整批停止

export

records、format:ris/endnote/markdown/csv、out_path

纯文本;给了 out_path 则写盘且不回传正文

status

brief

渠道、剩余配额、冷却状态、桥接是否就绪

include_abstract 默认 false,fields 可把响应压到只留需要的键(url 与额度字段总是保留)。

检索后的详情不一定免费:WoS 的列表抓取会播种完整详情,detail 命中缓存扣 0;知网的列表 不播种详情,第一次 detail 需要一次网络动作,扣 1。同一篇再取则扣 0。

search 的年份筛选是客户端筛选:只对本次抓到的那一页生效,total 仍是站点总数。 筛选后为空说明目标年份不在这一页,换页或换检索式,不要连续翻页扫库。

并发

一个浏览器 profile 同一时间只应服务一个 agent。

同一 profile 下的检索与详情由同一把跨进程事务锁串行化:一条检索从提交到读取期间持有整把锁, detail 和 journal 也拿同一把,所以它们不会插进检索的中途。后到的请求排队等待,不会读到 别人的页面。

多个 profile 时,每个浏览器有自己的 host。host 无法报告自己属于哪个 profile——它读的是同一份 browser.json——所以当有多个 host 且它们声称同一个 profile 时,工具会拒绝连接并说明原因, 而不是随机挑一个。目前可行的多 profile 用法是:一个 profile 一个 host,用 WENSU_PROFILE 指定本次调用使用哪个;无法消歧时请关掉多余浏览器。

升级到新版本

pip install --upgrade wensu
wensu setup --force
# 重启 MCP 客户端,让它重新拉起 server 进程

要点:

  • 必须重启 MCP 客户端。server 是 stdio 子进程,模块在启动时导入,换文件不会热生效。

  • 扩展通常不用重装:Python 侧改动不影响扩展;只有 extension/ 里的 JS 或 manifest.json 变了才需要重新加载扩展。

  • 原生宿主在升级后要重跑 wensu setup --force(它负责写清单、注册表项和低完整性标签)。

  • --force 只覆盖复制出去的资源,不动已记录的浏览器配置。如果你用 wensu browser adopt 指定过专用 profile,升级后它仍然有效。要连浏览器配置一起重置, 用 wensu setup --force --reset-browser——这会把 browser.json 换成默认的 profiles/edge,原来的窗口和已经装好的扩展不会跟着迁移。

完整流程、目录布局与回滚见 docs/operations.md。

状态

当前版本见 wensu --version(pip install wensu 即可,PyPI 与 GitHub Release 同步)。真机验证过的能力:

能力

状态

知网关键词检索

通过(IPMC 595 条、钙钛矿太阳能电池 11820 条)

知网专业检索式

通过(SU='IPMC' and KY='驱动器')

知网翻页 1–3

通过

知网每页 50 条

通过

知网排序(时间 / 被引)

通过,稳定降序

知网单篇详情

通过(含摘要、作者单位、卷期页)

导出 RIS / EndNote

通过(图书 → TY - BOOK,学位论文 → THES)

WoS 关键词检索

通过(actuator 63025 条,单次取 50 条约 23 秒)

WoS 专业检索式

通过(TS=(ionic AND (soft OR flexible) AND actuator) AND PY=(2026))

WoS 翻页第 2 页

通过(50 条,与第 1 页无重叠)

WoS 影响因子

通过(记录自带 impact_factor,本地筛选/排序零请求)

WoS 摘要按需取

通过(检索时播种缓存,detail 零网络动作)

检索失败了?先看这三条

这个 MCP 报告"检索失败"时,九成不是 MCP 的问题,而是浏览器或网络环境。 按下面的顺序排查, 不要反复重试(重试只会消耗配额,遇到风控还会触发 24 小时冷却)。

1. 代理软件对知网做了 TLS 中间人(国内最常见)

现象:search 返回 sleep failed: content_not_ready 或 type failed: bridge.timeout; 去看浏览器,窗口标题是「隐私错误」,页面上写着 NET::ERR_CERT_COMMON_NAME_INVALID,地址是 kns.cnki.net。

原因:Clash / v2ray / 其他系统代理把 kns.cnki.net 的证书换成了自己的,证书名对不上, 浏览器拒绝加载,页面变成错误页——错误页上没有人注入内容脚本,动作自然全部失败。

容易误判的地方:用 PowerShell 的 Invoke-WebRequest 或 curl 访问同一个地址会返回 200, 因为命令行工具不走系统代理设置。于是很容易得出"网站是好的,是 MCP 坏了"的结论——恰恰相反。

处理:让 cnki.net 直连。任选其一:

# 在代理软件里加规则(推荐,持久)
DOMAIN-SUFFIX,cnki.net → DIRECT
# 或者把它加进 Windows 的代理例外,然后重启浏览器
$key = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings'
$cur = (Get-ItemProperty $key).ProxyOverride
if ($cur -notmatch 'cnki\.net') {
    Set-ItemProperty $key -Name ProxyOverride -Value ($cur.TrimEnd(';') + ';*.cnki.net;cnki.net')
}

验证:在那个浏览器窗口里打开 https://kns.cnki.net/kns8s/search,能看到检索框就对了。

2. 全新浏览器环境被要求人工验证

新 profile 没有 Cookie 与访问历史,第一次检索多半会落到知网的「安全验证」页,工具会正确返回 blocked 并上 24 小时冷却。这不是故障:在那个窗口里人工过验证,然后 wensu reset --confirm,再检索一次。详见 浏览器环境。

3. 窗口不在前台,定时器被节流

浏览器把后台窗口的定时器按整秒分桶,暂停动作会迟到,表现为 bridge.timeout 且 duration_ms 贴着超时值。把知网窗口切到前台、只留一个可见窗口再试。

更多排障(宿主没起来、goto 超时、配额用尽等)见运维手册。

目录

src/scholar_search/core/       内核:契约、注册表、策略、风控、审计、缓存、导出
src/scholar_search/channels/   渠道插件(cnki/2026.10、webofscience/2026.11)
src/scholar_search/adapters/   浏览器适配器(bridge 生产 / fixture 测试)
src/scholar_search/transports/ stdio 与 HTTP
native-host/                   原生消息宿主(纯通讯层,Windows)
extension/                     浏览器扩展(九个动作,零站点知识)
schemas/                       记录与工具 JSON Schema
skills/                        给 agent 的技能说明
docs/                          架构、ADR、协议、运维、接入说明
tests/                         单元 + 契约 + fixture 回放

文档

文档

内容

架构说明

分层、请求流、策略与风控、扩展点

运维手册

目录布局、部署、升级、回滚、排障

知网改版应对

站点变了改哪里、怎么验证

浏览器环境

新建独立 Edge 环境、装扩展、扩展 ID

Zotero 接入

手动导入 RIS 的步骤(不做自动化)

发布到 GitHub

推送、tag、CI 与发布

渠道契约

新增渠道要实现的接口

桥接协议

宿主与扩展的帧格式与校验

ADR 索引

关键决策记录

故障台账

线上踩过的坑与结论

合规声明

本项目仅用于个人学术研究中的题录检索。使用者应遵守目标站点的服务条款与所在机构的 使用规定。项目本身不附带任何数据、凭证或会话材料,也不提供把数据灌入第三方系统的能力。

来源与致谢

本仓库的代码是为本项目独立编写的,没有复制任何外部项目的源码文件、模块或函数。 沿用的只有三样:知网页面的 CSS 选择器字符串(属于 DOM 事实)、交互步骤的先后顺序 (由站点决定)、以及已知坑的知识(例如常驻隐藏的验证码 DOM)。这些做法受到三个公开的 MIT 项目启发:

浏览器通道、微内核结构、策略/风控引擎、解析器与导出层都是本项目自己的设计,与它们不同 (对照见 借鉴对照表)。完整的来源声明、依赖许可与 fixture 脱敏说明见 NOTICE。

tests/fixtures/ 下的页面快照已脱敏:摘要、作者、单位、关键词全部替换为合成占位文本, 邮箱与会话参数已删除,只保留标记结构、类名和公开的题录事实(标题、刊名、卷期页、DOI)。

License

MIT,见 LICENSE。

Available Tools

5 tools
detailA

Fetch full metadata for one record.

url may be either the URL search returned, or a bare DOI such as 10.13841/j.cnki.jxsj.2026.11.001. CNKI detail URLs are several hundred characters of encrypted signature — this one has no parameters but v= — so passing them back verbatim is easy to truncate. A DOI is short, stable and already in every record.

include_abstract defaults to false, matching search: a CNKI abstract runs about 1200 characters and a WoS one about 1000, which is most of what a detail response weighs. A caller that wants the volume, issue, pages and DOI should not pay for text it will not read. fields projects the rest, and always keeps url so the record stays followable.

A DOI costs one extra search to resolve into a URL, because that is the only way to reach the detail page. A URL that is already cached costs nothing.

channel is optional: it is inferred from the URL's host, or from the DOI prefix. Pass it only to override that inference.

Inputs: url (required), fields, channel, include_abstract. Returns: object

detail_manyA

Fetch several records in one call.

Each lookup costs the same as detail and they run in sequence on purpose: the policy layer serialises network actions anyway, so firing them in parallel would only queue them while each held a timeout budget.

include_abstract and fields behave as in detail. A batch of twelve abstracts is roughly 14 KB, so the default is off here too — this is the call that most needs it, since the cost multiplies by the batch size.

A failure on one record does not abandon the rest — the response is {"results": [{"url", "ok", "record"|"error"}], "ok_count", "failed_count"}, so a caller can retry just the ones that failed.

A risk block is the exception: it stops the batch. detail returns a status: "blocked" payload rather than raising, so this loop used to file it under ok: true and carry on — reporting a batch as successful while the site was asking the caller to stop. AGENTS.md requires stopping on a block, and a batch that keeps visiting after one is exactly the behaviour that rule exists to prevent.

Inputs: urls (required), fields, channel, include_abstract. Returns: object

exportB

Render records as RIS or EndNote text.

With out_path, the text is written there and not returned: a caller that wants 143 records on disk should not have to pull them through its context to do it. Without it, the text comes back inline as before.

include_abstract defaults to false here even though the records may carry one. An AB field roughly quadruples an RIS entry, and an export is usually for a reference manager, which fetches abstracts on its own.

Inputs: records (required), format, out_path, include_abstract. Returns: object

statusA

Session state: channels, cooldown, quota, bridge readiness.

brief returns only version, bridge_ready, bridge_last_seen, quota_remaining and cooldown_until. The full payload is about 500 tokens, more than a search, and three of its blocks — channel_capabilities, detail_capabilities, action_cost — are static. Poll brief while planning and read the full answer once.

Inputs: brief. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct operation: session diagnostics (status), discovery (search), single-record retrieval (detail), batch retrieval (detail_many), and formatting (export). The only near-overlap is detail vs detail_many, but the one-vs-many distinction is explicit and unlikely to cause misselection.

    Naming Consistency3/5

    The set mixes noun-only names (status, detail), verb names (search, export), and noun_snake (detail_many). It remains readable, but it does not follow a single predictable verb_noun or other consistent pattern.

    Tool Count5/5

    Five tools is tightly scoped for a scholarly search server: one for status, one for discovery, two for record retrieval, and one for export. Each earns its place without redundancy.

    Completeness4/5

    The surface covers discovery, full-record retrieval (single and batch), export, and session diagnostics, which is the core lifecycle for bibliographic search. Minor gaps like no dedicated channel-listing tool or related-work traversal are workable through existing tools or outside the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to search and retrieve academic papers from China National Knowledge Infrastructure (CNKI), supporting various search types including subject, keyword, author, and DOI lookups.
      3
      21
      -
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server for searching Chinese academic papers and core journal information across multiple free platforms like Baidu Scholar and the National Center for Philosophy and Social Sciences. It enables users to retrieve metadata for social science and STEM research papers without requiring API keys.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to search and retrieve paper information from CNKI (China National Knowledge Infrastructure), supporting 15 search types, pagination, sorting, and detailed metadata extraction.
      3
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI to search, filter, and process CNKI academic literature through natural language, including structured search, metadata retrieval, full-text reading, citation export, and PDF/CAJ download.
      9
      12
      GPL 3.0