literature-review-agent

文献综述 Agent（步骤 3）

忠实实现 PaperOrchestra 中的混合文献 Agent （Song 等人，2026，arXiv:2604.05018，§4 步骤 3、附录 D.3、附录 F.1 第 46 页）。

成本：约 20–30 次 LLM 调用。 这是两个耗时最长的步骤之一（另一个是 绘图）。耗时下限由 Semantic Scholar 每秒 1 次请求的验证限制决定。

输入

• workspace/outline.json — 具体为 intro_related_work_plan，其中包含引言的搜索方向和 2-4 个相关工作方法学类别
• workspace/inputs/conference_guidelines.md — 用于推导 cutoff_date
• workspace/inputs/idea.md、workspace/inputs/experimental_log.md — 用于构思引言，并为相关工作的定位提供依据

输出

• workspace/citation_pool.json — 所有通过验证的论文的 Semantic Scholar 元数据
• workspace/refs.bib — 根据已验证的文献池生成的 BibTeX 文件
• workspace/drafts/intro_relwork.tex — 写入模板的引言和相关工作章节，其余模板内容保持原样

两阶段工作流（附录 D.3）

PHASE 1 — Parallel Candidate Discovery
   For each search direction in introduction_strategy.search_directions:
   For each limitation_search_query in each related_work cluster:
     - Use the host's web search tool to discover up to ~10 candidate papers.
     - Run up to 10 discovery queries in parallel (host-permitting).
     - Collect (title, snippet, url) tuples — no verification yet.
   → PRE-DEDUP before Phase 2 (see Step 1.5 below)

PHASE 2 — Sequential Citation Verification (1 QPS, with cache)
   For each candidate (after pre-dedup), sequentially:
     0. Check s2_cache.json first (scripts/s2_cache.py --check).
        If HIT: use cached response, skip live S2 call. No throttle needed.
        If MISS: proceed with live request below.
     1. Query Semantic Scholar by title:
          GET https://api.semanticscholar.org/graph/v1/paper/search?query=<title>
              &fields=title,abstract,year,authors,venue,externalIds&limit=5
        (Public endpoint, no key. Throttle to 1 QPS for live requests only.)
     2. Store the S2 response in cache: s2_cache.py --store.
     3. Pick the top hit. Check Levenshtein title ratio against the original
        candidate title. If ratio < 70: discard.
     4. Bonus: if year and venue exactly align with hints, add a +5 point
        match-quality bonus.
     5. Require: abstract is non-empty.
     6. Require: paper.year (or month if known) strictly predates cutoff_date.
        Months default to day-1: e.g., "October 2024" → 2024-10-01.
     7. If all checks pass, add to verified pool.
   After all candidates are verified, dedup by Semantic Scholar paperId.

宿主 Agent 负责 LLM 和网络搜索工作；scripts/ 中的确定性辅助程序负责计算。

分步说明

0. 推导 cutoff_date

从 conference_guidelines.md 中解析投稿截止日期。论文将研究截止日期与会议投稿截止日期对齐（附录 D.1）：

会议	截止日期
CVPR 2025	2024 年 11 月
ICLR 2025	2024 年 10 月
其他	所述投稿截止日期前一个月

编码为 YYYY-MM-DD。月份默认取当月 1 日（例如，2024-10-01）。

1. 阶段 1：并行发现候选论文

从 outline.json 中获取：

• 所有 introduction_strategy.search_directions（3-5 个查询）
• 对于 related_work_strategy.subsections 中的每个类别：
  • 将该类别的 sota_investigation_mission 作为搜索查询
  • 所有 limitation_search_queries（每个 1-3 个）

对于每个查询，使用宿主提供的网络搜索工具（例如，Claude Code 中的 WebSearch、Cursor 中的 @web、Antigravity 中的搜索工具）。收集每个查询排名靠前的约 10 篇候选论文：标题、摘要片段和来源 URL。

如果宿主支持并行子任务，可同时发起最多 10 个搜索查询。如果不支持，则按顺序运行——速度较慢，但功能等效。

可选：使用 Exa 作为阶段 1 后端

如果宿主没有内置网络搜索，或你想使用信噪比更高、专为研究论文优化的后端，可以通过捆绑的 scripts/exa_search.py 辅助程序使用 Exa。此功能需选择启用，并从环境中读取 EXA_API_KEY——仓库不会提交密钥。

