literature-survey

文献综述循环

一个搜索 → 提取 → 映射 → 扩展循环，用于构建证据／矛盾矩阵，并在达到饱和时停止。最终产物是矩阵（主张 × 来源，并标明每个来源的立场）；反馈信号是每轮新增的会改变矩阵的来源数量——持续扩展，直到连续 <patience> 轮新增数量低于 <min_new>。与一次性摘要不同，该循环会刻意搜寻矛盾和空白，不断追查线索，直到全貌不再变化。

基本原则：每个单元格——即某个来源对某项主张的立场——都必须有真实检索所得的逐字摘录作为依据。价值不在于编排整齐的叙述，而在于如实呈现文献在哪些方面意见一致、存在分歧或保持沉默。

何时使用

当问题需要进行多来源综述，且交付物是结构化的证据图谱而非一段文字时，使用此方法。默认：运行下方完整的扩展→纳入→映射循环，直到达到饱和。备用方案：如果用户只想快速浏览，则只运行第 0 轮（种子），并返回种子矩阵。不用于依据文献评估书面提案，也不用于提出新假设。

设置

以交互方式解析绑定项。 如果工作目录中存在 loop.run.yaml，则加载该文件，用一行确认其中的值，然后跳转到循环。否则：在 Claude Code 中（可使用 AskUserQuestion 工具），推断每个绑定项的可能值并将其作为推荐选项展示；在其他宿主环境中，以引用的纯文本提示逐项询问。然后写入 loop.run.yaml（格式：examples/run.example.yaml），并在创建任何其他文件之前，确认每个值以及实时／降级文献层级。

绑定项	含义	默认值	推断方式
<question>	调研问题／主题，以及任何范围限定（年份、子领域、纳入标准）	—	询问用户；复述范围以供确认
<eval_scale>	每轮的深度（low/medium/high，见下文）	medium	—
<matrix>	结构化输出矩阵（通过 schemas/matrix.schema.json 验证）；同时写入 survey.md	<sandbox_root>/matrix.json	—
<sandbox_root>	矩阵、survey.md、台账和文献缓存的存放位置	./sandbox	—
<budget>	最大轮数	6	—
<patience>	连续出现这么多轮“无进展”后停止	2	—
<min_new>	饱和阈值——一轮新增的、会改变矩阵内容的来源少于此数量时，该轮即为“无进展”	2	—

评估深度调节项（<eval_scale> 用于限制每轮的查询 · 引文追溯 · 全文阅读 · 新来源准入上限）：

预设	查询 · 追溯	全文阅读	新来源上限
low	2 · 0	0（仅摘要片段／摘要）	~6
medium (推荐)	4 · 1	1	~10
high	6 · ≥2	3	~16

文献工具链。 论文搜索通过同级的 literature-search 技能进行：解析 <lit_skill_dir>（它会安装为同级目录，默认路径为 ~/.claude/skills/literature-search/），<lit_py> = python3，以及 <lit> = <lit_skill_dir>/tools/lit_search.py（注意其中的 tools/ 目录）；在子命令后追加 --cache-dir <sandbox_root>/literature/.cache 以复用缓存。此处使用的子命令：search "<q>"（发现来源）、snippet "<q>"（原文片段＝单元格的证据）、cite <paperId> --direction references|citations|recommend（遍历引文图）、fulltext <arxivId>（深入阅读一篇关键论文）。在设置期间确认 <lit> --help 可以正常运行；由于此循环本身就是文献检索，因此如果缺少该技能，不要悄然继续——告知用户，并选择安装该技能，或将所有检索降级为 WebSearch/WebFetch（不使用排序后的摘要片段或引文图扩展），并将此类证据标记为 source:"web"。

S2 密钥（可选，不得阻塞流程）。 免费的 S2_API_KEY 可提高 snippet/cite 的可靠性。运行 <lit> keys --init，让用户自行填写输出的 keys.env，切勿在聊天中粘贴密钥；缺少密钥时只会降级为无密钥来源池 → WebSearch。在 loop.run.yaml 中记录密钥是否存在（仅布尔值）。

循环

matrix = 来源 + 主张 + 缺口（初始为空）。dry = 连续无新增来源的轮数（初始为 0）。<N> 初始为 0。

复制此清单并逐项勾选：

