dysprosium231/litloop-paper-agent

Academic Paper Agent · 让 Agent 帮你找论文、筛论文、下论文、存进 Zotero
它能做什么 · 安装 · 依赖与 Key · 怎么用 · 检索与筛选 · 下载与机构通道 · Zotero · 项目状态
> **项目还在开发中。** 检索、筛选、下载、存进 Zotero 这条流程已经能用，并在真实课题上验收过；深度检索已在两个测试集上验收；系统综述、分析归纳还没做，可视化界面在规划中。详见项目状态。
>
> LitLoop 是 Rimagination/scansci-pdf（Apache-2.0）的独立衍生项目，由 dysprosium231 维护，与原作者无隶属关系。下载和机构通道的大部分能力来自原项目，LitLoop 的改动见 NOTICE。
它能做什么
LitLoop 是一个 MCP 服务器加命令行工具，装进 Claude Code、Codex 等 Agent 后，用一句话就能走完一条文献流程：
- **检索：结果少而准。** 同时查 OpenAlex、Semantic Scholar、Crossref，合并去重，去掉离题结果。可以按真实被引数排序，年份过滤在数据源一侧完成。每条结果带清洗过的完整摘要，并标出撤稿和关注声明。
- **筛选：AI 给理由，你来拍板。** Agent 读摘要，把每篇评为 高 / 中 / 低 / 不相关，并写一句理由。你选定要哪些，选择记录存在本地，可以直接生成下载队列。
- **下载：自动选最快的路。** 开放获取直链、预印本、出版商 API、你学校的机构通道同时竞速，先成功的那条胜出。论文按 作者年份_标题前几个词_DOI.pdf 命名，文件名和论文一一对应。支持 100 多所高校的 WebVPN、CARSI 联邦认证、EZProxy，以及 Elsevier API 快速通道。
- **归档：直接进 Zotero。** 按 DOI 建条目，库里已有就复用，PDF 直接写进你本机的 Zotero，同步交给 Zotero 自己。
登录都在你自己的浏览器里完成，密码不经过 LitLoop。
安装
对 Claude Code、Codex 或 ZCode 里的 Agent 说：
安装和更新都是这一句。Agent 会克隆或更新仓库、建独立环境、注册 MCP、装好技能，最后跑一次自检。装完重启客户端即可使用。
给 Agent 的步骤 （也可以自己照着做）
1. 插件目录用 ~/plugins/litloop-paper-agent：已存在就直接用，否则执行 git clone https://github.com/dysprosium231/litloop-paper-agent.git ~/plugins/litloop-paper-agent。
2. 用 Python 3.11+ 运行 scripts/deploy.py：
Windows 上路径是 %USERPROFILE%\plugins\litloop-paper-agent\scripts\deploy.py。脚本只用标准库，会做这几件事：
- 同步代码；
- 在 ~/.litloop/venv 建环境并安装；
- 向本机的 Claude Code、Claude Desktop（已有配置文件时）和 Codex 注册 MCP；
- 复制技能并自检。
已注册且可用的安装会原地更新，不会重建。
3. 把脚本最后输出的摘要（警告和下一步）转告用户，并提醒重启客户端。如果脚本因为“本地有未推送的改动”而退出，不要强行覆盖，先问用户。
4. 常用选项：
- --extras fast,vpnsci,patchright,zotero：加装可选依赖，zotero 会把 zotero-mcp 装进同一环境；
- --with-find：加装 scansci-find；
- --dry-run：只看不改；
- --clients none：只装不注册。
没有 Python 3.11+ 或 Git 时，先请用户安装（Windows：winget install Python.Python.3.12 Git.Git）。
手动配置 MCP （Claude Desktop、Cursor、Cline、Cherry Studio 等）
先在虚拟环境里执行 pip install -e ~/plugins/litloop-paper-agent，然后在客户端里配置：
各客户端的插件入口：
- **Codex**：.codex-plugin/plugin.json、.mcp.json 和 skills/；
- **ZCode**：zcode-plugin/，包含技能和 /litloop 快捷命令；
- **Claude Code**：.claude/skills/ 加上面的 MCP 配置。
其他运行方式 （HTTP 远程 / Web UI / Docker）
依赖与 Key
装好就能用；下面几样配上以后效果明显更好。Key 都可以用 litloop_config 写进配置，也可以设成环境变量（配置文件优先，来自环境变量的 Key 不会被写进文件）。
| 组件 | 必需吗 | 用来做什么 | 没有时 | 怎么获取 |
|---|---|---|---|---|
| Python 3.11+、Git | 必需 | 运行和更新 LitLoop | 装不上 | Windows：winget install Python.Python.3.12 Git.Git |
| OpenAlex API Key | **强烈推荐** | 快速检索和深度检索的主要数据源（目前唯一） | 走公共接口，请求多时容易被限流，深度检索会变慢或中断 | 在 openalex.org 注册后免费获取；openalex_api_key 或环境变量 OPENALEX_API_KEY |
| Elsevier API Key | **强烈推荐** | ScienceDirect 全文下载（需校园网出口）；从 Scopus 补摘要 | Elsevier 期刊多的领域大量文章缺摘要，深度检索只能凭标题排序。PDC 测试集上，26 篇目标里 16 篇的摘要靠它补；去掉后，下一批能读到的目标明显变少 | dev.elsevier.com 免费申请；litloop_elsevier_setup，或 elsevier_api_key / 环境变量 ELSEVIER_API_KEY |
| scansci-find（发现引擎） | 推荐 | 快速检索和深度检索的关键词路线 | 自动退回内置的三源检索，较慢 | 安装时加 --with-find |
| Zotero 桌面版 + zotero-mcp | 可选 | 把文献和 PDF 直接写进本机 Zotero | 只能下载到本地文件夹 | 见下文 Zotero |
| 本机 Chrome | 可选 | 需要浏览器的出版商和机构通道 | 这些通道不可用，开放获取和 API 照常 | 正常安装 Chrome 即可，LitLoop 会自动复制一份私有副本 |
| 学校账号（WebVPN / CARSI / EZProxy） | 可选 | 下载学校订阅的论文 | 只能下开放获取和 API 能拿到的 | 见下文 下载与机构通道 |
| Semantic Scholar API Key | 可选 | 多一个检索来源；补摘要更快 | 不影响使用：补摘要时几个来源同时问，它慢也不会拖住别的来源 | semanticscholar.org/product/api，审批较严，不一定能通过；环境变量 SEMANTIC_SCHOLAR_API_KEY |
| litloop-journal-rank | 可选（未公开） | 期刊分区、预警名单、本地撤稿库 | 没有分区信息，撤稿标记改用 OpenAlex 的数据 | 暂未公开 |
怎么用
装好后直接对 Agent 说：
也可以直接用命令行：
MCP 工具全表 （20 个，按用途分组）
| 想做什么 | 工具 |
|---|---|
| 下载单篇（可拉附件、转 Markdown） | litloop_download |
| 批量下载（列表 / xlsx·csv·bib·APA 文件） | litloop_batch_download |
| 检索、作者检索、深度检索（关键词 + 共同引用扩展，分批筛选） | litloop_search · litloop_find · litloop_deep_search |
| 筛选记录（相关度 + 理由，记录选择，生成下载队列） | litloop_screening |
| 准备队列（校验 / OA 定位 / 构建） | litloop_prepare_queue |
| 机构登录与状态（WebVPN / CARSI / EZProxy / 出版商 SSO） | litloop_login · litloop_channel_status · litloop_schools |
| 引文 / 元数据 / Zotero | litloop_citation · litloop_zotero_push |