export EXA_API_KEY="your-key-here"   # get one at https://dashboard.exa.ai/
python skills/literature-review-agent/scripts/exa_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 15 \
    --discovered-for "related_work[2.1]"

输出为标准化的候选论文列表，可直接合并到 raw_candidates.json。阶段 2 的验证（Semantic Scholar 模糊匹配、 截止日期筛选、去重）保持不变。完整流程、查询模式、成本估算和安全说明，请参阅 references/exa-search-cookbook.md。

可选：使用 Tavily 作为阶段 1 后端

如果宿主没有内置网络搜索，或你想使用相关性评分较高、针对 LLM 优化的搜索后端，可以通过捆绑的 scripts/tavily_search.py 辅助程序使用 Tavily。此功能需选择启用，并从环境中读取 TAVILY_API_KEY——仓库不会提交密钥。

export TAVILY_API_KEY="tvly-your-key-here"   # get one at https://app.tavily.com
python skills/literature-review-agent/scripts/tavily_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 15 \
    --academic \
    --discovered-for "related_work[2.1]"

输出为标准化的候选论文列表，可直接合并到 raw_candidates.json。阶段 2 的验证（Semantic Scholar 模糊匹配、 截止日期筛选、去重）保持不变。完整流程、查询模式、成本估算和安全说明，请参阅 references/tavily-search-cookbook.md。

可选：将 Serply 用作第 1 阶段后端

如果你的宿主没有原生网页搜索，或者你想获取真实的 Google 结果 （支持 site: 过滤器），可以通过随附的 scripts/serply_search.py 辅助脚本使用 Serply （文档）。它是可选启用的，会从环境中读取 SERPLY_API_KEY——此仓库绝不会提交密钥。

export SERPLY_API_KEY="your-key-here"   # get one at https://serply.io
python skills/literature-review-agent/scripts/serply_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 10 \
    --academic \
    --discovered-for "related_work[2.1]"

输出是经过规范化的候选列表，可直接合并到 raw_candidates.json 中。第 2 阶段验证（Semantic Scholar 模糊匹配、 截止时间、去重）保持不变。完整步骤、查询模式、成本估算和安全说明，请参阅 references/serply-search-cookbook.md。

将发现的所有候选项合并为一个工作列表。为每个候选项标记来源查询 ID， 以便之后将其归属到“intro”或“related_work[i]”。

1.5. 第 2 阶段之前的预去重

开始第 2 阶段前务必执行此步骤。 多个搜索查询通常会返回相同的论文（例如，“Attention is All You Need”几乎会出现在每个 NLP 发现查询中）。在 1 QPS 的限制下，验证重复项会浪费 30-40% 的 S2 配额。

python skills/literature-review-agent/scripts/pre_dedup_candidates.py \
    --in workspace/raw_candidates.json \
    --out workspace/deduped_candidates.json
# Prints: "150 candidates → 97 unique (53 duplicates removed)"

使用 workspace/deduped_candidates.json 作为第 2 阶段的输入。

2. 第 2 阶段：通过 Semantic Scholar 顺序验证（使用缓存）

按顺序处理 deduped_candidates.json 中的每个候选项：

步骤 A — 先检查缓存（不调用 S2，无需限流）：

python skills/literature-review-agent/scripts/s2_cache.py \
    --cache workspace/cache/s2_cache.json \
    --check "<candidate title>"
# exit 0 + prints JSON → use cached response, skip Step B
# exit 1 → proceed to Step B

步骤 B — 发起实时 S2 请求（仅缓存未命中时，限速为 1 QPS）：

**首选方式：**使用随附的 scripts/s2_search.py 辅助脚本——它会自动处理 身份验证、重试和 429 退避：

python skills/literature-review-agent/scripts/s2_search.py \
    --query "<URL-decoded candidate title>" --limit 5
# If SEMANTIC_SCHOLAR_API_KEY is set the key is forwarded automatically.
# If not, the public unauthenticated endpoint is used (≤1 QPS, still works).

开始第 2 阶段前，检查密钥是否已配置：

python skills/literature-review-agent/scripts/s2_search.py --check-key

**备用方式：**如果你更愿意使用宿主的 URL 获取工具，请 GET：

