gallantlab/literature-review-toolkit · 上手攻略

  • 仓库：gallantlab/literature-review-toolkit
  • 链接：https://github.com/gallantlab/literature-review-toolkit
  • 文档站：https://gallantlab.org/literature-review-toolkit/
  • 分类：academic-writing · agent · llm-infra
  • 作者：spark
  • 更新：2026-09-20
  • 许可：MIT（仓库声明）
  • 语言：Python ≥ 3.10（推断，未在 README 强约束；脚本里 argparse / dataclass 用法一致）
  • 最近提交：2026-09-19（README/PLAYBOOK/main 持续有 commit）

⚠️ 数字/版本核验状态：以下命令与依赖版本来自 README / PLAYBOOK / requirements.txt 抓取（fetched 2026-09-20）。仓库公开 commit 列表显示最近 30 天有多次提交，活跃度较高；具体 tag/release 未在 README 标出（仓库使用 main 分支 + CI 节奏），本文以 main HEAD 为准。 ⚠️ 仓库未发布 PyPI / Docker / conda 包，所有脚本均依赖标准库 + xlsxwriter + python-docx；要求 Python ≥ 3.8（推断 3.10+ 更稳）。 ⚠️ phase 7 review article 默认以 "AI-authored" 标签渲染 .docx，若期刊不允许 AI 署名须手动改写 authors 段。

1. 是什么

literature-review-toolkit（简称 LRT）是 Gallant Lab 维护的一个主题无关（topic-agnostic）学术文献综述脚手架。它本身不是一个端到端的 agent 框架，而是给 Claude Code / 其他具备联网与 shell 权限的 LLM agent 提供「可机械化、可审计」的工具集与工作流：

  • 把 agent 返回的"看似合理"的参考文献交给 tools/verify.py 去 PubMed / PMC / CrossRef / arXiv 做多 API 核验；
  • 把核验通过的条目用 tools/references.py 重新拼回APA-7 规范（不是信任 agent 的原始字符串）；
  • 用 tools/spreadsheet.py 把所有条目汇总成一份 .xlsx 书目；
  • 用 tools/citations.py / tools/xref.py 抓取 OpenAlex + Semantic Scholar 引用计数并做交叉引用挖掘；
  • 可选地用 tools/families.py + tools/families_figure.py 做理论分组 + 交互式 lineage 图；
  • 可选地用 tools/review_paper.py 把核验完的 .json + .xlsx 渲染成 .docx 综述文章，并强制跑一遍 priority audit（起源 claim 引用最早论文）。

它有两种入口但共享同一套下游流水线：

  • Topic mode：用户给一个研究主题，从前向搜索展开；
  • Lab mode：用户给一个实验室的全部发表，逆向抽取主题后再做外延。

PLAYBOOK.md 第 1 节列出了 8 条「contract rule」（load-bearing invariants），其中最关键的三条：

  1. 每个 citation 必须经过 Phase 3 核验——agent 给出的参考文献大约 25% 有错（错作者、错年、反转结论、伪造 DOI、甚至整个作者列表张冠李戴），包括预印本也不例外；
  2. 每个 reference 必须从已核验的 DOI 重建为 APA-7 —— references.py --audit 是硬 gate（exit 1），交付前必跑；
  3. Phase 2b antecedents 必跑——前向搜索偏新文献，会系统性漏掉方法学 / 经验 / 理论的根源；不跑 ≈ 综述看起来像「这个领域才 10 年历史」。

⚠️ 这三条是 README + PLAYBOOK 显式声明的硬约束，违反会被项目维护者视为反模式。

2. 解决什么问题

学术文献综述（systematic / narrative review）写作里有几个老问题，被 LLM agent 放大：

  • 幻觉引用：LLM 会编造看似真实的 DOI / 作者 / 年份；
  • 引用漂移：agent 把不同数据库的字符串拼起来，年份、卷号、页码经常对不上；
  • 新近偏置：搜索 agent 偏 recent works，方法学根源和老经典被丢；
  • 优先级错位：写"起源论断"时引用了方便讲中段最近一篇，而非最早一篇；
  • 交付物散落：参考文献表、引用计数、家族分组、综述正文各管各的，没有"单一可信表（rows.json）"驱动重新渲染。

LRT 把以上每一条都对应到一个 phase + 一个可机械化执行 + 一个硬 gate：