• 第 0 轮 — 播种。 将 <question> 分解为若干子主题；每个子主题运行一次 <lit> search，纳入最相关的来源，将每个来源的关键主张提取到矩阵中，并附上逐字引用的 snippet，记录明显的缺口。
• 扩展。 选择覆盖最少的子主题，并关注尚未解决的矛盾和缺口；运行新的 <lit> search 查询，并从最核心的 1-2 篇论文出发沿引文图追溯（<lit> cite）。遵守 <eval_scale> 上限。
• 纳入并提取。 与现有 sources 按标题/ID 去重；对每个确实新增的来源，提取其关键主张并附上逐字引用的 snippet。
• 梳理。 对每项主张，记录每个相关来源的立场——支持 / 反驳 / 补充限定，并附上相应的 snippet；当来源既有支持也有反驳时，设置 is_contested；添加新发现的 gaps。
• 饱和度检查。 统计本轮新增且会改变矩阵的来源：少于 <min_new> 时执行 dry += 1，否则执行 dry = 0。下一轮重点关注仍然薄弱的部分。
• 记录一行台账；N = N + 1；达到饱和（dry == <patience>）或 <budget> 时停止。

停止后，写入 <matrix>（通过 schemas/matrix.schema.json 验证）和 survey.md——综合报告按共识（有充分支持的主张）、争议（有争议的主张及各方立场）和缺口（尚未解决的问题）组织，每项均引用其来源；此外，还需如实说明覆盖情况，指出哪些子主题覆盖充分，哪些覆盖不足。

矩阵是经 schema 验证的产物；精简的通用示例见 schemas/matrix.schema.json：

{
  "question": "<question>",
  "sources": [{"key": "S1", "title": "...", "source": "s2", "id": "...", "year": 2022}],
  "claims": [{
    "claim_id": "C1", "statement": "...", "is_contested": true,
    "positions": [
      {"source_key": "S1", "stance": "supports",    "snippet": "verbatim passage ..."},
      {"source_key": "S3", "stance": "contradicts",  "snippet": "verbatim passage ..."}
    ]
  }],
  "gaps": ["open question the survey surfaced"]
}

source ∈ {s2, arxiv, web}；stance ∈ {supports, contradicts, qualifies}。

台账

<sandbox_root>/ledger.tsv，以制表符分隔，文本中不得出现逗号。表头：

round	queries	new_sources	total_sources	new_claims	contested	dry

示例：

round	queries	new_sources	total_sources	new_claims	contested	dry
0	4	7	7	9	1	0
1	5	5	12	4	2	0
2	4	1	13	0	2	1
3	4	0	13	0	2	2

报告新增来源的变化轨迹，让读者看到饱和过程确实发生，而不仅仅是最终数量。

约束

• 绝不捏造。 每个来源、主张摘录和立场都必须来自本轮真实的 <lit> / WebFetch 检索，且摘录必须逐字引用；遇到 {"error","fallback"} 时，使用 WebSearch/WebFetch，并将证据标记为 source:"web"——逐字引用规则正是矩阵可信的保障。
• 梳理分歧，不要抹平。 来源冲突时，明确记录矛盾（is_contested，并附上双方的摘录）；呈现争议才是重点，而非选定赢家。
• 饱和度要依据测量，而非猜测——只有当每轮新增来源数确实低于 <min_new> 时才停止；如实报告覆盖情况，不要暗示搜索未能达到的完整性。
• 来源去重，确保“新增来源”统计的是实际新增项，而非重复发现同一篇论文。
• 不安装任何内容——同级的 literature-search 技能仅使用标准库；绝不打印或提交 API 密钥（keys.env 在项目根目录中保持 git 忽略状态）。沙箱是自包含的——不得通过 ../ 越界。
• 不要暂停循环询问是否继续；持续运行，直到达到饱和、耐心阈值或预算上限。

停止条件

循环遇到以下任一条件时立即停止：

• 饱和 — dry == <patience>（这些轮次中，每轮新增来源都少于 <min_new>）。
• 预算 — 达到 N == <budget> 轮。

始终以以下内容收尾：<matrix> 路径、综合报告（共识 / 争议 / 缺口）、来源数量，以及 ledger.tsv 中显示饱和过程的新增来源变化轨迹；另附指出薄弱部分的覆盖情况说明。