https://api.semanticscholar.org/graph/v1/paper/search?query=<URL-encoded title>&limit=5&fields=title,abstract,year,authors,venue,externalIds

如果环境变量已设置，则添加标头 x-api-key: <SEMANTIC_SCHOLAR_API_KEY>。 请注意控制请求频率：实时请求每秒不超过 1 次。缓存命中不消耗配额。

步骤 C — 写入缓存（每次实时请求成功后都要执行）：

python skills/literature-review-agent/scripts/s2_cache.py \
    --cache workspace/cache/s2_cache.json \
    --store "<candidate title>" \
    --response '<full S2 JSON response>'

对于排名最高的结果：

python skills/literature-review-agent/scripts/levenshtein_match.py \
    --candidate "Original candidate title" \
    --found "S2 returned title"
# prints integer 0-100. Discard if < 70.

然后检查时间截止条件：

python skills/literature-review-agent/scripts/check_cutoff.py \
    --paper-year 2024 \
    --paper-month 9 \
    --cutoff 2024-10-01
# exit 0 if strictly predates, exit 1 if not

如果两项检查均通过且摘要非空，则将论文的完整 S2 元数据添加到已验证论文池中。

3. 去重并构建论文池

验证完所有候选项后：

python skills/literature-review-agent/scripts/dedupe_by_id.py \
    --in raw_pool.json \
    --out workspace/citation_pool.json

去重脚本以 paperId（Semantic Scholar 的内部唯一 ID）作为键； 如果没有，则依次回退到 externalIds.DOI、externalIds.ArXiv，再到 规范化后的标题。

脚本还会计算并写入 min_cite_paper_count = floor(0.9 * len(papers))——这是写作步骤必须引用的论文最低数量 （论文 ≥90% 的整合规则，附录 D.3）。

运行 dedupe_by_id.py 后立即验证并自动修复论文池架构：

python skills/literature-review-agent/scripts/validate_pool.py \
    --pool workspace/citation_pool.json --fix
# Catches and fixes authors-as-strings, reports missing required fields.
# Must pass before proceeding to Step 4.

3.5. 跨索引核验（Crossref + OpenAlex）

Semantic Scholar 是一个索引，可能会为不存在的论文返回看似可信的记录， 或附上错误的元数据。在编制参考文献之前，使用两个独立索引重新核验每篇 通过 S2 核验的论文——这是防止虚构引文混入文献列表的实用方法。

# Optional but recommended: a polite-pool email gives faster, more reliable
# service. The repo never commits an address.
export PAPER_ORCHESTRA_MAILTO="[email protected]"

python skills/literature-review-agent/scripts/cross_verify.py \
    --pool workspace/citation_pool.json --inplace
# Annotates each paper with a `cross_verification` field and writes
# workspace/cross_verification_report.json.
# exit 0 = all corroborated; exit 1 = WARN (something flagged or an index
# was unreachable); exit 2 = usage error.

这是一个警告关卡，而非硬性关卡（类似 validate_consistency.py）：它 会标记可疑引文，但不会阻断工作流或删除任何内容。请检查报告中的 low 和 conflict 等级：

• high — 至少有 1 个外部索引佐证 → 保留。
• medium — 有佐证，但年份不一致 → 保留，并抽查年份。
• low — 在 Crossref 或 OpenAlex 中均未找到 → 手动审核。请注意， 仅 arXiv 预印本（没有 DOI）是常见的正常原因；low 表示 “无法核实”，而非“伪造”。S2 已确认其存在。
• conflict — 池中的 DOI 与外部 DOI 不一致 → 记录很可能有误。

只删除确实无法核实的条目，然后从 dedupe_by_id.py 开始重新运行后续步骤。 如果两个索引都无法访问（离线），脚本会平稳降级，工作流将仅依靠 S2 核验继续运行。

完整说明、置信度等级以及 arXiv 误报提示，请参阅 references/cross-index-verification.md。

4. 构建 BibTeX 文件

python skills/literature-review-agent/scripts/bibtex_format.py \
    --pool workspace/citation_pool.json \
    --out workspace/refs.bib

脚本根据 `firstauthor + year

• first significant word of title 确定性地生成引文键（例如，vaswani2017attention）。它只写入 @article/@inproceedings/@misc条目，绝不编造字段。它还会将规范的bibtex_key写回每篇论文在citation_pool.json` 中的记录。