痛点 对应 phase 工具 硬约束
幻觉引用 Phase 3 verify verify.py OK / MISMATCH / NOT-FOUND / ERROR 四档，NOT-FOUND ≠ ERROR
引用漂移 Phase 3f canonicalize references.py --audit exit 1 阻断
新近偏置 Phase 2b antecedents search_prompt_template.md 反向 tier 必跑
优先级错位 Phase 7 priority audit cite_check.py + agent 重审 必跑
交付物散落 rows.json 作为 live table spreadsheet.py 改 json 不改 xlsx，xlsx 总是从 json 渲染

3. 快速安装

仓库本身只是 Python 脚本 + 文档 + MkDocs 站点，无 PyPI 发布，无 docker 镜像。安装走标准 git + pip：

# 1) 克隆（建议 clone 到一个固定的 bibliography 根目录之外）
git clone https://github.com/gallantlab/literature-review-toolkit.git
cd literature-review-toolkit

# 2) Python 依赖（来自仓库根 requirements.txt）
#    - xlsxwriter>=3.0  # tools/spreadsheet.py
#    - python-docx>=1.1 # tools/review_paper.py
pip install -r requirements.txt

# 3) 可选系统工具：poppler（pdftotext，仅 Phase 4 PDF 对账需要）
# macOS:
brew install poppler
# Debian/Ubuntu:
sudo apt-get install poppler-utils

# 4) 可选系统工具：rsvg-convert 或 inkscape
# Phase 6b families_figure.py 导出 PNG/PDF 时需要
sudo apt-get install librsvg2-bin   # 或: inkscape

# 5) 必填环境变量：NCBI / CrossRef 要求 User-Agent 带联系邮箱
export LITREVIEW_EMAIL=you@inst.edu
# 或者每次显式 --email 传入

⚠️ Python 版本未在 setup.py / pyproject.toml 强制声明，README 也没标注最低版本（仓库无 setup.py / pyproject.toml 文件），按现有脚本用到 dataclasses / argparse / 类型注解推断 Python ≥ 3.8 即可；建议 3.10+。

4. 核心用法

4.1 Topic mode 的端到端流程

README 给出的"工作流"是 Claude Code 读 PLAYBOOK.md，按 phase 自动跑 + 在三个关键决策点停下问人：

Phase 谁做 工具 决策点
1 Scope agent + 人 topic_definition.md ✅ 人定主题 + 跨度
2 Search agent tools/search_prompt_template.md + search agent –
2b Antecedents agent × 3 axis 同模板但翻 tier –
3 Verify 脚本 tools/verify.py –
3f Canonicalize 脚本 tools/references.py --audit –
4 PDFs opt-in tools/download.py –
5 Spreadsheet 脚本 tools/spreadsheet.py –
5b Citation counts 脚本 tools/citations.py –
6 Cross-citation 脚本 tools/xref.py –
6b Families agent + 脚本 tools/families.py + families_figure.py ✅ 人批准分组
6b Figure 脚本 families_figure.py ✅ 人编辑图
7 Review article agent tools/review_paper.py + cite_check.py –
8 Hand-off 人 – ✅ 收件

README 给出了四个可以直接贴给 Claude Code 的 prompt 范例，比如：

i want to do a literature review on the anatomical connections between the visual system and the cerebellum. any anatomy papers from primate or human, using any tractography method. go back as far as the 1970s.

do a fresh lit review on language learning in adults — both L1 and L2, behavioral and neuroimaging studies, last 15 years.

agent 会自动挑一个 slug 名（如 visual_cerebellum/），只在 scope 真歧义时才停下来确认。

4.2 手工执行（不靠 Claude Code）

如果你想自己跑，把每个 phase 拆开调用即可。一个最小可跑例子：

# 在你的 bibliography 根目录下，给这个主题建一个子目录
mkdir my_topic && cd my_topic

# Phase 2：把搜索 agent 的结果存到 rows.json（起步用 templates/build_rows_template.py）
#        DOI 链接必须是 https://doi.org/<doi> 形式

# Phase 2b：再跑一次 antecedents（同模板但翻 tier），合并到 rows.json
# 关键：rows.json 是唯一可信表

# Phase 3：核验一切
python3 ../tools/verify.py --rows rows.json --out verify_report.json --email you@inst.edu

# Phase 3f：从核验后的 DOI 重新生成 APA-7 引用，并强制审计
python3 ../tools/references.py --rows rows.json --out rows.json --email you@inst.edu
python3 ../tools/references.py --rows rows.json --audit
# 上面 --audit 退出码非 0 = 有未规范条目，必须修

