Gleaner

多源学术文献采集（Skill + CLI）。把「检索 → 下载全文 → 归一化元数据」交给 Agent / 本机命令一键完成。入口是 gleaner_cli.py 与 ~/.grok/skills/gleaner/。

Authors: liuqiaodongdong and Grok 仓库：https://github.com/liuqiaodongdong/gleaner

输出目录：corpus/<批次>/metadata.csv；全文采集另有 papers/。

快速开始

1. 安装

git clone https://github.com/liuqiaodongdong/gleaner.git
cd gleaner

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate

pip install -r requirements.txt
# 把 Skill 注册到 ~/.grok、~/.cursor、~/.codex（写入 .gleaner_root）
python gleaner_cli.py install-skill
# 若不用系统 Edge 跑知网，再执行：
# playwright install chromium

需要 Python 3.11+。知网线建议 Windows + 系统 Edge。

Agent 装机：用户说「安装项目」或「安装 skill」都是同一条——第一条命令必须是 git clone，再 pip 和 install-skill。只把 SKILL.md 拷到 ~/.cursor/skills 不算安装。没有仓库时可跑 skill/gleaner/scripts/bootstrap.py（会自己 clone）。约定见 skill/gleaner/SKILL.md。

2. 准备账号（按需）

首次使用请先跑：

python gleaner_cli.py status

它会检查缺什么并给出配置步骤。

Elsevier 官方 API Key（els 必需）

本项目只使用 Elsevier Developer Portal 官方 API，不要使用第三方 Key、破解或网页爬取代替。

1. 用学校/机构邮箱注册/登录：https://account.elsevier.com/

2. 打开 https://dev.elsevier.com/ → Create / Manage API Key

3. Create API Key（Label 如 gleaner-local；Website 本地可用 http://localhost）

4. 将 Key 写入 .env 的 ELSEVIER_API_KEY，或单行写入 acq/data/.elsevier_key

5. 再跑 python gleaner_cli.py status 确认 elsevier.ready

说明：Key 负责 API 鉴权与配额；订阅全文仍依赖你的机构权益。配额见 api_key_settings。逐步图与 Agent 话术见 docs/ELSEVIER_API.md。

3. 配置环境（.env / Skill）

复制 .env.example 为 .env，填写：

ELSEVIER_API_KEY=your_key
CJY_USER=chaojiying_user
CJY_PASS=chaojiying_pass
CJY_SOFTID=your_softid
# 可选：需要代理时才取消注释，并将 PORT 换成真实端口
# ACQ_PROXY=http://127.0.0.1:PORT

• 默认直连，ACQ_PROXY 完全可选。不会自动读取系统代理；校园网或 VPN 的系统路由仍正常生效。仅在确需代理时填写实际地址和数字端口

• 若电脑已在校园网 / 机构 VPN 内、浏览器能直接下知网，通常不必再设 ACQ_PROXY

• 推荐设置 GLEANER_ROOT 指向本仓库根

• 用户 Skill：在仓库根跑 python gleaner_cli.py install-skill（不要手拷目录）

4. 知网登录（首次必做）

机构会话写在 cookies.json（已 gitignore）。没有这份文件就不要跑 cnki / cnki-list，冷启动下不了全文，只会空烧超级鹰。

首次安装先填写实际的 CJY_USER、CJY_PASS、CJY_SOFTID，再查询超级鹰账号与积分。占位值不算有效配置。Windows 默认使用已安装的 Edge。

python gleaner_cli.py score
python login.py --first-run
python gleaner_cli.py status

首次建立会话使用 --first-run；后续刷新运行 python login.py，保留已有会话。Agent 应执行项目内登录脚本，超级鹰调用和拖动由脚本完成。账号错误、余额不足或网络错误先按日志修正；自动验证最多两次，失败返回非零退出码并保留原会话，不以“脚本退出”代替登录成功。

默认不等待人工拖动。用户明确选择人工处理时，可临时设置 $env:ACQ_MANUAL_CAPTCHA='1'；失败后的人工等待最多 90 秒。通过检索页/验证成功信号后才保存 Cookie。

调用示例

python gleaner_cli.py status

# 1) Agent 拓展概念组后建式（不启浏览器）
python gleaner_cli.py prepare \
  --topic "数字经济" \
  --concept-groups '[{"name":"数字经济","keywords":["数字经济","数字化","数据要素"]}]' \
  --year-from 2015

# 2) 先题录看 TOTAL，再全文
python gleaner_cli.py cnki-list --level L1 --search-md "<prepare 返回的 search_md>" --num 100
# 全文串行多批直到采够：--until 目标篇数（每批 40–60 随机，批间自动 login.py）
python gleaner_cli.py cnki --level L1 --search-md "<search_md>" --out-name demo_topic_L1 --until 200