运行 bibtex_format.py 后立即，同步 intro_relwork.tex 中的键：

python skills/literature-review-agent/scripts/sync_keys.py \
    --pool workspace/citation_pool.json \
    --tex  workspace/drafts/intro_relwork.tex \
    --inplace
# Replaces every \cite{agent_key} with \cite{canonical_bibtex_key}.
# Eliminates citation_coverage gate failures caused by key mismatch.

这两个步骤取代了之前必须手动运行的 Python 代码片段。现在的工作流如下：

dedupe_by_id → validate_pool --fix → cross_verify --inplace → bibtex_format → sync_keys

5. 起草引言和相关工作

这是由你（宿主 Agent）实际撰写文本的环节。加载 references/prompt.md 中原文不变的 Literature Review Agent 提示词。 替换模板占位符：

占位符	值
intro_related_work_plan	outline.json 中的完整 JSON 对象
project_idea	idea.md 的内容
project_experimental_log	experimental_log.md 的内容
citation_checklist	refs.bib 中的 BibTeX 键
collected_papers	citation_pool.json 中 {key, title, abstract} 的列表
paper_count	len(citation_pool.papers)
min_cite_paper_count	来自 citation_pool.json
cutoff_date	你在步骤 0 中推导出的日期

还要在前面附上来自 ../paper-orchestra/references/anti-leakage-prompt.md 的 Anti-Leakage Prompt。

还要在后面附上来自 skills/shared/section_rhetoric.md 的 Introduction 和 Related Work 模板。该文件中的两个约束 最为关键：

• 引言的第 2 部分必须陈述一个由局限及其原因构成的技术挑战。“先前方法速度慢”只是症状；“先前方法在每一步都会重新编码完整上下文，因此延迟会随着对话长度线性增长”才是该方法随后可以解决的挑战。第 2 部分若未说明原因，第 3 部分就无法撰写。
• 相关工作中的每个段落都应遵循以下结构：范围句 → 代表性方法 → 与我们的挑战相关的该类方法的局限 → 过渡句。应按技术主题分组，绝不能按年份分组。min_cite_paper_count 关卡衡量的是覆盖度，而非定位——草稿即使通过该关卡，也仍可能只是引文堆砌。

使用组合后的提示词，让你的 LLM 以 template.tex 为基础生成文本。Agent 的任务是 填充模板中空白的引言和相关工作部分，并保持其他所有内容不变。输出：填充 这两个部分后的完整 template.tex。保存至 workspace/drafts/intro_relwork.tex。

5b. 将 §2 附加到 research_brief.md

在起草完 intro_relwork.tex 后、检查引文覆盖率之前，将 §2 附加到 workspace/research_brief.md（参见 skills/shared/research_brief_template.md）。

模板：

## §2 · Literature Landscape
_Written by: literature-review-agent, Step 3_

**What the literature says about the core claim:** <2-3 sentence synthesis>

**Strongest prior work (must address in the paper):**
- <bibtex_key>: <why this is the strongest comparator or predecessor>

**Gaps confirmed by the literature:** <list>

**Baseline comparisons — verification status:**
| Baseline | In citation_pool? | Confidence tier |
|---|---|---|

**Related Work cluster coverage:**
| Cluster | Papers found | Notes |
|---|---|---|

**Anything the section-writing agent should know:** <important context>

这部分总结实际找到的内容，而不是大纲中的假设。

6. 验证引文覆盖率 ≥90%

python skills/literature-review-agent/scripts/citation_coverage.py \
    --tex workspace/drafts/intro_relwork.tex \
    --pool workspace/citation_pool.json
# exit 0 if ≥90% of pool is cited; exit 1 otherwise

如果未通过检查，请重新提示写作步骤，明确列出缺失的键，并要求 Agent 在语境合适的地方将其整合进去。

提示词中的关键规则

以下内容摘自 references/prompt.md。宿主 Agent 在执行写作调用时必须遵守：