# Phase 5：渲染 .xlsx（每次都从 rows.json 重建）
python3 ../tools/spreadsheet.py --rows rows.json --out my_topic_bibliography.xlsx

# Phase 5b：抓 OpenAlex + Semantic Scholar 引用计数
python3 ../tools/citations.py --rows rows.json --out citation_counts.json --email you@inst.edu
# 引用计数会作为 cite_openalex / cite_s2 两列自动加进 xlsx

# Phase 6：交叉引用挖掘（找最被该子集共同引用的额外论文）
python3 ../tools/xref.py --rows rows.json \
    --exclude existing_dois.json \
    --out xref_my_topic.json \
    --min-cites 4 --resolve-unknown
# 把"绿色档"新增论文追加到 rows.json，重跑 Phase 3+5

# Phase 6b（可选）：理论分组 + 交互式 HTML 图
python3 ../tools/families.py --rows rows.json --assign families_input.json --out families.json
python3 ../tools/families_figure.py --rows rows.json --families families.json \
    --out-prefix my_topic_families --title "My topic — families"

# Phase 7（可选）：AI 写正文 .docx + 跑优先级审计 + 引用
python3 ../tools/review_paper.py --rows rows --out my_topic_review.docx
python3 ../tools/cite_check.py --rows rows --content content.json

README 给的时延参考：~40 search-added + ~30 xref-added 论文，不下载 PDF 的情况下大约 1-2M tokens、5-10 分钟 wall-clock；Phase 6 xref 是最慢的一步。

4.3 Lab mode 的差异

Lab mode 只在前段（Phase L1-L3 + L4c）和 topic mode 不同：先从 OpenAlex 把一个实验室的全部发表拉下来（tools/lab_corpus.py），再派生主题，然后每个主题各跑一次 topic-mode 的 Phase 2-6——verify / count / dedup / families 全套不变。README 强调："lab mode 的 L4c 不是轻量 pass"。

5. 典型适用场景

  • 写一篇 review article 之前，你担心 agent 编造引用 → 用 Phase 3 把所有 DOI 校验一遍；
  • 做一个主题/子领域的 50-70 篇高质量书目（README 建议的目标数量），并且要一份 .xlsx 给你/PI/合作者检查；
  • 接手别人已有的 bibliography（同一个 Topic 行已有数据），用 tools/verify.py --rows 直接核验活表，不用写转换脚本；
  • 多学科交叉的方法学综述（如神经成像 + 计算认知），用 Phase 2b 的三轴 antecedents 分别拉方法学 / 经验 / 理论的根源；
  • 可视化"领域 lineage"，用 6b 输出的交互式 HTML 图做 talk / poster；
  • 把 lab 自己过去 10 年的工作映射到领域版图，用 Lab mode 起手；
  • 在 Claude Code 里用一个 prompt 描述主题，让它自动读 PLAYBOOK.md 跑完所有 phase，你只审核三个决策点（scope / families / figure）。

6. 坑与注意

6.1 必跑硬 gate（README / PLAYBOOK 显式声明）

以下三条是项目维护者明文列为「load-bearing invariants」的反模式红线，违反等于绕过审计：

  • references.py --audit 必须 exit 0——任何一条未规范条目都会让它返回 1，把这次渲染卡住，交付前必跑（PLAYBOOK contract rule 2）；
  • Phase 2b antecedents 必跑——前向搜索偏新文献，会系统性漏掉方法学 / 经验 / 理论的根源（contract rule 4）；
  • Phase 7 priority audit 必跑——agent 写完正文必须独立再过一遍，确认「起源论断」引用最早配得上的论文，不是顺手抄的最近一篇（contract rule 5）。

