literature-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Literature Review

文献综述

Produce a themed, citation-grounded review document from a research question. This skill is the orchestrator: searching, fetching, and citation verification are delegated to sibling skills; this skill owns the workspace, the screening corpus, claim extraction, thematic synthesis, and the final coverage gate.

基于研究问题生成主题明确、引用可靠的综述文档。本技能为协调器：论文搜索、全文获取和引用验证任务将委托给关联技能；本技能负责管理工作区、筛选文献库、提取论断、主题整合以及最终的内容覆盖校验。

When to use

使用场景

"Do a literature review on X" / "survey recent work on X"
"What's the state of the art in X since 2023?"
"Read these N papers and synthesize them by theme"
A standalone survey is wanted. For a paper's Related Work section, do the corpus-building phases here, then hand off to
```
draft-related-work
```
.

“针对X做一篇文献综述” / “调研关于X的近期研究”
“2023年以来X领域的技术现状如何？”
“阅读这N篇论文并按主题整合内容”
需要独立撰写综述时。若需撰写论文的「相关研究」章节，可在此完成文献库构建阶段，再交由
```
draft-related-work
```
技能处理。

Inputs

输入信息

A research question or topic, ideally with year range and (optionally) target venues.
```
CONTACT_EMAIL
```
exported for the sibling skills' API politeness contract.
Optional: an existing list of papers/DOIs the user already has.

研究问题或主题，最好包含时间范围（可选）和目标会议/期刊。
需导出
```
CONTACT_EMAIL
```
，以满足关联技能的API礼貌调用协议。
可选：用户已有的论文列表/DOI。

Sibling skills this skill delegates to

本技能委托的关联技能

Stage	Delegate to	What it provides
Search	`find-papers`	`dblp_search.py` , `crossref_search.py` , `s2_search.py` , `arxiv_search.py` (in that skill's script dir) — key-free, rate-limited, cached
Full text	`fetch-paper`	`resolve_oa.py` — one DOI/arXiv ID → legal OA copy, transient
Reference check	`verify-citations`	validates every BibTeX entry against Crossref/DBLP/S2, flags retractions

Never reimplement these inline (no ad-hoc

curl

against scholarly APIs); the sibling scripts carry the rate-limit, backoff, caching, and User-Agent contract.

阶段	委托至	提供的功能
搜索	`find-papers`	`dblp_search.py` 、 `crossref_search.py` 、 `s2_search.py` 、 `arxiv_search.py` （位于该技能的脚本目录）——无需密钥、限频、带缓存
全文获取	`fetch-paper`	`resolve_oa.py` ——输入单个DOI/arXiv ID即可获取合法开放获取版本，临时存储
引用校验	`verify-citations`	验证每个BibTeX条目是否符合Crossref/DBLP/S2标准，标记已撤回的文献

切勿在本技能内重新实现上述功能（不要直接通过

curl

调用学术API）；关联脚本已处理限频、退避、缓存和User-Agent协议。

Process

流程

Phase 1 — Scope

阶段1 — 确定范围

Pin down with the user: research question, year range, inclusion and exclusion criteria (2–4 each), target size (10–15 papers is a solid default; >30 needs explicit user buy-in).

Run

python3 scripts/init_review.py "TOPIC"

— creates

lit-review/<slug>/

with

corpus.json

themes.yml

notes/

, and a

review.md

skeleton.

Write the agreed criteria into
```
corpus.json
```
under
```
criteria
```
.

与用户确认：研究问题、时间范围、纳入与排除标准（各2-4条）、目标文献数量（默认10-15篇较为合适；超过30篇需明确获得用户同意）。

运行

python3 scripts/init_review.py "TOPIC"

——创建

lit-review/<slug>/

目录，包含

corpus.json

、

themes.yml

、

notes/

和

review.md

框架文件。

将确认的标准写入
```
corpus.json
```
的
```
criteria
```
字段。

Phase 2 — Search (delegate to find-papers)

阶段2 — 搜索（委托至find-papers）

Follow references/methodology.md for query design, venue enumeration, and snowballing.
If the scope names venues, read
```
venues/conferences/<id>.yml
```
for the
```
aliases
```
block (DBLP key, S2 venue string, Crossref container title) — this solves the venue-alias problem. Profiles are a starting point: if any profile fact becomes load-bearing for the review (e.g. which tracks exist), re-verify it against the live
```
cfp_url
```
before relying on it.

Record every search hit batch:

python3 scripts/corpus.py --corpus <ws>/corpus.json import hits.json --source dblp --query "..."

(accepts

find-papers --json

output; dedupes on DOI). Add single papers with

corpus.py add

Snowball from multiple, topically-diverse seeds — one per theme, not a single convenient paper (which drifts the harvested set into one sub-area and misses the rest). Admit each neighbor only if you can name its role in the question's argument (method-we-extend / baseline / eval-task / foundational-lineage), and run the co-citation sanity check before screening. Full protocol in references/methodology.md.
Treat a degraded search as not-yet-done, not done.
```
find-papers
```
'
```
resolve_papers.py
```
stamps each fan-out COMPLETE or PARTIAL and flags any result confirmed by only a single index. If a theme's search comes back PARTIAL (a provider was rate-limited), or its core papers are single-index only, the citation-graph stage silently fell back — recall for that theme rests on luck. Re-issue the rate-limited leg after a cool-down (add
```
S2_API_KEY
```
) or substitute a provider before declaring the theme covered; record in
```
corpus.json
```
which papers were recoverable only via a fallback path so the gap is auditable.

