literature-survey

name	literature-survey
description	当 Supervisor 说"调研""survey""了解研究现状"，或需要系统了解某主题的文献全貌时，搜索外部文献、批量 digest、综合生成调研报告
argument-hint	<topic> [scope]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch

Purpose

给定一个研究主题，主动搜索外部文献、自动调用 paper-digest 生成结构化笔记，最终综合所有论文产出一份领域调研报告。

Steps

Step 1：明确调研范围

解析用户输入，确定以下参数：

参数	默认值	说明
topic	（必填）	研究主题
year_range	近 3 年	时间范围
venue_preference	无	venue 偏好
max_papers	20	最终纳入调研的论文数量上限
scope	full	full = 外部搜索 + vault 综合；vault-only = 只综合库内已读论文，产出报告到 Reports/（触发词："根据已读论文写个 XX 报告""vault 里关于 XX 的综合"）

基于 topic 生成 3-5 条搜索策略，覆盖以下角度：

1. 核心主题：topic 本身的直接搜索
2. 相关方法：该领域的主流技术路线
3. Survey / 综述：搜索已有 survey 论文作为参考锚点
4. Benchmark / 数据集：该领域常用的评测基准
5. 应用场景：下游应用或跨领域迁移

每条策略生成 1-2 个具体的搜索 query（英文），共 5-10 个 query。

Step 2：Vault-first 检索

在执行外部搜索之前，先检查 vault 中已有的相关内容：

1. 用 Grep 在 Papers/ 的 frontmatter 和正文中搜索 topic 相关关键词（2-3 个核心关键词）。
2. 用 Grep 在 Topics/ 中搜索是否已有相关调研或分析。
3. 收集所有匹配的 Paper 笔记，建立"已知论文清单"（title 列表），后续用于去重。
4. 若发现已有 Survey（如 Topics/{Topic}-Survey.md 已存在），先检查 frontmatter。若 status: merged，沿 merged_into 读取 canonical survey 并把后续检索、综合与写入目标全部改为 canonical；redirect 只读且不得复活。否则读取原文件作为基线，后续步骤在此基础上增量更新（补充新论文、更新分析），而非从零重建。

Step 3：外部搜索与筛选

scope: vault-only 时跳过本步与 Step 4（不做外部搜索、不新增 digest），直接以 Step 2 的库内命中论文进入 Step 5 综合分析。

调研走 两条互补检索通道，合并候选：

通道 A — OpenAlex 主题检索（零 token，覆盖期刊/venue）：先对核心 query 跑 OpenAlex 搜索，捞回 WebSearch（偏 arxiv）容易漏掉的期刊/顶会论文（IJCV/TNNLS/TPAMI/CVPR 等）。每个核心 query 跑一次：

python3 skills/1-literature/daily-papers/fetch_and_score.py \
  --search "<query>" --year-from <起始年> --limit 25
# 可选 --venues 0920-5691,0162-8828 限定 ISSN（逗号分隔）

输出 JSON 数组（title/authors/abstract/url/doi/venue/date）。url 优先 arxiv 链接、否则 doi.org，可直接喂给 Step 4 的 paper-digest（doi/CVF 走 paper-digest 对应分支）。

通道 B — WebSearch（开放网络）：

1. 对每个 query，用 WebSearch 搜索（建议加 site:arxiv.org 或 "论文标题" arxiv），提取搜索结果中的论文信息。
2. 从搜索结果中收集候选论文列表，提取：title、authors、year、venue（若可判断）、url。

合并与去重：

3. 去重：将每个候选论文的 title（转小写，去标点）与已知论文清单及两通道彼此对比，跳过重复（同一论文 arxiv 版与期刊版视为一篇）。
4. 搜索轮数上限：OpenAlex 最多 5 次 --search、WebSearch 最多 10 次。若某些 query 返回结果质量低（无相关论文），提前停止该策略。

搜索/抓取兜底：若 WebSearch 或 WebFetch 在 arXiv / HuggingFace 上卡顿，先读取 references/network-fetch-fallback.md。对已知标题可构造 arXiv search URL 或 HuggingFace paper URL 后用：

