文溯 · wensu

只读的中文文献题录检索服务，以 MCP 工具的形式提供给 AI 客户端。微内核 + 渠道插件： 知网是第一个渠道，万方、维普等以后按同一契约接入。

发行名 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 纯文本，保留页面给出的文献类型（期刊 / 学位论文 / 会议 / 图书 / 报纸…）

它不做什么

• 不下载 PDF / CAJ，不调用任何下载接口，不碰全文
• 不把题录写入 Zotero / EndNote / Mendeley。只输出 RIS / EndNote 文本， 导入由你自己在软件里完成（原因见 ADR 0006）
• 不破解验证码，遇到验证页立即停机，等你人工处理
• 不做批量抓取，没有"爬全库"模式，日上限 300 次由内核强制
• 不实现来源类型筛选（传了会明确报错）；年份筛选只作用于本次已抓取的记录

安全边界

工作原理

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

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

快速开始

前置：Windows、Python 3.11+、Edge（或 Chrome）。浏览器侧目前只在 Windows 上提供。

# 1) 装包（已发布到 PyPI；离线时用 Releases 里的 wheel，把 <版本> 换成实际版本号）
pip install wensu
# 或
pip install .\wensu-<版本>-py3-none-any.whl

# 2) 导出浏览器侧资源并注册原生宿主
wensu assets --target .\browser
pwsh .\browser\native-host\install.ps1

# 3) 装扩展：edge://extensions → 开发者模式 → 加载解压缩的扩展 → 选 .\browser\extension
#    扩展 ID 由 manifest 里的 key 固定，恒为 gmaimbocfjkolcpljeekjcomakipoaph

# 4) 验证
wensu status

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 的年份筛选是客户端筛选：只对本次抓到的那一页生效，total 仍是站点总数。 筛选后为空说明目标年份不在这一页，换页或换检索式，不要连续翻页扫库。

升级到新版本

pip install --upgrade .\dist\wensu-<新版>-py3-none-any.whl
wensu assets --target .\browser --force
pwsh .\browser\native-host\install.ps1 -Python <venv>\Scripts\python.exe
# 重启 MCP 客户端，让它重新拉起 server 进程

要点：

• 必须重启 MCP 客户端。server 是 stdio 子进程，模块在启动时导入，换文件不会热生效。
• 扩展通常不用重装：Python 侧改动不影响扩展；只有 extension/ 里的 JS 或 manifest.json 变了才需要重新加载扩展。
• 原生宿主在升级后要重跑 install.ps1（它负责写清单、注册表项和低完整性标签）。

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

状态

当前版本 v0.4.0（最新 release 见仓库 Releases 页）。真机验证过的能力（2026-10-21，知网 2026.10 版页面）：

检索失败了？先看这三条

这个 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）
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 回放

文档

合规声明

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

来源与致谢

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

• cookjohn/cnki-skills
• SepineTam/cnki-mcp
• wuruiqi/cnki-mcp

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

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

License

MIT，见 LICENSE。