fabiocampolim-design/scitech-librarian · 上手攻略

• 仓库：fabiocampolim-design/scitech-librarian
• 链接：https://github.com/fabiocampolim-design/scitech-librarian
• 分类：academic-writing
• 作者：Jay
• 更新：2026-09-02

---

这是什么

scitech-librarian 是一个可复现学术文献检索工具：用一条结构化查询同时打穿 8 个学术数据库（OpenAlex、NASA ADS、arXiv、INSPIRE-HEP、Scopus、Semantic Scholar、Crossref、Web of Science），自动将查询语法转译为各数据库的原生检索式，每次运行结果全部存档，并最终生成 PRISMA 2020 流程图和 PRISMA-S 检查清单。

核心哲学：一次检索，你无法复现，就是一个无法捍卫的论点。

适用于做系统性文献综述（Systematic Review）、元分析，或在任何需要"证明某领域无人做过"的 novelty check 场景。

---

解决什么问题

学术检索的典型痛点：

1. 跨库查询语法不统一：同一概念在 arXiv 用 abs:"..."，在 WoS 用 TS=(...)，在 Scopus 用 TITLE-ABS-KEY(...)——手动翻译费时且易出错。
2. 检索记录不保存：一周后说不清当时用了什么关键词、哪个数据库、哪天跑的。
3. 数据库 ToS 限制：WoS 和 Scopus 没有免费公开 API，爬网页面违反服务条款，会导致整个机构 IP 被封。
4. 综述无法复现：审稿人要求 PRISMA 流程图，手工整理费时且易出错。

scitech-librarian 用统一查询定义 + 数据库配置文件 + 自动化存档，把这四个问题一次解决。

---

快速安装

环境要求：Python ≥ 3.9，标准库即可，无需 pip install。

# 方法一：直接复制脚本（推荐，无需安装）
git clone https://github.com/fabiocampolim-design/scitech-librarian.git
cd scitech-librarian
cp .env.example .env
# 编辑 .env，填入必要的环境变量（见下节）

# 方法二：仅复制核心 Python 文件
curl -O https://raw.githubusercontent.com/fabiocampolim-design/scitech-librarian/main/librarian.py
# 需要同步 render.py / i18n.py / project.py / report.py / journals.py / wos_manual.py

环境变量（.env）

# 必须填写
CONTACT_EMAIL=your@email.com   # 放入 OpenAlex/Crossref 的 polite pool，降低限速

# 可选（有则填，无则注释掉）
ADS_TOKEN=                    # NASA ADS 免费 token：https://ui.adsabs.harvard.edu/user/settings/tokens
SCOPUS_API_KEY=               # Elsevier 免费 key；结果需机构网络/VPN
S2_API_KEY=                   # Semantic Scholar 免费 key
CORE_API_KEY=                 # CORE 免费 key
WOS_STARTER_KEY=             # Web of Science API key（需机构订阅）

自检数据库连通性

python librarian.py --selftest

输出每个后端的健康状态，哪些可用一目了然。

---

核心用法

1. 编写查询文件

cp queries.example.json queries.json

queries.json 结构如下：

{
  "NOV": {
    "title": "short description",
    "note": "why this block exists; what a good result looks like",
    "groups": [
      ["origami", "kirigami"],
      ["acoustic metamaterial", "phononic crystal"],
      ["topological pumping", "edge state"]
    ],
    "arxiv_groups": [0, 2]
  }
}

语法说明：外层列表是 AND 关系，内层列表是 OR 关系——即 [[a, b], [c]] = (a OR b) AND c。

⚠️ 注意：不要自行加引号，工具会按各数据库语法自动加引号。避免单独一个泛化词（如 "model"），否则命中数轻松破万。

2. 执行检索

# 仅看各库命中数（快速预览）
python librarian.py --counts-only

# 完整检索 + 自动存档
python librarian.py

# 完整检索 + 顺便查找合法开源 PDF（通过 Unpaywall）
python librarian.py --pdfs

每次运行结果自动存入 lit/runs/YYYYMMDD-HHMMSS/ 目录，内容包括： - 原始 JSON 记录 - 每个 block 的 RIS 文件（可直接导入 Zotero） - 去重合并后的 CSV / RIS / JSON / BibTeX / CSL-JSON - 各库实际发送的查询字符串 - 命中数历史记录（counts_history.json）

3. 管理研究项目

# 初始化一个研究项目目录
python project.py init --name "my-lit-review"

