# CUC Literature MCP：中传 SCI 论文检索与腾讯论文表维护

[![CI](https://github.com/SHENAO1/cuc-literature-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SHENAO1/cuc-literature-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js >= 20](https://img.shields.io/badge/Node.js-%3E%3D20-43853d)](https://nodejs.org/)

一个运行在用户电脑上的 TypeScript STDIO MCP，配套可被 Codex 自动发现的 Skill。它使用独立、持久化的 Chrome 或 Edge 配置访问 Web of Science、IEEE/开放全文和腾讯文档，不调用 OpenAI API，也不会读取或返回账号密码和 Cookie。

> 当前版本：`0.2.0`。除原有检索流程外，新增存量工作表审计、DOI核验、正式版PDF升级、10 MiB压缩、变更预览与指纹保护写回。WOS、出版社和腾讯文档均为网页自动化适配器；页面不确定时会停止并返回可恢复错误，不会绕过验证码、登录或付费限制。

## 目录

- [能做什么](#能做什么)
- [工作边界](#工作边界)
- [让 Codex 指导安装](#让-codex-指导安装)
- [Windows 快速安装](#windows-快速安装)
- [macOS 快速安装](#macos-快速安装)
- [首次登录](#首次登录)
- [开始使用](#开始使用)
- [配置与输出](#配置与输出)
- [MCP 工具](#mcp-工具)
- [升级与卸载](#升级与卸载)
- [常见问题](#常见问题)
- [开发和测试](#开发和测试)

## 能做什么

- 在 WOS Core Collection 构造并执行高级检索；
- 默认检索中国传媒大学2024年至当前年份的 SCI-EXPANDED 论文；
- 围绕无线通信、通信导航融合、通信感知一体化扩展 RIS、语义通信、近场定位、卫星通信、SAGIN、毫米波、太赫兹、MIMO、NOMA、车联网、无人机通信、信道编码和6G等紧邻主题；
- 按 DOI → WOS号 → 标准化题名去重；
- 从腾讯正式工作表只读提取“期刊—2025中科院大类分区”映射；
- 按 IEEE 机构正式PDF → 出版商开放PDF → 预印本/作者公开稿的顺序尝试下载；
- 只保存 HTTPS、具有 `%PDF` 文件头、大小合理并通过 SHA-256 校验的文件；
- 增量同步到腾讯文档的非正式工作表，保护人工备注和已有附件；
- 按年份倒序，同年份按 `1区 Top → 1区 → 2区 Top → 2区 → 3区 → 4区 → 待核验` 整行排序；
- 把运行进度保存在本地，可在登录或验证码处理后用原 `run_id` 继续；
- 按腾讯表头动态定位现有论文、DOI和附件，兼容旧A—J与扩展A—L表；
- 通过Crossref及DOI解析器核验/补全DOI，仅接受题名、期刊、年份完全一致的记录；
- 从PDF正文核对题名、作者、期刊、DOI、出版社、中传单位和页数；
- 超过10 MiB时用Ghostscript生成保留原件的压缩副本，并在上传前重新核验；
- 维护写回先生成带工作表指纹的变更集，附件替换需要显式授权。

## 工作边界

本项目不会：

- 提供或共享中国传媒大学、WOS、IEEE、腾讯文档账号；
- 传输账号密码、Cookie 或浏览器配置；
- 绕过统一身份认证、验证码、机构权限或付费墙；
- 把未知中科院分区猜成“未收录”；
- 自动修改正式来源工作表“工作表1”；
- 授予论文 PDF 的再分发权。

每位使用者都必须拥有相应数据库和腾讯文档的合法访问权限。公开仓库不包含任何个人腾讯文档链接、浏览器登录态或已下载PDF。

## 让 Codex 指导安装

OpenAI 官方说明，Codex 会从仓库路径上的 `.agents/skills` 发现项目 Skill，本地 STDIO MCP 可以通过 `codex mcp add` 注册；ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享该配置：

- [OpenAI：Build skills](https://learn.chatgpt.com/docs/build-skills)
- [OpenAI：Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)
- [OpenAI：Windows desktop app](https://learn.chatgpt.com/docs/windows/windows-app)

把仓库交给 Codex 后，可以直接发送：

```text
请先完整阅读仓库根目录的 AGENTS.md 和 README.md。
检查我的操作系统、Node.js、Codex 和浏览器环境，指导并执行本项目安装。
不要读取或复制 .runtime/chrome-profile，不要询问我的密码、Cookie或验证码。
安装前向我索取一个有编辑权限的腾讯表格URL；目标工作表使用“MCP测试”。
安装后执行 doctor，打开专用浏览器让我自行完成WOS、IEEE和腾讯文档登录，并告诉我如何开始第一次检索。
```

Codex 应按照 [AGENTS.md](AGENTS.md) 执行。登录、验证码和腾讯文档授权必须由用户在可见浏览器中亲自完成。

## Windows 快速安装

### 1. 前置条件

- Windows 11，推荐；
- ChatGPT Windows 桌面应用或 Codex CLI；
- Node.js 20 或以上；
- Google Chrome，或 Microsoft Edge；
- Git，可选，也可以下载 ZIP。

可以在 PowerShell 检查：

```powershell
node --version
npm --version
codex --version
```

如果没有 Node.js：

```powershell
winget install OpenJS.NodeJS.LTS
```

如果没有 Git：

```powershell
winget install Git.Git
```

安装后重新打开 PowerShell。

### 2. 获取仓库

```powershell
git clone https://github.com/SHENAO1/cuc-literature-mcp.git
cd cuc-literature-mcp
```

也可以从 GitHub 的 **Code → Download ZIP** 下载并解压，然后在该目录打开 PowerShell。

### 3. 执行安装

把下面的示例链接替换成你有编辑权限的腾讯表格链接：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
./scripts/install.ps1 `
  -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID" `
  -BrowserChannel chrome
```

使用 Edge：

```powershell
./scripts/install.ps1 `
  -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID" `
  -BrowserChannel msedge
```

安装脚本会：

1. 用 `npm ci` 安装锁定版本依赖；
2. 编译并运行完整测试；
3. 把本机配置写到 `.runtime/settings.json`；
4. 使用 `codex mcp add` 注册 `cuc-literature`；
5. 执行安装诊断。

如果希望在其他项目目录也能用 `$cuc-literature-search`，增加：

```powershell
-InstallGlobalSkill
```

完整 Windows 说明见 [docs/WINDOWS.md](docs/WINDOWS.md)。

## macOS 快速安装

```bash
git clone https://github.com/SHENAO1/cuc-literature-mcp.git
cd cuc-literature-mcp
chmod +x scripts/install.sh scripts/uninstall.sh
./scripts/install.sh \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --browser-channel chrome
```

可选的全局 Skill：

```bash
./scripts/install.sh \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --install-global-skill
```

完整说明见 [docs/MACOS.md](docs/MACOS.md)。Linux/WSL 可以构建和运行协议测试，但本项目依赖可见桌面浏览器，主要支持 Windows 原生和 macOS。

## 首次登录

安装后运行：

```bash
npm run login
```

工具会启动独立浏览器配置目录：

```text
.runtime/chrome-profile
```

请在这个专用窗口中分别完成：

1. 中国传媒大学统一身份认证；
2. WOS 机构访问；
3. IEEE Xplore 机构访问；
4. 腾讯文档登录，并确认对目标文档有编辑和附件上传权限；
5. 如果出现验证码，由用户自行完成。

完成后回到终端按回车，程序会重新检查会话。不要把日常 Chrome 的用户目录复制到 `.runtime`，也不要把 `.runtime` 分享给别人。

诊断当前会话：

```bash
npm run diagnose
```

安装诊断：

```bash
npm run doctor
```

完成安装或修改 MCP 配置后，重启 ChatGPT/Codex。

## 开始使用

在本仓库打开新的 Codex 会话，输入：

```text
使用 $cuc-literature-search 检索中国传媒大学2024年以来无线通信、通信导航融合和通信感知一体化相关SCI论文，写入默认腾讯文档并下载PDF。
```

如果安装了全局 Skill，也可以在其他项目中这样调用。

维护现有腾讯工作表时，推荐先生成预览，不立即写入：

```text
使用 $cuc-literature-search 维护以下腾讯文档的“补充论文”工作表：
https://docs.qq.com/sheet/你的文档ID

审计所有论文的题目、作者、期刊、年份、DOI和PDF附件；
核验并补全高置信度DOI，检查附件是否为正式出版版；
下载可以合法获取的正式版PDF，超过10 MiB时压缩并重新核验。
先执行preview_updates并展示变更，不要立即写入腾讯文档。
```

核对预览后，再发送：

```text
继续原 run_id，应用刚才的 change_set_id。
允许上传新增附件，并允许用核验通过的正式出版PDF替换预印本附件。
应用后重新审计，确认没有错行、重复附件或未保存内容。
```

`download_fulltext` 支持三种范围：

- `missing_only`：只处理缺失PDF；
- `upgrade_to_formal`：把预印本或作者稿升级为正式出版版；
- `all`：逐篇重新获取并核验正式版，适合全面复核。

正常编排顺序：

```text
check_browser_session
  → refresh_partition_map
  → create_search_run
  → search_wos
  → download_fulltext
  → sync_results
  → get_run_status
```

维护现有工作表：

```text
create_maintenance_run
  → audit_sheet
  → resolve_dois
  → download_fulltext
  → preview_updates
  → apply_updates
  → audit_sheet
```

出现 `login_required`、`captcha_required` 或 `needs_user_action` 时，不要新建运行。完成页面操作后让 Codex使用原 `run_id` 重试。详细示例见 [docs/USAGE.md](docs/USAGE.md)。

## 配置与输出

### 本机设置

安装器把非敏感设置写入：

```text
.runtime/settings.json
```

该文件不会提交到 Git。重新配置：

```bash
npm run configure -- \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --browser-channel chrome \
  --source-sheet "工作表1" \
  --target-sheet "MCP测试" \
  --pdf-directory "output/pdfs"
```

PowerShell 可以把反斜杠续行改为一行，或使用反引号 `` ` ``。

环境变量优先于 `.runtime/settings.json`：

| 变量 | 用途 | 默认值 |
|---|---|---|
| `CUC_LITERATURE_HOME` | 项目绝对路径 | 当前工作目录 |
| `CUC_TENCENT_DOC_URL` | 腾讯表格链接 | 必填，无公开默认值 |
| `CUC_SOURCE_SHEET` | 分区映射来源表 | `工作表1` |
| `CUC_TARGET_SHEET` | MCP写入目标表 | `MCP测试` |
| `CUC_PDF_DIR` | PDF目录 | `output/pdfs` |
| `CUC_BROWSER_CHANNEL` | `chrome`或`msedge` | `chrome` |
| `CUC_WOS_URL` | WOS入口覆盖 | 中传机构入口 |
| `CUC_IEEE_URL` | IEEE入口覆盖 | 中传图书馆IEEE入口 |
| `CUC_HEADLESS` | 测试用无头模式，设为`1`启用 | 不启用 |

### 腾讯文档表头

新建检索表默认使用 A—J：

```text
论文题目、作者、年份、期刊、SCI索引、WOS号、DOI、
中科院SCI分区（2025大类）、PDF附件、学校数据库下载核验/未下载原因
```

- MCP 生成的备注以 `[MCP]` 开头；
- 已有非 `[MCP]` 人工备注不覆盖；
- 已有 PDF 附件不重复上传；
- 已有表通过表头名称定位，不假设PDF或DOI列号；
- 检索排序使用表头后的首个空列作为临时列，完成后清空；维护模式原位更新、不排序；
- 目标工作表与来源工作表同名时程序拒绝运行。

### 本地文件

```text
output/pdfs/<年份>/                 通过校验的PDF
.runtime/runs/<run-id>.json         可恢复进度
.runtime/chrome-profile/            独立浏览器登录态
.runtime/partition-map.csv          本地分区映射
config/partition-overrides.csv      可提交的人工分区覆盖
```

分区覆盖 CSV 格式：

```csv
journal,normalized_journal,partition,top,source
IEEE Access,ieee access,2区,false,override
```

## MCP 工具

| 工具 | 主要输入 | 作用 |
|---|---|---|
| `check_browser_session` | `open_login_window` | 检查 WOS、IEEE、腾讯文档会话 |
| `refresh_partition_map` | 文档URL、来源工作表 | 只读提取期刊分区并生成本地映射 |
| `create_search_run` | 主题、年份、单位、输出位置 | 创建 `run_id` 和 WOS 查询式 |
| `search_wos` | `run_id` | 检索、完整记录导出、筛选和去重 |
| `create_maintenance_run` | 文档URL、工作表、PDF目录 | 创建存量维护 `run_id` |
| `audit_sheet` | `run_id` | 动态读取表头、逐行问题和工作表指纹 |
| `resolve_dois` | `run_id` | 核验已有DOI并补全高置信度缺失项 |
| `download_fulltext` | `run_id`、模式、论文键 | 下载、升级并正文验证有权获取的PDF |
| `preview_updates` | `run_id` | 生成不修改云端的变更集 |
| `apply_updates` | `run_id`、变更集、替换授权 | 指纹一致时原位应用并复核 |
| `sync_results` | `run_id` | 增量写表、上传附件、整行排序 |
| `get_run_status` | `run_id` | 查看阶段、错误、输出和待操作项 |

所有工具返回简短文本和结构化 JSON。命中超过500篇时会停止，避免不受控批量操作。

## 升级与卸载

### 升级

```powershell
git pull
./scripts/install.ps1 -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID"
```

macOS：

```bash
git pull
./scripts/install.sh --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID"
```

安装器只替换同名 `cuc-literature` MCP，不修改其他 MCP 配置。

### Windows 卸载

只移除 MCP 注册，保留登录态、运行记录和PDF：

```powershell
./scripts/uninstall.ps1
```

同时移除本地运行态和全局 Skill：

```powershell
./scripts/uninstall.ps1 -RemoveRuntime -RemoveGlobalSkill
```

只有明确希望删除下载的论文时才增加：

```powershell
-RemoveDownloadedPdfs
```

macOS 对应参数见 `./scripts/uninstall.sh --help`或 [docs/MACOS.md](docs/MACOS.md)。

## 常见问题

### `codex` 命令不存在

先确认 ChatGPT/Codex 已安装并重启终端。也可以在 ChatGPT 桌面应用中打开 **Settings → MCP servers → Add server**，选择 STDIO，手动填写 Node 路径和 `dist/server.js`。详细步骤见 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。

### PowerShell 禁止运行脚本

只对当前窗口临时放行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
```

### 找不到 Chrome

安装 Chrome，或者重新执行安装并指定：

```powershell
-BrowserChannel msedge
```

### WOS 或 IEEE 一直要求登录

确认使用的是工具启动的专用浏览器窗口，且当前网络/账号具有中国传媒大学数据库权限。校外访问可能还需要学校允许的 VPN 或统一身份认证。

### 腾讯文档能打开但不能写入

确认文档不是只读共享，并拥有编辑、创建工作表和上传附件权限。第一版依赖腾讯表格网页UI；页面改版可能触发 `TENCENT_UI_CHANGED` 等错误。

### 为什么有论文没有PDF

常见原因包括机构无权限、无PDF入口、登录失效、验证码、HTML伪PDF、附件超过限制或只有不接受的版本。元数据仍可写入，J列会记录标准化原因。

更多错误码和恢复方式见 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。

## 开发和测试

```bash
npm ci
npm run check
npm test
npm run validate:skill
```

测试覆盖：

- WOS查询、筛选、导出解析和500篇安全边界；
- DOI/WOS/题名标准化及去重；
- 中科院分区解析和排序；
- PDF文件头、大小和SHA-256校验；
- 人工备注保护；
- WOS、IEEE、腾讯文档合成页面状态；
- MCP工具枚举、Schema、错误结构和编译后STDIO握手。

GitHub Actions 在 Windows、macOS 和 Ubuntu 上执行构建与测试。真实机构登录后的端到端测试不会在公共 CI 中运行。

贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，安全问题请阅读 [SECURITY.md](SECURITY.md)。架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 许可证

[MIT](LICENSE)。数据库、出版商页面、腾讯文档及下载论文分别受其自身条款和版权约束；MIT 许可证只覆盖本仓库代码和文档。