• **只能引用 collected_papers 中的文献。**绝不编造 BibTeX 键，也绝不引用文献池中没有的论文。
• 在引言和相关工作两部分合计引用其中至少 min_cite_paper_count 篇。
• 时间线规则：不要将 cutoff_date 之后发表的论文视为需要超越的先前基线。它们只能视为同期工作。
• 评估规则：除非 experimental_log.md 明确记录了针对某篇引用论文的评估，否则不得声称我们的方法优于该论文或在 SOTA 上超过该论文。对其他近期论文，必须严格将其描述为同期工作、正交工作或概念性工作。
• 输出格式：返回更新后的 template.tex 的完整代码，填入两个空白章节（引言和相关工作），并确保其他所有代码（软件包、样式、其他章节）与原始 template.tex 完全一致。
• 将输出放在 ```latex ... ``` 代码围栏中。
• 不要将 \usepackage[capitalize]{cleveref} 改为 cleverref（因为不存在 cleverref.sty）。

降级模式（无网络搜索）

如果宿主没有网络搜索工具，请切换到降级模式：

1. 如果用户已在工作区中放置预构建的 workspace/inputs/refs.bib，则直接将其加载到 workspace/refs.bib，并跳过阶段 1 和阶段 2。
2. 否则，生成 workspace/drafts/intro_relwork.tex，其中在引言和相关工作章节各放置一个 TODO 标记，并告知用户，没有网络搜索就无法完成步骤 3。

资源

• references/prompt.md — App. F.1 中 Literature Review Agent 提示词的原文
• references/discovery-pipeline.md — 详细说明阶段 1 + 阶段 2
• references/verification-rules.md — Levenshtein 阈值、年份对齐、去重
• references/citation-density-rule.md — ≥90% 引用整合规则
• references/s2-api-cookbook.md — Semantic Scholar URL、字段、速率限制
• references/cross-index-verification.md — Crossref + OpenAlex 交叉验证、置信度等级、arXiv 误报说明
• references/exa-search-cookbook.md — 阶段 1 的可选 Exa 后端（专注研究论文的网络搜索）
• references/tavily-search-cookbook.md — 阶段 1 的可选 Tavily 后端（针对大模型优化的网络搜索）
• references/serply-search-cookbook.md — 阶段 1 的可选 Serply 后端（Google SERP API）
• scripts/pre_dedup_candidates.py — NEW 在阶段 2 前对阶段 1 候选项去重（可节省 30-40% 的 S2 配额）
• scripts/s2_cache.py — NEW 持久化 S2 响应缓存（重新运行时无需重新验证）
• scripts/validate_pool.py — NEW 验证并自动修复 citation_pool.json 架构（作者格式）
• scripts/sync_keys.py — NEW 在运行 bibtex_format.py 后，将 .tex 中的引用键与规范 bibtex_keys 同步
• scripts/levenshtein_match.py — 模糊标题匹配（比率 > 70）
• scripts/check_cutoff.py — 日期比较，未指定月份时默认使用第 1 天
• scripts/dedupe_by_id.py — 根据 S2 paperId 对已验证文献池去重
• scripts/bibtex_format.py — 根据 JSON 文献池生成 refs.bib
• scripts/citation_coverage.py — ≥90% 引用覆盖率门槛
• scripts/s2_search.py — NEW Semantic Scholar 标题搜索辅助脚本；从环境变量读取 SEMANTIC_SCHOLAR_API_KEY（可选——未设置时回退到未认证模式）
• scripts/exa_search.py — 可选的 Exa 阶段 1 后端（从环境变量读取 EXA_API_KEY）
• scripts/tavily_search.py — 可选的 Tavily 阶段 1 后端（从环境变量读取 TAVILY_API_KEY）
• scripts/serply_search.py — 可选的 Serply 阶段 1 后端（从环境变量读取 SERPLY_API_KEY）
• scripts/crossref_client.py — NEW 用于交叉索引验证的 Crossref 标题/DOI 查询（无需密钥；读取 CROSSREF_MAILTO / PAPER_ORCHESTRA_MAILTO）
• scripts/openalex_client.py — NEW 用于交叉索引验证的 OpenAlex 标题/DOI 查询（无需密钥；读取 OPENALEX_MAILTO / PAPER_ORCHESTRA_MAILTO）
• scripts/cross_verify.py — NEW 使用 Crossref + OpenAlex 对 S2 验证后的文献池进行交叉验证；标记幻觉引用（WARN 门槛）
• skills/shared/research_brief_template.md — NEW §2 架构；起草 intro_relwork.tex 后追加
• skills/shared/section_rhetoric.md — NEW Introduction 逻辑链 + Related Work 段落模板