---
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 跑一次：

```bash
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 后用：

```bash
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 最高价值资产。
8. **章节成段叙事，不做罗列**（Supervisor 2026-07-21 补充）：每章开篇设"发展进程与研究现状"叙事段，章末有待解决问题段；概念分类、发展阶段、风险面等内容写成按因果链组织的完整段落（每一步解决了什么、又暴露了什么），不做方法名的 bullet 罗列。表格保留，但每张表前需 1-3 句框架段说明它回答什么问题，重要谱系表后加综合段。第 4 条的"演进链竖排"仅适用于单一机制的紧凑 lineage，不适用于章节级发展叙事。

#### 6b. 追加日志

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

```markdown
### [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 解释，可脱离对话独立读懂
- [ ] **成段叙事**：各章有发展进程/研究现状叙事段与章末待解决问题段；无孤立 bullet 罗列；每张表前有框架段

## 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`