# 兼容：无分级
python gleaner_cli.py cnki --query "数字经济" --num 10 --out-name demo_cnki

python gleaner_cli.py els \
  --query '("digital economy" OR digitalization) AND innovation' \
  --num 10 --tier 1+2 --year-from 2020

只采集完整题录，不下载 PDF

python gleaner_cli.py status
python gleaner_cli.py cnki-list --details --query "数字经济" --num 50 --out-name demo_cnki_metadata

--details 会逐篇打开详情页补充摘要、关键词、机构、基金，不调用全文下载器，也不创建 papers/。支持 --pro --query ... 或 --level L1 --search-md ...。

corpus/<批次>/metadata.csv 按以下顺序输出且仅输出 11 列：

title,authors,abstract,keywords,journal,pub_date,institution,fund,cite_count,download_count,url

CSV 使用 UTF-8 BOM，方便 Excel 读取中文。页面未提供的字段留空；详情页加载失败会报错并保留此前逐篇保存的结果。按题名去重，同一批次重跑会重新采集并更新同名记录。

--num 是本次题录目标数，默认 100，不使用全文的 --until。不指定 --out-name 时，完整题录批次名自动加 _metadata；指定时请使用题录专用目录。已有 CSV 含本模式以外的列（例如 file_path）会拒绝写入，避免丢失原数据。普通 7 列题录可升级为 11 列。

省略 --details 仍只采列表页的 7 列。仅题录请求完成后即结束，不继续下载全文或转换。

也可用 Skill 包装（先安装，见下方）：

pwsh "$env:USERPROFILE\.grok\skills\gleaner\scripts\gleaner.ps1" status

安装用户 Skill

必须先有本仓库。 用户只说「安装 skill」时，Agent 仍要先 clone，禁止只拷 SKILL.md。

# 还没有仓库：
git clone https://github.com/liuqiaodongdong/gleaner.git
cd gleaner
python -m pip install -r requirements.txt
# 或：python skill\gleaner\scripts\bootstrap.py

# 仓库已在，注册到 ~/.grok、~/.cursor、~/.codex：
python gleaner_cli.py install-skill
$env:GLEANER_ROOT = (Resolve-Path .).Path

install-skill 会在每份 Skill 副本里写入 .gleaner_root 指向本仓库。当前会话仍建议设 GLEANER_ROOT。也可用 GLEANER_PYTHON 指定解释器。

普通版仅提供 CNKI、Elsevier。国际采集命令及专用模块已移除；既有文献目录保留。校外机构登录版本名为 gleanera，位于 feature/cnki-institution-session 分支，使用独立技能目录。

Related MCP server: Paper Search MCP

工作原理（简）

Agent / 终端
  └── gleaner_cli.py
        ├── CNKI  → Playwright + 默认直连/可选代理 + 超级鹰
        └── Elsevier → REST API + API Key
              └── corpus/<批次>/

• 知网：无头浏览器（默认 Edge），验证码走超级鹰 9602

• Elsevier：Search API + Article Retrieval + Object Retrieval，同时保存完整 PDF 和全文 XML

• Elsevier 的 HTTP 请求默认绕过系统代理（trust_env=False），避免部分代理导致的 SSL 错误；知网默认直连，只有显式配置 ACQ_PROXY 才使用代理。VPN 的系统路由仍正常生效

• 长任务由 CLI 子进程执行，默认不设硬超时；日志见 corpus/*_run.log

底层脚本（调试用）

python run_batch.py params.json
python run_els_batch.py els_params.json

参数字段见各脚本文件头注释。统一入口仍推荐 gleaner_cli.py。

项目结构

gleaner_cli.py       # 统一 CLI
skill/gleaner/       # 用户 Skill 源（install-skill 注册；scripts/bootstrap.py 无仓库时会 clone）
acq/                 # 采集核心与各源 adapter
  cli_support.py     # ROOT / env / 子进程 / 摘要
  setup_check.py     # status 实现
  sources/           # CNKI 检索式与 Elsevier API
run_*.py             # 各线批量入口
browser.py / captcha.py / login.py …
tests/
AGENTS.md            # 给 Agent 的使用约定（Skill+CLI）

故障排查

License

MIT © liuqiaodongdong

本仓库代码按 MIT 许可开源：可自由使用、修改、分发（含闭源商用），保留版权与许可声明即可。

使用声明（与许可证独立）

• 请遵守知网、Elsevier 等平台服务条款，仅在合法授权（机构订阅等）范围内使用。

• 验证码打码、第三方镜像等能力由你自行承担合规风险；MIT 许可代码 ≠ 授权你违反第三方 ToS 或版权法。

• 本软件按「现状」提供，作者不对滥用、封禁或数据合规问题负责。

Issues / PR 欢迎：https://github.com/liuqiaodongdong/gleaner