literature-review

文献综述

编排结构化的两轮综述。脚本负责状态管理和数据获取；Agent 负责判断（筛选、综合）。每次综述都是一个持久会话——你可以暂停、恢复和重新查看。

阶段

1. init      Create session, capture the research question
2. search    Wide net across Semantic Scholar (+ arXiv optional), dedup
3. screen    Agent reads titles/abstracts/tldrs, marks keepers
4. fetch     Script produces a fetch plan (arxiv-analyze or PDF URL per paper)
5. [read]    Agent reads each shortlisted paper via the indicated strategy
6. [synth]   Agent writes the review: established findings, tensions, gaps

第 5 步和第 6 步由 Agent 驱动（没有新的子命令）；脚本的职责是准备材料。

用法

# 1. Start a session
python3 scripts/literature_review.py init \
    "what makes sparse autoencoders interpretable in practice" \
    [--out-dir /path/to/reviews]

# Returns: {"session": "./literature-reviews/what-makes-sparse-..", "slug": "..."}

# 2. Cast a wide net
python3 scripts/literature_review.py search <session-dir> \
    --limit 50 --year 2023-2026 --min-citations 5 \
    [--venue ICLR,NeurIPS] [--include-arxiv]

# 3. Agent reads candidates.json, picks keepers
python3 scripts/literature_review.py screen <session-dir> \
    --include "a3ec0b75...,2501.11120,10.48550/arXiv.2401.00032" \
    [--reasons-file keep-reasons.json]

# 4. Get the fetch plan
python3 scripts/literature_review.py fetch <session-dir>

# 5-6. Agent reads each paper and writes ./literature-reviews/<slug>/final.md

# Status check at any time
python3 scripts/literature_review.py status <session-dir>
python3 scripts/literature_review.py list-sessions [--out-dir /path]

会话布局

./literature-reviews/<slug>/
├── state.json         # phase, question, counters
├── candidates.json    # phase-1 output: full search results
├── shortlist.json     # phase-2 output: papers the agent kept + reasons
├── fetch_plan.json    # phase-3 output: per-paper read strategy
└── final.md           # phase-4 output: agent writes this

除 final.md 外，其他文件均为 JSON。会话可以重新运行（重新运行 search 以刷新，重新执行 screen 以修订入选名单）。删除会话目录即可重新开始。

工作流

阶段 1：init

清晰地记录研究问题。好的问题具体明确：“在条件 Z 下，X 与 Y 有何不同”就比“X 和 Y”更好。如果问题含糊不清，请先提示用户明确问题，再运行 init。

阶段 2：search

默认限制为 50。使用 --year 限定时间范围，使用 --min-citations 减少噪声。如果已安装 arxiv-search，且你希望覆盖学术索引可能收录滞后的预印本，可添加 --include-arxiv。

脚本会根据 arxiv_id、doi 和转为小写的标题去重。

阶段 3：screen（由 Agent 执行）

阅读 candidates.json。逐篇判断：纳入或排除。快速浏览时先看摘要的前 1-2 句；只有在判断不明确时才深入阅读完整摘要。

明确的纳入标准有助于保持一致性：

• 论文是否直接探讨了该问题？
• 方法或主张是否足够具体，具有参考价值？
• 发表 venue、年份或引用次数是否达到门槛？

调用 screen 时，传入入选论文的逗号分隔 ID。也可以传入 --reasons-file，其中将每个纳入的 ID 对应到一行理由——这些理由会写入 shortlist.json，并用于最终综合。

目标入选名单规模：10-25 篇论文。太少会导致覆盖不足；太多则会让综合难以处理。

阶段 4：fetch

脚本会生成 fetch_plan.json，为每篇入选论文提供最佳阅读方式：

• arxiv-analyze——存在 arxiv_id 时使用（优先采用分层回退：Markdown → HTML → TeX）
• open-access-pdf——直接 PDF URL
• abstract-only——没有全文；由 Agent 决定是否保留

阶段 5：read（由 Agent 驱动）

对 fetch 计划中的每篇论文，使用指定策略获取全文。提取：主张、方法、结果、局限。将笔记保存在记忆中，或存入会话目录下的临时文件。

阶段 6：synthesize（由 Agent 驱动）

按以下结构编写 final.md：

# Literature Review: <question>

## TL;DR
One paragraph. What does the literature say?

## Established findings
Claims multiple papers converge on, with citations.

## Active debates
Claims papers disagree about. Who holds each position, and on what grounds.

## Methodological patterns
Dominant approaches and their trade-offs.

## Gaps
What's unstudied, understudied, or inconclusive.

## Most important paper to read next
One paper. Why.

## Appendix: included papers
Table: title | authors | year | venue | one-line takeaway | full-text status

硬性规则

• 绝不捏造引文或 TLDR。 如果 shortlist.json 中缺少某个字段，请在综合结果中如实标注。
• 两轮筛选不可省略。 跳过筛选阶段，直接阅读 50 篇论文的全文，会浪费大量 token，也会严重影响质量（信噪比）。
• 按照约定，会话状态只追加。 如果需要修订，优先创建新会话，而不是直接编辑 state.json。
• 目标入选论文数约为 10-25 篇。 太少会导致覆盖不足；太多则难以处理。
• 注明无法阅读的内容。 在综述中提及 abstract-only 论文，并说明无法获取全文——不要假装读过。

Token 预算

阶段	Token 数（约）
search（50 条结果，含摘要）	15K-30K
screen（Agent 快速浏览）	输入 15K-30K，输出极少
fetch plan	2K
read（通过 arxiv-analyze 的 Markdown 层级读取 15 篇论文）	150K-300K
synthesis	5K-15K

总计：一次完整综述会消耗 200K-400K token。请据此规划——如果上下文预算紧张，可将各阶段拆分到多个会话中。

最重要的一点

每份 status 报告都要以当前阶段最有影响力的下一步操作收尾——不要以状态摘要收尾。例如：“阶段：已筛选（入选 12 篇）。下一步：运行 fetch，然后从论文 2501.11120 开始——它被你的入选名单中的另外 6 篇论文引用，先读它就能为后续阅读奠定基础。”

要求

• Python 3.11+（仅使用标准库）
• 已将 scholar-search 技能安装为同级目录（位于同一 skills/ 目录中）
• 可选：使用 arxiv-search 和 arxiv-analyze 技能进行 arxiv 集成（从 https://github.com/dsebastien/ai-skill-arxiv 安装）
• 可选：设置 OPENALEX_EMAIL 环境变量以访问 polite-pool（无需 API 密钥；OpenAlex 免费）