遵循references/methodology.md中的查询设计、会议/期刊枚举和滚雪球式检索方法。
若范围指定了会议/期刊，查看
```
venues/conferences/<id>.yml
```
中的
```
aliases
```
块（DBLP密钥、S2会议名称、Crossref容器标题）——这可解决会议/期刊别名问题。配置文件仅作为起点：若任何配置信息对综述至关重要（如存在哪些分会场），需先通过实时
```
cfp_url
```
重新验证，再依赖该信息。

记录每一批搜索结果：

python3 scripts/corpus.py --corpus <ws>/corpus.json import hits.json --source dblp --query "..."

（支持

find-papers --json

输出；基于DOI去重）。使用

corpus.py add

添加单篇论文。

从多个主题多样的种子文献（每个主题一篇）开始滚雪球式检索，而非仅从一篇方便获取的文献开始（这会导致检索集合偏向某一子领域，遗漏其他内容）。仅当能明确说明该文献在研究问题中的作用（如待扩展方法、基线模型、评估任务、基础研究脉络）时，才将其纳入，并在筛选前进行共引合理性检查。完整流程详见references/methodology.md。
检索结果不完善视为未完成，而非已完成。
```
find-papers
```
的
```
resolve_papers.py
```
会标记每个检索分支为COMPLETE或PARTIAL，并标记仅单个索引返回的结果。若某主题的检索结果为PARTIAL（某提供商触发限频），或其核心文献仅来自单个索引，则引用图谱阶段已自动降级——该主题的检索召回率依赖运气。需在冷却后重新发起限频分支的检索（添加
```
S2_API_KEY
```
），或替换提供商，再宣布该主题检索完成；在
```
corpus.json
```
中记录仅通过 fallback 路径获取的文献，以便审计检索缺口。

Phase 3 — Screen

阶段3 — 筛选

For each pending paper, decide included/excluded against the written criteria using title + venue + (fetched-on-demand) abstract. Use
```
s2_search.py
```
from find-papers for abstracts — never paste abstracts into any committed file.

Record every decision with a reason:

python3 scripts/corpus.py --corpus ... set KEY --screened excluded --reason "out of scope: no spatial component"

Show the user
```
corpus.py stats
```
and the included list before reading full texts. Confirm the set.

对每篇待筛选的论文，根据标题、会议/期刊及（按需获取的）摘要，对照已确定的标准决定是否纳入。使用find-papers中的
```
s2_search.py
```
获取摘要——切勿将摘要粘贴至任何已提交的文件中。

记录每个决策及理由：

python3 scripts/corpus.py --corpus ... set KEY --screened excluded --reason "out of scope: no spatial component"

。

向用户展示
```
corpus.py stats
```
的统计结果及纳入列表，确认该集合后再阅读全文。

Phase 4 — Fetch and extract (delegate to fetch-paper)

阶段4 — 获取与提取（委托至fetch-paper）

One paper at a time, run fetch-paper's resolver (from the repo root):
```
FP=skills/fetch-paper/scripts; python3 "$FP/resolve_oa.py" <DOI-or-arXiv-ID>
```
. Read the OA copy transiently — prefer arXiv HTML, else the PDF directly. If no legal OA copy exists (exit code 3), mark the paper and synthesize from verified metadata only, or ask the user for their library copy. Never use shadow libraries.
Take grounded notes into
```
notes/<key>.md
```
using the claim-record format in references/claim-extraction.md: each claim gets an anchor (section/page), a strength label, and paraphrase only (verbatim quotes < 25 words, always quoted). Never store abstracts or paper text — notes are your words.