python3 scripts/lexmount_fetch.py extract "<url>" --format markdown

该兜底只用于恢复真实页面内容，不得用来凭空扩展候选论文；纳入候选的论文仍必须有可访问来源。

搜索完成后，对所有候选论文进行筛选和排序：

• 相关性：与 topic 的直接相关程度
• 影响力：优先选择知名 venue 或者知名机构的论文
• 时效性：在 year_range 内的论文优先
• 多样性：确保覆盖不同技术路线，避免全部来自同一方向

选取 top-N（N = max_papers 减去 vault 中已有的相关论文数，最少 3 篇）作为待 digest 的论文列表。

Step 4：批量 paper-digest

对 Step 3 筛选出的每篇论文，执行 paper-digest：

1. 读取 skills/1-literature/paper-digest/SKILL.md，按其 Steps 逐一处理每篇论文。
2. 输入为论文的 arXiv URL（优先）或论文标题。
3. 跳过规则：
   • 若 paper-digest 的去重检查发现 vault 已有该笔记，跳过。
   • 若 WebFetch 无法获取论文内容（如非 arXiv 论文、付费墙），先按 paper-digest 的 Lexmount fallback 重试；仍失败才记录为"未能获取"并跳过，不阻塞流程。
4. 记录每篇论文的 digest 结果：成功（文件路径）/ 跳过（原因）/ 失败（原因）。

Step 5：综合分析

基于 vault 中所有相关论文笔记（Step 2 已有的 + Step 4 新 digest 的），进行综合分析：

1. 用 Read 读取所有相关 Paper 笔记（重点：Summary、Method、Key Results、Strengths & Weaknesses）。
2. 读取 DomainMaps/_index.md（索引页）找到相关 domain，再读取对应的 DomainMaps/{Name}.md 了解当前认知状态。

读取Templates/Survey.md 按其中的 section 结构综合分析。

Step 6：产出

6a. 生成 Survey 文件

scope: vault-only 时输出到 Reports/YYYY-MM-DD-{Topic}-Report.md（报告性质，不覆盖 Topics/ 下的正式 survey），frontmatter 增加 scope: vault-only；以下 survey 文件规则仅适用于 scope: full。

Topic 名称根据主题生成（CamelCase，如 VLA-Manipulation、DiffusionPolicy-Robotics）。

• 新建：若 Topics/{Topic}-Survey.md 不存在，用 Write 按 Templates/Survey.md 模板创建并填充各 section。新建 survey 必须填 frontmatter keywords（小写短语）与 domain_map（无对应 DomainMap 填 null），否则该 survey 无法进入 digest→survey 信息流。
• 增量更新：若已存在且不是 status: merged，用 Edit 在其基础上补充新论文、刷新分析，保留原有内容中仍然有效的部分。若命中 merged redirect，只更新其 merged_into 指向的 canonical survey。

所有论文引用使用 [[wikilink]] 格式。

写作基线（Supervisor 2026-07-07 手改确立，最基础要求）：

1. 一句话结论就是一句话：Overview 首句只保留单一核心论题；并列的分类/需求轴用竖排 bullet list，不塞进长句。
2. 零对话性内容：survey 是沉淀文档，不是对 Supervisor 的回复——不写"直觉得到验证"式框架、导览铺垫、与其他 survey 的分工说明；"建议加入 DomainMaps"等流程注记只放调研日志。
3. 标题平实：用"时间段/对象：内容"式描述性标题，不用叙事修辞（如"五幕""第 X 幕"）。
4. 每行一个论点：拆长复合句；演进链（A→B→C）竖排分行、每级加粗。
5. 砍论据的展开，不砍论断的解释：机制细节（文件系统原理、算法推导）留在 Paper 笔记，正文只留论断 + 关键数字 + wikilink；反之，预测/新概念/反直觉论断必须 self-contained 展开 2-4 句（是什么/为什么/萌芽证据）——压缩成标签再靠事后口头解释 = 写作失败。
6. Takeaway ≤5 条且硬：只留可操作/可预测/指向行动的结论；类比只留一句 thesis，不留论证展开。
7. 表格优先：凡"维度 × 对象"的对比（能力矩阵/需求分层/用途分化）一律表格化——表格是 survey 最高价值资产。