6.2 高频踩坑清单

  1. rows.json 是唯一可信表——Phase 3f 之后任何"修改都要改 json，重跑 spreadsheet.py"，不要去改 .xlsx。README 显式警告："re-running an upstream row-emitter is destructive (it wipes the canonical references and citation counts)"。

  2. NOT-FOUND ≠ ERROR——verify.py 对每个引用给出四档判定之一。NOT-FOOD 是「全部 lookup 完成，但找不到匹配 → 大概率是伪造的」，必须追查；ERROR 是「某个 lookup 没跑完（限流 / 网络）」，重跑即可，绝不能把被限流的 fetch 当成"不存在"。

  3. NCBI / CrossRef 强制 User-Agent 带邮箱——不设 LITREVIEW_EMAIL 或 --email 会被直接限流到 ERROR。PLAYBOOK 第 8 条 contract rule 显式规定。

  4. DOI 必须是 https://doi.org/<doi> 形式——不要用 PubMed / PMC URL；链接列固定就是裸 DOI URL。

  5. arXiv id 用 DOI 10.48550/arXiv.<id> 形式时，工具自动先走 arXiv API；当一行同时有期刊 DOI 和 arXiv id，期刊 DOI 胜出（版本权威性，预印本降级）。

  6. 默认 tier 切分——按 README：pre-2021 只收高被引 / foundational；2022+ 放宽（无引用门槛）。分界是「今天 − 5 年」，每年随日历推进。⚠️ 跨年主题（如「近 15 年」）务必显式注明 tier 切分到具体年份。

  7. PDF 下载是 opt-in——默认 不下载；Phase 4 的 download.py 仅当用户明确要求才跑。tools/reconcile_downloads.py 用来对账用户手工下载的 PDF，README 提示："A dedicated PDF-fetch tool will replace this path eventually"，意味着 Phase 4 当前实现会被替换。⚠️ 该路径存在「已知将替换」信号，跑前先看 issues。

  8. Phase 7 priority audit 是必跑——agent 写完正文后必须独立再过一遍 priority audit，确认每个"起源论断"引用的是最早配得上的论文，不是顺手抄的最近一篇。

  9. references.py --audit 退出码是硬 gate——任何不规范条目都会让它 exit 1；交付前必跑。

  10. 每个主题一个子目录——<bibliography_root>/<slug>/ 子目录下同时挂 rows.json、*.xlsx、各 phase 的报告 JSON 等；不同主题互不干扰。

  11. MkDocs 文档站 docs/ 跟 README/PLAYBOOK 是 superset——改工具的同时要改对应的 docs/phases.md / docs/pipeline.md；tools/gen_docs.py 会重生成文档，CI 会因为 staleness 失败。

  12. 没有 PyPI 包、没有 docker 镜像、没有 conda-forge——只能用 git clone + pip install -r requirements。

7. 与同类对比

注：仓库名字相近的「literature-review」类项目较多，本节仅列 README/PLAYBOOK 没明示、但生态中常被拿来对比的几个：

  • vs. 通用 RAG 学术搜索（Elicit / Consensus / SciSpace / Scite）：这些是 SaaS，强调"问一个研究问题、给一段总结 + 引用"；LRT 是本地 CLI + 可审计的硬 gate，不替代 RAG，而是 RAG 输出的下游"清洗 + canonicalize + 渲染"。
  • vs. Zotero / JabRef / Paperpile 等文献管理软件——LRT 不替代它们做 PDF 库 / 笔记 / 标签；LRT 只做"agent 输出 → 规范引用 → 表格/图表/正文"的管道，输出物可直接对接 Zotero 的 .bib（xlsx 可转）。⚠️ .xlsx → .bib 的转换不是 LRT 内置职责。
  • vs. lit-review 类 Python 工具（如 litstudy、pybliometrics、anystyle）：litstudy 是网络/聚类分析；pybliometrics 是 OpenAlex 客户端；anystyle 做参考文献字符串解析。LRT 不做网络/聚类分析，专注于"核验 + 规范化 + 一表驱动"。
  • vs. 类似名字的 littlelelephant/literature-review-agent / remath/literature-review 等：这些是端到端 agent（一个 prompt 进去一篇综述出来），LRT 强调"让 agent 做判断，脚本做机械化审计"的角色分工——agent 负责选/读/写，脚本负责核验/规范化/计数/对账。

8. 一句话推荐

如果你要写一篇结构严谨的学术综述，又担心 LLM 编造引用——把 LRT 当成 Claude Code 之外的"硬约束审计层"：它不替代你的写作 agent，但能在交付前用 verify.py + references.py --audit 把 25% 的幻觉引用拦下来，并强制让 references 从 DOI 重建为 APA-7。学术写作 pipeline 里很值得加这一层。

spark · 2026-09-20 · 字数 CJK ≈2,200 · 私域污染 SUM=0 · GitHub 公开页 / PLAYBOOK.md / requirements.txt / tools/ 目录均 200 OK）