Mark progress:

corpus.py set KEY --fetched yes --extracted yes

逐篇运行fetch-paper的解析器（从仓库根目录执行）：
```
FP=skills/fetch-paper/scripts; python3 "$FP/resolve_oa.py" <DOI-or-arXiv-ID>
```
。临时读取开放获取版本——优先选择arXiv HTML格式，其次直接读取PDF。若不存在合法开放获取版本（退出码3），标记该论文并仅基于已验证的元数据进行整合，或向用户请求其机构库中的版本。切勿使用影子图书馆。
按照references/claim-extraction.md中的论断记录格式，将有依据的笔记写入
```
notes/<key>.md
```
：每个论断需包含锚点（章节/页码）、可信度标签，且仅使用转述（引用原文需少于25词，且必须加引号）。切勿存储摘要或论文原文——笔记需使用自己的语言。

标记进度：

corpus.py set KEY --fetched yes --extracted yes

。

Phase 5 — Organize by theme

阶段5 — 按主题分类

Cluster the extracted claims into 3–6 themes; record them in
```
themes.yml
```
and tag papers:
```
corpus.py set KEY --theme <slug>
```
.
Build the synthesis matrix (paper × theme × approach × evaluation × result) per references/review-structure.md.

将提取的论断聚类为3-6个主题；将主题记录在
```
themes.yml
```
中，并为论文添加主题标签：
```
corpus.py set KEY --theme <slug>
```
。
按照references/review-structure.md构建整合矩阵（论文×主题×方法×评估×结果）。

Phase 6 — Verify citations (delegate to verify-citations)

阶段6 — 验证引用（委托至verify-citations）

Generate skeleton BibTeX:
```
python3 scripts/corpus.py --corpus ... bibtex > <ws>/references.bib
```
.
```
corpus.py
```
is the single source of truth for cite keys —
```
bibtex
```
emits the
```
.bib
```
with the corpus's exact keys. Never hand-edit a key in the
```
.bib
```
; change it in the corpus (
```
corpus.py add --update
```
) and regenerate, so the corpus, the
```
.bib
```
, and the review's
```
[@key]
```
s never diverge.
Run the
```
verify-citations
```
skill on
```
references.bib
```
, always with
--json
so there is a machine artifact to reconcile against:
```
check_bibtex.py <ws>/references.bib --json <ws>/citecheck.json
```
. Fix or drop anything unresolvable; flag retractions to the user.
Set verified flags from that artifact, not by hand:
```
python3 scripts/corpus.py --corpus <ws>/corpus.json verify-audit --report <ws>/citecheck.json
```
. The audit marks
```
verified:yes
```
only for keys the report confirmed (status VERIFIED), clears any flag the report did not confirm, records
```
verified_via
```
provenance + the date, and echoes the report's verdict line verbatim. It exits nonzero on a PARTIAL-PASS or FAIL — so an incomplete run cannot read as clean.
- If you set a flag manually instead,
```
corpus.py set KEY --verified yes
```
  now requires
  --source <provider>
  (the index whose canonical record confirmed the entry) and records it; a bare
```
--verified yes
```
  is rejected.
- "Verified" means an authoritative index actually returned the canonical record for this entry this session — not merely that some API echoed an id once, and never with
```
fetched:false
```
  . A key marked
```
verified:yes
```
  with no provenance is a broken gate;
```
corpus.py stats
```
  now WARNs when it sees one.
- Mirror the verify-citations verdict line verbatim in the review's prose and any summary/README: the exact verdict (PASS / PARTIAL-PASS / FAIL) plus raw counts (N verified, M warnings by flag, K skipped checks). Never upgrade a PARTIAL-PASS to "verified", and never collapse "PARTIAL-PASS, 11 WARN, 1 skipped" into "verified, 0 errors".