6b. 追加日志

用 Edit（若文件不存在则用 Write）将以下格式的 log entry 追加到 Workbench/logs/YYYY-MM-DD.md：

### [HH:MM] literature-survey
- **input**: topic: <topic> | year_range: <year_range>
- **output**: [[Topics/{Topic}-Survey]]
- **stats**: 搜索 N 次，候选 N 篇，digest N 篇（成功 N / 跳过 N / 失败 N）
- **observation**: <一句话概括该领域的核心发现>
- **status**: success

若日志文件不存在，先创建文件（包含一级标题 # YYYY-MM-DD），再追加 entry。

Guard

• paper-digest 失败不阻塞：单篇论文 digest 失败时记录原因并继续处理下一篇，不中断整个 survey 流程。
• merged survey 只读：frontmatter 含 status: merged 的文件只承担旧链接跳转，不得恢复 keywords、追加正文或重新参与增量更新；必须沿 merged_into 写入 canonical survey。
• 搜索上限：最多执行 50 次 WebSearch，避免过度消耗 token 和 API 配额。
• 不捏造论文：所有纳入分析的论文必须来自实际搜索结果或 vault 已有笔记，不得凭记忆编造论文信息。
• 不直接修改 DomainMaps：综合分析中如有值得纳入 DomainMaps 的发现，在 Survey 文件的调研日志中标注"建议加入 DomainMaps"（不放 Key Takeaways，见写作基线第 2 条），不得直接修改 DomainMaps/ 下的任何文件。
• Papers/ 已有笔记只读：不得修改 vault 中已存在的 Paper 笔记，只可读取。新论文的笔记由 paper-digest 创建。

Verify

• Topics/*-Survey.md 已创建
• 技术路线分类 ≥2 条
• Datasets & Benchmarks 表非空
• Open Problems 节非空
• 写作基线：Overview 首句为单一论题句；全篇无对话性内容与流程注记（后者只在调研日志）
• 展开度：Takeaway 中每条预测/新概念/反直觉论断都有 2-4 句 self-contained 解释，可脱离对话独立读懂

Examples

示例 1：调研一个主题

"调研一下 VLA for manipulation 的研究现状"

执行过程：

1. 解析：topic = "VLA for manipulation"，year_range = 2023-2026
2. 生成搜索策略：
   • "Vision-Language-Action models manipulation arxiv"
   • "VLA robot manipulation policy learning"
   • "VLA survey embodied AI"
   • "manipulation benchmark evaluation VLA"
3. Grep Papers/ 搜索已有 VLA 相关笔记，发现 3 篇
4. WebSearch 执行 6 次搜索，收集 20 篇候选，去重后剩 14 篇
5. 筛选 top-5
6. 逐一 paper-digest：成功 4 篇，失败 1 篇（付费墙）
7. 综合分析 7 篇论文（3 已有 + 4 新增），生成调研报告
8. Write Topics/VLA-Manipulation-Survey.md
9. 追加日志到 Workbench/logs/2026-03-27.md

输出文件：Topics/VLA-Manipulation-Survey.md

---

示例 2：带约束的调研

"survey diffusion policy in robotics，只看 2024 年以后的 top venue 论文，最多 5 篇"

执行过程：

1. 解析：topic = "diffusion policy in robotics"，year_range = 2024-2026，venue_preference = top-tier
2. Grep Papers/ 发现 1 篇已有
3. WebSearch 搜索，优先筛选 CoRL / RSS / ICRA / NeurIPS / ICML 论文
4. 筛选 top-4
5. 逐一 paper-digest
6. 综合分析，生成报告
7. Write Topics/DiffusionPolicy-Robotics-Survey.md

输出文件：Topics/DiffusionPolicy-Robotics-Survey.md