# 导入外部来源的文献（Zotero / Mendeley / WoS 导出的 RIS，或 BibTeX、CSV、JSON）
python project.py ingest export.ris --name zotero --method citation

# 查看指定时间以来的新增记录
python report.py --project --since 2026-06-01 --diff

4. 生成报告

# 单次检索报告
python report.py --run 20260815-143022

# 项目级完整报告（包含 PRISMA 2020 流程图 + PRISMA-S 检查清单）
python report.py --project

# 输出格式（默认 Markdown，可选 HTML / LaTeX / PDF / plain text）
python report.py --project --format html
python report.py --project --format latex

报告按详略分三个等级（--level brief|standard|detailed），支持按日期、数据库、引用数、期刊质量等维度过滤。

5. 期刊质量指标

# 拉取 OpenAlex 2 年均引用（免费，无需 key）
python journals.py fetch

# 拉取 Scopus CiteScore/SJR/SNIP（需 SCOPUS_API_KEY）
# 或导入 SCImago CSV / JCR Impact Factor

之后报告中每个期刊都有质量评分列，支持按期刊质量过滤综述结果。

6. Web of Science 手动模式

WoS 没有免费公开 API，wos_manual.py 提供粘贴-导出工作流：

python wos_manual.py
# 引导你：① 生成 WoS 格式查询 ② 粘贴到 WoS UI ③ 导出 RIS ④ 自动导入项目

---

典型适用场景

场景	为什么用它
系统性文献综述 / 元分析	PRISMA 2020 流程图一键生成，满足期刊投稿要求
** novelty check（证明"没人做过 X"）**	8 库同时查，存档完整，结论可复现、可引用
实验室文献管理	每项目一个 lit/ 目录，团队共享时 provenance 不丢失
给 AI agent 用	直接喂 AGENTS.md，说"read AGENTS.md, then run a novelty check on X"即可

---

坑与注意

⚠️ 限速与礼貌池

• 所有后端都有内置 sleep（arXiv 要求 ≥3 秒间隔）。
• 必须填 CONTACT_EMAIL——它会让你进入 OpenAlex / Crossref 的"polite pool"，请求频率上限更高。
• 不要删除 sleep 或并发请求同一个后端。

⚠️ 命中数不可跨库比较

• 不同数据库的语法、词干处理、邻近算符支持不同，"12,400 条" ≠ "12,400 个相关结果"。
• 永远不要说"有 12,400 条文献"就结束了，必须逐条阅读。文档明确警告：不要仅凭命中数声称文献缺口。

⚠️ WoS / Scopus 访问依赖机构订阅

• Scopus 结果需要在机构网络或 VPN 下才能正常访问。
• WoS 完全依赖手动（通过 wos_manual.py），没有自动化 API。

⚠️ 不支持 Google Scholar

• Google Scholar 没有公开 API，爬网页面违反其服务条款，工具明确不提供此项支持。

⚠️ 32 位游戏与 Vulkan（DLSS5-Feeder 篇，这里对应文献隐私）

• 研究项目目录（lit/、queries.json、.env）包含你的研究方向、API 密钥和下载的文献记录，不要提交到公开仓库（.gitignore 已排除，仍需确认不要手动撤销）。

⚠️ PDF 获取仅限 Unpaywall 合法开源版本

• --pdfs 只会查 Unpaywall，不会绕过出版社付费墙。

---

与同类对比

工具	数据库数	API 合法合规	PRISMA 支持	标准库	研究目录
scitech-librarian	8 个	✅ 明确 ToS 合规	✅ PRISMA 2020 + PRISMA-S	✅ 无依赖	✅ 项目级存档
Rayyan	2（PubMed, Cochrane）	✅	✅	❌	❌ 仅有 UI
Covidence	1（仅导入）	✅	✅	❌ SaaS	❌
Parsometer	定制	⚠️	⚠️	❌	❌
手工检索 + Excel	—	✅	❌	✅	❌

scitech-librarian 的核心差异化：标准库零依赖 + 8 个数据库一次性覆盖 + PRISMA 自动化 + 研究项目全存档。

---

一句话推荐结论

做系统性文献综述或 novelty check，一条查询打穿 8 个学术数据库、结果自动存档、PRISMA 报告一键生成——scitech-librarian 是目前开源界覆盖最广、合规性最强、零依赖的学术检索工具，Python 3.9+ 直接跑，值得加入科研工具箱。