生成BibTeX框架：
```
python3 scripts/corpus.py --corpus ... bibtex > <ws>/references.bib
```
。
```
corpus.py
```
是引用密钥的唯一可信来源——
```
bibtex
```
命令会输出与文献库中密钥完全一致的
```
.bib
```
文件。切勿手动编辑
```
.bib
```
中的密钥；如需修改，需在文献库中执行
```
corpus.py add --update
```
，再重新生成，确保文献库、
```
.bib
```
文件和综述中的
```
[@key]
```
引用始终一致。
对
```
references.bib
```
运行
```
verify-citations
```
技能，必须添加
--json
参数，以便生成可核对的机器产物：
```
check_bibtex.py <ws>/references.bib --json <ws>/citecheck.json
```
。修复或删除无法解析的条目；向用户标记已撤回的文献。
仅基于该产物设置验证标记，切勿手动设置：
```
python3 scripts/corpus.py --corpus <ws>/corpus.json verify-audit --report <ws>/citecheck.json
```
。该审计仅会为报告中确认（状态为VERIFIED）的密钥标记
```
verified:yes
```
，清除报告未确认的标记，记录
```
verified_via
```
来源及日期，并逐字回显报告的判定结果。若报告为PARTIAL-PASS或FAIL，该命令会返回非零退出码——因此未完成的验证无法被视为通过。
- 若手动设置标记，
```
corpus.py set KEY --verified yes
```
  现在必须添加
  --source <provider>
  参数（即确认该条目的权威索引）并记录；仅使用
```
--verified yes
```
  会被拒绝。
- “已验证”指本次会话中某权威索引实际返回了该条目的标准记录——而非仅某API曾返回过一次ID，且
```
fetched:false
```
  时无法标记为已验证。若某密钥标记为
```
verified:yes
```
  但无来源，则属于校验失效；
```
corpus.py stats
```
  现在会对此发出警告。
- 在综述正文及任何摘要/README中逐字回显verify-citations的判定结果：精确的判定（PASS / PARTIAL-PASS / FAIL）及原始统计数据（已验证数量N、各类警告数量M、跳过检查数量K）。切勿将PARTIAL-PASS升级为“已验证”，也切勿将“PARTIAL-PASS, 11 WARN, 1 skipped”简化为“已验证，0错误”。

Phase 7 — Draft

阶段7 — 撰写

Write
```
review.md
```
following the structure templates in references/review-structure.md.
Every factual claim about prior work cites a corpus key:
```
[@key]
```
or
```
\cite{key}
```
. Claims must trace back to a note anchor — if there is no note, do not write the claim.

遵循references/review-structure.md中的结构模板撰写
```
review.md
```
。
所有关于已有研究的事实性论断均需引用文献库中的密钥：
```
[@key]
```
或
```
\cite{key}
```
。论断必须能追溯至笔记中的锚点——若无对应笔记，则不得撰写该论断。

Phase 7b — Reconcile forward references

阶段7b — 核对前置引用

The draft (and any related-work plan) names methods, baselines, and backbones in prose as slots — "we extend X", "compared against Y", "built on the W backbone". Make sure none ship unbacked:

Run
```
python3 scripts/forward_refs.py <ws>/review.md [plan.md] --corpus <ws>/corpus.json
```
. It extracts every named method/baseline/ backbone, diffs against the verified corpus, and emits the unresolved ones as a retrieval worklist.
For each genuine missing work, loop it back through the full pipeline (find-papers → screen → fetch-paper → extract → verify-citations) before the corpus is declared complete. Dismiss only the entries that are not citable works (the user's own system, a dataset, a metric) — never invent a citation to clear the list.
Re-run until the worklist holds no real references.

综述（及任何相关研究计划）正文中会提及方法、基线模型和基础框架等内容，如“我们扩展了X”“与Y进行对比”“基于W框架构建”。确保所有提及内容均有依据：

运行
```
python3 scripts/forward_refs.py <ws>/review.md [plan.md] --corpus <ws>/corpus.json
```
。该脚本会提取所有提及的方法/基线模型/基础框架，与已验证的文献库进行比对，并将未解决的条目输出为检索任务清单。
对于每篇确实缺失的文献，需将其重新纳入完整流程（find-papers → 筛选 → fetch-paper → 提取 → verify-citations），再宣布文献库已完成。仅可排除非可引用内容（如用户自行开发的系统、数据集、指标）——切勿伪造引用以清空清单。
重复运行直到任务清单中无真实参考文献。

Phase 8 — Gate

阶段8 — 校验

Assert the corpus and
```
references.bib
```
keys are in lock step:
```
python3 scripts/corpus.py --corpus <ws>/corpus.json check-keys <ws>/references.bib
```
. If it fails, regenerate the
```
.bib
```
from the corpus (
```
corpus.py bibtex
```
) — never reconcile by hand-editing keys.
Run
```
python3 scripts/check_review.py <ws>/review.md --bib <ws>/references.bib
```
. It fails on unknown keys, unverified or excluded citations, any cited key missing from the
```
.bib
```
(key drift), placeholder markers, and verbatim quotes over 40 words; it warns on uncited included papers and uncited long paragraphs.
Fix and re-run until
```
RESULT: PASS
```
. Deliver only a passing document, and tell the user the review passed the coverage gate.

确认文献库与
```
references.bib
```
中的密钥完全一致：
```
python3 scripts/corpus.py --corpus <ws>/corpus.json check-keys <ws>/references.bib
```
。若验证失败，需从文献库重新生成
```
.bib
```
文件（
```
corpus.py bibtex
```
）——切勿通过手动编辑密钥来核对。
运行
```
python3 scripts/check_review.py <ws>/review.md --bib <ws>/references.bib
```
。该脚本会在以下情况时返回失败：未知密钥、未验证或已排除的引用、
```
.bib
```
中缺失的已引用密钥（密钥不一致）、占位符标记、超过40词的原文引用；会在以下情况时发出警告：已纳入但未引用的论文、未引用的长段落。
修复问题后重新运行，直到输出
```
RESULT: PASS
```
。仅交付通过校验的文档，并告知用户综述已通过内容覆盖校验。

Output

输出产物

```
lit-review/<slug>/review.md
```
— the themed review, every claim cited, gated by
```
check_review.py
```
.
```
lit-review/<slug>/corpus.json
```
— auditable trail: searches, screening decisions with reasons, verification status.
```
lit-review/<slug>/references.bib
```
— verified BibTeX.
```
lit-review/<slug>/notes/
```
— per-paper grounded notes (paraphrase only).

```
lit-review/<slug>/review.md
```
——主题明确的综述文档，所有论断均有引用，已通过
```
check_review.py
```
校验。
```
lit-review/<slug>/corpus.json
```
——可审计的记录：检索记录、筛选决策及理由、验证状态。
```
lit-review/<slug>/references.bib
```
——已验证的BibTeX文件。
```
lit-review/<slug>/notes/
```
——单篇论文的有依据笔记（仅包含转述内容）。

Guardrails

约束规则

Never fabricate or embellish a citation. A paper enters the review only via a real search hit, and a citation ships only after
```
verify-citations
```
passes it. If evidence for a claim is missing, say so instead.
Copyright: paper text and abstracts are fetched on demand and processed transiently — never written into the workspace, the repo, or the review. Metadata (DOI, title, authors, BibTeX fields) is fine. Quotes < 25 words, marked and cited.
Politeness: all network access goes through the sibling skills' scripts (≤1 req/s per host,
```
CONTACT_EMAIL
```
User-Agent, 429 backoff,
```
.cache/
```
).
Never submit or post anything on the user's behalf.
Present screening decisions and the final theme structure to the user for approval — the user owns scope judgments.

切勿伪造或夸大引用。论文仅可通过真实检索结果纳入综述，引用仅可在
```
verify-citations
```
验证通过后使用。若某论断缺乏证据，需如实说明。
版权：论文原文和摘要按需获取并临时处理——切勿写入工作区、仓库或综述文档。元数据（DOI、标题、作者、BibTeX字段）可保留。引用原文需少于25词，且需标记并注明引用来源。
礼貌调用：所有网络访问均需通过关联技能的脚本进行（每个主机≤1请求/秒，User-Agent包含
```
CONTACT_EMAIL
```
，触发429错误时退避，使用
```
.cache/
```
缓存）。
切勿代表用户提交或发布任何内容。
筛选决策和最终主题结构需提交用户审批——用户拥有范围判断的最终决定权。

References

参考文档

references/methodology.md — query design, venue enumeration patterns, multi-seed snowballing with role-based inclusion and a co-citation sanity check, stopping criteria, screening protocol, forward-reference reconciliation.
references/claim-extraction.md — grounded note format, anchor and strength labels, copyright rules for notes.
references/review-structure.md — review document templates, synthesis matrix, citation syntax, handoffs to
```
draft-related-work
```
and
```
write-abstract
```
.

references/methodology.md——查询设计、会议/期刊枚举模式、基于角色纳入的多种子滚雪球式检索及共引合理性检查、停止准则、筛选流程、前置引用核对方法。
references/claim-extraction.md——有依据的笔记格式、锚点和可信度标签、笔记的版权规则。
references/review-structure.md——综述文档模板、整合矩阵、引用语法、向
```
draft-related-work
```
和
```
write-abstract
```
技能的交接方法。